Documentation and Tutorials
Features overview...

Admin API

Overview

The administrative API allows full control of all uploaded raw files and images, fetched social profile pictures, generated transformations and more. The admin API supports the following actions:

  • Listing all uploaded images and raw files.
  • Receiving details and metadata for uploaded images, including timestamps, format, dimensions, etc.
  • Listing the derived images of uploaded images.
  • Finding all images that share a given tag.
  • Listing all transformations.
  • Listing tags.
  • Receiving transformation details.
  • Creating named transformations.
  • Deleting images, raw files, derived images and transformations.
  • Getting usage report.

Protocol and authentication

The API is accessed using HTTPS to endpoints in the following format:

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

For example, image listing of the 'demo' account:

https://api.cloudinary.com/v1_1/demo/resources/images

You can try the following cURL command after setting the correct cloud name, API key and API secret of your account:

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

Authentication is done using Basic Authentication over secure HTTP. Your Cloudinary API Key and API Secret are used for the authentication.

Request parameters are appended to the URL. The response is in a simple JSON snippet. Like any REST API, read-only requests are sent in HTTP GET while write requests are sent in PUT, POST and DELETE.

Pagination

Listing 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 listing. There is a maximum number of results you can request for a single API call (either 100 or 500 for the various methods).

Resource deletion methods also operate in chunks. A single call can delete up to 1000 resources.

When a listing request has more results to return than max_results or when a deletion request has more resources to delete than 1000, 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 listing or deletion request. This way you can browse through the full lists of uploaded images, transformations and tags of your Cloudinary account or delete the entire set that matches the deletion query.

Error handling

The API returns the status of requests using the HTTP status code:

  • 200 - OK. Successful.
  • 400 - Bad request.
  • 401 - Authorization required.
  • 403 - Not allowed.
  • 404 - Not found
  • 409 - Already exists
  • 420 - Rate limited

The API wrapping of Cloudinary's client libraries report errors by raising applicative exception.

In addition, a JSON with an informative message is returned. For example:

{ "error": { "message": "Resource not found - strange_name" } }

Usage limits

You can use the Admin API quite extensively. We ask for that you keep your ongoing API requests to 500 per hour (12,000 daily) when using our Free plan. Subscribe to our Basic plan onward to increase the limit to 2,000 calls per hour (48,000 daily). If you require more flexible limits, don’t hesitate to contact us.

Note: This limit refers only to Admin API requests (listing & deleting images and resources), and not to image uploads.

For each 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.

Here is how these headers might look like:

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

Framework integration

Our client libraries provide an easy to use wrapper for this URL-based API, utilizing your native programming language of choice. Request building and authentication are done automatically, and the JSON response is parsed and returned.

Usage examples
URL:
GET /resources/image
Ruby:
require 'cloudinary'        
result = Cloudinary::Api.resources
PHP:
require "cloudinary.php";

require "api.php";

$api = new \Cloudinary\Api();

$result = $api->resources();
Python:
import cloudinary.api

result = cloudinary.api.resources()
Node.js:
var cloudinary = require('cloudinary');

cloudinary.api.resources(function(result) { console.log(result) });
Java:
import com.cloudinary.*;

Map config = Cloudinary.asMap(
  "cloud_name", "my_cloud_name",
  "api_key", "my_api_key",
  "api_secret", "my_api_secret");

Cloudinary cloudinary = new Cloudinary(config);
Api api = cloudinary.api();

Map result = api.resources(Cloudinary.emptyMap());
Limit checking
Ruby:
$ result = Cloudinary::Api.resources
$ result.rate_limit_allowed
=> 500
$ result.rate_limit_remaining
=> 499
$ result.rate_limit_reset_at
=> 2012-10-03 10:00:00 +0200
PHP:
php > $result = $api->resources();
php > var_dump($result->rate_limit_allowed);
int(500)
php > var_dump($result->rate_limit_allowed);
int(500)
php > var_dump($result->rate_limit_remaining);
int(499)
php > var_dump($result->rate_limit_reset_at);
int(1349622000)
Python:
>>> result = cloudinary.api.resources()
>>> result.rate_limit_allowed
500
>>>result.rate_limit_remaining
499
>>>result.rate_limit_reset_at
(2012, 10, 7, 15, 0, 0, 0, 1, -1)
Node.js:
> cloudinary.api.resources(
  function(result) {
    console.log(result.rate_limit_allowed,
                result.rate_limit_remaining,
                result.rate_limit_reset_at)
  });
