Image upload API reference

The upload API consists of a number of methods for uploading and managing images 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.

The Upload API includes the following methods:

  • Upload - for uploading images to the cloud.
  • Rename - to rename an image (change its Public ID).
  • Destroy - to delete an image.
  • Tags - for managing image tags.
  • Explicit - to update or apply actions to an already uploaded image.
  • Explode - to generate an image for each page in a PDF file.
  • Generate_archive - to create or download an archive file (currently only ZIP supported).
  • Generate_sprite - for generating a single large image from multiple smaller images.
  • Multi - to create an animated GIF from multiple images.
  • Text - to create an image from text.

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.

For more information on calling the API methods directly, see the documentation on Uploading with a direct call to the API. Direct calls to the API generally need to be authenticated, which means that they must always include at least the timestamp, api_key and signature parameters (see Creating API authentication signatures for more details). Note that this is not necessary when using the Cloudinary SDKs as all authentication is taken care of for you.

For more in depth documentation and general information on uploading images see the Upload images documentation.

SDK specific documentation can be found at:

Note: The Cloudinary Admin API also has useful methods for administering and organizing your image files, such as listing all uploaded images, listing tags, finding all images that share a given tag, updating transformations, bulk deleting, and more. See the documentation on the Cloudinary Admin API for more information.

Upload

The upload method is used to upload images to the cloud. For more information on all the options involved in uploading images, see the uploading images documentation.

Syntax:
RubyPHPPythonNode.jsJavaEndpointAll
Ruby:
result = Cloudinary::Uploader.upload(file, options = {})
PHP:
$result = \Cloudinary\Uploader::upload($file, $options = array());
Python:
result = cloudinary.uploader.upload(file, **options)
Node.js:
cloudinary.v2.uploader.upload(file, options, callback);
Java:
Map result = cloudinary.uploader().upload(String file, Map options);
Endpoint:
https://api.cloudinary.com/v1_1/<cloud_name>/image/upload
Required parameters:
Parameter Type Description
file String The file to upload. Can be a local file path (supported in SDKs only), the actual data (byte array buffer), the Data URI (Base64 encoded), a remote FTP, HTTP or HTTPS URL of an existing file, or an S3 URL (of a whitelisted bucket).
Optional parameters:
Parameter Type Description
public_id String The identifier that is used for accessing the uploaded resource. A randomly generated ID is assigned if not specified. The Public ID may contain a full path including folders separated by a slash (/).
use_filename Boolean Whether to use the original file name of the uploaded resource 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.
folder String An optional folder name where the uploaded resource will be stored. The Public ID contains the full path of the uploaded resource, including the folder name.
overwrite Boolean Whether to overwrite existing resources with the same Public ID. When set to false, return immediately if a resource with the same Public ID was found. Default: true (when using unsigned upload, the default is false and cannot be changed to true).
resource_type String Set the type of file uploading or 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.
type String Allows uploading resources 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.
tags String An array (using the SDKs) or comma-separated list (for direct API calls) of tag names to assign to the uploaded resource 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 resource. The context values of uploaded files are available for fetching using the Admin API. For example: alt=My imageâť?caption=Profile image.
transformation String An incoming transformation to run on the uploaded resource 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 resource to before saving in the cloud. For example: jpg.
allowed_formats String 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).
eager String An array (using the SDKs) or pipe-separated list (for direct API calls) of transformations to create for the uploaded resource during the upload process, instead of lazily creating each of them when first accessed by your site's visitors.
async Boolean Tells Cloudinary whether to perform the upload request in the background (asynchronously). Default: false.
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.
proxy String Tells Cloudinary to upload resources from remote URLs through the given proxy. Format: http://hostname:port.
headers String An HTTP header or a list of headers lines for returning as response HTTP headers when delivering the uploaded resource to your users. Supported headers: Link, X-Robots-Tag. For example: X-Robots-Tag: noindex.
callback String A URL to redirect your user to after the upload is completed. This is needed in case the upload process is done through an upload form in your website.
notification_url String 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.
eager_notification_url String An HTTP or HTTPS URL to send a notification to (a webhook) when the generation of eager transformations is completed.
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.
image_metadata Boolean Whether to return IPTC, XMP, and detailed Exif metadata of the uploaded photo in the upload response. Default: false.
exif Boolean Whether to retrieve the Exif metadata of the uploaded photo. Default: false. Deprecated - please use image_metadata instead
colors Boolean Whether to retrieve predominant colors & color histogram of the uploaded image. Default: false.
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.
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.
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.
backup Boolean Tell Cloudinary whether to backup the uploaded resource. Overrides the default backup settings of your account.
return_delete_token Boolean Whether to return a deletion token in the upload response. The token can be used to delete the uploaded resource within 10 minutes using an unauthenticated API request. Default: false.
invalidate Boolean Whether to invalidate CDN cached copies of a previously uploaded image (and all its transformed versions) that shares 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.
discard_original_filename Boolean Whether to discard the name of the original uploaded file. Relevant when delivering resources as attachments (setting the flag transformation parameter to attachment). Default: false.
moderation String Set to manual to add the uploaded image to a queue of pending moderation images that can be moderated using the Admin API or the Cloudinary Management Console. Set to webpurify to automatically moderate the uploaded image using the WebPurify Image Moderation add-on.
upload_preset String 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 directly allowed parameters to: public_id, folder, tags, context, face_coordinates and custom_coordinates.
raw_convert String Set to aspose to automatically convert Office documents to PDF files and other image formats using the Aspose Document Conversion add-on.
categorization String Set to imagga_tagging to automatically classify the scenes of the uploaded image. See Imagga Auto Tagging for more details.
auto_tagging Decimal Whether to assign tags to an image according to detected scene categories with a confidence score higher than the given value (between 0.0 and 1.0). See Imagga Auto Tagging for more details.
background_removal String Set to remove_the_background to automatically clear the background of an uploaded photo using the Remove-The-Background Editing add-on.
detection String Set to adv_face to extract an extensive list of face attributes from a photo using the Advanced Facial Attribute Detection add-on.
responsive_breakpoints JSON Requests that Cloudinary automatically find the best breakpoints. The parameter value is an 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: width, height, bytes, url and secure_url.

