Admin API reference

The Admin API is a rate-limited API that provides full control of all uploaded media assets (resources), fetched social profile pictures, generated transformations and more.

On this page:

API Overview
Resources
Transformations
Upload mappings
Upload presets
Metadata fields
Folders
Adaptive streaming profiles
Tags
Usage
Ping

API Overview

The Admin API is accessed using HTTPS to endpoints. By default, the API endpoint uses the following format:

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

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

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 on your own Cloudinary account 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.

You can find more details about the elements included in your JSON response in the API Response Reference.

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

Using SDKs with the Admin API
Error handling
Usage limits
Pagination
Alternative data centers and endpoints (Premium feature)

Using SDKs with the Admin API

Our server-side SDK libraries provide a wrapper for the Admin API, enabling you to use your native programming language of choice. When using an SDKs, 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 All

Ruby:

Cloudinary::Api.resources

PHP:

$api->resources();

Python:

cloudinary.api.resources()

Node.js:

cloudinary.v2.api.resources(
function(error, result) {console.log(result, error); });

Java:

api.resources(ObjectUtils.emptyMap());

.Net:

cloudinary.ListResources();

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 All

Ruby:

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:

$result = $api->resources();
var_dump($result->rate_limit_allowed);
php > int(500)
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:

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.v2.api.resources(
function(error, 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:

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:

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

Tip

You can also retrive rate limits details as well as transformation, bandwidth, and storage limits, and a variety of additional account 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 Cloudinary account 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:

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

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

Note

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

Resources

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

Method	Description
GET`/resources/:resource_type(/:type)`	Get resources
GET`/resources/:resource_type/tags/:tag`	Get resources by tag
GET`/resources/:resource_type/context/`	Get resources by context
GET`/resources/:resource_type/moderations/:moderation_kind/:status`	Get resources in moderation queues
GET`/resources/:resource_type/:type/:public_id`	Get the details of a single resource
GET`/resources/search`	Search for resources
POST`/resources/:resource_type/:type/:public_id`	Update details of an existing resource
POST`/resources/:resource_type/:type/restore`	Restore resources
POST`/resources/:resource_type/upload/update_access_mode`	Update access mode
DELETE`/resources/:resource_type/:type`	Delete resources
DELETE`/resources/:resource_type/tags/:tag`	Delete resources by tags

Get resources

Lists resources (assets) uploaded to your account.

Syntax

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

Ruby PHP Python Node.js Java .Net All

Ruby:

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

PHP:

$api->resources($options = array());

Python:

cloudinary.api.resources(**options)

Node.js:

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

Java:

api.resources(Map options);

.Net:

cloudinary.ListResources(ListResourceParams params);

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`, `instagram_name`, `gravatar`, `youtube`, `hulu`, `vimeo`, `animoto`, `worldstarhiphop`, `dailymotion`. Default: all.
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.
public_ids	String[]	An array of public IDs. Get assets with the given public IDs (up to 100).
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. Supported unless `prefix` or `public_ids` were specified.
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 context 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 cURL All

Ruby:

Cloudinary::Api.resources

PHP:

$api->resources();

Python:

cloudinary.api.resources()

Node.js:

cloudinary.v2.api.resources(
  function(error, result) {console.log(result, error); });

Java:

api.resources(ObjectUtils.emptyMap());

.Net:

cloudinary.ListResources();

cURL:

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

Get uploaded images, up to a maximum of 30 results:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

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

PHP:

$api->resources(
  array("type" => "upload", "max_results" => 30));

Python:

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

Node.js:

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

Java:

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

.Net:

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

cURL:

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

Get all uploaded images with a given prefix:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

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

PHP:

$api->resources(
array(
  "type" => "upload", 
  "prefix" => "sample"));

Python:

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

Node.js:

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

Java:

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

.Net:

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

cURL:

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

Get Facebook images:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

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

PHP:

$api->resources(
array("type" => "facebook"));

Python:

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

Node.js:

cloudinary.v2.api.resources(
  { type: 'facebook' }, 
  function(error, result) {console.log(result, error); });

Java:

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

.Net:

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

cURL:

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

Get raw uploaded files:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

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

PHP:

$api->resources(
  array("resource_type" => "raw"));

Python:

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

Node.js:

cloudinary.v2.api.resources(
  { resource_type: 'raw' }, 
  function(error, result) {console.log(result, error); });

Java:

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

.Net:

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

cURL:

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

Get all uploaded images with the given IDs:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

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

PHP:

$api->resources_by_ids(array("user_photo_1", "user_photo_2"));

Python:

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

Node.js:

cloudinary.v2.api.resources_by_ids(["user_photo_1", "user_photo_2"],
  function(error, result) {console.log(result, error); });

Java:

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

.Net:

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

cURL:

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

Sample response

{
    "resources": [
      {
        "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,
        "access_mode": "public",
        "url": "http://res.cloudinary.com/demo/image/upload/v1333013579/face_center.jpg",
        "secure_url": "https://.../image/upload/v1333013579/face_center.jpg"
      },
      {
        "public_id": "12208495",
        "format": "jpg",
        "resource_type": "image",
        "type": "facebook",
        "created_at": "2012-10-06T17:18:52Z",
        "bytes": 0,
        "url": "http://res.cloudinary.com/demo/image/facebook/4.jpg",
        "secure_url": "https://.../image/facebook/4.jpg"
      },
    ]
}

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.

Syntax

GET /resources/:resource_type/tags/:tag

Ruby PHP Python Node.js Java .Net All

Ruby:

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

PHP:

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

Python:

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

Node.js:

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

Java:

api.resourcesByTag(String tag, Map options);

.Net:

cloudinary.ListResourcesByTag(ListResourcesByTagParams params);

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 context 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 cURL All

Ruby:

Cloudinary::Api.resources_by_tag('mytag')

PHP:

$api->resources_by_tag("mytag");

Python:

cloudinary.api.resources_by_tag("mytag")

Node.js:

cloudinary.v2.api.resources_by_tag("mytag", 
  function(error, result) {console.log(result, error); });

Java:

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

.Net:

cloudinary.ListResourcesByTag("mytag");

cURL:

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

Get all raw files by tag:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

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

PHP:

$api->resources_by_tag("mytag",
  array("resource_type" => "raw"));

Python:

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

Node.js:

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

Java:

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

.Net:

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

cURL:

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

Get resources by context

Retrieves resources (assets) with a specified context 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 All

Ruby:

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

PHP:

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

Python:

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

Node.js:

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

Java:

api.resourcesByContext(String key, Map options);

.Net:

Not supported by this SDK

Required parameters

Parameter	Type	Description
key	String	Only assets with this context 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 context key are returned. If this parameter is not provided, all assets with the given context 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 context associated with each asset. Default: `false`.
moderations	Boolean	Whether to include image moderation status of each asset. Default: `false`.

Examples

Get images by context key:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

Cloudinary::Api.resources_by_context('mycontextkey')

PHP:

$api->resources_by_context("mycontextkey");

Python:

cloudinary.api.resources_by_context("mycontextkey")

Node.js:

cloudinary.v2.api.resources_by_context("mycontextkey", 
  function(error, result) {console.log(result, error); });

Java:

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

.Net:

Not supported by this SDK

cURL:

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

Get video files by context key=value:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

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

PHP:

$api->resources_by_context("mycontextkey", "mycontextvalue"
  array("resource_type" => "video"));

Python:

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

Node.js:

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

Java:

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

.Net:

Not supported by this SDK

cURL:

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

Get resources in moderation queues

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

Syntax

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

Ruby PHP Python Node.js Java .Net All

Ruby:

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

PHP:

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

Python:

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

Node.js:

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

Java:

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

.Net:

cloudinary.ListResourcesByModerationStatus(ModerationStatus Params);

Required parameters

Parameter	Type	Description
moderation_kind	String	The type of moderation queue to list. Possible values: `manual`, `webpurify`, `aws_rek`, `metascan`.
status	String	The moderation status of assets to retrieve. Possible values: `pending`, `approved`, `rejected`.

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 context 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 cURL All

Ruby:

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

PHP:

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

Python:

cloudinary.api.resources_by_moderation("manual", "pending")

Node.js:

cloudinary.v2.api.resources_by_moderation('manual', 'pending',
  function(error, result) {console.log(result, error); });

Java:

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

.Net:

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

cURL:

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

Get images automatically approved by the WebPurify add-on:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

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

PHP:

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

Python:

cloudinary.api.resources_by_moderation("webpurify", "approved")

Node.js:

cloudinary.v2.api.resources_by_moderation('webpurify', 'approved',
  function(error, result) {console.log(result, error); });

Java:

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

.Net:

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

cURL:

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

Sample response

{
   "resources":
    [{
      "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,
      "url":
       "http://res.cloudinary.com/demo/image/upload/v1570976812/q7vcvrfjm9mj4bfp3qc8.jpg",
      "secure_url":
       "https://res.cloudinary.com/demo/image/upload/v1570976812/q7vcvrfjm9mj4bfp3qc8.jpg"
     },
     {
      "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,
      "url":
       "http://res.cloudinary.com/demo/image/upload/v1570977154/zp4fgdbabhlwwa7bxu84.jpg",
      "secure_url":
       "https://res.cloudinary.com/demo/image/upload/v1570977154/zp4fgdbabhlwwa7bxu84.jpg"
     }
   ]
}

Get the details of a single resource

Return details of the requested resource (asset) as well as all its derived assets.

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

Syntax

Ruby PHP Python Node.js Java .Net All

Ruby:

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

PHP:

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

Python:

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

Node.js:

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

Java:

api.resource(String public_id, Map options);

.Net:

cloudinary.GetResource(ResourceParams params);

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`, `instagram_name`, `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`.
image_metadata	Boolean	Whether to include IPTC, XMP, and detailed Exif metadata. Default: `false`. Returned metadata by type: - Images: `PixelsPerUnitX`, `PixelsPerUnitY`, `PixelUnits`, `Colorspace`, and `DPI`. - Audio and video: `audio_codec`, `audio_bit_rate`, `audio_frequency`, `channels`, `channel_layout`. - Video: `pix_format`, `codec`, `level`, `profile`, `video_bit_rate`, `dar`. Note: Using this parameter also returns the asset's ETag value for all asset types, including raw.
exif	Boolean	Deprecated. Use image_metadata instead. Default: `false`.
faces	Boolean	Whether to include a list of coordinates of detected faces. Default: `false`.
quality_analysis	Boolean	Whether to return a quality analysis value for the image between 0 and 1, where 0 means the image is blurry and out of focus and 1 means the image is sharp and in focus. 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`.
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 cURL All

Ruby:

Cloudinary::Api.resource('sample')

PHP:

$api->resource("sample");

Python:

cloudinary.api.resource("sample")

Node.js:

cloudinary.v2.api.resource('sample',
  function(error, result) {console.log(result, error); });

Java:

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

.Net:

cloudinary.GetResource("sample");

cURL:

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

Faces, colors and Exif image details:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

Cloudinary::Api.resource('sample',
  :faces => true, 
  :colors => true, 
  :exif => true)

PHP:

$api->resource("sample",
  array(
    "faces" => TRUE, 
    "colors" => TRUE, 
    "exif" => TRUE));

Python:

cloudinary.api.resource("sample",
  faces = True, 
  colors = True, 
  exif = True)

Node.js:

cloudinary.v2.api.resource('sample', 
  { faces: true, 
    colors: true, 
    exif: true },
  function(error, result) {console.log(result, error); });

Java:

api.resource("sample", 
  ObjectUtils.asMap(
    "faces", true,
    "colors", true, 
    "exif", true));

.Net:

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

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

cURL:

curl \
  -d "faces=1&colors=1&exif=1" \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload/sample

Facebook picture details:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

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

PHP:

$api->resource("4", 
  array("type" => "facebook"));

Python:

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

Node.js:

cloudinary.v2.api.resource('4', 
  { type: 'facebook' },
  function(error, result) {console.log(result, error); });

Java:

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

.Net:

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

cURL:

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

Uploaded raw file details:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

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

PHP:

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

Python:

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

Node.js:

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

Java:

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

.Net:

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

cURL:

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

Sample response

{
    "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"
      }
    },
    "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"
      }
    ],

    "faces": [[98,74,61,83], [140,130,52,71]],

    "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
        ]
      ]
    },
}

Search for resources

Search allows you fine control on filtering and retrieving information on all the resources (assets) in your account 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 All

Ruby:

result = Cloudinary::Search.execute

PHP:

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

Python:

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

Node.js:

cloudinary.v2.search.execute().then(result=>console.log(result));

Java:

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

.Net:

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

Optional parameters

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 section in the Search API 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 `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 - 5mb), large (5mb - 100 mb), and huge (>100 mb). - Video `duration` is divided into short (< 3 minutes), medium (3-12 min), and long (> 12 min).

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 cURL All

Ruby:

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

PHP:

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

Python:

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

Node.js:

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

Java:

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

.Net:

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

cURL:

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

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 cURL All

Ruby:

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

PHP:

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

Python:

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

Node.js:

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

Java:

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

.Net:

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

cURL:

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

Sample response

{
    "total_count": 32,
    "time": 30,
    "aggregations": {
      "format": {
        "png": 4,
        "jpg": 21,
        "mp4": 3,
        "doc": 4
      }
    },
    "next_cursor": "b16b8bd80426df43a107f26b0348",
    "resources": [
    {
      "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,
      "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"
    },
    {
      "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 All

Ruby:

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

PHP:

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

Python:

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

Node.js:

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

Java:

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

.Net:

cloudinary.Update(UpdateParams params);

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`, `instagram_name`, `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 general textual context metadata to attach to an uploaded asset. The context values of uploaded files are available for fetching 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	Whether to assign tags to an image according to detected scene categories with confidence score higher than the given value. See the Google Automatic Video Tagging, Google Auto Tagging, Imagga Auto Tagging, Amazon Rekognition Auto Tagging, and Amazon Rekognition Celebrity Detection add-ons for more details. Range: 0.0 to 1.0
detection	String	Set to `adv_face` or `aws_rek_face` to extract an extensive list of face attributes from an image using the Advanced Facial Attribute Detection or Amazon Rekognition Celebrity Detection add-ons. 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. 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 publically 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 cURL All

Ruby:

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

PHP:

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

Python:

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

Node.js:

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

Java:

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

.Net:

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

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

Restore resources

Restores one or more resources (assets) from backup.

Syntax

POST /resources/:resource_type/:type/restore

Ruby PHP Python Node.js Java .Net All

Ruby:

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

PHP:

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

Python:

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

Node.js:

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

Java:

api.restore(Map public_ids, Map options);

.Net:

cloudinary.Restore(RestoreParams params);

Required parameters

Parameter	Type	Description
public_ids	String[]	The public IDs of (deleted or existing) backed up assets to restore. Reverts to the latest backed up version 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`, Default: `image`.

Examples

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

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

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

PHP:

$api->restore(array("image1", "image2");

Python:

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

Node.js:

cloudinary.v2.api.restore(["image1", "image2"],
  function(error, result) {console.log(result, error); });

Java:

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

.Net:

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

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

Sample response

The details of the restored resources:

{
  "image1": 
  {
    "public_id": "image1", 
    "version": 1574260348, 
    "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
  }
  "image2": 
  {
    "public_id": "image2", 
    "version": 1574261348, 
    "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
  }
}

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: Upload method and Access mode.

Syntax

POST /resources/:resource_type/upload/update_access_mode

Ruby PHP Python Node.js Java .Net All

Ruby:

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

PHP:

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

Python:

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

Node.js:

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

Java:

api.updateResourcesAccessMode(String access_mode, Map options);

.Net:

cloudinary.UpdateResourceAccessMode(RestoreParams params);

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 cURL All

Ruby:

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

PHP:

$api->update_resources_access_mode_by_ids("public", 
  array("image1", "image2"));

Python:

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

Node.js:

cloudinary.v2.api.update_resources_access_mode_by_ids("public", 
  ['image1', 'image2'],
  function(error, result){console.log(result);});

Java:

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

.Net:

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

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

Update the access mode of uploaded videos by prefix:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

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

PHP:

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

Python:

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

Node.js:

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

Java:

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

.Net:

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

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

Update the access mode of uploaded images by tag:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

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

PHP:

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

Python:

cloudinary.api.update_resources_access_mode_by_tag("public", "20170216")

Node.js:

cloudinary.v2.api.update_resources_access_mode_by_tag('public', "20170216", 
  function(error, result){console.log(result);});

Java:

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

.Net:

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

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

Sample response

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

Delete resources

Deletes resources (assets) uploaded to your account

Syntax

DELETE /resources/:resource_type/:type

Ruby PHP Python Node.js Java .Net All

Ruby:

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

PHP:

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

Python:

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

Node.js:

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

Java:

api.deleteResources(Map public_ids, Map options);

.Net:

cloudinary.DeleteResources(DelResParams params);

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`, `authenticated`, `facebook`, `twitter`, `instagram_name`, `gravatar`, `youtube`, `hulu`, `vimeo`, `animoto`, `worldstarhiphop`, `dailymotion`. Default: all.
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 a few minutes (although it might take up to an hour) 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 cURL All

Ruby:

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

PHP:

$api->delete_resources(array("image1", "image2"));

Python:

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

Node.js:

cloudinary.v2.api.delete_resources(['image1', 'image2'],
  function(error, result) {console.log(result, error); });

Java:

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

.Net:

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

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

Delete Facebook pictures by public IDs:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

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

PHP:

$api->delete_resources(array("4"), 
  array("type" => "facebook"));

Python:

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

Node.js:

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

Java:

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

.Net:

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

cURL:

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

Delete uploaded images by prefix:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

Cloudinary::Api.delete_resources_by_prefix('sunday')

PHP:

$api->delete_resources_by_prefix("sunday");

Python:

cloudinary.api.delete_resources_by_prefix("sunday")

Node.js:

cloudinary.v2.api.delete_resources_by_prefix('sunday', 
  function(error, result) {console.log(result, error); });

Java:

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

.Net:

cloudinary.DeleteResourcesByPrefix("sunday");

cURL:

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

Delete derived images only:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

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

PHP:

$api->delete_resources(array("image1", "image2"),
  array("keep_original" => TRUE));

Python:

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

Node.js:

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

Java:

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

.Net:

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

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

Delete all Facebook pictures:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

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

PHP:

$api->delete_all_resources(
  array("type" => "facebook"));

Python:

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

Node.js:

cloudinary.v2.api.delete_all_resources(
  {type: 'facebook'}, 
  function(error, result) {console.log(result, error); });

Java:

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

.Net:

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

cURL:

curl \
  -d "all=true" \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/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 All

Ruby:

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

PHP:

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

Python:

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

Node.js:

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

Java:

api.deleteResourcesByTag(String tag, Map options);

.Net:

cloudinary.DeleteResourcesByTag(TagParams params);

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 a few minutes (although it might take up to an hour) 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 cURL All

Ruby:

Cloudinary::Api.delete_resources_by_tag('mytag')

PHP:

$api->delete_resources_by_tag("mytag");

Python:

cloudinary.api.delete_resources_by_tag("mytag")

Node.js:

cloudinary.v2.api.delete_resources_by_tag('mytag',
  function(error, result) {console.log(result, error); });

Java:

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

.Net:

cloudinary.DeleteResourcesByTag("mytag");

cURL:

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

Sample response

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

Transformations

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

Method	Description
GET `/transformations`	Get all transformations
GET `/transformations/:transformation`	Get details of a transformation
POST`/transformations/:name`	Create a named transformation
PUT`/transformations/:transformation`	Update a transformation
DELETE`/transformations/:transformation`	Delete a transformation

Get Transformations

List all transformations.

Syntax

GET /transformations

Ruby PHP Python Node.js Java .Net All

Ruby:

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

PHP:

$api->transformations($options = array());

Python:

cloudinary.api.transformations(**options)

Node.js:

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

Java:

api.transformations(Map options);

.Net:

cloudinary.ListTransformations(TransformParams params);

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 cURL All

Ruby:

Cloudinary::Api.transformations

PHP:

$api->transformations();

Python:

cloudinary.api.transformations()

Node.js:

cloudinary.v2.api.transformations(function(error, result){console.log(result);});

Java:

api.transformations(ObjectUtils.emptyMap());

.Net:

cloudinary.ListTransformations();

cURL:

curl \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/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 All

Ruby:

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

PHP:

$api->transformation($transformation, $options = array());

Python:

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

Node.js:

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

Java:

api.transformations(String transformation, Map options);

.Net:

cloudinary.GetTransform(TransformParams params);

Required parameters

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

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 cURL All

Ruby:

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

PHP:

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

Python:

cloudinary.api.transformation("w_150,h_100,c_fill")

Node.js:

cloudinary.v2.api.transformation('w_150,h_100,c_fill',
  function(error, result) {console.log(result, error); });

Java:

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

.Net:

cloudinary.GetTransform("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

Get transformation by parameters:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

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

PHP:

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

Python:

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

Node.js:

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

Java:

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

.Net:

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

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 All

Ruby:

Cloudinary::Api.create_transformation(name, transformation)

PHP:

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

Python:

cloudinary.api.create_transformation(name, transformation)

Node.js:

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

Java:

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

.Net:

cloudinary.CreateTransform(createTransformParams params);

Required parameters

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

Examples

Create named transformation by string:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

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

PHP:

$api->create_transformation("small_fill", "w_150,h_100,c_fill");

Python:

cloudinary.api.create_transformation("small_fill",
  "w_150,h_100,c_fill")

Node.js:

cloudinary.v2.api.create_transformation('small_fill',
  'w_150,h_100,c_fill',
  function(error, result) {console.log(result, error); });

Java:

api.createTransformation("small_fill", "w_150,h_100,c_fill",
  ObjectUtils.emptyMap());

.Net:

var createTransformParams = new CreateTransformParams(){
  Name = "small_fill",
  Transformation = new Transformation().Width(150).Height(100).Crop("fill")};
cloudinary.CreateTransform(createTransformParams);

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

Create named transformation by parameters:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

Cloudinary::Api.create_transformation('small_fill2',
  {:width => 150, :height => 100, :crop => :fill})

PHP:

$api->create_transformation("small_fill2",
  array("width" => 150, "height" => 100, "crop" => "fill"));

Python:

cloudinary.api.create_transformation("small_fill2",
  dict(width = 150, height = 100, crop = "fill"))

Node.js:

cloudinary.v2.api.create_transformation('small_fill2',
  { width: 150, height: 100, crop: 'fill' },
  function(error, result) {console.log(result, error); });

Java:

api.createTransformation("small_fill2",
  new Transformation().width(150).height(100).crop("fill").generate(),
  ObjectUtils.emptyMap());

.Net:

var createTransformParams = new CreateTransformParams(){
  Name = "small_fill2",
  Transformation = new Transformation().Width(150).Height(100).Crop("fill")};
cloudinary.CreateTransform(createTransformParams);

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

Sample response

{
 "message": "created"
}

Update transformation

Update a single transformation. Supply either the name of the transformation or the transformation parameters.

Syntax

PUT /transformations/:transformation

Ruby PHP Python Node.js Java .Net All

Ruby:

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

PHP:

$api->update_transformation($transformation, $options = array());

Python:

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

Node.js:

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

Java:

api.updateTransformations(String transformation, Map options));

.Net:

cloudinary.UpdateTransform(updateTransformParams params);

Required parameters

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

Optional parameters

Parameter	Type	Description
allowed_for_strict	Boolean	Whether allow this transformation when Strict Transformations are enabled. Default: `false`.
unsafe_update	String	Allows updating an existing named transformation without updating all associated derived images (the new settings of the named transformation only take effect from now on).

Examples

Allow transformation by name:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

Cloudinary::Api.update_transformation('w_150,h_100,c_fill',
  :allowed_for_strict => true)

PHP:

$api->update_transformation("w_150,h_100,c_fill",
  array("allowed_for_strict" => 1));

Python:

cloudinary.api.update_transformation("w_150,h_100,c_fill",
  allowed_for_strict = True)

Node.js:

cloudinary.v2.api.update_transformation('w_150,h_100,c_fill',
  { allowed_for_strict: true },
  function(error, result) {console.log(result, error); });

Java:

api.updateTransformation("w_150,h_100,c_fill",
  ObjectUtils.asMap("allowed_for_strict", true);

.Net:

var updateTransformParams = new UpdateTransformParams(){
  Transformation = "w_150,h_100,c_fill",
  Strict = true};
cloudinary.UpdateTransform(updateTransformParams);

cURL:

curl \
  -d 'allowed_for_strict=true' \
  -X PUT \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/transformations/w_150,h_100,c_fill

Disallow transformation by parameters:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

Cloudinary::Api.update_transformation(
  { :width => 150, :height => 100, :crop => :fill},
  { :allowed_for_strict => false })

PHP:

$api->update_transformation(
  array("width" => 150, "height" => 100,"crop" => "fill"),
  array("allowed_for_strict" => 0));

Python:

cloudinary.api.update_transformation(
  dict(width = 150, height = 100, crop = "fill"), 
  dict(allowed_for_strict = False))

Node.js:

cloudinary.v2.api.update_transformation(
  { width: 150, height: 100, crop: 'fill' },
  { allowed_for_strict: false },
  function(error, result) {console.log(result, error); });

Java:

api.updateTransformation(
  new Transformation().width(150).height(100).crop("fill").generate(), 
  ObjectUtils.asMap("allowed_for_strict", false);

.Net:

:
var updateTransformParams = new UpdateTransformParams(){
  Transformation = "w_150,h_100,c_fill",
  Strict = false};
cloudinary.UpdateTransform(updateTransformParams);

cURL:

curl \
  -d 'allowed_for_strict=false' \
  -X PUT \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/transformations/c_fill,h_100,w_150

Update a named transformation:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

Cloudinary::Api.update_transformation('my_named',
  :unsafe_update => { :crop => :scale, :width =>103 })

PHP:

:
$api->update_transformation("my_named",
  array("crop" => "scale", "width" => 103));

Python:

cloudinary.api.update_transformation("my_named",
  dict(crop = "scale", width = 103))

Node.js:

cloudinary.v2.api.update_transformation("my_named",
  {crop: 'scale', width: 103},
  function(error, result) {console.log(result, error); });

Java:

api.updateTransformation("my_named",
  ObjectUtils.asMap("unsafe_update",
  new Transformation().crop("scale").width(103).generate());

.Net:

var updateTransformParams = new UpdateTransformParams(){
  Transformation = "my_named",
  UnsafeTransform = new Transformation().Crop("scale").Width(103)};
cloudinary.UpdateTransform(updateTransformParams);

cURL:

curl \
  -d 'unsafe_update=c_scale,w_103' \
  -X PUT \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/transformations/my_named

Sample response

{
 "message": "updated"
}

Delete transformation

Delete a single transformation. Supply either the name of the transformation or the transformation parameters.

Note

Deleting a transformation also deletes all the derived images based on this transformation (up to 1000). The method returns an error if there are more than 1000 derived images based on this transformation.

Syntax

DELETE /transformations/:transformation

Ruby PHP Python Node.js Java .Net All

Ruby:

Cloudinary::Api.delete_transformation(transformation)

PHP:

$api->delete_transformation($transformation);

Python:

cloudinary.api.delete_transformation(transformation)

Node.js:

cloudinary.v2.api.delete_transformation(transformation, callback});

Java:

api.deleteTransformations(String transformation);

.Net:

cloudinary.DeleteTransform(transformation);

Required parameters

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

Examples

Delete transformation by name:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

Cloudinary::Api.delete_transformation('w_150,h_100,c_fill')

PHP:

$api->delete_transformation("w_150,h_100,c_fill");

Python:

cloudinary.api.delete_transformation("w_150,h_100,c_fill")

Node.js:

cloudinary.v2.api.delete_transformation('w_150,h_100,c_fill',
  function(error, result) {console.log(result, error); });

Java:

api.deleteTransformation("w_150,h_100,c_fill",
  ObjectUtils.emptyMap());

.Net:

cloudinary.DeleteTransform("w_150,h_100,c_fill");

cURL:

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

Delete transformation by parameters:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

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

PHP:

$api->delete_transformation(array("width" => 150, "height" => 100,
  "crop" => "fill"));

Python:

cloudinary.api.delete_transformation(dict(width = 150, height = 100,
  crop = "fill"))

Node.js:

cloudinary.v2.api.delete_transformation(
  {width: 150, height: 100, crop: 'fill'},
  function(error, result) {console.log(result, error); });

Java:

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

.Net:

Not supported by this SDK

cURL:

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

Sample response

{
 "message": "deleted"
}

Upload mappings

Dynamically fetches images from existing online locations and uploads the files to your account.

See the Auto upload remote images documentation for more information.

Method	Description
GET`/upload_mappings`	Get upload mappings
GET`/upload_mappings/:folder`	Get the details of a single upload mapping
POST`/upload_mappings`	Create an upload mapping
PUT`/upload_mappings`	Update an upload mapping
DELETE`/upload_mappings/:folder`	Delete an upload mapping

Get upload mappings

List all upload mappings by folder and includes its mapped template (URL).

Syntax

GET /upload_mappings

Ruby PHP Python Node.js Java .Net All

Ruby:

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

PHP:

$api->upload_mappings($options = array());

Python:

cloudinary.api.upload_mappings(**options)

Node.js:

cloudinary.v2.api.upload_mappings(options, callback);

Java:

api.uploadMappings(Map options);

.Net:

cloudinary.UploadMappings(uploadMappingParams params);

Optional parameters

Parameter	Type	Description
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.

Examples

List all upload mappings

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

Cloudinary::Api.upload_mappings

PHP:

$api->upload_mappings();

Python:

cloudinary.api.upload_mappings()

Node.js:

cloudinary.v2.api.upload_mappings(function(error, result){console.log(result);});

Java:

api.uploadMappings(ObjectUtils.emptyMap());

.Net:

cloudinary.UploadMappings();

cURL:

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

Sample response

{
    "mappings": [
      {
        "folder": "wiki", 
        "template": "https://u.wiki.example.com/wiki-images/"
      },
      {
        "folder": "exam", 
        "template": "http://images.example.com/product_assets/images/"
      }, 
    ]
}

Get the details of a single upload mapping

Retrieve the mapped template (URL) of a given upload mapping folder.

Syntax

GET /upload_mappings/:folder

Ruby PHP Python Node.js Java .Net All

Ruby:

Cloudinary::Api.upload_mapping(folder)

PHP:

$api->upload_mapping($folder);

Python:

cloudinary.api.upload_mapping(folder)

Node.js:

cloudinary.v2.api.upload_mapping(folder, callback);

Java:

api.uploadMapping(String folder));

.Net:

cloudinary.UploadMapping(uploadMappingParams params);

Required parameters

Parameter	Type	Description
folder	String	The name of the folder to map.

Examples

Upload mapping details by folder the 'wiki' folder:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

Cloudinary::Api.upload_mapping('wiki')

PHP:

$api->upload_mapping("wiki");

Python:

cloudinary.api.upload_mapping("wiki")

Node.js:

cloudinary.v2.api.upload_mapping('wiki',
  function(error, result){console.log(result);});

Java:

api.uploadMapping("wiki",
  ObjectUtils.emptyMap());

.Net:

cloudinary.UploadMapping("wiki");

cURL:

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

Sample response

{
    "folder": "wiki", 
    "template": "https://u.wiki.example.com/wiki-images/"
}

Create an upload mapping

Create a new upload mapping folder and its template (URL).

Syntax

POST /upload_mappings

Ruby PHP Python Node.js Java .Net All

Ruby:

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

PHP:

$api->create_upload_mapping(folder, $options = array());

Python:

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

Node.js:

cloudinary.v2.api.create_upload_mapping(folder, options, callback);

Java:

api.createUploadMapping(String folder, Map options));

.Net:

cloudinary.CreateUploadMapping(uploadMappingParams params);

Required parameters

Parameter	Type	Description
folder	String	The name of the folder to map.
template	String	The URL to be mapped to the folder, as part of `options`.

Examples

Create upload mapping from 'http://www.example.com/images/' to a folder called 'my_map':

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

Cloudinary::Api.create_upload_mapping("my_map",
  :template => "http://www.example.com/images/")

PHP:

$api->create_upload_mapping("my_map",
  array("template" => "http://www.example.com/images/"));

Python:

cloudinary.api.create_upload_mapping("my_map",
  template = "http://www.example.com/images/")

Node.js:

cloudinary.v2.api.create_upload_mapping('my_map',
  { template: "http://www.example.com/images/" },
  function(error, result){console.log(result);});

Java:

api.createUploadMapping("my_map",
  ObjectUtils.asMap("template", "http://www.example.com/images/"));

.Net:

cloudinary.CreateUploadMapping("my_map", "http://www.example.com/images/");

cURL:

curl \
 -d "folder=my_map&template=http://www.example.com/images/" \
 -X POST \
 https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/upload_mappings

Sample response

{
    "message": "created"
}

Update an upload mapping

Update an existing upload mapping folder with a new template (URL).

Syntax

PUT /upload_mappings

Ruby PHP Python Node.js Java .Net All

Ruby:

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

PHP:

$api->update_upload_mapping(folder, $options = array());

Python:

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

Node.js:

cloudinary.v2.api.update_upload_mapping(folder, options, callback);

Java:

api.updateUploadMapping(String folder, Map options));

.Net:

cloudinary.UpdateUploadMapping(uploadMappingParams params);

Required parameters

Parameter	Type	Description
folder	String	The name of the folder to map.
template	String	The URL to be mapped to the folder, as part of `options`.

Examples

Update an upload mapping to the 'wiki' folder with the https://u.wiki.com/images/ URL:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

Cloudinary::Api.update_upload_mapping("wiki",
  :template => "https://u.wiki.com/images/")

PHP:

$api->update_upload_mapping("wiki",
  array("template" => "https://u.wiki.com/images/"));

Python:

cloudinary.api.update_upload_mapping("wiki",
  template = "https://u.wiki.com/images/")

Node.js:

cloudinary.v2.api.update_upload_mapping('wiki',
  { template: "https://u.wiki.com/images/" },
  function(error, result){console.log(result);});

Java:

api.updateUploadMapping("wiki",
  ObjectUtils.asMap("template", "https://u.wiki.com/images/"), ObjectUtils.emptyMap());

.Net:

var uploadMappingParams = new UploadMappingParams(){
  Folder = "wiki",
  Template = "https://u.wiki.com/images/";
cloudinary.UploadMapping(uploadMappingParams);

cURL:

curl \
  -d "folder=wiki&template=https://u.wiki.com/images/" \
  -X PUT \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/upload_mappings

Sample response

{
    "message": "updated"
}

Delete an upload mapping

Delete an upload mapping by folder name.

Syntax

DELETE /upload_mappings/:folder

Ruby PHP Python Node.js Java .Net All

Ruby:

Cloudinary::Api.delete_upload_mapping(folder)

PHP:

$api->delete_upload_mapping(folder);

Python:

cloudinary.api.delete_upload_mapping(folder)

Node.js:

cloudinary.v2.api.delete_upload_mapping(folder, callback);

Java:

api.deleteUploadMapping(String folder));

.Net:

cloudinary.DeleteUploadMapping(uploadMappingParams params);

Required parameters

Parameter	Type	Description
folder	String	The name of the folder to map.

Examples

Delete an upload mapping to the 'wiki' folder:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

Cloudinary::Api.delete_upload_mapping('wiki')

PHP:

$api->delete_upload_mapping("wiki");

Python:

cloudinary.api.delete_upload_mapping("wiki")

Node.js:

cloudinary.v2.api.delete_upload_mapping('wiki',
  function(error, result){console.log(result);});

Java:

api.deleteUploadMapping("wiki",
  ObjectUtils.emptyMap());

.Net:

cloudinary.DeleteUploadMapping("wiki");

cURL:

curl \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/upload_mappings/wiki

Sample response

{
    "message": "deleted"
}

Upload presets

Enables you to centrally define image upload options instead of specifying them in each upload call.

See the upload preset documentation for more information.

Methods	Description
GET `/upload_presets`	Get upload presets
GET `/upload_presets/:name`	Get the details of a single upload preset
POST`/upload_presets`	Create an upload preset
PUT`/upload_presets/:name`	Update an upload preset
DELETE`/upload_presets/:name`	Delete an upload preset

Get upload presets

Lists the upload presets defined for your account.

Syntax

GET /upload_presets

Ruby PHP Python Node.js Java .Net All

Ruby:

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

PHP:

$api->upload_presets($options = array());

Python:

cloudinary.api.upload_presets(**options)

Node.js:

cloudinary.v2.api.upload_presets(options, callback);

Java:

api.uploadPresets(Map options);

.Net:

cloudinary.ListUploadPresets(uploadPresetParams params);

Optional parameters

Parameter	Type	Description
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.

Examples

List all upload presets:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

Cloudinary::Api.upload_presets

PHP:

$api->upload_presets();

Python:

cloudinary.api.upload_presets()

Node.js:

cloudinary.v2.api.upload_presets(function(error, result){console.log(result);});

Java:

api.uploadPresets(ObjectUtils.emptyMap());

.Net:

cloudinary.ListUploadPresets();

cURL:

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

Sample response

{
    "presets": [
      {
        "name": "pd1e4lst",
        "unsigned": true,
        "settings": 
          {
            "transformation": "c_crop,g_custom/ar_1,c_pad,w_1.0"
          }
      }, 
      {
        "name": "remote_media",
        "unsigned": false,
        "settings": 
          {
            "tags": "test"
            "allowed_formats": "jpg,png",
            "eager": "c_fill,g_face,h_150,w_200"
          }
      }, 
    ]
}

Get the details of a single upload preset

Retrieves the details of an upload preset.

Syntax

GET /upload_presets/:name

Ruby PHP Python Node.js Java .Net All

Ruby:

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

PHP:

$api->upload_presets($name, $options = array());

Python:

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

Node.js:

cloudinary.v2.api.upload_presets(name, options, callback);

Java:

api.uploadPresets(String name, Map options);

.Net:

cloudinary.GetUploadPreset(uploadPresetParams params);

Required parameters

Parameter	Type	Description
name	String	The name of the upload preset.

Examples

Upload preset details for the 'remote_media' preset:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

Cloudinary::Api.upload_presets('remote_media')

PHP:

$api->upload_presets("remote_media");

Python:

cloudinary.api.upload_presets("remote_media")

Node.js:

cloudinary.v2.api.upload_presets('remote_media',
  function(error, result){console.log(result);});

Java:

api.uploadPresets("remote_media",
  ObjectUtils.emptyMap());

.Net:

cloudinary.GetUploadPreset("remote_media");

cURL:

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

Sample response

{
    "name": "remote_media",
    "unsigned": false,
    "settings": 
      {
        "tags": "test",
        "allowed_formats": "jpg,png",
        "eager": "c_fill,g_face,h_150,w_200"
      }
}

Create an upload preset

Create a new upload preset.

Syntax

POST /upload_presets

Ruby PHP Python Node.js Java .Net All

Ruby:

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

PHP:

$api->create_upload_preset($options = array());

Python:

cloudinary.api.create_upload_preset(**options)

Node.js:

cloudinary.v2.api.create_upload_preset(options, callback);

Java:

api.createUploadPreset(Map options);

.Net:

cloudinary.CreateUploadPreset(uploadPresetParams params);

Optional parameters

Parameter	Type	Description
name	String	The name to assign to the new upload preset. If not specified, a random name is generated. If the name is of an existing preset, it will be overwritten.
unsigned	Boolean	Whether this upload preset allows unsigned uploading to Cloudinary. Default: `false`.
disallow_public_id	Boolean	Whether this upload preset disables assigning a public_id in the upload call. Default: `false`.
{Upload parameters}		The upload parameters to apply to assets uploaded with this preset.

Examples

Create a new upload preset called 'my_preset', that allows unsigned uploading, adds the tag 'remote' to uploaded images, and only allows the uploading of JPG and PNG image formats:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

Cloudinary::Api.create_upload_preset(
  :name => "my_preset",
  :unsigned => true, 
  :tags => "remote", 
  :allowed_formats => "jpg,png")

PHP:

$api->create_upload_preset(
  array(
    "name" => "my_preset", 
    "unsigned" => true, 
    "tags" => "remote", 
    "allowed_formats" => "jpg,png"));

Python:

cloudinary.api.create_upload_preset(
  name = "my_preset",
  unsigned = true, 
  tags = "remote", 
  allowed_formats = "jpg,png")

Node.js:

cloudinary.v2.api.create_upload_preset(
  { name: "my_preset", 
    unsigned: true, 
    tags: "remote", 
    allowed_formats: "jpg,png" },
  function(error, result){console.log(result);});

Java:

api.createUploadPreset(
  ObjectUtils.asMap(
    "name", "my_preset"
    "unsigned", true, 
    "tags" => "remote", 
    "allowed_formats" => "jpg,png"));

.Net:

var uploadPresetParams = new UploadPresetParams(){
  Name = "my_preset"
  Unsigned = true,
  Tags = "remote",
  AllowedFormats = "jpg,png"};
cloudinary.CreateUploadPreset(uploadPresetParams);

cURL:

curl \
  -d "name=my_preset&unsigned=true&tags=remote&allowed_formats=jpg,png" \
  -X POST \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/upload_presets

Sample response

{
    "message": "created"
}

Update an upload preset

Update an existing upload preset.

Syntax

PUT /upload_presets/:name

Ruby PHP Python Node.js Java .Net All

Ruby:

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

PHP:

$api->update_upload_preset($name, $options = array());

Python:

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

Node.js:

cloudinary.v2.api.update_upload_preset(name, options, callback);

Java:

api.updateUploadPreset(String name, Map options);

.Net:

cloudinary.UpdateUploadPreset(uploadPresetParams params);

Optional parameters

Parameter	Type	Description
name	String	The name of the upload preset.
unsigned	Boolean	Whether this upload preset allows unsigned uploading to Cloudinary. Default: `false`.
disallow_public_id	Boolean	Whether this upload preset disables assigning a public_id in the upload call. Default: `false`.
{Upload parameters}		The upload parameters to apply to assets uploaded with this preset.

Examples

Update an upload preset called 'wiki', to allow unsigned uploading, add the tag 'remote' to uploaded images, and only allow the uploading of JPG and PNG image formats:

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

Cloudinary::Api.update_upload_preset("wiki",
  :unsigned => true, 
  :tags => "remote", 
  :allowed_formats => "jpg,png")

PHP:

$api->update_upload_preset("wiki",
  array(
    "unsigned" => true, 
    "tags" => "remote", 
    "allowed_formats" => "jpg,png"));

Python:

cloudinary.api.update_upload_preset("wiki",
  unsigned = true, 
  tags = "remote", 
  allowed_formats = "jpg,png")

Node.js:

cloudinary.v2.api.update_upload_preset('wiki',
  { unsigned: true,
    tags: "remote", 
    allowed_formats: "jpg,png"},
  function(error, result){console.log(result);});

Java:

api.updateUploadPreset("wiki",
  ObjectUtils.asMap(
    "unsigned", true, 
    "tags" => "remote", 
    "allowed_formats" => "jpg,png"));

.Net:

var uploadPresetParams = new UploadPresetParams(){
  Name = "wiki",
  Unsigned = true,
  Tags = "remote",
  AllowedFormats = "jpg,png"};
cloudinary.UpdateUploadPreset(uploadPresetParams);

cURL:

curl \
  -d "unsigned=true&tags=remote&allowed_formats=jpg,png" \
  -X PUT \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/upload_presets/wiki

Sample response

{
    "message": "updated"
}

Delete an upload preset

Delete an existing upload preset.

Syntax

DELETE /upload_presets/:name

Ruby PHP Python Node.js Java .Net All

Ruby:

Cloudinary::Api.delete_upload_preset(name)

PHP:

$api->delete_upload_preset($name);

Python:

cloudinary.api.delete_upload_preset(name)

Node.js:

cloudinary.v2.api.delete_upload_preset(name, callback);

Java:

api.deleteUploadPreset(String name));

.Net:

cloudinary.DeleteUploadPreset(String name);

Required parameters

Parameter	Type	Description
name	String	The name of the upload preset.

Examples

Delete an upload preset called 'remote_media':

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

Cloudinary::Api.delete_upload_preset('remote_media')

PHP:

$api->delete_upload_preset("remote_media");

Python:

cloudinary.api.delete_upload_preset("remote_media")

Node.js:

cloudinary.v2.api.delete_upload_preset('remote_media',
  function(error, result){console.log(result);});

Java:

api.deleteUploadPreset("remote_media",
  ObjectUtils.emptyMap());

.Net:

cloudinary.DeleteUploadPreset("remote_media");

cURL:

curl \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/upload_presets/remote_media

Sample response

{
    "message": "deleted"
}

Metadata fields

Cloudinary structured metadata allows you to define typed fields for media assets, populate them with values programmatically or via the Media Library, and execute searches on them. You can also add validation rules, set default values, and define fields as mandatory.

A metadata field is a custom typed field (key) for storing user defined data (value) with a media asset.

Important

Structured metadata is currently in BETA, and is available in the Media Library only by request.

In this section:

Generic structure of a metadata field
Validating data
Datasource values
Metadata fields API

Generic structure of a metadata field

{
    "external_id": <string>,
    "type": <field_type_enum>,
    "label": <string>,
    "mandatory": <boolean>,
    "default_value": <field_type_value>,
    "validation": <validation_object>,
    "datasource": <datasource_object>  //enum and set types
}

Parameter	Required	Description
`external_id`	No	A unique immutable identification string for the metadata field. Default: auto-generated by Cloudinary (although we recommend you specify this yourself)
`type`	Yes	The type of value that can be assigned to the metadata field, possible types are limited to: * `string` - a single string value * `integer` - a single integer value * `date` - a custom date in the following format: {yyyy-mm-dd} * `enum` - a single value referenced by an `external_id` from a given list, predefined with the `datasource` parameter * `set` - multiple values referenced by `external_id`s from a given list, predefined with the `datasource` parameter
`label`	Yes	The label of the metadata field for display purposes.
`mandatory`	No	Whether a value must be given for this field, either when an asset is first uploaded, or when it is updated. Default: `false`
`default_value`	Yes (if `mandatory` is true)	The default value for the field (a set can have multiple default values defined by an array). Default: `null`
`validation`	No	Any validation rules to apply when values are entered (or updated) for this field. See Validating data for more details. Default: `null`
`datasource`	Yes (for the enum and set `type`)	The predefined list of values, referenced by `external_id`s, available for this field. See Datasource values for more details.

Validating data

The validation parameter defines a validation object with the logic to apply when a value is entered for the field, via the metadata, upload, explicit or update resource methods, or via the Media Library. The boolean validations also allow for combinations of more than one rule. The following validations are supported:

greater_than
less_than
strlen
and

greater_than validation

Relevant for integer and date types:

{
    "type": "greater_than",
    "value": <value_by_type>,
    "equals": <boolean>
}

Property	Type	Description
`value`	String	The value for validation.
`equals`	Boolean	Whether to check if greater than or equals. Default: `false`

For example:

"validation":{ 
    "type": "greater_than",
    "value": "2018-10-15",
    "equals": true
}

less_than validation

Relevant for integer and date types:

{
    "type": "less_than",
    "value": <value_by_type>,
    "equals": <boolean>
}

Property	Type	Description
`value`	String	The value for validation.
`equals`	Boolean	Whether to check if less than or equals. Default: `false`

For example:

"validation":{ 
    "type": "less_than",
    "value": 50,
    "equals": true
}

strlen validation

Relevant only for string types:

{
    "type": "strlen",
    "min": <positive integer>,
    "max": <positive integer>
}

Property	Type	Description
`min`	Integer	The minimum string length. Default: `0`
`max`	Integer	The maximum string length. Default: `1024`

Note

Either min or max must be given, supplying both is optional.

For example:

"validation":{ 
    "type": "strlen",
    "min": 5,
    "max": 20
}

and validation

Relevant for all field types. Allows you to include more than one validation rule to be evaluated:

{
    "type": "and",
    "rules": [ <validation_object>, <validation_object>, … ]
}

Property	Type	Description
`validation_object`	Object	One of the other validations above: `greater_than`, `less_than` or `strlen`

For example:

"validation":{
    "type":  "and"
    "rules": [{ 
        "type": "greater_than",
        "value": 10,
        "equals": true
    },
    { 
        "type": "less_than",
        "value": 50,
        "equals": true
    }]
}

Datasource values

The datasource parameter is only relevant for fields where the selected values must come from a predefined list of values (enum or set type fields). The parameter contains only the values property, in order to be future compatible with different kinds of datasource types.

{
    "values": [ <datasource_entry>, <datasource_entry>, … ]
}

Each datasource_entry defines a single possible value for the field:

{
    "external_id": <string>,
    "value": <string>,
    "state": “active” | “inactive”
}

Property	Type	Description
`external_id`	String	(optional) A unique immutable identification string for the datasource entry, (required if the value is referenced by the default_value field). Default: auto-generated by Cloudinary
`value`	String	(mandatory) The value for this datasource.
`state`	String	(read only) Only given as part of a response - ignored on requests. It is immutable unless changed via DELETE of a datasource entry.

For example:

"datasource": {
    "values": [{
        "external_id": "color1", 
        "value": "red"
    },
    {   
        "external_id": "color2", 
        "value": "green"
    },
    {
        "external_id": "color3", 
        "value": "blue"
    },
    {
        "external_id": "color4", 
        "value": "yellow"
    }]
}

Metadata fields API

Enables you to manage the metadata fields for your account.

Method	Description
GET`/metadata_fields`	Get metadata fields
GET`/metadata_fields/:external_id`	Get a metadata field by external id
POST`/metadata_fields`	Create a metadata field
POST`/metadata_fields/:external_id/datasource_restore`	Restore entries in a metadata field datasource
PUT`/metadata_fields/:external_id`	Update a metadata field by external id
PUT`/metadata_fields/:external_id/datasource`	Update a metadata field datasource
DELETE`/metadata_fields/:external_id`	Delete a metadata field by external id
DELETE`/metadata_fields/:external_id/datasource`	Delete entries in a metadata field datasource

Get metadata fields

Returns a list of all metadata field definitions as an array of JSON objects.

Syntax

GET /metadata_fields

Sample response

{
    "Metadata_fields": 
    [
      {
        "type": "date",
        "external_id": "available_date",
        "label": "Available date",
        "mandatory": false,
        "default_value": "2015-01-01",
        "validation": null
      },
      {
        "type": "integer",
        "external_id": "in_stock",
        "label": "In stock",
        "mandatory": false,
        "default_value": 42,
        "validation": null
      }
    ]
}

Get a metadata field by external id

Returns a single metadata field definition.

Syntax

GET /metadata_fields/:external_id

Required parameters

Parameter	Type	Description
`external_id`	String	The ID of the metadata field (included in the endpoint URL when using the REST API).

Examples

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

Sample response

{
    "type": "integer",
    "external_id": "in_stock",
    "label": "In stock",
    "mandatory": false,
    "default_value": 100,
    "validation": null
}

Create a metadata field

Creates a new metadata field definition. Expects a single JSON object which defines the field, according to the structure for the required field type. See Generic structure of a metadata field for details.

Syntax

POST /metadata_fields

Examples

curl \
  -H "Content-Type: application/json" \
  -d '{          
    "external_id": "color_id",
    "label": "Colors",
    "type": "set" ,
    "mandatory": "true",
    "default_value": ["color1","color2"],
    "datasource": {
      "values": [
        {"external_id": "color1", "value": "red"},
        {"external_id": "color2", "value": "green"},
        {"external_id": "color3", "value": "blue"},
        {"external_id": "color4", "value": "yellow"}
      ]
    }
  }' \  
  -X POST \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/metadata_fields

Restore entries in a metadata field datasource

Restores (unblocks) any previously deleted datasource entries for a specified metadata field definition. Sets the state of the entries to active.

Syntax

POST /metadata_fields/:external_id/datasource_restore

Required parameters

Parameter	Type	Description
`external_id`	String	The ID of the metadata field (included in the endpoint URL when using the REST API).
`external_ids`	String[]	An array of IDs of datasource entries to restore (unblock).

Examples

Restore (unblock) the datasource entry with external_id 'color1' from the metadata field with external_id 'color_id':

curl \
  -d "external_ids[]=color1" \
  -X POST \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/metadata_fields/color_id/datasource_restore

Update a metadata field by external id

Updates a metadata field definition (partially, no need to pass the entire object) passed as JSON data. See Generic structure of a metadata field for details.

Syntax

PUT /metadata_fields/:external_id

Required parameters

Parameter	Type	Description
`external_id`	String	The ID of the metadata field (included in the endpoint URL when using the REST API).

Examples

curl \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Now in stock",
    "mandatory": true
  }' \
  -X PUT \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/metadata_fields/in_stock