> 500 499 Sun, 07 Oct 2012 15:00:00 GMT
Java:
import com.cloudinary.Api.*;

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

Browse resources

GET /resources/:resource_type(/:type)

List resources

Parameters:
  • prefix - Optional. Find all resources that their public ID starts with the given prefix.
  • public_ids - Optional. (String, comma-separated list of public IDs). List resources with the given public IDs (up to 100). Either images or raw files can be listed separately.
  • max_results - Optional. Max number of resources to return. Default=10. Maximum=500.
  • next_cursor - Optional.
  • start_at - Optional. (Timestamp string). List resources that were created since the given timestamp. Supported if no prefix or public IDs were specified.
  • direction - Optional. (String: "asc", "desc", 1 or -1, default: "desc" by time if no prefix specified, "asc" by public ID otherwise). Control the order of returned resources.
  • tags - Optional (Boolean, default: false). If true, include the list of tag names assigned each resource.
  • context - Optional (Boolean, default: false). If true, include key-value pairs of context associated with each resource.
  • moderations - Optional (Boolean, default: false). If true, include image moderation status of each listed resource.
Result sample:
{
  "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,
      "url": "http://res.cloudinary.com/demo/image/upload/v1333013579/face_center.jpg",
      "secure_url": "https://.../image/upload/v1333013579/face_center.jpg"
    },
    {
      "public_id": "zuck",
      "format": "jpg",
      "resource_type": "image",
      "type": "facebook",
      "created_at": "2012-10-06T17:18:52Z",
      "bytes": 0,
      "url": "http://res.cloudinary.com/demo/image/facebook/zuck.jpg",
      "secure_url": "https://.../image/facebook/zuck.jpg"
    },
  ]
}
List all images
URL:
GET /resources/image
Ruby:
Cloudinary::Api.resources
PHP:
$api->resources();
Python:
cloudinary.api.resources()
Node.js:
cloudinary.api.resources(function(result)  { console.log(result) });
Java:
api.resources(Cloudinary.emptyMap());
List uploaded images:
URL:
GET /resources/image/upload
Ruby:
Cloudinary::Api.resources(:type => :upload)
PHP:
$api->resources(array("type" => "upload"));
Python:
cloudinary.api.resources(type = "upload")
Node.js:
cloudinary.api.resources(function(result){}, { type: 'upload' });
Java:
api.resources(Cloudinary.asMap("type", "upload"));
List all uploaded images with a given prefix
URL:
GET /resources/image/upload/?prefix=sampl
Ruby:
Cloudinary::Api.resources(:type => :upload, :prefix => "sampl")
PHP:
$api->resources(array("type" => "upload", "prefix" => "sampl"));
Python:
cloudinary.api.resources(type = "upload", prefix = "sampl")
Node.js:
cloudinary.api.resources(function(result){},
    { type: 'upload', prefix: 'sampl' });
