Admin API reference

Last updated: Jan-31-2023

The Admin API is a rate-limited API that provides full control of all media assets (resources), upload presets, named transformations and other product environment entities.

On this page:

Overview
folders
metadata_fields
metadata_rules
ping
resources
streaming_profiles
tags
transformations
upload_mappings
upload_presets
usage

Overview

The Admin API endpoints are accessed using HTTPS. By default, the API endpoints use the following format:

https://api.cloudinary.com/v1_1/:cloud_name/:action

For example, to list all video assets in the 'demo' product environment:

GET https://api.cloudinary.com/v1_1/demo/resources/video

The API uses Basic Authentication over secure HTTP. Your Cloudinary API Key and API Secret (which can be found on the Dashboard page of your Cloudinary console) are used for the authentication.

You can experiment with returning a list of the images in your own Cloudinary product environment by replacing the API_KEY, API_SECRET, and CLOUD_NAME in the cURL command below:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/resources/image

For most actions, request parameters are appended to the URL. In a few cases, they are passed as JSON objects. The response is in a JSON snippet. The response includes information about the action that was performed as well as data about the relevant assets.

Run in Postman Learn more about running Postman collections

The following sections provide additional details on working with the Admin API:

Using SDKs with the Admin API
Using the CLI to access the Admin API
Error handling
Usage limits
Pagination
Alternative data centers and endpoints (premium feature)

Using SDKs with the Admin API

Our backend SDK libraries provide a wrapper for the Admin API, enabling you to use your native programming language of choice. When using an SDK, request building and authentication are handled automatically, and the JSON response is parsed and returned.

For example, you can use the following SDK command to return a listing of all image (the default resource_type) assets:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.resources

PHP (cloudinary_php 2.x):

$result = $api
->assets();

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->resources();

Python (cloudinary 1.x):

result = cloudinary.api\
.resources()

Node.js (cloudinary 1.x):