Sample response

{
    "type": "integer",
    "external_id": "in_stock",
    "label": "Now in stock",
    "mandatory": true,
    "default_value": 100,
    "validation": null
}

Update a metadata field datasource

Updates the datasource of a supported field type (currently only enum and set), passed as JSON data. The update is partial: datasource entries with an existing external_id will be updated and entries with new external_id’s (or without external_id’s) will be appended.

Syntax

PUT /metadata_fields/:external_id/datasource

Required parameters

Parameter	Type	Description
`external_id`	String	The ID of the metadata field (included in the endpoint URL when using the REST API).

Examples

curl \
  -H "Content-Type: application/json" \
  -d '{  
    "values":[{  
      "external_id":"color1",
      "value":"orange"
    },
    {  
      "external_id":"color2",
      "value":"black"
    }]
  }' \
  -X PUT \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/metadata_fields/color_id/datasource

Delete a metadata field by external id

Deletes a metadata field definition. The field should no longer be considered a valid candidate for all other endpoints (it will not show up in the list of fields, etc).

Syntax

DELETE /metadata_fields/:external_id

Required parameters

Parameter	Type	Description
`external_id`	String	The ID of the metadata field (included in the endpoint URL when using the REST API).

Examples

curl 
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/metadata_fields/in_stock