Java:
api.resources(Cloudinary.asMap("type", "upload", "prefix", "sampl"));
List Facebook images:
URL:
GET /resources/image/facebook
Ruby:
Cloudinary::Api.resources(:type => :facebook)
PHP:
$api->resources(array("type" => "facebook"));
Python:
cloudinary.api.resources(type = "facebook))
Node.js:
cloudinary.api.resources(function(result){}, { type: 'facebook' });
Java:
api.resources(Cloudinary.asMap("type", "facebook"));
List raw uploaded files
URL:
GET /resources/raw
Ruby:
Cloudinary::Api.resources(:resource_type => :raw)
PHP:
$api->resources(array("resource_type" => "raw"));
Python:
cloudinary.api.resources(resource_type = "raw")
Node.js:
cloudinary.api.resources(function(result){}, { resource_type: 'raw' });
Java:
api.resources(Cloudinary.asMap("resource_type", "raw"));
List all uploaded images with the given IDs
URL:
GET /resources/image/upload/?public_ids=user_photo_1,user_photo_2
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.api.resources_by_ids(["user_photo_1", "user_photo_2"], 
  function(result){});
Java:
api.resources_by_ids(Arrays.asList("user_photo_1", "user_photo_2"), 
  Cloudinary.emptyMap());
GET /resources/:resource_type/tags/:tag

List resources by tag

Parameters:
  • max_results - Optional. Max number of resources to return. Default=10. Maximum=500.
  • next_cursor - Optional.
  • direction - Optional. (String: "asc", "desc", 1 or -1, default: "desc" by time). Control the order of returned resources.
  • tags - Optional (Boolean, default: false). If true, include the list of tag names assigned each resource.
  • context - Optional (Boolean, default: false). If true, include key-value pairs of context associated with each resource.
  • moderations - Optional (Boolean, default: false). If true, include image moderation status of each listed resource.
List images by tag
URL:
GET /resources/image/tags/mytag
Ruby:
Cloudinary::Api.resources_by_tag('mytag')
PHP:
$api->resources_by_tag("mytag");
Python:
cloudinary.api.resources_by_tag("mytag")
Node.js:
cloudinary.api.resources_by_tag("mytag", function(result){});
Java:
api.resourcesByTag("mytag", Cloudinary.emptyMap());
List raw files by tag
URL:
GET /resources/raw/tags/mytag
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.api.resources_by_tag("mytag",
    function(result){}, { resource_type: 'raw' });
Java:
api.resourcesByTag("mytag", Cloudinary.asMap("resource_type", "raw"));
GET /resources/:resource_type/moderations/:moderation_type/:status

List resources in moderation queues

Parameters:
  • moderation_type - (String: "manual", "webpurify", "metascan"). Type of image moderation queue to list.
  • status - (String: "pending", "approved", "rejected"). Moderation status of resources.
  • max_results - Optional. Max number of resources to return. Default=10. Maximum=500.
  • next_cursor - Optional.
  • direction - Optional. (String: "asc", "desc", 1 or -1, default: "desc" by time). Control the order of returned resources.
  • tags - Optional (Boolean, default: false). If true, include the list of tag names assigned each resource.
  • context - Optional (Boolean, default: false). If true, include key-value pairs of context associated with each resource.
  • moderations - Optional (Boolean, default: false). If true, include image moderation status of each listed resource.
Result sample:
{
 "resources"=>
  [{
    "public_id": "q7vcvrfjm9mj4bfp3qc8",
    "format": "jpg",
    "version": 1393794403,
    "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/v1393794403/q7vcvrfjm9mj4bfp3qc8.jpg",
    "secure_url": 
     "https://res.cloudinary.com/demo/image/upload/v1393794403/q7vcvrfjm9mj4bfp3qc8.jpg"
   },
   {
    "public_id": "zp4fgdbabhlwwa7bxu84",
    "format": "jpg",
    "version": 1393794399,
    "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/v1393794399/zp4fgdbabhlwwa7bxu84.jpg",
    "secure_url": 
     "https://res.cloudinary.com/demo/image/upload/v1393794399/zp4fgdbabhlwwa7bxu84.jpg"
   }
 ]
}
List images pending manual moderation
URL:
GET /resources/image/moderations/manual/pending
Ruby:
Cloudinary::Api.resources_by_moderation("manual", "pending")
PHP:
$api = new \Cloudinary\Api();
$api->resources_by_moderation("manual", "pending");
Python:
cloudinary.api.resources_by_moderation("manual", "pending")
Node.js:
cloudinary.api.resources_by_moderation('manual', 'pending', 
  function(result)  { console.log(result) });
Java:
cloudinary.api().resourcesByModeration("manual", "pending", 
  Cloudinary.emptyMap());
List images automatically approved by the WebPurify add-on
URL:
GET /resources/image/moderations/webpurify/approved
Ruby:
Cloudinary::Api.resources_by_moderation("webpurify", "approved")
PHP:
$api = new \Cloudinary\Api();
$api->resources_by_moderation("webpurify", "approved");
Python:
cloudinary.api.resources_by_moderation("webpurify", "approved")
Node.js:
cloudinary.api.resources_by_moderation('webpurify', 'approved', 
  function(result)  { console.log(result) });
Java:
cloudinary.api().resourcesByModeration("webpurify", "approved", 
  Cloudinary.emptyMap());
GET /tags/:resource_type

List tags

Parameters:
  • prefix - Optional. Find all tags that start with the given prefix.
  • max_results - Optional. Max number of tags to return. Default=10. Maximum=500.
  • next_cursor - Optional.
Result sample:
{
  "tags": [
    "arrow_animation",
    "logo"
  ]
}
List tags of images
URL:
GET /tags/image
Ruby:
Cloudinary::Api.tags
PHP:
$api->tags();
Python:
cloudinary.api.tags()
Node.js:
cloudinary.api.tags(function(result){});
Java:
api.tags(Cloudinary.emptyMap());
List all tags with a given prefix
URL:
GET /tags/image/?prefix=myta
Ruby:
Cloudinary::Api.tags(:prefix => "myta")
PHP:
$api->tags(array("prefix" => "myta"));
Python:
cloudinary.api.tags(prefix = "myta")
Node.js:
cloudinary.api.tags(function(result){}, { prefix: 'myta' });
Java:
api.tags(Cloudinary.asMap("prefix", "myta"));
GET /resources/:resource_type/:type/:public_id

Details of a single resource

Parameters:
  • colors - Optional (Boolean, default: false). If true, include color information: predominant colors and histogram of 32 leading colors.
  • image_metadata - Optional (Boolean, default: false). If true, include IPTC, XMP and detailed Exif metadata of the uploaded photo.
  • exif - Optional (Boolean, default: false). If true, include image metadata (e.g., camera details). Deprecated. Please use image_metadata instead.
  • faces - Optional (Boolean, default: false). If true, include a list of coordinates of detected faces.
  • pages - Optional (Boolean, default: false). If true, report the number of pages in multi-page documents (e.g., PDF)
  • phash - Optional (Boolean, default: false). If true, include the perceptual hash (pHash) of the uploaded photo for image similarity detection.
  • coordinates - Optional (Boolean, default: false). If true, include previously specified custom cropping coordinates and faces coordinates.
  • max_results - Optional. Max number of derived images to include. Default=10. Maximum=100.
Result sample:
{
  "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,
  "url": "http://res.cloudinary.com/demo/image/upload/v1312461204/sample.jpg",
  "secure_url": "https://.../image/upload/v1312461204/sample.jpg",
  "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
      ]
    ]
  },
  
  "exif": {
    "ApertureValue": "4281/1441",
    "ColorSpace": "1",
    "ComponentsConfiguration": "1, 2, 3, 0",
    "Compression": "6",
    "DateTime": "2010:12:27 11:17:34",
    "DateTimeDigitized": "2010:12:27 11:17:34",
    "DateTimeOriginal": "2010:12:27 11:17:34",
    "ExifImageLength": "1936",
    "ExifImageWidth": "2592",
    "ExifOffset": "204",
    "ExifVersion": "48, 50, 50, 49",
    "ExposureMode": "0",
    "ExposureProgram": "2",
    "ExposureTime": "1/4309",
    "Flash": "24",
    "FlashPixVersion": "48, 49, 48, 48",
    "FNumber": "14/5",
    "FocalLength": "77/20",
    "GPSAltitude": "20723/924",
    "GPSAltitudeRef": "0",
    "GPSImgDirection": "42155/344",
    "GPSImgDirectionRef": "T",
    "GPSInfo": "574",
    "GPSLatitude": "21/1, 768/100, 0/1",
    "GPSLatitudeRef": "N",
    "GPSLongitude": "86/1, 4500/100, 0/1",
    "GPSLongitudeRef": "W",
    "GPSTimeStamp": "17/1, 17/1, 3326/100",
    "ISOSpeedRatings": "80",
    "JPEGInterchangeFormat": "870",
    "JPEGInterchangeFormatLength": "9932",
    "Make": "Apple",
    "MeteringMode": "1",
    "Model": "iPhone 4",
    "Orientation": "6",
    "ResolutionUnit": "2",
    "SceneCaptureType": "0",
    "SensingMethod": "2",
    "Sharpness": "2",
    "ShutterSpeedValue": "4781/396",
    "Software": "4.2.1",
    "SubjectArea": "1295, 967, 699, 696",
    "WhiteBalance": "0",
    "XResolution": "72/1",
    "YCbCrPositioning": "1",
    "YResolution": "72/1"
  },
               
}
Uploaded image details
URL:
GET /resources/image/upload/sample
Ruby:
Cloudinary::Api.resource('sample')
PHP:
$api->resource("sample");
Python:
cloudinary.api.resource("sample")
Node.js:
cloudinary.api.resource('sample', 
    function(result)  { console.log(result) });
