Upload API reference

The upload API consists of a number of methods for uploading and managing media assets in the cloud. The API methods can be called directly from within your own custom code or by using one of Cloudinary's SDKs that wrap the API and greatly simplify using its methods.

Authenticated uploading is done over HTTPS using a secure protocol based on your account's cloud_name, api_key and api_secret parameters. When using Cloudinary's SDKs, these parameters are generally configured globally but they can be provided with each call instead.

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.

For more in depth documentation and general information on uploading media assets see the Media upload documentation.

For additional information and examples, see the uploading images and uploading videos documentation. The Cloudinary SDKs wrap the upload method and offer 2 separate methods: one for signed uploading and one for unsigned uploading.

(Required for unsigned uploading / optional for signed uploading) Name of an upload preset that you defined for your Cloudinary account. An upload preset consists of upload parameters centrally managed using the Admin API or from the settings page of the management console. 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 and custom_coordinates.

Optional parameters:

Parameter

Type

Description

Naming and storage:

public_id

String

The identifier that is used for accessing the uploaded asset. A randomly generated ID is assigned if not specified. The Public ID may contain a full path including folders separated by a slash (/). Note: The public ID value for images and videos should not include a file extension. Include the file extension for raw files only.

folder

String

An optional folder name where the uploaded asset will be stored. The public ID contains the full path of the uploaded asset, including the folder name.

use_filename

Boolean

Whether to use the original file name of the uploaded asset if available for the public ID. The file name is normalized and random characters are appended to ensure uniqueness. Default: false.

unique_filename

Boolean

When set to false, should not add random characters at the end of the filename that guarantee its uniqueness. Only relevant if use_filename is also set to true. Default: true.

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 for direct calls to the API). Valid values: image, raw, video and auto. Defaults: image for server-side uploading 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

Allows uploading assets as 'private' or 'authenticated' instead of the default public mode. Only relevant as a parameter when using the SDKs (the type is included in the endpoint URL for direct calls to the API). Valid values: upload, private and authenticated. Default: upload.

access_control

JSON

An array of access types for the asset. The asset is accessible as long as one of the access types is valid. Possible values for each access type:

- 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 publically 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, return immediately if an asset with the same Public ID was found. Default: true (when using unsigned upload, the default is false and cannot be changed to true).

Resource data:

tags

String

An array (using the SDKs) or comma-separated list (for direct API calls) of tag names to assign to the uploaded asset for later group reference.

context

String

A map (using the SDKs) or pipe-separated list (for direct API calls) of the key-value pairs of general textual context 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 (the = and ❘ characters can be supported as values when escaped with a prepended backslash (\)). Note that key values are limited to 1024 characters.

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 direct 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.

image_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.

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: create_derived, transformation, max_width, min_width, bytes_step, max_images (see the table below for more information). The return response will include an array of the selected breakpoints for each breakpoint request, where the following information is given for each breakpoint: transformation, width, height, bytes, url and secure_url. Relevant for images only.

An array (using the SDKs) or pipe-separated list (for direct API calls) of transformation representations. This generates derived resources in advance, instead of lazily creating each of the derived resources when first accessed by your site's visitors. (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. Using the SDKs, this parameter is given as a hash of transformation parameters (or an array of hashes for chained transformations), and for direct API calls it is given as a string of comma-separated single characters (separated with a slash for chained transformations). Note that when using the SDK for a dynamically-typed language, the transformation parameters can be specified directly without using this transformation parameter.

format

String

An optional format to convert the uploaded asset to before saving in the cloud. For example: jpg.

custom_coordinates

String

Sets the coordinates of a single region contained in an uploaded image that is subsequently used for cropping uploaded images using the custom gravity mode. The region is specified by the X & Y coordinates of the top left corner and the width & height of the region, as an array (using the SDKs) or comma-separated list (for direct API calls). For example: 85,120,220,310. Relevant for images only.

face_coordinates

String

Sets the coordinates of faces contained in an uploaded image and overrides 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 an array (using the SDKs) or a comma-separated list (for direct API calls) with individual faces separated with a pipe (❘). For example: 10,20,150,130❘213,345,82,61. Relevant for images only.