Note: Unauthenticated requests are restricted to the following allowed parameters: public_id, folder, callback, tags, context, face_coordinates and custom_coordinates.

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

RubyPHPPythonNode.jsJavacURLAll
Ruby:
Cloudinary::Uploader.upload("http://www.example.com/sample.jpg")
PHP:
\Cloudinary\Uploader::upload("http://www.example.com/sample.jpg");
Python:
cloudinary.uploader.upload("http://www.example.com/sample.jpg")
Node.js:
cloudinary.v2.uploader.upload("http://www.example.com/sample.jpg", 
        function(result) {console.log(result); });
Java:
cloudinary.uploader().upload("http://www.example.com/sample.jpg", 
        ObjectUtils.emptyMap());
cURL:
curl https://api.cloudinary.com/v1_1/demo/image/upload -X POST --data 'file=http://www.example.com/sample.jpg&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'

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:

  1. Pad to a width of 400 pixels and height of 300 pixels.
  2. Crop to a width of 260 pixels and a height of 200 pixels with north gravity.
RubyPHPPythonNode.jsJavacURLAll
Ruby:
Cloudinary::Uploader.upload("ftp://user1:mypass@ftp.example.com/sample.jpg",
            :eager => [
            {:width => 400, :height => 300, 
             :crop => :pad}, 
            {:width => 260, :height => 200, 
             :crop => :crop, :gravity => :north}])
PHP:
\Cloudinary\Uploader::upload("ftp://user1:mypass@ftp.example.com/sample.jpg", array( 
            "eager" => array(
              array("width" => 400, "height" => 300,
                  "crop" => "pad"),
              array("width" => 260, "height" => 200,
                  "crop" => "crop", "gravity" => "north"))));
Python:
cloudinary.uploader.upload("ftp://user1:mypass@ftp.example.com/sample.jpg", 
            eager = [
              {"width": 400, "height": 300,
                  "crop": "pad"},
              {"width": 260, "height": 200,
                  "crop": "crop", "gravity": "north"}])
Node.js:
cloudinary.v2.uploader.upload("ftp://user1:mypass@ftp.example.com/sample.jpg", 
        { eager: [
          { width: 400, height: 300,
              crop: "pad" }, 
          { width: 260, height: 200,
                  crop: "crop", gravity: "north"} ]}, 
        function(error, result) {console.log(result); });
Java:
cloudinary.uploader().upload("ftp://user1:mypass@ftp.example.com/sample.jpg", 
        ObjectUtils.asMap(
        "eager", Arrays.asList(
              new Transformation().width(400).height(300).crop("pad"),
              new Transformation().width(260).height(200).crop("crop").gravity("north"))));
cURL:
curl https://api.cloudinary.com/v1_1/demo/image/upload -X POST --data 'file=ftp://user1:mypass@ftp.example.com/sample.jpg&eager=w_400,h_300,c_pad|w_260,h_200,c_crop,g_north&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'
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.

{
  "public_id": "eneivicys42bq5f2jpn2",
  "version": 1473596672,
  "signature": "abcdefghijklmnopqrstuvwxyz12345",
  "width": 1000,
  "height": 672,
  "format": "jpg",
  "resource_type": "image",
  "created_at": "2016-09-11T12:24:32Z",
  "tags": [

  ],
  "bytes": 350749,
  "type": "upload",
  "etag": "5297bd123ad4ddad723483c176e35f6e",
  "url": "http://res.cloudinary.com/demo/image/upload/v1473596672/eneivicys42bq5f2jpn2.jpg",
  "secure_url": "https://res.cloudinary.com/demo/image/upload/v1473596672/eneivicys42bq5f2jpn2.jpg",
  "original_filename": "sample",
  "eager": [
    {
      "transformation": "c_pad,h_300,w_400",
      "width": 400,
      "height": 300,
      "url": "http://res.cloudinary.com/demo/image/upload/c_pad,h_300,w_400/v1473596672/eneivicys42bq5f2jpn2.jpg",
      "secure_url": "https://res.cloudinary.com/demo/image/upload/c_pad,h_300,w_400/v1473596672/eneivicys42bq5f2jpn2.jpg"
    },
    {
      "transformation": "c_crop,g_north,h_200,w_260",
      "width": 260,
      "height": 200,
      "url": "http://res.cloudinary.com/demo/image/upload/c_crop,g_north,h_200,w_260/v1473596672/eneivicys42bq5f2jpn2.jpg",
      "secure_url": "https://res.cloudinary.com/demo/image/upload/c_crop,g_north,h_200,w_260/v1473596672/eneivicys42bq5f2jpn2.jpg"
    }
  ]
}

