Last updated: Aug-13-2025
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.
For a detailed walkthrough of the upload process, see the
Upload guide.
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.
Never expose your API secret in public client-side code.
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.
For more in-depth documentation and general information on uploading media assets see the
Uploadguide. For more information on calling the REST API methods directly, see the documentation on
Uploading with a direct call to the API.
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.
Cloudinary may add more fields to API responses and notifications in the future, so please ensure that your response parsing remains forward compatible and won't break as a result of unknown fields.
Using Postman for Upload REST API callsTake 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 APIOur 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:
SDK-specific documentation can be found in the
SDK Guides.
Using the CLI to access the Upload APIYou 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 handlingThe 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
Enables you to perform basic and advanced management tasks on your assets.
uploadUploads an asset to your product environment.
The Cloudinary SDKs wrap the upload endpoint and offer two separate methods: one for signed uploading and one for unsigned uploading.
Learn more: Upload guide
Signed upload syntaxPOST /:resource_type/upload
POST /:resource_type/upload
To support large file uploads, the Cloudinary SDKs include the upload_large method, which offers a degree of tolerance for network issues by uploading files to your product environment in chunks. It's required for any files that are larger than 100 MB or you will get a '413 Request entity too large' error. This is often relevant for video files, as they tend to have larger files sizes. See the Chunked asset upload documentation for more details.
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 is set to true.
Notes:
raw files only..), forward slashes (/), underscores (_), hyphens (-).?, &, #, \, %, <, >.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 doesn't 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 public_id (or the last segment of the public ID if the public ID includes slashes).
public id and its value doesn't impact the delivery URL in any way.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 doesn't impact the assetâs public ID path (unless theuse_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.
Notes:
.), underscores (_), hyphens (-)./). Additionally, they can't include the following characters: ? & # \ % < >.Not relevant for product environments using the legacy fixed folder mode.
use_asset_folder_as_public_id_prefix Boolean Whether to add theasset_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 public_id_prefix (or folder) has not been separately specified.
Default: false
Not relevant for product environments using the legacy fixed folder mode.
folder StringOnly 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 public_id value with a forward slash.
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 asset_folder parameter to control where the asset will be placed. If you also want your public_id to match the initial asset folder path, include the use_asset_folder_as_public_id_prefixparameter.
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: false.
display_name parameter isn't set.
Note: If you set use_filename_as_display_name to true (in the upload call or upload preset) and the original filename of the asset includes forward slashes, the upload will fail with an error that the display name can't include slashes.
Default: false.
Not relevant for product environments using the legacy fixed folder mode.
unique_filename Boolean When set to true, appends random characters to the end of the filename to guarantee its uniqueness. This parameter is relevant only ifuse_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.
- token requires either Token-based access or Cookie-based access for accessing the asset.
access_type: "token"- anonymous allows public access to the asset during a set time period. 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.
Note: The access_mode parameter is no longer supported. To restrict access to assets, you can use the access_control parameter. For more details, see Access-controlled media assets.
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 is 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, context, or metadata parameters as part of your upload).
Resource data: tags String A comma-separated list of tag names to assign to the uploaded asset for later group reference. For example: animal,dogSDKs: 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
= and | characters can be supported as values when escaped with a prepended backslash (\).['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:=, " and | characters can be supported as values when escaped with a prepended backslash (\).false. colors Boolean Whether to retrieve predominant colors & color histogram of the uploaded image.
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.
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.
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.
false. Supported for images, video, and audio.
PixelsPerUnitX, PixelsPerUnitY, PixelUnits, Colorspace, and DPI.audio_codec, audio_bit_rate, audio_frequency, channels, channel_layout.pix_format, codec, level, profile, video_bit_rate, dar.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.
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:
create_derived(Boolean - Required) If true, create and keep the derived images of the selected breakpoints during the API call. If false, images generated during the analysis process are thrown away.format (String - Optional) Sets the file extension of the derived assets to the format indicated (as opposed to changing the format as part of a transformation - which would be included as part of the transformation component (e.g., f_jpg)).transformation (String - Optional) The base transformation to first apply to the image before finding the best breakpoints. The API accepts a string representation of a chained transformation (same as the regular transformation parameter of the upload API).max_width (Integer - Optional) The maximum width needed for this image. If specifying a width bigger than the original image, the width of the original image is used instead. Default: 1000.min_width (Integer - Optional) The minimum width needed for this image. Default: 50.bytes_step (Integer - Optional) The minimum number of bytes between two consecutive breakpoints (images). Default: 20000.max_images (Integer - Optional) The maximum number of breakpoints to find, between 3 and 200. This means that there might be size differences bigger than the given bytes_step value between consecutive images. Default: 20.transformation, width, height, bytes, url and secure_url.
Use together with the detection parameter for:
Use together with the categorization parameter for:
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:
coco_v2) to return a list of detected content using the Cloudinary AI Content Analysis add-on. Can be used together with the auto_tagging parameter to apply tags automatically.captioning to analyze an image and suggest a caption based on the image's contents.iqa to analyze the quality of an image.watermark-detection to detect watermarks in an image.adv_face to return a list of facial attributes using the Advanced Facial Attribute Detection add-on.aws_rek_face to return a list of detected celebrities and facial attributes using the Amazon Rekognition Celebrity Detection add-on. Can be used together with the auto_tagging parameter to apply tags automatically.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.
false.
Relevant for videos only.
auto_transcription Boolean or Object Whether to trigger automatic video transcription or a set of languages to translate the transcript to alongside the native language. The transcripts get generated and saved as a .transcript file with the same public ID as the video (and with the language code appended for the translated transcripts). You can use your transcript file to show subtitles or captions using the Cloudinary Video Player.false.
Relevant for videos only.
ocr String Set toadv_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.
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 transformation parameter.
jpg. custom_coordinates String Relevant for images only. The coordinates of one or more regions contained in the image being uploaded that can be subsequently used for cropping or adding layers using the custom gravity mode. Specify regions 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. To specify more than one region, separate them with a pipe (|), for example: 85,120,220,310|150,180,100,300.
SDKs: Supports arrays. For example: [85, 120, 220, 310].
{ "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.
face_coordinates String Relevant for images only. 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.
SDKs: Supports arrays. For example: [[10, 20, 150, 130],[213, 345, 82, 61]].
cloudinary_ai to use Cloudinary's built-in deep-learning based functionality. pixelz to use the human-powered Pixelz Remove-The-Background Editing add-on service.(Asynchronous)
raw_convert String Generates a related file based on the uploaded file.aspose to automatically create a PDF or other image format from a raw Office document using the Aspose Document Conversion add-on. (Asynchronous)google_speech to instruct the Google AI Video Transcription add-on to generate an automatic transcript raw file from an uploaded video. (Asynchronous)extract_text to extract all the text from a PDF file and store it in a raw JSON file with a public ID in the format: [pdf_public_id].extract_text.json. The full URL of the generated JSON file is included in the API response. Unlike the above raw_convert options, this option doesn't require registering for an add-on.(Synchronous)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 won't 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: **{"async": True}
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:
manual to add the uploaded asset to a list of pending assets that can be moderated using the Admin API or the Cloudinary Console.perception_point to automatically moderate the uploaded asset using the Perception Point Malware Detection add-on.webpurify to automatically moderate the uploaded image using the WebPurify Image Moderation add-on.aws_rek to automatically moderate the uploaded image using the Amazon Rekognition AI Moderation add-on.duplicate:<threshold> to detect if the same or a similar image already exists using the Cloudinary Duplicate Image Detection add-on. Set threshold to a float greater than 0 and less than or equal to 1.0 to specify how similar an image needs to be in order to be considered a duplicate. Set threshold to 0 to add an image to the index of images that are searched when duplicate detection is invoked for another image.aws_rek_video to automatically moderate the uploaded video using the Amazon Rekognition Video Moderation add-on.google_video_moderation automatically moderate the uploaded video using the Google AI Video Moderation add-on.manual moderation, if relevant, being last.
For example: aws_rek|duplicate:0|perception_point|manual
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
You can define the following parameters directly in an unsigned upload request:
upload_preset, public_id, public_id_prefix (dynamic-folder mode only), folder, asset_folder (dynamic-folder mode only), tags, context, metadata, face_coordinates, custom_coordinates, regions, source, filename_override, manifest_transformation, manifest_json, template, template_vars.
While only certain parameters are allowed directly in unsigned requests, any permitted parameter can be included in an upload preset.
Parameters defined in both the request and the upload preset
When an unsigned upload request includes one of the above supported parameters and the same parameter is also defined in the upload preset, Cloudinary handles precedence as follows:
Single-value parameters:
Cloudinary uses the value from the upload preset. The value in the request is used only if the preset doesn't define that parameter.
Multi-value parameters (e.g., tags, context, metadata):
Cloudinary merges the values from both the preset and the request.
This differs from signed uploads, where parameters defined in the request always take precedence over those in the preset.
Cloudinary always treats
overwrite
as
false
in unsigned uploads, even if the request or upload preset sets it to
true
.
ExamplesTo 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:
If running the CLI command on Windows, you need to escape the double quotes within the curly braces using either
\
or
"
, for example,
\"text\"
or
""text""
.
Sample responseThe 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.
async = true) only includes a few details such as the status (pending) and a batch_id for tracking. Once the upload completes, the notification_url set for the asynchronous upload will receive the full response including the details in the example above.overwritten or existing (depending on whether the overwrite parameter was set to true or false).Updates existing assets already stored in your product environment.
This can be useful for updating asset attributes, such as adding/modifying tags or structured metadata values, moving assets to new asset folder locations (dynamic folder mode only) or generating eager transformations to warm up the cache for faster delivery of complex transformations.
Learn more: Updating existing assets.
SyntaxPOST /:resource_type/explicit
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.
public id and its value doesn't impact the delivery URL in any way.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 explicit method moves the asset to the specified asset folder, but does not impact the assetâs public ID path.
Notes:
.), underscores (_), hyphens (-)./). Additionally, they can't include the following characters: ? & # \ % < >.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 isEagerTransforms.) 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,dogSDKs: 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
= and | characters can be supported as values when escaped with a prepended backslash (\).['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:=, " and | characters can be supported as values when escaped with a prepended backslash (\).Link, X-Robots-Tag. For example: X-Robots-Tag: noindex. face_coordinates String Relevant for images only. 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.
SDKs: Supports arrays. For example: [[10, 20, 150, 130],[213, 345, 82, 61]].
custom gravity mode. Specify regions 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. To specify more than one region, separate them with a pipe (|), for example: 85,120,220,310|150,180,100,300.
SDKs: Supports arrays. For example: [85, 120, 220, 310].
{ "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.
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.
false. Supported for images, video, and audio.
PixelsPerUnitX, PixelsPerUnitY, PixelUnits, Colorspace, and DPI.audio_codec, audio_bit_rate, audio_frequency, channels, channel_layout.pix_format, codec, level, profile, video_bit_rate, dar.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.
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.
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.
false. Relevant for images only.
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:
manual to add the asset to a list of pending assets that can be moderated using the Admin API or the Cloudinary Console.perception_point to automatically moderate the uploaded asset using the Perception Point Malware Detection add-on.webpurify to automatically moderate the image using the WebPurify Image Moderation add-on.aws_rek to automatically moderate the image using the Amazon Rekognition AI Moderation add-on.duplicate:<threshold> to detect if the same or a similar image already exists using the Cloudinary Duplicate Image Detection add-on. Set threshold to a float greater than 0 and less than or equal to 1.0 to specify how similar an image needs to be in order to be considered a duplicate. Set threshold to 0 to add an image to the index of images that are searched when duplicate detection is invoked for another image.aws_rek_video to automatically moderate the uploaded video using the Amazon Rekognition Video Moderation add-on.google_video_moderation automatically moderate the uploaded video using the Google AI Video Moderation add-on.manual moderation, if relevant, being last.
For example: aws_rek|duplicate:0|perception_point|manual
create_derived(Boolean - Required) If true, create and keep the derived images of the selected breakpoints during the API call. If false, images generated during the analysis process are thrown away.format (String - Optional) Sets the file extension of the derived assets to the format indicated (as opposed to changing the format as part of a transformation - which would be included as part of the transformation component (e.g., f_jpg)).transformation (String - Optional) The base transformation to first apply to the image before finding the best breakpoints. The API accepts a string representation of a chained transformation (same as the regular transformation parameter of the upload API).max_width (Integer - Optional) The maximum width needed for this image. If specifying a width bigger than the original image, the width of the original image is used instead. Default: 1000.min_width (Integer - Optional) The minimum width needed for this image. Default: 50.bytes_step (Integer - Optional) The minimum number of bytes between two consecutive breakpoints (images). Default: 20000.max_images (Integer - Optional) The maximum number of breakpoints to find, between 3 and 200. This means that there might be size differences bigger than the given bytes_step value between consecutive images. Default: 20.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.
false.
Relevant for videos only.
auto_transcription Boolean or Object Whether to trigger automatic video transcription, or a set of languages to translate the transcript to, alongside the native language. The transcripts get generated and saved as a .transcript file with the same public ID as the video (and with the language code appended for the translated transcripts). You can use your transcript file to show subtitles or captions using the Cloudinary Video Player.false.
Relevant for videos only.
ExampleTo perform two eager transformations for the already uploaded image with a public ID of sample as follows:
When you perform an eager transformation using
explicit
, the transformation is processed upon request (and counted in your transformation quota) even if an identical derived asset already exists.
Sample responseThe following is a sample response based on the example above. Two explicit transformations were performed on the sample image.
Modifies the public ID (or optionally the delivery type) of an existing asset.
After running the
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.
, Cloudinaryâs drag-and-drop workflow builder for image and video, enables users to easily rename media at scale in a low-code implementation. See MediaFlowâs documentation on renaming media
here.
SyntaxPOST /:resource_type/rename
The
rename
method is relevant only for modifying the asset's public ID (including any segment of the public ID path). If you want to modify the asset's
display nameand/or
asset folder, pass a new value for the
display_name
or
asset_folder
parameter in an
Explicitor
Updatemethod call.
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 thesignature 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 tags, context, or metadata parameters as part of your upload).
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:
The following is a sample response based on the example above. The canyon image was renamed to grand_canyon.
Permanently deletes a single asset from your Cloudinary product environment based on public ID and resource type.
See also: destroy (by asset ID)
To bypass CDN caching, you can include the invalidate parameter in your destroy 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.
POST /:resource_type/destroy
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:
A successful destroy operation returns the following:
Permanently deletes a single asset from your Cloudinary product environment based on asset ID.
See also: destroy (by public ID)
To bypass CDN caching, you can include the invalidate parameter in your destroy 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.
POST /:destroy
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 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 asset ID of wu1js8tlwoib7839a0bkw:
A successful destroy operation returns the following:
Retrieves a specific version of a backed up asset without restoring it.
GET /download_backup
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):
The following is a sample SDK response based on the example above. The call returns the URL to download the requested backed up version of the asset.
Metadata managementEnables you to manage your assets' metadata.
contextEnables you to manage the contextual metadata stored with an asset.
You can perform different operations with the context endpoint by setting the value of the command parameter to add, or remove_all.
SDKs: The Cloudinary SDKs wrap the context endpoint and offer separate methods for these operations.
POST /:resource_type/context
POST /:resource_type/context
alt=My image|caption=Profile image
= and | characters can be supported as values when escaped with a prepended backslash (\).['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
The following is a sample response based on the example above. A contextual metadata value was added to the dog and lion images.
Adds values to an asset's metadata fields.
Learn more: Structured metadata
SyntaxPOST /:resource_type/metadata
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:=, " and | characters can be supported as values when escaped with a prepended backslash (\).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 responseThe following is a sample response based on the example above. Metadata values were added to the shirt and pants images.
tagsEnables you to manage the set of tags stored with an asset.
You can perform different operations with the tags endpoint by setting the value of the command parameter to add, remove, remove_all, or replace.
SDKs: The Cloudinary SDKs wrap the tags endpoint and offer 4 separate methods for these operations.
Tags are useful for categorizing and organizing your assets, as well as for applying group actions to assets, such as deleting multiple assets and creating sprites, ZIP files, JSON lists, or animated GIFs.
A tag can have up to 255 characters. An asset can have up to 1000 tags.
Learn more: Tags
Adding tags syntaxPOST /:resource_type/tags
POST /:resource_type/tags
POST /:resource_type/tags
POST /:resource_type/tags
animal,dog
SDKs: Supports arrays. For example: ['animal', 'dog']
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.
This method supports a maximum of 1000 total operations (public_ids * tags <= 1000).
Optional parameters Parameter Type Description resource_type String The type of asset. Only relevant as a parameter when using the SDKs (theresource_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
The following is a sample response based on the example above. A tag was added to the dog and lion images.
Enables you to create different types of assets from existing assets. The generated assets are stored as new assets in your product environment.
create_collageCreates an image collage as a new asset by combining specified existing assets in a pre-defined or custom layout.
To create a collage, supply a manifest_json that defines all the images, colors, positions, and optional image-specific transformations.
Learn more: Create image collages
SyntaxPOST /image/create_collage
There is no SDK support yet for
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 thesignature 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 Presets 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, context, or metadata parameters as part of your upload).
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:
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.
explodeGenerates derived images for each of the individual pages/frames in a multi-page file (PDF or animated image).
You can deliver these derived images using the same public ID as the original file and applying the page transformation parameter to deliver a for the relevant page or frame.
Note that you can also generate and deliver individual pages/frames from a multi-page file on the fly using the page transformation parameter. The explode method is useful for warming the cache in advance with all the pages/frames of the file to improve delivery performance on first access.
POST /image/explode
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 responseThe following is a sample response indicating that the explode command is in process.
Creates an archive file that contains all the assets meeting specified tag, public ID, or prefix criteria (or a combination thereof).
You can perform different operations with the generate_archive endpoint by setting the value of the mode parameter to download, create, or create_and_download.
SDKs: The Cloudinary SDKs wrap the generate_archive endpoint and offer separate methods for the supported operations.
The assets are added to the archive as files with their display names as follows:
skip_transformation_name parameter, the transformation or a numeric value is appended to the file name to differentiate the assets derived from the same original using different transformations.flatten_transformations parameter, asset files derived from the same original may be stored in separate folders named after the original assetâs display name.If your product environment uses the legacy
fixed foldermode, the assets are stored in the archive with their public IDs instead of display names.
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.
Important note for free accounts
By default, while you can still use this method to generate archive files, Free accounts are blocked from delivering
zip,
rar,
tagz, and other archive formats for security reasons.
For details, see
Media delivery.
The Cloudinary SDKs wrap the generate_archive REST API method and offer several related helper methods:
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.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.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.If the archive generation requires creating derived assets and the size of the original resource is too big, the operation fails. Depending on your account setup, the following occurs:
create action, the operation fails and returns a 400 error.download action, the file downloads, but the archive includes an ERROR.txt file, explaining the issue.To avoid these issues, generate the derived assets using eager transformations with the upload or explicit endpoints before attempting to generate the archive.
create_zip syntaxPOST /:resource_type/generate_archive
POST /:resource_type/generate_archive
POST /:resource_type/generate_archive
POST /:resource_type/generate_archive
POST /:resource_type/generate_archive
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,dogSDKs: 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:
video resource type to request video assets as well as for audio files, such as .mp3.all.upload/private/authenticated). If tags are specified as a filter then all types are included. Default: upload. transformations String Allows you to apply one or more transformations to all assets before storing them in the archive. (A single transformation is given as a comma-separated list of transformation parameters, and separated with a slash for chained transformations.) You can specify multiple transformations as a pipe ( mode String (Only relevant when using the REST API - not for use with SDKs) Determines how to generate and deliver the archive:
download - generates and delivers the archive file without storing it in your product environment.create - creates and stores it as a raw asset in your Cloudinary product environment (does not deliver the archive file itself, but returns a JSON response with the URLs for accessing the archive file).create_and_download - creates, stores AND delivers the archive file.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:
mode parameter is set to create (or when using one of the create* SDK methods), this parameter defines the public ID to assign to the generated archive.mode parameter is set to download (or when using one of the download* SDK methods), this parameter defines the filename of the downloaded archive file.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. The transformation details are always stored on the file name. 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,dogSDKs: 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:
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.
Creates a single animated image (GIF, PNG or WebP), video (MP4 or WebM) or PDF from all image assets with a specified tag or from a set of specified image URLs.
Each asset becomes a single page or frame in the resulting animated image, video, or PDF, sorted alphabetically by their public ID.
Learn more: Creating animated images | Creating PDF files from images
Important note for free accounts
By default, while you can use this method to generate PDF files, Free accounts are blocked from delivering files in PDF format for security reasons.
For details, see
Media delivery.
SyntaxPOST /image/multi
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).
Behavior differs for video formats
If the requested output format is a video (mp4, webm), the transformation behaves differently:
- The source images are first combined into a video.
- The specified transformation is then applied as a video transformation, not an image transformation.
- Some image transformation capabilities are not supported or may not behave as expected in this context.
For example, advanced transformations such as:
- g_auto (automatic gravity)
- c_auto (automatic cropping)
- dpr_auto, q_auto (automatic DPR or quality)
- f_auto (automatic format)
are designed for individual image optimization and do not apply correctly to video transformations.
Note: When using the SDK for a dynamically typed language, the transformation parameters can be specified directly without using the transformation parameter.
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 responseThe 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.
Creates a sprite from all images with the specified tag or from a set of specified image URLs and generates the following 2 files:
Sprites can help reduce network overhead and bypass certain download limitations because they combine multiple images into a single file. The CSS file then directs the browser to display the appropriate section of the sprite for each image.
Learn more: Create sprites
SyntaxPOST /image/sprite
urls) The sprite 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 sprite is created from all image URLs in the array. 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. Examples
Generate a sprite from all images tagged with logo. It 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.
Generate a sprite from three image URLs and set the format of the sprite to WebP. It creates a single WebP image file with a random public ID that contains all the images specified, and a CSS file with the same random public ID and .css extension.
The following sample responses are based on the examples above:
textDynamically generates an image from a specified text string.
You can deliver and transform the returned textual image like any other image, for example, as an overlay for other images. You can specify various font, color, and style parameters to customize the look and feel of the text before converting it to an image.
SyntaxPOST /image/text
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.
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 responseThe 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.
âï¸ Feedback sent!
âï¸Â  ErrorUnfortunately there's been an error sending your feedback.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4