Delete entries in a metadata field datasource

Deletes (blocks) the datasource entries for a specified metadata field definition. Sets the state of the entries to inactive. This is a soft delete, the entries still exist under the hood and can be activated again with the restore datasource entries method.

Syntax

DELETE /metadata_fields/:external_id/datasource

Required parameters

Parameter	Type	Description
`external_id`	String	The ID of the metadata field (included in the endpoint URL when using the REST API).
`external_ids`	String[]	An array of IDs of datasource entries to delete.

Examples

Delete (block) the datasource entry with external_id 'color1' from the metadata field with external_id 'color_id':

curl \
  -d "external_ids[]=color1" \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/metadata_fields/color_id/datasource

Folders

Enables you to manage folders for your account.

Methods	Description
GET`/folders`	Get root folders
GET`/folders/:root_folder`	Get subfolders
POST`/folders/:folder`	Create a folder
DELETE`/folders/:folder`	Delete a folder

Get root folders

Lists all the root folders. Limited to 2000 results.

Syntax

GET /folders

Ruby PHP Python Node.js Java .Net All

Ruby:

Cloudinary::Api.root_folders

PHP:

$api->root_folders();

Python:

cloudinary.api.root_folders()

Node.js:

cloudinary.v2.api.root_folders(callback);

Java:

api.rootFolders(ObjectUtils.emptyMap());

.Net:

cloudinary.RootFolders();

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 path of all the subfolders of a given folder. Limited to 2000 results.

Syntax

GET /folders/:folder

Ruby PHP Python Node.js Java .Net All

Ruby:

Cloudinary::Api.subfolders(folder)

PHP:

$api->subfolders($folder);

Python:

cloudinary.api.subfolders(folder)

Node.js:

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

Java:

api.subfolders(String folder);

.Net:

cloudinary.SubFolders(folder);

Required parameters

Parameter	Type	Description
folder	String	The full path of the folder to return subfolders of.

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 cURL All

Ruby:

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

PHP:

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

Python:

cloudinary.api.subfolders("product/shoe")

Node.js:

cloudinary.v2.api.sub_folders("product/shoe", function(error, result){console.log(result);});

Java:

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

.Net:

cloudinary.SubFolders("product/shoe");

cURL:

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

Sample response

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

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

Create folder

Create a new empty folder.

Syntax

POST /folders/:folder

Ruby PHP Python Node.js Java .Net All

Ruby:

Cloudinary::Api.create_folder(folder)

PHP:

$api->create_folder($folder);

Python:

cloudinary.api.create_folder(folder)

Node.js:

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

Java:

api.createFolder(String folder);