An array (using the SDKs) or comma-separated list (for direct API calls) 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).

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) 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.

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. Note that it usually takes a few minutes (although it might take up to an hour) for the invalidation to fully propagate through the CDN. There are also a number of other important considerations when using the invalidate functionality.

An HTTP or HTTPS URL to receive the upload response (a webhook) when the upload is completed or a notification when any requested asynchronous action is completed.

proxy

String

Tells Cloudinary to upload assets from remote URLs through the given proxy. Format: http://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.

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), 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.

responsive_breakpoints parameter request settings:

The responsive_breakpoints parameter accepts an array of breakpoint request settings, where each request setting includes the following parameters:

Parameter

Type

Description

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 resources 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.

Examples:

To upload an image from a remote url: http://www.example.com/sample.jpg:

Sample JSON response:

The following is a sample JSON response based on the example above. sample.jpg was uploaded with two eager transformations. Because no public_id was specified in the upload, a random public_id was assigned.

Renamed assets are immediately and permanently updated in your cloud storage with the rename method. The existing URLs of renamed assets and their associated derived resources 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. Note that it usually takes a few minutes (although it might take up to an hour) for the invalidation to fully propagate through the CDN. For details on invalidating assets, see Invalidating cached media assets on the CDN.

Required parameters:

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 for direct calls to the 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 specific type of the asset. Only relevant as a parameter when using the SDKs (the type is included in the endpoint URL for direct calls to the API). Valid values: upload, private and authenticated. Default: upload.

to_type

String

The new type for the asset. Valid values: upload, private and authenticated. Default: the type remains the same as before.

overwrite

Boolean

Whether to overwrite an existing asset with the target public ID. Default: false.

invalidate

Boolean

Whether to invalidate CDN cached copies of the asset (and all its transformed versions). Default: false. Note that it usually takes a few minutes (although it might take up to an hour) for the invalidation to fully propagate through the CDN. There are also a number of other important considerations when using the invalidate functionality

The destroy method is used to immediately and permanently delete a single asset from your Cloudinary account (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. Note that it usually takes a few minutes (although it might take up to an hour) for the invalidation to fully propagate through the CDN. For details on invalidating media assets, see Invalidating cached media assets on the CDN.

Required parameters:

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.

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 for direct calls to the 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 specific type of the asset. Only relevant as a parameter when using the SDKs (the type is included in the endpoint URL for direct calls to the API). Valid values: upload, private and authenticated. Default: upload.

invalidate

Boolean

If true, invalidates CDN cached copies of the asset (and all its transformed versions). Default: false. Note that it usually takes a few minutes (although it might take up to an hour) for the invalidation to fully propagate through the CDN. There are also a number of other important considerations when using the invalidate functionality.

Sample JSON response:

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. Each asset can be assigned one or more tags, which is a short name (up to 255 characters) that you can dynamically use (no need to predefine tags).

The tags method can be used to manage tags by directly calling the method and setting the value of the command parameter to either add, remove, remove_all, or replace tags. 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.

Required parameters:

The tag to assign, remove, or replace. Not relevant when removing all tags.

public_ids

String

A list of public IDs (up to 1000) of assets uploaded to Cloudinary.

command

String

(Only relevant when using the API method directly 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.

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 for direct calls to the 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 specific type of the asset. Only relevant as a parameter when using the SDKs (the type is included in the endpoint URL for direct calls to the API). Valid values: upload, private and authenticated. Default: upload.

Examples:

To add the tag animal to the images with the Public IDs of dog and lion

Sample JSON response:

The context parameter of an uploaded asset contains a map (using the SDKs) or pipe-separated list (for direct API calls) of key-value pairs of general textual context metadata (up to 255 characters). The context method can be used to manage the context metadata of an uploaded asset by directly calling the method and setting the value of the command parameter to either add a new key-value pair, or remove_all context metadata from the asset. The Cloudinary SDKs wrap the context method and offer 2 separate methods: one for adding context data and one for removing all context data.

Required parameters:

Parameter

Type

Description

context

String

(Only relevant when adding context) A pipe-separated list (or map using the SDKs) of the key-value pairs of general textual context metadata to add to the asset. The additional key-value pairs are merged with any existing context key-value pairs (if the key already exists then only the value is overwritten, and an empty value for an existing key clears the value). The = and ❘ characters can be supported as values when escaped with a prepended backslash (\).

public_ids

String

A list of Public IDs of assets uploaded to Cloudinary.

command

String

(Only relevant when using the API method directly - not for use with SDKs) The action to perform on assets: either add the given context, or remove_all the context key-value pairs assigned.

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 for direct calls to the 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 specific type of the asset. Only relevant as a parameter when using the SDKs (the type is included in the endpoint URL for direct calls to the API). Valid values: upload, private and authenticated. Default: upload.

Examples:

To add the context key-pairs alt=Animal and class=Mammalia to the images with the Public IDs of dog and lion

Sample JSON response:

The explicit method is used to apply actions to already uploaded 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 account and you cannot create transformed assets on the fly. For more information, see Access control to images). You can also use this method to pre-generate transformations for remotely fetched images.

Optional parameters:

Parameter

Type

Description

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 Image transformation reference and Video transformation reference documentation for more details on possible values). This option accepts either a single transformation or an array of transformations (pipe-separated list for direct API calls) to create for the uploaded asset. (In .NET SDK, parameter name is EagerTransforms.)