cloudinary.v2.api
.resources()
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api.resources(ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

result = cloudinary.ListResources();

Go (cloudinary-go 1.x):

resp, err := cld.Admin.Assets(ctx, admin.AssetsParams{})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources

cli:

cld admin resources

Using the CLI to access the Admin API

You can use the Cloudinary CLI (Command Line Interface) to interact with the Admin API. This can provide an easy way to add automation to your workflows and manage your assets without the need for a formal coding environment or having to access your Cloudinary Console.

You can find instructions for setting up and using the CLI in the CLI reference.

Error handling

The Admin API returns the status of requests using HTTP status codes:

200: OK | Success.
400: Bad request.
401: Authorization required.
403: Not allowed.
404: Not found.
409: Already exists.
420: Rate limited.

The SDKs report errors by raising applicative exceptions. Additionally, an informative JSON message is returned. For example:

{ "error": { "message": "Resource not found - 5traNge_nam3" } }

Usage limits

You can use the Admin API quite extensively, but it is a rate limited API. The specific limits depend on the plan your account is registered to. If you require more flexible limits, don't hesitate to contact us.

Note

This limit refers only to Admin API requests, and not to requests that use the Upload API, which is not rate-limited. In some cases, you may be able to use certain methods of the Upload API to achieve some administration goals. For example, you can modify or remove tags for one or multiple resources using the tags method. You can modify many attributes of an individual resource using the explicit method, and you can return most details about a single (original) resource in response to any upload or explicit method call.

For each Admin API call, standard HTTP headers are returned with details on your current usage statistics, including your per-hour limit, remaining number of actions and the time the hourly count will be reset.

The header might look something like this:

X-FeatureRateLimit-Limit: 500
X-FeatureRateLimit-Remaining: 499
X-FeatureRateLimit-Reset: Wed, 03 Oct 2012 08:00:00 GMT

You can use the SDKs to retrieve this data as follows:

Ruby PHP Python Node.js Java .NET Go All

Ruby (cloudinary 1.x):

result = Cloudinary::Api.resources
result.rate_limit_allowed
=> 500
$ result.rate_limit_remaining
=> 499
$ result.rate_limit_reset_at
=> 2019-10-03 10:00:00 +0200

PHP (cloudinary_php 2.x):

$result = $api->assets();
var_dump($result->rateLimitAllowed);
php > int(500)
var_dump($result->rateLimitRemaining);
php > int(499)
var_dump($result->rateLimitResetAt);
php > int(1570089600)

PHP (cloudinary_php 1.x (legacy)):

$result = $api->resources();
var_dump($result->rate_limit_allowed);
php > int(500)
var_dump($result->rate_limit_remaining);
php > int(499)
var_dump($result->rate_limit_reset_at);
php > int(1570089600)

Python (cloudinary 1.x):

result = cloudinary.api.resources()
result.rate_limit_allowed
>>>500
result.rate_limit_remaining
>>>499
result.rate_limit_reset_at
>>>(2019, 10, 3, 08, 0, 0, 0, 1, -1)

Node.js (cloudinary 1.x):

cloudinary.v2.api
.resources()
.then(result=>console.log(result.rate_limit_allowed,
              result.rate_limit_remaining,
              result.rate_limit_reset_at));

> 500 499 Sun, 03 Oct 2019 08:00:00 GMT

Java (cloudinary 1.x):

ApiResponse result = api.resources(ObjectUtils.emptyMap());
System.out.println(result.apiRateLimit().getLimit());
=> 500
System.out.println(result.apiRateLimit().getRemaining());
=> 499
System.out.println(result.apiRateLimit().getReset());
=> 2019-10-03 10:00:00 +0200

.NET (CloudinaryDotNet 1.x):

var result = cloudinary.ListResources();
result.Limit
// returns 500
result.Remaining
// returns 499
result.Reset
//returns  2019-10-03 10:00:00 +0200

Go (cloudinary-go 1.x):

Not supported by this SDK

Tip

You can also retrieve rate limits details as well as transformation, bandwidth, and storage limits, and a variety of additional product environment usage data with the GET /usage method.

Pagination

The GET methods of the API return a limited set of results, ordered by the creation time of the relevant entities. You can control the number of results returned in a single request by specifying the max_results parameter. The default is 10 for most methods. There is also a maximum number of results you can request for a single API call (either 100 or 500 as documented for each of the relevant methods). DELETE methods also operate in chunks.

When a GET request has more results to return than max_results or when a DELETE request has more than 1000 entities to delete, the next_cursor value is returned as part of the response. You can then specify this cursor value as the next_cursor parameter of the following GET or DELETE request. For example, this enables you to iterate through the full list of uploaded resources, transformations, or tags in your product environment or to delete an entire set of entities that matches your deletion request.

Alternative data centers and endpoints (premium feature)

By default, Cloudinary accounts use US-based data centers. In these cases, the endpoint format is as shown at the beginning of this Overview.

If the majority of your users are located in Europe or Asia, Cloudinary can set up your account to use our Europe (EU) or Asia Pacific (AP) data center. In that case, your endpoints will take the form:

https://api-eu.cloudinary.com/v1_1/:cloud_name/:action

https://api-ap.cloudinary.com/v1_1/:cloud_name/:action

Note

This is a premium feature that is supported only for our Enterprise plans and must be arranged when the account is created. Contact support for more information.

folders

Run in Postman Learn more about running Postman collections

Enables you to manage your product environment's asset folders.

Note

For product environments using dynamic folder mode, keep in mind that this API relates to asset folders in the Media Library, and that those folders do not necessarily match the public ID paths of the assets in those folders.

Method	Description
GET`/folders`	Lists all the root folders.
GET`/folders/:folder`	Lists the name and full path of all subfolders of a specified folder.
POST`/folders/:folder`	Creates a new folder.
DELETE`/folders/:folder`	Deletes a folder.

Get root folders

Lists all the root folders. Limited to 2000 results.

Syntax

GET /folders

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.root_folders

PHP (cloudinary_php 2.x):

$api->rootFolders();

PHP (cloudinary_php 1.x (legacy)):

$api->root_folders();

Python (cloudinary 1.x):

cloudinary.api.root_folders()

Node.js (cloudinary 1.x):

cloudinary.v2.api.root_folders().then(callback);

Java (cloudinary 1.x):

api.rootFolders(ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

cloudinary.RootFolders();

Go (cloudinary-go 1.x):

resp, err := cld.Admin.RootFolders(ctx, admin.RootFoldersParams{})

cli:

cld admin root_folders

Sample response

The response contains an array of all the root folders.

{
    "folders": [
      {
        "name": "cloud",
        "path": "cloud"
      }, 
      {
        "name": "brooks",
        "path": "brooks"
      }   
    ]
}

Get subfolders

Lists the name and full path of all subfolders of a specified folder. Limited to 2000 results.

Syntax

GET /folders/:folder

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.subfolders(folder, options = {})

PHP (cloudinary_php 2.x):

$api->subfolders($folder, $options = []);

PHP (cloudinary_php 1.x (legacy)):

$api->subfolders($folder, $options = []);

Python (cloudinary 1.x):

cloudinary.api.subfolders(folder, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.sub_folders(folder, options).then(callback);

Java (cloudinary 1.x):

api.subfolders(String folder, Map options);

.NET (CloudinaryDotNet 1.x):

cloudinary.SubFolders(folderParams params);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.SubFolders(ctx, admin.SubFoldersParams{})

cli:

cld admin subfolders (folder)

Required parameters

Parameter	Type	Description
folder	String	The full path of the parent folder whose subfolders you want to return.

Optional parameters

Parameter	Type	Description
max_results	Integers	Maximum number of results to return (up to 500). Default: `10`.
next_cursor	String	When a request has more results to return than `max_results`, the `next_cursor` value is returned as part of the response. You can then specify this value as the `next_cursor` parameter of a following request.

Examples

List all subfolders of a given folder 'product/shoe':

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.subfolders("product/shoe")

PHP (cloudinary_php 2.x):

$result = $api
->subfolders("product/shoe");

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->subfolders("product/shoe");

Python (cloudinary 1.x):

result = cloudinary.api\
.subfolders("product/shoe")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.sub_folders("product/shoe")
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.subfolders("product/shoe", ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

result = cloudinary
.SubFolders("product/shoe");

Go (cloudinary-go 1.x):

resp, err := cld.Admin.SubFolders(ctx, admin.SubFoldersParams{"product/shoe"})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/folders/product/shoe

cli:

cld admin subfolders "product/shoe"

Sample response

The response contains an array of all the subfolders of the specified folder.

{
    "folders": [
      {
        "name": "red",
        "path": "product/shoe/red"
      }, 
      {
        "name": "white",
        "path": "product/shoe/white"
      }   
    ]
 }

Create folder

Creates a new empty asset folder.

Syntax

POST /folders/:folder

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.create_folder(folder)

PHP (cloudinary_php 2.x):

$api->createFolder($folder);

PHP (cloudinary_php 1.x (legacy)):

$api->create_folder($folder);

Python (cloudinary 1.x):

cloudinary.api.create_folder(folder)

Node.js (cloudinary 1.x):

cloudinary.v2.api.create_folder(folder).then(callback);

Java (cloudinary 1.x):

api.createFolder(String folder, Map options);

.NET (CloudinaryDotNet 1.x):

cloudinary.CreateFolder(folder);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.CreateFolder(ctx, admin.CreateFolderParams{})

cli:

cld admin create_folder $folder

Required parameters

Parameter	Type	Description
folder	String	The full path of the new asset folder.

Examples

Create a new folder called 'test' as a subfolder of the parent folder 'product' ('product/test'):

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.create_folder("product/test")

PHP (cloudinary_php 2.x):

$result = $api
->createFolder("product/test");

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->create_folder("product/test");

Python (cloudinary 1.x):

result = cloudinary.api\
.create_folder("product/test")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.create_folder("product/test")
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api.createFolder("product/test", ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

result = cloudinary.CreateFolder("product/test");

Go (cloudinary-go 1.x):

resp, err := cld.Admin.CreateFolder(ctx, admin.CreateFolderParams{Folder: "product/test"})

curl:

curl \
  -X POST
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/folders/product/test

cli:

cld admin create_folder "product/test"

Sample response

{
    "success": true,
    "path": "product/test",
    "name": "test"
}

Delete folder

Deletes an empty folder.

Tips

The folder must be empty before you can delete it.

To find all assets currently in a folder:
- In dynamic folder mode, use the get resources by asset folder method.
- In fixed folder mode, use the get resources method with the prefix parameter to find all assets with a specified path in the public ID.
To move assets out of a folder:
- In dynamic folder mode, use the update method with the asset_folder parameter to change the asset's asset folder.
- In fixed folder mode, use the rename method to change the public ID path.
To delete assets: use the Delete resources method.

Syntax

DELETE /folders/:folder

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.delete_folder(folder)

PHP (cloudinary_php 2.x):

$api->deleteFolder($folder);

PHP (cloudinary_php 1.x (legacy)):

$api->delete_folder($folder);

Python (cloudinary 1.x):

cloudinary.api.delete_folder(folder)

Node.js (cloudinary 1.x):

cloudinary.v2.api.delete_folder(folder).then(callback);

Java (cloudinary 1.x):

api.deleteFolder(String folder, Map options);

.NET (CloudinaryDotNet 1.x):

cloudinary.DeleteFolder(folder);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.DeleteFolder(ctx, admin.DeleteFolderParams{})

cli:

cld admin delete_folder (folder)

Required parameters

Parameter	Type	Description
folder	String	The full path of the empty folder to delete.

Examples

Delete a folder called 'test' which is a subfolder of the root folder 'product' ('product/test'):

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.delete_folder("product/test")

PHP (cloudinary_php 2.x):

$result = $api
->deleteFolder("product/test");

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->delete_folder("product/test");

Python (cloudinary 1.x):

result = cloudinary.api\
.delete_folder("product/test")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.delete_folder("product/test")
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.deleteFolder("product/test", ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

result = cloudinary
.DeleteFolder("product/test");

Go (cloudinary-go 1.x):

resp, err := cld.Admin.DeleteFolder(ctx, admin.DeleteFolderParams{Folder: "product/test"})

curl:

curl \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/folders/product/test

cli:

cld admin delete_folder "product/test"

Sample response

{
    "deleted": [
        "product/test"
    ]
}

metadata_fields

Run in Postman Learn more about running Postman collections

Enables you to manage the metadata fields available for your product environment.

The table below provides a quick summary of the methods available for the Admin API metadata_fields endpoint. See the Metadata API documentation for detailed information on the following Metadata methods, as well as detailed information on the Metadata field structure, including how to work with field validation and list (datasource) values.

Methods summary

Method	Description
GET`/metadata_fields`	Lists all metadata field definitions.
GET`/metadata_fields/:external_id`	Returns a single metadata field definition by external ID.
POST`/metadata_fields`	Creates a new metadata field definition.
POST`/metadata_fields/:external_id/datasource_restore`	Restores entries in a metadata field datasource.
PUT`/metadata_fields/:external_id`	Updates a metadata field definition by external ID.
PUT`/metadata_fields/:external_id/datasource`	Updates a metadata field datasource by external ID.
DELETE`/metadata_fields/:external_id`	Deletes a metadata field by external ID.
DELETE`/metadata_fields/:external_id/datasource`	Deletes entries in a metadata field datasource for a specified metadata field definition.

metadata_rules

Enables you to set up dependencies and hierarchical relationships between structured metadata fields and field options.

The table below provides a quick summary of the methods available for the Admin API metadata_rules endpoint. See the Conditional metadata rules API documentation for detailed information on the following Metadata rules methods, as well as detailed information on the Metadata rule structure, including how to work with conditions that evaluate on metadata payloads, and results that are applied to specified metadata fields in the case those conditions are met.

Methods summary

Method	Description
GET`/metadata_rules`	Returns an index of all metadata rules.
POST`/metadata_rules`	Creates a new metadata rule definition.
PUT`/metadata_rules/:external_id`	Updates an existing metadata rule definition.
DELETE`/metadata_rules/:external_id`	Deletes a metadata rule by external ID.

ping

Run in Postman Learn more about running Postman collections

Enables you to test the reachability of the Cloudinary API with the ping method.

Method	Description
GET`/ping`	Pings Cloudinary servers.

Ping Cloudinary servers

Syntax

GET /ping

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.ping

PHP (cloudinary_php 2.x):

$api->ping();

PHP (cloudinary_php 1.x (legacy)):

$api->ping();

Python (cloudinary 1.x):

cloudinary.api.ping()

Node.js (cloudinary 1.x):

cloudinary.v2.api.ping().then(callback);

Java (cloudinary 1.x):

api.ping(ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

Not supported by this SDK

Go (cloudinary-go 1.x):

resp, err := cld.Admin.Ping(ctx)

cli:

cld admin ping

Sample response

The response contains the current status of the Cloudinary servers.

{
 "status": "ok"
}

resources

Run in Postman Learn more about running Postman collections

Enables you to manage all the resources (assets) stored in your product environment.

Method	Description
GET`/resources/:resource_type(/:type)`	Lists resources (assets) stored in your product environment.
GET`/resources/by_asset_folder`	Lists resources (assets) located in a specified asset folder. Supported only for product environments using dynamic folders mode.
GET`/resources/by_asset_ids`	Lists resources (assets) based on the specified asset IDs.
GET`/resources/:resource_type/tags/:tag`	Lists resources (assets) with a specified tag.
GET`/resources/:resource_type/context/`	Lists resources (assets) with a specified contextual metadata key.
GET`/resources/:resource_type/moderations/:moderation_kind/:status`	Lists resources (assets) with a particular status from a specified moderation type.
GET`/resources/:resource_type/:type/:public_id`	List details of the asset with the specified public ID, as well as all its derived assets.
GET`/resources/:asset_id`	List details of the asset with the specified asset ID, as well as all its derived assets.
GET`/resources/search`	Filters and retrieves information on all the resources (assets) in your product environment.
POST`/resources/:resource_type/:type/:public_id`	Updates one or more of the attributes associated with a specified resource (asset).
POST`/resources/:resource_type/:type/restore`	Restores one or more resources (assets) from backup.
POST`/resources/:resource_type/upload/update_access_mode`	Updates the access mode of resources (assets) by public ID, by tag, or by prefix.
POST`/resources/related_assets/:resource_type/:type/:public_id`	Relates assets by public IDs.
DELETE`/resources/related_assets/:resource_type/:type/:public_id`	Unrelates related assets by public IDs.
DELETE`/resources/:resource_type/:type`	Deletes resources (assets) by public IDs.
DELETE`/resources/:resource_type/tags/:tag`	Deletes resources by tags.
DELETE`/derived_resources`	Deletes derived resources.

Get resources

Lists resources (assets) uploaded to your product environment.

Syntax

GET /resources(/:resource_type(/:type))

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.resources(options = {})

PHP (cloudinary_php 2.x):

$api->assets($options = []);

PHP (cloudinary_php 1.x (legacy)):

$api->resources($options = []);

Python (cloudinary 1.x):

cloudinary.api.resources(**options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.resources(options).then(callback);

Java (cloudinary 1.x):

api.resources(Map options);

.NET (CloudinaryDotNet 1.x):

cloudinary.ListResources(ListResourceParams params);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.Assets(ctx, admin.AssetsParams{})

cli:

cld admin resources

Optional parameters

Parameter	Type	Description
resource_type	String	The type of asset. Relevant as a parameter only when using the SDKs (the `resource_type` is included in the endpoint URL when using the REST API). Note: use `video` for all video and audio assets, such as .mp3. Possible values: `image`, `raw`, `video`. Default: image.
type	String	The delivery type, relevant as a parameter only when using the SDKs (the `type` is included in the endpoint URL when using the REST API). Possible values: `upload`, `private`, `authenticated`, `facebook`, `twitter`, `gravatar`, `youtube`, `hulu`, `vimeo`, `animoto`, `worldstarhiphop`, `dailymotion`. Default: upload.
prefix	String	Find all assets with a public ID that starts with the given prefix. The assets are sorted by public ID in the response. Note: use this parameter to find public IDs with a `+` character in them.
public_ids	String[]	An array of public IDs. Get assets with the given public IDs (up to 100). Note: Not supported for SDKs. Instead use the `resources_by_ids` SDK method. This parameter does not support public IDs with a `+` character in them (use the `prefix` parameter to find the assets instead).
max_results	Integers	Maximum number of assets to return (up to 500). Default: `10`.
next_cursor	String	When a request has more results to return than `max_results`, the `next_cursor` value is returned as part of the response. You can then specify this value as the `next_cursor` parameter of a following request.
start_at	String	Get assets that were created since the given timestamp (ISO 8601 format). Supported unless `prefix` or `public_ids` were specified. For example: `2020-12-01`
direction	String/Integer	Control the order of returned assets, according to the `created_at` date. Note: if a `prefix` is specified, this parameter is ignored and the results are sorted by public ID. Possible values: `desc` or `-1` (default), `asc` or `1`.
tags	Boolean	Whether to include the list of tag names assigned to each asset. Default: `false`.
context	Boolean	Whether to include key-value pairs of contextual metadata associated with each asset. Default: `false`.
moderation	Boolean	Whether to include the image moderation status of each asset. Default: `false`.

Examples

Get all images:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.resources

PHP (cloudinary_php 2.x):

$result = $api
->assets();

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->resources();

Python (cloudinary 1.x):

result = cloudinary.api\
.resources()

Node.js (cloudinary 1.x):

cloudinary.v2.api
.resources()
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.resources(ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

result = cloudinary
.ListResources();

Go (cloudinary-go 1.x):

resp, err := cld.Admin.Assets(ctx, admin.AssetsParams{})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image

cli:

cld admin resources

Get images of delivery type 'upload', up to a maximum of 30 results:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.resources(
  :type => :upload,
  :max_results => 30)

PHP (cloudinary_php 2.x):

result = api
->assets(
  ["type" => "upload", "max_results" => 30]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->resources(
  ["type" => "upload", "max_results" => 30]);

Python (cloudinary 1.x):

result = cloudinary.api\
.resources(type = "upload", max_results = 30)

Node.js (cloudinary 1.x):

cloudinary.v2.api
.resources(
  { type: 'upload', max_results: 30 })
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.resources(
  ObjectUtils.asMap("type", "upload", "max_results", 30));

.NET (CloudinaryDotNet 1.x):

var listResourcesParams = new ListResourcesParams(){
  Type = "upload",
  MaxResults = 30};
var listResourcesResult = cloudinary.ListResources(listResourcesParams);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.Assets(ctx, admin.AssetsParams{
        DeliveryType:   "upload",
        MaxResults:     30})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload

cli:

cld admin resources type=upload

Get all uploaded images with a given prefix:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.resources(
:type => :upload, 
:prefix => "sample")

PHP (cloudinary_php 2.x):

$result = $api
->assets([
  "type" => "upload", 
  "prefix" => "sample"]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->resources([
  "type" => "upload", 
  "prefix" => "sample"]);

Python (cloudinary 1.x):

result = cloudinary.api\
.resources(
type = "upload", 
prefix = "sample")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.resources(
{ type: 'upload', 
  prefix: 'sample' })
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.resources(
ObjectUtils.asMap(
  "type", "upload", 
  "prefix", "sample"));

.NET (CloudinaryDotNet 1.x):

var listResourcesByPrefixParams = new listResourcesByPrefixParams(){
  Type = "upload",
  Prefix = "sample"};
var listResourcesResult = cloudinary.ListResources(listResourcesByPrefixParams);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.Assets(ctx, admin.AssetsParams{
        DeliveryType: "upload",
        Prefix:       "sample"})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload?prefix=sample

cli:

cld admin resources type=upload prefix=sample

Get Facebook images:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.resources(:type => :facebook)

PHP (cloudinary_php 2.x):

$result = $api
>assets(["type" => "facebook"]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->resources(["type" => "facebook"]);

Python (cloudinary 1.x):

result = cloudinary.api\
.resources(type = "facebook"))

Node.js (cloudinary 1.x):

cloudinary.v2
.api.resources(
  { type: 'facebook' })
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api.resources(
  ObjectUtils.asMap("type", "facebook"));

.NET (CloudinaryDotNet 1.x):

var listResourcesParams = new ListResourcesParams(){
  Type = "facebook"};
var listResourcesResult = cloudinary.ListResources(listResourcesParams);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.Assets(ctx, admin.AssetsParams{
        DeliveryType: "facebook"})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/facebook

cli:

cld admin resources type=facebook

Get raw uploaded files:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.resources(
  :resource_type => :raw)

PHP (cloudinary_php 2.x):

$result = $api
->assets(["resource_type" => "raw"]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->resources(["resource_type" => "raw"]);

Python (cloudinary 1.x):

result = cloudinary.api\
.resources(resource_type = "raw")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.resources(
  { resource_type: 'raw' })
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.resources(
  ObjectUtils.asMap("resource_type", "raw"));

.NET (CloudinaryDotNet 1.x):

var listResourcesParams = new ListResourcesParams(){
  ResourceType = "raw"};
var listResourcesResult = cloudinary.ListResources(listResourcesParams);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.Assets(ctx, admin.AssetsParams{
        AssetType:    "raw",
        DeliveryType: "upload"})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/raw

cli:

cld admin resources resource_type=raw

Get all uploaded images with the given IDs:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.resources_by_ids(["user_photo_1", "user_photo_2"])

PHP (cloudinary_php 2.x):

$result = $api
->assetsByIds(["user_photo_1", "user_photo_2"]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->resources_by_ids(["user_photo_1", "user_photo_2"]);

Python (cloudinary 1.x):

result = cloudinary\
.api.resources_by_ids(["user_photo_1", "user_photo_2"])

Node.js (cloudinary 1.x):

cloudinary.v2.api
.resources_by_ids(["user_photo_1", "user_photo_2"])
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.resources_by_ids(Arrays.asList("user_photo_1", "user_photo_2"),
  ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

var publicIds = new List<string>(){"user_photo_1", "user_photo_2" };
cloudinary.ListResourceByPublicIds(publicIds);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.AssetsByIDs(ctx, admin.AssetsByIDsParams{
      DeliveryType: "upload",
      PubicIDs:     []string{"user_photo_1", "user_photo_2"}})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload?public_ids[]=user_photo_1&public_ids[]=user_photo_2

cli:

cld admin resources_by_ids '["user_photo_1","user_photo2"]'

Sample response

{
  "resources": [
    {
      "asset_id": "b1ce1d159bc3696e5a74d8b8aefbe707",
      "public_id": "face_center",
      "format": "jpg",
      "version": 1333013579,
      "resource_type": "image",
      "type": "upload",
      "created_at": "2012-03-29T09:32:59Z",
      "bytes": 128891,
      "width": 283,
      "height": 424,
      "backup": true,
      "access_mode": "public",
      "url": "http://res.cloudinary.com/demo/image/upload/v1333013579/face_center.jpg",
      "secure_url": "https://.../image/upload/v1333013579/face_center.jpg"
    },
    {
      "asset_id": "835d1cf89bd7c1b84dc4f53d35bc235f",
      "public_id": "12208495",
      "format": "jpg",
      "resource_type": "image",
      "type": "facebook",
      "created_at": "2012-10-06T17:18:52Z",
      "bytes": 0,
      "access_mode": "public",
      "url": "http://res.cloudinary.com/demo/image/facebook/12208495.jpg",
      "secure_url": "https://.../image/facebook/12208495.jpg"
    },
  ]
}

Get resources by asset folder

Returns all assets stored directly in a specified asset folder, regardless of the public_id paths or resource_type of those assets. This method does not return assets stored in sub-folders of the specified folder. The asset folder name isn't case sensitive.

Note

Supported only for product environments using dynamic folder mode.

Syntax:

GET /resources/by_asset_folder

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.resources_by_asset_folder(asset_folder, options = {})

PHP (cloudinary_php 2.x):

$api->assetsByAssetFolder($asset_folder, $options = []));

PHP (cloudinary_php 1.x (legacy)):

Not supported in this version of the SDK.

Python (cloudinary 1.x):

cloudinary.api.resources_by_asset_folder(asset_folder, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.resources_by_asset_folder(asset_folder, options, callback);

Java (cloudinary 1.x):

api.resourcesByAssetFolder(String asset_folder, Map options);

.NET (CloudinaryDotNet 1.x):

cloudinary.ListResourcesByAssetFolder(ListResourcesByAssetFolder params);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.AssetsByAssetFolder(ctx, admin.AssetsByAssetFolderParams{})

cli:

cld admin resources_by_asset_folder $asset_folder $options

Required parameters

Parameter	Type	Description
asset_folder	String	The name of the asset folder.

Optional parameters

Parameter	Type	Description
max_results	Integer	Maximum number of assets to return (maximum=500). Default: `10`.
next_cursor	String	When a request has more results to return than `max_results`, the `next_cursor` value is returned as part of the response. You can then specify this value as the `next_cursor` parameter of the following request.
direction	String/Integer	Control the order of returned assets, according to the `created_at` date. Note: if a `prefix` is specified, this parameter is ignored and the results are sorted by public ID. Possible values: `desc` or `-1` (default), `asc` or `1`.
tags	Boolean	Whether to include the list of tag names assigned to each asset. Default: `false`.
context	Boolean	Whether to include key-value pairs of contextual metadata associated with each asset. Default: `false`.
moderations	Boolean	Whether to include image moderation status of each asset. Default: `false`.
metadata	Boolean	Whether to include the metadata fields and values set for each asset. Default: `false`.

Example

Get all assets in the 'technology asset folder. In the response, include the tags and metadata associated with each asset:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

Cloudinary::Api.resources_by_asset_folder('technology'
  :tags => true, 
  :metadata => true)

PHP (cloudinary_php 2.x):

$api->assetsByAssetFolder("technology"
  "tags" => true, 
  "metadata" => true]);

PHP (cloudinary_php 1.x (legacy)):

Not supported in this version of the SDK.

Python (cloudinary 1.x):

cloudinary.api.resources_by_asset_folder("technology"
  tags = true, 
  metadata = true)

Node.js (cloudinary 1.x):

cloudinary.v2.api.resources_by_asset_folder("technology", 
  { tags: true, 
    metadata: true }, 
function(error, result) {console.log(result, error); });

Java (cloudinary 1.x):

api.resourcesByAssetFolder("technology", 
ObjectUtils.asMap(
  "tags", true, 
  "metadata", true));

.NET (CloudinaryDotNet 1.x):

var assetFolderParams = new ListResourcesByAssetFolderParams(){
  Tags = true,
  Metadata = true};
var assetFolderResult = cloudinary.ListResourcesByAssetFolder("technology", assetFolderParams);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.AssetsByAssetFolder(ctx, admin.AssetsByAssetFolderParams{
  AssetFolder: "technology"
  Tags: true
  Metadata:true})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/by_asset_folder?asset_folder=technology&tags=true&metadata=true

cli:

cld admin resources_by_asset_folder technology tags=true metadata=true

Get resources by asset IDs

Returns details of the assets with the specified asset IDs. This enables you to get assets by their immutable identifiers, regardless of resource type, type, public ID, display name, or asset folder.

Syntax:

GET /resources/by_asset_ids

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.resources_by_asset_ids(asset_ids, options = {})

PHP (cloudinary_php 2.x):

$api->assetsByAssetIds($asset_ids, $options = []);

PHP (cloudinary_php 1.x (legacy)):

Not supported in this version of the SDK.

Python (cloudinary 1.x):

cloudinary.api.resources_by_asset_ids(**asset_ids, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.resources_by_asset_ids(asset_ids, options, callback);

Java (cloudinary 1.x):

api.resourcesByAssetIds(Map asset_ids, Map options);

.NET (CloudinaryDotNet 1.x):

cloudinary.ListResourcesByAssetIDs(ListResourcesByAssetIdsParams params);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.AssetsByAssetIDs(ctx, admin.AssetsByAssetIDsParams{})

cli:

cld admin resources_by_asset_ids (asset_ids)

Required parameters

Parameter	Type	Description
asset_ids	String[]	An array of asset IDs.

Optional parameters

Parameter	Type	Description
max_results	Integer	Maximum number of assets to return (maximum=500). Default: `10`.
next_cursor	String	When a request has more results to return than `max_results`, the `next_cursor` value is returned as part of the response. You can then specify this value as the `next_cursor` parameter of the following request.
direction	String/Integer	Control the order of returned assets, according to the `created_at` date. Note: if a `prefix` is specified, this parameter is ignored and the results are sorted by public ID. Possible values: `desc` or `-1` (default), `asc` or `1`.
tags	Boolean	Whether to include the list of tag names assigned to each asset. Default: `false`.
context	Boolean	Whether to include key-value pairs of contextual metadata associated with each asset. Default: `false`.
moderations	Boolean	Whether to include image moderation status of each asset. Default: `false`.
metadata	Boolean	Whether to include the metadata fields and values set for each asset. Default: `false`.

Example

Get the details of two assets by their specified asset IDs.

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

Cloudinary::Api.resources_by_asset_ids(["e12345b5c456c8901bbb0efc00c0fcf", "f12345a5c789c1234bbb0efc00c0f12"])

PHP (cloudinary_php 2.x):

$api->assetsByAssetIds(["e12345b5c456c8901bbb0efc00c0fcf", "f12345a5c789c1234bbb0efc00c0f12"]);

PHP (cloudinary_php 1.x (legacy)):

Not supported in this version of the SDK.

Python (cloudinary 1.x):

cloudinary.api.resources_by_asset_ids(["e12345b5c456c8901bbb0efc00c0fcf", "f12345a5c789c1234bbb0efc00c0f12"])

Node.js (cloudinary 1.x):

cloudinary.v2.api.resources_by_asset_ids(["e12345b5c456c8901bbb0efc00c0fcf", "f12345a5c789c1234bbb0efc00c0f12"],
  function(error, result) {console.log(result, error); });

Java (cloudinary 1.x):

cloudinary.api().resourcesByAssetIds(Arrays.asList("e12345b5c456c8901bbb0efc00c0fcf", "f12345a5c789c1234bbb0efc00c0f12"),
  ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

var assetIds = new List<string>(){"e12345b5c456c8901bbb0efc00c0fcf", "f12345a5c789c1234bbb0efc00c0f12"};
cloudinary.ListResourcesByAssetIDs(assetIds);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.AssetsByAssetIDs(ctx, admin.AssetsByAssetIDsParams{
          AssetIDs: []string{"e12345b5c456c8901bbb0efc00c0fcf", "f12345a5c789c1234bbb0efc00c0f12"}})

curl:

curl \
 -d "asset_ids[]=e12345b5c456c8901bbb0efc00c0fcf&asset_ids[]=f12345a5c789c1234bbb0efc00c0f12" \
 -X POST \
 https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/by_asset_ids

cli:

cld admin resources_by_asset_ids '["e12345b5c456c8901bbb0efc00c0fcf", "f12345a5c789c1234bbb0efc00c0f12"]'

Get resources by tag

Lists resources (assets) with a specified tag. This method does not return deleted assets even if they have been backed up.

Tip

You can also return a JSON listing of resources (assets) by tag in your front-end code using the client-side asset lists delivery option.

Syntax

GET /resources/:resource_type/tags/:tag

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.resources_by_tag(tag, options = {})

PHP (cloudinary_php 2.x):

$api->assetsByTag($tag, $options = []);

PHP (cloudinary_php 1.x (legacy)):

$api->resources_by_tag($tag, $options = []));

Python (cloudinary 1.x):

cloudinary.api.resources_by_tag(tag, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.resources_by_tag(tag, options).then(callback);

Java (cloudinary 1.x):

api.resourcesByTag(String tag, Map options);

.NET (CloudinaryDotNet 1.x):

cloudinary.ListResourcesByTag(ListResourcesByTagParams params);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.AssetsByTag(ctx, admin.AssetsByTagParams{})

cli:

cld admin resources_by_tag (tag)

Required parameters

Parameter	Type	Description
tag	String	The assets to return that have this tag.

Optional parameters

Parameter	Type	Description
resource_type	String	The type of asset. Relevant as a parameter only when using the SDKs (the `resource_type` is included in the endpoint URL when using the REST API). Note: use `video` for all video and audio assets, such as .mp3. Possible values: `image` (default), `raw`, `video`.
max_results	Integer	Maximum number of assets to return (maximum=500). Default: `10`.
next_cursor	String	When a request has more results to return than `max_results`, the `next_cursor` value is returned as part of the response. You can then specify this value as the `next_cursor` parameter of the following request.
direction	String/Integer	Control the order of returned assets, according to the `created_at` date. Note: if a `prefix` is specified, this parameter is ignored and the results are sorted by public ID. Possible values: `desc` or `-1` (default), `asc` or `1`.
tags	Boolean	Whether to include the list of tag names assigned to each asset. Default: `false`.
context	Boolean	Whether to include key-value pairs of contextual metadata associated with each asset. Default: `false`.
moderations	Boolean	Whether to include image moderation status of each asset. Default: `false`.

Examples

Get all images by tag:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.resources_by_tag('mytag')

PHP (cloudinary_php 2.x):

$result = $api
->assetsByTag("mytag");

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->resources_by_tag("mytag");

Python (cloudinary 1.x):

result = cloudinary.api\
.resources_by_tag("mytag")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.resources_by_tag("mytag")
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.resourcesByTag("mytag", ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

result = cloudinary
.ListResourcesByTag("mytag");

Go (cloudinary-go 1.x):

resp, err := cld.Admin.AssetsByTag(ctx, admin.AssetsByTagParams{Tag: "mytag"})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/tags/mytag

cli:

cld admin resources_by_tag mytag

Get all raw files by tag:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.resources_by_tag('mytag',
  :resource_type => :raw)

PHP (cloudinary_php 2.x):

$result = $api
->assetsByTag("mytag", ["resource_type" => "raw"]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->resources_by_tag("mytag", ["resource_type" => "raw"]);

Python (cloudinary 1.x):

result = cloudinary.api\
.resources_by_tag("mytag",
resource_type = "raw")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.resources_by_tag("mytag", 
  { resource_type: 'raw'})
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.resourcesByTag("mytag", 
  ObjectUtils.asMap("resource_type", "raw"));

.NET (CloudinaryDotNet 1.x):

var listResourcesParams = new ListResourcesByTagParams(){
  Tag = "mytag",
  ResourceType = "raw"};
var listResourcesResult = cloudinary.ListResources(ListResourcesByTagParams);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.AssetsByTag(ctx, admin.AssetsByTagParams{
        Tag:          "mytag",
        DeliveryType: "raw"})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/raw/tags/mytag

cli:

cld admin resources_by_tag mytag resource_type=raw

Get resources by context

Retrieves resources (assets) with a specified contextual metadata key. This method does not return deleted assets even if they have been backed up.

Syntax

GET /resources/:resource_type/context/

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.resources_by_context(key, options = {})

PHP (cloudinary_php 2.x):

$api->assetsByContext($key, $options = []));

PHP (cloudinary_php 1.x (legacy)):

$api->resources_by_context($key, $options = []));

Python (cloudinary 1.x):

cloudinary.api.resources_by_context(key, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.resources_by_context(key, options).then(callback);

Java (cloudinary 1.x):

api.resourcesByContext(String key, Map options);

.NET (CloudinaryDotNet 1.x):

Not supported by this SDK

Go (cloudinary-go 1.x):

resp, err := cld.Admin.AssetsByContext(ctx, admin.AssetsByContextParams{})

cli:

cld admin resources_by_context $key $options

Required parameters

Parameter	Type	Description
key	String	Only assets with this contextual metadata key are returned.

Optional parameters

Parameter	Type	Description
resource_type	String	The type of asset. Relevant as a parameter only when using the SDKs (the `resource_type` is included in the endpoint URL when using the REST API). Note: use `video` for all video and audio assets, such as .mp3. Possible values: `image` (default), `raw`, `video`.
value	String	Only assets with this value for the contextual metadata key are returned. If this parameter is not provided, all assets with the given contextual metadata key are returned, regardless of the actual value of the key.
max_results	Integer	Maximum number of assets to return (maximum=500). Default: `10`.
next_cursor	String	When a request has more results to return than `max_results`, the `next_cursor` value is returned as part of the response. You can then specify this value as the `next_cursor` parameter of the following request.
direction	String/Integer	Control the order of returned assets, according to the `created_at` date. Note: if a `prefix` is specified, this parameter is ignored and the results are sorted by public ID. Possible values: `desc` or `-1` (default), `asc` or `1`.
tags	Boolean	Whether to include the list of tag names assigned to each asset. Default: `false`.
context	Boolean	Whether to include key-value pairs of contextual metadata associated with each asset. Default: `false`.
moderations	Boolean	Whether to include image moderation status of each asset. Default: `false`.

Examples

Get images by contextual metadata key:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.resources_by_context('mycontextkey')

PHP (cloudinary_php 2.x):

$result = $api
->assetsByContext("mycontextkey");

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->resources_by_context("mycontextkey");

Python (cloudinary 1.x):

result = cloudinary.api\
.resources_by_context("mycontextkey")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.resources_by_context("mycontextkey")
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.resourcesByContext("mycontextkey", ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

Not supported by this SDK

Go (cloudinary-go 1.x):

resp, err := cld.Admin.AssetsByContext(ctx, admin.AssetsByContextParams{
        Key: "mycontextkey"})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/context?key=mycontextkey

cli:

cld admin resources_by_context "mycontextkey"

Get video files by contextual metadata key and value:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.resources_by_context('mycontextkey', 'mycontextvalue',
  :resource_type => :video)

PHP (cloudinary_php 2.x):

$result = $api
->assetsByContext("mycontextkey", "mycontextvalue"
  ["resource_type" => "video"]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->resources_by_context("mycontextkey", "mycontextvalue"
  ["resource_type" => "video"]);

Python (cloudinary 1.x):

result = cloudinary.api\
.resources_by_context("mycontextkey", "mycontextvalue"
  resource_type = "video")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.resources_by_context("mycontextkey", "mycontextvalue", 
  { resource_type: 'video'})
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api.resourcesByContext("mycontextkey", "mycontextvalue", 
  ObjectUtils.asMap("resource_type", "video"));

.NET (CloudinaryDotNet 1.x):

Not supported by this SDK

Go (cloudinary-go 1.x):

resp, err := cld.Admin.AssetsByContext(ctx, admin.AssetsByContextParams{
      Key:            "mycontextkey", 
      Value:          "mycontextvalue",
      DeliveryType:   "video"})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/video/context?key=mycontextkey&value=mycontextvalue

cli:

cld admin resources_by_context "mycontextkey" value="mycontextvalue" resource_type="video"

Get resources in moderation

Retrieves resources (assets) with a particular status from a specified moderation type.

Syntax

GET /resources/:resource_type/moderations/:moderation_kind/:status

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.resources_by_moderation(moderation_kind, status, options = {})

PHP (cloudinary_php 2.x):

$api->assetsByModeration($moderation_kind, $status, $options = []);

PHP (cloudinary_php 1.x (legacy)):

$api->resources_by_moderation($moderation_kind, $status, $options = []);

Python (cloudinary 1.x):

cloudinary.api.resources_by_moderation(moderation_kind, status, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.resources_by_moderation(moderation_kind, status, options).then(callback);

Java (cloudinary 1.x):

cloudinary.api().resourcesByModeration(String moderation_kind, String status, Map options);

.NET (CloudinaryDotNet 1.x):

cloudinary.ListResourcesByModerationStatus(ModerationStatus Params);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.AssetsByModeration(ctx, admin.AssetsByModerationParams{})

cli:

cld admin resources_by_moderation (moderation_kind, status)

Required parameters

Parameter	Type	Description
moderation_kind	String	The type of moderation list to retrieve. Possible values: `manual`, `webpurify`, `aws_rek`, `perception_point`.
status	String	The moderation status of assets to retrieve. Possible values: `pending`, `approved`, `rejected`, `queued`, `aborted`. Note: `queued` and `aborted` are relevant only when an asset is marked for multiple moderations.

Optional parameters

Parameter	Type	Description
resource_type	String	The type of asset. Relevant as a parameter only when using the SDKs (the `resource_type` is included in the endpoint URL when using the REST API). Note: use `video` for all video and audio assets, such as .mp3. Possible values: `image` (default), `raw`, `video`.
max_results	Integer	Maximum number of assets to return (maximum=500). Default: `10`.
next_cursor	String	When a request has more results to return than `max_results`, the `next_cursor` value is returned as part of the response. You can then specify this value as the `next_cursor` parameter of the following request.
direction	String/Integer	Control the order of returned assets, according to the `created_at` date. Note: if a `prefix` is specified, this parameter is ignored and the results are sorted by public ID. Possible values: `desc` or `-1` (default), `asc` or `1`.
tags	Boolean	Whether to include the list of tag names assigned to each asset. Default: `false`.
context	Boolean	Whether to include key-value pairs of contextual metadata associated with each asset. Default: `false`.
moderations	Boolean	Whether to include image moderation status of each asset. Default: `false`.

Examples

Get images pending manual moderation:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.resources_by_moderation("manual", "pending")

PHP (cloudinary_php 2.x):

$result = $api
->assetsByModeration("manual", "pending");

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->resources_by_moderation("manual", "pending");

Python (cloudinary 1.x):

result = cloudinary.api\
.resources_by_moderation("manual", "pending")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.resources_by_moderation('manual', 'pending')
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = cloudinary.api()
.resourcesByModeration("manual", "pending",
  ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

result = cloudinary
.ListResourcesByModerationStatus("manual", "pending");

Go (cloudinary-go 1.x):

resp, err := cld.Admin.AssetsByModeration(ctx, admin.AssetsByModerationParams{
      Kind:   "manual", 
      Status: "pending"})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/moderations/manual/pending

cli:

cld admin resources_by_moderation manual pending

Get images automatically approved by the WebPurify add-on:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.resources_by_moderation("webpurify", "approved")

PHP (cloudinary_php 2.x):

$result = $api
->assetsByModeration("webpurify", "approved");

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->resources_by_moderation("webpurify", "approved");

Python (cloudinary 1.x):

result = cloudinary\
.api.resources_by_moderation("webpurify", "approved")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.resources_by_moderation('webpurify', 'approved')
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = cloudinary.api()
.resourcesByModeration("webpurify", "approved",
  ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

result = cloudinary
.ListResourcesByModerationStatus("webpurify", "approved");

Go (cloudinary-go 1.x):

resp, err := cld.Admin.AssetsByModeration(ctx, admin.AssetsByModerationParams{
      Kind:   "webpurify", 
      Status: "approved"})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/moderations/webpurify/approved

cli:

cld admin resources_by_moderation webpurify approved

Sample response

{
   "resources":
    [{
      "asset_id": "e590ea35ca6f56ee383e0437e43e1c54",
      "public_id": "q7vcvrfjm9mj4bfp3qc8",
      "format": "jpg",
      "version": 1570976812,
      "resource_type": "image",
      "type": "upload",
      "created_at": "2014-03-02T21:06:43Z",
      "bytes": 120253,
      "width": 864,
      "height": 576,
      "backup": true,
      "access_mode": "public",
      "url":
       "http://res.cloudinary.com/demo/image/upload/v1570976812/q7vcvrfjm9mj4bfp3qc8.jpg",
      "secure_url":
       "https://res.cloudinary.com/demo/image/upload/v1570976812/q7vcvrfjm9mj4bfp3qc8.jpg"
     },
     {
      "asset_id": "53270b5120ab81ede6f570a203677652",
      "public_id": "zp4fgdbabhlwwa7bxu84",
      "format": "jpg",
      "version": 1570977154,
      "resource_type": "image",
      "type": "upload",
      "created_at": "2014-03-02T21:06:39Z",
      "bytes": 120253,
      "width": 864,
      "height": 576,
      "backup": true,
      "access_mode": "public",
      "url":
       "http://res.cloudinary.com/demo/image/upload/v1570977154/zp4fgdbabhlwwa7bxu84.jpg",
      "secure_url":
       "https://res.cloudinary.com/demo/image/upload/v1570977154/zp4fgdbabhlwwa7bxu84.jpg"
     }
   ]
}

Get details of a single resource by public ID

Retrieves details of the requested resource (asset), the date and time that specific changes were made to asset attributes, and details of all derived assets.

GET /resources/:resource_type/:type/:public_id

Syntax

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.resource(public_id, options = {})

PHP (cloudinary_php 2.x):

$api->asset($public_id, $options = []);

PHP (cloudinary_php 1.x (legacy)):

$api->resource($public_id, $options = []);

Python (cloudinary 1.x):

cloudinary.api.resource(public_id, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.resource(public_id, options).then(callback);

Java (cloudinary 1.x):

api.resource(String public_id, Map options);

.NET (CloudinaryDotNet 1.x):

cloudinary.GetResource(ResourceParams params);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.Asset(ctx, admin.AssetParams{})

cli:

cld admin resource (public_id)

Required parameters

Parameter	Type	Description
public_id	String	The public ID of the asset.

Optional parameters

Parameter	Type	Description
resource_type	String	The type of asset. Relevant as a parameter only when using the SDKs (the `resource_type` is included in the endpoint URL when using the REST API). Note: use `video` for all video and audio assets, such as .mp3. Possible values: `image` (default), `raw`, `video`.
type	String	The delivery type, relevant as a parameter only when using the SDKs (the `type` is included in the endpoint URL when using the REST API). Possible values: `upload`, `private`, `authenticated`, `facebook`, `twitter`, `gravatar`, `youtube`, `hulu`, `vimeo`, `animoto`, `worldstarhiphop`, `dailymotion`. Default: all.
colors	Boolean	Whether to include color information: predominant colors and histogram of 32 leading colors. Default: `false`.
media_metadata	Boolean	Whether to include IPTC, XMP, and detailed Exif metadata in the response. Default: `false`. This parameter applies to both `image` and `video` asset types (including audio files). The exact set of metadata fields that gets returned for an asset depends on the asset type. Note: Using this parameter also returns the asset's ETag value for all asset types, including raw.
exif	Boolean	Deprecated. Use `media_metadata` instead. Default: `false`.
image_metadata	Boolean	Deprecated. Use `media_metadata` instead. Default: `false`.
faces	Boolean	Whether to include a list of coordinates of detected faces. Default: `false`.
quality_analysis	Boolean	Whether to return quality analysis scores for the image. Default: `false`.
accessibility_analysis	Boolean	Whether to return accessibility analysis scores for the image. Default: `false`.
pages	Boolean	Whether to report the number of pages in multi-page documents (e.g., PDF). Default: `false`.
phash	Boolean	Whether to include the perceptual hash (pHash) of the uploaded photo for image similarity detection. Default: `false`.
coordinates	Boolean	Whether to include previously specified custom cropping coordinates and faces coordinates. Default: `false`.
versions	Boolean	Whether to include details of all the backed up versions of the asset. Default: `false`.
related	Boolean	Whether to include the list of assets related to this asset. Default: `false`.
related_next_cursor	String	If there are more than 100 `related` assets, the `related_next_cursor` value is returned as part of the response. You can then specify this value as the `related_next_cursor` parameter of the following request.
max_results	Integer	Maximum number of derived assets to return (maximum=500). Default: `10`.
derived_next_cursor	String	If there are more derived images than `max_results`, the `derived_next_cursor` value is returned as part of the response. You can then specify this value as the `derived_next_cursor` parameter of the following request.

Examples

Uploaded image details:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.resource('sample')

PHP (cloudinary_php 2.x):

$result = $api
->asset("sample");

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->resource("sample");

Python (cloudinary 1.x):

result = cloudinary\
.api.resource("sample")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.resource('sample')
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api.resource("sample", ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

result = cloudinary.GetResource("sample");

Go (cloudinary-go 1.x):

resp, err := cld.Admin.Asset(ctx, admin.AssetParams{PublicID: "sample"})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload/sample

cli:

cld admin resource sample

Faces, colors, media metadata and versions details:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.resource('sample',
  :faces => true, 
  :colors => true, 
  :media_metadata => true,
  :versions => true)

PHP (cloudinary_php 2.x):

$result = $api
->asset("sample", [
    "faces" => TRUE, 
    "colors" => TRUE, 
    "media_metadata" => TRUE,
    "versions" => TRUE]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->resource("sample", [
    "faces" => TRUE, 
    "colors" => TRUE, 
    "media_metadata" => TRUE,
    "versions" => TRUE]);

Python (cloudinary 1.x):

result = cloudinary.api\
.resource("sample",
  faces = True, 
  colors = True, 
  media_metadata = True,
  versions = True)

Node.js (cloudinary 1.x):

cloudinary.v2.api
.resource('sample', 
  { faces: true, 
    colors: true, 
    media_metadata: true,
    versions: true })
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.resource("sample", 
  ObjectUtils.asMap(
    "faces", true,
    "colors", true, 
    "media_metadata", true,
    "versions", true));

.NET (CloudinaryDotNet 1.x):

var getResource = new GetResourceParams("sample"){
  Faces = true,

Colors = ImageMetadata = Versions = true };
var info = cloudinary.GetResource(getResource);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.Asset(ctx, admin.AssetParams{
        PublicID:       "sample",
        Faces:          api.Bool(true),
        Colors:         api.Bool(true),
        ImageMetadata:  api.Bool(true),
        Versions:       api.Bool(true)})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload/sample?faces=1&colors=1&media_metadata=1&versions=1

cli:

cld admin resource sample faces=true colors=true media_metadata=true versions=true

Facebook picture details:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.resource('4', 
  :type => :facebook)

PHP (cloudinary_php 2.x):

$result = $api
->asset("4", 
  ["type" => "facebook"]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->resource("4", 
  ["type" => "facebook"]);

Python (cloudinary 1.x):

result = cloudinary.api\
.resource("4", 
  type = "facebook")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.resource('4', 
  { type: 'facebook' })
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.resource("4", 
  ObjectUtils.asMap("type", "facebook"));

.NET (CloudinaryDotNet 1.x):

var getResource = new GetResourceParams("4"){
Type = "facebook" };
var info = cloudinary.GetResource(getResource);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.Asset(ctx, admin.AssetParams{
        PublicID:       "sample",
        DeliveryType:   "facebook"})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/facebook/4

cli:

cld admin resource "4" type=facebook

Uploaded raw file details:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.resource('rwkaliebnufp3bxyrvyo.txt',
  :resource_type => :raw)

PHP (cloudinary_php 2.x):

$result = $api
->asset("rwkaliebnufp3bxyrvyo.txt",
  ["resource_type" => "raw"]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->resource("rwkaliebnufp3bxyrvyo.txt",
  ["resource_type" => "raw"]);

Python (cloudinary 1.x):

result = cloudinary.api\
.resource("rwkaliebnufp3bxyrvyo.txt",
  resource_type = "raw")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.resource('rwkaliebnufp3bxyrvyo.txt', 
  { resource_type: 'raw'})
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api.resource("rwkaliebnufp3bxyrvyo.txt",
  ObjectUtils.asMap("resource_type", "raw"));

.NET (CloudinaryDotNet 1.x):

var getResource = new GetResourceParams("rwkaliebnufp3bxyrvyo.txt"){
ResourceType = "raw" };
var info = cloudinary.GetResource(getResource);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.Asset(ctx, admin.AssetParams{
        PublicID:   "rwkaliebnufp3bxyrvyo.txt",
        AssetType:  "raw"})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/raw/upload/rwkaliebnufp3bxyrvyo.txt

cli:

cld admin resource rwkaliebnufp3bxyrvyo.txt resource_type=raw

Sample response

This sample response is from the request including faces, colors and versions:

{
    "asset_id": "d86882d7788f5d1d702cb63418f082a6",
    "public_id": "sample",
    "format": "jpg",
    "version": 1312461204,
    "resource_type": "image",
    "type": "upload",
    "created_at": "2011-08-04T12:33:24Z",
    "bytes": 120253,
    "width": 864,
    "height": 576,
    "access_mode": "public",
    "url": "http://res.cloudinary.com/demo/image/upload/v1312461204/sample.jpg",
    "secure_url": "https://.../image/upload/v1312461204/sample.jpg",
    "tags": [
      "flower",
      "plant",
      "naturet"
    ],
    "context": {
      "custom": {
        "alt": "sample flower",
        "caption": "beautiful flower"
      }
    },
    "metadata": {
      "approval_status_0": "status_new",
      "categories_0": [
          "cat_mens_clothes",
          "cat_shirts",
          "qzaihnfnasrzba0qrdpr"
      ],
      "owner_0": "Adam Adams",
      "product_id_0": 12345,
      "publish_date_0": "2022-02-17"
    },
    "last_updated": {
      "access_control_updated_at": "2022-10-13T03:49:21Z",
      "context_updated_at": "2022-11-10T06:05:21Z",
      "metadata_updated_at": "2022-10-14T06:40:13Z",
      "public_id_updated_at": "2022-12-11T05:41:21Z",
      "tags_updated_at": "2022-12-14T06:09:21Z", 
      "updated_at": "2022-12-14T06:09:21Z"
    },
    "next_cursor": "041a39fc10971b9eabd4993470f6bfaf",
    "derived": [
      {
        "transformation": "c_fill,w_100,h_100",
        "format": "jpg",
        "bytes": 7112,
        "id": "8267a869b62a93a59248f35d7f124c1f",
        "url": "http://.../demo/image/upload/c_fill,w_100,h_100/v1312461204/sample.jpg",
        "secure_url": "https://.../image/upload/c_fill,w_100,h_100/v1312461204/sample.jpg"
      },
      {
        "transformation": "w_230,h_168,c_fit",
        "format": "jpg",
        "bytes": 19173,
        "id": "383e22a57167445552a3cdc16f0a0c85",
        "url": "http://.../demo/image/upload/w_230,h_168,c_fit/v1312461204/sample.jpg",
        "secure_url": "https://.../image/upload/w_230,h_168,c_fit/v1312461204/sample.jpg"
      }
    ],
    "etag": "619dfd2901577eb4259f91a2c0e43dac",
    "faces": [[98,74,61,83], [140,130,52,71]],
    "illustration_score": 0.0,
    "semi_transparent": false,
    "grayscale": false,
    "colors": [["#162E02",6.7], ["#385B0C",6.3], ["#F3285C",5.0], ["#B3CB6E",5.0], ["#688F1C",4.4], ["#324D07",4.4], ["#8EAA34",4.3], ["#4F6D0D",4.2], ["#789446",4.1], ["#DF1327",3.9], ["#A10B12",3.7], ["#273804",3.4], ["#0D1802",3.4], ["#D5E191",3.2], ["#646E20",3.1], ["#94AF4D",2.9], ["#FB54A9",2.8], ["#48570B",2.7], ["#ACC655",2.7], ["#FCA2D9",2.7], ["#63110A",2.6], ["#E9B327",2.2], ["#6D644D",2.1], ["#6D8D12",2.0], ["#8F9F27",1.9], ["#C3573E",1.8], ["#CFD76E",1.6], ["#A0B058",1.6], ["#FCD0E9",1.6], ["#728F2D",1.4], ["#F958A1",1.4], ["#D1B694",1.0]],

    "predominant": {
      "google": [
        [
          "yellow",
          52.9
        ],
        [
          "pink",
          13.5
        ],
        [
          "red",
          12.0
        ],
        [
          "black",
          10.1
        ],
        [
          "green",
          6.3
        ]
      ]
    },

    "versions": [
        {
            "version_id": "d214063097a43d1d1293db61a397f60f",
            "version": "1312461204",
            "format": "jpg",
            "size": 109669,
            "time": "2011-08-04T12:33:24+00:00",
            "restorable": false
        }
    ]
}

Get details of a single resource by asset ID

Returns the details of the asset with the specified asset ID, including details on all derived assets. This enables you to get all details of an asset by its immutable identifier, regardless of public ID, display name, asset folder, resource type or deliver type.

Syntax

GET /resources/:asset_id

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.resource_by_asset_id(asset_id, options = {})

PHP (cloudinary_php 2.x):

$api->assetByAssetId($asset_id, $options = []);

PHP (cloudinary_php 1.x (legacy)):

Not supported in this version of the SDK.

Python (cloudinary 1.x):

cloudinary.api.resource_by_asset_id(asset_id, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.resource_by_asset_id(asset_id, options, callback);

Java (cloudinary 1.x):

api.resourceByAssetId(String asset_id, Map options);

.NET (CloudinaryDotNet 1.x):

cloudinary.GetResourceByAssetID(GetResourceByAssetIDParams params);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.AssetByAssetID(ctx, admin.AssetByAssetIDParams{})

cli:

cld admin resource_by_asset_id (asset_id)

Optional parameters

Parameter	Type	Description
colors	Boolean	Whether to include color information: predominant colors and histogram of 32 leading colors. Default: `false`.
image_metadata	Boolean	Whether to include IPTC, XMP, and detailed Exif metadata in the response. Default: `false`. This parameter applies to both `image` and `video` asset types (including audio files). The exact set of metadata fields that gets returned for an asset depends on the asset type. Note: Using this parameter also returns the asset's ETag value for all asset types, including raw.
faces	Boolean	Whether to include a list of coordinates of detected faces. Default: `false`.
quality_analysis	Boolean	Whether to return quality analysis scores for the image. Default: `false`.
accessibility_analysis	Boolean	Whether to return accessibility analysis scores for the image. Default: `false`.
pages	Boolean	Whether to report the number of pages in multi-page documents (e.g., PDF). Default: `false`.
phash	Boolean	Whether to include the perceptual hash (pHash) of the uploaded photo for image similarity detection. Default: `false`.
coordinates	Boolean	Whether to include previously specified custom cropping coordinates and faces coordinates. Default: `false`.
versions	Boolean	Whether to include details of all the backed up versions of the asset. Default: `false`.
max_results	Integer	Maximum number of derived assets to return (maximum=500). Default: `10`.
derived_next_cursor	String	If there are more derived images than `max_results`, the `derived_next_cursor` value is returned as part of the response. You can then specify this value as the `derived_next_cursor` parameter of the following request.

Examples

Get details of the asset with the specified asset ID, including faces, colors, image metadata and versions details:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

Cloudinary::Api.resource_by_asset_id('e12345b5c456c8901bbb0efc00c0fcf',
  :faces => true, 
  :colors => true, 
  :image_metadata => true,
  :versions => true)

PHP (cloudinary_php 2.x):

$api->assetByAssetId("e12345b5c456c8901bbb0efc00c0fcf", [
    "faces" => TRUE, 
    "colors" => TRUE, 
    "image_metadata" => TRUE,
    "versions" => TRUE]);

PHP (cloudinary_php 1.x (legacy)):

$api->resource_by_asset_id("e12345b5c456c8901bbb0efc00c0fcf", [
    "faces" => TRUE, 
    "colors" => TRUE, 
    "image_metadata" => TRUE,
    "versions" => TRUE]);

Python (cloudinary 1.x):

cloudinary.api.resource_by_asset_id("e12345b5c456c8901bbb0efc00c0fcf",
  faces = True, 
  colors = True, 
  image_metadata = True,
  versions = True)

Node.js (cloudinary 1.x):

cloudinary.v2.api.resource_by_asset_id('e12345b5c456c8901bbb0efc00c0fcf', 
  { faces: true, 
    colors: true, 
    image_metadata: true,
    versions: true },
  function(error, result) {console.log(result, error); });

Java (cloudinary 1.x):

api.resourceByAssetId("e12345b5c456c8901bbb0efc00c0fcf", 
  ObjectUtils.asMap(
    "faces", true,
    "colors", true, 
    "image_metadata", true,
    "versions", true));

.NET (CloudinaryDotNet 1.x):

var getResourceByAssetID = new GetResourceByAssetIDParams("e12345b5c456c8901bbb0efc00c0fcf"){
  Faces = true,
  Colors = ImageMetadata = Versions = true };
var info = cloudinary.GetResourceByAssetID(getResourceByAssetID);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.AssetByAssetID(ctx, admin.AssetByAssetIDParams{
        PublicID:       "e12345b5c456c8901bbb0efc00c0fcf",
        Faces:          true,
        Colors:         true,
        ImageMetadata:  true,
        Versions:       true})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/e12345b5c456c8901bbb0efc00c0fcf?faces=1&colors=1&image_metadata=1&versions=1

cli:

cld admin resource_by_asset_id e12345b5c456c8901bbb0efc00c0fcf faces=true colors=true image_metadata=true versions=true

Search for resources

Search allows you fine control on filtering and retrieving information on all the resources (assets) in your product environment with the help of query expressions in a Lucene-like query language.

For detailed information on the search method and building expressions, see the Search API documentation.

Note

Request parameters cannot be appended to the endpoint URL as in the other Admin API methods. Search API parameters are passed as JSON data.

Syntax

GET /resources/search

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

result = Cloudinary::Search.execute

PHP (cloudinary_php 2.x):

$result = $cloudinary->searchApi()->execute();

PHP (cloudinary_php 1.x (legacy)):

$result = \Cloudinary\search->execute();

Python (cloudinary 1.x):

result = cloudinary.Search().expression().execute()

Node.js (cloudinary 1.x):

cloudinary.v2.search.execute().then(callback);

Java (cloudinary 1.x):

result = cloudinary.search().execute();

.NET (CloudinaryDotNet 1.x):

SearchResult result = cloudinary.Search().Execute();

Go (cloudinary-go 1.x):

resp, err := cld.Admin.Search(ctx, search.Query{})

cli:

cld search

Note

Cloudinary implements eventual consistency: any changes made to assets will only be reflected in a search made a few seconds after the change is processed.

Optional parameters

All the parameters of the search method are optional. Including no parameters in the method call will return the 50 most recently created resources in descending order of creation time.

Parameter	Type	Description
expression	String	The (Lucene-like) string expression specifying the search query. If this parameter is not provided then all resources are listed (up to `max_results`). For details, see the expressions documentation.
sort_by	String[]	An array of string values representing a key value pair, where the key is the field to sort by and the value is the direction. Valid sort directions are `asc` or `desc`. If this parameter is not provided then the results are sorted by descending creation date. You can specify more than one `sort_by` parameter; results will be sorted according to the order of the fields provided.
max_results	Integer	Maximum number of assets to return (maximum=500). Default: `10`.
next_cursor	String	When a request has more results to return than `max_results`, the `next_cursor` value is returned as part of the response. You can then specify this value as the `next_cursor` parameter of the following request.
with_field	String	The name of an additional asset attribute to include for each asset in the response. You can specify more than one `with_field` parameter. Possible value: `context`, `tags`, and for Tier 2 also `metadata`, `image_metadata`, and `image_analysis`.
aggregate	String	(Tier 2 only) The name of a field (attribute) for which an aggregation count should be calculated and returned in the response. You can specify more than one `aggregate` parameter. Supported values: `resource_type`, `type`, `pixels` (only the image assets in the response are aggregated), `duration` (only the video assets in the response are aggregated), `format`, and `bytes`. For aggregation fields without discrete values, the results are divided into categories. For example: - `bytes` are divided into small (<500 kb), medium (500 kb - 5 mb), large (5 mb - 100 mb), and huge (>100 mb). - Video `duration` is divided into short (< 3 minutes), medium (3-12 min), and long (> 12 min).

Important

A new Search query object should be initialized for every distinct query executed. Please avoid reusing the same instance of a Search query object, as that might lead to unexpected behavior, especially when using the sort_by parameter.
When iterating through the results using the next_cursor parameter, the query should be reused without changing any of the other parameter values.
When making direct calls to the Cloudinary endpoint, make sure to pass any parameters using JSON (with Content-Type: application/json) as in the cURL examples on this page.

Examples

Find assets containing 'cat' in any field (attribute), include context metadata and tags in the details of each resource, and limit the returned results to 10 resources:

Ruby PHP Python Node.js Java .NET Go Endpoint All

Ruby (cloudinary 1.x):

result = Cloudinary::Search
  .expression('cat')
  .with_field('context')
  .with_field('tags')
  .max_results(10)
  .execute

PHP (cloudinary_php 2.x):

$result = $cloudinary->searchApi()
  ->expression('cat')
  ->withField('context')
  ->withField('tags')
  ->maxResults(10)
  ->execute();

PHP (cloudinary_php 1.x (legacy)):

$result = \Cloudinary\search
  ->expression('cat')
  ->with_field('context')
  ->with_field('tags')
  ->max_results(10)
  ->execute();

Python (cloudinary 1.x):

result = cloudinary.Search()\
  .expression("cat")\
  .with_field("context")\
  .with_field("tags")\
  .max_results("10")\
  .execute()

Node.js (cloudinary 1.x):

cloudinary.v2.search
  .expression('cat')
  .with_field('context')
  .with_field('tags')
  .max_results(10)
  .execute()
  .then(result=>console.log(result));

Java (cloudinary 1.x):

result = cloudinary.search()
  .expression("cat")
  .withField("context")
  .withField("tags")
  .maxResults(10)
  .execute();

.NET (CloudinaryDotNet 1.x):

SearchResult result = cloudinary.Search()
  .Expression("cat")
  .WithField("context")
  .WithField("tags")
  .MaxResults(10)
  .Execute();

Go (cloudinary-go 1.x):

resp, err := cld.Admin.Search(ctx, search.Query{
          Expression: "cat",
          WithField:  []string{"tags", "context"},
          MaxResults: 10})

endpoint:

curl \
  -H "Content-Type: application/json" \
  -d '{
        "expression": "cat",
        "with_field": ["context", "tags"],
        "max_results": 10
      }' \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/search

cli:

cld search "cat" -f context -f tags -n 10

Find assets containing 'cat' in any field but not 'kitten' in the tags field, sort the results by public_id in descending order, and calculate an aggregation count based on the values of the format field:

Ruby PHP Python Node.js Java .NET Go Endpoint All

Ruby (cloudinary 1.x):

result = Cloudinary::Search
  .expression('cat AND -tags:kitten')
  .sort_by('public_id','desc')
  .aggregate('format')
  .execute

PHP (cloudinary_php 2.x):

$result = $cloudinary->searchApi()
  ->expression('cat AND -tags:kitten')
  ->sortBy('public_id','desc')
  ->aggregate('format')
  ->execute();

PHP (cloudinary_php 1.x (legacy)):

$result = \Cloudinary\search()
  ->expression('cat AND -tags:kitten')
  ->sort_by('public_id','desc')
  ->aggregate('format')
  ->execute();

Python (cloudinary 1.x):

result = cloudinary.Search()\
  .expression("cat AND -tags:kitten")\
  .sort_by("public_id","desc")\
  .aggregate("format")\
  .execute()

Node.js (cloudinary 1.x):

cloudinary.v2.search
  .expression('cat AND -tags:kitten')
  .sort_by('public_id','desc')
  .aggregate('format')
  .execute()
  .then(result=>console.log(result));

Java (cloudinary 1.x):

result = cloudinary.search()
  .expression("cat AND -tags:kitten")
  .sortBy("public_id","desc")
  .aggregate("format")
  .execute();

.NET (CloudinaryDotNet 1.x):

SearchResult result = cloudinary.Search()
  .Expression("cat AND -tags:kitten")
  .SortBy("public_id","desc")
  .Aggregate("format")
  .Execute();

Go (cloudinary-go 1.x):

resp, err := cld.Admin.Search(ctx, search.Query{
      Expression: "cat AND -tags:kitten",
      SortBy:     []search.SortByField{{"public_id": "desc"}},
      Aggregate:  []string{"format"},
      MaxResults: 2})

endpoint:

curl \
  -H "Content-Type: application/json" \
  -d '{
        "expression": "cat AND -tags:kitten",
        "sort_by": [{"public_id": "desc"}],
        "aggregate": ["format"]
      }' \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/search

cli:

cld search "cat AND -tags:kitten" -s public_id desc -a format

Tip

For more examples, see the expression examples documentation.

Sample response

{
  "total_count": 32,
  "time": 30,
  "aggregations": {
    "format": {
      "png": 4,
      "jpg": 21,
      "mp4": 3,
      "doc": 4
    }
  },
  "next_cursor": "b16b8bd80426df43a107f26b0348",
  "resources": [
  {
    "asset_id": "5f9d30acd36ac3c4f48a82241a37a299",
    "public_id": "sample",
    "folder": "",
    "filename": "sample",
    "format": "png",
    "version": 1492606756,
    "resource_type": "image",
    "type": "upload",
    "created_at": "2017-04-03T09:56:49+00:00",
    "uploaded_at": "2017-04-19T12:59:16+00:00",
    "bytes": 3381,
    "backup_bytes": 16905,
    "width": 241,
    "height": 51,
    "aspect_ratio": 4.7254901960784315,
    "pixels": 12291,
    "access_control": [       
     { access_type: "token" },
     { access_type: "anonymous", start: "2017-12-15T12:00Z", end: "2018-01-20T12:00Z" }],
    "context": {},
    "image_analysis": { 
      "face_count": 0,
      "faces": [],
      "grayscale": true,
      "illustration_score": 1,
      "transparent": false,
      "colors": {
        "gray": 96.7
      }
    },
    "url": "http://res.cloudinary.com/demo/image/upload/v1492606756/sample.png",
    "secure_url": "https://res.cloudinary.com/demo/image/upload/v1492606756/sample.png",
    "status": "active",
    "access_mode": "public",
    "last_updated": {
      "access_control_updated_at": "2022-10-13T03:49:21Z",
      "context_updated_at": "2022-11-10T06:05:21Z",
      "metadata_updated_at": "2022-10-14T06:49:13Z",
      "public_id_updated_at": "2022-12-11T05:41:21Z",
      "tags_updated_at": "2022-12-14T06:49:21Z", 
      "updated_at": "2022-12-14T06:49:21Z"
    }
  },
  {
    "public_id": "dog",
     …
     …
  }
  …
}

Update details of an existing resource

Update one or more of the attributes associated with a specified resource (asset). Note that you can also update many attributes of an existing asset using the explicit method, which is not rate limited.

Syntax

POST /resources/:resource_type/:type/:public_id

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.update(public_id, options = {})

PHP (cloudinary_php 2.x):

$api->update($public_id, $options = []);

PHP (cloudinary_php 1.x (legacy)):

$api->update($public_id, $options = []);

Python (cloudinary 1.x):

cloudinary.api.update(public_id, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.update(public_id, options).then(callback);

Java (cloudinary 1.x):

cloudinary.api().update(String public_id, Map options);

.NET (CloudinaryDotNet 1.x):

cloudinary.UpdateResource(UpdateParams params);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.UpdateAsset(ctx, admin.UpdateAssetParams{})

cli:

cld admin update (public_id)

Required parameters

Parameter	Type	Description
public_id	String	The public ID of the asset to update.

Optional parameters

Parameter	Type	Description
resource_type	String	The type of asset. Relevant as a parameter only when using the SDKs (the `resource_type` is included in the endpoint URL when using the REST API). Note: use `video` for all video and audio assets, such as .mp3. Possible values: `image` (default), `raw`, `video`.
type	String	The delivery type, relevant as a parameter only when using the SDKs (the `type` is included in the endpoint URL when using the REST API). Possible values: `upload`, `private`, `authenticated`, `facebook`, `twitter`, `gravatar`, `youtube`, `hulu`, `vimeo`, `animoto`, `worldstarhiphop`, `dailymotion`. Default: all.
tags	String	A comma-separated list of tag names to assign to the uploaded asset for later group reference.
context	String	A map (using the SDKs) or pipe-separated list (for REST API calls) of key-value pairs of contextual metadata to attach to an uploaded asset. The contextual metadata values of uploaded files can be retrieved using the Admin API. For example: `alt=My image
metadata	String	A map (supported for Java SDK only) or pipe-separated list (for REST API calls) of custom metadata fields (by external_id) and the values to assign to each of them. The =, " and ❘ characters can be supported as values when escaped with a prepended backslash (`\`). For example: `in_stock_id=50❘color_id=[\"green\",\"red\"]`.
face_coordinates	String	List of coordinates of faces contained in an uploaded image. The given coordinates are used for cropping uploaded images using the `face` or `faces` gravity mode. The specified coordinates override the automatically detected faces. Each face is specified by the X & Y coordinates of the top left corner and the width & height of the face. The coordinates are comma separated while faces are concatenated with a pipe (`
custom_coordinates	String	Coordinates of an interesting region contained in an uploaded image. The given coordinates are used for cropping uploaded images using the `custom` gravity mode. The region is specified by the X & Y coordinates of the top left corner and the width & height of the region. For example: `85,120,220,310`.
quality_override	Integer	Sets a quality value for this asset that will override any automatic quality transformations (q_auto) for this specific asset.
moderation_status	String	Manually set image moderation status or override previously automatically moderated images by approving or rejecting. Possible values: `approved`, `rejected`.
auto_tagging	Decimal	Automatically assigns tags to an asset according to detected objects or categories with a confidence score higher than the specified value. Use together with the `detection` parameter for: Cloudinary AI Content Analysis Amazon Rekognition Celebrity Detection Use together with the `categorization` parameter for: Google Automatic Video Tagging Google Auto Tagging Imagga Auto Tagging Amazon Rekognition Auto Tagging Range: 0.0 to 1.0
detection	String	Invokes the relevant add-on to return a list of detected content. Set to: <content-aware model>_[<version>] (e.g. `coco_v1`) to return a list of detected content using the Cloudinary AI Content Analysis add-on. Can be used together with the `auto_tagging` parameter to apply tags automatically. `adv_face` to return a list of facial attributes using the Advanced Facial Attribute Detection add-on. `aws_rek_face` to return a list of detected celebrities and facial attributes using the Amazon Rekognition Celebrity Detection add-on. Can be used together with the `auto_tagging` parameter to apply tags automatically. Relevant for images only.
ocr	String	Set to `adv_ocr` to extract all text elements in an image as well as the bounding box coordinates of each detected element using the OCR text detection and extraction add-on. Relevant for images only.
raw_convert	String	Asynchronously generates a related file based on the uploaded file. Set to `aspose` to automatically create a PDF or other image format from a `raw` Office document using the Aspose Document Conversion add-on. Set to `google_speech` to instruct the Google AI Video Transcription add-on to generate an automatic transcript `raw` file from an uploaded video. Set to `extract_text` to extract all the text from a PDF file and store it in a `raw` file. The public ID of the generated raw file will be in the format: [pdf_public_id].extract_text.json. See also: Converting raw files.
categorization	String	A comma-separated list of the categorization add-ons to run on the asset. Set to `google_tagging`, `google_video_tagging`, `imagga_tagging` and/or `aws_rek_tagging` to automatically classify the scenes of the uploaded asset. Can be used together with the `auto_tagging` parameter to apply tags automatically. See the Google Automatic Video Tagging, Google Auto Tagging, Imagga Auto Tagging and Amazon Rekognition Auto Tagging add-ons for more details.
background_removal	String	Automatically remove the background of an image using an add-on. Set to `cloudinary_ai` to use the deep-learning based Cloudinary AI Background Removal add-on. Set to `pixelz` to use the human-powered Pizelz Remove-The-Background Editing add-on service. Relevant for images only.
access_control	access_types[]	An array of `access_types` for the asset. The asset is accessible as long as one of the access types is valid. Possible values for each access type: `token` - requires either Token-based authentication or Cookie-based authentication for accessing the resource. For example: `access_type: 'token'` `anonymous` - allows public access to the resource. The anonymous access type should also include `start` and `end` dates (in ISO 8601 format) defining when the resource is publicly available. For example: `access_type: 'anonymous', start: '2017-12-15T12:00Z', end: '2018-01-20T12:00Z'`

Examples

Update tags and moderation status of an uploaded image:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.update("image1",
  :tags => "important",
  :moderation_status => "approved")

PHP (cloudinary_php 2.x):

$result = $api
->update("image1", [
    "tags" => "important", 
    "moderation_status" => "approved"]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->update("image1", [
    "tags" => "important", 
    "moderation_status" => "approved"]);

Python (cloudinary 1.x):

result = cloudinary.api\
.update("image1",
  tags = "important",
  moderation_status = "approved")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.update("image1", 
  { tags: "important", 
    moderation_status: "approved"})
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = cloudinary.api()
.update("image1",
  ObjectUtils.asMap(
    "tags", "important",
    "moderation_status", "approved"));

.NET (CloudinaryDotNet 1.x):

var updateParams = new UpdateParams("image1"){
  Tags = "important",
  ModerationStatus = "approved"};
var updateResult = cloudinary.UpdateResource(updateParams);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.UpdateAsset(ctx, admin.UpdateAssetParams{
        PublicID:         "image1",
        Tags:              []string{"important"},
        ModerationStatus: "approved"})

curl:

curl \
 -d "tags=important&moderation_status=approved" \
 -X POST \
 https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload/image1

cli:

cld admin update image1 tags="important" moderation_status="approved"

Restore resources

Restores one or more resources (assets) from backup.

Syntax

POST /resources/:resource_type/:type/restore

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.restore(public_ids, options = {})

PHP (cloudinary_php 2.x):

$api->restore($public_ids, $options = []);

PHP (cloudinary_php 1.x (legacy)):

$api->restore($public_ids, $options = []);

Python (cloudinary 1.x):

cloudinary.api.restore(**public_ids, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.restore(public_ids, options).then(callback);

Java (cloudinary 1.x):

api.restore(Map public_ids, Map options);

.NET (CloudinaryDotNet 1.x):

cloudinary.Restore(RestoreParams params);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.RestoreAssets(ctx, admin.RestoreAssetsParams{})

cli:

cld admin restore (public_ids)

Required parameters

Parameter	Type	Description
public_ids	String[]	The public IDs of (deleted or existing) backed up assets to restore (array of up to 100 public_ids). By default, the latest backed up version of the asset is restored. If the `versions` parameter is specified, the corresponding version of each public ID is restored.

Optional parameters

Parameter	Type	Description
resource_type	String	The asset type of the requested assets. Relevant as a parameter only when using the SDKs (the `resource_type` is included in the endpoint URL when using the REST API). Note: use `video` for all video and audio assets, such as .mp3. Possible values: `image` (default), `raw`, `video`.
type	String	The delivery type of the requested assets, relevant as a parameter only when using the SDKs (the `type` is included in the endpoint URL when using the REST API). Possible values: `upload`, `private`, `authenticated`, Default: `upload`.
versions	String[]	The version of each of the assets to restore. Specify the `version_id` for each public ID. Use the resource method to list details of backed up versions of an asset.

Examples

Restore deleted resources by public_ids 'image1' and 'image2':

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.restore(["image1", "image2"])

PHP (cloudinary_php 2.x):

$result = $api
->restore(["image1", "image2"]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->restore(["image1", "image2"]);

Python (cloudinary 1.x):

result = cloudinary.api\
.restore(["image1", "image2"])

Node.js (cloudinary 1.x):

cloudinary.v2.api
.restore(["image1", "image2"])
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = cloudinary.api()
.restore(Arrays.asList("image1", "image2"),
  ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

var publicIds = new List<string>(){"image1", "image2"};
cloudinary.Restore(publicIds);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.RestoreAssets(ctx, admin.RestoreAssetsParams{
          PublicIDs: []string{"api_test_restore_20891", "api_test_restore_94060"}})

curl:

curl \
 -d "public_ids[]=image1&public_ids[]=image2" \
 -X POST \
 https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload/restore

cli:

cld admin restore '["image1","image2"]'

Restore specific versions of deleted resources by public_ids 'image1' and 'image2':

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.restore(["image1", "image2"], versions => ["c3fe4be5921eb89acd9af738c892f654", "d214063097a43d1d1293db61a397f60f"])

PHP (cloudinary_php 2.x):

$result = $api
->restore(["image1", "image2"], "versions" => ["c3fe4be5921eb89acd9af738c892f654", "d214063097a43d1d1293db61a397f60f"]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->restore(["image1", "image2"], "versions" => ["c3fe4be5921eb89acd9af738c892f654", "d214063097a43d1d1293db61a397f60f"]);

Python (cloudinary 1.x):

result = cloudinary.api\
.restore(["image1", "image2"], versions = ["c3fe4be5921eb89acd9af738c892f654", "d214063097a43d1d1293db61a397f60f"])

Node.js (cloudinary 1.x):

cloudinary.v2.api
.restore(["image1", "image2"], versions: ["c3fe4be5921eb89acd9af738c892f654", "d214063097a43d1d1293db61a397f60f"])
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = cloudinary.api()
.restore(Arrays.asList("image1", "image2"), ObjectUtils.asMap("versions", Arrays.asList("c3fe4be5921eb89acd9af738c892f654", "d214063097a43d1d1293db61a397f60f")),
  ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

var publicIds = new List<string>(){"image1", "image2"};
var versionIds = new List<string>(){"c3fe4be5921eb89acd9af738c892f654", "d214063097a43d1d1293db61a397f60f" };
var restoreParams = new RestoreParams(){
  PublicIds = publicIds,
  Versions = versionIds};
cloudinary.Restore(restoreParams);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.RestoreAssets(ctx, admin.RestoreAssetsParams{
        PublicIDs: []string{"image1", "image2"},
        Versions:  []string{"c3fe4be5921eb89acd9af738c892f654", "d214063097a43d1d1293db61a397f60f"}})

curl:

curl \
 -d "public_ids[]=image1&public_ids[]=image2&versions[]=c3fe4be5921eb89acd9af738c892f654&versions[]=d214063097a43d1d1293db61a397f60f" \
 -X POST \
 https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload/restore

cli:

cld admin restore '["image1","image2"]' versions="c3fe4be5921eb89acd9af738c892f654","d214063097a43d1d1293db61a397f60f"

Sample response

The details of the restored resources (note that when specific versions are restored, they are given new version IDs):

{
  "image1": 
  {
    "asset_id": "9ec64ab330767f4c1e939e2b4fcbaeac",
    "public_id": "image1", 
    "version": 1574260348, 
    "version_id": "8a7d06c83656a2a2d1d559f2ea5661f7",
    "signature": "b7f24977706edff33686e053e5a57a1684ff260b", 
    "width": 5472, 
    "height": 3648, 
    "format": "jpg", 
    "resource_type": "image", 
    "created_at": "2019-11-20T14:32:28Z", 
    "tags": [], 
    "bytes": 3477251, 
    "type": "upload", 
    "placeholder": false,
    "access_mode": "public"
  }
  "image2": 
  {
    "asset_id": "835d1cf89bd7c1b84dc4f53d35bc235f",
    "public_id": "image2", 
    "version": 1574261348, 
    "version_id": "80541d2d17a4485b84a7d264b3e778d0",
    "signature": "1aa2b977b02adffa268ae05a22aa57a1682fa202", 
    "width": 5234, 
    "height": 3234, 
    "format": "jpg", 
    "resource_type": "image", 
    "created_at": "2019-10-20T12:34:18Z", 
    "tags": [], 
    "bytes": 2427151, 
    "type": "upload", 
    "placeholder": false,
    "access_mode": "public"
  }
}

Update access mode

Update the access_mode of resources (assets) by public_id(s), by tag, or by prefix. When access_mode = 'authenticated', uploaded resources of type 'upload' behave as if they are of type 'authenticated'. The resource can later be made public by changing its access_mode to 'public', without having to update any image delivery URLs. In the case where public images are reverted to authenticated by changing their access_mode to 'authenticated', all the existing original and derived versions of the images are also invalidated on the CDN.

Note

You can only update the access_mode of an asset that was already assigned an access_mode when uploaded. For more details, see the upload method and Access mode.

Syntax

POST /resources/:resource_type/upload/update_access_mode

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.update_resources_access_mode(access_mode, options = {})

PHP (cloudinary_php 2.x):

Not supported by this SDK

PHP (cloudinary_php 1.x (legacy)):

$api->update_resources_access_mode($access_mode, $options = []);

Python (cloudinary 1.x):

cloudinary.api.update_resources_access_mode(access_mode, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.update_resources_access_mode(access_mode, options).then(callback);

Java (cloudinary 1.x):

api.updateResourcesAccessMode(String access_mode, Map options);

.NET (CloudinaryDotNet 1.x):

cloudinary.UpdateResourceAccessMode(RestoreParams params);

Go (cloudinary-go 1.x):

Not supported by this SDK

cli:

Not supported by the CLI

Required parameters

Parameter	Type	Description
access_mode	String	The new access mode to be set. Possible values: `public`, `authenticated`.
One of the following:
- public_ids	String[]	Update all assets with the given public IDs (array of up to 100 public_ids).
- prefix	String	Update all assets where the public ID starts with the given prefix (up to a maximum of 100 matching original assets).
- tag	String	Update all assets with the given tag (up to a maximum of 100 matching original assets).

Optional parameters

Parameter	Type	Description
resource_type	String	The type of asset. Relevant as a parameter only when using the SDKs (the `resource_type` is included in the endpoint URL when using the REST API). Note: use `video` for all video and audio assets, such as .mp3. Possible values: `image` (default), `raw`, `video`.

Examples

Update the access mode of uploaded images by public IDs:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.update_resources_access_mode_by_ids('public', 
  ['image1', 'image2'])

PHP (cloudinary_php 2.x):

Not supported by this SDK

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->update_resources_access_mode_by_ids("public", 
  ["image1", "image2"]);

Python (cloudinary 1.x):

result = cloudinary.api\
.update_resources_access_mode_by_ids("public", 
  ["image1", "image2"])

Node.js (cloudinary 1.x):

cloudinary.v2.api
.update_resources_access_mode_by_ids("public", 
  ['image1', 'image2'])
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.updateResourcesAccessModeByIds("public", 
  Arrays.asList("image1", "image2"), null);

.NET (CloudinaryDotNet 1.x):

var updateResourceAccessModeParams = new UpdateResourceAccessModeParams(){
  AccessMode = "public",
  PublicIds = new List<string>(){"image1", "image2"}};
cloudinary.UpdateResourceAccessModeByIds(updateResourceAccessModeParams);

Go (cloudinary-go 1.x):

Not supported by this SDK

curl:

curl \
  -d "access_mode=public&public_ids[]=image1&public_ids[]=image2" \
  -X POST \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload/update_access_mode

cli:

Not supported by the CLI

Update the access mode of uploaded videos by prefix:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.update_resources_access_mode_by_prefix('public', "to-publish", 
  :resource_type => :video)

PHP (cloudinary_php 2.x):

Not supported by this SDK

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->update_resources_access_mode_by_prefix("public", "to-publish", 
  ["resource_type" => "video"]);

Python (cloudinary 1.x):

result = cloudinary.api\
.update_resources_access_mode_by_prefix("public", "to-publish", 
  resource_type = "video")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.update_resources_access_mode_by_prefix("public", "to-publish",
  { resource_type: 'video'})
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.updateResourcesAccessModeByPrefix("public", "to-publish", 
  ObjectUtils.asMap("resource_type", "video"));

.NET (CloudinaryDotNet 1.x):

var updateResourceAccessModeParams = new UpdateResourceAccessModeParams(){
  AccessMode = "public",
  ResourceType = "video"};
cloudinary.UpdateResourceAccessModeByPrefix("to-publish", updateResourceAccessModeParams);

Go (cloudinary-go 1.x):

Not supported by this SDK

curl:

curl \
  -d "access_mode=public&prefix=to-publish" \
  -X POST \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/video/upload/update_access_mode

cli:

Not supported by the CLI

Update the access mode of uploaded images by tag:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.update_resources_access_mode_by_tag('public', '20170216')

PHP (cloudinary_php 2.x):

Not supported by this SDK

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->update_resources_access_mode_by_tag("public", "20170216");

Python (cloudinary 1.x):

result = cloudinary.api\
.update_resources_access_mode_by_tag("public", "20170216")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.update_resources_access_mode_by_tag('public', "20170216")
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api.updateResourcesAccessModeByTag("public", "20170216", null);

.NET (CloudinaryDotNet 1.x):

var updateResourceAccessModeParams = new UpdateResourceAccessModeParams(){
  AccessMode = "public"};
cloudinary.UpdateResourceAccessModeByTag("20170216", updateResourceAccessModeParams);

Go (cloudinary-go 1.x):

Not supported by this SDK

curl:

curl \
  -d "access_mode=public&tag=20170216" \
  -X POST \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload/update_access_mode

cli:

Not supported by the CLI

Sample response

{
    "updated": {
      "image1": "updated",
      "image2": "updated"
    },
    "failed": {
    },
}

Add related assets

Relates an asset to other assets by public IDs. This allows you to indicate that the asset is logically related to other assets in some way (e.g., similar content, or a peripheral asset like video/transcript, etc). This is a biderectional process, meaning that the asset will also be added as a related_asset to all the other assets given. The relation is also a one to many relationship, where the asset is related to all the assets given but those assets are not also related to each other.

Tip

Calling the Get the details of a single resource method with the related parameter set to true, will include the list of related assets in the response.

Syntax

POST /resources/related_assets/:resource_type/:type/:public_id

URL parameters

Parameter	Type	Description
resource_type	String	The type of asset is included in the endpoint URL. Note: use `video` for all video and audio assets, such as .mp3. Possible values: `image`, `raw`, `video`.
type	String	The delivery type is included in the endpoint URL. Possible values: `upload`, `private`, `authenticated`.
public_id	String	The public ID of the asset to update.

Required parameters

Parameter	Type	Description
assets_to_relate	Array	Relates the asset to all the assets given in this array of up to 10 public_ids given as `resource_type/type/public_id`. For example: `["image/upload/dog","video/authenticated/cat"]`

Examples

Relate the asset with a public ID of 'image/upload/dog' to the assets with public IDs of 'image/upload/animals' and 'video/authenticated/animals':

curl \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/related_assets/image/upload/dog -X POST --data '{"assets_to_relate":["image/upload/animals","video/authenticated/animals"]}'

Sample response

{
  "failed": [],
  "success": [
    {
      "message": "success",
      "code": "success_ids",
      "asset": "image/upload/animals",
      "status": 200
    },
    {
      "message": "success",
      "code": "success_ids",
      "asset": "video/authenticated/animals",
      "status": 200
    }
  ]
}

Delete related assets

Unrelates the asset from other assets given by public IDs. This is a biderectional process, meaning that the asset will also be removed as a related_asset from all the other assets given. See Add related assets for more information.

Syntax

DELETE /resources/related_assets/:resource_type/:type/:public_id

URL parameters

Parameter	Type	Description
resource_type	String	The type of asset is included in the endpoint URL. Note: use `video` for all video and audio assets, such as .mp3. Possible values: `image`, `raw`, `video`.
type	String	The delivery type is included in the endpoint URL. Possible values: `upload`, `private`, `authenticated`.
public_id	String	The public ID of the asset to update.

Required parameters

Parameter	Type	Description
assets_to_unrelate	Array	Unrelates the asset from all the assets given in this array of public_ids given as `resource_type/type/public_id`. For example: `["image/upload/dog","video/authenticated/cat"]`

Examples

Unrelate the asset with a public ID of 'image/upload/dog' from the assets with public IDs of 'image/upload/animals' and 'video/authenticated/animals':

curl \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/related_assets/image/upload/dog -X DELETE --data '{"assets_to_unrelate":["image/upload/animals","video/authenticated/animals"]}'

Sample response

{ 
  "failed": [] , 
  "deleted": [{
    "asset_id": "6e3696e5a73696e5a7445a74", 
    "message": "success"
  },
  {
    "asset_id": "33696e5a74693696e5a746e7", 
    "message": "success"
  }]
}

Delete resources

Deletes resources (assets) uploaded to your product environment

Syntax

DELETE /resources/:resource_type/:type

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.delete_resources(public_ids, options = {})

PHP (cloudinary_php 2.x):

$api->deleteAssets($public_ids, $options = []);

PHP (cloudinary_php 1.x (legacy)):

$api->delete_resources($public_ids, $options = []);

Python (cloudinary 1.x):

cloudinary.api.delete_resources(**public_ids, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.delete_resources(public_ids, options).then(callback);

Java (cloudinary 1.x):

api.deleteResources(Map public_ids, Map options);

.NET (CloudinaryDotNet 1.x):

cloudinary.DeleteResources(DelResParams params);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.DeleteAssets(ctx, admin.DeleteAssetsParams{})

cli:

cld admin delete_resources (public_ids)

Required parameters

One of the following:

Parameter	Type	Description
public_ids	String[]	Delete all assets with the given public IDs (array of up to 100 public_ids).
prefix	String	Delete all assets, including derived assets, where the public ID starts with the given prefix (up to a maximum of 1000 original resources).
all	Boolean	Delete all assets (of the relevant resource_type and type), including derived assets (up to a maximum of 1000 original resources).

Optional parameters

Parameter	Type	Description
resource_type	String	The type of asset. Relevant as a parameter only when using the SDKs (the `resource_type` is included in the endpoint URL when using the REST API). Note: use `video` for all video and audio assets, such as .mp3. Possible values: `image` (default), `raw`, `video`.
type	String	The delivery type, relevant as a parameter only when using the SDKs (the `type` is included in the endpoint URL when using the REST API). Possible values: `upload`, `private`, `fetch`,`authenticated`, `facebook`, `twitter`, `gravatar`, `youtube`, `hulu`, `vimeo`, `animoto`, `worldstarhiphop`, `dailymotion`. Default: `upload`.
keep_original	Boolean	Whether to delete only the derived resources. Default: `false`.
invalidate	Boolean	Whether to also invalidate the copies of the resource on the CDN. It usually takes between a few seconds and a few minutes for the invalidation to fully propagate through the CDN. There are also a number of other important considerations to keep in mind when invalidating files. Note that by default this parameter is not enabled: if you need this parameter enabled, please open a support request. Default: `false`.
next_cursor	String	When a deletion request has more than 1000 resources to delete, the response includes the `partial` boolean parameter set to true, as well as a `next_cursor` value. You can then specify this returned `next_cursor` value as a parameter of the following deletion request.
transformations	String	Only the derived resources matching this hash of transformation parameters will be deleted.

Examples

Delete uploaded images by public IDs:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.delete_resources(['image1', 'image2'])

PHP (cloudinary_php 2.x):

$result = $api
->deleteAssets(["image1", "image2"]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->delete_resources(["image1", "image2"]);

Python (cloudinary 1.x):

result = cloudinary.api\
.delete_resources(["image1", "image2"])

Node.js (cloudinary 1.x):

cloudinary.v2.api
.delete_resources(['image1', 'image2'])
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.deleteResources(Arrays.asList("image1", "image2"),
  ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

var delResParams = new DelResParams(){
  PublicIds = new List<string>{"image1", "image2"}};
cloudinary.DeleteResources(delResParams);

Go (cloudinary-go 1.x):

resp, err := adminAPI.DeleteAssets(ctx, admin.DeleteAssetsParams{
      PublicIDs: []string{"api_test_restore_20891", "api_test_restore_94060"}})

curl:

curl \
  -d "public_ids[]=image1&public_ids[]=image2" \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload

cli:

cld admin delete_resources '["image1","image2"]'

Delete Facebook pictures by public IDs:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.delete_resources(['4'], 
  :type => :facebook)

PHP (cloudinary_php 2.x):

$result = $api
->deleteAssets(["4"], 
   ["type" => "facebook"]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->delete_resources(["4"], 
  ["type" => "facebook"]);

Python (cloudinary 1.x):

result = cloudinary.api\
.delete_resources(["4"], 
  type = "facebook")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.delete_resources(['4'], 
  { type: 'facebook' })
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.deleteResources(Arrays.asList("4"),
  ObjectUtils.asMap("type", "facebook"));

.NET (CloudinaryDotNet 1.x):

var delResParams = new DelResParams(){
  PublicIds = new List<string>{"4"},
  Type = "facebook"};
cloudinary.DeleteResources(delResParams);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.DeleteAssets(ctx, admin.DeleteAssetsParams{
        PublicIDs:    []string{"4"},
        DeliveryType: "facebook"})

curl:

curl \
  -d "public_ids=4" \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/facebook

cli:

cld admin delete_resources "4" type="facebook"

Delete uploaded images by prefix:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.delete_resources_by_prefix('sunday')

PHP (cloudinary_php 2.x):

$result = $api
->deleteAssetsByPrefix("sunday");

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->delete_resources_by_prefix("sunday");

Python (cloudinary 1.x):

result = cloudinary.api\
.delete_resources_by_prefix("sunday")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.delete_resources_by_prefix('sunday')
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.deleteResourcesByPrefix("sunday", 
  ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

result = cloudinary.DeleteResourcesByPrefix("sunday");

Go (cloudinary-go 1.x):

resp, err := cld.Admin.DeleteAssetsByPrefix(ctx, admin.DeleteAssetsByPrefixParams{
        Prefix: []string{"sunday"}})

curl:

curl \
  -d "prefix=sunday" \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload

cli:

cld admin delete_resources_by_prefix "sunday"

Delete derived images only:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.delete_resources(['image1', 'image2'],
  :keep_original => true)

PHP (cloudinary_php 2.x):

$result = $api
->deleteAssets(["image1", "image2"],
  ["keep_original" => TRUE]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->delete_resources(["image1", "image2"],
  ["keep_original" => TRUE]);

Python (cloudinary 1.x):

result = cloudinary.api\
.delete_resources(["image1", "image2"],
  keep_original = True)

Node.js (cloudinary 1.x):

cloudinary.v2.api
.delete_resources(['image1', 'image2'], 
  { keep_original: true})
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.deleteResources(Arrays.asList("image1", "image2"),
<OBJECT></OBJECT>ObjectUtils.asMap("keep_original", true));

.NET (CloudinaryDotNet 1.x):

var delResParams = new DelResParams(){
PublicIds = new List<string>{"image1", "image2"},
  KeepOriginal = true};
cloudinary.DeleteResources(delResParams);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.DeleteAssetsByPrefix(ctx, admin.DeleteAssetsByPrefixParams{
      Prefix:           []string{"image1", "image2"},
      KeepOriginal:     api.Bool(true)})

curl:

curl \
  -d "public_ids[]=image1&public_ids[]=image2&keep_original=1" \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload

cli:

cld admin delete_resources '["image1","image2"]' keep_original=true

Delete all Facebook pictures:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.delete_all_resources(
  :type => :facebook)

PHP (cloudinary_php 2.x):

$result = $api
->deleteAllAssets(
  ["type" => "facebook"]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->delete_all_resources(
  ["type" => "facebook"]);

Python (cloudinary 1.x):

result = cloudinary.api\
.delete_all_resources(
  type = "facebook")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.delete_all_resources(
  {type: 'facebook'})
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.deleteAllResources(
  ObjectUtils.asMap("type", "facebook"));

.NET (CloudinaryDotNet 1.x):

var delResParams = new DelResParams(){
  Type = "facebook",
  All = true};
cloudinary.DeleteResources(delResParams);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.DeleteAllAssets(ctx, admin.DeleteAllAssetsParams{
      DeliveryType: "facebook",
      All:          api.Bool(true)})

curl:

curl \
  -d "all=true" \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/facebook

cli:

cld admin delete_all_resources type="facebook"

Sample response

{
    "deleted": {
        "image1": "deleted",
        "image2": "deleted"
    },
    "partial": false
}

Delete resources by tags

Deletes resources (assets) with a specified tag.

Syntax

DELETE /resources/:resource_type/tags/:tag

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.delete_resources_by_tag(tag, options = {})

PHP (cloudinary_php 2.x):

$api->deleteAssetsByTag($tag, $options = []);

PHP (cloudinary_php 1.x (legacy)):

$api->delete_resources_by_tag($tag, $options = []);

Python (cloudinary 1.x):

cloudinary.api.delete_resources_by_tag(tag, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.delete_resources_by_tag(tag, options).then(callback);

Java (cloudinary 1.x):

api.deleteResourcesByTag(String tag, Map options);

.NET (CloudinaryDotNet 1.x):

cloudinary.DeleteResourcesByTag(TagParams params);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.DeleteAssetsByTag(ctx, admin.DeleteAssetsByTagParams{})

cli:

cld admin delete_resources_by_tag (tag)

Required parameters

Parameter	Type	Description
tag	String	Delete all assets (and their derivatives) with the given tag name (up to a maximum of 1000 original assets).

Optional parameters

Parameter	Type	Description
resource_type	String	The type of asset. Relevant as a parameter only when using the SDKs (the `resource_type` is included in the endpoint URL when using the REST API). Note: use `video` for all video and audio assets, such as .mp3. Possible values: `image` (default), `raw`, `video`.
keep_original	Boolean	Whether to delete only the derived resources. Default: `false`.
invalidate	Boolean	Whether to also invalidate the copies of the resource on the CDN. It usually takes between a few seconds and a few minutes for the invalidation to fully propagate through the CDN. There are also a number of other important considerations to keep in mind when invalidating files. Note that by default this parameter is not enabled: if you need this parameter enabled, please open a support request. Default: `false`.
next_cursor	String	When a deletion request has more than 1000 resources to delete, the response includes the `partial` boolean parameter set to true, as well as a `next_cursor` value. You can then specify this returned `next_cursor` value as a parameter of the following deletion request.
transformations	String	Only the derived resources matching this hash of transformation parameters will be deleted.

Examples

Delete images by tag name:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.delete_resources_by_tag('mytag')

PHP (cloudinary_php 2.x):

$result = $api
->deleteAssetsByTag("mytag");

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->delete_resources_by_tag("mytag");

Python (cloudinary 1.x):

result = cloudinary.api\
.delete_resources_by_tag("mytag")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.delete_resources_by_tag('mytag')
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.deleteResourcesByTag("mytag", ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

result = cloudinary
.DeleteResourcesByTag("mytag");

Go (cloudinary-go 1.x):

resp, err := cld.Admin.DeleteAssetsByTag(ctx, admin.DeleteAssetsByTagParams{
      Tag:  "mytag"})

curl:

curl \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/tags/mytag

cli:

cld admin delete_resources_by_tag mytag

Sample response

{
    "deleted": {
        "image1": "deleted",
        "image2": "deleted"
    },
    "partial": false
}

Delete derived resources

Deletes derived resources (assets) from your product environment.

Syntax

DELETE /derived_resources

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.delete_derived_resources(derived_resource_ids, options = {})

PHP (cloudinary_php 2.x):

$api->deleteDerivedAssets($derived_resource_ids, $options = []);

PHP (cloudinary_php 1.x (legacy)):

$api->delete_derived_resources($derived_resource_ids, $options = []);

Python (cloudinary 1.x):

cloudinary.api.delete_derived_resources(**derived_resource_ids, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.delete_derived_resources(derived_resource_ids, options).then(callback);

Java (cloudinary 1.x):

api.deleteDerivedResources(Iterable<String> derivedResourceIds, Map options)

.NET (CloudinaryDotNet 1.x):

cloudinary.DeleteDerivedResources(List<string> DerivedResourceIds);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.DeleteDerivedAssets(ctx, admin.DeleteDerivedAssetsParams{DerivedAssetIDs})

cli:

cld admin delete_derived_resources (derived_resource_ids)

Required parameters

Parameter	Type	Description
derived_resource_ids	String[]	Delete all assets with the given derived_resource_ids IDs (array of up to 100 IDs). The derived resource IDs are returned when calling the Details of a single resource method.

Examples

Delete assets by derived resource IDs (8267a869b62a93a59248f35d7f124c1f and 383e22a57167445552a3cdc16f0a0c85):

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.delete_derived_resources(['8267a869b62a93a59248f35d7f124c1f', '383e22a57167445552a3cdc16f0a0c85'])

PHP (cloudinary_php 2.x):

$result = $api
->deleteDerivedAssets(["8267a869b62a93a59248f35d7f124c1f", "383e22a57167445552a3cdc16f0a0c85"]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->delete_derived_resources(["8267a869b62a93a59248f35d7f124c1f", "383e22a57167445552a3cdc16f0a0c85"]);

Python (cloudinary 1.x):

result = cloudinary.api\
.delete_derived_resources(["8267a869b62a93a59248f35d7f124c1f", "383e22a57167445552a3cdc16f0a0c85"])

Node.js (cloudinary 1.x):

cloudinary.v2.api
.delete_derived_resources(['8267a869b62a93a59248f35d7f124c1f', '383e22a57167445552a3cdc16f0a0c85'])
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.deleteDerivedResources(Arrays.asList("8267a869b62a93a59248f35d7f124c1f", "383e22a57167445552a3cdc16f0a0c85"),
  ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

result = cloudinary
.DeleteDerivedResources(new List<string>{"8267a869b62a93a59248f35d7f124c1f", "383e22a57167445552a3cdc16f0a0c85");

Go (cloudinary-go 1.x):

resp, err := cld.Admin.DeleteDerivedAssets(ctx, admin.DeleteDerivedAssetsParams{
      DerivedAssetIDs: []string{"8267a869b62a93a59248f35d7f124c1f", "383e22a57167445552a3cdc16f0a0c85"}})

curl:

curl \
  -d "derived_resource_ids[]=8267a869b62a93a59248f35d7f124c1f&derived_resource_ids[]=383e22a57167445552a3cdc16f0a0c85" \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/derived_resources

cli:

cld admin delete_derived_resources '["8267a869b62a93a59248f35d7f124c1f","383e22a57167445552a3cdc16f0a0c85"]'

streaming_profiles

Run in Postman Learn more about running Postman collections

Enables you to list, get details of, create, modify, or delete built-in and custom adaptive streaming profiles, which can be used to deliver your video using HLS and MPEG-DASH adaptive bitrate streaming.

Method	Description
GET`/streaming_profiles`	Lists the adaptive streaming profiles.
GET`/streaming_profiles/:name`	Lists the details of a single streaming profile specified by name.
POST`/streaming_profiles`	Creates a new streaming profile.
PUT`/streaming_profiles/:name`	Updates the specified existing streaming profile.
DELETE`/streaming_profiles/:name`	Deletes or reverts the specified streaming profile.

Get adaptive streaming profiles

List streaming profiles, including built-in and custom profiles.

Syntax

GET /streaming_profiles

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.list_streaming_profiles

PHP (cloudinary_php 2.x):

$api->listStreamingProfiles();

PHP (cloudinary_php 1.x (legacy)):

$api->list_streaming_profiles();

Python (cloudinary 1.x):

cloudinary.api.list_streaming_profiles()

Node.js (cloudinary 1.x):

cloudinary.v2.api.list_streaming_profiles().then(callback);

Java (cloudinary 1.x):

api.listStreamingProfiles();

.NET (CloudinaryDotNet 1.x):

cloudinary.ListStreamingProfiles()

Go (cloudinary-go 1.x):

resp, err := cld.Admin.ListStreamingProfiles(ctx, admin.ListStreamingProfilesParams{})

cli:

cld admin list_streaming_profiles

Sample response

The response contains an array of all the defined streaming profiles.

{
  "data": [
    {
      "name": "4k",
      "display_name": "4K (2160p)",
      "predefined": true
    },
    {
      "name": "full_hd",
      "display_name": "Full HD (1080p)",
      "predefined": true
    },
    {
      "name": "hd",
      "display_name": "HD (720p)",
      "predefined": true
    },
    {
      "name": "sd",
      "display_name": "SD (480p)",
      "predefined": true
    },
    {
      "name": "full_hd_wifi",
      "display_name": "Full HD WiFi (1080p)",
      "predefined": true
    },
    {
      "name": "full_hd_lean",
      "display_name": "Full HD Lean (1080p)",
      "predefined": true
    },
    {
      "name": "hd_lean",
      "display_name": "HD Lean (720p)",
      "predefined": true
    },
    {
      "name": "custom_square",
      "display_name": "Custom square resolution",
      "predefined": false
    }
  ]
}

Get details of a single streaming profile

Retrieve the details of a single streaming profile by name.

Syntax

GET /streaming_profiles/:name

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.get_streaming_profile(name)

PHP (cloudinary_php 2.x):

$api->getStreamingProfile($name);

PHP (cloudinary_php 1.x (legacy)):

$api->get_streaming_profile($name);

Python (cloudinary 1.x):

cloudinary.api.get_streaming_profile(name)

Node.js (cloudinary 1.x):

cloudinary.v2.api.get_streaming_profile(name).then(callback);

Java (cloudinary 1.x):

api.getStreamingProfile(String name);

.NET (CloudinaryDotNet 1.x):

cloudinary.GetStreamingProfile(name)

Go (cloudinary-go 1.x):

resp, err := cld.Admin.GetStreamingProfile(ctx, admin.GetStreamingProfileParams{})

cli:

cld admin get_streaming_profile (name)

Required parameters

Parameter	Type	Description
name	String	The name of the streaming profile to get the details of.

Examples

Get the details of a specified streaming file:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.get_streaming_profile('custom_square')

PHP (cloudinary_php 2.x):

$result = $api
->getStreamingProfile("custom_square");

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->get_streaming_profile("custom_square");

Python (cloudinary 1.x):

result = cloudinary.api\
.get_streaming_profile("custom_square")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.get_streaming_profile('custom_square')
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.getStreamingProfile("custom_square");

.NET (CloudinaryDotNet 1.x):

result = cloudinary
.GetStreamingProfile("custom_square")

Go (cloudinary-go 1.x):

resp, err := cld.Admin.GetStreamingProfile(ctx, admin.GetStreamingProfileParams{Name: "custom_square"})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/streaming_profiles/custom_square

cli:

cld admin get_streaming_profile "custom_square"

Sample response

The response contains details for a single streaming profile.

{
 "data": {
   "name": "custom_square",
   "display_name": "Custom square resolution",
   "predefined": false,
   "representations": [
     {
       "transformation": {
         "width": 1200, "height": 1200, "bit_rate": "5m", "video_codec": "h264:main:3.1"
       }
     },
     {
       "transformation": {
         "width": 900, "height": 900, "bit_rate": "3500k", "video_codec": "h264:main:3.1"
       }
     },
     {
       "transformation": {
         "width": 600, "height": 600, "bit_rate": "1500k", "video_codec": "h264:baseline:3.0"
       }
     }
   ]
 }
}

Create a streaming profile

Create a new, custom streaming profile.

Syntax

POST /streaming_profiles

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.create_streaming_profile(name, options = {})

PHP (cloudinary_php 2.x):

$api->createStreamingProfile($name, $options = []);

PHP (cloudinary_php 1.x (legacy)):

$api->create_streaming_profile($name, $options = []);

Python (cloudinary 1.x):

cloudinary.api.create_streaming_profile(name, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.create_streaming_profile(name, options).then(callback);

Java (cloudinary 1.x):

api.createStreamingProfile(String name, Map options);

.NET (CloudinaryDotNet 1.x):

cloudinary.CreateStreamingProfile(StreamingProfileCreateParams params);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.CreateStreamingProfile(ctx, admin.CreateStreamingProfileParams{})

cli:

cld admin create_streaming_profile (name)

Required parameters

Parameter	Type	Description
name	String	The identification name to assign to the new streaming profile. The name is case-insensitive and can contain alphanumeric characters, underscores (_) and hyphens (-).
representations	JSON string	An array of structures that defines a custom streaming profile.
transformation	String or Hash	Specifies the transformation parameters for the representation. All video transformation parameters except `video_sampling` are supported. Common transformation parameters for representations include: `width`, `height` (or `aspect_ratio`), `bit_rate`, `video_codec`, `audio_codec`, `sample_rate` (or `fps`), etc.

Optional parameters

Parameter	Type	Description
display_name	String	A descriptive name for the profile.

Examples

Create a streaming profile with 3 representations:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.create_streaming_profile("custom_square",
  :display_name => "Custom square resolution",
  :representations =>
    [{:transformation => {:crop => "limit", :width => "1200", :height => "1200", :bit_rate => "5m"}},
     {:transformation => {:crop => "limit", :width => "900", :height => "900", :bit_rate => "3500k"}}
     {:transformation => {:crop => "limit", :width => "600", :height => "600", :bit_rate => "1500k"}}])

PHP (cloudinary_php 2.x):

$result = $api
->createStreamingProfile("custom_square", [
    "display_name" => "Custom square resolution",
    "representations" => [
      ["crop" => "limit", "width" => 1200, "height" => 1200, "bit_rate" => "5m"],
      ["crop" => "limit", "width" => 900, "height" => 900, "bit_rate" => "3500k"],
      ["crop" => "limit", "width" => 600, "height" => 600, "bit_rate" => "1500k"]]]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->create_streaming_profile("custom_square", [
    "display_name" => "Custom square resolution",
    "representations" => [
      ["crop" => "limit", "width" => 1200, "height" => 1200, "bit_rate" => "5m"],
      ["crop" => "limit", "width" => 900, "height" => 900, "bit_rate" => "3500k"],
      ["crop" => "limit", "width" => 600, "height" => 600, "bit_rate" => "1500k"]]]);

Python (cloudinary 1.x):

result = cloudinary.api\
.create_streaming_profile("custom_square",
  display_name="Custom square resolution",
  representations=[
    {"transformation": {"crop": "limit", "width": 1200, "height": 1200, "bit_rate": "5m"}},
    {"transformation": {"crop": "limit", "width": 900, "height": 900, "bit_rate": "3500k"}},
    {"transformation": {"crop": "limit", "width": 600, "height": 600, "bit_rate": "1500k"}}])

Node.js (cloudinary 1.x):

cloudinary.v2.api
.create_streaming_profile('custom_square',
  { display_name: "Custom square resolution",
    representations: [
    { transformation:{crop: "limit", width: 1200, height: 1200, bit_rate: "5m" }},
    { transformation:{crop: "limit", width: 900, height: 900, bit_rate: "3500k" }},
    { transformation:{crop: "limit", width: 600, height: 600, bit_rate: "1500k" }}] })
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.createStreamingProfile("custom_square", "Custom square resolution",
  Arrays.asList(
    ObjectUtils.asMap("transformation", new 
      Transformation().crop("limit").width(1200).height(1200).bitRate("5m")),
    ObjectUtils.asMap("transformation", new 
      Transformation().crop("limit").width(900).height(900).bitRate("3500k")),
    ObjectUtils.asMap("transformation", new 
      Transformation().crop("limit").width(600).height(600).bitRate("1500k"))));

.NET (CloudinaryDotNet 1.x):

var streamingProfileParams = new StreamingProfileCreateParams()
  {
    Name = "custom_square",
    DisplayName = "Custom square resolution",
    Representations = new List<Representation>
      {
        new Representation {Transformation = new Transformation().Crop("limit").Width(1200).Height(1200).BitRate("5m")},
        new Representation {Transformation = new Transformation().Crop("limit").Width(900).Height(900).BitRate("3500k")},
        new Representation {Transformation = new Transformation().Crop("limit").Width(600).Height(600).BitRate("1500k")}
      }
  };
cloudinary.CreateStreamingProfile(streamingProfileParams);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.CreateStreamingProfile(ctx, admin.CreateStreamingProfileParams{
      Name:        "custom_square",
      DisplayName: "Custom square resolution",
      Representations: admin.StreamingProfileRepresentations{
          {Transformation: "c_limit,w_1200,h_1200,br_5m"},
          {Transformation: "c_limit,w_900,h_900,br_3500k"},
          {Transformation: "c_limit,w_600,h_600,br_1500k"},
        }})

curl:

curl \
  -d 'name=custom_square&display_name=Custom%20square%20resolution&representations=\[\{%22transformation%22:%22c_limit,w_1200,h_1200,br_5m%22\},\{%22transformation%22:%22c_limit,w_900,h_900,br_3500k%22\},\{%22transformation%22:%22c_limit,w_600,h_600,br_1500k%22\}\]'
  -X POST \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/streaming_profiles

cli:

cld admin create_streaming_profile "custom_square" display_name="Custom square resolution" representations='[{"transformation": {"crop": "limit","width": 1200, "height": 1200, "bit_rate": "5m"}},{"transformation": {"crop": "limit", "width": 900, "height": 900, "bit_rate": "3500k"}},{"transformation": {"crop": "limit", "width": 600, "height": 600, "bit_rate": "1500k"}}]'

Note

If running the CLI command on Windows, you need to escape the double quotes within the curly braces using either \ or ", for example, \"text\" or ""text"".

Sample response

The response contains details for the streaming profile that was created.

{
 "data": {
   "name": "custom_square",
   "display_name": "Custom square resolution",
   "predefined": false,
   "representations": [
     {
       "transformation": {
         "width": 1200, "height": 1200, "bit_rate": "5m", "video_codec": "h264:main:3.1"
       }
     },
     {
       "transformation": {
         "width": 900, "height": 900, "bit_rate": "3500k", "video_codec": "h264:main:3.1"
       }
     },
     {
       "transformation": {
         "width": 600, "height": 600, "bit_rate": "1500k", "video_codec": "h264:baseline:3.0"
       }
     }
   ]
 }
}

Create a streaming profile with 6 representations and a combination of codecs:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.create_streaming_profile("custom_square_combo",
  :display_name => "Custom square resolution with combination of codecs",
  :representations =>
    [{:transformation => {:crop => "limit", :width => "1200", :height => "1200", :video_codec => "h265", :bit_rate => "5m"}},
     {:transformation => {:crop => "limit", :width => "900", :height => "900", :video_codec => "h265", :bit_rate => "3500k"}},
     {:transformation => {:crop => "limit", :width => "600", :height => "600", :video_codec => "h265", :bit_rate => "1500k"}},
     {:transformation => {:crop => "limit", :width => "1200", :height => "1200", :video_codec => "vp9", :bit_rate => "5m"}},
     {:transformation => {:crop => "limit", :width => "900", :height => "900", :video_codec => "vp9", :bit_rate => "3500k"}}
     {:transformation => {:crop => "limit", :width => "600", :height => "600", :video_codec => "vp9", :bit_rate => "1500k"}}])

PHP (cloudinary_php 2.x):

$result = $api
->createStreamingProfile("custom_square_combo", [
    "display_name" => "Custom square resolution with combination of codecs",
    "representations" => [
      ["crop" => "limit", "width" => 1200, "height" => 1200, "video_codec" => "h265", "bit_rate" => "5m"],
      ["crop" => "limit", "width" => 900, "height" => 900, "video_codec" => "h265", "bit_rate" => "3500k"],
      ["crop" => "limit", "width" => 600, "height" => 600, "video_codec" => "h265", "bit_rate" => "1500k"],
      ["crop" => "limit", "width" => 1200, "height" => 1200, "video_codec" => "vp9", "bit_rate" => "5m"],
      ["crop" => "limit", "width" => 900, "height" => 900, "video_codec" => "vp9", "bit_rate" => "3500k"],
      ["crop" => "limit", "width" => 600, "height" => 600, "video_codec" => "vp9", "bit_rate" => "1500k"]]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->create_streaming_profile("custom_square_combo", [
    "display_name" => "Custom square resolution with combination of codecs",
    "representations" => [
      ["crop" => "limit", "width" => 1200, "height" => 1200, "video_codec" => "h265", "bit_rate" => "5m"],
      ["crop" => "limit", "width" => 900, "height" => 900, "video_codec" => "h265", "bit_rate" => "3500k"],
      ["crop" => "limit", "width" => 600, "height" => 600, "video_codec" => "h265", "bit_rate" => "1500k"],
      ["crop" => "limit", "width" => 1200, "height" => 1200, "video_codec" => "vp9", "bit_rate" => "5m"],
      ["crop" => "limit", "width" => 900, "height" => 900, "video_codec" => "vp9", "bit_rate" => "3500k"],
      ["crop" => "limit", "width" => 600, "height" => 600, "video_codec" => "vp9", "bit_rate" => "1500k"]]);

Python (cloudinary 1.x):

result = cloudinary.api\
.create_streaming_profile("custom_square_combo",
  display_name="Custom square resolution with combination of codecs",
  representations=[
    {"transformation": {"crop": "limit", "width": 1200, "height": 1200, "video_codec": "h265", "bit_rate": "5m"}},
    {"transformation": {"crop": "limit", "width": 900, "height": 900, "video_codec": "h265", "bit_rate": "3500k"}},
    {"transformation": {"crop": "limit", "width": 600, "height": 600, "video_codec": "h265", "bit_rate": "1500k"}},
    {"transformation": {"crop": "limit", "width": 1200, "height": 1200, "video_codec": "vp9", "bit_rate": "5m"}},
    {"transformation": {"crop": "limit", "width": 900, "height": 900, "video_codec": "vp9", "bit_rate": "3500k"}},
    {"transformation": {"crop": "limit", "width": 600, "height": 600, "video_codec": "vp9", "bit_rate": "1500k"}}])

Node.js (cloudinary 1.x):

cloudinary.v2.api
.create_streaming_profile('custom_square_combo',
  { display_name: "Custom square resolution with combination of codecs",
    representations: [
    { transformation:{crop: "limit", width: 1200, height: 1200, video_codec: "h265", bit_rate: "5m" }},
    { transformation:{crop: "limit", width: 900, height: 900, video_codec: "h265", bit_rate: "3500k" }},
    { transformation:{crop: "limit", width: 600, height: 600, video_codec: "h265", bit_rate: "1500k" }},
    { transformation:{crop: "limit", width: 1200, height: 1200, video_codec: "vp9", bit_rate: "5m" }},
    { transformation:{crop: "limit", width: 900, height: 900, video_codec: "vp9", bit_rate: "3500k" }},
    { transformation:{crop: "limit", width: 600, height: 600, video_codec: "vp9", bit_rate: "1500k" }}] })
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.createStreamingProfile("custom_square_combo", "Custom square resolution with combination of codecs",
  Arrays.asList(
    ObjectUtils.asMap("transformation", new 
      Transformation().crop("limit").width(1200).height(1200).videoCodec("h265").bitRate("5m")),
    ObjectUtils.asMap("transformation", new 
      Transformation().crop("limit").width(900).height(900).videoCodec("h265").bitRate("3500k")),
    ObjectUtils.asMap("transformation", new 
      Transformation().crop("limit").width(600).height(600).videoCodec("h265").bitRate("1500k")),
    ObjectUtils.asMap("transformation", new 
      Transformation().crop("limit").width(1200).height(1200).videoCodec("vp9").bitRate("5m")),
    ObjectUtils.asMap("transformation", new 
      Transformation().crop("limit").width(900).height(900).videoCodec("vp9").bitRate("3500k")),
    ObjectUtils.asMap("transformation", new 
      Transformation().crop("limit").width(600).height(600).videoCodec("vp9").bitRate("1500k"))));

.NET (CloudinaryDotNet 1.x):

var streamingProfileParams = new StreamingProfileCreateParams()
  {
    Name = "custom_square",
    DisplayName = "Custom square resolution",
    Representations = new List<Representation>
      {
        new Representation {Transformation = new Transformation().Crop("limit").Width(1200).Height(1200).BitRate("5m")},
        new Representation {Transformation = new Transformation().Crop("limit").Width(900).Height(900).BitRate("3500k")},
        new Representation {Transformation = new Transformation().Crop("limit").Width(600).Height(600).BitRate("1500k")}
        new Representation { Transformation = new Transformation().Crop("limit").Width(1200).Height(1200).VideoCodec("vp9").BitRate("5m")},
        new Representation { Transformation = new Transformation().Crop("limit").Width(900).Height(900).VideoCodec("vp9").BitRate("3500k")},
        new Representation { Transformation = new Transformation().Crop("limit").Width(600).Height(600).VideoCodec("vp9").BitRate("1500k")}
      }
  };
cloudinary.CreateStreamingProfile(streamingProfileParams);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.CreateStreamingProfile(ctx, admin.CreateStreamingProfileParams{
      Name:        "custom_square",
      DisplayName: "Custom square resolution",
      Representations: admin.StreamingProfileRepresentations{
          {Transformation: "c_limit,w_1200,h_1200,vc_h265,br_5m"},
          {Transformation: "c_limit,w_900,h_900,vc_h265,br_3500k"},
          {Transformation: "c_limit,w_600,h_600,vc_h265,br_1500k"},
          {Transformation: "c_limit,w_1200,h_1200,vc_vp9,br_5m"},
          {Transformation: "c_limit,w_900,h_900,vc_vp9,br_3500k"},
          {Transformation: "c_limit,w_600,h_600,vc_vp9,br_1500k"},
        }})

curl:

curl \
  -d 'name=custom_square_combo&display_name=Custom%20square%20resolution%20with%20combination%20of%20codecs&representations=\[\{%22transformation%22:%22c_limit,w_1200,h_1200,vc_h264,br_5m%22\},\{%22transformation%22:%22c_limit,w_900,h_900,vc_h264,br_3500k%22\},\{%22transformation%22:%22c_limit,w_600,h_600,vc_h264,br_1500k%22\},\{%22transformation%22:%22c_limit,w_1200,h_1200,vc_vp9,br_5m%22\},\{%22transformation%22:%22c_limit,w_900,h_900,vc_vp9,br_3500k%22\},\{%22transformation%22:%22c_limit,w_600,h_600,vc_vp9,br_1500k%22\}\]'
  -X POST \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/streaming_profiles

cli:

cld admin create_streaming_profile "custom_square_combo" display_name="Custom square resolution with combination of codecs" representations='[{"transformation": {"crop": "limit", "width": 1200, "height": 1200, "video_codec": "h265", "bit_rate": "5m"}},{"transformation": {"crop": "limit", "width": 900, "height": 900, "video_codec": "h265", "bit_rate": "3500k"}},{"transformation": {"crop": "limit", "width": 600, "height": 600, "video_codec": "h265", "bit_rate": "1500k"}},{"transformation": {"crop": "limit", "width": 1200, "height": 1200, "video_codec": "vp9", "bit_rate": "5m"}},{"transformation": {"crop": "limit", "width": 900, "height": 900, "video_codec": "vp9", "bit_rate": "3500k"}},{"transformation": {"crop": "limit", "width": 600, "height": 600, "video_codec": "vp9", "bit_rate": "1500k"}}]'

Note

If running the CLI command on Windows, you need to escape the double quotes within the curly braces using either \ or ", for example, \"text\" or ""text"".

Sample response

The response contains details for the streaming profile that was created.

{
  "data":{
    "name":"custom_square_combo",
    "display_name":"Custom square resolution with combination of codecs",
    "predefined":false,
    "representations":[
      {
        "transformation":[
          {
            "width":1200,
            "height":1200,
            "video_codec":"h265",
            "bit_rate":"5m",
            "crop":"limit"
          }
        ]
      },
      {
        "transformation":[
          {
            "width":900,
            "height":900,
            "video_codec":"h265",
            "bit_rate":"3500k",
            "crop":"limit"
          }
        ]
      },
      {
        "transformation":[
          {
            "width":600,
            "height":600,
            "video_codec":"h265",
            "bit_rate":"1500k",
            "crop":"limit"
          }
        ]
      },
      {
        "transformation":[
          {
            "width":1200,
            "height":1200,
            "video_codec":"vp9",
            "bit_rate":"5m",
            "crop":"limit"
          }
        ]
      },
      {
        "transformation":[
          {
            "width":900,
            "height":900,
            "video_codec":"vp9",
            "bit_rate":"3500k",
            "crop":"limit"
          }
        ]
      },
      {
        "transformation":[
          {
            "width":600,
            "height":600,
            "video_codec":"vp9",
            "bit_rate":"1500k",
            "crop":"limit"
          }
        ]
      }
    ]
  }
}

Update an existing streaming profile

Update the specified existing streaming profile. You can update both custom and built-in profiles. The specified list of representations replaces the previous list.

Syntax

PUT /streaming_profiles

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.update_streaming_profile(name, options = {})

PHP (cloudinary_php 2.x):

$api->updateStreamingProfile($name, $options = []);

PHP (cloudinary_php 1.x (legacy)):

$api->update_streaming_profile($name, $options = []);

Python (cloudinary 1.x):

cloudinary.api.update_streaming_profile(name, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.update_streaming_profile(name,up options).then(callback);

Java (cloudinary 1.x):

api.updateStreamingProfile(String name, Map options);

.NET (CloudinaryDotNet 1.x):

cloudinary.UpdateStreamingProfile(String name, StreamingProfileUpdateParams params);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.UpdateStreamingProfile(ctx, admin.UpdateStreamingProfileParams{})

cli:

cld admin update_streaming_profile (name)

Required parameters

Parameter	Type	Description
name	String	The identification name to assign to the new streaming profile. The name is case-insensitive and can contain alphanumeric characters, underscores (_) and hyphens (-).
representations	JSON string	An array of structures that defines a custom streaming profile.
transformation	String or Hash	Specifies the transformation parameters for the representation. All video transformation parameters except `video_sampling` are supported. Common transformation parameters for representations include: `width`, `height` (or `aspect_ratio`), `bit_rate`, `video_codec`, `audio_codec`, `sample_rate` (or `fps`), etc.

Optional parameters

Parameter	Type	Description
display_name	String	A descriptive name for the profile.

Examples

Add a fourth (fallback) representation to an existing custom streaming profile:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.update_streaming_profile("custom_square",  
:representations => 
  [{:transformation => {:crop => "limit", :width => "1200", :height => "1200", :bit_rate => "5m"}},
   {:transformation => {:crop => "limit", :width => "900", :height => "900", :bit_rate => "3500k"}},
   {:transformation => {:crop => "limit", :width => "600", :height => "600", :bit_rate => "1500k"}},
   {:transformation => {:crop => "limit", :width => "320", :height => "320", :bit_rate => "192k"}}])

PHP (cloudinary_php 2.x):

$result = $api
->updateStreamingProfile("custom_square", [
    "representations" => [
      ["transformation" => ["crop" => "limit", "width" => 1200, "height" => 1200, "bit_rate" => "5m"]],
      ["transformation" => ["crop" => "limit", "width" => 900, "height" => 900, "bit_rate" => "3500k"]],
      ["transformation" => ["crop" => "limit", "width" => 600, "height" => 600, "bit_rate" => "1500k"]],
      ["transformation" => ["crop" => "limit", "width" => 320, "height" => 320, "bit_rate" => "192k"]]]]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->update_streaming_profile("custom_square", [
    "representations" => [
      ["transformation" => ["crop" => "limit", "width" => 1200, "height" => 1200, "bit_rate" => "5m"]],
      ["transformation" => ["crop" => "limit", "width" => 900, "height" => 900, "bit_rate" => "3500k"]],
      ["transformation" => ["crop" => "limit", "width" => 600, "height" => 600, "bit_rate" => "1500k"]],
      ["transformation" => ["crop" => "limit", "width" => 320, "height" => 320, "bit_rate" => "192k"]]]]);

Python (cloudinary 1.x):

result = cloudinary.api\
.update_streaming_profile("custom_square",
  representations=[
    {"transformation": {"crop": "limit", "width": 1200, "height": 1200, "bit_rate": "5m"}},
    {"transformation": {"crop": "limit", "width": 900, "height": 900, "bit_rate": "3500k"}},
    {"transformation": {"crop": "limit", "width": 600, "height": 600, "bit_rate": "1500k"}},
    {"transformation": {"crop": "limit", "width": 320, "height": 320, "bit_rate": "192k"}}])

Node.js (cloudinary 1.x):

cloudinary.v2.api
.update_streaming_profile('custom_square',
  { representations: [
    { transformation: {crop: "limit", width: 1200, height: 1200, bit_rate: "5m" }},
    { transformation: {crop: "limit", width: 900, height: 900, bit_rate: "3500k" }},
    { transformation: {crop: "limit", width: 600, height: 600, bit_rate: "1500k" }},
    { transformation: {crop: "limit", width: 320, height: 320, bit_rate: "192k" }}]})
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.updateStreamingProfile("custom_square", null,
  Arrays.asList(
    new Transformation().crop("limit").width(1200).height(1200).bit_rate("5m"),
    new Transformation().crop("limit").width(900).height(900).bit_rate("3500k"),
    new Transformation().crop("limit").width(600).height(600).bit_rate("1500k"),
    new Transformation().crop("limit").width(320).height(320).bit_rate("192k")));

.NET (CloudinaryDotNet 1.x):

var streamingUpdateParams = new StreamingProfileUpdateParams()
  {
    Representations = new List<Representation>
      {
        new Representation {Transformation = new Transformation().Crop("limit").Width(1200).Height(1200).BitRate("5m")},
        new Representation {Transformation = new Transformation().Crop("limit").Width(900).Height(900).BitRate("3500k")},
        new Representation {Transformation = new Transformation().Crop("limit").Width(600).Height(600).BitRate("1500k")},
        new Representation {Transformation = new Transformation().Crop("limit").Width(320).Height(320).BitRate("192k")},
      }
  };
    cloudinary.UpdateStreamingProfile("custom_square", streamingUpdateParams);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.UpdateStreamingProfile(ctx, admin.UpdateStreamingProfileParams{
      Name: "custom_square",
      Representations: admin.StreamingProfileRepresentations{
          {Transformation: "c_limit,w_1200,h_1200,br_5m"},
          {Transformation: "c_limit,w_900,h_900,br_3500k"},
          {Transformation: "c_limit,w_600,h_600,br_1500k"},
          {Transformation: "c_limit,w_320,h_320,br_192k"},
        }})

curl:

curl \
  -d 'representations=\[\{%22transformation%22:%22c_limit,w_1200,h_1200,br_5m%22\},\{%22transformation%22:%22c_limit,w_900,h_900,br_3500k%22\},\{%22transformation%22:%22c_limit,w_600,h_600,br_1500k%22\},\{%22transformation%22:%22c_limit,w_320,h_320,br_192k%22\}\]' \
  -X PUT \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/streaming_profiles/custom_square

cli:

cld admin update_streaming_profile "custom_square" representations='[{"transformation": {"crop": "limit", "width": 1200, "height": 1200, "bit_rate": "5m"}},{"transformation": {"crop": "limit", "width": 900, "height": 900, "bit_rate": "3500k"}},{"transformation": {"crop": "limit", "width": 600, "height": 600, "bit_rate": "1500k"}},{"transformation": {"crop": "limit", "width": 320, "height": 320, "bit_rate": "192k"}}]'

Note

If running the CLI command on Windows, you need to escape the double quotes within the curly braces using either \ or ", for example, \"text\" or ""text"".

Sample response

The response contains details for the streaming profile that was updated.

{
  "message": "updated",
  "data": {
    "name": "custom_square",
    "display_name": "Custom square resolution",
    "predefined": false,
    "representations": [
      {
        "transformation": {
          "width": 1200, "height": 1200, "bit_rate": "5m", "video_codec": "h264:main:3.1"
        }
      },
      {
        "transformation": {
          "width": 900, "height": 900, "bit_rate": "3500k", "video_codec": "h264:main:3.1"
        }
      },
      {
        "transformation": {
          "width": 600, "height": 600, "bit_rate": "1500k", "video_codec": "h264:baseline:3.0"
        }
      }
      {
        "transformation": {
          "width": 320, "height": 320, "bit_rate": "192k", "video_codec": "h264:baseline:3.0"
        }
      }                
    ]
  }
}

Delete or revert the specified streaming profile

For custom streaming profiles, delete the specified profile.

For built-in streaming profiles, if the built-in profile was modified, revert the profile to the original settings.

For built-in streaming profiles that have not been modified, the Delete method returns an error.

Syntax

DELETE /streaming_profiles/:name

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.delete_streaming_profile(name)

PHP (cloudinary_php 2.x):

$api->deleteStreamingProfile($name);

PHP (cloudinary_php 1.x (legacy)):

$api->delete_streaming_profile($name);

Python (cloudinary 1.x):

cloudinary.api.delete_streaming_profile(name)

Node.js (cloudinary 1.x):

cloudinary.v2.api.delete_streaming_profile(name).then(callback);

Java (cloudinary 1.x):

api.deleteStreamingProfile(String name);

.NET (CloudinaryDotNet 1.x):

cloudinary.DeleteStreamingProfile(name);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.DeleteStreamingProfile(ctx, admin.DeleteStreamingProfileParams{})

cli:

cld admin delete_streaming_profile (name)

Required parameters

Parameter	Type	Description
name	String	The name of the streaming profile to delete or revert.

Examples

Delete the custom_square streaming file:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.delete_streaming_profile('custom_square')

PHP (cloudinary_php 2.x):

$result = $api
->deleteStreamingProfile("custom_square");

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->delete_streaming_profile("custom_square");

Python (cloudinary 1.x):

result = cloudinary.api\
.delete_streaming_profile("custom_square")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.delete_streaming_profile('custom_square')
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.deleteStreamingProfile("custom_square");

.NET (CloudinaryDotNet 1.x):

result = cloudinary
.DeleteStreamingProfile("custom_square");

Go (cloudinary-go 1.x):

resp, err := cld.Admin.DeleteStreamingProfile(ctx, admin.DeleteStreamingProfileParams{Name: "custom_square"})

curl:

curl \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/streaming_profiles/custom_square

cli:

cld admin delete_streaming_profile "custom_square"

Sample response

{ "message": "deleted" }

Method	Description
GET `/tags`	Lists tags used for a specified resource type.

transformations

Run in Postman Learn more about running Postman collections

Enables you to manage stored transformations. See the Image transformations and video transformations documentation for more information.

Method	Description
GET `/transformations`	Lists all transformations.
GET `/transformations/:transformation`	Lists details of a single transformation specified by name or parameters.
POST`/transformations/:name`	Creates a new named transformation.
PUT`/transformations/:transformation`	Updates a specified transformation.
DELETE`/transformations/:transformation`	Deletes a specified transformation.

Get transformations

List all transformations.

Syntax

GET /transformations

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.transformations(options = {})

PHP (cloudinary_php 2.x):

$api->transformations($options = []);

PHP (cloudinary_php 1.x (legacy)):

$api->transformations($options = []);

Python (cloudinary 1.x):

cloudinary.api.transformations(**options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.transformations(options).then(callback);

Java (cloudinary 1.x):

api.transformations(Map options);

.NET (CloudinaryDotNet 1.x):

cloudinary.ListTransformations(TransformParams params);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.ListTransformations(ctx, admin.ListTransformationsParams{})

cli:

cld admin transformations

Optional parameters

Parameter	Type	Description
max_results	Integer	Maximum number of transformations to return (up to 500). Default: `10`.
next_cursor	String	When a request has more results to return than `max_results`, the `next_cursor` value is returned as part of the response. You can then specify this value as the `next_cursor` parameter of a following request.
named	Boolean	Whether to return only named (`true`) or unnamed (`false`) transformations. If this parameter is not included, both named and unnamed transformations will be returned.

Examples

List all transformations:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.transformations

PHP (cloudinary_php 2.x):

$result = $api
->transformations();

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->transformations();

Python (cloudinary 1.x):

result = cloudinary.api\
.transformations()

Node.js (cloudinary 1.x):

cloudinary.v2.api
.transformations()
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.transformations(ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

result = cloudinary
.ListTransformations();

Go (cloudinary-go 1.x):

resp, err := cld.Admin.ListTransformations(ctx, admin.ListTransformationsParams{})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/transformations

cli:

cld admin transformations

Sample response

The response contains an array of transformations. If the number of transformations exceeds the max_results value, the next_cursor parameter is also returned. You can specify this value as the next_cursor parameter of the following listing request.

{
    "transformations": [
    {
        "name": "t_Aspen_LUT",
        "allowed_for_strict": true,
        "used": false,
        "named": true
    },
    {
        "name": "w_110,h_100,c_fill",
        "allowed_for_strict": false,
        "used": false,
        "named": false
    },
    {
        "name": "c_thumb,g_face,h_100,w_80",
        "allowed_for_strict": false,
        "used": true,
        "named": false
    },
    {
        "name": "c_fill,h_75,w_75/jpg",
        "allowed_for_strict": false,
        "used": true,
        "named": false
    }
    ],
    "next_cursor": "8edbc61040178db60b0973ca9494bf3a"
}

Get transformation details

Get details of a single transformation. Supply either the name of the transformation or the transformation parameters.

Syntax

GET /transformations/:transformation

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.transformation(transformation, options = {})

PHP (cloudinary_php 2.x):

$api->transformation($transformation, $options = []);

PHP (cloudinary_php 1.x (legacy)):

$api->transformation($transformation, $options = []);

Python (cloudinary 1.x):

cloudinary.api.transformation(transformation, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.transformation(transformation, options).then(callback);

Java (cloudinary 1.x):

api.transformations(String transformation, Map options);

.NET (CloudinaryDotNet 1.x):

cloudinary.GetTransform(TransformParams params);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.GetTransformation(ctx, admin.GetTransformationParams{})

cli:

cld admin transformation

Required parameters

Parameter	Type	Description
transformation	String	The name of the transformation or the transformation parameters.

Note

If the derived assets do not have an extension, add "/" at the end of the transformation value: For example: f_webp,q_80,b_blue,w_200,h_200 becomes f_webp,q_80,b_blue,w_200,h_200/

Optional parameters

Parameter	Type	Description
max_results	Integer	Maximum number of derived resources to return (up to 500). Default: `10`.
next_cursor	String	When a request has more results to return than `max_results`, the `next_cursor` value is returned as part of the response. You can then specify this value as the `next_cursor` parameter of a following request.

Examples

Get transformation by name:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.transformation('w_150,h_100,c_fill')

PHP (cloudinary_php 2.x):

$result = $api
->transformation("w_150,h_100,c_fill");

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->transformation("w_150,h_100,c_fill");

Python (cloudinary 1.x):

result = cloudinary.api\
.transformation("w_150,h_100,c_fill")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.transformation('w_150,h_100,c_fill')
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.transformations("w_150,h_100,c_fill", ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

result = cloudinary
.GetTransform("w_150,h_100,c_fill");

Go (cloudinary-go 1.x):

resp, err := cld.Admin.GetTransformation(ctx, admin.GetTransformationParams{Transformation: "w_150,h_100,c_fill"})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/transformations/w_150,h_100,c_fill

cli:

cld admin transformation "w_150,h_100,c_fill"

Get transformation by parameters:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.transformation(:width => 150, :height => 100,
  :crop => :fill)

PHP (cloudinary_php 2.x):

$result = $api
->transformation(["width" => 150, "height" => 100,
  "crop" => "fill"]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api-
>transformation(["width" => 150, "height" => 100,
  "crop" => "fill"]);

Python (cloudinary 1.x):

result = cloudinary.api\
.transformation(dict(width = 150, height = 100, crop = "fill"))

Node.js (cloudinary 1.x):

cloudinary.v2.api
.transformation({width: 150, height: 100, crop: 'fill'})
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.transformation(new Transformation().width(150).height(100).
  crop("fill").generate(), ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

Not supported by this SDK

Go (cloudinary-go 1.x):

Not supported by this SDK

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/transformations/c_fill,h_100,w_150

cli:

cld admin transformation '{"width": 500, "height": 100, "crop": "fill"}'

Note

If running the CLI command on Windows, you need to escape the double quotes within the curly braces using either \ or ", for example, \"text\" or ""text"".

Sample response

{
  "name": "w_150,h_100,c_fill",
  "allowed_for_strict": false,
  "used": true,
  "named": false,
  "info": [
    {
      "width": 150,
      "height": 100,
      "crop": "fill"
    }
  ],
  "derived": [
    {
      "public_id": "sample",
      "resource_type": "image",
      "type": "upload",
      "format": "jpg",
      "url":
        "http://.../demo/image/upload/w_150,h_100,c_fill/v1341141057/sample.jpg",
      "secure_url":
        "https://.../demo/image/upload/w_150,h_100,c_fill/v1341141057/sample.jpg",
      "bytes": 10202,
      "id": "2adf1841874c7b2326d1f90cbedbc914"
    }
  ]
}

Create a named transformation

Create a new named transformation.

Syntax

POST /transformations/:name

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.create_transformation(name, transformation)

PHP (cloudinary_php 2.x):

$api->createTransformation($name, transformation);

PHP (cloudinary_php 1.x (legacy)):

$api->create_transformation($name, transformation);

Python (cloudinary 1.x):

cloudinary.api.create_transformation(name, transformation)

Node.js (cloudinary 1.x):

cloudinary.v2.api.create_transformation(name, transformation).then(callback);

Java (cloudinary 1.x):

api.createTransformations(String name, String transformation));

.NET (CloudinaryDotNet 1.x):

cloudinary.CreateTransform(createTransformParams params);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.CreateTransformation(ctx, admin.CreateTransformationParams{})

cli:

cld admin create_transformation (name, transformation)

Required parameters

Parameter	Type	Description
name	String	The name of the transformation.
transformation	String	The transformation parameters.

Optional parameters

Parameter	Type	Description
allowed_for_strict	Boolean	Whether to allow this named transformation when strict transformations are enabled. Default: `true`.

Examples

Create named transformation by string:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.create_transformation('small_fill',
  'w_150,h_100,c_fill')

PHP (cloudinary_php 2.x):

$result = $api
->createTransformation("small_fill", "w_150,h_100,c_fill");

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->create_transformation("small_fill", "w_150,h_100,c_fill");

Python (cloudinary 1.x):

result = cloudinary.api\
.create_transformation("small_fill",
  "w_150,h_100,c_fill")

Node.js (cloudinary 1.x):

cloudinary.v2.api
.create_transformation('small_fill',
  'w_150,h_100,c_fill')
.then(result=>console.log(result));

Java (cloudinary 1.x):

result = api
.createTransformation("small_fill", "w_150,h_100,c_fill",
  ObjectUtils.emptyMap());

.NET (CloudinaryDotNet 1.x):

var createTransformParams = new CreateTransformParams(){
  Name = "small_fill",
  Transformation = new Transformation().Width(150).Height(100).Crop("fill")};
cloudinary.CreateTransform(createTransformParams);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.CreateTransformation(ctx, admin.CreateTransformationParams{
      Name:           "small_fill", 
      Transformation: "w_150,h_100,c_fill"})

curl:

curl \
  -d 'transformation=w_150,h_100,c_fill' \
  -X POST \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/transformations/small_fill

cli:

cld admin create_transformation "small_fill" "w_150,h_100,c_fill"

Create named transformation by parameters:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

result = Cloudinary::Api
.create_transformation('small_fill2',
  {:width => 150, :height => 100, :crop => :fill})

PHP (cloudinary_php 2.x):

$result = $api
->createTransformation("small_fill2",
  ["width" => 150, "height" => 100, "crop" => "fill"]);

PHP (cloudinary_php 1.x (legacy)):

$result = $api
->create_transformation("small_fill2",
  ["width