.Net:

cloudinary.CreateFolder(folder);

Required parameters

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

Examples

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

Ruby PHP Python Node.js Java .Net cURL All

Ruby:

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

PHP:

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

Python:

cloudinary.api.create_folder("product/test")

Node.js:

cloudinary.v2.api.create_folder("product/test", function(error, result){console.log(result);});

Java:

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

.Net:

cloudinary.CreateFolder("product/test");

cURL:

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

Sample response

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

Delete folder

Deletes an empty folder.

Note

Use the Delete resources method to delete the assets within a folder.

Syntax

DELETE /folders/:folder

Ruby PHP Python Node.js Java .Net All

Ruby:

Cloudinary::Api.delete_folder(folder)

PHP:

$api->delete_folder($folder);

Python:

cloudinary.api.delete_folder(folder)

Node.js:

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

Java:

api.deleteFolder(String folder);

.Net:

cloudinary.DeleteFolder(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 cURL All

Ruby:

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

PHP:

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

Python:

cloudinary.api.delete_folder("product/test")

Node.js:

cloudinary.v2.api.delete_folder("product/test", function(error, result){console.log(result);});

Java:

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

.Net:

cloudinary.DeleteFolder("product/test");

cURL:

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

Sample response

{
    "deleted": [
        "test"
    ]
}

Adaptive streaming profiles

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.

Methods	Description
GET`/streaming_profiles`	Get adaptive streaming profiles
GET`/streaming_profiles/:name`	Get details of a streaming profile
POST`/streaming_profiles`	Create a streaming profile
PUT`/streaming_profiles/:name`	Update an existing streaming profile
DELETE`/streaming_profiles/:name`	Delete or revert 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 All

Ruby:

Cloudinary::Api.list_streaming_profiles

PHP:

$api->list_streaming_profiles();

Python:

cloudinary.api.list_streaming_profiles()

Node.js:

cloudinary.v2.api.list_streaming_profiles(callback);

Java:

api.listStreamingProfiles();

.Net:

Not supported by this SDK

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 All

Ruby:

Cloudinary::Api.get_streaming_profile(name)

PHP:

$api->get_streaming_profile($name);

Python:

cloudinary.api.get_streaming_profile(name)

Node.js:

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

Java:

api.getStreamingProfile(String name);

.Net:

Not supported by this SDK

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 cURL All

Ruby:

Cloudinary::Api.get_streaming_profile('custom_square')

PHP:

$api->get_streaming_profile("custom_square");

Python:

cloudinary.api.get_streaming_profile("custom_square")

Node.js:

cloudinary.v2.api.get_streaming_profile('custom_square', function(error, result){console.log(result);});

Java:

api.getStreamingProfile("custom_square");

.Net:

Not supported by this SDK

cURL:

curl \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/streaming_profiles/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 All

Ruby:

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

PHP:

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

Python:

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

Node.js:

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

Java:

:
api.createStreamingProfile(String name, Map options);

.Net:

Not supported by this SDK

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 cURL All

Ruby:

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:

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

Python:

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.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" }}] },
  function(error, result){console.log(result);});