Java:
api.resource("sample", Cloudinary.emptyMap());
Faces, colors and Exif image details
URL:
GET /resources/image/upload/sample?faces=1&colors=1&exif=1
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.api.resource('sample', 
    function(result)  { console.log(result) },
    { faces: true, colors: true, exif: true });
Java:
api.resource("sample", Cloudinary.asMap("faces", true, 
    "colors", true, "exif", true));
Facebook picture details
URL:
GET /resources/image/facebook/zuck
Ruby:
Cloudinary::Api.resource('zuck', :type => :facebook)
PHP:
$api->resource("zuck", array("type" => "facebook"));
Python:
cloudinary.api.resource("zuck", type = "facebook")
Node.js:
cloudinary.api.resource('zuck', 
    function(result){}, { type: 'facebook' });
Java:
api.resource("zuck", Cloudinary.asMap("type", "facebook"));
Uploaded raw file details
URL:
GET /resources/raw/upload/rwkaliebnufp3bxyrvyo.txt
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.api.resource('rwkaliebnufp3bxyrvyo.txt', 
    function(result){}, { resource_type: 'raw' });
Java:
api.resource("rwkaliebnufp3bxyrvyo.txt", 
    Cloudinary.asMap("resource_type", "raw"));

Update resources

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

Update details of an existing resource

