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 following are just a sub-set of actions that you can achieve with the Admin API:
- Interface with the Cloudinary Admin API
- Listing uploaded resources and receiving details and metadata for the files
- Listing the derived images of an uploaded image
- Listing tags
- Update the details of an existing resource
- Deleting resources, derived resources and transformations
- Listing transformations
- Receiving transformation details
- Creating named transformations
- Restoring deleted files from backup
- Listing upload mappings
- Creating, updating, and deleting upload mappings
- Updating access mode
- Listing upload presets
- Creating, updating and deleting upload presets
- Listing root folders and subfolders
- Manage adaptive bitrate streaming profiles
- Getting usage reports
- Pinging Cloudinary's API.
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/image
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. 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 resources, 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.
require 'cloudinary' result = Cloudinary::Api.resources
require "cloudinary.php"; require "api.php"; $api = new \Cloudinary\Api(); $result = $api->resources();
import cloudinary.api result = cloudinary.api.resources()
var cloudinary = require('cloudinary'); cloudinary.api.resources(function(result) { console.log(result) });
import com.cloudinary.*; import com.cloudinary.utils.*; Map config = ObjectUtils.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(ObjectUtils.emptyMap());
/resources/image
$ 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 > $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)
>>> 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)
> 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
import com.cloudinary.Api.*; 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()); => 2012-10-03 10:00:00 +0200
Browse resources
Use the resources methods to: list all uploaded resources, list resources by tag, list resources in moderation queues, list tags or list the details of a single resource.
List resources
- prefix - Optional. (String). Find all resources with a public ID that starts with the given prefix. The resources are sorted by public ID in the response.
- public_ids - Optional. (String, comma-separated list of public IDs). List resources with the given public IDs (up to 100).
- max_results - Optional. (Integer, default=10. maximum=500). Max number of resources to return.
- next_cursor - Optional. When a listing 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 listing request.
- 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/Integer, "asc" (or 1), "desc" (or -1), default: "desc" according to the created_at date). Control the order of returned resources. Note that if a prefix is specified, this parameter is ignored and the results are sorted by public ID.
- 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.
{ "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" }, ] }
Cloudinary::Api.resources
$api->resources();
cloudinary.api.resources()
cloudinary.api.resources(function(result) { console.log(result) });
api.resources(ObjectUtils.emptyMap());
/resources/image
Cloudinary::Api.resources(:type => :upload)
$api->resources(array("type" => "upload"));
cloudinary.api.resources(type = "upload")
cloudinary.api.resources(function(result){}, { type: 'upload' });
api.resources(ObjectUtils.asMap("type", "upload"));
/resources/image/upload
Cloudinary::Api.resources(:type => :upload, :prefix => "sampl")
$api->resources(array("type" => "upload", "prefix" => "sampl"));
cloudinary.api.resources(type = "upload", prefix = "sampl")
cloudinary.api.resources(function(result){}, { type: 'upload', prefix: 'sampl' });
api.resources(ObjectUtils.asMap("type", "upload", "prefix", "sampl"));
/resources/image/upload/?prefix=sampl
Cloudinary::Api.resources(:type => :facebook)
$api->resources(array("type" => "facebook"));
cloudinary.api.resources(type = "facebook"))
cloudinary.api.resources(function(result){}, { type: 'facebook' });
api.resources(ObjectUtils.asMap("type", "facebook"));
/resources/image/facebook
Cloudinary::Api.resources(:resource_type => :raw)
$api->resources(array("resource_type" => "raw"));
cloudinary.api.resources(resource_type = "raw")
cloudinary.api.resources(function(result){}, { resource_type: 'raw' });
api.resources(ObjectUtils.asMap("resource_type", "raw"));
/resources/raw
resources_by_ids Cloudinary::Api.resources_by_ids(["user_photo_1", "user_photo_2"])
$api->resources_by_ids(array("user_photo_1", "user_photo_2"));
cloudinary.api.resources_by_ids(["user_photo_1", "user_photo_2"])
cloudinary.api.resources_by_ids(["user_photo_1", "user_photo_2"], function(result){});
api.resources_by_ids(Arrays.asList("user_photo_1", "user_photo_2"), ObjectUtils.emptyMap());
/resources/image/upload/?public_ids[]=user_photo_1&public_ids[]=user_photo_2
List resources by tag
Retrieve a list of resources with a specified tag. This method does not return deleted resources even if they have been backed up.
- max_results - Optional. (Integer, default=10. maximum=500). Max number of resources to return.
- next_cursor - Optional. When a listing 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 listing request.
- direction - Optional. (String/Integer, "asc" (or 1), "desc" (or -1), default: "desc" by creation date). 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.
Cloudinary::Api.resources_by_tag('mytag')
$api->resources_by_tag("mytag");
cloudinary.api.resources_by_tag("mytag")
cloudinary.api.resources_by_tag("mytag", function(result){});
api.resourcesByTag("mytag", ObjectUtils.emptyMap());
/resources/image/tags/mytag
Cloudinary::Api.resources_by_tag('mytag', :resource_type => :raw)
$api->resources_by_tag("mytag", array("resource_type" => "raw"));
cloudinary.api.resources_by_tag("mytag", resource_type = "raw")
cloudinary.api.resources_by_tag("mytag", function(result){}, { resource_type: 'raw' });
api.resourcesByTag("mytag", ObjectUtils.asMap("resource_type", "raw"));
/resources/raw/tags/mytag
List resources by context
Retrieve a list of resources with a specified context key. This method does not return deleted resources even if they have been backed up.
- key - Required. (String). Only resources with this context key are returned.
- value - Optional. (String). Only resources with this value for the context key are returned. If this parameter is not provided, all resources with the given context key are returned, regardless of the actual value of the key.
- max_results - Optional. (Integer, default=10. maximum=500). Max number of resources to return.
- next_cursor - Optional. When a listing 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 listing request.
- direction - Optional. (String/Integer, "asc" (or 1), "desc" (or -1), default: "desc" by creation date). 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 all key-value pairs of context associated with each resource.
Cloudinary::Api.resources_by_context('mycontextkey')
$api->resources_by_context("mycontextkey");
cloudinary.api.resources_by_context("mycontextkey")
cloudinary.api.resources_by_context("mycontextkey", function(result){});
api.resourcesByContext("mycontextkey", ObjectUtils.emptyMap());
/resources/image/context/?key=mycontextkey
Cloudinary::Api.resources_by_context('mycontextkey', 'mycontextvalue', :resource_type => :video)
$api->resources_by_context("mycontextkey", "mycontextvalue" array("resource_type" => "video"));
cloudinary.api.resources_by_context("mycontextkey", "mycontextvalue" resource_type = "video")
cloudinary.api.resources_by_context("mycontextkey", "mycontextvalue" function(result){}, { resource_type: 'video' });
api.resourcesByContext("mycontextkey", "mycontextvalue", ObjectUtils.asMap("resource_type", "video"));
/resources/video/context/?key=mycontextkey&value=mycontextvalue
List resources in moderation queues
- 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. (Integer, default=10. maximum=500). Max number of resources to return.
- next_cursor - Optional. When a listing 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 listing request.
- direction - Optional. (String/Integer, "asc" (or 1), "desc" (or -1), default: "desc" by creation date). 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.
{ "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" } ] }
Cloudinary::Api.resources_by_moderation("manual", "pending")
$api = new \Cloudinary\Api(); $api->resources_by_moderation("manual", "pending");
cloudinary.api.resources_by_moderation("manual", "pending")
cloudinary.api.resources_by_moderation('manual', 'pending', function(result) { console.log(result) });
cloudinary.api().resourcesByModeration("manual", "pending", ObjectUtils.emptyMap());
/resources/image/moderations/manual/pending
Cloudinary::Api.resources_by_moderation("webpurify", "approved")
$api = new \Cloudinary\Api(); $api->resources_by_moderation("webpurify", "approved");
cloudinary.api.resources_by_moderation("webpurify", "approved")
cloudinary.api.resources_by_moderation('webpurify', 'approved', function(result) { console.log(result) });
cloudinary.api().resourcesByModeration("webpurify", "approved", ObjectUtils.emptyMap());
/resources/image/moderations/webpurify/approved
List tags
- 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. When a listing 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 listing request.
{ "tags": [ "arrow_animation", "logo" ] }
Cloudinary::Api.tags
$api->tags();
cloudinary.api.tags()
cloudinary.api.tags(function(result){});
api.tags(ObjectUtils.emptyMap());
/tags/image
Cloudinary::Api.tags(:prefix => "myta")
$api->tags(array("prefix" => "myta"));
cloudinary.api.tags(prefix = "myta")
cloudinary.api.tags(function(result){}, { prefix: 'myta' });
api.tags(ObjectUtils.asMap("prefix", "myta"));
/tags/image/?prefix=myta
Details of a single resource
- 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 colorspace, ETag, IPTC, XMP, and detailed Exif metadata of the uploaded photo. Note: retrieves video metadata if the resource is a video file.
- 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.
{ "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", "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" }, }
Note : The 'next_cursor' value returned in the response is for use with the various List Resources methods, where you can return results starting from the resource with this next_cursor value. Resources in those methods are returned in order of the date created, so in effect using this next_cursor value in one of those methods will return all resources created after the created_at date of this resource.
Cloudinary::Api.resource('sample')
$api->resource("sample");
cloudinary.api.resource("sample")
cloudinary.api.resource('sample', function(result) { console.log(result) });
api.resource("sample", ObjectUtils.emptyMap());
/resources/image/upload/sample
Cloudinary::Api.resource('sample', :faces => true, :colors => true, :exif => true)
$api->resource("sample", array("faces" => TRUE, "colors" => TRUE, "exif" => TRUE));
cloudinary.api.resource("sample", faces = True, colors = True, exif = True)
cloudinary.api.resource('sample', function(result) { console.log(result) }, { faces: true, colors: true, exif: true });
api.resource("sample", ObjectUtils.asMap("faces", true, "colors", true, "exif", true));
/resources/image/upload/sample?faces=1&colors=1&exif=1
Cloudinary::Api.resource('4', :type => :facebook)
$api->resource("4", array("type" => "facebook"));
cloudinary.api.resource("4", type = "facebook")
cloudinary.api.resource('4', function(result){}, { type: 'facebook' });
api.resource("4", ObjectUtils.asMap("type", "facebook"));
/resources/image/facebook/4
Cloudinary::Api.resource('rwkaliebnufp3bxyrvyo.txt', :resource_type => :raw)
$api->resource("rwkaliebnufp3bxyrvyo.txt", array("resource_type" => "raw"));
cloudinary.api.resource("rwkaliebnufp3bxyrvyo.txt", resource_type = "raw")
cloudinary.api.resource('rwkaliebnufp3bxyrvyo.txt', function(result){}, { resource_type: 'raw' });
api.resource("rwkaliebnufp3bxyrvyo.txt", ObjectUtils.asMap("resource_type", "raw"));
/resources/raw/upload/rwkaliebnufp3bxyrvyo.txt
Update resources
Update one or more of the parameters associated with a specified resource.
Update details of an existing resource
- 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 'adv_face' to automatically extract advanced face attributes of photos using the Advanced Facial Attributes Detection 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 'imagga_tagging' to automatically detect scene categories of photos using the Imagga Auto Tagging add-on.
- background_removal - (Optional). Set to 'remove_the_background' (or 'pixelz' - the new name of the company) to automatically clear the background of an uploaded photo using the Remove-The-Background Editing add-on.
Cloudinary::Api.update("image1", :tags => "important", :moderation_status => "approved")
$api = new \Cloudinary\Api(); $api->update("image1", array("tags" => "important", "moderation_status" => "approved"));
cloudinary.api.update("image1", tags = "important", moderation_status = "approved")
cloudinary.api.update("image1", function(result) { console.log(result); }, { tags: "important", moderation_status: "approved" });
cloudinary.api().update("image1", ObjectUtils.asMap("tags", "important", "moderation_status", "approved"));
/resources/image/upload/image1
Delete resources
Use the delete methods to: delete all or selected resources, delete resources by tag, or delete derived resources.
Delete all or selected resources
This method deletes resources of a specific resource type and type (default = image, upload) according to the defined conditions:
- public_ids - Delete all resources with the given public IDs (array of up to 100 public_ids).
- prefix - Delete all resources, including derived resources, where the public ID starts with the given prefix (up to a maximum of 1000 original resources).
- all - Optional (Boolean, default: false). Delete all resources (of the relevant resource type and type), including derived resources (up to a maximum of 1000 original resources).
- keep_original - Optional (Boolean, default: false). If true, delete only the derived resources.
- invalidate - Optional (Boolean, default: false). 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.
- next_cursor - Optional. 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 the next_cursor parameter of the following deletion request.
- transformations - Optional. Only the derived resources matching this array of transformation parameters will be deleted.
{ "deleted": { "image1": "deleted", "image2": "deleted" }, "partial": false }
Cloudinary::Api.delete_resources(['image1', 'image2'])
$api->delete_resources(array("image1", "image2"));
cloudinary.api.delete_resources(["image1", "image2"])
cloudinary.api.delete_resources(['image1', 'image2'], function(result){});
api.deleteResources(Arrays.asList("image1", "image2"), ObjectUtils.emptyMap());
/resources/image/upload?public_ids[]=image1&public_ids[]=image2
Cloudinary::Api.delete_resources(['4'], :type => :facebook)
$api->delete_resources(array("4"), array("type" => "facebook"));
cloudinary.api.delete_resources(["4"], type = "facebook")
cloudinary.api.delete_resources(['4'], function(result){}, { type: 'facebook' });
api.deleteResources(Arrays.asList("4"), ObjectUtils.asMap("type", "facebook"));
/resources/image/facebook?public_ids=4
Cloudinary::Api.delete_resources_by_prefix('sunday')
$api->delete_resources_by_prefix("sunday");
cloudinary.api.delete_resources_by_prefix("sunday")
cloudinary.api.delete_resources_by_prefix('sunday', function(result){});
api.deleteResourcesByPrefix("sunday", ObjectUtils.emptyMap());
/resources/image/upload?prefix=sunday
Cloudinary::Api.delete_resources(['image1', 'image2'], :keep_original => true)
$api->delete_resources(array("image1", "image2"), array("keep_original" => TRUE));
cloudinary.api.delete_resources(["image1", "image2"], keep_original = True)
cloudinary.api.delete_resources(['image1', 'image2'], function(result){}, { keep_original: true });
api.deleteResources(Arrays.asList("image1", "image2"), ObjectUtils.asMap("keep_original", true));
/resources/image/upload?public_ids[]=image1&public_ids[]=image2&keep_original=1
Cloudinary::Api.delete_all_resources(:type => :facebook)
$api->delete_all_resources(array("type" => "facebook"));
cloudinary.api.delete_all_resources(type = "facebook")
cloudinary.api.delete_all_resources(function(result){}, { type: 'facebook' });
api.deleteAllResources(ObjectUtils.asMap("type", "facebook"));
/resources/image/facebook?all=true
Delete resources by tags
- tag - Delete all resources (and their derivatives) with the given tag name (up to a maximum of 1000 original resources).
- keep_original - Optional (Boolean, default: false). If true, delete only the derived images of the matching resources.
- invalidate - Optional (Boolean, default: false). 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.
- transformations - Optional. Only the derived resources matching this array of transformation parameters will be deleted.
- next_cursor - Optional. 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 the next_cursor parameter of the following deletion request.
{ "deleted": { "image1": "deleted", "image2": "deleted" }, "partial": false }
Cloudinary::Api.delete_resources_by_tag('mytag')
$api->delete_resources_by_tag("mytag");
cloudinary.api.delete_resources_by_tag("mytag")
cloudinary.api.delete_resources_by_tag('mytag', function(result){});
api.deleteResourcesByTag("mytag", ObjectUtils.emptyMap());
/resources/image/tags/mytag
Delete derived resources
- derived_resource_ids - Delete all derived resources with the given IDs (an array of up to 100 derived_resource_ids). The derived resource IDs are returned when calling the Details of a single resource method.
{ "deleted": { "cb4eaaf650": "deleted", "a7b2a2756a": "deleted" } }
Cloudinary::Api.delete_derived_resources(['cb4eaaf6503', 'a7b2a2756ab'])
$api->delete_derived_resources(array("cb4eaaf6503", "a7b2a2756ab"));
cloudinary.api.delete_derived_resources(["cb4eaaf6503", "a7b2a2756ab"])
cloudinary.api.delete_derived_resources(['cb4eaaf6503', 'a7b2a2756ab'], function(result){});
api.deleteDerivedResources(Arrays.asList("cb4eaaf6503", "a7b2a2756ab"), ObjectUtils.emptyMap());
/derived_resources?derived_resource_ids[]=cb4eaaf650&derived_resource_ids[]=a7b2a2756a
Manage transformations
Use the transformations methods to: retrieve a list of all transformations, retrieve the details of a single transformation, delete a transformation, update a transformation or create named transformation.
See the Image transformations and video transformations documentation for more information.
List transformations
- max_results - Optional. Max number of transformations to return. Default=10. Maximum=500.
- next_cursor - Optional. When a listing 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 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" }
Cloudinary::Api.transformations
$api->transformations();
cloudinary.api.transformations()
cloudinary.api.transformations(function(result){console.log(result)});
api.transformations(ObjectUtils.emptyMap());
/transformations
Details of a single transformation
- max_results - Optional. Max number of derived resources to return. Default=10. Maximum=100.
- next_cursor - Optional. When a listing 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 listing request.
{ "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" } ] }
Cloudinary::Api.transformation('w_150,h_100,c_fill')
$api->transformation("w_150,h_100,c_fill");
cloudinary.api.transformation("w_150,h_100,c_fill")
cloudinary.api.transformation('w_150,h_100,c_fill', function(result) { console.log(result) });
api.transformation("w_150,h_100,c_fill",
ObjectUtils.emptyMap());
/transformations/w_150,h_100,c_fill
Cloudinary::Api.transformation(:width => 150, :height => 100, :crop => :fill)
$api->transformation(array("width" => 150, "height" => 100, "crop" => "fill"));
cloudinary.api.transformation(dict(width = 150, height = 100, crop = "fill"))
cloudinary.api.transformation({width: 150, height: 100, crop: 'fill'}, function(result) { console.log(result) });
api.transformation(new Transformation().width(150).height(100). crop("fill").generate(), ObjectUtils.emptyMap());
/transformations/c_fill,h_100,w_150
Delete transformation
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.
{ "message": "deleted" }
Cloudinary::Api.delete_transformation('w_150,h_100,c_fill')
$api->delete_transformation("w_150,h_100,c_fill");
cloudinary.api.delete_transformation("w_150,h_100,c_fill")
cloudinary.api.delete_transformation('w_150,h_100,c_fill', function(result) { console.log(result) });
api.deleteTransformation("w_150,h_100,c_fill",
ObjectUtils.emptyMap());
/transformations/w_150,h_100,c_fill
Cloudinary::Api.delete_transformation(:width => 150, :height => 100, :crop => :fill)
$api->delete_transformation(array("width" => 150, "height" => 100, "crop" => "fill"));
cloudinary.api.delete_transformation(dict(width = 150, height = 100, crop = "fill"))
cloudinary.api.delete_transformation( {width: 150, height: 100, crop: 'fill'}, function(result) { console.log(result) });
api.deleteTransformation(new Transformation().width(150).height(100). crop("fill").generate(), ObjectUtils.emptyMap());
/transformations/c_fill,h_100,w_150
Update transformation
- 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 (the new settings of the named transformation only take effect from now on).
{ "message": "updated" }
Cloudinary::Api.update_transformation('w_150,h_100,c_fill', :allowed_for_strict => true)
$api->update_transformation("w_150,h_100,c_fill", array("allowed_for_strict" => 1));
cloudinary.api.update_transformation("w_150,h_100,c_fill", allowed_for_strict = True)
cloudinary.api.update_transformation('w_150,h_100,c_fill', { allowed_for_strict: true }, function(result) { console.log(result) });
api.updateTransformation("w_150,h_100,c_fill", ObjectUtils.asMap("allowed_for_strict", true), ObjectUtils.emptyMap());
/transformations/w_150,h_100,c_fill?allowed_for_strict=true
Cloudinary::Api.update_transformation({:width => 150, :height => 100, :crop => :fill}, {:allowed_for_strict => false})
$api->update_transformation( array("width" => 150, "height" => 100,"crop" => "fill") array("allowed_for_strict" => 0));
cloudinary.api.update_transformation(dict(width = 150, height = 100, crop = "fill"), dict( allowed_for_strict = False))
cloudinary.api.update_transformation( { width: 150, height: 100, crop: 'fill' }, { allowed_for_strict: false }, function(result) { console.log(result) });
api.updateTransformation(new Transformation().width(150).height(100). crop("fill").generate(), ObjectUtils.asMap("allowed_for_strict", false), ObjectUtils.emptyMap());
/transformations/c_fill,h_100,w_150?allowed_for_strict=false
Cloudinary::Api.update_transformation('my_named', :unsafe_update => { :crop => :scale, :width =>103 })
$api->update_transformation("my_named", array("crop" => "scale", "width" => 103));
cloudinary.api.update_transformation("my_named", dict(crop = "scale", width = 103))
cloudinary.api.update_transformation("my_named", { crop: 'scale', width: 103 }, function(result) { console.log(result) });
api.updateTransformation("my_named", ObjectUtils.asMap("unsafe_update", new Transformation().crop("scale").width(103).generate()), ObjectUtils.emptyMap());
/transformations/my_named?unsafe_update=c_scale,w_103
Create named transformation
- transformation - String representation of transformation parameters.
{ "message": "created" }
Cloudinary::Api.create_transformation('small_fill', 'w_150,h_100,c_fill')
$api->create_transformation("small_fill", "w_150,h_100,c_fill");
cloudinary.api.create_transformation("small_fill", "w_150,h_100,c_fill")
cloudinary.api.create_transformation('small_fill', 'w_150,h_100,c_fill', function(result) { console.log(result) });
api.createTransformation("small_fill", "w_150,h_100,c_fill", ObjectUtils.emptyMap());
/transformations/small_fill?transformation=w_150,h_100,c_fill
Cloudinary::Api.create_transformation('small_fill2', {:width => 150, :height => 100, :crop => :fill})
$api->create_transformation("small_fill2", array("width" => 150, "height" => 100, "crop" => "fill"));
cloudinary.api.create_transformation("small_fill2", dict(width = 150, height = 100, crop = "fill"))
cloudinary.api.create_transformation('small_fill2', { width: 150, height: 100, crop: 'fill' }, function(result) { console.log(result) });
api.createTransformation("small_fill2", new Transformation().width(150).height(100).crop("fill").generate(), ObjectUtils.emptyMap());
/transformations/small_fill2?transformation=c_fill,h_100,w_150
Restore resources
Restore one or more resources from backup.
Restore a deleted resource
- public_ids - The public IDs of (deleted or existing) backed up resources to restore. Reverts to the latest backed up version of the resource.
{ "message": "restored" }
Cloudinary::Api.restore(["image1", "image2"])
$api->restore(array("image1", "image2");
cloudinary.api.restore(["image1", "image2"])
cloudinary.api.restore(["image1", "image2"], function(result) { console.log(result); });
cloudinary.api().restore(Arrays.asList("image1", "image2"), ObjectUtils.emptyMap());
/resources/image/upload/restore?public_ids[]=image1&public_ids[]=image2
Manage upload mappings
The Upload Mappings feature is used for dynamic image fetching from existing online locations. Use the upload_mappings methods to: retrieve a list of all upload mappings, retrieve the details of a single upload mapping, delete an upload mapping, update an upload mapping or create a new upload mapping.
See the Auto upload remote images documentation for more information.
List upload mappings
List all upload mappings by folder and its mapped template (URL).
- max_results - Optional. Max number of upload mappings to return. Default=10. Maximum=500.
- next_cursor - Optional. When a listing 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 listing request.
{ "mappings"=>[ { "folder": "wiki", "template": "https://u.wiki.example.com/wiki-images/" }, { "folder"=>"exam", "template": "http://images.example.com/product_assets/images/" }, ] }
Cloudinary::Api.upload_mappings
$api->upload_mappings();
cloudinary.api.upload_mappings()
cloudinary.api.upload_mappings(function(result){console.log(result)});
api.uploadMappings(ObjectUtils.emptyMap());
/upload_mappings
Details of a single upload mapping
Retrieve the mapped template (URL) of a given upload mapping folder.
{ "folder": "wiki", "template": "https://u.wiki.example.com/wiki-images/" }
Cloudinary::Api.upload_mapping('wiki')
$api->upload_mapping("wiki");
cloudinary.api.upload_mapping("wiki")
cloudinary.api.upload_mapping('wiki', function(result) { console.log(result) });
api.uploadMapping("wiki",
ObjectUtils.emptyMap());
/upload_mappings/wiki
Create an upload mapping
Create a new upload mapping folder and its template (URL).
- folder - The name of the folder to map.
- template - The URL to be mapped to the folder.
{ "message": "created" }
Cloudinary::Api.create_upload_mapping("my_map", :template => "http://www.example.com/images/")
$api->create_upload_mapping("my_map", array("template" => "http://www.example.com/images/"));
cloudinary.api.create_upload_mapping("my_map", template = "http://www.example.com/images/")
cloudinary.api.create_upload_mapping('my_map', { template: "http://www.example.com/images/" }, function(result) { console.log(result) });
api.createUploadMapping("my_map", ObjectUtils.asMap("template", "http://www.example.com/images/"), ObjectUtils.emptyMap());
/upload_mappings?folder=my_map&template=http://www.example.com/images/
Delete an upload mapping
Delete an upload mapping by folder name.
{ "message": "deleted" }
Cloudinary::Api.delete_upload_mapping('wiki')
$api->delete_upload_mapping("wiki");
cloudinary.api.delete_upload_mapping("wiki")
cloudinary.api.delete_upload_mapping('wiki', function(result) { console.log(result) });
api.deleteUploadMapping("wiki",
ObjectUtils.emptyMap());
/upload_mappings/wiki
Update an upload mapping
Update an existing upload mapping folder with a new template (URL).
- folder - The name of the mapped folder.
- template - The new URL to be mapped to the folder.
{ "message": "updated" }
Cloudinary::Api.update_upload_mapping("wiki", :template => "https://u.wiki.com/images/")
$api->update_upload_mapping("wiki", array("template" => "https://u.wiki.com/images/"));
cloudinary.api.update_upload_mapping("wiki", template = "https://u.wiki.com/images/")
cloudinary.api.update_upload_mapping('wiki', { template: "https://u.wiki.com/images/" }, function(result) { console.log(result) });
api.updateUploadMapping("wiki", ObjectUtils.asMap("template", "https://u.wiki.com/images/"), ObjectUtils.emptyMap());
/upload_mappings?folder=wiki&template=https://u.wiki.com/images/
Update access mode
Use the update access mode methods to: update the access_mode of resources by public_id(s), by tag, or by prefix.
Update access mode for selected resources
This method updates the access_mode of resources of a specific resource type (default = image) according to the defined conditions. 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:
- access_mode - The new access mode to be set ("public" or "authenticated").
- public_ids - Update all resources with the given public IDs (array of up to 100 public_ids).
- prefix - Update all resources where the public ID starts with the given prefix (up to a maximum of 100 matching original resources).
- tag - Update all resources with the given tag (up to a maximum of 100 matching original resources).
- next_cursor - Optional. When an update request has more than 100 resources to update, the response includes a next_cursor value. You can then specify this returned next_cursor value as the next_cursor parameter of the following update request.
{ "updated": { "image1": "updated", "image2": "updated" }, "failed": { }, }
Cloudinary::Api.update_resources_access_mode_by_ids('public', ['image1', 'image2'])
$api->update_resources_access_mode_by_ids("public", array("image1", "image2"));
cloudinary.api.update_resources_access_mode_by_ids("public", ["image1", "image2"])
cloudinary.api.update_resources_access_mode_by_ids("public", ['image1', 'image2'], function(result){});
api.updateResourcesAccessModeByIds("public", Arrays.asList("image1", "another-image2"), null);
/resources/image/upload/update_access_mode?access_mode=public&public_ids[]=image1&public_ids[]=image2
Cloudinary::Api.update_resources_access_mode_by_prefix('public', "to-publish", :resource_type => :video)
$api->update_resources_access_mode_by_prefix("public", "to-publish", array("resource_type" => "video"));
cloudinary.api.update_resources_access_mode_by_prefix("public", "to-publish", resource_type = "video")
cloudinary.api.update_resources_access_mode_by_prefix("public", "to-publish", function(result){}, { resource_type: 'video' });
api.updateResourcesAccessModeByPrefix("public", "to-publish", ObjectUtils.asMap("resource_type", "video"));
/resources/video/upload/update_access_mode?access_mode=public&prefix=to-publish
Cloudinary::Api.update_resources_access_mode_by_tag('public', '20170216')
$api->update_resources_access_mode_by_tag("public", "20170216");
cloudinary.api.update_resources_access_mode_by_tag("public", "20170216")
cloudinary.api.update_resources_access_mode_by_tag('public', "20170216", function(result){});
api.updateResourcesAccessModeByTag("public", "20170216", null);
/resources/image/upload/update_access_mode?access_mode=public&tag=20170216
Manage upload presets
The Upload Presets feature is used for centrally defining image upload options instead of specifying them in each upload call. Use the upload_presets methods to: retrieve a list of all upload presets, retrieve the details of a single upload preset, delete an upload preset, update an upload preset or create a new upload preset.
See the upload preset documentation for more information.
List upload presets
- max_results - Optional. Max number of upload presets to return. Default=10. Maximum=500.
- next_cursor - Optional. When a listing 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 listing request.
{ "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" } }, ] }
Cloudinary::Api.upload_presets
$api->upload_presets();
cloudinary.api.upload_presets()
cloudinary.api.upload_presets(function(result){console.log(result)});
api.uploadPresets(ObjectUtils.emptyMap());
/upload_presets
Details of a single upload preset
Retrieves the details of an upload preset.
{ "name": "remote_media", "unsigned": false, "settings": { "tags": "test" "allowed_formats": "jpg,png", "eager": "c_fill,g_face,h_150,w_200" } }
Cloudinary::Api.upload_presets('remote_media')
$api->upload_presets("remote_media");
cloudinary.api.upload_presets("remote_media")
cloudinary.api.upload_presets('remote_media', function(result) { console.log(result) });
api.uploadPresets("remote_media",
ObjectUtils.emptyMap());
/upload_presets/remote_media
Create an upload preset
Create a new upload preset.
- name - The name to assign to the upload preset.
- unsigned - Boolean. Whether this upload preset allows unsigned uploading to Cloudinary.
- disallow_public_id - Boolean. Whether this upload preset disables assigning a public_id in the image upload call.
- Settings - The upload actions to apply to the images uploaded with this preset.
{ "message": "created" }
Cloudinary::Api.create_upload_preset("my_preset", :unsigned => true, :tags => "remote", :allowed_formats => "jpg,png")
$api->create_upload_preset("my_preset", array("unsigned" => true, "tags" => "remote", "allowed_formats" => "jpg,png"));
cloudinary.api.create_upload_preset("my_preset", unsigned = true, tags = "remote", allowed_formats = "jpg,png")
cloudinary.api.create_upload_preset(function(result) { console.log(result) }, { name: "my_preset", unsigned: true, tags: "remote", allowed_formats: "jpg,png" });
api.createUploadPreset("my_preset", ObjectUtils.asMap("unsigned", true, "tags" => "remote", "allowed_formats" => "jpg,png"), ObjectUtils.emptyMap());
/upload_presets?name=my_preset&unsigned=true&tags=remote&allowed_formats=jpg,png
Delete an upload preset
Delete an existing upload preset.
{ "message": "deleted" }
Cloudinary::Api.delete_upload_preset('remote_media')
$api->delete_upload_preset("remote_media");
cloudinary.api.delete_upload_preset("remote_media")
cloudinary.api.delete_upload_preset('remote_media', function(result) { console.log(result) });
api.deleteUploadPreset("remote_media",
ObjectUtils.emptyMap());
/upload_presets/remote_media
Update an upload preset
Update an existing upload preset.
- unsigned - Boolean. Whether this upload preset allows unsigned uploading to Cloudinary.
- disallow_public_id - Boolean. Whether this upload preset disables assigning a public_id in the image upload call.
- Settings - The upload actions to apply to the images uploaded with this preset.
{ "message": "updated" }
Cloudinary::Api.update_upload_preset("wiki", :unsigned => true, :tags => "remote", :allowed_formats => "jpg,png")
$api->update_upload_preset("wiki", array("unsigned" => true, "tags" => "remote", "allowed_formats" => "jpg,png"));
cloudinary.api.update_upload_preset("wiki", unsigned = true, tags = "remote", allowed_formats = "jpg,png")
cloudinary.api.update_upload_preset('wiki', { unsigned: true, tags: "remote", allowed_formats: "jpg,png"}, function(result) { console.log(result) });
api.updateUploadPreset("wiki", ObjectUtils.asMap("unsigned", true, "tags" => "remote", "allowed_formats" => "jpg,png"), ObjectUtils.emptyMap());
/upload_presets/wiki?unsigned=true&tags=remote&allowed_formats=jpg,png
Manage folders
Use the folders methods to retrieve a list of all root folders or the subfolders of a specified root folder.
List root folders
Lists all the root folders.
{ "folders": [ { "name"=>"cloud", "path"=>"cloud" }, { "name"=>"brooks", "path"=>"brooks" } ] }
Cloudinary::Api.root_folders
$api->root_folders();
cloudinary.api.root_folders()
cloudinary.api.root_folders(function(result) { console.log(result) });
api.rootFolders(ObjectUtils.emptyMap());
/folders
List subfolders
Lists the name and path of all the subfolders of a given root folder.
{ "folders": [ { "name"=>"blue", "path"=>"cloud/blue" }, { "name"=>"white", "path"=>"cloud/white" } ] }
Cloudinary::Api.subfolders("cloud")
$api->subfolders("cloud");
cloudinary.api.subfolders("cloud")
cloudinary.api.sub_folders("cloud", function(result) { console.log(result) });
api.subfolders("cloud", ObjectUtils.emptyMap());
/folders/cloud
Manage adaptive streaming profiles
Use the streaming_profiles methods 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.
List streaming profiles
List streaming profiles, including built-in and custom 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 } ] }
Cloudinary::Api.list_streaming_profiles
$api->list_streaming_profiles();
cloudinary.api.list_streaming_profiles()
cloudinary.api.list_streaming_profiles(function(result){console.log(result)});
api.listStreamingProfiles();
/streaming_profiles
Get details of a single streaming profile
Retrieve the details of a single streaming profile by name.
{ "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" } } ] } }
Cloudinary::Api.get_streaming_profile('custom_square')
$api->get_streaming_profile("custom_square");
cloudinary.api.get_streaming_profile("custom_square")
cloudinary.api.list_streaming_profile('custom_square', function(result){ console.log(result)});
api.getStreamingProfile("custom_square");
/streaming_profiles/custom_square
Create a streaming profile
Create a new, custom streaming profile.
- name - String. Required. The identification name to assign to the new streaming profile. The name is case-insensitive and can contain alphanumeric characters, underscores (_) and hyphens (-).
- display_name - String. A descriptive name for the profile.
- 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.
{ "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" } } ] } }
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"}}])
$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") )));
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"}} ])
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); });
api.createStreamingProfile("custom_square", "Custom square resolution", 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") ) );
/streaming_profiles?name=custom_square
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.
- display_name - String. A descriptive name for the profile.
- representations - JSON String. An array of structures that defines the updated 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.
{ "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" } } ] } }
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"}}])
$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")) )));
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"}} ])
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); });
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") ) );
/streaming_profiles?name=custom_square
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.
{ "message": "deleted" }
Cloudinary::Api.delete_streaming_profile('custom_square')
$api->delete_streaming_profile("custom_square");
cloudinary.api.delete_streaming_profile("custom_square")
cloudinary.api.delete_streaming_profile('custom_square', function(result){ console.log(result)});
api.deleteStreamingProfile("custom_square");
/streaming_profiles/custom_square
Usage report
Get a report on the status of your Cloudinary account usage details, including storage, bandwidth, requests, number of resources, and add-on usage. Note that numbers are updated periodically.
Get account usage details
{ "plan": "Basic", "last_updated": "2017-01-15", "transformations": {"usage": 7270, "limit": 75000, "used_percent": 9.69 }, "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, "url2png": {"usage": 0, "limit": 50}, "webpurify": {"usage": 0, "limit": 50}, "aspose": {"usage": 0, "limit": 50}, "imagga_tagging": {"usage": 0, "limit": 50}, "adv_face": {"usage": 0, "limit": 50} }
Ping Cloudinary
Test the reachability of the Cloudinary API with the ping method.