Admin API reference
The Admin API is a rate-limited API that provides full control of all uploaded media assets (resources), fetched social profile pictures, generated transformations and more.
API Overview
The Admin API endpoints are accessed using HTTPS. By default, the API endpoints use the following format:
https://api.cloudinary.com/v1_1/:cloud_name/:action
For example, to list all video assets in the 'demo' account:
The API uses Basic Authentication over secure HTTP. Your Cloudinary API Key and API Secret (which can be found on the Dashboard page of your Cloudinary console) are used for the authentication.
You can experiment with returning a list of the images on your own Cloudinary account by replacing the API_KEY
, API_SECRET
, and CLOUD_NAME
in the cURL command below:
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/resources/image
For most actions, request parameters are appended to the URL. In a few cases, they are passed as JSON objects. The response is in a JSON snippet. The response includes information about the action that was performed as well as data about the relevant assets.
The following sections provide additional details on working with the Admin API:
- Using SDKs with the Admin API
- Using the CLI to access the Admin API
- Error handling
- Usage limits
- Pagination
- Alternative data centers and endpoints (premium feature)
Using SDKs with the Admin API
Our server-side SDK libraries provide a wrapper for the Admin API, enabling you to use your native programming language of choice. When using an SDK, request building and authentication are handled automatically, and the JSON response is parsed and returned.
For example, you can use the following SDK command to return a listing of all image (the default resource_type
) assets:
Using the CLI to access the Admin API
You can use the Cloudinary CLI (Command Line Interface) to interact with the admin API. This can provide an easy way to add automation to your workflows and manage your assets without the need for a formal coding environment or having to access your management console.
You can find instructions for setting up and using the CLI in the CLI reference.
Error handling
The Admin API returns the status of requests using HTTP status codes:
200: OK | Success.
400: Bad request.
401: Authorization required.
403: Not allowed.
404: Not found.
409: Already exists.
420: Rate limited.
The SDKs report errors by raising applicative exceptions. Additionally, an informative JSON message is returned. For example:
Usage limits
You can use the Admin API quite extensively, but it is a rate limited API. The specific limits depend on the plan your account is registered to. If you require more flexible limits, don’t hesitate to contact us.
For each Admin API call, standard HTTP headers are returned with details on your current usage statistics, including your per-hour limit, remaining number of actions and the time the hourly count will be reset.
The header might look something like this:
X-FeatureRateLimit-Limit: 500 X-FeatureRateLimit-Remaining: 499 X-FeatureRateLimit-Reset: Wed, 03 Oct 2012 08:00:00 GMT
You can use the SDKs to retrieve this data as follows:
Pagination
The GET methods of the API return a limited set of results, ordered by the creation time of the relevant entities. You can control the number of results returned in a single request by specifying the max_results
parameter. The default is 10 for most methods. There is also a maximum number of results you can request for a single API call (either 100 or 500 as documented for each of the relevant methods). DELETE methods also operate in chunks.
When a GET request has more results to return than max_results
or when a DELETE request has more than 1000 entities to delete, the next_cursor
value is returned as part of the response. You can then specify this cursor value as the next_cursor
parameter of the following GET or DELETE request. For example, this enables you to iterate through the full list of uploaded resources, transformations, or tags in your Cloudinary account or to delete an entire set of entities that matches your deletion request.
Alternative data centers and endpoints (premium feature)
By default, Cloudinary accounts use US-based data centers. In these cases, the endpoint format is as shown at the beginning of this Overview.
If the majority of your users are located in Europe or Asia, Cloudinary can set up your account to use our Europe (EU) or Asia Pacific (AP) data center. In that case, your endpoints will take the form:
https://api-eu.cloudinary.com/v1_1/:cloud_name/:action
OR
https://api-ap.cloudinary.com/v1_1/:cloud_name/:action
Resources
Enables you to manage all the resources (assets) stored in your account.
Method | Description |
---|---|
GET/resources/:resource_type(/:type) |
Get resources |
GET/resources/:resource_type/tags/:tag |
Get resources by tag |
GET/resources/:resource_type/context/ |
Get resources by context |
GET/resources/:resource_type/moderations/:moderation_kind/:status |
Get resources in moderation queues |
GET/resources/:resource_type/:type/:public_id |
Get the details of a single resource |
GET/resources/search |
Search for resources |
POST/resources/:resource_type/:type/:public_id |
Update details of an existing resource |
POST/resources/:resource_type/:type/restore |
Restore resources |
POST/resources/:resource_type/upload/update_access_mode |
Update access mode |
DELETE/resources/:resource_type/:type |
Delete resources |
DELETE/resources/:resource_type/tags/:tag |
Delete resources by tags |
DELETE/derived_resources |
Delete derived resources |
Get resources
Lists resources (assets) uploaded to your account.
Syntax
GET /resources(/:resource_type)(/:type)
Optional parameters
Parameter | Type | Description |
---|---|---|
resource_type | String | The type of asset. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Possible values: image (default), raw , video . |
type | String | The delivery type, relevant as a parameter only when using the SDKs (the type is included in the endpoint URL when using the REST API). Possible values: upload , private , authenticated , facebook , twitter , gravatar , youtube , hulu , vimeo , animoto , worldstarhiphop , dailymotion . Default: all. |
prefix | String | Find all assets with a public ID that starts with the given prefix. The assets are sorted by public ID in the response. |
public_ids | String[] | An array of public IDs. Get assets with the given public IDs (up to 100). Note: Not supported for SDKs. Instead use the |
max_results | Integers | Maximum number of assets to return (up to 500). Default: 10 . |
next_cursor | String | When a request has more results to return than max_results , the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of a following request. |
start_at | String | Get assets that were created since the given timestamp (ISO 8601 format). Supported unless prefix or public_ids were specified. For example: 2020-12-01 |
direction | String/Integer | Control the order of returned assets, according to the created_at date. Note: if a prefix is specified, this parameter is ignored and the results are sorted by public ID. Possible values: desc or -1 (default), asc or 1 . |
tags | Boolean | Whether to include the list of tag names assigned to each asset. Default: false . |
context | Boolean | Whether to include key-value pairs of contextual metadata associated with each asset. Default: false . |
moderation | Boolean | Whether to include the image moderation status of each asset. Default: false . |
metadata | Boolean | Whether to include the metadata fields and values set for each asset. Default: false . |
Examples
Get all images:
Get uploaded images, up to a maximum of 30 results:
Get all uploaded images with a given prefix:
Get Facebook images:
Get raw uploaded files:
Get all uploaded images with the given IDs:
Sample response
{ "resources": [ { "asset_id": "b1ce1d159bc3696e5a74d8b8aefbe707", "public_id": "face_center", "format": "jpg", "version": 1333013579, "resource_type": "image", "type": "upload", "created_at": "2012-03-29T09:32:59Z", "bytes": 128891, "width": 283, "height": 424, "backup": true, "access_mode": "public", "url": "http://res.cloudinary.com/demo/image/upload/v1333013579/face_center.jpg", "secure_url": "https://.../image/upload/v1333013579/face_center.jpg" }, { "asset_id": "835d1cf89bd7c1b84dc4f53d35bc235f", "public_id": "12208495", "format": "jpg", "resource_type": "image", "type": "facebook", "created_at": "2012-10-06T17:18:52Z", "bytes": 0, "access_mode": "public", "url": "http://res.cloudinary.com/demo/image/facebook/12208495.jpg", "secure_url": "https://.../image/facebook/12208495.jpg" }, ] }
Get resources by tag
Lists resources (assets) with a specified tag. This method does not return deleted assets even if they have been backed up.
Syntax
GET /resources/:resource_type/tags/:tag
Required parameters
Parameter | Type | Description |
---|---|---|
tag | String | The assets to return that have this tag. |
Optional parameters
Parameter | Type | Description |
---|---|---|
resource_type | String | The type of asset. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Possible values: image (default), raw , video . |
max_results | Integer | Maximum number of assets to return (maximum=500). Default: 10 . |
next_cursor | String | When a request has more results to return than max_results , the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of the following request. |
direction | String/Integer | Control the order of returned assets, according to the created_at date. Note: if a prefix is specified, this parameter is ignored and the results are sorted by public ID. Possible values: desc or -1 (default), asc or 1 . |
tags | Boolean | Whether to include the list of tag names assigned to each asset. Default: false . |
context | Boolean | Whether to include key-value pairs of contextual metadata associated with each asset. Default: false . |
moderations | Boolean | Whether to include image moderation status of each asset. Default: false . |
metadata | Boolean | Whether to include the metadata fields and values set for each asset. Default: false . |
Examples
Get all images by tag:
Get all raw files by tag:
Get resources by context
Retrieves resources (assets) with a specified contextual metadata key. This method does not return deleted assets even if they have been backed up.
Syntax
GET /resources/:resource_type/context/
Required parameters
Parameter | Type | Description |
---|---|---|
key | String | Only assets with this contextual metadata key are returned. |
Optional parameters
Parameter | Type | Description |
---|---|---|
resource_type | String | The type of asset. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Possible values: image (default), raw , video . |
value | String | Only assets with this value for the contextual metadata key are returned. If this parameter is not provided, all assets with the given contextual metadata key are returned, regardless of the actual value of the key. |
max_results | Integer | Maximum number of assets to return (maximum=500). Default: 10 . |
next_cursor | String | When a request has more results to return than max_results , the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of the following request. |
direction | String/Integer | Control the order of returned assets, according to the created_at date. Note: if a prefix is specified, this parameter is ignored and the results are sorted by public ID. Possible values: desc or -1 (default), asc or 1 . |
tags | Boolean | Whether to include the list of tag names assigned to each asset. Default: false . |
context | Boolean | Whether to include key-value pairs of contextual metadata associated with each asset. Default: false . |
moderations | Boolean | Whether to include image moderation status of each asset. Default: false . |
metadata | Boolean | Whether to include the metadata fields and values set for each asset. Default: false . |
Examples
Get images by contextual metadata key:
Get video files by contextual metadata key and value:
Get resources in moderation queues
Retrieves resources (assets) with a particular status from a specified moderation queue.
Syntax
GET /resources/:resource_type/moderations/:moderation_kind/:status
Required parameters
Parameter | Type | Description |
---|---|---|
moderation_kind | String | The type of moderation queue to list. Possible values: manual , webpurify , aws_rek , metascan . |
status | String | The moderation status of assets to retrieve. Possible values: pending , approved , rejected . |
Optional parameters
Parameter | Type | Description |
---|---|---|
resource_type | String | The type of asset. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Possible values: image (default), raw , video . |
max_results | Integer | Maximum number of assets to return (maximum=500). Default: 10 . |
next_cursor | String | When a request has more results to return than max_results , the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of the following request. |
direction | String/Integer | Control the order of returned assets, according to the created_at date. Note: if a prefix is specified, this parameter is ignored and the results are sorted by public ID. Possible values: desc or -1 (default), asc or 1 . |
tags | Boolean | Whether to include the list of tag names assigned to each asset. Default: false . |
context | Boolean | Whether to include key-value pairs of contextual metadata associated with each asset. Default: false . |
moderations | Boolean | Whether to include image moderation status of each asset. Default: false . |
metadata | Boolean | Whether to include the metadata fields and values set for each asset. Default: false . |
Examples
Get images pending manual moderation:
Get images automatically approved by the WebPurify add-on:
Sample response
{ "resources": [{ "asset_id": "e590ea35ca6f56ee383e0437e43e1c54", "public_id": "q7vcvrfjm9mj4bfp3qc8", "format": "jpg", "version": 1570976812, "resource_type": "image", "type": "upload", "created_at": "2014-03-02T21:06:43Z", "bytes": 120253, "width": 864, "height": 576, "backup": true, "access_mode": "public", "url": "http://res.cloudinary.com/demo/image/upload/v1570976812/q7vcvrfjm9mj4bfp3qc8.jpg", "secure_url": "https://res.cloudinary.com/demo/image/upload/v1570976812/q7vcvrfjm9mj4bfp3qc8.jpg" }, { "asset_id": "53270b5120ab81ede6f570a203677652", "public_id": "zp4fgdbabhlwwa7bxu84", "format": "jpg", "version": 1570977154, "resource_type": "image", "type": "upload", "created_at": "2014-03-02T21:06:39Z", "bytes": 120253, "width": 864, "height": 576, "backup": true, "access_mode": "public", "url": "http://res.cloudinary.com/demo/image/upload/v1570977154/zp4fgdbabhlwwa7bxu84.jpg", "secure_url": "https://res.cloudinary.com/demo/image/upload/v1570977154/zp4fgdbabhlwwa7bxu84.jpg" } ] }
Get the details of a single resource
Return details of the requested resource (asset) as well as all its derived assets.
GET /resources/:resource_type/:type/:public_id
Syntax
Required parameters
Parameter | Type | Description |
---|---|---|
public_id | String | The public ID of the asset. |
Optional parameters
Parameter | Type | Description |
---|---|---|
resource_type | String | The type of asset. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Possible values: image (default), raw , video . |
type | String | The delivery type, relevant as a parameter only when using the SDKs (the type is included in the endpoint URL when using the REST API). Possible values: upload , private , authenticated , facebook , twitter , gravatar , youtube , hulu , vimeo , animoto , worldstarhiphop , dailymotion . Default: all. |
colors | Boolean | Whether to include color information: predominant colors and histogram of 32 leading colors. Default: false . |
image_metadata | Boolean | Whether to include IPTC, XMP, and detailed Exif metadata. Default: false .Returned metadata by type: - Images: PixelsPerUnitX , PixelsPerUnitY , PixelUnits , Colorspace , and DPI .- Audio and video: audio_codec , audio_bit_rate , audio_frequency , audio_profile ,channels , channel_layout .- Video: pix_format , codec , level , profile , video_duration , video_bit_rate , dar .Note: Using this parameter also returns the asset's ETag value for all asset types, including raw. |
exif | Boolean | Deprecated. Use image_metadata instead. Default: false . |
faces | Boolean | Whether to include a list of coordinates of detected faces. Default: false . |
quality_analysis | Boolean | Whether to return quality analysis scores for the image. Default: false . |
accessibility_analysis | Boolean | Whether to return accessibility analysis scores for the image. Default: false . |
pages | Boolean | Whether to report the number of pages in multi-page documents (e.g., PDF). Default: false . |
phash | Boolean | Whether to include the perceptual hash (pHash) of the uploaded photo for image similarity detection. Default: false . |
coordinates | Boolean | Whether to include previously specified custom cropping coordinates and faces coordinates. Default: false . |
versions | Boolean | Whether to include details of all the backed up versions of the asset. Default: false . |
max_results | Integer | Maximum number of derived assets to return (maximum=500). Default: 10 . |
derived_next_cursor | String | If there are more derived images than max_results , the derived_next_cursor value is returned as part of the response. You can then specify this value as the derived_next_cursor parameter of the following request. |
Examples
Uploaded image details:
Faces, colors, image metadata and versions details:
Facebook picture details:
Uploaded raw file details:
Sample response
This sample response is from the request including faces, colors, image metadata and versions:
{ "asset_id": "d86882d7788f5d1d702cb63418f082a6", "public_id": "sample", "format": "jpg", "version": 1312461204, "resource_type": "image", "type": "upload", "created_at": "2011-08-04T12:33:24Z", "bytes": 120253, "width": 864, "height": 576, "access_mode": "public", "url": "http://res.cloudinary.com/demo/image/upload/v1312461204/sample.jpg", "secure_url": "https://.../image/upload/v1312461204/sample.jpg", "tags": [ "flower", "plant", "naturet" ], "context": { "custom": { "alt": "sample flower", "caption": "beautiful flower" } }, "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 ] ] }, "versions": [ { "version_id": "d214063097a43d1d1293db61a397f60f", "version": "1312461204", "format": "jpg", "size": 109669, "time": "2011-08-04T12:33:24+00:00", "restorable": false } ] }
Search for resources
Search allows you fine control on filtering and retrieving information on all the resources (assets) in your account with the help of query expressions in a Lucene-like query language.
For detailed information on the search method and building expressions, see the Search API documentation.
Syntax
GET /resources/search
Cloudinary implements eventual consistency: any changes made to assets will only be reflected in a search made a few seconds after the change is processed.
Optional parameters
All the parameters of the search
method are optional. Including no parameters in the method call will return the 50 most recently created resources in descending order of creation time.
Parameter | Type | Description |
---|---|---|
expression | String | The (Lucene-like) string expression specifying the search query. If this parameter is not provided then all resources are listed (up to max_results ). For details, see the expressions documentation. |
sort_by | String[] | An array of string values representing a key value pair, where the key is the field to sort by and the value is the direction. Valid sort directions are asc or desc . If this parameter is not provided then the results are sorted by descending creation date. You can specify more than one sort_by parameter; results will be sorted according to the order of the fields provided. |
max_results | Integer | Maximum number of assets to return (maximum=500). Default: 10 . |
next_cursor | String | When a request has more results to return than max_results , the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of the following request. |
with_field | String | The name of an additional asset attribute to include for each asset in the response. You can specify more than one with_field parameter. Possible value: context , tags , and for Tier 2 also image_metadata , and image_analysis . |
aggregate | String | (Tier 2 only) The name of a field (attribute) for which an aggregation count should be calculated and returned in the response. You can specify more than one aggregate parameter. Supported values: resource_type , type , pixels (only the image assets in the response are aggregated), duration (only the video assets in the response are aggregated), format , and bytes . For aggregation fields without discrete values, the results are divided into categories. For example: - bytes are divided into small (<500 kb), medium (500 kb - 5 mb), large (5 mb - 100 mb), and huge (>100 mb).- Video duration is divided into short (< 3 minutes), medium (3-12 min), and long (> 12 min). |
- A new Search query object should be initialized for every distinct query executed. Please avoid reusing the same instance of a Search query object, as that might lead to unexpected behavior, especially when using the
sort_by
parameter. - When iterating through the results using the
next_cursor
parameter, the query should be reused without changing any of the other parameter values. - When making direct calls to the Cloudinary endpoint, make sure to pass any parameters using JSON (with Content-Type: application/json) as in the cURL examples on this page.
Examples
Find assets containing 'cat' in any field (attribute), include context metadata and tags in the details of each resource, and limit the returned results to 10 resources:
Find assets containing 'cat' in any field but not 'kitten' in the tags field, sort the results by public_id in descending order, and calculate an aggregation count based on the values of the format field:
TipFor more examples, see the expression examples documentation.
Sample response
{ "total_count": 32, "time": 30, "aggregations": { "format": { "png": 4, "jpg": 21, "mp4": 3, "doc": 4 } }, "next_cursor": "b16b8bd80426df43a107f26b0348", "resources": [ { "asset_id": "5f9d30acd36ac3c4f48a82241a37a299", "public_id": "sample", "folder": "", "filename": "sample", "format": "png", "version": 1492606756, "resource_type": "image", "type": "upload", "created_at": "2017-04-03T09:56:49+00:00", "uploaded_at": "2017-04-19T12:59:16+00:00", "bytes": 3381, "backup_bytes": 16905, "width": 241, "height": 51, "aspect_ratio": 4.7254901960784315, "pixels": 12291, "access_control": [ { access_type: "token" }, { access_type: "anonymous", start: "2017-12-15T12:00Z", end: "2018-01-20T12:00Z" }], "context": {}, "image_analysis": { "face_count": 0, "faces": [], "grayscale": true, "illustration_score": 1, "transparent": false, "colors": { "gray": 96.7 } }, "url": "http://res.cloudinary.com/demo/image/upload/v1492606756/sample.png", "secure_url": "https://res.cloudinary.com/demo/image/upload/v1492606756/sample.png", "status": "active", "access_mode": "public" }, { "public_id": "dog", … … } … }
Update details of an existing resource
Update one or more of the attributes associated with a specified resource (asset). Note that you can also update many attributes of an existing asset using the explicit method, which is not rate limited.
Syntax
POST /resources/:resource_type/:type/:public_id
Required parameters
Parameter | Type | Description |
---|---|---|
public_id | String | The public ID of the asset to update. |
Optional parameters
Parameter | Type | Description |
---|---|---|
resource_type | String | The type of asset. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Possible values: image (default), raw , video . |
type | String | The delivery type, relevant as a parameter only when using the SDKs (the type is included in the endpoint URL when using the REST API). Possible values: upload , private , authenticated , facebook , twitter , gravatar , youtube , hulu , vimeo , animoto , worldstarhiphop , dailymotion . Default: all. |
tags | String | A comma-separated list of tag names to assign to the uploaded asset for later group reference. |
context | String | A map (using the SDKs) or pipe-separated list (for REST API calls) of key-value pairs of contextual metadata to attach to an uploaded asset. The contextual metadata values of uploaded files are available for fetching using the Admin API. For example: `alt=My image |
metadata | String | A map (supported for Java SDK only) or pipe-separated list (for REST API calls) of custom metadata fields (by external_id) and the values to assign to each of them. The =, " and ❘ characters can be supported as values when escaped with a prepended backslash (\ ). For example: in_stock_id=50❘color_id=[\"green\",\"red\"] . |
face_coordinates | String | List of coordinates of faces contained in an uploaded image. The given coordinates are used for cropping uploaded images using the face or faces gravity mode. The specified coordinates override the automatically detected faces. Each face is specified by the X & Y coordinates of the top left corner and the width & height of the face. The coordinates are comma separated while faces are concatenated with a pipe (` |
custom_coordinates | String | Coordinates of an interesting region contained in an uploaded image. The given coordinates are used for cropping uploaded images using the custom gravity mode. The region is specified by the X & Y coordinates of the top left corner and the width & height of the region. For example: 85,120,220,310 . |
quality_override | Integer | Sets a quality value for this asset that will override any automatic quality transformations (q_auto) for this specific asset. |
moderation_status | String | Manually set image moderation status or override previously automatically moderated images by approving or rejecting. Possible values: approved , rejected . |
auto_tagging | Decimal | Automatically assigns tags to an asset according to detected objects or categories with a confidence score higher than the specified value. Use together with the Use together with the |
detection | String | Invokes the relevant add-on to return a list of detected content. Set to:
Relevant for images only. |
ocr | String | Set to adv_ocr to extract all text elements in an image as well as the bounding box coordinates of each detected element using the OCR text detection and extraction add-on.Relevant for images only. |
raw_convert | String | Asynchronously generates a related file based on the uploaded file.
|
categorization | String | A comma-separated list of the categorization add-ons to run on the asset. Set to google_tagging , google_video_tagging , imagga_tagging and/or aws_rek_tagging to automatically classify the scenes of the uploaded asset. Can be used together with the auto_tagging parameter to apply tags automatically. See the Google Automatic Video Tagging, Google Auto Tagging, Imagga Auto Tagging and Amazon Rekognition Auto Tagging add-ons for more details. |
background_removal | String | Automatically remove the background of an image using an add-on.
|
access_control | access_types[] | An array of access_types for the asset. The asset is accessible as long as one of the access types is valid. Possible values for each access type:
|
Examples
Update tags and moderation status of an uploaded image:
Restore resources
Restores one or more resources (assets) from backup.
Syntax
POST /resources/:resource_type/:type/restore
Required parameters
Parameter | Type | Description |
---|---|---|
public_ids | String[] | The public IDs of (deleted or existing) backed up assets to restore (array of up to 100 public_ids). By default, the latest backed up version of the asset is restored. If the versions parameter is specified, the corresponding version of each public ID is restored. |
Optional parameters
Parameter | Type | Description |
---|---|---|
resource_type | String | The asset type of the requested assets. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Possible values: image (default), raw , video . |
type | String | The delivery type of the requested assets, relevant as a parameter only when using the SDKs (the type is included in the endpoint URL when using the REST API). Possible values: upload , private , authenticated , Default: upload . |
versions | String[] | The version of each of the assets to restore. Specify the version_id for each public ID. Use the resource method to list details of backed up versions of an asset. |
Examples
Restore deleted resources by public_ids 'image1' and 'image2':
Restore specific versions of deleted resources by public_ids 'image1' and 'image2':
var publicIds = new List<string>(){"image1", "image2"}; var versionIds = new List<string>(){"c3fe4be5921eb89acd9af738c892f654", "d214063097a43d1d1293db61a397f60f" }; var restoreParams = new RestoreParams(){ PublicIds = publicIds, Versions = versionIds}; cloudinary.Restore(restoreParams);
Sample response
The details of the restored resources (note that when specific versions are restored, they are given new version IDs):
{ "image1": { "asset_id": "9ec64ab330767f4c1e939e2b4fcbaeac", "public_id": "image1", "version": 1574260348, "version_id": "8a7d06c83656a2a2d1d559f2ea5661f7", "signature": "b7f24977706edff33686e053e5a57a1684ff260b", "width": 5472, "height": 3648, "format": "jpg", "resource_type": "image", "created_at": "2019-11-20T14:32:28Z", "tags": [], "bytes": 3477251, "type": "upload", "placeholder": false, "access_mode": "public" } "image2": { "asset_id": "835d1cf89bd7c1b84dc4f53d35bc235f", "public_id": "image2", "version": 1574261348, "version_id": "80541d2d17a4485b84a7d264b3e778d0", "signature": "1aa2b977b02adffa268ae05a22aa57a1682fa202", "width": 5234, "height": 3234, "format": "jpg", "resource_type": "image", "created_at": "2019-10-20T12:34:18Z", "tags": [], "bytes": 2427151, "type": "upload", "placeholder": false, "access_mode": "public" } }
Update access mode
Update the access_mode of resources (assets) by public_id(s), by tag, or by prefix. When access_mode = 'authenticated', uploaded resources of type 'upload' behave as if they are of type 'authenticated'. The resource can later be made public by changing its access_mode to 'public', without having to update any image delivery URLs. In the case where public images are reverted to authenticated by changing their access_mode to 'authenticated', all the existing original and derived versions of the images are also invalidated on the CDN.
Syntax
POST /resources/:resource_type/upload/update_access_mode
Required parameters
Parameter | Type | Description |
---|---|---|
access_mode | String | The new access mode to be set. Possible values: public , authenticated . |
One of the following: | ||
- public_ids | String[] | Update all assets with the given public IDs (array of up to 100 public_ids). |
- prefix | String | Update all assets where the public ID starts with the given prefix (up to a maximum of 100 matching original assets). |
- tag | String | Update all assets with the given tag (up to a maximum of 100 matching original assets). |
Optional parameters
Parameter | Type | Description |
---|---|---|
resource_type | String | The type of asset. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Possible values: image (default), raw , video . |
Examples
Update the access mode of uploaded images by public IDs:
Update the access mode of uploaded videos by prefix:
Update the access mode of uploaded images by tag:
Sample response
Delete resources
Deletes resources (assets) uploaded to your account
Syntax
DELETE /resources/:resource_type/:type
Required parameters
One of the following:
Parameter | Type | Description |
---|---|---|
public_ids | String[] | Delete all assets with the given public IDs (array of up to 100 public_ids). |
prefix | String | Delete all assets, including derived assets, where the public ID starts with the given prefix (up to a maximum of 1000 original resources). |
all | Boolean | Delete all assets (of the relevant resource_type and type), including derived assets (up to a maximum of 1000 original resources). |
Optional parameters
Parameter | Type | Description |
---|---|---|
resource_type | String | The type of asset. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Possible values: image (default), raw , video . |
type | String | The delivery type, relevant as a parameter only when using the SDKs (the type is included in the endpoint URL when using the REST API). Possible values: upload , private , fetch ,authenticated , facebook , twitter , gravatar , youtube , hulu , vimeo , animoto , worldstarhiphop , dailymotion . Default: all. |
keep_original | Boolean | Whether to delete only the derived resources. Default: false . |
invalidate | Boolean | Whether to also invalidate the copies of the resource on the CDN. It usually takes between a few seconds and a few minutes for the invalidation to fully propagate through the CDN. There are also a number of other important considerations to keep in mind when invalidating files. Note that by default this parameter is not enabled: if you need this parameter enabled, please open a support request. Default: false . |
next_cursor | String | When a deletion request has more than 1000 resources to delete, the response includes the partial boolean parameter set to true, as well as a next_cursor value. You can then specify this returned next_cursor value as a parameter of the following deletion request. |
transformations | String | Only the derived resources matching this hash of transformation parameters will be deleted. |
Examples
Delete uploaded images by public IDs:
Delete Facebook pictures by public IDs:
Delete uploaded images by prefix:
Delete derived images only:
Delete all Facebook pictures:
Sample response
Delete resources by tags
Deletes resources (assets) with a specified tag.
Syntax
DELETE /resources/:resource_type/tags/:tag
Required parameters
Parameter | Type | Description |
---|---|---|
tag | String | Delete all assets (and their derivatives) with the given tag name (up to a maximum of 1000 original assets). |
Optional parameters
Parameter | Type | Description |
---|---|---|
resource_type | String | The type of asset. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Possible values: image (default), raw , video . |
keep_original | Boolean | Whether to delete only the derived resources. Default: false . |
invalidate | Boolean | Whether to also invalidate the copies of the resource on the CDN. It usually takes between a few seconds and a few minutes for the invalidation to fully propagate through the CDN. There are also a number of other important considerations to keep in mind when invalidating files. Note that by default this parameter is not enabled: if you need this parameter enabled, please open a support request. Default: false . |
next_cursor | String | When a deletion request has more than 1000 resources to delete, the response includes the partial boolean parameter set to true, as well as a next_cursor value. You can then specify this returned next_cursor value as a parameter of the following deletion request. |
transformations | String | Only the derived resources matching this hash of transformation parameters will be deleted. |
Examples
Delete images by tag name:
Sample response
Delete derived resources
Deletes derived resources (assets) from your account.
Syntax
DELETE /derived_resources
Required parameters
One of the following:
Parameter | Type | Description |
---|---|---|
derived_resource_ids | String[] | Delete all assets with the given derived_resource_ids IDs (array of up to 100 IDs). The derived resource IDs are returned when calling the Details of a single resource method. |
Optional parameters
Parameter | Type | Description |
---|---|---|
invalidate | Boolean | Whether to also invalidate the copies of the resource on the CDN. It usually takes between a few seconds and a few minutes for the invalidation to fully propagate through the CDN. There are also a number of other important considerations to keep in mind when invalidating files. Note that by default this parameter is not enabled: if you need this parameter enabled, please open a support request. Default: false . |
Examples
Delete assets by derived resource IDs (8267a869b62a93a59248f35d7f124c1f and 383e22a57167445552a3cdc16f0a0c85):
Transformations
Enables you to manage stored transformations. See the Image transformations and video transformations documentation for more information.
Method | Description |
---|---|
GET /transformations |
Get all transformations |
GET /transformations/:transformation |
Get details of a transformation |
POST/transformations/:name |
Create a named transformation |
PUT/transformations/:transformation |
Update a transformation |
DELETE/transformations/:transformation |
Delete a transformation |
Get Transformations
List all transformations.
Syntax
GET /transformations
Optional parameters
Parameter | Type | Description |
---|---|---|
max_results | Integer | Maximum number of transformations to return (up to 500). Default: 10 . |
next_cursor | String | When a request has more results to return than max_results , the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of a following request. |
named | Boolean | Whether to return only named (true ) or unnamed (false ) transformations. If this parameter is not included, both named and unnamed transformations will be returned. |
Examples
List all transformations:
Sample response
The response contains an array of transformations. If the number of transformations exceeds the max_results
value, the next_cursor
parameter is also returned. You can specify this value as the next_cursor
parameter of the following listing request.
{ "transformations": [ { "name": "t_Aspen_LUT", "allowed_for_strict": true, "used": false, "named": true }, { "name": "w_110,h_100,c_fill", "allowed_for_strict": false, "used": false, "named": false }, { "name": "c_thumb,g_face,h_100,w_80", "allowed_for_strict": false, "used": true, "named": false }, { "name": "c_fill,h_75,w_75/jpg", "allowed_for_strict": false, "used": true, "named": false } ], "next_cursor": "8edbc61040178db60b0973ca9494bf3a" }
Get Transformation details
Get details of a single transformation. Supply either the name of the transformation or the transformation parameters.
Syntax
GET /transformations/:transformation
Required parameters
Parameter | Type | Description |
---|---|---|
transformation | String | The name of the transformation or the transformation parameters. |
Optional parameters
Parameter | Type | Description |
---|---|---|
max_results | Integer | Maximum number of derived resources to return (up to 500). Default: 10 . |
next_cursor | String | When a request has more results to return than max_results , the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of a following request. |
Examples
Get transformation by name:
Get transformation by parameters:
Sample response
{ "name": "w_150,h_100,c_fill", "allowed_for_strict": false, "used": true, "named": false, "info": [ { "width": 150, "height": 100, "crop": "fill" } ], "derived": [ { "public_id": "sample", "resource_type": "image", "type": "upload", "format": "jpg", "url": "http://.../demo/image/upload/w_150,h_100,c_fill/v1341141057/sample.jpg", "secure_url": "https://.../demo/image/upload/w_150,h_100,c_fill/v1341141057/sample.jpg", "bytes": 10202, "id": "2adf1841874c7b2326d1f90cbedbc914" } ] }
Create a named transformation
Create a new named transformation.
Syntax
POST /transformations/:name
Required parameters
Parameter | Type | Description |
---|---|---|
name | String | The name of the transformation. |
transformation | String | The transformation parameters. |
Examples
Create named transformation by string:
Create named transformation by parameters:
Sample response
Update transformation
Update a specific transformation.
Syntax
PUT /transformations/:transformation
Required parameters
Parameter | Type | Description |
---|---|---|
transformation | String | The name of the transformation or a listing of the transformation parameters. |
Optional parameters
Parameter | Type | Description |
---|---|---|
allowed_for_strict | Boolean | Whether to allow this named transformation when strict transformations are enabled. Default: false . |
unsafe_update | String | Required when modifying the transformation parameters of an existing named transformation. The new transformation definition for the named transformation. Because this change can be unsafe for assets in production, the change is applied only to newly generated derived assets. |
Examples
Allow transformation by name:
Disallow transformation by parameter listing:
Update the transformation definition for a named transformation:
Sample response
Delete transformation
Delete a single transformation. Supply either the name of the transformation or the transformation parameters.
Syntax
DELETE /transformations/:transformation
Required parameters
Parameter | Type | Description |
---|---|---|
transformation | String | The name of the transformation or the transformation parameters. |
Examples
Delete transformation by name:
Delete transformation by parameters:
Sample response
Upload mappings
Dynamically fetches images from existing online locations and uploads the files to your account.
See the Auto upload remote images documentation for more information.
Method | Description |
---|---|
GET/upload_mappings |
Get upload mappings |
GET/upload_mappings/:folder |
Get the details of a single upload mapping |
POST/upload_mappings |
Create an upload mapping |
PUT/upload_mappings |
Update an upload mapping |
DELETE/upload_mappings/:folder |
Delete an upload mapping |
Get upload mappings
List all upload mappings by folder and includes its mapped template (URL).
Syntax
GET /upload_mappings
Optional parameters
Parameter | Type | Description |
---|---|---|
max_results | Integers | Maximum number of assets to return (up to 500). Default: 10 . |
next_cursor | String | When a request has more results to return than max_results , the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of a following request. |
Examples
List all upload mappings
Sample response
{ "mappings": [ { "folder": "wiki", "template": "https://u.wiki.example.com/wiki-images/" }, { "folder": "exam", "template": "https://images.example.com/product_assets/images/" }, ] }
Get the details of a single upload mapping
Retrieve the mapped template (URL) of a given upload mapping folder.
Syntax
GET /upload_mappings/:folder
Required parameters
Parameter | Type | Description |
---|---|---|
folder | String | The name of the folder to map. |
Examples
Upload mapping details by folder the 'wiki' folder:
Sample response
Create an upload mapping
Create a new upload mapping folder and its template (URL).
Syntax
POST /upload_mappings
Required parameters
Parameter | Type | Description |
---|---|---|
folder | String | The name of the folder to map. |
template | String | The URL to be mapped to the folder, as part of options . |
Examples
Create upload mapping from 'https://www.example.com/images/' to a folder called 'my_map':
Sample response
Update an upload mapping
Update an existing upload mapping folder with a new template (URL).
Syntax
PUT /upload_mappings
Required parameters
Parameter | Type | Description |
---|---|---|
folder | String | The name of the folder to map. |
template | String | The URL to be mapped to the folder, as part of options . |
Examples
Update an upload mapping to the 'wiki' folder with the https://u.wiki.com/images/ URL:
Sample response
Delete an upload mapping
Delete an upload mapping by folder name.
Syntax
DELETE /upload_mappings/:folder
Required parameters
Parameter | Type | Description |
---|---|---|
folder | String | The name of the folder to map. |
Examples
Delete an upload mapping to the 'wiki' folder:
Sample response
Upload presets
Enables you to centrally define image upload options instead of specifying them in each upload call.
See the upload preset documentation for more information.
Methods | Description |
---|---|
GET /upload_presets |
Get upload presets |
GET /upload_presets/:name |
Get the details of a single upload preset |
POST/upload_presets |
Create an upload preset |
PUT/upload_presets/:name |
Update an upload preset |
DELETE/upload_presets/:name |
Delete an upload preset |
Get upload presets
Lists the upload presets defined for your account.
Syntax
GET /upload_presets
Optional parameters
Parameter | Type | Description |
---|---|---|
max_results | Integers | Maximum number of assets to return (up to 500). Default: 10 . |
next_cursor | String | When a request has more results to return than max_results , the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of a following request. |
Examples
List all upload presets:
Sample response
{ "presets": [ { "name": "pd1e4lst", "unsigned": true, "settings": { "transformation": "c_crop,g_custom/ar_1,c_pad,w_1.0" } }, { "name": "remote_media", "unsigned": false, "settings": { "tags": "test" "allowed_formats": "jpg,png", "eager": "c_fill,g_face,h_150,w_200" } }, ] }
Get the details of a single upload preset
Retrieves the details of an upload preset.
Syntax
GET /upload_presets/:name
Required parameters
Parameter | Type | Description |
---|---|---|
name | String | The name of the upload preset. |
Examples
Upload preset details for the 'remote_media' preset:
Sample response
{ "name": "remote_media", "unsigned": false, "settings": { "tags": "test", "allowed_formats": "jpg,png", "eager": "c_fill,g_face,h_150,w_200" } }
Create an upload preset
Create a new upload preset.
Syntax
POST /upload_presets
Optional parameters
Parameter | Type | Description |
---|---|---|
name | String | The name to assign to the new upload preset. If not specified, a random name is generated. If the name is of an existing preset, it will be overwritten. |
unsigned | Boolean | Whether this upload preset allows unsigned uploading to Cloudinary. Default: false . |
disallow_public_id | Boolean | Whether this upload preset disables assigning a public_id in the upload call. Default: false . |
live | Boolean | Whether to enable "live broadcast", so that the upload preset can be used for live streaming. |
{Upload parameters} | The upload parameters to apply to assets uploaded with this preset. |
Examples
Create a new upload preset called 'my_preset', that allows unsigned uploading, adds the tag 'remote' to uploaded images, and only allows the uploading of JPG and PNG image formats:
Sample response
Update an upload preset
Update an existing upload preset.
Syntax
PUT /upload_presets/:name
Optional parameters
Parameter | Type | Description |
---|---|---|
name | String | The name of the upload preset. |
unsigned | Boolean | Whether this upload preset allows unsigned uploading to Cloudinary. Default: false . |
disallow_public_id | Boolean | Whether this upload preset disables assigning a public_id in the upload call. Default: false . |
live | Boolean | Whether to enable "live broadcast", so that the upload preset can be used for live streaming. |
{Upload parameters} | The upload parameters to apply to assets uploaded with this preset. |
Examples
Update an upload preset called 'wiki', to allow unsigned uploading, add the tag 'remote' to uploaded images, and only allow the uploading of JPG and PNG image formats:
Sample response
Delete an upload preset
Delete an existing upload preset.
Syntax
DELETE /upload_presets/:name
Required parameters
Parameter | Type | Description |
---|---|---|
name | String | The name of the upload preset. |
Examples
Delete an upload preset called 'remote_media':
Sample response
Metadata
Enables you to manage the metadata fields available for your account.
See the Metadata API documentation for detailed information on the the following Metadata methods, as well as detailed information on the Metadata field structure, including how to work with field validation and list (datasource) values:
Method | Description |
---|---|
GET/metadata_fields |
Get metadata fields |
GET/metadata_fields/:external_id |
Get a metadata field by external id |
POST/metadata_fields |
Create a metadata field |
POST/metadata_fields/:external_id/datasource_restore |
Restore entries in a metadata field datasource |
PUT/metadata_fields/:external_id |
Update a metadata field by external id |
PUT/metadata_fields/:external_id/datasource |
Update a metadata field datasource |
DELETE/metadata_fields/:external_id |
Delete a metadata field by external id |
DELETE/metadata_fields/:external_id/datasource |
Delete entries in a metadata field datasource |
Folders
Enables you to manage folders for your account.
Methods | Description |
---|---|
GET/folders |
Get root folders |
GET/folders/:folder |
Get subfolders |
POST/folders/:folder |
Create a folder |
DELETE/folders/:folder |
Delete a folder |
Get root folders
Lists all the root folders. Limited to 2000 results.
Syntax
GET /folders
Sample response
The response contains an array of all the root folders.
{ "folders": [ { "name": "cloud", "path": "cloud" }, { "name": "brooks", "path": "brooks" } ] }
Get subfolders
Lists the name and path of all the subfolders of a given folder. Limited to 2000 results.
Syntax
GET /folders/:folder
Required parameters
Parameter | Type | Description |
---|---|---|
folder | String | The full path of the folder to return subfolders of. |
Optional parameters
Parameter | Type | Description |
---|---|---|
max_results | Integers | Maximum number of results to return (up to 500). Default: 10 . |
next_cursor | String | When a request has more results to return than max_results , the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of a following request. |
Examples
List all subfolders of a given folder 'product/shoe':
Sample response
The response contains an array of all the subfolders of the given folder.
{ "folders": [ { "name": "red", "path": "product/shoe/red" }, { "name": "white", "path": "product/shoe/white" } ] }
Create folder
Create a new empty folder.
Syntax
POST /folders/:folder
Required parameters
Parameter | Type | Description |
---|---|---|
folder | String | The full path of the new folder to create. |
Examples
Create a new folder called 'test' as a subfolder of the root folder 'product' ('product/test'):
Sample response
Delete folder
Deletes an empty folder.
Syntax
DELETE /folders/:folder
Required parameters
Parameter | Type | Description |
---|---|---|
folder | String | The full path of the empty folder to delete. |
Examples
Delete a folder called 'test' which is a subfolder of the root folder 'product' ('product/test'):
Sample response
Adaptive streaming profiles
Enables you to list, get details of, create, modify, or delete built-in and custom adaptive streaming profiles, which can be used to deliver your video using HLS and MPEG-DASH adaptive bitrate streaming.
Methods | Description |
---|---|
GET/streaming_profiles |
Get adaptive streaming profiles |
GET/streaming_profiles/:name |
Get details of a streaming profile |
POST/streaming_profiles |
Create a streaming profile |
PUT/streaming_profiles/:name |
Update an existing streaming profile |
DELETE/streaming_profiles/:name |
Delete or revert the specified streaming profile |
Get adaptive streaming profiles
List streaming profiles, including built-in and custom profiles.
Syntax
GET /streaming_profiles
Sample response
The response contains an array of all the defined streaming profiles.
{ "data": [ { "name": "4k", "display_name": "4K (2160p)", "predefined": true }, { "name": "full_hd", "display_name": "Full HD (1080p)", "predefined": true }, { "name": "hd", "display_name": "HD (720p)", "predefined": true }, { "name": "sd", "display_name": "SD (480p)", "predefined": true }, { "name": "full_hd_wifi", "display_name": "Full HD WiFi (1080p)", "predefined": true }, { "name": "full_hd_lean", "display_name": "Full HD Lean (1080p)", "predefined": true }, { "name": "hd_lean", "display_name": "HD Lean (720p)", "predefined": true }, { "name": "custom_square", "display_name": "Custom square resolution", "predefined": false } ] }
Get details of a single streaming profile
Retrieve the details of a single streaming profile by name.
Syntax
GET /streaming_profiles/:name
Required parameters
Parameter | Type | Description |
---|---|---|
name | String | The name of the streaming profile to get the details of. |
Examples
Get the details of a specified streaming file:
Sample response
The response contains details for a single streaming profile.
{ "data": { "name": "custom_square", "display_name": "Custom square resolution", "predefined": false, "representations": [ { "transformation": { "width": 1200, "height": 1200, "bit_rate": "5m", "video_codec": "h264:main:3.1" } }, { "transformation": { "width": 900, "height": 900, "bit_rate": "3500k", "video_codec": "h264:main:3.1" } }, { "transformation": { "width": 600, "height": 600, "bit_rate": "1500k", "video_codec": "h264:baseline:3.0" } } ] } }
Create a streaming profile
Create a new, custom streaming profile.
Syntax
POST /streaming_profiles
Required parameters
Parameter | Type | Description |
---|---|---|
name | String | The identification name to assign to the new streaming profile. The name is case-insensitive and can contain alphanumeric characters, underscores (_) and hyphens (-). |
representations | JSON string | An array of structures that defines a custom streaming profile. |
transformation | String or Hash | Specifies the transformation parameters for the representation. All video transformation parameters except video_sampling are supported. Common transformation parameters for representations include: width , height (or aspect_ratio ), bit_rate , video_codec , audio_codec , sample_rate (or fps ), etc. |
Optional parameters
Parameter | Type | Description |
---|---|---|
display_name | String | A descriptive name for the profile. |
Examples
Create a streaming profile with 3 representations:
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", [ "display_name" => "Custom square resolution", "representations" => [ ["crop" => "limit", "width" => 1200, "height" => 1200, "bit_rate" => "5m"], ["crop" => "limit", "width" => 900, "height" => 900, "bit_rate" => "3500k"], ["crop" => "limit", "width" => 600, "height" => 600, "bit_rate" => "1500k"]]]);
$api->createStreamingProfile("custom_square", [ "display_name" => "Custom square resolution", "representations" => [ ["crop" => "limit", "width" => 1200, "height" => 1200, "bit_rate" => "5m"], ["crop" => "limit", "width" => 900, "height" => 900, "bit_rate" => "3500k"], ["crop" => "limit", "width" => 600, "height" => 600, "bit_rate" => "1500k"]]]);
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( ObjectUtils.asMap("transformation", new Transformation().crop("limit").width(1200).height(1200).bitRate("5m")), ObjectUtils.asMap("transformation", new Transformation().crop("limit").width(900).height(900).bitRate("3500k")), ObjectUtils.asMap("transformation", new Transformation().crop("limit").width(600).height(600).bitRate("1500k"))));
curl \ -d 'name=custom_square&display_name=Custom%20square%20resolution&representations=\[\{%22transformation%22:%22c_limit,w_1200,h_1200,br_5m%22\},\{%22transformation%22:%22c_limit,w_900,h_900,br_3500k%22\},\{%22transformation%22:%22c_limit,w_600,h_600,br_1500k%22\}\]' -X POST \ https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/streaming_profiles
cld admin create_streaming_profile "custom_square" display_name="Custom square resolution" representations='[{"transformation": {"crop": "limit","width": 1200, "height": 1200, "bit_rate": "5m"}},{"transformation": {"crop": "limit", "width": 900, "height": 900, "bit_rate": "3500k"}},{"transformation": {"crop": "limit", "width": 600, "height": 600, "bit_rate": "1500k"}}]'
Sample response
The response contains details for the streaming profile that was created.
{ "data": { "name": "custom_square", "display_name": "Custom square resolution", "predefined": false, "representations": [ { "transformation": { "width": 1200, "height": 1200, "bit_rate": "5m", "video_codec": "h264:main:3.1" } }, { "transformation": { "width": 900, "height": 900, "bit_rate": "3500k", "video_codec": "h264:main:3.1" } }, { "transformation": { "width": 600, "height": 600, "bit_rate": "1500k", "video_codec": "h264:baseline:3.0" } } ] } }
Create a streaming profile with 6 representations and a combination of codecs:
Cloudinary::Api.create_streaming_profile("custom_square_combo", :display_name => "Custom square resolution with combination of codecs", :representations => [{:transformation => {:crop => "limit", :width => "1200", :height => "1200", :video_codec => "h265", :bit_rate => "5m"}}, {:transformation => {:crop => "limit", :width => "900", :height => "900", :video_codec => "h265", :bit_rate => "3500k"}}, {:transformation => {:crop => "limit", :width => "600", :height => "600", :video_codec => "h265", :bit_rate => "1500k"}}, {:transformation => {:crop => "limit", :width => "1200", :height => "1200", :video_codec => "vp9", :bit_rate => "5m"}}, {:transformation => {:crop => "limit", :width => "900", :height => "900", :video_codec => "vp9", :bit_rate => "3500k"}} {:transformation => {:crop => "limit", :width => "600", :height => "600", :video_codec => "vp9", :bit_rate => "1500k"}}])
$api->create_streaming_profile("custom_square_combo", [ "display_name" => "Custom square resolution with combination of codecs", "representations" => [ ["crop" => "limit", "width" => 1200, "height" => 1200, "video_codec" => "h265", "bit_rate" => "5m"], ["crop" => "limit", "width" => 900, "height" => 900, "video_codec" => "h265", "bit_rate" => "3500k"], ["crop" => "limit", "width" => 600, "height" => 600, "video_codec" => "h265", "bit_rate" => "1500k"], ["crop" => "limit", "width" => 1200, "height" => 1200, "video_codec" => "vp9", "bit_rate" => "5m"], ["crop" => "limit", "width" => 900, "height" => 900, "video_codec" => "vp9", "bit_rate" => "3500k"], ["crop" => "limit", "width" => 600, "height" => 600, "video_codec" => "vp9", "bit_rate" => "1500k"]]);
$api->createStreamingProfile("custom_square_combo", [ "display_name" => "Custom square resolution with combination of codecs", "representations" => [ ["crop" => "limit", "width" => 1200, "height" => 1200, "video_codec" => "h265", "bit_rate" => "5m"], ["crop" => "limit", "width" => 900, "height" => 900, "video_codec" => "h265", "bit_rate" => "3500k"], ["crop" => "limit", "width" => 600, "height" => 600, "video_codec" => "h265", "bit_rate" => "1500k"], ["crop" => "limit", "width" => 1200, "height" => 1200, "video_codec" => "vp9", "bit_rate" => "5m"], ["crop" => "limit", "width" => 900, "height" => 900, "video_codec" => "vp9", "bit_rate" => "3500k"], ["crop" => "limit", "width" => 600, "height" => 600, "video_codec" => "vp9", "bit_rate" => "1500k"]]);
cloudinary.api.create_streaming_profile("custom_square_combo", display_name="Custom square resolution with combination of codecs", representations=[ {"transformation": {"crop": "limit", "width": 1200, "height": 1200, "video_codec": "h265", "bit_rate": "5m"}}, {"transformation": {"crop": "limit", "width": 900, "height": 900, "video_codec": "h265", "bit_rate": "3500k"}}, {"transformation": {"crop": "limit", "width": 600, "height": 600, "video_codec": "h265", "bit_rate": "1500k"}}, {"transformation": {"crop": "limit", "width": 1200, "height": 1200, "video_codec": "vp9", "bit_rate": "5m"}}, {"transformation": {"crop": "limit", "width": 900, "height": 900, "video_codec": "vp9", "bit_rate": "3500k"}}, {"transformation": {"crop": "limit", "width": 600, "height": 600, "video_codec": "vp9", "bit_rate": "1500k"}}])
cloudinary.v2.api.create_streaming_profile('custom_square_combo', { display_name: "Custom square resolution with combination of codecs", representations: [ { transformation:{crop: "limit", width: 1200, height: 1200, video_codec: "h265", bit_rate: "5m" }}, { transformation:{crop: "limit", width: 900, height: 900, video_codec: "h265", bit_rate: "3500k" }}, { transformation:{crop: "limit", width: 600, height: 600, video_codec: "h265", bit_rate: "1500k" }}, { transformation:{crop: "limit", width: 1200, height: 1200, video_codec: "vp9", bit_rate: "5m" }}, { transformation:{crop: "limit", width: 900, height: 900, video_codec: "vp9", bit_rate: "3500k" }}, { transformation:{crop: "limit", width: 600, height: 600, video_codec: "vp9", bit_rate: "1500k" }}] }, function(error, result){console.log(result);});
: api.createStreamingProfile("custom_square_combo", "Custom square resolution with combination of codecs", Arrays.asList( ObjectUtils.asMap("transformation", new Transformation().crop("limit").width(1200).height(1200).videoCodec("h265").bitRate("5m")), ObjectUtils.asMap("transformation", new Transformation().crop("limit").width(900).height(900).videoCodec("h265").bitRate("3500k")), ObjectUtils.asMap("transformation", new Transformation().crop("limit").width(600).height(600).videoCodec("h265").bitRate("1500k")), ObjectUtils.asMap("transformation", new Transformation().crop("limit").width(1200).height(1200).videoCodec("vp9").bitRate("5m")), ObjectUtils.asMap("transformation", new Transformation().crop("limit").width(900).height(900).videoCodec("vp9").bitRate("3500k")), ObjectUtils.asMap("transformation", new Transformation().crop("limit").width(600).height(600).videoCodec("vp9").bitRate("1500k"))));
curl \ -d 'name=custom_square_combo&display_name=Custom%20square%20resolution%20with%20combination%20of%20codecs&representations=\[\{%22transformation%22:%22c_limit,w_1200,h_1200,vc_h264,br_5m%22\},\{%22transformation%22:%22c_limit,w_900,h_900,vc_h264,br_3500k%22\},\{%22transformation%22:%22c_limit,w_600,h_600,vc_h264,br_1500k%22\},\{%22transformation%22:%22c_limit,w_1200,h_1200,vc_vp9,br_5m%22\},\{%22transformation%22:%22c_limit,w_900,h_900,vc_vp9,br_3500k%22\},\{%22transformation%22:%22c_limit,w_600,h_600,vc_vp9,br_1500k%22\}\]' -X POST \ https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/streaming_profiles
cld admin create_streaming_profile "custom_square_combo" display_name="Custom square resolution with combination of codecs" representations='[{"transformation": {"crop": "limit", "width": 1200, "height": 1200, "video_codec": "h265", "bit_rate": "5m"}},{"transformation": {"crop": "limit", "width": 900, "height": 900, "video_codec": "h265", "bit_rate": "3500k"}},{"transformation": {"crop": "limit", "width": 600, "height": 600, "video_codec": "h265", "bit_rate": "1500k"}},{"transformation": {"crop": "limit", "width": 1200, "height": 1200, "video_codec": "vp9", "bit_rate": "5m"}},{"transformation": {"crop": "limit", "width": 900, "height": 900, "video_codec": "vp9", "bit_rate": "3500k"}},{"transformation": {"crop": "limit", "width": 600, "height": 600, "video_codec": "vp9", "bit_rate": "1500k"}}]'
Sample response
The response contains details for the streaming profile that was created.
{ "data":{ "name":"custom_square_combo", "display_name":"Custom square resolution with combination of codecs", "predefined":false, "representations":[ { "transformation":[ { "width":1200, "height":1200, "video_codec":"h265", "bit_rate":"5m", "crop":"limit" } ] }, { "transformation":[ { "width":900, "height":900, "video_codec":"h265", "bit_rate":"3500k", "crop":"limit" } ] }, { "transformation":[ { "width":600, "height":600, "video_codec":"h265", "bit_rate":"1500k", "crop":"limit" } ] }, { "transformation":[ { "width":1200, "height":1200, "video_codec":"vp9", "bit_rate":"5m", "crop":"limit" } ] }, { "transformation":[ { "width":900, "height":900, "video_codec":"vp9", "bit_rate":"3500k", "crop":"limit" } ] }, { "transformation":[ { "width":600, "height":600, "video_codec":"vp9", "bit_rate":"1500k", "crop":"limit" } ] } ] } }
Update an existing streaming profile
Update the specified existing streaming profile. You can update both custom and built-in profiles. The specified list of representations replaces the previous list.
Syntax
PUT /streaming_profiles
Required parameters
Parameter | Type | Description |
---|---|---|
name | String | The identification name to assign to the new streaming profile. The name is case-insensitive and can contain alphanumeric characters, underscores (_) and hyphens (-). |
representations | JSON string | An array of structures that defines a custom streaming profile. |
transformation | String or Hash | Specifies the transformation parameters for the representation. All video transformation parameters except video_sampling are supported. Common transformation parameters for representations include: width , height (or aspect_ratio ), bit_rate , video_codec , audio_codec , sample_rate (or fps ), etc. |
Optional parameters
Parameter | Type | Description |
---|---|---|
display_name | String | A descriptive name for the profile. |
Examples
Add a fourth (fallback) representation to an existing custom streaming profile:
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", [ "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->updateStreamingProfile("custom_square", [ "representations" => [ ["transformation" => ["crop" => "limit", "width" => 1200, "height" => 1200, "bit_rate" => "5m"]], ["transformation" => ["crop" => "limit", "width" => 900, "height" => 900, "bit_rate" => "3500k"]], ["transformation" => ["crop" => "limit", "width" => 600, "height" => 600, "bit_rate" => "1500k"]], ["transformation" => ["crop" => "limit", "width" => 320, "height" => 320, "bit_rate" => "192k"]]]]);
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")));
curl \ -d 'representations=\[\{%22transformation%22:%22c_limit,w_1200,h_1200,br_5m%22\},\{%22transformation%22:%22c_limit,w_900,h_900,br_3500k%22\},\{%22transformation%22:%22c_limit,w_600,h_600,br_1500k%22\},\{%22transformation%22:%22c_limit,w_320,h_320,br_192k%22\}\]' \ -X PUT \ https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/streaming_profiles/custom_square
cld admin update_streaming_profile "custom_square" representations='[{"transformation": {"crop": "limit", "width": 1200, "height": 1200, "bit_rate": "5m"}},{"transformation": {"crop": "limit", "width": 900, "height": 900, "bit_rate": "3500k"}},{"transformation": {"crop": "limit", "width": 600, "height": 600, "bit_rate": "1500k"}},{"transformation": {"crop": "limit", "width": 320, "height": 320, "bit_rate": "192k"}}]'
Sample response
The response contains details for the streaming profile that was updated.
{ "message": "updated", "data": { "name": "custom_square", "display_name": "Custom square resolution", "predefined": false, "representations": [ { "transformation": { "width": 1200, "height": 1200, "bit_rate": "5m", "video_codec": "h264:main:3.1" } }, { "transformation": { "width": 900, "height": 900, "bit_rate": "3500k", "video_codec": "h264:main:3.1" } }, { "transformation": { "width": 600, "height": 600, "bit_rate": "1500k", "video_codec": "h264:baseline:3.0" } } { "transformation": { "width": 320, "height": 320, "bit_rate": "192k", "video_codec": "h264:baseline:3.0" } } ] } }
Delete or revert the specified streaming profile
For custom streaming profiles, delete the specified profile.
For built-in streaming profiles, if the built-in profile was modified, revert the profile to the original settings.
For built-in streaming profiles that have not been modified, the Delete method returns an error.
Syntax
DELETE /streaming_profiles/:name
Required parameters
Parameter | Type | Description |
---|---|---|
name | String | The name of the streaming profile to delete or revert. |
Examples
Delete the custom_square streaming file:
Sample response
Tags
Enables you to retrieve a list of all the tags currently used for a specified resource_type.
Methods | Description |
---|---|
GET /tags |
Get tags |
Get tags
Syntax
GET /tags/:resource_type
Optional parameters
Parameter | Type | Description |
---|---|---|
resource_type | String | The type of asset. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Possible values: image (default), raw , video . |
prefix | String | Find all tags that start with the given prefix. |
max_results | Integers | Maximum number of assets to return (up to 500). Default: 10 . |
next_cursor | String | When a request has more results to return than max_results , the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of a following request. |
Examples
List tags for all images
List tags that start with 'pro' for all images:
Sample response
Usage
Enables you to get a report on the status of your Cloudinary account usage details, including storage, credits, bandwidth, requests, number of resources, and add-on usage. Note that numbers are updated periodically.
Methods | Description |
---|---|
GET /usage |
Get account usage details |
Get account usage details
Syntax
GET /usage
Optional parameters
Parameter | Type | Description |
---|---|---|
date | String | The date for the usage report. Must be within the last 3 months and given in the format: dd-mm-yyyy . Default: the current date |
Examples
Return a usage report for the 10th of November, 2019 (10-11-2019):
Sample response
The response contains an object with detailed usage information.
{ "plan": "Basic", "last_updated": "2019-11-10", "transformations": {"usage": 1218018, "credits_usage": 1.22}, "objects": {"usage": 1217216}, "bandwidth": {"usage": 268903064875, "credits_usage": 0.24}, "storage": {"usage": 10298444599, "credits_usage": 0.01}, "credits": {"usage": 1.47}, "requests": 877212, "resources": 1239, "derived_resources": 10091, "url2png": {"usage": 15, "limit": 50}, "webpurify": {"usage": 28, "limit": 50}, "aspose": {"usage": 40, "limit": 50}, "style_transfer": {"usage": 76, "limit": 5000}, "azure_video_indexer": {"usage": 2340, "limit": 5000}, "object_detection": {"usage": 340, "limit": 500}, "media_limits": { "image_max_size_bytes": 157286400, "video_max_size_bytes": 3145728000, "raw_max_size_bytes": 2097152000, "image_max_px": 100000000, "asset_max_total_px": 300000000 } }
Ping
Enables you to test the reachability of the Cloudinary API with the ping method.
Methods | Description |
---|---|
GET/ping |
Ping Cloudinary servers |
Ping Cloudinary servers
Syntax
GET /ping
Sample response
The response contains the current status of the Cloudinary servers.