Parameters:
  • public_id - The public ID of a single image or a raw file that was uploaded to Cloudinary.
  • tags - (Optional). A comma-separated list of tag names to assign to the uploaded image for later group reference.
  • context - (Optional). A pipe separated list of key-value pairs of general textual context metadata to attach to an uploaded resource. The context values of uploaded files are available for fetching using the Admin API. For example: "alt=My image|caption=Profile Photo".
  • face_coordinates - (Optional). 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 '|'. For example: "10,20,150,130|213,345,82,61".
  • custom_coordinates - (Optional). 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".
  • moderation_status - (Optional. String: "approved", "rejected"). Manually set image moderation status or override previously automatically moderated images by approving or rejecting.
  • auto_tagging (0.0 to 1.0 Decimal number) - (Optional). Whether to assign tags to an image according to detected scene categories with confidence score higher than the given value.
  • detection - (Optional). Set to 'rekognition_face' to automatically extract advanced face attributes of photos using the ReKognition Detect Face Attributes add-on.
  • raw_convert - (Optional). Set to 'aspose' to automatically convert Office documents to PDF files and other image formats using the Aspose Document Conversion add-on.
  • categorization - (Optional). Set to 'rekognition_scene' to automatically detect scene categories of photos using the ReKognition Scene Categorization add-on.
Update tags and moderation status of an uploaded image
URL:
POST /resources/image/upload/image1
Ruby:
Cloudinary::Api.update("image1", 
  :tags => "important",
  :moderation_status => "approved")
PHP:
$api = new \Cloudinary\Api();
$api->update("image1", 
  array("tags" => "important", "moderation_status" => "approved"));
Python:
cloudinary.api.update("image1",
  tags = "important",
  moderation_status = "approved")
Node.js:
cloudinary.api.update("image1", 
  function(result) { console.log(result); }, 
  { tags: "important", moderation_status: "approved" });
Java:
cloudinary.api().update("image1", 
  Cloudinary.asMap("tags", "important", 
    "moderation_status", "approved"));

Delete resources

DELETE /resources/:resource_type/:type

Delete resources by public ID or prefix

Parameters:
  • public_ids - Delete all resources with the given public IDs (comma-separated)
  • prefix - Delete all resources that their public ID starts with the given prefix.
  • all - Optional (Boolean, default: false). Delete all resources.
  • keep_original - Optional (Boolean, default: false). If true, delete only the derived images of the matching resources.
Result sample:
{
  "deleted": {
    "image1": "deleted",
    "image2": "deleted"
  },
  "partial": false
}
Delete uploaded images by public IDs
URL:
DELETE /resources/image/upload?public_ids=image1,image2
Ruby:
Cloudinary::Api.delete_resources(['image1', 'image2'])
PHP:
$api->delete_resources(array("image1", "image2"));
Python:
cloudinary.api.delete_resources(["image1", "image2"])
Node.js:
cloudinary.api.delete_resources(['image1', 'image2'],
    function(result){});
Java:
api.deleteResources(Arrays.asList("image1", "image2"), 
    Cloudinary.emptyMap());
Delete Facebook pictures by public IDs
URL:
DELETE /resources/image/facebook?public_ids=zuck
Ruby:
Cloudinary::Api.delete_resources(['zuck'], :type => :facebook)
PHP:
$api->delete_resources(array("zuck"), array("type" => "facebook"));
Python:
cloudinary.api.delete_resources(["zuck"], type = "facebook")
Node.js:
cloudinary.api.delete_resources(['zuck'],
    function(result){}, { type: 'facebook' });