async

Boolean

Tells Cloudinary 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.

tags

String

An array (using the SDKs) or comma-separated list (for direct API calls) of tag names to assign to an asset that replaces any current tags assigned to the asset (if any).

invalidate

Boolean

Whether to invalidate the asset (and all its transformed versions) on the CDN. Default: false. Note that it usually takes a few minutes (although it might take up to an hour) for the invalidation to fully propagate through the CDN. There are also a number of other important considerations when using the invalidate functionality.

context

String

A map (using the SDKs) or pipe-separated list (for direct API calls) of the key-value pairs of general textual context metadata to attach to an uploaded asset. The context values of uploaded files are available for fetching using the Admin API. For example: alt=My image❘caption=Profile image.

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

Sets the coordinates of faces contained in an uploaded image and overrides 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 an array (using the SDKs) or a comma-separated list (for direct API calls) with individual faces separated with a pipe (❘). For example: 10,20,150,130❘213,345,82,61. Relevant for images only.

custom_coordinates

String

Sets the coordinates of a region contained in an uploaded image that is subsequently used for cropping uploaded images using the custom gravity mode. The region is specified by the X & Y coordinates of the top left corner and the width & height of the region, as an array (using the SDKs) or comma-separated list (for direct API calls). For example: 85,120,220,310. Relevant for images only.

notification_url

String

An HTTP URL to send notification to (a webhook) when the upload is completed or any requested asynchronous action is completed.

image_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.

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 direct 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.

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, transformation, max_width, min_width, bytes_step, max_images (see the table below for more information). The return response will include an array of the selected breakpoints for each breakpoint request, where the following information is given for each breakpoint: transformation, width, height, bytes, url and secure_url. Relevant for images only.

responsive_breakpoints parameter request settings:

The responsive_breakpoints parameter accepts an array of breakpoint request settings, where each request setting includes the following parameters:

Parameter

Type

Description

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 resources 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.

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.

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.

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 an array (using the SDKs) or comma-separated list (for direct API calls) 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.

Note that 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.

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 method can be used directly to either return a URL to the generated archive file ('download') or to store it as a raw asset in your Cloudinary account ('create'), 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 assets or 5000 derived resources. The maximum archive file size is the larger of 100 MB or your account's raw file size limit.

create_zip: generates a ZIP file based on the given parameter values, uploads the file to your Cloudinary account, 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 given parameter values (default target_format = zip), uploads the file to your Cloudinary account, 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): 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 given parameter values. The resulting ZIP file is not cached or stored in your Cloudinary account.

download_archive_url (downloadArchive in Java): generates a signed URL that expires after 1 hour (by default). The URL can be accessed to dynamically create and then download an archive file based on the given parameter values. The resulting archive file is not cached or stored in your Cloudinary account.

Required parameters:

At least one of the following "filtering" 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

An array (using the SDKs) or comma-separated list (for direct API calls) of tag names. All assets with the specified tags are included in the archive. Up to 20 tags are supported.

public_ids

String

An array (using the SDKs) or comma-separated list (for direct API calls) of public IDs for the specific assets to be included in the archive. Up to 1000 public IDs are supported.

prefixes

String