Rename

Renamed images are immediately and permanently updated in your cloud storage with the rename method. The existing URLs of renamed images and their associated derived images are no longer valid, although images and transformed images already downloaded by visitors of your web site 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 image 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 images, see Invalidating cached images on the CDN.

Syntax:
RubyPHPPythonNode.jsJavaEndpointAll
Ruby:
result = Cloudinary::Uploader.rename(from_public_id, to_public_id, options = {})
PHP:
$result = \Cloudinary\Uploader::rename($from_public_id, $to_public_id, $options = array());
Python:
result = cloudinary.uploader.rename(from_public_id, to_public_id, **options)
Node.js:
cloudinary.v2.uploader.rename(from_public_id, to_public_id, options, callback);
Java:
Map result = cloudinary.uploader().rename(String from_public_id, String to_public_id, Map options);
Endpoint:
https://api.cloudinary.com/v1_1/<cloud_name>/image/rename
Required parameters:
Parameter Type Description
from_public_id String The current identifier of the uploaded image.
to_public_id String The new identifier to assign to the uploaded image.
Optional parameters:
Parameter Type Description
resource_type String The type of file 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.
type String The specific type of the resource. 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 resource. Valid values: upload, private and authenticated. Default: the type remains the same as before.
overwrite Boolean Whether to overwrite an existing resource with the target Public ID. Default: false.
invalidate Boolean Whether to invalidate CDN cached copies of the image (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
Example:

To rename an image from canyon to grand_canyon:

RubyPHPPythonNode.jsJavacURLAll
Ruby:
Cloudinary::Uploader.rename('canyon', 'grand_canyon')
PHP:
\Cloudinary\Uploader::rename('canyon', 'grand_canyon');
Python:
cloudinary.uploader.rename('canyon', 'grand_canyon')
Node.js:
cloudinary.v2.uploader.rename('canyon', 'grand_canyon',
        function(error,result) {console.log(result) });
Java:
cloudinary.uploader().rename("canyon", "grand_canyon", 
        ObjectUtils.emptyMap());
cURL:
curl https://api.cloudinary.com/v1_1/demo/image/rename -X POST --data 'from_public_id=canyon&to_public_id=grand_canyon&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'
Sample JSON response:

The following is a sample JSON response based on the example above. The canyon image was renamed to grand_canyon. 

{
  "public_id": "grand_canyon",
  "version": 1473597073,
  "signature": "abcdefghijklmnopqrstuvwxyz12345",
  "width": 2896,
  "height": 1944,
  "format": "jpg",
  "resource_type": "image",
  "created_at": "2016-09-11T12:31:13Z",
  "tags": [

  ],
  "bytes": 1414789,
  "type": "upload",
  "url": "http://res.cloudinary.com/demo/image/upload/v1473597073/grand_canyon.jpg",
  "secure_url": "https://res.cloudinary.com/demo/image/upload/v1473597073/grand_canyon.jpg"
}

Destroy

The destroy method is used to immediately and permanently delete images from your Cloudinary account. Backed up images are not deleted, and any images and transformed images 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 image 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 images, see Invalidating cached images on the CDN.

Syntax:
RubyPHPPythonNode.jsJavaEndpointAll
Ruby:
result = Cloudinary::Uploader.destroy(public_id, options = {})
PHP:
$result = \Cloudinary\Uploader::destroy($public_id, $options = array());
Python:
result = cloudinary.uploader.destroy(public_id, **options)
Node.js:
cloudinary.v2.uploader.destroy(public_id, options, callback);
Java:
Map result = cloudinary.uploader().destroy(String public_id, Map options);
Endpoint:
https://api.cloudinary.com/v1_1/<cloud_name>/image/destroy
Required parameters:
Parameter Type Description
public_id String The identifier of the uploaded image.
Optional parameters:
Parameter Type Description
resource_type String The type of file 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.
type String The specific type of the resource. 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 image (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.
Example:

Deleting an image with the Public ID of "sample":

RubyPHPPythonNode.jsJavacURLAll
Ruby:
Cloudinary::Uploader.destroy('sample')
PHP:
\Cloudinary\Uploader::destroy('sample');
Python:
cloudinary.uploader.destroy('sample')
Node.js:
cloudinary.v2.uploader.destroy('sample', function(error,result) {
        console.log(result) });
Java:
cloudinary.uploader().destroy('sample',
        ObjectUtils.emptyMap());
cURL:
curl https://api.cloudinary.com/v1_1/demo/image/destroy -X POST --data 'public_id=sample&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'
Sample JSON response:

A successful destroy operation returns the following:

{"result"=>"ok"}

Tags

Tags are used to categorize and organize your images, and can also be used to apply group actions to images, for example to delete images, create sprites, ZIP files, JSON lists, or animated GIFs. Each image can be assigned one or more tags, which is a short name 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 or replace tags. The Cloudinary SDKs wrap the tags method and offer 3 separate methods: one for adding tags, one for removing tags, and one for replacing tags.

Adding tags syntax:
RubyPHPPythonNode.jsJavaEndpointAll
Ruby:
result = Cloudinary::Uploader.add_tag(tag, public_ids, options = {})
PHP:
$result = \Cloudinary\Uploader::add_tag($tag, $public_ids, $options = array());
Python:
result = cloudinary.uploader.add_tag(tag, public_ids, **options)
Node.js:
cloudinary.v2.uploader.add_tag(tag, public_ids, options, callback);
Java:
Map result = cloudinary.uploader().addTag(String tag, String public_ids, Map options);
Endpoint:
https://api.cloudinary.com/v1_1/<cloud_name>/image/tags
Removing tags syntax:
RubyPHPPythonNode.jsJavaEndpointAll
Ruby:
result = Cloudinary::Uploader.remove_tag(tag, public_ids, options = {})
PHP:
$result = \Cloudinary\Uploader::remove_tag($tag, $public_ids, $options = array());
Python:
result = cloudinary.uploader.remove_tag(tag, public_ids, **options)
Node.js:
cloudinary.v2.uploader.remove_tag(tag, public_ids, options, callback);
Java:
Map result = cloudinary.uploader().removeTag(String tag, String public_ids, Map options);
Endpoint:
https://api.cloudinary.com/v1_1/<cloud_name>/image/tags
Replacing tags syntax:
RubyPHPPythonNode.jsJavaEndpointAll
Ruby:
result = Cloudinary::Uploader.replace_tag(tag, public_ids, options = {})
PHP:
$result = \Cloudinary\Uploader::replace_tag($tag, $public_ids, $options = array());
Python:
result = cloudinary.uploader.replace_tag(tag, public_ids, **options)
Node.js:
cloudinary.v2.uploader.replace_tag(tag, public_ids, options, callback);
Java:
Map result = cloudinary.uploader().replaceTag(String tag, String public_ids, Map options);
Endpoint:
https://api.cloudinary.com/v1_1/<cloud_name>/image/tags
Required parameters:
Parameter Type Description
tag String The tag to assign, remove, or replace.
public_ids String A list of Public IDs of images uploaded to Cloudinary.
command String (Only relevant when using the API method directly - not for use with SDKs) The action to perform on image resources using the given tag. Either add the given tag, remove the given tag, 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 file to tag. 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.
type String The specific type of the resource. 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

RubyPHPPythonNode.jsJavacURLAll
Ruby:
Cloudinary::Uploader.add_tag('animal', ['dog', 'lion'])
PHP:
\Cloudinary\Uploader::add_tag('animal', array('dog', 'lion'));
Python:
cloudinary.uploader.add_tag('animal', ['dog', 'lion'])
Node.js:
cloudinary.v2.uploader.add_tag('animal', [ 'dog', 'lion' ],
        function(result) { console.log(result) });
Java:
cloudinary.uploader().addTag("animal",
        ["dog", "lion"], ObjectUtils.emptyMap());
cURL:
curl https://api.cloudinary.com/v1_1/demo/image/tags -X POST --data 'tag=animal&public_ids=dog,lion&command=add&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'

To remove the tag animal from the images with the Public IDs of dog and lion

RubyPHPPythonNode.jsJavacURLAll
Ruby:
Cloudinary::Uploader.remove_tag('animal', ['dog', 'lion'])
PHP:
\Cloudinary\Uploader::remove_tag('animal', array('dog', 'lion'));
Python:
cloudinary.uploader.remove_tag('animal', ['dog', 'lion'])
Node.js:
cloudinary.v2.uploader.remove_tag('animal', [ 'dog', 'lion' ],
        function(result) { console.log(result) });
Java:
cloudinary.uploader().removeTag("animal",
        ["dog", "lion"], ObjectUtils.emptyMap());
cURL:
curl https://api.cloudinary.com/v1_1/demo/image/tags -X POST --data 'tag=animal&public_ids=dog,lion&command=remove&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'

To replace all existing tags with the tag animal for the images with the Public IDs of dog and lion

RubyPHPPythonNode.jsJavacURLAll
Ruby:
Cloudinary::Uploader.replace_tag('animal', ['dog', 'lion'])
PHP:
\Cloudinary\Uploader::replace_tag('animal', array('dog', 'lion'));
Python:
cloudinary.uploader.replace_tag('animal', ['dog', 'lion'])
Node.js:
cloudinary.v2.uploader.replace_tag('animal', [ 'dog', 'lion' ],
        function(result) { console.log(result) });
Java:
cloudinary.uploader().replaceTag("animal",
        ["dog", "lion"], ObjectUtils.emptyMap());
cURL:
curl https://api.cloudinary.com/v1_1/demo/image/tags -X POST --data 'tag=animal&public_ids=dog,lion&command=replace&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'
Sample JSON response:

The following is a sample JSON response based on the example above. A tag was added to the dog and lion images. 

{
  "public_ids": [
    "dog",
    "lion"
  ]
}

Explicit

The explicit method is used to apply actions to already uploaded images, i.e., to update images that have already been uploaded. The most common usage of this method is to generate transformations for images 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 images on the fly (for more information, see Access control to images). You can also use this method to pregenerate transformations for remotely fetched images.

For more information see the documentation on updating already uploaded images.

Syntax:
RubyPHPPythonNode.jsJavaEndpointAll
Ruby:
result = Cloudinary::Uploader.explicit(public_id, options = {})
PHP:
$result = \Cloudinary\Uploader::explicit($public_id, $options = array());
Python:
result = cloudinary.uploader.explicit(public_id, **options)
Node.js:
cloudinary.v2.uploader.explicit(public_id, options, callback);
Java:
Map result = cloudinary.uploader().explicit(String public_id, Map options);
Endpoint:
https://api.cloudinary.com/v1_1/<cloud_name>/image/explicit
Required parameters:
Parameter Type Description
public_id String The identifier of the uploaded image or the URL of the remote resource.
type String The specific type of resource. Valid values for uploaded images: upload, private, or authenticated. Valid values for remote images: fetch, facebook, twitter, gplus, instagram_name, gravatar, youtube, hulu, vimeo, animoto, worldstarhiphop or dailymotion.
Optional parameters:
Parameter Type Description
eager String A list of transformations to create for the uploaded image, instead of lazily creating them when first accessed by your site's visitors (see the Image 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 resource.
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 image that replaces any current tags assigned to the image (if any).
invalidate Boolean Whether to invalidate the image (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 resource. 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 resource 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.
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.
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 retrieve IPTC and detailed Exif metadata of the uploaded photo. Default: false.
colors Boolean Whether to retrieve predominant colors & color histogram of the uploaded image. Default: false.
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.
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.
raw_convert String Set to aspose to automatically convert Office documents to PDF files and other image formats using the Aspose Document Conversion add-on.
categorization String Set to imagga_tagging to automatically classify the scenes of the uploaded image. See Imagga Auto Tagging for more details.
auto_tagging Decimal Whether to assign tags to an image according to detected scene categories with a confidence score higher than the given value (between 0.0 and 1.0). See Imagga Auto Tagging for more details.
background_removal String Set to remove_the_background to automatically clear the background of an uploaded photo using the Remove-The-Background Editing add-on.
detection String Set to adv_face to extract an extensive list of face attributes from a photo using the Advanced Facial Attribute Detection add-on.
responsive_breakpoints JSON Requests that Cloudinary automatically find the best breakpoints. The parameter value is an 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: width, height, bytes, url and secure_url.
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.
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 explicitly create two transformed images for the already uploaded image with a Public ID of sample as follows:

  1. Crop to a width and height of 400 pixels including the biggest face detected.
  2. Pad to a width of 660 pixels and a height of 400 pixels with a blue background.
RubyPHPPythonNode.jsJavacURLAll
Ruby:
Cloudinary::Uploader.explicit("sample", 
    :type => "upload",
    :eager => [
      {:width => 400, :height => 400, 
       :crop => :crop, :gravity => :face}, 
      {:width => 660, :height => 400, 
       :crop => :pad, :background => "blue"}])
PHP:
\Cloudinary\Uploader::explicit("sample", 
    array(
        "type" => "upload", 
        "eager" => array(
            array(
                "width" => 400, "height" => 400,
                "crop" => "crop", "gravity" => "face"),
            array(
                "width" => 660, "height" => 400,
                "crop" => "pad", "background" => "blue"))));
Python:
cloudinary.uploader.explicit("sample", 
    type = "upload",
    eager = [
        {"width": 400, "height": 400,
         "crop": "crop", "gravity": "face"},
        {"width": 660, "height": 400,
         "crop": "pad", "background": "blue"}])
Node.js:
cloudinary.v2.uploader.explicit("sample", 
    { type: "upload",
      eager: [
        { width: 400, height: 400,
          crop: "crop", gravity: "face"}, 
        { width: 660, height: 400,
          crop: "pad", background: "blue"} ]}, 
    function(error, result) {console.log(result); });
Java:
cloudinary.uploader().explicit("sample", 
    ObjectUtils.asMap(
        "type", "upload",
        "eager", Arrays.asList(
            new Transformation().width(400).height(400).crop("crop").gravity("face"),
            new Transformation().width(660).height(400).crop("pad").background("blue"))));
cURL:
curl https://api.cloudinary.com/v1_1/demo/image/explicit -X POST --data 'public_id==sample&eager=w_400,h_400,c_crop,g_face|w_660,h_400,c_pad,b_blue&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'
Sample JSON response:

The following is a sample JSON response based on the example above. Two explicit transformations were performed on the sample image.

{
  "public_id": "sample",
  "version": 1473599877,
  "signature": "abcdefghijklmnopqrstuvwxyz12345",
  "width": 864,
  "height": 576,
  "format": "jpg",
  "resource_type": "image",
  "created_at": "2016-09-11T13:17:57Z",
  "bytes": 109669,
  "type": "upload",
  "url": "http://res.cloudinary.com/demo/image/upload/v1473599877/sample.jpg",
  "secure_url": "https://res.cloudinary.com/demo/image/upload/v1473599877/sample.jpg",
  "eager": [
    {
      "transformation": "c_crop,g_face,h_400,w_400",
      "width": 400,
      "height": 400,
      "url": "http://res.cloudinary.com/demo/image/upload/c_crop,g_face,h_400,w_400/v1473599877/sample.jpg",
      "secure_url": "https://res.cloudinary.com/demo/image/upload/c_crop,g_face,h_400,w_400/v1473599877/sample.jpg"
    },
    {
      "transformation": "b_blue,c_pad,h_400,w_660",
      "width": 660,
      "height": 400,
      "url": "http://res.cloudinary.com/demo/image/upload/b_blue,c_pad,h_400,w_660/v1473599877/sample.jpg",
      "secure_url": "https://res.cloudinary.com/demo/image/upload/b_blue,c_pad,h_400,w_660/v1473599877/sample.jpg"
    }
  ]
}

Explode

The explode method creates derived images for all of the individual pages in a PDF file. Each derived image is stored with the same Public ID as the PDF file, and can be accessed using the page parameter, in order to deliver the image of a specific PDF page (see the documentation on Creating images from PDF files).

You could deliver individual pages of a PDF on-the-fly without the explode method. This method is useful for pregenerating all the pages of the PDF as a chunk explicit transformation, so that they do not need to be generated on-the-fly when first accessed by your users.

Syntax:
RubyPHPPythonNode.jsJavaEndpointAll
Ruby:
result = Cloudinary::Uploader.explode(public_id, options = {})
PHP:
$result = \Cloudinary\Uploader::explode($public_id, $options = array());
Python:
result = cloudinary.uploader.explode(public_id, **options)
Node.js:
cloudinary.v2.uploader.explode(public_id, options, callback);
Java:
Map result = cloudinary.uploader().explode(String public_id, Map options);
Endpoint:
https://api.cloudinary.com/v1_1/<cloud_name>/image/explode
Required parameters:
Parameter Type Description
public_id String The identifier of the uploaded PDF file.
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.
Optional parameters:
Parameter Type Description
type String The specific file type of the resource. Valid values: upload, private and authenticated. Default: upload.
format String An optional format to convert the images before storing them in your Cloudinary account Default: jpg.
async Boolean Tells Cloudinary whether to perform the image 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.
Example:

To explode a PDF with the Public ID of "sample.pdf":

RubyPHPPythonNode.jsJavacURLAll
Ruby:
Cloudinary::Uploader.explode('sample.pdf', 
    :page => 'all')
PHP:
\Cloudinary\Uploader::explode('sample.pdf', 
    array(
        'page' => 'all'));
Python:
cloudinary.uploader.explode('sample.pdf', 
    page = 'all')
Node.js:
cloudinary.v2.uploader.explode('sample.pdf', 
    { page: 'all'},
    function(error,result) {console.log(result) });
Java:
cloudinary.uploader().explode('sample.pdf',
    ObjectUtils.asMap('transformation', new Transformation().page('all'));
cURL:
curl https://api.cloudinary.com/v1_1/demo/image/explode -X POST --data 'public_id=sample.pdf&transformation=pg_all&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'
Sample JSON response:

The following is a sample JSON response indicating that the explode command is in process. 

{
  "status": "processing",
  "batch_id": "4e485321b4a6f9692089cf40ab9aaa255b92afd8ecc17e1d415ae0a29dd31c42dc0b9139214ff488bba9ec8329482903"
}

Generate_archive

The generate_archive method creates an archive file that contains all the images meeting specified tag, Public ID, or prefix criteria (or a combination thereof). The method can be used directly to either return the generated archive file ('download') or to store it as a raw resource in your Cloudinary account ('create'), by setting the value of the mode parameter.

By default, if all the images in the archive have the identical transformation applied, they are stored in the archive with the original image filename only, regardless of the value of the flatten_transformations or skip_transformation_name parameters. If images with different transformations are included in the archive, then the relevant transformation data is appended to the filename of each image, according to the settings of the flatten_transformations or skip_transformation_name parameters.

The Cloudinary SDKs wrap the generate_archive method and offer 4 separate methods:

  • 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, 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: 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: 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.
create_zip syntax:
RubyPHPPythonNode.jsJavaEndpointAll
Ruby:
result = Cloudinary::Uploader.create_zip(options = {})
PHP:
$result = \Cloudinary\Uploader::create_zip($options = array());
Python:
result = cloudinary.uploader.create_zip(**options)
Node.js:
cloudinary.v2.uploader.create_zip(options, callback);
Java:
Map result = cloudinary.uploader().createZip(Map options);
Endpoint:
https://api.cloudinary.com/v1_1/<cloud_name>/image/generate_archive
create_archive syntax:
RubyPHPPythonNode.jsJavaEndpointAll
Ruby:
result = Cloudinary::Uploader.create_archive(options = {})
PHP:
$result = \Cloudinary\Uploader::create_archive($options = array());
Python:
result = cloudinary.uploader.create_archive(**options)
Node.js:
cloudinary.v2.uploader.create_archive(options, callback);
Java:
Map result = cloudinary.uploader().createArchive(Map options);
Endpoint:
https://api.cloudinary.com/v1_1/<cloud_name>/image/generate_archive
download_zip_url syntax:
RubyPHPPythonNode.jsJavaEndpointAll
Ruby:
url = Cloudinary::Utils.download_zip_url(options = {})
PHP:
$url = \Cloudinary\Utils::download_zip_url($options = array());
Python:
url = cloudinary.utils.download_zip_url(**options)
Node.js:
cloudinary.utils.download_zip_url(options, callback);
Java:
String url = cloudinary.utils().downloadZipUrl(Map options);
Endpoint:
https://api.cloudinary.com/v1_1/<cloud_name>/image/generate_archive
download_archive_url syntax:
RubyPHPPythonNode.jsJavaEndpointAll
Ruby:
url = Cloudinary::Utils.download_archive_url(options = {})
PHP:
$url = \Cloudinary\Utils::download_archive_url($options = array());
Python:
url = cloudinary.utils.download_archive_url(**options)
Node.js:
cloudinary.utils.download_archive_url(options, callback);
Java:
String url = cloudinary.utils().downloadArchiveUrl(Map options);
Endpoint:
https://api.cloudinary.com/v1_1/<cloud_name>/image/generate_archive
Required parameters:

At least one of the following "filtering" parameters needs to be specified, in order to tell Cloudinary which resources to include in the archive file. Specifying any combination of the three parameters is also allowed - a unique union of all the matching resources 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 images with the specified tags are included in the archive.
public_ids String An array (using the SDKs) or comma-separated list (for direct API calls) of Public IDs for the specific images to be included in the archive.
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 images in the account for the given resource type and type (up to the max files limit).
Optional parameters:
Parameter Type Description
resource_type String The resource type (image, video or raw) of files to include in the archive: Default: image.
type String The specific file type of resources 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 images 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 images are 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 resource 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 images 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 images (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 images used for generating the archive. Default: false.
Examples:

To create a zip file that contains all images that have the lion tag:

RubyPHPPythonNode.jsJavacURLAll
Ruby:
Cloudinary::Uploader.create_zip(
    :tags => 'lion', 
    :resource_type => 'image')
PHP:
\Cloudinary\Uploader::create_zip(
    array(
        'tags' => 'lion', 
        'resource_type' => 'image'));
Python:
cloudinary.uploader.create_zip(
    tags = 'lion', 
    resource_type = 'image')
Node.js:
cloudinary.v2.uploader.create_zip(
    { tags: 'lion', resource_type: 'image'},
    function(error,result) {console.log(result) });
Java:
cloudinary.uploader().createZip(
    ObjectUtils.asMap('tags', 'lion', 'resource_type', 'image'));
cURL:
curl https://api.cloudinary.com/v1_1/demo/image/generate_archive -X POST --data 'tags=lion&resource_type=image&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'

To generate a URL for downloading a zip file that contains the images with the following public_ids: dog, cat and lion:

RubyPHPPythonNode.jsJavacURLAll
Ruby:
Cloudinary::Utils.download_zip_url(
    :public_ids => 'dog,cat,lion', 
    :resource_type => 'image')
PHP:
\Cloudinary\Utils::download_zip_url(
    array(
        'public_ids' => 'dog,cat,lion', 
        'resource_type' => 'image'));
Python:
cloudinary.utils.download_zip_url(
    public_ids = 'dog,cat,lion', 
    resource_type = 'image')
Node.js:
cloudinary.v2.utils.download_zip_url(
    { public_ids: 'dog,cat,lion', resource_type: 'image'},
    function(error,result) {console.log(result) });
Java:
cloudinary.utils().downloadZipUrl(
    ObjectUtils.asMap('public_ids', 'dog,cat,lion', 'resource_type', 'image'));
cURL:
curl https://api.cloudinary.com/v1_1/demo/image/generate_archive -X POST --data 'public_ids[]=dog&public_ids[]=cat&public_ids[]=lion&resource_type=image&mode=download&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'
Sample JSON response:

The following is a sample JSON response based on the create_zip example above. 6 image resources 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.


{
  "public_id": "oe5bz4vbtdg0ijr323on.zip",
  "version": 1473689011,
  "signature": "abcdefghijklmnopqrstuvwxyz12345",
  "resource_type": "raw",
  "created_at": "2016-09-12T14:03:31Z",
  "tags": [

  ],
  "bytes": 1153022,
  "type": "upload",
  "etag": "00e3a782aa2c390dc605d0548d067177",
  "url": "http://res.cloudinary.com/demo/raw/upload/v1473689011/oe5bz4vbtdg0ijr323on.zip",
  "secure_url": "https://res.cloudinary.com/demo/raw/upload/v1473689011/oe5bz4vbtdg0ijr323on.zip",
  "resource_count": 6,
  "file_count": 6
}

Generate_sprite

Cloudinary supports generating sprites by merging multiple images into a single large image for reducing network overhead and bypassing download limitations. The browser downloads only a single image and a CSS file that directs the browser to which part of the sprite to use for displaying each contained image. The 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.

For a detailed explanation on generating and using sprites, see the documentation on sprite generation.

Syntax:
RubyPHPPythonNode.jsJavaEndpointAll
Ruby:
result = Cloudinary::Uploader.generate_sprite(tag, options = {})
PHP:
$result = \Cloudinary\Uploader::generate_sprite($tag, $options = array());
Python:
result = cloudinary.uploader.generate_sprite(tag, **options)
Node.js:
cloudinary.v2.uploader.generate_sprite(tag, options, callback);
Java:
Map result = cloudinary.uploader().generateSprite(String tag, Map options);
Endpoint:
https://api.cloudinary.com/v1_1/<cloud_name>/image/generate_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 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.
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.
Example:

Generating a sprite from all images tagged with logo, creates a single PNG image file with the Public ID of logo that contains all the tagged images, and a CSS file with the Public ID of logo.css.

RubyPHPPythonNode.jsJavacURLAll
Ruby:
Cloudinary::Uploader.generate_sprite('logo')
PHP:
\Cloudinary\Uploader::generate_sprite('logo');
Python:
cloudinary.uploader.generate_sprite('logo')
Node.js:
cloudinary.v2.uploader.generate_sprite('logo',
    function(error,result) {console.log(result) });
Java:
cloudinary.uploader().generateSprite('logo', 
        ObjectUtils.emptyMap());
cURL:
curl https://api.cloudinary.com/v1_1/demo/image/generate_sprite -X POST --data 'tag=logo&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'
Sample JSON response:

The following is a sample JSON response based on the example above. 3 images with the tag logo were added to the logo png and css files to create the sprite.

{
  "css_url": "http://res.cloudinary.com/demo/image/sprite/v1473689611/logo.css",
  "image_url": "http://res.cloudinary.com/demo/image/sprite/v1473689611/logo.png",
  "secure_css_url": "https://res.cloudinary.com/demo/image/sprite/v1473689611/logo.css",
  "json_url": "http://res.cloudinary.com/demo/image/sprite/v1473689611/logo.json",
  "version": 1473689611,
  "public_id": "logo",
  "image_infos": {
    "logo_slogan": {
      "width": 300,
      "height": 165,
      "x": 0,
      "y": 0
    },
    "http://cloudinary.com/product_icon.png": {
      "width": 32,
      "height": 32,
      "x": 0,
      "y": 167
    },
    "http://cloudinary.com/images/logo.png": {
      "width": 165,
      "height": 165,
      "x": 0,
      "y": 201
    }
  }
}

Multi

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.

Syntax:
RubyPHPPythonNode.jsJavaEndpointAll
Ruby:
result = Cloudinary::Uploader.multi(tag, options = {})
PHP:
$result = \Cloudinary\Uploader::multi($tag, $options = array());
Python:
result = cloudinary.uploader.multi(tag, **options)
Node.js:
cloudinary.v2.uploader.multi(tag, options, callback);
Java:
Map result = cloudinary.uploader().multi(String tag, Map options);
Endpoint:
https://api.cloudinary.com/v1_1/<cloud_name>/image/multi
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.
async Boolean Tells Cloudinary whether to perform the GIF generation in the background (asynchronously). Default: false.
format String Can be set to 'zip' to generate a zip file containing the images instead of an animated GIF file. Default: gif (deprecated - use the new generate_archive method to create zip files)
notification_url String An HTTP or HTTPS URL to notify your application (a webhook) when the process has completed.
Example:

Generating an animated GIF from all images tagged with logo:

RubyPHPPythonNode.jsJavacURLAll
Ruby:
Cloudinary::Uploader.multi('logo')
PHP:
\Cloudinary\Uploader::multi('logo');
Python:
cloudinary.uploader.multi('logo')
Node.js:
cloudinary.v2.uploader.multi('logo',
    function(error,result) {console.log(result) });
Java:
cloudinary.uploader().multi('logo', ObjectUtils.emptyMap());
cURL:
curl https://api.cloudinary.com/v1_1/demo/image/multi -X POST --data 'tag=logo&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'
Sample JSON response:

The following is a sample JSON response based on the example above. An animated logo.gif image was created from all the images with the tag logo.

{
  "url": "http://res.cloudinary.com/demo/image/multi/v1473690796/logo.gif",
  "secure_url": "https://res.cloudinary.com/demo/image/multi/v1473690796/logo.gif",
  "public_id": "logo",
  "version": 1473690796
}

Text

You can use Cloudinary to dynamically generate an image from a given textual string with the text method. You can then use this textual image as any other image, for example, as an overlay for other images. Various font, color and style parameters can be specified to customize the look & feel of the text before converting it to an image.

Syntax:
RubyPHPPythonNode.jsJavaEndpointAll
Ruby:
result = Cloudinary::Uploader.text(text, options = {})
PHP:
$result = \Cloudinary\Uploader::text($text, $options = array());
Python:
result = cloudinary.uploader.text(text, **options)
Node.js:
cloudinary.v2.uploader.text(text, options, callback);
Java:
Map result = cloudinary.uploader().text(String text, Map options);
Endpoint:
https://api.cloudinary.com/v1_1/<cloud_name>/image/text
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.
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":

RubyPHPPythonNode.jsJavacURLAll
Ruby:
Cloudinary::Uploader.text("Sample text string",
    :public_id => "sample_text_image",
    :font_family => "Roboto", 
    :font_size => 42,
    :font_color => "red",
    :font_weight => "bold")
PHP:
\Cloudinary\Uploader::text("Sample text string",
    array(
        "public_id" => "sample_text_image",
        "font_family" => "Roboto", 
        "font_size" => 42,
        "font_color" => "red", 
        "font_weight" => "bold"));
Python:
cloudinary.uploader.text("Sample text string",
    public_id = 'sample_text_image',
    font_family = 'Roboto', 
    font_size = 42,
    font_color = 'red',
    font_weight = 'bold')
Node.js:
cloudinary.v2.uploader.text("Sample text string",
    { public_id: "sample_text_image",
      font_family: "Roboto", 
      font_size: 42,
      font_color: "red", 
      font_weight: "bold" }, 
    function(result) { console.log(result) });
Java:
cloudinary.uploader.text("Sample text string",
    ObjectUtils.asMap(
        "public_id", "sample_text_image",
        "font_family", "Roboto",
        "font_size", 42,
        "font_color", "red",
        "font_weight", "bold"));
cURL:
curl https://api.cloudinary.com/v1_1/demo/image/text -X POST --data 'public_id=sample_text_image&font_family=Roboto&font_size=42&font_color=red&font_weight=bold&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'
Sample JSON response:

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

{
  "public_id": "sample_text_image",
  "version": 1473692896,
  "signature": ""abcdefghijklmnopqrstuvwxyz12345"",
  "width": 342,
  "height": 41,
  "format": "png",
  "resource_type": "image",
  "created_at": "2016-09-12T15:08:16Z",
  "tags": [

  ],
  "bytes": 3670,
  "type": "text",
  "url": "http://res.cloudinary.com/demo/image/text/v1473692896/sample_text_image.png",
  "secure_url": "https://res.cloudinary.com/demo/image/text/v1473692896/sample_text_image.png"
}