Java:
api.deleteResources(Arrays.asList("zuck"), 
    Cloudinary.asMap("type", "facebook"));
Delete uploaded images by prefix
URL:
DELETE /resources/image/upload?prefix=sunday
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.api.delete_resources_by_prefix('sunday', function(result){});
Java:
api.deleteResourcesByPrefix("sunday", Cloudinary.emptyMap());
Delete derived images only
URL:
DELETE /resources/image/upload?public_ids=image1,image2&keep_original=1
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.api.delete_resources(['image1', 'image2'],
    function(result){}, { keep_original: true });
Java:
api.deleteResources(Arrays.asList("image1", "image2"), 
    Cloudinary.asMap("keep_original", true));
Delete all Facebook pictures
URL:
DELETE /resources/image/facebook?all=true
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.api.delete_all_resources(function(result){}, { type: 'facebook' });
Java:
api.deleteAllResources(Cloudinary.asMap("type", "facebook"));
DELETE /resources/:resource_type/tags/:tag

Delete resources by tags

Parameters:
  • tag - Delete all resources with the given tag name.
  • keep_original - Optional (Boolean, default: false). If true, delete only the derived images of the matching resources.
Result sample:
{
  "deleted": {
    "image1": "deleted",
    "image2": "deleted"
  },
  "partial": false
}
Delete images by tag name
URL:
DELETE /resources/image/tags/mytag
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.api.delete_resources_by_tag('mytag',
    function(result){});
Java:
api.deleteResourcesByTag("mytag", Cloudinary.emptyMap());
DELETE /derived_resources

Delete derived resources

Parameters:
  • derived_resource_ids - Delete all derived resources with the given IDs (comma-separated)
Result sample:
{
  "deleted": {
    "cb4eaaf650": "deleted",
    "a7b2a2756a": "deleted"
  }
}
Delete transformed images by IDs
URL:
DELETE /derived_resources?derived_resource_ids=cb4eaaf650,a7b2a2756a
Ruby:
Cloudinary::Api.delete_derived_resources(['cb4eaaf6503',
    'a7b2a2756ab'])
PHP:
$api->delete_derived_resources(array("cb4eaaf6503", "a7b2a2756ab"));
Python:
cloudinary.api.delete_derived_resources(["cb4eaaf6503", "a7b2a2756ab"])
Node.js:
cloudinary.api.delete_derived_resources(['cb4eaaf6503', 'a7b2a2756ab'],
    function(result){});
Java:
api.deleteDerivedResources(Arrays.asList("cb4eaaf6503", "a7b2a2756ab"), 
    Cloudinary.emptyMap());

Manage transformations

GET /transformations

List transformations

Parameters:
  • max_results - Optional. Max number of transformations to return. Default=10. Maximum=500.
  • next_cursor - Optional.
Result sample:
{
  "transformations": [
    {
      "name": "w_120,h_100,c_fill",
      "allowed_for_strict": false,
      "used": false
    },
    {
      "name": "w_110,h_100,c_fill",
      "allowed_for_strict": false,
      "used": false
    },
    {
      "name": "c_thumb,g_face,h_100,w_80",
      "allowed_for_strict": false,
      "used": true
    },
    {
      "name": "c_fill,h_75,w_75/jpg",
      "allowed_for_strict": false,
      "used": true
    }
  ],
  "next_cursor": "8edbc61040178db60b0973ca9494bf3a"
}
List all image transformations
URL:
GET /transformations
Ruby:
Cloudinary::Api.transformations
PHP:
$api->transformations();
Python:
cloudinary.api.transformations()
Node.js:
cloudinary.api.transformations(function(result){console.log(result)});
Java:
api.transformations(Cloudinary.emptyMap());
GET /transformations/:transformation

Details of a single transformation

Parameters:
  • max_results - Optional. Max number of derived resources to return. Default=10. Maximum=100.
Result sample:
{
  "name": "w_150,h_100,c_fill",
  "allowed_for_strict": false,
  "used": true,
  "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"
    }
  ]
}
Transformation details by name
URL:
GET /transformations/w_150,h_100,c_fill
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.api.transformation('w_150,h_100,c_fill', 
    function(result) { console.log(result) });
Java:
api.transformation("w_150,h_100,c_fill", 
    Cloudinary.emptyMap());