An array (using the SDKs) or comma-separated list (for direct API calls) of prefixes of public IDs (e.g., folders). Setting this parameter to a slash (/) is a shortcut for including all assets in the account for the given resource_type and type (up to the max files limit). Up to 20 prefixes are supported.

Optional parameters:

Parameter

Type

Description

resource_type

String

The asset type (image, video or raw) of files to include in the archive: Default: image.

Note: The video resource type applies to video assets and to audio files, such as .mp3.

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 account. This parameter is given as an array (using the SDKs) or comma-separated list (for direct API calls) of transformations, and separated with a slash for chained transformations. Note that when using the SDK for a dynamically-typed language, the transformation parameters can be specified directly without using the transformation parameter. 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.

mode

String

Determines whether to return a URL to dynamically generate and download the archive file (download) or to create and store it as a raw asset in your Cloudinary account and return a JSON with the URLs for accessing the archive file (create). Only relevant when using the API method directly - not for use with SDKs. Default: create.

target_format

String

The format for the generated archive: zip or tgz. Only relevant when using the direct API call or the 'archive' SDK methods - not for use with the 'zip' SDK methods. Default: zip.

target_public_id

String

The Public ID to assign to the generated archive. If not specified, a random Public ID is generated. Only relevant when using the 'create' SDK methods and the 'create' mode in direct calls.

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

The date (UNIX time in seconds) for the URL expiration (e.g., 1415060076). Only relevant when using the 'download' SDK methods and the 'download' mode in direct calls. 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

Whether to perform the archive generation in the background (asynchronously). Only relevant when using the 'create' SDK methods and the 'create' mode in direct calls. Default: false.

notification_url

String

An HTTP or HTTPS URL to notify your application (a webhook) when the archive creation process has completed. Only relevant when using the 'create' SDK methods and the 'create' mode in direct calls.

target_tags

String

An array (using the SDKs) or comma-separated list (for direct API calls) of tag names to assign to the generated archive. Only relevant when using the 'create' SDK methods and the 'create' mode in direct calls.

keep_derived

Boolean

Whether to keep the derived assets used for generating the archive. Default: false.

Sample JSON response:

The following is a sample JSON 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.

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 generate_sprite method creates a sprite from all images that have been assigned a specified tag. The process produces 2 files as follows:

A single image file containing all the images with the specified tag (PNG by default).

A CSS file that includes the style class names and the location of the individual images in the sprite.

Required parameters:

Parameter

Type

Description

tag

String

The sprite is created from all images with this tag.

Optional parameters:

Parameter

Type

Description

transformation

String

A transformation to run on all the individual images before creating the sprite. This parameter is given as an array (using the SDKs) or comma-separated list (for direct API calls) of transformations, and separated with a slash for chained transformations. Note that when using the SDK for a dynamically-typed language, the transformation parameters can be specified directly without using this transformation parameter.

format

String

An optional format to convert the sprite before saving it in your Cloudinary account. Default: png.

The multi method creates a single animated GIF file from all images that have been assigned a specified tag, where each image is included as a single frame of the resulting animating GIF (sorted alphabetically by their Public ID). For a detailed explanation on generating animated GIFs, see the documentation on creating animated GIFs.

Animated GIFs can be created from a maximum of 500 frames (individual images), except in the following cases where the limit is 100 frames maximum:

If the processing is done in a synchronous mode (i.e., without the async parameter set to true).

If there is a underlay or overlay added to the image (l_ or u_).

If any transformation parameters are added that are not on the following list: background, flags, crop, width, height, x, y, gravity, quality, angle, page, and dpr.

If the angle parameter is added with a value that is anything but exif or auto.

If the crop parameter is added with a value that is anything but scale, limit, fit, fill, thumb or crop.

Required parameters:

Parameter

Type

Description

tag

String

The animated GIF is created from all images with this tag.

Optional parameters:

Parameter

Type

Description

transformation

String

A transformation to run on all the individual images before creating the animated GIF. This parameter is given as an array (using the SDKs) or comma-separated list (for direct API calls) of transformations, and separated with a slash for chained transformations. Note that when using the SDK for a dynamically-typed language, the transformation parameters can be specified directly without using this transformation parameter.

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.

Required parameters:

Parameter

Type

Description

text

String

The text string to generate an image for.

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:

To 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":