Java:

:
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:

Not supported by this SDK

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

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 cURL All

Ruby:

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:

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

Python:

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.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" }}] },
  function(error, result){console.log(result);});

Java:

:
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:

Not supported by this SDK

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

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 All

Ruby:

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

PHP:

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

Python:

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

Node.js:

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

Java:

:
api.updateStreamingProfile(String name, Map options);

.Net:

Not supported by this SDK

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 cURL All

Ruby:

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:

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

Python:

cloudinary.api.create_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.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" }}]},
  function(error, result){console.log(result);});

Java:

:

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:

Not supported by this SDK

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

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 All

Ruby:

Cloudinary::Api.delete_streaming_profile(name)

PHP:

$api->delete_streaming_profile($name);

Python:

cloudinary.api.delete_streaming_profile(name)

Node.js:

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

Java:

api.deleteStreamingProfile(String name);

.Net:

Not supported by this SDK

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 cURL All

Ruby:

Cloudinary::Api.delete_streaming_profile('custom_square')

PHP:

$api->delete_streaming_profile("custom_square");

Python:

cloudinary.api.delete_streaming_profile("custom_square")

Node.js:

cloudinary.v2.api.delete_streaming_profile('custom_square', 
  function(error, result){console.log(result);});

Java:

api.deleteStreamingProfile("custom_square");

