Last updated: Oct-09-2024
The Upload API is a rate-unlimited RESTful API that enables you to upload your media assets (resources) and provides a wide range of functionality, including basic and advanced asset management, metadata management, and asset generation.
Cloudinary's backend SDKs wrap these REST APIs, handle authentication, and enable you to perform these methods using your preferred programming language or framework. This reference provides both SDK and REST/cURL syntax and examples for each endpoint method.
Overview
By default, the API endpoints use the following format:
https://api.cloudinary.com/v1_1/:cloud_name/:action
For example, to upload an image asset to the demo
product environment:
Your Cloudinary Cloud name and API Key (which can be found on the API Keys page of the Cloudinary Console Settings) are used for the authentication.
All the methods in this API also require a signature, for which you need your API Secret, to authenticate the request on the Cloudinary servers. The Cloudinary SDKs automatically generate this signature for you, so you only need to add it when using the REST API calls directly to the endpoint. For more details on how to manually generate a signature, see the Generating authentication signatures documentation.
You can upload an image on your own Cloudinary product environment by replacing the CLOUD_NAME
, FILE
, TIMESTAMP
, API_KEY
, and SIGNATURE
in the cURL command below:
Responses to API calls include information about the action that was performed as well as data about the relevant assets.
After you upload files, you can use the Cloudinary Admin API, which has useful methods for managing and organizing your media assets, such as listing all uploaded assets, listing tags, finding all assets that share a given tag, updating transformations, bulk deleting, and more.
Using Postman for Upload REST API calls
Take advantage of our Cloudinary Postman Collections to experiment with our REST APIs and view the responses before adding them to your own code.
For details on setting up your own fork of our collections and configuring your Postman environment with your Cloudinary product environment credentials, see Using Cloudinary Postman collections.
Using SDKs with the Upload API
Our backend SDK libraries provide a wrapper for the Upload 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 create an image asset saved to your Cloudinary product environment from a string passed as a parameter:
Using the CLI to access the Upload API
You can use the Cloudinary CLI (Command Line Interface) to interact with the Upload API. This can provide an easy way to add automation to your workflows and manage your assets without the need for a formal coding environment or having to access your Cloudinary Console.
You can find instructions for setting up and using the CLI in the CLI reference.
Error handling
The Admin API returns the status of requests using HTTP status codes:
200: OK | Success.
400: Bad request.
401: Authorization required.
403: Not allowed.
404: Not found.
409: Already exists.
The SDKs report errors by raising applicative exceptions. Additionally, an informative JSON message is returned. For example:
EU or AP 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
Asset management
Enables you to perform basic and advanced management tasks on your assets.
Method | Description |
---|---|
POST/:resource_type/upload
|
Uploads an asset to a Cloudinary product environment. |
POST/:resource_type/explicit
|
Applies actions to existing assets. |
POST/:resource_type/rename
|
Renames an asset. |
POST/:resource_type/destroy
|
Destroys an asset. |
GET/download_backup
|
Gets a specific version of a backed-up asset. |
upload
The upload
method is used to upload assets to the cloud.
For additional information and examples, see the Upload guide. The Cloudinary SDKs wrap the upload method and offer two separate methods: one for signed uploading and one for unsigned uploading.
Signed upload syntax
POST /:resource_type/upload
Unsigned upload syntax
POST /:resource_type/upload
Required parameters
Parameter | Type | Description |
---|---|---|
file | String | The file to upload. It can be:
|
upload_preset | String | (Required for unsigned uploading / optional for signed uploading) Name of an upload preset that you defined for your Cloudinary product environment. An upload preset consists of upload parameters centrally managed using the Admin API or from the Upload page of the Console Settings. An upload preset may be marked as unsigned, which allows unsigned uploading directly from the browser and restricts the optional parameters to: public_id , folder , tags , context , face_coordinates , regions and custom_coordinates . |
signature | String | (Required for signed REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs for signed requests, the signature is automatically generated and added to the request. If you manually generate your own signed POST request, you need to manually generate the signature parameter and add it to the request together with the api_key and timestamp parameters. For more details, see manually generating signatures. |
Optional parameters
Parameter | Type | Description |
---|---|---|
Naming and storage: |
||
public_id | String | The identifier that's used for accessing and delivering the uploaded asset. If not specified, then the public ID of the asset will either be comprised of random characters or will use the original file's filename, depending whether use_filename was set to true.Notes:
|
public_id_prefix | String | A string or path that's automatically prepended to the public_id with a forward slash. The value can contain the same characters as the public_id including additional forward slashes. This prefix can be useful to provide context and improve the SEO of an asset's filename in the delivery URL, but the value does not impact the location where the asset is stored. Not relevant for product environments using the legacy fixed folder mode. |
display_name | String | A user-friendly name for the asset. Default: Same value as the
Not relevant for product environments using the legacy fixed folder mode. |
asset_folder | String | The folder where the asset is placed within the Cloudinary repository. This value does not impact the asset’s public ID path (unless the use_asset_folder_as_public_id_prefix option is applied).Default: If not specified, the uploaded asset will be located in the root of your product environment asset repository, even if the public ID value includes slashes. Not relevant for product environments using the legacy fixed folder mode. |
use_asset_folder_as_public_id_prefix | Boolean | Whether to add the asset_folder value as a prefix to the public_id value (prepended with a forward slash). This ensures that the public ID path will always match the initial asset folder, and can help to retain the behavior that previously existed in fixed folder mode. However, keep in mind that even when this option is used during upload, an asset with a certain public ID path can later be moved to a completely different asset folder hierarchy without impacting the public ID. This option only ensures path matching for the initial upload.Relevant only when Default: Not relevant for product environments using the legacy fixed folder mode. |
folder | String |
Only relevant for product environments using the legacy fixed folder mode. Defines both the full path of the folder where the uploaded asset will be placed and also a path value that's prepended to Default: root folder. Note: If Dynamic folders mode is enabled on your product environment, this parameter is deprecated, and it's recommended to use the |
use_filename | Boolean | Whether to use the original file name of the uploaded file as the public_id . Relevant only if the public_id parameter isn't set. When false and the public_id parameter is also not defined, the public ID will be comprised of random characters. When true and the public_id parameter is not defined, the uploaded file's original filename becomes the public ID. Random characters are appended to the filename value to ensure public ID uniqueness if unique_filename is true. If the filename of the asset you upload contains a character that's not supported for public IDs, preceding/trailing occurrences are trimmed off, while illegal characters anywhere else in the filename are replaced with underscores. Default: |
use_filename_as_display_name | Boolean | Whether to automatically assign the original filename of the uploaded asset as the asset's display name. Relevant only if the display_name parameter isn't set.Note: If you set Default: Not relevant for product environments using the legacy fixed folder mode. |
unique_filename | Boolean | When set to false, does not add random characters at the end of the filename that guarantee its uniqueness. Note that if the overwrite parameter is also false, the public ID will be comprised of random characters. This parameter is relevant only if use_filename is also set to true. Default: true . |
filename_override | String | Sets the 'original-filename' metadata header stored on the asset (instead of using the actual filename of the uploaded file). Useful together with the use_filename parameter and for advanced search by filename, and relevant when delivering assets as attachments (setting the flag transformation parameter to attachment ). |
resource_type | String | Set the type of file you are uploading or use auto to automatically detect the file type. Only relevant as a parameter when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Valid values: image , raw , video and auto . Defaults: image for server-side uploading (with the exception of the Go SDK which defaults to auto ) and auto for client-side uploading.
Note: Use the video resource type for all video assets as well as for audio files, such as .mp3 . |
type | String | The delivery type. Allows uploading assets as private or authenticated instead of the default upload mode. Only relevant as a parameter when using the SDKs (the delivery type value is part of the endpoint URL when using the REST API). Valid values: upload , private and authenticated . Default: upload . |
access_control | JSON | Restrict access to the asset by passing an array of access types for the asset. The asset is restricted unless one of the access types is valid. Possible values for each access type: - token requires either Token-based access or Cookie-based access for accessing the asset. For example: access_type: "token" - anonymous allows public access to the asset. The anonymous access type can optionally include start and/or end dates (in ISO 8601 format) that define when the asset is publicly available. Note that you can only include a single 'anonymous' access type. For example: access_type: "anonymous", start: "2017-12-15T12:00Z", end: "2018-01-20T12:00Z"
|
access_mode | String | Allows the asset to behave as if it's of the authenticated 'type' (see above) while still using the default 'upload' type in delivery URLs. The asset can later be made public by changing its access_mode via the Admin API, without having to update any delivery URLs. Valid values: public , and authenticated . Default: public . |
discard_original_filename | Boolean | Whether to discard the name of the original uploaded file. Relevant when delivering assets as attachments (setting the flag transformation parameter to attachment ). Default: false . |
overwrite | Boolean | Whether to overwrite existing assets with the same public ID. When set to false, a response is returned immediately if an asset with the same public ID was found. When overwriting assets, if you include versions in your delivery URLs, you will need to update the URLs with the new version number to deliver the new asset. If you don't include versions, you will need to invalidate the old assets on the CDN server cache.
Default: true (when using unsigned upload, the default is false and cannot be changed to true). Important: Depending on your product environment setup, overwriting an asset may clear the tags, contextual, and structured metadata values for that asset. If you have a Master admin role, you can change this behavior for your product environment in the Media Library Preferences pane, so that these field values are retained when new version assets overwrite older ones (unless you specify different values for the |
Resource data: |
||
tags | String | A comma-separated list of tag names to assign to the uploaded asset for later group reference. For example: animal,dog SDKs: Supports arrays. For example: ['animal', 'dog']
|
context | String | A pipe-separated list of the key-value pairs of contextual metadata to attach to an uploaded asset. The context values of uploaded files can be retrieved using the Admin API. For example: alt=My image|caption=Profile image Notes:
['alt': 'My image', 'caption': 'Profile image']
|
metadata | String | A pipe-separated list of custom metadata fields (by external_id ) and the values to assign to each of them. For example: in_stock_id=50|color_id=[\"green\",\"red\"] .
SDKs: Supports maps. Notes:
|
clear_invalid | Boolean | (Relevant for cascading metadata, and assets with multiple metadata fields) When updating the value of a metadata field results in another metadata field’s value becoming invalid, that invalid value is cleared instead of resulting in an error. Default: false . |
colors | Boolean | Whether to retrieve predominant colors & color histogram of the uploaded image. Note:If all returned colors are opaque, then 6-digit RGB hex values are returned. If one or more colors contain an alpha channel, then 8-digit RGBA hex quadruplet values are returned. Default: false . Relevant for images only. |
faces | Boolean | Whether to return the coordinates of faces contained in an uploaded image (automatically detected or manually defined). Each face is specified by the X & Y coordinates of the top left corner and the width & height of the face. The coordinates for each face are returned as an array (using the SDKs) or a comma-separated list (for REST API calls), and individual faces are separated with a pipe (| ). For example: 10,20,150,130|213,345,82,61 . Default: false . Relevant for images only. |
quality_analysis | Boolean | Whether to return a quality analysis value for the image between 0 and 1, where 0 means the image is blurry and out of focus and 1 means the image is sharp and in focus. Default: false . Relevant for images only.Paid customers can request to take part in the extended quality analysis Beta trial. When activated, this parameter returns quality scores for various other factors in addition to focus , such as jpeg_quality , noise , exposure , lighting and resolution , together with an overall weighted quality_score . The quality_score , quality_analysis.color_score and quality_analysis.pixel_score fields can be used in the Search API. |
accessibility_analysis | Boolean | Currently available only to paid customers requesting to take part in the accessibility analysis Beta trial. Set to true to return accessibility analysis values for the image and to enable the accessibility_analysis.colorblind_accessibility_score field to be used in the Search API.Default: false . Relevant for images only. |
cinemagraph_analysis | Boolean | Whether to return a cinemagraph analysis value for the media asset between 0 and 1, where 0 means the asset is not a cinemagraph and 1 means the asset is a cinemagraph. Default: false . Relevant for animated images and video only. A static image will return 0. |
image_metadata | Boolean | Deprecated. Use media_metadata instead. Default: false . |
media_metadata | Boolean | Whether to return IPTC, XMP, and detailed Exif metadata of the uploaded asset in the response. Default: false . Supported for images, video, and audio.
Metadata .) |
phash | Boolean | Whether to return the perceptual hash (pHash) on the uploaded image. The pHash acts as a fingerprint that allows checking image similarity. Default: false . Relevant for images only. |
responsive_breakpoints | [JSON] | Requests that Cloudinary automatically find the best breakpoints. The parameter value is an array of breakpoint request settings, where each request setting can include the following parameters:
transformation , width , height , bytes , url and secure_url . Relevant for images only. |
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 |
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. |
detection | String | Invokes the relevant add-on to return a list of detected content. Set to:
Relevant for images only. |
auto_chaptering | Boolean | Whether to trigger automatic generation of video chapters. Chapters will be generated and saved as a .vtt file with -chapters appended to the public ID of the video. You can enable chapters as part of the Cloudinary Video Player. Default: false . Relevant for videos only. |
auto_transcription | Boolean | Whether to trigger automatic video transcription. The transcript will be generated and saved as a .transcript file with the same public ID as the video. You can use your transcript file to show subtitles or captions using the Cloudinary Video Player. Default: false . Relevant for videos 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. |
visual_search | Boolean | Whether to index the image for use with visual searches. Default: false. Relevant for images only. |
exif | Boolean | Whether to retrieve the Exif metadata of the uploaded photo. Default: false. Deprecated - use media_metadata instead
|
Manipulations: |
||
eager | String | A list of transformations to create for the uploaded asset, instead of lazily creating them when first accessed by your site's visitors (see the Transformation URL API Reference for more details on possible values). This option accepts either a single transformation or a pipe-separated list of transformations to create for the uploaded asset.
SDKs: Supports arrays. (In .NET SDK, parameter name is EagerTransforms .) |
eager_async | Boolean | Whether to generate the eager transformations asynchronously in the background after the upload request is completed rather than online as part of the upload call. Default: false . |
eager_notification_url | String | An HTTP or HTTPS URL to send a notification to (a webhook) when the generation of eager transformations is completed. |
transformation | String | An incoming transformation to run on the uploaded asset before saving it in the cloud. This parameter is given as a string of comma-separated single characters (separated with a slash for chained transformations).SDKs: Supports a hash of transformation parameters (or an array of hashes for chained transformations). Note: When using the SDK for a dynamically-typed language such as Ruby, the transformation parameters can be specified directly without using this |
format | String | An optional format to convert the uploaded asset to before saving in the cloud. For example: jpg . |
custom_coordinates | String | The coordinates of a region contained in the image being uploaded that can be subsequently used for cropping or adding layers 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, as a comma-separated list. For example: 85,120,220,310 . Relevant for images only. SDKs: Supports arrays. For example: |
regions | JSON | The coordinates of one or more named regions contained in the image being uploaded that can be subsequently used for cropping using the region gravity mode. Each region is specified by a name (alphanumeric characters and hyphens permitted) and an array of at least two X,Y coordinate pairs, e.g., { "name1": [[1, 2], [3, 4]], "name2": [[5,6], [7,8], [9,10]] } . If two pairs are specified, these refer to the top left and bottom right coordinates of a rectangle. Otherwise, if more pairs are specified, they refer to the corners of a custom region.Relevant for images only. |
face_coordinates | String | The coordinates of faces contained in an uploaded image to 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 for each face are given as a comma-separated list, with individual faces separated with a pipe (| )). For example: 10,20,150,130|213,345,82,61 . Relevant for images only. SDKs: Supports arrays. For example: |
background_removal | String | Automatically remove the background of an image using an add-on.
|
raw_convert | String | Generates a related file based on the uploaded file.
See also: Converting raw files. |
Additional options: |
||
allowed_formats | String | A comma-separated list of file formats that are allowed for uploading. Files of other types will be rejected. The formats can be any combination of image types, video formats or raw file extensions. For example: mp4,ogv,jpg,png,pdf . Default: any supported format for images and videos, and any kind of raw file (i.e. no restrictions by default).
SDKs: Supports arrays. For example: [mp4, ogv, jpg, png, pdf]
Note: You can also add the format parameter to convert other file types instead of rejecting them. In this case, only files that would normally be rejected are converted, any file format allowed for upload wont be converted. |
async | Boolean | Tells Cloudinary whether to perform the upload request in the background (asynchronously). Default: false .Note: In the Python SDK, this parameter is passed as a dictionary: |
backup | Boolean | Tell Cloudinary whether to back up the uploaded asset. Overrides the default backup settings of your product environment. |
callback | String | A URL to redirect to after the upload is completed instead of returning the upload response. Signed upload result parameters are added to the callback URL. This parameter is ignored for XHR (Ajax XMLHttpRequest) or JavaScript Fetch API upload requests. Note: This parameter is relevant for direct uploads from a form in the browser. It is automatically set if you perform direct upload from the browser using Cloudinary's SDKs and the jQuery plugin. |
eval | String | Allows you to modify upload parameters by specifying custom logic with JavaScript. This can be useful for conditionally adding tags, contextual metadata, structured metadata or eager transformations depending on specific criteria of the uploaded file. For more details see Evaluating and modifying upload parameters. |
on_success | String | Allows you to update an asset by specifying custom logic with JavaScript that is executed after the upload to Cloudinary is completed successfully. This can be useful for conditionally adding tags, contextual metadata, and structured metadata, depending on the results of using the detection parameter on upload. For more details see On Success update script. |
headers | String | An HTTP header or a list of headers lines for adding as response HTTP headers when delivering the asset to your users. Supported headers: Link , Authorization , X-Robots-Tag . For example: X-Robots-Tag: noindex . |
invalidate | Boolean | Whether to invalidate CDN cached copies of a previously uploaded asset (and all transformed versions that share the same public ID). Default: false . 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 when using the invalidate functionality. |
moderation | String |
For all asset types, set to:
|
notification_url | String | An HTTP or HTTPS URL to receive the upload response (a webhook) when the upload or any requested asynchronous action is completed. If not specified, the response is sent to the Notification URL (if defined) in the Webhook Notifications settings of your Cloudinary Console. |
proxy | String | Tells Cloudinary to upload assets from remote URLs through the given proxy. Format: https://hostname:port . |
return_delete_token | Boolean | Whether to return a deletion token in the upload response. The token can be used to delete the uploaded asset within 10 minutes using an unauthenticated API request. Default: false . |
timeout | Integer | (SDKs only) Add this parameter to override the maximum amount of time to wait for a response from Cloudinary before the connection is terminated. |
Unsigned upload parameters
Unsigned requests are restricted to the following allowed parameters: public_id
, folder
, callback
, tags
, context
, face_coordinates
(images only), custom_coordinates
(images only), regions
(images only) and upload_preset
. Most of the other upload parameters can be defined in your upload_preset
.
Additionally, although the public_id
parameter can be specified, the overwrite
parameter is always set to 'false' for unsigned uploads to prevent overwriting existing files.
Examples
To upload an image by specifying the local path /home/sample.jpg
:
To upload an image from a remote url: https://www.example.com/sample.jpg
and request Cloudinary to find the best breakpoints based on the following guidelines: a minimum width of 200 pixels, a maximum width of 1000 pixels, at least 20000 bytes file size difference between the breakpoints, while keeping the generated derived images:
To upload an image from a remote FTP private server ftp://ftp.example.com/sample.jpg
with a username of user1
and a password of mypass
. Two transformed images are also eagerly generated as follows:
- Pad to a width of 400 pixels and height of 300 pixels.
- Crop to a width of 260 pixels and a height of 200 pixels with north gravity.
\
or "
, for example, \"text\"
or ""text""
.Sample response
The following is a sample response based on the example upload of sample.jpg
with two eager transformations and a request for detailed metadata (media_metadata = true
). Because no public_id was specified in the upload, a random public_id was assigned.
- The response for asynchronous uploads (when setting
async = true
) only includes a few details such as thestatus
(pending) and abatch_id
for tracking. Once the upload completes, thenotification_url
set for the asynchronous upload will receive the full response including the details in the example above. - If the public ID of the asset you're uploading already exists, the upload response includes whether the asset was
overwritten
orexisting
(depending on whether theoverwrite
parameter was set to true or false).
explicit
The explicit
method is used to apply actions to existing assets. The most common usage of this method is to eagerly generate transformations for assets that have already been uploaded, either so that they do not need to be generated on the fly when first accessed by users, or because Strict transformations are enabled for your product environment and you cannot create transformed assets on the fly. You can also use this method to pre-generate transformations for remotely fetched assets.
For more information, see Updating existing assets.
Syntax
POST /:resource_type/explicit
Required parameters
Parameter | Type | Description |
---|---|---|
public_id | String | The identifier of the uploaded asset or the URL of the remote asset. Note: The public ID value for images and videos should not include a file extension. Include the file extension for raw files only. |
type | String | The delivery type of the asset. For a list of all possible delivery types, see Delivery types. |
signature | String | (Required for signed REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs for signed requests, the signature is automatically generated and added to the request. If you manually generate your own signed POST request, you need to manually generate the signature parameter and add it to the request together with the api_key and timestamp parameters. For more details, see manually generating signatures. |
Optional parameters
Parameter | Type | Description |
---|---|---|
resource_type | String | The type of asset. Only relevant as a parameter when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Valid values: image , raw , and video . Default: image .
Note: Use the video resource type for all video assets as well as for audio files, such as .mp3 . |
display_name | String | A user-friendly name for the asset.
Not relevant for product environments using the legacy fixed folder mode. |
asset_folder | String | The folder where the asset is placed within the Cloudinary repository. Setting this value in an Not relevant for product environments using the legacy fixed folder mode. |
eager | String | A list of transformations to create for the uploaded asset, instead of lazily creating them when first accessed by your site's visitors (see the Transformation URL API Reference for more details on possible values). This option accepts either a single transformation or a pipe-separated list of transformations to create for the uploaded asset.
SDKs: Supports arrays. (In .NET SDK, parameter name is EagerTransforms .) |
async | Boolean | Whether to perform the request in the background (asynchronously). Default: false . |
eager_async | Boolean | Determines whether to generate the eager transformations asynchronously in the background. Default: false . |
eager_notification_url | String | An HTTP or HTTPS URL to notify your application (a webhook) when the generation of eager transformations is completed. |
overwrite | Boolean | When applying eager for already existing video transformations, this setting indicates whether to force the existing derived video resources to be regenerated. Default for videos: false .
Note: When specifying existing eager transformations for images, corresponding derived images are always regenerated. |
tags | String | A comma-separated list of tag names to assign to an asset that replaces any current tags assigned to the asset (if any). For example: animal,dog SDKs: Supports arrays. For example: ['animal', 'dog']
|
invalidate | Boolean | Whether to invalidate the asset (and all its derived assets) on the CDN. Default: false . 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 when using the invalidate functionality. |
context | String | A pipe-separated list of the key-value pairs of contextual metadata to attach to an uploaded asset. The context values of uploaded files can be retrieved using the Admin API. For example: alt=My image|caption=Profile image Notes:
['alt': 'My image', 'caption': 'Profile image']
|
metadata | String | A pipe-separated list of custom metadata fields (by external_id ) and the values to assign to each of them. For example: in_stock_id=50|color_id=[\"green\",\"red\"] .
SDKs: Supports maps. Notes:
|
headers | String | An HTTP header or a list of headers lines for returning as response HTTP headers when delivering the uploaded asset to your users. Supported headers: Link , X-Robots-Tag . For example: X-Robots-Tag: noindex . |
face_coordinates | String | The coordinates of faces contained in an uploaded image to 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 for each face are given as a comma-separated list, with individual faces separated with a pipe (| ). For example: 10,20,150,130|213,345,82,61 . Relevant for images only. SDKs: Supports arrays. For example: |
custom_coordinates | String | The coordinates of a region contained in an uploaded image that can be subsequently used for cropping or adding layers 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, as a comma-separated list. For example: 85,120,220,310 . Relevant for images only.SDKs: Supports arrays. For example: |
regions | JSON | The coordinates of one or more named regions contained in an uploaded image that can be subsequently used for cropping using the region gravity mode. Each region is specified by a name (alphanumeric characters and hyphens permitted) and an array of at least two X,Y coordinate pairs, e.g., { "name1": [[1, 2], [3, 4]], "name2": [[5,6], [7,8], [9,10]] } . If two pairs are specified, these refer to the top left and bottom right coordinates of a rectangle. Otherwise, if more pairs are specified, they refer to the corners of a custom region.Relevant for images only. |
notification_url | String | An HTTP or HTTPS URL to send the notification to (a webhook) when the operation or any additional requested asynchronous action is completed. If not specified, the response is sent to the Notification URL (if defined) in the Webhook Notifications settings of your Cloudinary Console. |
image_metadata | Boolean | Deprecated. Use media_metadata instead. Default: false . |
media_metadata | Boolean | Whether to return IPTC, XMP, and detailed Exif metadata of the uploaded asset in the response. Default: false . Supported for images, video, and audio.
Metadata .) |
colors | Boolean | Whether to retrieve predominant colors & color histogram of the uploaded image. If one or more colors contain an alpha channel, then 8-digit RGBA hex quadruplet values are returned. Default: false . Relevant for images only. |
phash | Boolean | Whether to return the perceptual hash (pHash) on the uploaded image. The pHash acts as a fingerprint that allows checking image similarity. Default: false . Relevant for images only. |
faces | Boolean | Whether to return the coordinates of faces contained in an uploaded image (automatically detected or manually defined). Each face is specified by the X & Y coordinates of the top left corner and the width & height of the face. The coordinates for each face are returned as an array (using the SDKs) or a comma-separated list (for REST API calls), and individual faces are separated with a pipe (| ). For example: 10,20,150,130|213,345,82,61 . Default: false . Relevant for images only. |
quality_analysis | Boolean | Whether to return a quality analysis value for the image between 0 and 1, where 0 means the image is blurry and out of focus and 1 means the image is sharp and in focus. Default: false . Relevant for images only.Paid customers can request to take part in the extended quality analysis Beta trial. When activated, this parameter returns quality scores for various other factors in addition to focus , such as jpeg_quality , noise , exposure , blockiness and resolution , together with an overall weighted quality_score . Note: Unlike when used with the upload method, the returned quality_score , quality_analysis.color_score and quality_analysis.pixel_score fields are not indexed for search. |
accessibility_analysis | Boolean | Currently available only to paid customers requesting to take part in the accessibility analysis Beta trial. Set to true to return accessibility analysis values for the image.Default: false . Relevant for images only. Note: Unlike when used with the upload method, the accessibility_analysis.colorblind_accessibility_score field is not indexed for search. |
quality_override | String | Sets a quality value to override the value used when the image is encoded with Cloudinary's automatic content-aware quality algorithm. |
cinemagraph_analysis | Boolean | Whether to return a cinemagraph analysis value for the media asset between 0 and 1, where 0 means the asset is not a cinemagraph and 1 means the asset is a cinemagraph. Default: false . Relevant for animated images and video only. A static image will return 0. |
moderation | String |
For all asset types, set to:
|
responsive_breakpoints | [JSON] | Requests that Cloudinary automatically find the best breakpoints. The parameter value is an array of breakpoint request settings, where each request setting can include the following parameters:
transformation , width , height , bytes , url and secure_url . Relevant for images only. |
auto_chaptering | Boolean | Whether to trigger automatic generation of video chapters. Chapters will be generated and saved as a .vtt file with -chapters appended to the public ID of the video. You can enable chapters as part of the Cloudinary Video Player. Default: false . Relevant for videos only. |
auto_transcription | Boolean | Whether to trigger automatic video transcription. The transcript will be generated and saved as a .transcript file with the same public ID as the video. You can use your transcript file to show subtitles or captions using the Cloudinary Video Player. Default: false . Relevant for videos only. |
Example
To perform two eager transformations for the already uploaded image with a public ID of sample
as follows:
- Crop to a width and height of 400 pixels including the biggest face detected.
- Pad to a width of 660 pixels and a height of 400 pixels with a blue background.
explicit
, the transformation is processed upon request (and counted in your transformation quota) even if an identical derived asset already exists.Sample response
The following is a sample response based on the example above. Two explicit transformations were performed on the sample
image.
rename (public ID)
Modifies the public ID (or optionally the delivery type) of an existing asset.
rename
method on an asset, the asset's existing URL and its associated derived assets are no longer valid, although delivery URLs already requested by visitors of your web site or application might still be accessible for a certain period of time through cached copies on the CDN. To bypass the CDN caching, you can include the invalidate
parameter in your POST request in order to also invalidate the cached copies of the asset on the CDN. It usually takes between a few seconds and a few minutes for the invalidation to fully propagate through the CDN. For details on invalidating assets, see Invalidating cached media assets on the CDN.
Syntax
POST /:resource_type/rename
Required parameters
Parameter | Type | Description |
---|---|---|
from_public_id | String | The current identifier of the uploaded asset. |
to_public_id | String | The new identifier to assign to the uploaded asset. |
signature | String | (Required for signed REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs for signed requests, the signature is automatically generated and added to the request. If you manually generate your own signed POST request, you need to manually generate the signature parameter and add it to the request together with the api_key and timestamp parameters. For more details, see manually generating signatures. |
Optional parameters
Parameter | Type | Description |
---|---|---|
resource_type | String | The type of asset to rename. Only relevant as a parameter when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Valid values: image , raw , video . Default: image .
Note: Use the video resource type for all video assets as well as for audio files, such as .mp3 . |
type | String | The delivery type of the asset. Only relevant as a parameter when using the SDKs (the delivery type is included in the endpoint URL when using the REST API). Valid values: upload , private , authenticated . Default: upload . |
to_type | String | The new delivery type for the asset. Valid values: upload , private , authenticated . Default: the asset's current type is unchanged. |
overwrite | Boolean | Whether to overwrite an existing asset with the target public ID. Default: false .Important: Depending on your product environment setup, overwriting an asset may clear the tags, contextual, and structured metadata values for that asset. If you have a Master admin role, you can change this behavior for your product environment in the Media Library Preferences pane, so that these field values are retained when new version assets overwrite older ones (unless you specify different values for the |
notification_url | String | An HTTP or HTTPS URL to notify your application (a webhook) when the process has completed. If not specified, the response is sent to the Notification URL (if defined) in the Webhook Notifications settings of your Cloudinary Console. |
invalidate | Boolean | Whether to invalidate CDN cached copies of the asset (and all its transformed versions). Default: false . 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 when using the invalidate functionality |
context | Boolean | Whether to include contextual metadata for the asset in the response. Default: false . |
metadata | Boolean | Whether to include structured metadata for the asset in the response. Default: false . |
Example
To rename an image from canyon
to grand_canyon
:
Sample response
The following is a sample response based on the example above. The canyon
image was renamed to grand_canyon
.
destroy
The destroy
method is used to immediately and permanently delete a single asset from your Cloudinary product environment (to delete multiple assets see the Admin API Delete resources method). Backed up assets are not deleted, and any assets and transformed assets already downloaded by visitors to your website might still be accessible through cached copies on the CDN.
To bypass the CDN caching, you can include the invalidate
parameter in your POST request in order to also invalidate the cached copies of the asset on the CDN. It usually takes between a few seconds and a few minutes for the invalidation to fully propagate through the CDN. For details on invalidating media assets, see Invalidating cached media assets on the CDN.
Syntax
POST /:resource_type/destroy
Required parameters
Parameter | Type | Description |
---|---|---|
public_id | String | The identifier of the uploaded asset. Note: The public ID value for images and videos should not include a file extension. Include the file extension for raw files only. |
signature | String | (Required for signed REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs for signed requests, the signature is automatically generated and added to the request. If you manually generate your own signed POST request, you need to manually generate the signature parameter and add it to the request together with the api_key and timestamp parameters. For more details, see manually generating signatures. |
Optional parameters
Parameter | Type | Description |
---|---|---|
resource_type | String | The type of asset to destroy. Only relevant as a parameter when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Valid values: image , raw , and video . Default: image .
Note: Use the video resource type for all video assets as well as for audio files, such as .mp3 . |
type | String | The delivery type of the asset. Only relevant as a parameter when using the SDKs (the type is included in the endpoint URL when using the REST API). Default: upload . For a list of all possible delivery types, see Delivery types. |
notification_url | String | An HTTP or HTTPS URL to notify your application (a webhook) when the process has completed. If not specified, the response is sent to the Notification URL (if defined) in the Webhook Notifications settings of your Cloudinary Console. |
invalidate | Boolean | If true, invalidates CDN cached copies of the asset (and all its transformed versions). Default: false . 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 when using the invalidate functionality. |
Examples
Deleting an image with the public ID of sample
:
Deleting a video with the public ID of sample
:
Sample response
A successful destroy
operation returns the following:
download_backup
The download_backup
method returns a specific version of a backed up asset without restoring it.
- The endpoint returns the specified version of the asset in bytes.
- The SDKs return a URL of the asset that can be used to download that version of the asset (within an hour of the request).
Syntax
GET /download_backup
Required parameters
Parameter | Type | Description |
---|---|---|
asset_id | String | The identifier of the uploaded asset. Note: This is returned in the response to various Admin API methods. |
version_id | String | The identifier of a backed up version of the asset. Note: To see details of backed up versions, including version_id , for a specific asset, use the resource method of the Admin API, setting the versions parameter to true. |
Example
To return the URL of a backed up version of an asset with asset_id
of 62c2a18d622be7e190d21df8e05b1416
and version_id
of 26fe6d95df856f6ae12f5678be94516a
(the cURL example returns the asset in bytes):
Sample response
The following is a sample SDK response based on the example above. The URL to download the requested backed up version of the asset is returned.
Metadata management
Enables you to manage your assets' metadata.
Method | Description |
---|---|
POST/:resource_type/context
|
Manages the contextual metadata of an uploaded asset. |
POST/:resource_type/metadata
|
Adds values to metadata fields. |
POST/:resource_type/tags
|
Manages the tags applied to your assets. |
context
The context
parameter of an uploaded asset contains a pipe-separated list of key-value pairs of contextual metadata (up to 255 characters). The context
method can be used to manage the contextual metadata of an uploaded asset by setting the value of the command
parameter to either add
a new key-value pair, or remove_all
contextual metadata from the asset.
context
method and offer 2 separate methods: one for adding contextual metadata and one for removing all contextual metadata.Adding context syntax
POST /:resource_type/context
Removing all context syntax
POST /:resource_type/context
Required parameters
Parameter | Type | Description |
---|---|---|
context | String | (Only relevant when adding contextual metadata) A pipe-separated list of the key-value pairs of contextual metadata to attach to an uploaded asset. The contextual metadata values of uploaded files can be retrieved using the Admin API. For example: alt=My image|caption=Profile image Notes:
['alt': 'My image', 'caption': 'Profile image']
|
public_ids | String[] | An array of public IDs of assets uploaded to Cloudinary. |
command | String | (Only relevant when using the REST API - not for use with SDKs) The action to perform on assets: either add the specified contextual metadata, or remove_all the contextual metadata key-value pairs assigned. |
signature | String | (Required for signed REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs for signed requests, the signature is automatically generated and added to the request. If you manually generate your own signed POST request, you need to manually generate the signature parameter and add it to the request together with the api_key and timestamp parameters. For more details, see manually generating signatures. |
Optional parameters
Parameter | Type | Description |
---|---|---|
resource_type | String | The type of asset. Only relevant as a parameter when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Valid values: image , raw , and video . Default: image .
Note: Use the video resource type for all video assets as well as for audio files, such as .mp3 . |
type | String | The delivery type of the asset. Only relevant as a parameter when using the SDKs (the delivery type is included in the endpoint URL when using the REST API). Default: upload . For a list of possible delivery types, see Delivery types. |
Examples
To add the contextual metadata key-pairs alt=Animal
and class=Mammalia
to the images with the public IDs of dog
and lion
To remove all existing contextual metadata for the images with the public IDs of dog
and lion
Sample response
The following is a sample response based on the example above. A contextual metadata value was added to the dog
and lion
images.
metadata
The metadata
parameter of an uploaded asset contains a map (for SDKs) or pipe-separated list (for REST API calls) of key-value pairs of custom predefined metadata fields. The metadata
method can be used to add values to these metadata fields.
Syntax
POST /:resource_type/metadata
Required parameters
Parameter | Type | Description |
---|---|---|
metadata | String | A pipe-separated list of custom metadata fields (by external_id ) and the values to assign to each of them. For example: in_stock_id=50|color_id=[\"green\",\"red\"] .
SDKs: Supports maps. Notes:
|
public_ids | String[] | An array of public IDs of assets uploaded to Cloudinary. |
signature | String | (Required for signed REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs for signed requests, the signature is automatically generated and added to the request. If you manually generate your own signed POST request, you need to manually generate the signature parameter and add it to the request together with the api_key and timestamp parameters. For more details, see manually generating signatures. |
Optional parameters
Parameter | Type | Description |
---|---|---|
resource_type | String | The type of asset. Only relevant as a parameter when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Valid values: image , raw , and video . Default: image .
Note: Use the video resource type for all video assets as well as for audio files, such as .mp3 . |
type | String | The delivery type. Valid values: upload , private and authenticated . Default: upload
|
Example
To add the datasource IDs of "id_us", "id_uk", and "id_france" to the metadata field with id 'countryFieldId', to the images with the public IDs of 'shirt' and 'pants':
Sample response
The following is a sample response based on the example above. Metadata values were added to the shirt and pants images.
tags
Tags are used to categorize and organize your assets, and can also be used to apply group actions to assets, for example to delete assets, create sprites, ZIP files, JSON lists, or animated GIFs. A tag is a short name (up to 255 characters) that you can dynamically use (no need to predefine tags). Each asset can be assigned up to 1000 tags.
The tags
method can be used to manage asset tags by setting the value of the command
parameter to either add
, remove
, remove_all
, or replace
tags.
SDKs: The Cloudinary SDKs wrap the tags
method and offer 4 separate methods: one for adding tags, one for removing specific tags, one for removing all tags, and one for replacing tags.
Adding tags syntax
POST /:resource_type/tags
Removing tags syntax
POST /:resource_type/tags
Removing all tags syntax
POST /:resource_type/tags
Replacing tags syntax
POST /:resource_type/tags
Required parameters
Parameter | Type | Description |
---|---|---|
tag | String | The tag(s) to assign, remove, or replace. Not relevant when removing all tags. You can pass multiple tags as a single comma-separated list of tag names to assign. For example: animal,dog SDKs: Supports arrays. For example: |
public_ids | String | A list of public IDs for the assets you want to update. |
command | String | (Only relevant when using the REST API or the .NET SDK - not for use with other SDKs) The action to perform on the assets: either add the given tag, remove the given tag, remove_all the tags assigned, or replace the given tag, which adds the given tag while removing all other tags assigned. |
signature | String | (Required for signed REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs for signed requests, the signature is automatically generated and added to the request. If you manually generate your own signed POST request, you need to manually generate the signature parameter and add it to the request together with the api_key and timestamp parameters. For more details, see manually generating signatures. |
Optional parameters
Parameter | Type | Description |
---|---|---|
resource_type | String | The type of asset. Only relevant as a parameter when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Valid values: image , raw , and video . Default: image .
Note: Use the video resource type for all video assets as well as for audio files, such as .mp3 . |
type | String | The delivery type of the asset. Only relevant as a parameter when using the SDKs (the delivery type is included in the endpoint URL when using the REST API). Default: upload . For a list of possible delivery types, see Delivery types. |
Examples
To add the tag animal
to the images with the public IDs of dog
and lion
To remove the tag animal
from the images with the public IDs of dog
and lion
To remove all existing tags for the images with the public IDs of dog
and lion
To replace all existing tags with the tag animal
for the images with the public IDs of dog
and lion
Sample response
The following is a sample response based on the example above. A tag was added to the dog
and lion
images.
Asset generation
Enables you to create different types of assets from existing assets to be stored in your Cloudinary product environment.
Method | Description |
---|---|
POST/:resource_type/create_collage
|
Creates a collage from existing assets. |
POST/:resource_type/create_video
|
Creates a video from existing assets. |
POST/image/explode
|
Derives images for the individual pages in a multi-page file (PDF or animated GIF). |
POST/:resource_type/generate_archive
|
Creates an archive file from existing assets. |
POST/image/multi
|
Generates animated images, videos, or PDFs from existing images. |
POST/image/sprite
|
Generates sprites from existing assets. |
POST/image/text
|
Dynamically generates an image from a given textual string. |
create_collage
Cloudinary supports the creation of image collages by combining a number of assets together in a defined or custom layout. Creating a collage generates a new image asset in your Cloudinary storage. To create a collage you need to supply a manifest_json
that defines all the images, colors and positions as well as any image specific transformations.
Syntax
POST /image/create_collage
create_collage
so you need to call the REST API directly.
Required parameters
Parameter | Type | Description |
---|---|---|
manifest_json | String | The collage specific manifest transformation as stringified JSON that specifies the assets to use as well as the dimensions and layout of the collage, color spacing and any image specific transformations. See the collage generation reference for full details on syntax. |
signature | String | (Required for signed REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs for signed requests, the signature is automatically generated and added to the request. If you manually generate your own signed POST request, you need to manually generate the signature parameter and add it to the request together with the api_key and timestamp parameters. For more details, see manually generating signatures. |
upload_preset | String | (Required for unsigned uploading / optional for signed uploading) Name of an upload preset that you defined for your Cloudinary product environment. An upload preset consists of upload parameters centrally managed using the Admin API or from the Upload page of your Console Settings. An upload preset may be marked as unsigned, which allows unsigned uploading directly from the browser and restricts the optional parameters to: public_id , folder , tags , context , face_coordinates , regions and custom_coordinates . |
Optional parameters
Parameter | Type | Description |
---|---|---|
public_id | String | The identifier that is used for accessing the image collage. The public ID may contain a full path including folders separated by a slash (/ ). If not specified, then the public ID of the collage will be comprised of random characters.
Note: The public ID value for collages should not include a file extension. |
transformation | String | A transformation to apply to the collage after it has been generated. This parameter is given as a comma-separated list of transformations, and separated with a slash for chained transformations. |
overwrite | Boolean | Whether to overwrite existing assets with the same public ID. When set to false, a response is returned immediately if an asset with the same public ID was found. When overwriting assets, if you include versions in your delivery URLs, you will need to update the URLs with the new version number to deliver the new asset. If you don't include versions, you will need to invalidate the old assets on the CDN server cache.
Default: true (when using unsigned upload, the default is false and cannot be changed to true). Important: Depending on your product environment setup, overwriting an asset may clear the tags, contextual, and structured metadata values for that asset. If you have a Master admin role, you can change this behavior for your product environment in the Media Library Preferences pane, so that these field values are retained when new version assets overwrite older ones (unless you specify different values for the |
tags | String | A comma-separated list of tag names to assign to the collage for later group reference. For example: animal,dog . |
notification_url | String | An HTTP or HTTPS URL to notify your application (a webhook) when the process has completed. If not specified, the response is sent to the Notification URL (if defined) in the Webhook Notifications settings of your Cloudinary Console. |
Examples
Generate a collage using the defined 3x3 grid layout, setting the public ID to test_collage
:
Generate a collage using a custom layout, setting the public ID to custom_collage
:
Sample response
The following is a sample response based on the examples above. As collage generation occurs asynchronously, a notification is sent once the collage has been successfully generated. You can see an example of the notification response below.
create_video
Cloudinary supports the creation of videos by combining assets, text and colors together as tracks, including animations, effects and transitions. Creating a video generates a new video asset in your Cloudinary storage. To create a video you need to supply a manifest_json
that defines all the tracks, clips, keyframes, durations, transitions, and more. You can use the manifest_json
as a template with variables to create many different variations of the video.
Video generation is currently in Beta. There may be minor changes to parameter names or other implementation details before the general access release. We invite you to try it out. We would appreciate any feedback via our support team.
Syntax
POST /video/create_video
Required parameters
Parameter | Type | Description |
---|---|---|
manifest_json | String | The video specific manifest transformation as stringified JSON that specifies the assets to use as well as tracks, clips, keyframes, durations, transitions and effects. See the video generation reference for full details on syntax. |
signature | String | (Required for signed REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs for signed requests, the signature is automatically generated and added to the request. If you manually generate your own signed POST request, you need to manually generate the signature parameter and add it to the request together with the api_key and timestamp parameters. For more details, see manually generating signatures. |
upload_preset | String | (Required for unsigned uploading / optional for signed uploading) Name of an upload preset that you defined for your Cloudinary product environment. An upload preset consists of upload parameters centrally managed using the Admin API or from the Upload page of your Console Settings. An upload preset may be marked as unsigned, which allows unsigned uploading directly from the browser and restricts the optional parameters to: public_id , folder , tags , context , face_coordinates , regions and custom_coordinates . |
Optional parameters
Parameter | Type | Description |
---|---|---|
public_id | String | The identifier that is used for accessing or delivering the video. The public ID may contain a full path including folders separated by a slash (/ ).If not specified, then the public ID of the video will be comprised of random characters. Note: The public ID value for videos should not include a file extension. |
transformation | String | A transformation to apply to the video after it has been generated. This parameter is given as a comma-separated list of transformations, and separated with a slash for chained transformations. |
overwrite | Boolean | Whether to overwrite existing assets with the same public ID. When set to false, a response is returned immediately if an asset with the same public ID was found. When overwriting assets, if you include versions in your delivery URLs, you will need to update the URLs with the new version number to deliver the new asset. If you don't include versions, you will need to invalidate the old assets on the CDN server cache. Default: Important: Depending on your product environment setup, overwriting an asset may clear the tags, contextual, and structured metadata values for that asset. If you have a Master admin role, you can change this behavior for your product environment in the Media Library Preferences pane, so that these field values are retained when new version assets overwrite older ones (unless you specify different values for the |
tags | String | A comma-separated list of tag names to assign to the video for later group reference. For example: animal,dog . |
notification_url | String | An HTTP or HTTPS URL to notify your application (a webhook) when the process has completed. If not specified, the response is sent to the Notification URL (if defined) in the Webhook Notifications settings of your Cloudinary Console. |
Example
Generating a video setting the public ID to test_video
:
Sample response
The following is a sample response based on the example above. As video generation occurs asynchronously, a notification is sent once the video has been successfully generated. You can see an example of the notification response below.
explode
The explode
method creates derived images for all of the individual pages in a multi-page file (PDF or animated GIF). Each derived image is stored with the same public ID as the original file, and can be accessed using the page
parameter, in order to deliver a specific image (for more details, see the documentation on delivering content from PDF files).
You could deliver individual pages of a multi-page file on the fly without using the explode
method first: this method is useful for pre-generating all the pages of the file so that they do not need to be generated on the fly when first accessed by your users.
Syntax
POST /image/explode
Required parameters
Parameter | Type | Description |
---|---|---|
public_id | String | The identifier of the uploaded multi-page file (PDF or animated GIF). Note: The public ID for images does not include a file extension. |
transformation | String | A transformation to run on all the pages before storing them as derived images. This parameter is given as a comma-separated list of transformations, and separated with a slash for chained transformations. At minimum, you must pass the page transformation with the value all . If you supply additional transformations, you must deliver the image using the same relative order of the page and the other transformations. If you use a different order when you deliver, then it is considered a different transformation, and will be generated on the fly as a new derived image.SDKs: Supports a hash of transformation parameters (or an array of hashes for chained transformations).
Note: When using the SDK for a dynamically-typed language, the transformation parameters can be specified directly without using this transformation parameter, as seen in the examples for Ruby, PHP, Python, and Node.js below. |
signature | String | (Required for signed REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs for signed requests, the signature is automatically generated and added to the request. If you manually generate your own signed POST request, you need to manually generate the signature parameter and add it to the request together with the api_key and timestamp parameters. For more details, see manually generating signatures. |
Optional parameters
Parameter | Type | Description |
---|---|---|
type | String | The specific file type of the asset. Valid values: upload , private and authenticated . Default: upload . |
format | String | An optional format to convert the images before storing them in your Cloudinary product environment. Default: png . |
notification_url | String | An HTTP or HTTPS URL to notify your application (a webhook) when the process has completed. |
Example
To explode a PDF file with the public ID of "sample":
Sample response
The following is a sample response indicating that the explode
command is in process.
generate_archive
The generate_archive
method creates an archive file that contains all the assets meeting specified tag, public ID, or prefix criteria (or a combination thereof). The REST API method can be used to either return the generated archive file ('download'), store it as a raw asset in your Cloudinary product environment ('create'), or do both ('create_and_download') by setting the value of the mode
parameter.
By default, if all the assets in the archive have the identical transformation applied, they are stored in the archive with the original asset filename only, regardless of the value of the flatten_transformations
or skip_transformation_name
parameters. If assets of the same type with different transformations are included in the archive, then the relevant transformation data is appended to the filename of each asset, according to the settings of the flatten_transformations
or skip_transformation_name
parameters.
The archive can contain up to 1000 different assets, and up to 5000 files if adding different derived versions of those assets using transformations. The maximum archive file size is the larger of 100 MB or your product environment's raw
file size limit.
For details, see Media delivery.
The Cloudinary SDKs wrap the generate_archive
REST API method and offer several related helper methods:
- create_zip: generates a ZIP file based on the specified parameter values, uploads the file to your Cloudinary product environment, returns a JSON response with the URLs for accessing the ZIP file, and can then be delivered like any other raw file uploaded to Cloudinary.
- create_archive: generates an archive file based on the specified parameter values (default target_format = zip), uploads the file to your Cloudinary product environment, returns a JSON response with the URLs for accessing the archive file, and can then be delivered like any other raw file uploaded to Cloudinary.
-
download_zip_url (
downloadZip
in Java,DownloadArchiveUrl
in .NET): generates a signed URL that expires after 1 hour (by default). The URL can be accessed to dynamically create and then download a ZIP file based on the specified parameter values. The resulting ZIP file is not cached or stored in your Cloudinary product environment. -
download_archive_url (
downloadArchive
in Java): generates a signed URL that expires after 1 hour (by default). When the URL is invoked, it dynamically creates and downloads an archive file based on the given parameter values. The resulting archive file is not cached or stored in your Cloudinary product environment. -
download_folder: generates a signed URL representing the contents of the specified folder (and its sub-folders). By default, the URL expires after 1 hour and includes all assets from the requested folder regardless of
resource_type
. When this folder URL is invoked, it dynamically creates and downloads an archive file with the folder contents. The resulting archive file is not cached or stored in your Cloudinary product environment.
create_zip syntax
POST /:resource_type/generate_archive
create_archive syntax
POST /:resource_type/generate_archive
download_zip_url syntax
POST /:resource_type/generate_archive
download_archive_url syntax
POST /:resource_type/generate_archive
download_folder syntax
POST /:resource_type/generate_archive
Required parameters
At least one of the 'tags', 'public_ids', or 'prefixes' parameters needs to be specified, in order to tell Cloudinary which assets to include in the archive file. Specifying any combination of the three parameters is also allowed - a unique union of all the matching assets will then be included in the archive file:
Parameter | Type | Description |
---|---|---|
tags | String | A comma-separated list of tag names. All assets with the specified tags are included in the archive. Up to 20 tags are supported. For example: animal,dog SDKs: Supports arrays. For example: ['animal', 'dog']
|
public_ids | String | A comma-separated list of public IDs for the specific assets to be included in the archive. Up to 1000 public IDs are supported. SDKs: Supports arrays. |
prefixes | String | A comma-separated list of prefixes of public IDs (e.g., folders). Setting this parameter to a slash (/ ) is a shortcut for including all assets in the product environment for the given resource_type and type (up to the max files limit). Up to 20 prefixes are supported.SDKs: Supports arrays. |
signature | String | (Required for signed REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs for signed requests, the signature is automatically generated and added to the request. If you manually generate your own signed POST request, you need to manually generate the signature parameter and add it to the request together with the api_key and timestamp parameters. For more details, see manually generating signatures. |
Optional parameters
Parameter | Type | Description |
---|---|---|
resource_type | String | The type of assets to include. Only relevant as a parameter when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Valid values: image , raw , video , all . Default: image . Notes:
|
type | String | The specific file type of assets to include in the archive (upload /private /authenticated ). If tags are specified as a filter then all types are included. Default: upload . |
transformations | String | A transformation to run on all the derived assets before storing them in your Cloudinary product environment. This parameter is given as a comma-separated list of transformations, and separated with a slash for chained transformations. If this parameter is not specified then the original assets are included in the archive. If you are including multiple asset types in your archive, make sure the transformations you specify are supported for all assets that will be included in the archive.SDKs: Supports a hash of transformation parameters (or an array of hashes for chained transformations). Note: When using the SDK for a dynamically-typed language, the transformation parameters can be specified directly without using the |
mode | String | (Only relevant when using the REST API - not for use with SDKs) Determines how to generate and deliver the archive:
create . |
target_format | String | (Only relevant when using the REST API or the 'archive' SDK methods - not for use with the 'zip' SDK methods)The format for the generated archive: zip or tgz . Default: zip . |
target_public_id | String | The name to use for the generated file:
|
target_asset_folder | String |
Not supported for product environments using the legacy fixed folder mode and only for the create* SDK methods / create mode. The folder where the generated file is placed within the Cloudinary repository. Default: If not specified, the generated file will be located in the root of your product environment asset repository, even if the public ID value includes slashes. |
flatten_folders | Boolean | Determines whether to flatten all files to be in the root of the archive file (no sub-folders). Any folder information included in the public ID is stripped and a numeric counter is added to the file name in the case of a name conflict. Default: false . |
flatten_transformations | Boolean | If multiple transformations are also applied, determines whether to flatten the folder structure of the derived assets and store the transformation details on the file name instead. Default: false . |
skip_transformation_name | Boolean | Determines whether to strip all transformation details from file names and add a numeric counter to a file name in the case of a name conflict. Default: false . |
allow_missing | Boolean | Allows generation of the archive if any of the supplied public IDs are not found, instead of returning an error. Default: false . |
expires_at | Integer | (Only relevant when using the 'download' SDK methods and the 'download' mode in REST API calls) The date (UNIX time in seconds) for the URL expiration (e.g., 1415060076). Default: 1 hour from the time that the URL is generated. |
use_original_filename | Boolean | Whether to use the original file name of the included assets (if available) instead of the public ID. Default: false . |
async | Boolean | (Only relevant when using the 'create' SDK methods and the 'create' mode in REST API calls) Whether to perform the archive generation in the background (asynchronously). Default: false . |
notification_url | String | (Only relevant when using the 'create' SDK methods and the 'create' mode in REST API calls) An HTTP or HTTPS URL to notify your application (a webhook) when the archive creation process has completed. If not specified for create operations, the response is sent to the Notification URL (if defined) in the Webhook Notifications settings of your Cloudinary Console. |
target_tags | String | (Only relevant when using the 'create' SDK methods and the 'create' mode in REST API calls) A comma-separated list of tag names to assign to the generated archive. For example: animal,dog SDKs: Supports arrays. For example: ['animal', 'dog']
|
keep_derived | Boolean | Whether to keep the derived assets used for generating the archive. Default: false.
|
Examples
To create a zip file that contains all images that have the lion
tag:
To generate a URL for downloading a zip file that contains the images with the following public_ids: dog
, cat
and lion
:
To generate a URL, that when accessed will download a zip file called MyFolder.zip
, which contains all assets from the MyFavoriteFolder
folder (and its sub-folders), regardless of resource_type
:
Sample response
The following is a sample response based on the create_zip
example above. 6 image assets with the tag 'lion' were added to the zip file. Because no target_public_id
was specified in the upload, a random public_id
was assigned to the zip file.
multi
The multi
method creates either a single animated image (GIF, PNG or WebP), video (MP4 or WebM) or a single PDF from all image assets that have been assigned a specified tag or from a set of image URLs. Each asset is included as a single frame of the resulting animated image/video, or a page of the PDF (sorted alphabetically by their public ID).
For a detailed explanation on generating animated images, see Creating animated images.
For further information about generating a PDF from a selection of images, see Creating PDF files from images.
For details, see Media delivery.
Syntax
POST /image/multi
Required parameters
Parameter | Type | Description |
---|---|---|
tag | String | (Required if not using urls ) The animated GIF or PDF is created from all images with this tag. |
signature | String | (Required for signed REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs for signed requests, the signature is automatically generated and added to the request. If you manually generate your own signed POST request, you need to manually generate the signature parameter and add it to the request together with the api_key and timestamp parameters. For more details, see manually generating signatures. |
Optional parameters
Parameter | Type | Description |
---|---|---|
urls | Array | (Required if not using tag ) The animated GIF or PDF is created from all image URLs in the array. |
transformation | String | A transformation to run on all the derived assets before creating the animated image or PDF. This parameter is given as a comma-separated list of transformations, and separated with a slash for chained transformations. SDKs: Supports a hash of transformation parameters (or an array of hashes for chained transformations).
Note: When using the SDK for a dynamically-typed language, the transformation parameters can be specified directly without using the transformation parameter. |
async | Boolean | Tells Cloudinary whether to perform the animated image or PDF generation in the background (asynchronously). Default: false . |
format | String | The file format of the result. Valid values: gif , png , webp , mp4 , webm and pdf . Default: gif
|
delay | Integer | The delay in milliseconds between frames. Valid for animated images and video formats. |
notification_url | String | An HTTP or HTTPS URL to notify your application (a webhook) when the process has completed. If not specified, the response is sent to the Notification URL (if defined) in the Webhook Notifications settings of your Cloudinary Console. |
Examples
Generating an animated GIF from all images tagged with logo
:
Generating an animated webp from all images tagged with logo
:
Generating a PDF from a set of sample image URLs:
Sample response
The following is a sample response based on the logo example above. An animated logo.webp
image was created from all the images with the tag logo
.
sprite
Cloudinary supports generating sprites by merging multiple images into a single large image for reducing network overhead and bypassing download limitations. The browser downloads only a single image and a CSS file that directs the browser to which part of the sprite to use for displaying each contained image. The sprite
method creates a sprite from all images that have been assigned a specified tag or from a list of image URLs. The process produces 2 files as follows:
- A single image file (PNG by default) containing all the images that were specified either with a tag, or with a set of URLs.
- A CSS file that includes the style class names and the location of the individual images in the sprite.
For a detailed explanation on generating and using sprites, see the documentation on sprite generation.
Syntax
POST /image/sprite
Required parameters
Parameter | Type | Description |
---|---|---|
tag | String | (Required if not using urls ) The sprite is created from all images with this tag. |
urls | Array | (Required if not using tag ) The sprite is created from all image URLs in the array. |
signature | String | (Required for signed REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs for signed requests, the signature is automatically generated and added to the request. If you manually generate your own signed POST request, you need to manually generate the signature parameter and add it to the request together with the api_key and timestamp parameters. For more details, see manually generating signatures. |
Optional parameters
Parameter | Type | Description |
---|---|---|
transformation | String | A transformation to run on all the derived assets before creating the sprite. This parameter is given as a comma-separated list of transformations, and separated with a slash for chained transformations. SDKs: Supports a hash of transformation parameters (or an array of hashes for chained transformations).
Note: When using the SDK for a dynamically-typed language, the transformation parameters can be specified directly without using the transformation parameter. |
format | String | An optional format to convert the sprite before saving it in your Cloudinary product environment. Default: png . |
async | Boolean | Tells Cloudinary whether to perform the sprite generation in the background (asynchronously). Default: false . |
notification_url | String | An HTTP or HTTPS URL to notify your application (a webhook) when the process has completed. If not specified, the response is sent to the Notification URL (if defined) in the Webhook Notifications settings of your Cloudinary Console. |
Example
Generating a sprite from all images tagged with logo
, creates a single PNG image file with the public ID of logo
that contains all the tagged images, and a CSS file with the public ID of logo.css
.
Sample response
The following is a sample response based on the example above. 3 images with the tag logo
were added to the logo
png and css files to create the sprite.
text
You can use Cloudinary to dynamically generate an image from a given textual string with the text
method. You can then use this textual image as any other image, for example, as an overlay for other images. Various font, color and style parameters can be specified to customize the look & feel of the text before converting it to an image.
Syntax
POST /image/text
Required parameters
Parameter | Type | Description |
---|---|---|
text | String | The text string to generate an image for. |
signature | String | (Required for signed REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs for signed requests, the signature is automatically generated and added to the request. If you manually generate your own signed POST request, you need to manually generate the signature parameter and add it to the request together with the api_key and timestamp parameters. For more details, see manually generating signatures. |
Optional parameters
Parameter | Type | Description |
---|---|---|
public_id | String | The identifier that is used for accessing the generated image. If not specified, a unique identifier is generated by Cloudinary. Note: The public ID value for images and videos should not include a file extension. Include the file extension for raw files only. |
font_family | String | The name of the font family. |
font_size | Integer | Font size in points. Default: 12 . |
font_color | String | Name or RGB representation of the font's color. For example: red or #ff0000 . Default: black . |
font_weight | String | Whether to use a normal or a bold font. Default: normal . |
font_style | String | Whether to use a normal or an italic font. Default: normal . |
background | String | Name or RGB representation of the background color of the generated image. For example: red or #ff0000 . Default: transparent . |
opacity | Integer | Text opacity value between 0 (invisible) and 100. Default: 100 . |
text_decoration | String | Set to underline to define a line below the text. Default: none . |
Example
Create an image of the text string "Sample text string" in 42 point, red, Roboto bold font, and the public ID of "sample_text_image":
Sample response
The following is a sample response based on the example above. A text image is created with the public ID sample_text_image
based on the transformations requested in the text
method.