Transformation details by parameters
URL:
GET /transformations/c_fill,h_100,w_150
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.api.transformation({width: 150, height: 100, crop: 'fill'}, 
    function(result) { console.log(result) });
Java:
api.transformation(new Transformation().width(150).height(100).
    crop("fill").generate(), Cloudinary.emptyMap());
DELETE /transformations/:transformation

Delete transformation

Result sample:
{
 "message": "deleted" 
}
Delete transformation name
URL:
DELETE /transformations/w_150,h_100,c_fill
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.api.delete_transformation('w_150,h_100,c_fill', 
    function(result) { console.log(result) });
Java:
api.deleteTransformation("w_150,h_100,c_fill", 
    Cloudinary.emptyMap());
Delete transformation by parameters
URL:
DELETE /transformations/c_fill,h_100,w_150
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.api.delete_transformation(
    {width: 150, height: 100, crop: 'fill'},
    function(result) { console.log(result) });
Java:
api.deleteTransformation(new Transformation().width(150).height(100).
    crop("fill").generate(), Cloudinary.emptyMap());
PUT /transformations/:transformation

Update transformation

Parameters:
  • allowed_for_strict - Boolean. Whether this transformation is allowed when Strict Transformations are enabled.
  • unsafe_update - Optional. Allows updating an existing named transformation without updating all associated derived images.
Result sample:
{
 "message": "updated" 
}
Allow transformation by name
URL:
PUT /transformations/w_150,h_100,c_fill?allowed_for_strict=true
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.api.update_transformation('w_150,h_100,c_fill',
    { allowed_for_strict: true },
    function(result) { console.log(result) });
Java:
api.updateTransformation("w_150,h_100,c_fill", 
    Cloudinary.asMap("allowed_for_strict", true), Cloudinary.emptyMap());
Disallow transformation by parameters
URL:
PUT /transformations/c_fill,h_100,w_150?allowed_for_strict=false
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.api.update_transformation(
    { width: 150, height: 100, crop: 'fill' },
    { allowed_for_strict: false },
    function(result) { console.log(result) });
Java:
api.updateTransformation(new Transformation().width(150).height(100).
    crop("fill").generate(), Cloudinary.asMap("allowed_for_strict", false), 
    Cloudinary.emptyMap());
Update a named transformation
URL:
PUT /transformations/my_named?unsafe_update=c_scale,w_103
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.api.update_transformation("my_named", 
    { crop: 'scale', width: 103 },
    function(result) { console.log(result) });
Java:
api.updateTransformation("my_named", 
    Cloudinary.asMap("unsafe_update", 
    new Transformation().crop("scale").width(103).generate()), 
        Cloudinary.emptyMap());
POST /transformations/:name

Create named transformation

Parameters:
  • transformation - Strinct representation of transformation parameters.
Result sample:
{
 "message": "created" 
}
Create named transformation by string
URL:
POST /transformations/small_fill?transformation=w_150,h_100,c_fill
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.api.create_transformation('small_fill',
    'w_150,h_100,c_fill',
    function(result) { console.log(result) });
Java:
api.createTransformation("small_fill", "w_150,h_100,c_fill", 
    Cloudinary.emptyMap());
Create named transformation by parameters
URL:
POST /transformations/small_fill2?transformation=c_fill,h_100,w_150
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.api.create_transformation('small_fill2',
    { width: 150, height: 100, crop: 'fill' },
    function(result) { console.log(result) });
Java:
api.createTransformation("small_fill2", 
    new Transformation().width(150).height(100).crop("fill").generate(), 
    Cloudinary.emptyMap());

Usage report

GET /usage

Get account usage details

Including storage, bandwidth, requests and number of images. Note that numbers are updated periodically.
Result sample:
{
 "plan": "Basic", 
 "last_updated": "2013-02-04", 
 "objects": { "usage": 11330, "limit": 1000000, "used_percent": 1.13 }, 
 "bandwidth": { "usage": 9844516305, "limit": 41943040000, "used_percent": 23.47 }, 
 "storage": { "usage": 704363507, "limit": 10485760000, "used_percent": 6.72 }, 
 "requests": 877212,
 "resources": 1239, 
 "derived_resources": 10091
}
Get usage details
URL:
GET /usage
Ruby:
Cloudinary::Api.usage
PHP:
$api->usage();
Python:
cloudinary.api.usage()
Node.js:
cloudinary.api.usage(function(result){console.log(result)});
Java:
api.usage(Cloudinary.emptyMap());