.Net:

Not supported by this SDK

cURL:

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

Sample response

{ "message": "deleted" }

Usage

Enables you to get a report on the status of your Cloudinary account usage details, including storage, credits, bandwidth, requests, number of resources, and add-on usage. Note that numbers are updated periodically.

Methods	Description
GET `/usage`	Get account usage details

Get account usage details

Syntax

GET /usage

Ruby PHP Python Node.js Java .Net All

Ruby:

Cloudinary::Api.usage

PHP:

$api->usage();

Python:

cloudinary.api.usage()

Node.js:

cloudinary.v2.api.usage(callback);

Java:

api.usage(ObjectUtils.emptyMap());

.Net:

cloudinary.GetUsage();

Sample response

The response contains an object with detailed usage information.

{
  "plan": "Basic",
  "last_updated": "2019-09-09",
  "transformations": {"usage": 1218018, "credits_usage": 1.22}, 
  "objects": {"usage": 1217216}, 
  "bandwidth": {"usage": 268903064875, "credits_usage": 0.24}, 
  "storage": {"usage": 10298444599, "credits_usage": 0.01}, 
  "credits": {"usage": 1.47}, 
  "requests": 877212,
  "resources": 1239,
  "derived_resources": 10091,
  "url2png": {"usage": 15, "limit": 50},
  "webpurify": {"usage": 28, "limit": 50},
  "aspose": {"usage": 40, "limit": 50},
  "style_transfer": {"usage": 76, "limit": 5000},
  "azure_video_indexer": {"usage": 2340, "limit": 5000}, 
  "object_detection": {"usage": 340, "limit": 500},
  "media_limits": { 
    "image_max_size_bytes": 157286400, 
    "video_max_size_bytes": 3145728000, 
    "raw_max_size_bytes": 2097152000, 
    "image_max_px": 100000000, 
    "asset_max_total_px": 300000000 
  }
}