Upload API reference

The upload API consists of a number of methods for uploading and managing media assets in the cloud. The REST API methods can be called directly from within your own custom code or by using one of Cloudinary's SDKs that wrap the REST 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.
SDK-specific documentation can be found in the SDK Guides.
For more information on calling the REST API methods directly, see the documentation on Uploading with a direct call to the API.
For instructions on setting up and using the CLI to access the upload API methods see the CLI reference.

Note

All the methods in this API also require a signature to authenticate the request on the Cloudinary servers. The Cloudinary SDKs automatically generate this signature for you, so you only need to add it when using the REST API calls directly to the endpoint. For more details on how to manually generate a signature, see the Generating authentication signatures documentation.

On this page:

Upload method
Rename method
Destroy method
Download_backup method
Tags method
Context method
Metadata method
Explicit method
Explode method
Generate_archive method
Sprite method
Multi method
Text method

Upload method

The upload method is used to upload assets to the cloud.

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

Signed upload syntax

POST /:resource_type/upload

Ruby PHP v1 PHP v2 Python Node.js Java .NET Android iOS CLI All

Ruby:

result = Cloudinary::Uploader.upload(file, options = {})

PHP v1:

$result = \Cloudinary\Uploader::upload($file, $options = array());

PHP v2:

$result = $cloudinary->uploadApi()->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);

.NET:

var uploadResult = cloudinary.Upload(UploadParams params);

Android:

MediaManager.get().upload(file).dispatch();

iOS:

cloudinary.createUploader().signedUpload(url: file, params: params)

CLI:

cld uploader upload $file $options

Unsigned upload syntax

POST /:resource_type/upload

Ruby PHP v1 PHP v2 Python Node.js Java .NET Android iOS CLI All

Ruby:

result = Cloudinary::Uploader.unsigned_upload(file, upload_preset, options = {})

PHP v1:

$result = \Cloudinary\Uploader::unsigned_upload($file, $upload_preset, $options = array());

PHP v2:

$result = $cloudinary->uploadApi()->unsignedUpload($file, $upload_preset, $options = []);

Python:

result = cloudinary.uploader.unsigned_upload(file, upload_preset, **options)

Node.js:

cloudinary.v2.uploader.unsigned_upload(file, upload_preset, options, callback);

Java:

Map result = cloudinary.uploader().unsignedUpload(String file, String uploadPreset, Map options);

.NET:

var uploadResult = cloudinary.Upload(UploadParams params);

Android:

MediaManager.get().upload(file).unsigned(upload_preset).dispatch();

iOS:

cloudinary.createUploader().signedUpload(url: file, uploadPreset: preset)

CLI:

cld uploader unsigned_upload $file $upload_preset $options

Required parameters

Parameter	Type	Description
file	String	The file to upload. It can be: a local file path (supported in SDKs only) the actual data (byte array buffer). For example, in some SDKs, this could be an IO input stream of the data (e.g., File.open(file, "rb")). the Data URI (Base64 encoded), max ~60 MB (62,910,000 chars) the remote FTP, HTTP or HTTPS URL address of an existing file a private storage bucket (S3 or Google Storage) URL of a whitelisted bucket For details and examples, see: file source options.
upload_preset	String	(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`.
signature	String	(Required for REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs, the signature is automatically generated and added to the request. If you manually generate your own POST request, you also need to manually generate this signature and add it to the request.

Optional parameters

Parameter	Type	Description
`Naming and storage:`
public_id	String	The identifier that is used for accessing the uploaded asset. The Public ID may contain a full path including folders separated by a slash (`/`). If not specified, then the Public ID of the asset will either be comprised of random characters or will use the original file's filename, depending whether `use_filename` was set to true. 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. Relevant only if the `public_id` parameter isn't set. When false and the `public_id` parameter is also not defined, the Public ID will be comprised of random characters. When true and the `public_id` parameter is not defined, the uploaded file's original filename becomes the Public ID. Random characters are appended to the filename value to ensure Public ID uniqueness if `unique_filename` is true. Default: `false`.
unique_filename	Boolean	When set to false, does not add random characters at the end of the filename that guarantee its uniqueness. In this case, if the `overwrite` parameter is also false, the upload returns an error. This parameter is relevant only 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 when using the REST 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	The delivery type. Allows uploading assets as `private` or `authenticated` instead of the default `upload` mode. Only relevant as a parameter when using the SDKs (the delivery `type` value is part of the endpoint URL when using the REST API). Valid values: `upload`, `private` and `authenticated`. Default: `upload`.
access_control	JSON	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: - `token` requires either Token-based authentication or Cookie-based authentication for accessing the asset. For example: `access_type: "token"` - `anonymous` allows public access to the asset. The anonymous access type can optionally include `start` and/or `end` dates (in ISO 8601 format) that define when the asset is 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, a response is returned immediately if an asset with the same Public ID was found. When overwriting assets, if you include versions in your delivery URLs, you will need to update the URLs with the new version number to deliver the new asset. If you don't include versions, you will need to invalidate the old assets on the CDN server cache. Default: `true` (when using unsigned upload, the default is false and cannot be changed to true). Important: Depending on the settings for your account, overwriting an asset may clear the tags, contextual, and structured metadata values for that asset. If you have a master admin role, you can change this behavior for your account in the Media Library Preferences pane, so that these field values are retained when new version assets overwrite older ones (unless you specify different values for the `tags`, `context`, or `metadata` parameters as part of your upload).
`Resource data:`
tags	String	A comma-separated list of tag names to assign to the uploaded asset for later group reference. For example: `animal,dog` SDKs: Supports arrays. For example: `['animal', 'dog']`
context	String	A pipe-separated list of the key-value pairs of contextual metadata to attach to an uploaded asset. The contextual metadata values of uploaded files can be retrieved using the Admin API. For example: `alt=My image❘caption=Profile image` Notes: The `=` and `❘` characters can be supported as values when escaped with a prepended backslash (`\`). Key values are limited to 1024 characters and an asset can have a maximum of 1000 contextual metadata key-value pairs. SDKs: Supports maps. For example: `['alt': 'My image', 'caption': 'Profile image']`
metadata	String	(Not supported for SDKs) A pipe-separated list of custom metadata fields (by external_id) and the values to assign to each of them. For example: `in_stock_id=50❘color_id=[\"green\",\"red\"]`. Notes: The `=` and `❘` characters can be supported as values when escaped with a prepended backslash (`\`). Metadata values are limited to 1024 characters and you can set a maximum of 1000 different metadata values on an asset.
colors	Boolean	Whether to retrieve predominant colors & color histogram of the uploaded image. Note:If all returned colors are opaque, then 6-digit RGB hex values are returned. If one or more colors contain an alpha channel, then 8-digit RGBA hex quadruplet values are returned. Default: `false`. Relevant for images only.
faces	Boolean	Whether to return the coordinates of faces contained in an uploaded image (automatically detected or manually defined). Each face is specified by the X & Y coordinates of the top left corner and the width & height of the face. The coordinates for each face are returned as an array (using the SDKs) or a comma-separated list (for REST API calls), and individual faces are separated with a pipe (`❘`). For example: `10,20,150,130❘213,345,82,61`. Default: `false`. Relevant for images only.
quality_analysis	Boolean	Whether to return a quality analysis value for the image between 0 and 1, where 0 means the image is blurry and out of focus and 1 means the image is sharp and in focus. Default: `false`. Relevant for images only. Paid customers can request to take part in the extended quality analysis Beta trial. When activated, this parameter returns quality scores for various other factors in addition to `focus`, such as `jpeg_quality`, `noise`, `exposure`, `lighting` and `resolution`, together with an overall weighted `quality_score`. The `quality_score`, `quality_analysis.color_score` and `quality_analysis.pixel_score` fields can be used in the Search API.
accessibility_analysis	Boolean	Currently available only to paid customers requesting to take part in the accessibility analysis Beta trial. Set to `true` to return accessibility analysis values for the image and to enable the `accessibility_analysis.colorblind_accessibility_score` field to be used in the Search API. Default: `false`. Relevant for images only.
cinemagraph_analysis	Boolean	Whether to return a cinemagraph analysis value for the media asset between 0 and 1, where 0 means the asset is not a cinemagraph and 1 means the asset is a cinemagraph. Default: `false`. Relevant for animated images and video only. A static image will return 0.
image_metadata	Boolean	Whether to return IPTC, XMP, and detailed Exif metadata of the uploaded asset in the response. Default: `false`. Supported for images, video, and audio. Returned metadata for images includes: `PixelsPerUnitX`, `PixelsPerUnitY`, `PixelUnits`, `Colorspace`, and `DPI`. Returned metadata for audio and video includes: `audio_codec`, `audio_bit_rate`, `audio_frequency`, `channels`, `channel_layout`. Additional metadata for video includes: `pix_format`, `codec`, `level`, `profile`, `video_bit_rate`, `dar`. (In .NET SDK, parameter name is `Metadata`.)
phash	Boolean	Whether to return the perceptual hash (pHash) on the uploaded image. The pHash acts as a fingerprint that allows checking image similarity. Default: `false`. Relevant for images only.
responsive_breakpoints	[JSON]	Requests that Cloudinary automatically find the best breakpoints. The parameter value is an array of breakpoint request settings, where each request setting can include the following parameters: `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`. 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.
auto_tagging	Decimal	Automatically assigns tags to an asset according to detected objects or categories with a confidence score higher than the specified value. Use together with the `detection` parameter for: Cloudinary AI Content Analysis Amazon Rekognition Celebrity Detection Use together with the `categorization` parameter for: Google Automatic Video Tagging Google Auto Tagging Imagga Auto Tagging Amazon Rekognition Auto Tagging Range: 0.0 to 1.0
categorization	String	A comma-separated list of the categorization add-ons to run on the asset. Set to `google_tagging`, `google_video_tagging`, `imagga_tagging` and/or `aws_rek_tagging` to automatically classify the scenes of the uploaded asset. Can be used together with the `auto_tagging` parameter to apply tags automatically. See the Google Automatic Video Tagging, Google Auto Tagging, Imagga Auto Tagging and Amazon Rekognition Auto Tagging add-ons for more details.
detection	String	Invokes the relevant add-on to return a list of detected content. Set to: <content-aware model>_[<version>] (e.g. `coco_v1`) to return a list of detected content using the Cloudinary AI Content Analysis add-on. Can be used together with the `auto_tagging` parameter to apply tags automatically. `adv_face` to return a list of facial attributes using the Advanced Facial Attribute Detection add-on. `aws_rek_face` to return a list of detected celebrities and facial attributes using the Amazon Rekognition Celebrity Detection add-on. Can be used together with the `auto_tagging` parameter to apply tags automatically. Relevant for images only.
ocr	String	Set to `adv_ocr` to extract all text elements in an image as well as the bounding box coordinates of each detected element using the OCR text detection and extraction add-on. Relevant for images only.
exif	Boolean	Whether to retrieve the Exif metadata of the uploaded photo. Default: false. Deprecated - use image_metadata instead
`Manipulations:`
eager	String	A list of transformations to create for the uploaded asset, instead of lazily creating them when first accessed by your site's visitors (see the Transformation URL API Reference for more details on possible values). This option accepts either a single transformation or a pipe-separated list of transformations to create for the uploaded asset. SDKs: Supports arrays. (In .NET SDK, parameter name is `EagerTransforms`.)
eager_async	Boolean	Whether to generate the eager transformations asynchronously in the background after the upload request is completed rather than online as part of the upload call. Default: `false`.
eager_notification_url	String	An HTTP or HTTPS URL to send a notification to (a webhook) when the generation of eager transformations is completed.
transformation	String	An incoming transformation to run on the uploaded asset before saving it in the cloud. This parameter is given as a string of comma-separated single characters (separated with a slash for chained transformations). SDKs: Supports a hash of transformation parameters (or an array of hashes for chained transformations). Note: When using the SDK for a dynamically-typed language such as Ruby, the transformation parameters can be specified directly without using this `transformation` parameter.
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 a comma-separated list. For example: `85,120,220,310`. Relevant for images only. SDKs: Supports arrays. For example: `[85, 120, 220, 310]`
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 a comma-separated list, with individual faces separated with a pipe (`❘`). For example: `10,20,150,130❘213,345,82,61`. Relevant for images only. SDKs: Supports arrays. For example: `[[10, 20, 150, 130],[213, 345, 82, 61]]`
background_removal	String	Automatically remove the background of an image using an add-on. Set to `cloudinary_ai` to use the deep-learning based Cloudinary AI Background Removal add-on. Set to `pixelz` to use the human-powered Pizelz Remove-The-Background Editing add-on service. Relevant for images only.
raw_convert	String	Asynchronously generates a related file based on the uploaded file. Set to `aspose` to automatically create a PDF or other image format from a `raw` Office document using the Aspose Document Conversion add-on. Set to `google_speech` to instruct the Google AI Video Transcription add-on to generate an automatic transcript `raw` file from an uploaded video. Set to `extract_text` to extract all the text from a PDF file and store it in a `raw` file. The public ID of the generated raw file will be in the format: [pdf_public_id].extract_text.json. See also: Converting raw files.
`Additional options:`
allowed_formats	String	A comma-separated list of file formats that are allowed for uploading. Files of other types will be rejected. The formats can be any combination of image types, video formats or raw file extensions. For example: `mp4,ogv,jpg,png,pdf`. Default: any supported format for images and videos, and any kind of raw file (i.e. no restrictions by default). SDKs: Supports arrays. For example: `[mp4, ogv, jpg, png, pdf]`
async	Boolean	Tells Cloudinary whether to perform the upload request in the background (asynchronously). Default: `false`.
backup	Boolean	Tell Cloudinary whether to back up the uploaded asset. Overrides the default backup settings of your account.
callback	String	A URL to redirect to after the upload is completed instead of returning the upload response. Signed upload result parameters are added to the callback URL. This parameter is ignored for XHR (Ajax XMLHttpRequest) upload requests. Note: This parameter is relevant for direct uploads from a form in the browser. It is automatically set if you perform direct upload from the browser using Cloudinary's SDKs and the jQuery plugin.
eval	String	Allows you to modify upload parameters by specifying custom logic with JavaScript. This can be useful for conditionally adding tags, contextual metadata, structured metadata or eager transformations depending on specific criteria of the uploaded file. For more details see Evaluating and modifying upload parameters.
headers	String	An HTTP header or a list of headers lines for adding as response HTTP headers when delivering the asset to your users. Supported headers: `Link`, `Authorization`, `X-Robots-Tag`. For example: `X-Robots-Tag: noindex`.
invalidate	Boolean	Whether to invalidate CDN cached copies of a previously uploaded asset (and all transformed versions that share the same Public ID). Default: `false`. It usually takes between a few seconds and a few minutes for the invalidation to fully propagate through the CDN. There are also a number of other important considerations when using the invalidate functionality.
moderation	String	For all asset types: Set to `manual` to add the uploaded asset to a queue of pending assets that can be moderated using the Admin API or the Cloudinary Management Console, or set to `metascan` to automatically moderate the uploaded asset using the MetaDefender Anti-Malware Protection add-on. For images only: Set to `webpurify` or `aws_rek` to automatically moderate the uploaded image using the WebPurify Image Moderation add-on or the Amazon Rekognition AI Moderation add-on respectively.
notification_url	String	An HTTP or HTTPS URL to receive the upload response (a webhook) when the upload or any requested asynchronous action is completed. If not specified, the response is sent to the global Notification URL (if defined) in the Upload settings of your account console.
proxy	String	Tells Cloudinary to upload assets from remote URLs through the given proxy. Format: `https://hostname:port`.
return_delete_token	Boolean	Whether to return a deletion token in the upload response. The token can be used to delete the uploaded asset within 10 minutes using an unauthenticated API request. Default: `false`.

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.

Examples

To upload an image by specifying the local path /home/sample.jpg:

Ruby PHP v1 PHP v2 Python Node.js Java .NET Android iOS CLI All

Ruby:

Cloudinary::Uploader.upload("/home/sample.jpg")

PHP v1:

\Cloudinary\Uploader::upload("/home/sample.jpg");

PHP v2:

$cloudinary->uploadApi()->upload("/home/sample.jpg");

Python:

cloudinary.uploader.upload("/home/sample.jpg")

Node.js:

cloudinary.v2.uploader.upload("/home/sample.jpg", 
  function(error, result) {console.log(result, error); });

Java:

cloudinary.uploader().upload("/home/sample.jpg", 
  ObjectUtils.emptyMap());

.NET:

var uploadParams = new ImageUploadParams(){
  File = new FileDescription(@"/home/sample.jpg")};
var uploadResult = cloudinary.Upload(uploadParams);

Android:

MediaManager.get().upload("/home/sample.jpg").dispatch();

iOS:

let params = CLDUploadRequestParams()
var mySig = MyFunction(params)  // your own function that returns a signature generated on your backend
params.setSignature(CLDSignature(signature: mySig.signature, timestamp: mySig.timestamp))
let request = cloudinary.createUploader().signedUpload(
  url: "/home/sample.jpg", params: params)

CLI:

cli uploader upload "/home/sample.jpg"

To upload an image from a remote url: https://www.example.com/sample.jpg and request Cloudinary to find the best breakpoints based on the following guidelines: a minimum width of 200 pixels, a maximum width of 1000 pixels, at least 20000 bytes file size difference between the breakpoints, while keeping the generated derived images:

Ruby PHP v1 PHP v2 Python Node.js Java .NET Android iOS cURL CLI All

Ruby:

Cloudinary::Uploader.upload("https://www.example.com/sample.jpg", 
  responsive_breakpoints: { 
    create_derived: true, 
    bytes_step: 20000, 
    min_width: 200, 
    max_width: 1000})

PHP v1:

\Cloudinary\Uploader::upload("https://www.example.com/sample.jpg", 
  array(
    "responsive_breakpoints" => 
      array( 
        "create_derived" => true, 
        "bytes_step" => 20000, 
        "min_width" => 200, 
        "max_width" => 1000 )));

PHP v2:

$cloudinary->uploadApi()->upload("https://www.example.com/sample.jpg", 
  array(
    "responsive_breakpoints" => 
      array( 
        "create_derived" => true, 
        "bytes_step" => 20000, 
        "min_width" => 200, 
        "max_width" => 1000 )));

Python:

cloudinary.uploader.upload("https://www.example.com/sample.jpg", 
  responsive_breakpoints = { 
    "create_derived": true, 
    "bytes_step": 20000, 
    "min_width": 200, 
    "max_width": 1000 })

Node.js:

cloudinary.v2.uploader.upload("https://www.example.com/sample.jpg",
  { responsive_breakpoints: 
    { create_derived: true, 
      bytes_step: 20000, 
      min_width: 200, 
      max_width: 1000 }}, 
  function(error, result) {console.log(result, error); });

Java:

cloudinary.uploader().upload("https://www.example.com/sample.jpg", 
  ObjectUtils.asMap(
    "responsive_breakpoints", 
      new ResponsiveBreakpoint()
       .createDerived("true")
       .bytesStep(20000)
       .minWidth(200)
       .maxWidth(1000)));

.NET:

var uploadParams = new ImageUploadParams(){
  File = new FileDescription(@"https://www.example.com/sample.jpg"),
  ResponsiveBreakpoints = new List<ResponsiveBreakpoint> { 
    new ResponsiveBreakpoint()
      .CreateDerived(true)
      .BytesStep(20000)
      .MinWidth(200)
      .MaxWidth(1000)}};
var uploadResult = cloudinary.Upload(uploadParams);

Android:

MediaManager.get().upload("/home/sample.jpg")
  .option("responsive_breakpoints", new ResponsiveBreakpoint()
       .createDerived("true")
       .bytesStep(20000)
       .minWidth(200)
       .maxWidth(1000)).dispatch();

iOS:

let responsive = CLDResponsiveBreakpoints(createDerived: true, bytesStep: 2000, minWidth: 200, maxWidth: 1000)
let params = CLDUploadRequestParams().setResponsiveBreakpoints(responsive)
var mySig = MyFunction(params)  // your own function that returns a signature generated on your backend
params.setSignature(CLDSignature(signature: mySig.signature, timestamp: mySig.timestamp))
let request = cloudinary.createUploader().signedUpload(
  url: "https://www.example.com/sample.jpg", params: params)

cURL:

curl https://api.cloudinary.com/v1_1/demo/image/upload -X POST --data 'file=https://www.example.com/sample.jpg&responsive_breakpoint=[{"create_derived":true,"bytes_step":20000,"min_width":200,"max_width":1000}]&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'

CLI:

cld uploader upload "https://www.example.com/sample.jpg" responsive_breakpoints='{"create_derived": true, "bytes_step": 20000, "min_width": 200, "max_width": 1000}'

To upload an image from a remote FTP private server ftp://ftp.example.com/sample.jpg with a username of user1 and a password of mypass. Two transformed images are also eagerly generated as follows:

Pad to a width of 400 pixels and height of 300 pixels.
Crop to a width of 260 pixels and a height of 200 pixels with north gravity.

Ruby PHP v1 PHP v2 Python Node.js Java .NET Android iOS cURL CLI All

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

\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"))));

PHP v2:

$cloudinary->uploadApi()->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, error); });

Java:

cloudinary.uploader().upload("ftp://user1:mypass@ftp.example.com/sample.jpg", 
  ObjectUtils.asMap(
    "eager", Arrays.asList(
      new EagerTransformation().width(400).height(300).crop("pad"),
      new EagerTransformation().width(260).height(200).crop("crop").gravity("north"))));

.NET:

var uploadParams = new ImageUploadParams(){
  File = new FileDescription(@"ftp://user1:mypass@ftp.example.com/sample.jpg"),
  EagerTransforms = new List<Transformation>(){
   new EagerTransformation().Width(400).Height(300).Crop("pad"),
   new EagerTransformation().Width(260).Height(200).Crop("crop").Gravity("north")}};
var uploadResult = cloudinary.Upload(uploadParams);

Android:

MediaManager.get().upload("/home/sample.jpg")
  .option("eager", Arrays.asList(
      new EagerTransformation().width(400).height(300).crop("pad"),
      new EagerTransformation().width(260).height(200).crop("crop").gravity("north"))).dispatch();

iOS:

let eager1 = CLDEagerTransformation()
  .setWidth(400).setHeight(300).setCrop("pad")
let eager2 = CLDEagerTransformation()
  .setWidth(260).setHeight(200).setCrop("crop").setGravity("north")
let params = CLDUploadRequestParams().setEager([eager1, eager2])
var mySig = MyFunction(params)  // your own function that returns a signature generated on your backend
params.setSignature(CLDSignature(signature: mySig.signature, timestamp: mySig.timestamp))
let request = cloudinary.createUploader().signedUpload(url: "ftp://user1:mypass@ftp.example.com/sample.jpg", params: params)

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'

CLI:

cld 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"}]'

Sample response

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

{
  "asset_id": "b5e6d2b39ba3e0869d67141ba7dba6cf",
  "public_id": "eneivicys42bq5f2jpn2",
  "version": 1570979139,
  "version_id": "98f52566f43d8e516a486958a45c1eb9",
  "signature": "abcdefghijklmnopqrstuvwxyz12345",
  "width": 1000,
  "height": 672,
  "format": "jpg",
  "resource_type": "image",
  "created_at": "2017-08-11T12:24:32Z",
  "tags": [],
  "pages": 1,
  "bytes": 350749,
  "type": "upload",
  "etag": "5297bd123ad4ddad723483c176e35f6e",
  "placeholder": false,
  "url": "http://res.cloudinary.com/demo/image/upload/v1570979139/eneivicys42bq5f2jpn2.jpg",
  "secure_url": "https://res.cloudinary.com/demo/image/upload/v1570979139/eneivicys42bq5f2jpn2.jpg",
  "access_mode": "public",
  "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/v1570979139/eneivicys42bq5f2jpn2.jpg",
      "secure_url": "https://res.cloudinary.com/demo/image/upload/c_pad,h_300,w_400/v1570979139/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/v1570979139/eneivicys42bq5f2jpn2.jpg",
      "secure_url": "https://res.cloudinary.com/demo/image/upload/c_crop,g_north,h_200,w_260/v1570979139/eneivicys42bq5f2jpn2.jpg" }]
}

Rename method

Renamed assets are immediately and permanently updated in your cloud storage with the rename method.

Caution

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. It usually takes between a few seconds and a few minutes for the invalidation to fully propagate through the CDN. For details on invalidating assets, see Invalidating cached media assets on the CDN.

Syntax

POST /:resource_type/rename

Ruby PHP v1 PHP v2 Python Node.js Java .NET Android iOS CLI All

Ruby:

result = Cloudinary::Uploader.rename(from_public_id, to_public_id, options = {})

PHP v1:

$result = \Cloudinary\Uploader::rename($from_public_id, $to_public_id, $options = array());

PHP v2:

$result = $cloudinary->uploadApi()->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);

.NET:

var renameParams = new RenameParams() 
{ string FromPublicId, string ToPublicId };
var renameResult = cloudinary.Rename(renameParams);

Android:

MediaManager.get().upload("/home/sample.jpg")
  .option("eager", Arrays.asList(
      new Transformation().width(400).height(300).crop("pad"),
      new Transformation().width(260).height(200).crop("crop").gravity("north"))).dispatch();

iOS:

let result = cloudinary.createManagementApi().rename(from_public_id, to: to_public_id, params: params)

CLI:

cld uploader rename $from_public_id $to_public_id $options

Required parameters

Parameter	Type	Description
from_public_id	String	The current identifier of the uploaded asset.
to_public_id	String	The new identifier to assign to the uploaded asset.
signature	String	(Required for REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs, the signature is automatically generated and added to the request. If you manually generate your own POST request, you also need to manually generate this signature and add it to the request.

Optional parameters

Parameter	Type	Description
resource_type	String	The type of asset to rename. Only relevant as a parameter when using the SDKs (the `resource_type` is included in the endpoint URL when using the REST API). Valid values: `image`, `raw`, and `video`. Default: `image`. Note: Use the `video` resource type for all video assets as well as for audio files, such as `.mp3`.
type	String	The delivery type of the asset. Only relevant as a parameter when using the SDKs (the delivery `type` is included in the endpoint URL when using the REST API). 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 asset's current type is unchanged.
overwrite	Boolean	Whether to overwrite an existing asset with the target public ID. Default: `false`. Important: Depending on the settings for your account, overwriting an asset may clear the tags, contextual, and structured metadata values for that asset. If you have a master admin role, you can change this behavior for your account in the Media Library Preferences pane, so that these field values are retained when new version assets overwrite older ones (unless you specify different values for the `tags`, `context`, or `metadata` parameters as part of your upload).
invalidate	Boolean	Whether to invalidate CDN cached copies of the asset (and all its transformed versions). Default: `false`. It usually takes between a few seconds and a few minutes for the invalidation to fully propagate through the CDN. There are also a number of other important considerations when using the invalidate functionality

Example

To rename an image from canyon to grand_canyon:

Ruby PHP v1 PHP v2 Python Node.js Java .NET Android iOS cURL CLI All

Ruby:

Cloudinary::Uploader.rename('canyon', 'grand_canyon')

PHP v1:

\Cloudinary\Uploader::rename('canyon', 'grand_canyon');

PHP v2:

$cloudinary->uploadApi()->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, error) });

Java:

cloudinary.uploader().rename("canyon", "grand_canyon", 
  ObjectUtils.emptyMap());

.NET:

var renameParams = new RenameParams(){
  FromPublicId = "canyon",
  ToPublicId = "grand_canyon"};
var renameResult = cloudinary.Rename(renameParams);

Android:

MediaManager.get().uploader().rename("canyon", "grand_canyon", 
  ObjectUtils.emptyMap());

iOS:

let result = cloudinary.createManagementApi().rename("canyon", to: "grand_canyon")

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'

CLI:

cld uploader rename "canyon" "grand_canyon"

Sample response

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

{
  "asset_id": "b5e6d2b39ba3e0869d67141ba7dba6ce",
  "public_id": "grand_canyon",
  "version": 1570979583,
  "version_id": "98f52566f43d8e516a486958a45c1eb0",
  "signature": "abcdefghijklmnopqrstuvwxyz12345",
  "width": 2896,
  "height": 1944,
  "format": "jpg",
  "resource_type": "image",
  "created_at": "2017-08-11T12:31:13Z",
  "tags": [],
  "bytes": 1414789,
  "type": "upload",
  "placeholder": false,
  "url": "http://res.cloudinary.com/demo/image/upload/v1570979583/grand_canyon.jpg",
  "secure_url": "https://res.cloudinary.com/demo/image/upload/v1570979583/grand_canyon.jpg",
  "access_mode": "public"
}

Destroy method

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. It usually takes between a few seconds and a few minutes for the invalidation to fully propagate through the CDN. For details on invalidating media assets, see Invalidating cached media assets on the CDN.

Syntax

POST /:resource_type/destroy

Ruby PHP v1 PHP v2 Python Node.js Java .NET iOS CLI All

Ruby:

result = Cloudinary::Uploader.destroy(public_id, options = {})

PHP v1:

$result = \Cloudinary\Uploader::destroy($public_id, $options = array());

PHP v2:

$result = $cloudinary->uploadApi()->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);

.NET:

var deletionParams = new DeletionParams() 
{ string PublicId };
var deletionResult = cloudinary.Destroy(deletionParams);

iOS:

let result = cloudinary.createManagementApi().destroy(public_id, params: params)

CLI:

cld uploader destroy $public_id $options

Required parameters

Parameter	Type	Description
public_id	String	The identifier of the uploaded asset. Note: The public ID value for images and videos should not include a file extension. Include the file extension for `raw` files only.
signature	String	(Required for REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs, the signature is automatically generated and added to the request. If you manually generate your own POST request, you also need to manually generate this signature and add it to the request.

Optional parameters

Parameter	Type	Description
resource_type	String	The type of asset to destroy. Only relevant as a parameter when using the SDKs (the `resource_type` is included in the endpoint URL when using the REST API). Valid values: `image`, `raw`, and `video`. Default: `image`. Note: Use the `video` resource type for all video assets as well as for audio files, such as `.mp3`.
type	String	The delivery type of the asset. Only relevant as a parameter when using the SDKs (the type is included in the endpoint URL when using the REST API). Default: `upload`. For a list of all possible delivery types, see Delivery types.
invalidate	Boolean	If true, invalidates CDN cached copies of the asset (and all its transformed versions). Default: `false`. It usually takes between a few seconds and a few minutes for the invalidation to fully propagate through the CDN. There are also a number of other important considerations when using the invalidate functionality.

Examples

Deleting an image with the Public ID of sample:

Ruby PHP v1 PHP v2 Python Node.js Java .NET iOS cURL CLI All

Ruby:

Cloudinary::Uploader.destroy('sample')

PHP v1:

\Cloudinary\Uploader::destroy('sample');

PHP v2:

$cloudinary->uploadApi()->destroy('sample');

Python:

cloudinary.uploader.destroy('sample')

Node.js:

cloudinary.v2.uploader.destroy('sample', function(error,result) {
  console.log(result, error) });

Java:

cloudinary.uploader().destroy("sample",
  ObjectUtils.emptyMap());

.NET:

var deletionParams = new DeletionParams(){
  PublicId = "sample"};
var deletionResult = cloudinary.Destroy(deletionParams);

iOS:

let result = cloudinary.createManagementApi().destroy("sample")

cURL:

curl https://api.cloudinary.com/v1_1/demo/image/destroy -X POST --data 'public_id=sample&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'

CLI:

cld uploader destroy "sample"

Deleting a video with the Public ID of sample:

Ruby PHP v1 PHP v2 Python Node.js Java .NET iOS cURL CLI All

Ruby:

Cloudinary::Uploader.destroy('sample', :resource_type => 'video')

PHP v1:

\Cloudinary\Uploader::destroy('sample', 'resource_type' => 'video');

PHP v2:

$cloudinary->uploadApi()->destroy('sample', 'resource_type' => 'video');

Python:

cloudinary.uploader.destroy('sample', resource_type = 'video')

Node.js:

cloudinary.v2.uploader.destroy('sample', resource_type: 'video', function(error,result) {
  console.log(result, error) });

Java:

cloudinary.uploader().destroy("sample",
  ObjectUtils.asMap("resourceType","video"));

.NET:

var deletionParams = new DeletionParams("sample"){
  ResourceType = "video"};
var deletionResult = cloudinary.Destroy(deletionParams);

iOS:

let params = CLDDestroyRequestParams()
  .setResourceType("video")
let result = cloudinary.createManagementApi().destroy("sample", params: params)

cURL:

curl https://api.cloudinary.com/v1_1/demo/image/destroy -X POST --data 'public_id=sample&resource_type=video&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'

CLI:

cld uploader destroy "sample" resource_type=video

Sample response

A successful destroy operation returns the following:

{
  "result": "ok"
}

Download_backup method

The download_backup method returns a specific version of a backed up asset without restoring it in your Media Library.

The endpoint returns the specified version of the asset in bytes.
The SDKs return a URL of the asset that can be used to download that version of the asset (within an hour of the request).

Syntax

GET /download_backup

Ruby PHP v1 PHP v2 Python Node.js Java .NET CLI All

Ruby:

url = Cloudinary::Utils.download_backedup_asset(asset_id, version_id)

PHP v1:

$url = \Cloudinary::download_backedup_asset($asset_id, $version_id);

PHP v2:

$url = $cloudinary->uploadApi()->downloadBackedupAsset($assetId, $versionId);

Python:

url = cloudinary.utils.download_backedup_asset(asset_id, version_id)

Node.js:

string url = cloudinary.v2.utils.download_backedup_asset(asset_id, version_id);

Java:

String url = cloudinary.downloadBackedupAsset(String asset_id, String version_id);

.NET:

var backupParams = new BackupParams() 
{ string AssetId, string VersionId };
var url = cloudinary.DownloadBackedupAsset(backupParams);

CLI:

cld utils download_backedup_asset $asset_id $version_id

Required parameters

Parameter	Type	Description
asset_id	String	The identifier of the uploaded asset. Note: This is returned in the response to various admin API methods.
version_id	String	The identifier of a backed up version of the asset. Note: To see details of backed up versions, including `version_id`, for a specific asset, use the resource method of the admin API, setting the `versions` parameter to true.

Example

To return the URL of a backed up version of an asset with asset_id of 62c2a18d622be7e190d21df8e05b1416 and version_id of 26fe6d95df856f6ae12f5678be94516a (the cURL example returns the asset in bytes):

Ruby PHP v1 PHP v2 Python Node.js Java .NET cURL CLI All

Ruby:

Cloudinary::Utils.download_backedup_asset('62c2a18d622be7e190d21df8e05b1416', '26fe6d95df856f6ae12f5678be94516a')

PHP v1:

\Cloudinary::download_backedup_asset('62c2a18d622be7e190d21df8e05b1416', '26fe6d95df856f6ae12f5678be94516a');

PHP v2:

$cloudinary->uploadApi()->downloadBackedupAsset('62c2a18d622be7e190d21df8e05b1416', '26fe6d95df856f6ae12f5678be94516a');

Python:

cloudinary.utils.download_backedup_asset('62c2a18d622be7e190d21df8e05b1416', '26fe6d95df856f6ae12f5678be94516a')

Node.js:

cloudinary.v2.utils.download_backedup_asset('62c2a18d622be7e190d21df8e05b1416', '26fe6d95df856f6ae12f5678be94516a');

Java:

cloudinary.downloadBackedupAsset("62c2a18d622be7e190d21df8e05b1416", "26fe6d95df856f6ae12f5678be94516a",
  ObjectUtils.emptyMap());

.NET:

var backupParams = new BackupParams() 
{AssetId = "62c2a18d622be7e190d21df8e05b1416", VersionId = "26fe6d95df856f6ae12f5678be94516a"};
var url = cloudinary.DownloadBackedupAsset(backupParams);

cURL:

curl https://api.cloudinary.com/v1_1/demo/download_backup?timestamp=173719931&asset_id=62c2a18d622be7e190d21df8e05b1416&version_id=26fe6d95df856f6ae12f5678be94516a&signature=c9937fe93eb655ce04633034f921b83969eff9aa&api_key=323127161127519

CLI:

cld utils download_backedup_asset "62c2a18d622be7e190d21df8e05b1416" "26fe6d95df856f6ae12f5678be94516a"

Sample response

The following is a sample SDK response based on the example above. The URL to download the requested backed up version of the asset is returned.

https://api.cloudinary.com/v1_1/demo/download_backup?timestamp=173719931&asset_id=62c2a18d622be7e190d21df8e05b1416&version_id=26fe6d95df856f6ae12f5678be94516a&signature=c9937fe93eb655ce04633034f921b83969eff9aa&api_key=323127161127519

Tags method

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 setting the value of the command parameter to either add, remove, remove_all, or replace tags.

SDKs: The Cloudinary SDKs wrap the tags method and offer 4 separate methods: one for adding tags, one for removing specific tags, one for removing all tags, and one for replacing tags.

Adding tags syntax

POST /:resource_type/tags

Ruby PHP v1 PHP v2 Python Node.js Java .NET iOS CLI All

Ruby:

result = Cloudinary::Uploader.add_tag(tag, public_ids, options = {})

PHP v1:

$result = \Cloudinary\Uploader::add_tag($tag, $public_ids, $options = array());

PHP v2:

$result = $cloudinary->uploadApi()->addTag($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);

.NET:

var tagParams = new TagParams() 
{ string Tag, List<string> PublicIds, TagCommand.Add };
var tagResult = cloudinary.Tag(tagParams);

iOS:

let result = cloudinary.createManagementApi().addTag(tag, publicIds: publicIds, params: params)

CLI:

cld uploader add_tag $tag $public_ids $options

Removing tags syntax

POST /:resource_type/tags

Ruby PHP v1 PHP v2 Python Node.js Java .NET iOS CLI All

Ruby:

result = Cloudinary::Uploader.remove_tag(tag, public_ids, options = {})

PHP v1:

$result = \Cloudinary\Uploader::remove_tag($tag, $public_ids, $options = array());

PHP v2:

$result = $cloudinary->uploadApi()->removeTag($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);

.NET:

var tagParams = new TagParams() 
{ string Tag, List<string> PublicIds, TagCommand.Remove };
var tagResult = cloudinary.Tag(tagParams);

iOS:

let result = cloudinary.createManagementApi().removeTag(tag, publicIds: publicIds, params: params)

CLI:

cld uploader remove_tag $tag $public_ids $options

Removing all tags syntax

POST /:resource_type/tags

Ruby PHP v1 PHP v2 Python Node.js Java .NET CLI All

Ruby:

result = Cloudinary::Uploader.remove_all_tags(public_ids, options = {})

PHP v1:

$result = \Cloudinary\Uploader::remove_all_tags($public_ids, $options = array());

PHP v2:

$result = $cloudinary->uploadApi()->removeAllTags($public_ids, $options = array());

Python:

result = cloudinary.uploader.remove_all_tags(public_ids, **options)

Node.js:

cloudinary.v2.uploader.remove_all_tags(public_ids, options, callback);

Java:

Map result = cloudinary.uploader().removeAllTags(String public_ids, Map options);

.NET:

var tagParams = new TagParams() 
{ List<string> PublicIds, TagCommand.RemoveAll };
var tagResult = cloudinary.Tag(tagParams);

CLI:

cld uploader remove_all_tags $public_ids $options

Replacing tags syntax

POST /:resource_type/tags

Ruby PHP v1 PHP v2 Python Node.js Java .NET iOS CLI All

Ruby:

result = Cloudinary::Uploader.replace_tag(tag, public_ids, options = {})

PHP v1:

$result = \Cloudinary\Uploader::replace_tag($tag, $public_ids, $options = array());

PHP v2:

$result = $cloudinary->uploadApi()->replaceTag($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);

.NET:

var tagParams = new TagParams() 
{ string Tag, List<string> PublicIds, TagCommand.Replace };
var tagResult = cloudinary.Tag(tagParams);

iOS:

let result = cloudinary.createManagementApi().replaceTag(tag, publicIds: publicIds, params: params)

CLI:

cld uploader replace_tag $tag $public_ids $options

Required parameters

Parameter	Type	Description
tag	String	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 REST API or the .NET SDK - not for use with other SDKs) The action to perform on the assets: either `add` the given tag, `remove` the given tag, `remove_all` the tags assigned, or `replace` the given tag, which adds the given tag while removing all other tags assigned.
signature	String	(Required for REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs, the signature is automatically generated and added to the request. If you manually generate your own POST request, you also need to manually generate this signature and add it to the request.

Optional parameters

Parameter	Type	Description
resource_type	String	The type of asset. Only relevant as a parameter when using the SDKs (the `resource_type` is included in the endpoint URL when using the REST API). Valid values: `image`, `raw`, and `video`. Default: `image`. Note: Use the `video` resource type for all video assets as well as for audio files, such as `.mp3`.
type	String	The delivery type of the asset. Only relevant as a parameter when using the SDKs (the delivery `type` is included in the endpoint URL when using the REST API). Default: `upload`. For a list of possible delivery types, see Delivery types.

Examples

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

Ruby PHP v1 PHP v2 Python Node.js Java .NET iOS cURL CLI All

Ruby:

Cloudinary::Uploader.add_tag('animal', ['dog', 'lion'])

PHP v1:

\Cloudinary\Uploader::add_tag('animal', array('dog', 'lion'));

PHP v2:

$cloudinary->uploadApi()->addTag('animal', array('dog', 'lion'));

Python:

cloudinary.uploader.add_tag('animal', ['dog', 'lion'])

Node.js:

cloudinary.v2.uploader.add_tag('animal', [ 'dog', 'lion' ],
  function(error, result) { console.log(result, error) });

Java:

cloudinary.uploader().addTag("animal",
  ["dog", "lion"], ObjectUtils.emptyMap());

.NET:

var tagParams = new TagParams(){
  PublicIds = new List<string>(){"dog","lion"},
  Tag = "animal",
  Command = TagCommand.Add};
var tagResult = cloudinary.Tag(tagParams);

iOS:

let result = cloudinary.createManagementApi().addTag("animal", publicIds: ["dog", "lion"])

cURL:

curl https://api.cloudinary.com/v1_1/demo/image/tags -X POST --data 'tag=animal&public_ids[]=dog&public_ids[]=lion&command=add&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'

CLI:

cld uploader add_tag "animal" '["dog", "lion"]'

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

Ruby PHP v1 PHP v2 Python Node.js Java .NET iOS cURL CLI All

Ruby:

Cloudinary::Uploader.remove_tag('animal', ['dog', 'lion'])

PHP v1:

\Cloudinary\Uploader::remove_tag('animal', array('dog', 'lion'));

PHP v2:

$cloudinary->uploadApi()->removeTag('animal', array('dog', 'lion'));

Python:

cloudinary.uploader.remove_tag('animal', ['dog', 'lion'])

Node.js:

cloudinary.v2.uploader.remove_tag('animal', [ 'dog', 'lion' ],
  function(error, result) { console.log(result, error) });

Java:

cloudinary.uploader().removeTag("animal",
  ["dog", "lion"], ObjectUtils.emptyMap());

.NET:

var tagParams = new TagParams(){
  PublicIds = new List<string>(){"dog","lion"},
  Tag = "animal",
  Command = TagCommand.Remove};
var tagResult = cloudinary.Tag(tagParams);

iOS:

let result = cloudinary.createManagementApi().removeTag("animal", publicIds: ["dog", "lion"])

cURL:

curl https://api.cloudinary.com/v1_1/demo/image/tags -X POST --data 'tag=animal&public_ids[]=dog&public_ids[]=lion&command=remove&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'

CLI:

cld uploader remove_tag "animal" '["dog", "lion"]'

To remove all existing tags for the images with the Public IDs of dog and lion

Ruby PHP v1 PHP v2 Python Node.js Java .NET cURL CLI All

Ruby:

Cloudinary::Uploader.remove_all_tags(['dog', 'lion'])

PHP v1:

\Cloudinary\Uploader::remove_all_tags(array('dog', 'lion'));

PHP v2:

$cloudinary->uploadApi()->removeAllTags(array('dog', 'lion'));

Python:

cloudinary.uploader.remove_all_tags(['dog', 'lion'])

Node.js:

cloudinary.v2.uploader.remove_all_tags([ 'dog', 'lion' ],
  function(error, result) { console.log(result, error) });

Java:

cloudinary.uploader().removeAllTags(["dog", "lion"], 
  ObjectUtils.emptyMap());

.NET:

var tagParams = new TagParams(){
  PublicIds = new List<string>(){"dog","lion"},
  Command = TagCommand.RemoveAll};
var tagResult = cloudinary.Tag(tagParams);

cURL:

curl https://api.cloudinary.com/v1_1/demo/image/tags -X POST --data 'public_ids[]=dog&public_ids[]=lion&command=replace_all&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'

CLI:

cld uploader remove_all_tags '["dog", "lion"]'

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

Ruby PHP v1 PHP v2 Python Node.js Java .NET iOS cURL CLI All

Ruby:

Cloudinary::Uploader.replace_tag('animal', ['dog', 'lion'])

PHP v1:

\Cloudinary\Uploader::replace_tag('animal', array('dog', 'lion'));

PHP v2:

$cloudinary->uploadApi()->replaceTag('animal', array('dog', 'lion'));

Python:

cloudinary.uploader.replace_tag('animal', ['dog', 'lion'])

Node.js:

cloudinary.v2.uploader.replace_tag('animal', [ 'dog', 'lion' ],
  function(error, result) { console.log(result, error) });

Java:

cloudinary.uploader().replaceTag("animal",
  ["dog", "lion"], ObjectUtils.emptyMap());

.NET:

var tagParams = new TagParams(){
  PublicIds = new List<string>(){"dog","lion"},
  Tag = "animal",
  Command = TagCommand.ReplaceAll};
var tagResult = cloudinary.Tag(tagParams);

iOS:

let result = cloudinary.createManagementApi().replaceTag("animal", publicIds: ["dog", "lion"])

cURL:

curl https://api.cloudinary.com/v1_1/demo/image/tags -X POST --data 'tag=animal&public_ids[]=dog&public_ids[]=lion&command=replace&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'

CLI:

cld uploader replace_tag "animal" '["dog", "lion"]'

Sample response

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

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

Context method

The context parameter of an uploaded asset contains a pipe-separated list of key-value pairs of contextual metadata (up to 255 characters). The context method can be used to manage the contextual metadata of an uploaded asset by setting the value of the command parameter to either add a new key-value pair, or remove_all contextual metadata from the asset.

SDKs: The Cloudinary SDKs wrap the REST API context method and offer 2 separate methods: one for adding contextual metadata and one for removing all contextual metadata.

Adding context syntax

POST /:resource_type/context

Ruby PHP v1 PHP v2 Python Node.js Java .NET CLI All

Ruby:

result = Cloudinary::Uploader.add_context(context, public_ids, options = {})

PHP v1:

$result = \Cloudinary\Uploader::add_context($context, $public_ids, $options = array());

PHP v2:

$result = $cloudinary->uploadApi()->addContext($context, $public_ids, $options = array());

Python:

result = cloudinary.uploader.add_context(context, public_ids, **options)

Node.js:

cloudinary.v2.uploader.add_context(context, public_ids, options, callback);

Java:

Map result = cloudinary.uploader().addContext(StringDictionary context, String[] public_ids, Map options);

.NET:

var contextParams = new ContextParams() 
{ string Context, List<string> PublicIds, ContextCommand.Add };
var contextResult = cloudinary.Context(contextParams);

CLI:

cld uploader add_context $context $public_ids $options

Removing all context syntax

POST /:resource_type/context

Ruby PHP v1 PHP v2 Python Node.js Java .NET CLI All

Ruby:

result = Cloudinary::Uploader.remove_all_context(public_ids, options = {})

PHP v1:

$result = \Cloudinary\Uploader::remove_all_context($public_ids, $options = array());

PHP v2:

$result = $cloudinary->uploadApi()->removeAllContext($public_ids, $options = array());

Python:

result = cloudinary.uploader.remove_all_context(public_ids, **options)

Node.js:

cloudinary.v2.uploader.remove_all_context(public_ids, options, callback);

Java:

Map result = cloudinary.uploader().removeAllContext(String[] public_ids, Map options);

.NET:

var contextParams = new ContextParams() 
{ List<string> PublicIds, ContextCommand.RemoveAll };
var contextResult = cloudinary.Context(contextParams);

CLI:

cld uploader remove_all_context $public_ids $options

Required parameters

Parameter	Type	Description
context	String	(Only relevant when adding contextual metadata) A pipe-separated list of the key-value pairs of contextual metadata to attach to an uploaded asset. The contextual metadata values of uploaded files can be retrieved using the Admin API. For example: `alt=My image❘caption=Profile image` Notes: The `=` and `❘` characters can be supported as values when escaped with a prepended backslash (`\`). Key values are limited to 1024 characters and an asset can have a maximum of 1000 contextual metadata key-value pairs. SDKs: Supports maps. For example: `['alt': 'My image', 'caption': 'Profile image']`
public_ids	String[]	An array of Public IDs of assets uploaded to Cloudinary.
command	String	(Only relevant when using the REST API - not for use with SDKs) The action to perform on assets: either `add` the specified contextual metadata, or `remove_all` the contextual metadata key-value pairs assigned.
signature	String	(Required for REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs, the signature is automatically generated and added to the request. If you manually generate your own POST request, you also need to manually generate this signature and add it to the request.

Optional parameters

Parameter	Type	Description
resource_type	String	The type of asset. Only relevant as a parameter when using the SDKs (the `resource_type` is included in the endpoint URL when using the REST API). Valid values: `image`, `raw`, and `video`. Default: `image`. Note: Use the `video` resource type for all video assets as well as for audio files, such as `.mp3`.
type	String	The delivery type of the asset. Only relevant as a parameter when using the SDKs (the delivery `type` is included in the endpoint URL when using the REST API). Default: `upload`. For a list of possible delivery types, see Delivery types.

Examples

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

Ruby PHP v1 PHP v2 Python Node.js Java .NET cURL CLI All

Ruby:

Cloudinary::Uploader.add_context('alt=Animal|class=Mammalia', ['dog', 'lion'])

PHP v1:

\Cloudinary\Uploader::add_context('alt=Animal|class=Mammalia', array('dog', 'lion'));

PHP v2:

$cloudinary->uploadApi()->addContext('alt=Animal|class=Mammalia', array('dog', 'lion'));

Python:

cloudinary.uploader.add_context('alt=Animal|class=Mammalia', ['dog', 'lion'])

Node.js:

cloudinary.v2.uploader.add_context('alt=Animal|class=Mammalia', [ 'dog', 'lion' ],
  function(error, result) { console.log(result, error) });

Java:

cloudinary.uploader().addContext("alt=Animal|class=Mammalia",
  ["dog", "lion"], ObjectUtils.emptyMap());

.NET:

var contextParams = new ContextParams(){
  PublicIds = new List<string>(){"dog","lion"},
  Context = "alt=Animal|class=Mammalia",
  Command = ContextCommand.Add};
var contextResult = cloudinary.Context(contextParams);

cURL:

curl https://api.cloudinary.com/v1_1/demo/image/context -X POST --data 'context=alt%3DAnimal%7Cclass%3DMammalia&public_ids[]=dog&public_ids[]=lion&command=add&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'

CLI:

cld uploader add_context 'alt=Animal|class=Mammalia' '["dog", "lion"]'

To remove all existing contextual metadata for the images with the Public IDs of dog and lion

Ruby PHP v1 PHP v2 Python Node.js Java .NET cURL CLI All

Ruby:

Cloudinary::Uploader.remove_all_context(['dog', 'lion'])

PHP v1:

\Cloudinary\Uploader::remove_all_context(array('dog', 'lion'));

PHP v2:

$cloudinary->uploadApi()->removeAllContext(array('dog', 'lion'));

Python:

cloudinary.uploader.remove_all_context(['dog', 'lion'])

Node.js:

cloudinary.v2.uploader.remove_all_context([ 'dog', 'lion' ],
  function(error, result) { console.log(result, error) });

Java:

cloudinary.uploader().removeAllContext(["dog", "lion"], ObjectUtils.emptyMap());

.NET:

var contextParams = new ContextParams(){
  PublicIds = new List<string>(){"dog","lion"},
  Command = ContextCommand.RemoveAll};
var contextResult = cloudinary.Context(contextParams);

cURL:

curl https://api.cloudinary.com/v1_1/demo/image/context -X POST --data 'public_ids[]=dog&public_ids[]=lion&command=replace_all&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'

CLI:

cld uploader remove_all_context '["dog", "lion"]'

Sample response

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

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

Metadata method

The metadata parameter of an uploaded asset contains a map (supported for Java SDK only) or pipe-separated list (for REST API calls) of key-value pairs of custom predefined metadata fields. The metadata method can be used to add values to these metadata fields.

Note

See the Metadata fields documentation for information on creating and managing these fields.

Syntax

POST /:resource_type/metadata

Map result = cloudinary.uploader().updateMetadata(Map metadata, String[] public_ids, Map options);

Required parameters

Parameter	Type	Description
metadata	String	A map (supported for Java SDK only) or pipe-separated list (for REST API calls) of custom metadata fields (by external_id) and the values to assign to each of them. Any metadata-value pairs given are merged with any existing metadata-value pairs (an empty value for an existing metadata field clears the value). The `=`, `"` and `❘` characters can be supported as values when escaped with a prepended backslash (`\`).
public_ids	String[]	An array of Public IDs of assets uploaded to Cloudinary.
signature	String	(Required for REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs, the signature is automatically generated and added to the request. If you manually generate your own POST request, you also need to manually generate this signature and add it to the request.

Optional parameters

Parameter	Type	Description
resource_type	String	The type of asset. Only relevant as a parameter when using the SDKs (the `resource_type` is included in the endpoint URL when using the REST API). Valid values: `image`, `raw`, and `video`. Default: `image`. Note: Use the `video` resource type for all video assets as well as for audio files, such as `.mp3`.
type	String	The delivery type. Valid values: `upload`, `private` and `authenticated`. Default: `upload`

Example

To add the datasource IDs of "id_us", "id_uk", and "id_france" to the metadata field with id 'countryFieldId', to the images with the Public IDs of 'shirt' and 'pants':

Java cURL All

Java:

cloudinary.uploader().updateMetadata(
    ObjectUtils.asMap(
        countryFieldId, 
        new String[]{"id_us", "id_uk", "id_france"}),
    new String[]{"pants", "shirt"}, 
    null);

cURL:

curl https://api.cloudinary.com/v1_1/demo/image/metadata -X POST --data 'metadata=countryFieldId%3D[\"id_us\",\"id_uk\",\"id_france"]&public_ids[]=pants&public_ids[]=shirt&timestamp=173719931&api_key=436264276&signature=a788d62f86a2f862af'

Sample response

The following is a sample response based on the example above. Metadata values were added to the shirt and pants images.

{
  "public_ids": [
    "shirt",
    "pants"
  ]
}

Explicit method

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. You can also use this method to pre-generate transformations for remotely fetched images.

For more information, see Updating already uploaded images.

Syntax

POST /:resource_type/explicit

Ruby PHP v1 PHP v2 Python Node.js Java .NET iOS CLI All

Ruby:

result = Cloudinary::Uploader.explicit(public_id, options = {})

PHP v1:

$result = \Cloudinary\Uploader::explicit($public_id, $options = array());

PHP v2:

$result = $cloudinary->uploadApi()->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);

.NET:

var explicitResult = cloudinary.Explicit(ExplicitParams params); // params includes PublicId

iOS:

let result = cloudinary.createManagementApi().explicit(publicId, params: params)

CLI:

cld uploader explicit $public_id $options

Required parameters

Parameter	Type	Description
public_id	String	The identifier of the uploaded asset or the URL of the remote asset. Note: The public ID value for images and videos should not include a file extension. Include the file extension for `raw` files only.
type	String	The delivery type of the asset. For a list of all possible delivery types, see Delivery types.
signature	String	(Required for REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs, the signature is automatically generated and added to the request. If you manually generate your own POST request, you also need to manually generate this signature and add it to the request.

Optional parameters

Parameter	Type	Description
resource_type	String	The type of asset. Only relevant as a parameter when using the SDKs (the `resource_type` is included in the endpoint URL when using the REST API). Valid values: `image`, `raw`, and `video`. Default: `image`. Note: Use the `video` resource type for all video assets as well as for audio files, such as `.mp3`.
eager	String	A list of transformations to create for the uploaded asset, instead of lazily creating them when first accessed by your site's visitors (see the Transformation URL API Reference for more details on possible values). This option accepts either a single transformation or a pipe-separated list of transformations to create for the uploaded asset. SDKs: Supports arrays. (In .NET SDK, parameter name is `EagerTransforms`.)
async	Boolean	Whether to perform the request in the background (asynchronously). Default: `false`.
eager_async	Boolean	Determines whether to generate the eager transformations asynchronously in the background. Default: `false`.
eager_notification_url	String	An HTTP or HTTPS URL to notify your application (a webhook) when the generation of eager transformations is completed.
overwrite	Boolean	When applying eager for already existing video transformations, this setting indicates whether to force the existing derived video resources to be regenerated. Default for videos: `false`. Note: When specifying existing eager transformations for images, corresponding derived images are always regenerated.
tags	String	A comma-separated list of tag names to assign to an asset that replaces any current tags assigned to the asset (if any). For example: `animal,dog` SDKs: Supports arrays. For example: `['animal', 'dog']`
invalidate	Boolean	Whether to invalidate the asset (and all its derived resources) on the CDN. Default: `false`. It usually takes between a few seconds and a few minutes for the invalidation to fully propagate through the CDN. There are also a number of other important considerations when using the invalidate functionality.
context	String	A pipe-separated list of the key-value pairs of contextual metadata to attach to an uploaded asset. The contextual metadata values of uploaded files can be retrieved using the Admin API. For example: `alt=My image❘caption=Profile image` Notes: The `=` and `❘` characters can be supported as values when escaped with a prepended backslash (`\`). Key values are limited to 1024 characters and an asset can have a maximum of 1000 contextual metadata key-value pairs. SDKs: Supports maps. For example: `['alt': 'My image', 'caption': 'Profile image']`
metadata	String	(not supported for SDKs) A pipe-separated list of custom metadata fields (by external_id) and the values to assign to each of them. The =, " and ❘ characters can be supported as values when escaped with a prepended backslash (`\`). For example: `in_stock_id=50❘color_id=[\"green\",\"red\"]`.
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 a comma-separated list, with individual faces separated with a pipe (`❘`). For example: `10,20,150,130❘213,345,82,61`. Relevant for images only. SDKs: Supports arrays. For example: `[[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 a comma-separated list. For example: `85,120,220,310`. Relevant for images only. SDKs: Supports arrays. For example: `[85, 120, 220, 310]`
notification_url	String	An HTTP URL to send notification to (a webhook) when the operation or any additional requested asynchronous action is completed. If not specified, the response is sent to the global Notification URL (if defined) in the Upload settings of your account console.
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. Returned metadata for images includes: `PixelsPerUnitX`, `PixelsPerUnitY`, `PixelUnits`, `Colorspace`, and `DPI`. Returned metadata for audio and video includes: `audio_codec`, `audio_bit_rate`, `audio_frequency`, `channels`, `channel_layout`. Additional metadata for video includes: `pix_format`, `codec`, `level`, `profile`, `video_bit_rate`, `dar`. (In .NET SDK, parameter name is `Metadata`.)
colors	Boolean	Whether to retrieve predominant colors & color histogram of the uploaded image. If one or more colors contain an alpha channel, then 8-digit RGBA hex quadruplet values are returned. Default: `false`. Relevant for images only.
phash	Boolean	Whether to return the perceptual hash (pHash) on the uploaded image. The pHash acts as a fingerprint that allows checking image similarity. Default: `false`. Relevant for images only.
faces	Boolean	Whether to return the coordinates of faces contained in an uploaded image (automatically detected or manually defined). Each face is specified by the X & Y coordinates of the top left corner and the width & height of the face. The coordinates for each face are returned as an array (using the SDKs) or a comma-separated list (for REST API calls), and individual faces are separated with a pipe (`❘`). For example: `10,20,150,130❘213,345,82,61`. Default: `false`. Relevant for images only.
quality_analysis	Boolean	Whether to return a quality analysis value for the image between 0 and 1, where 0 means the image is blurry and out of focus and 1 means the image is sharp and in focus. Default: `false`. Relevant for images only. Paid customers can request to take part in the extended quality analysis Beta trial. When activated, this parameter returns quality scores for various other factors in addition to `focus`, such as `jpeg_quality`, `noise`, `exposure`, `blockiness` and `resolution`, together with an overall weighted `quality_score`. Note: Unlike when used with the upload method, the returned `quality_score`, `quality_analysis.color_score` and `quality_analysis.pixel_score` fields are not indexed for search.
accessibility_analysis	Boolean	Currently available only to paid customers requesting to take part in the accessibility analysis Beta trial. Set to `true` to return accessibility analysis values for the image. Default: `false`. Relevant for images only. Note: Unlike when used with the upload method, the `accessibility_analysis.colorblind_accessibility_score` field is not indexed for search.
quality_override	String	Sets a quality value to override the value used when the image is encoded with Cloudinary's automatic content-aware quality algorithm.
cinemagraph_analysis	Boolean	Whether to return a cinemagraph analysis value for the media asset between 0 and 1, where 0 means the asset is not a cinemagraph and 1 means the asset is a cinemagraph. Default: `false`. Relevant for animated images and video only. A static image will return 0.
moderation	String	For all asset types: Set to `manual` to add the asset to a queue of pending assets that can be moderated using the Admin API or the Cloudinary Management Console, or set to `metascan` to automatically moderate the uploaded asset using the MetaDefender Anti-malware Protection add-on. For images only: Set to `webpurify` or `aws_rek` to automatically moderate the image using the WebPurify Image Moderation add-on or the Amazon Rekognition AI Moderation add-on respectively. Note: Rejected assets are automatically invalidated on the CDN within approximately ten minutes.
responsive_breakpoints	[JSON]	Requests that Cloudinary automatically find the best breakpoints. The parameter value is an array of breakpoint request settings, where each request setting can include the following parameters: `create_derived`(Boolean - Required) If true, create and keep the derived images of the selected breakpoints during the API call. If false, images generated during the analysis process are thrown away. `format` (String - Optional) Sets the file extension of the derived 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`. 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.
eval	String	Allows you to modify upload parameters by specifying custom logic with JavaScript. This can be useful for conditionally adding tags, contextual metadata, structured metadata or eager transformations depending on specific criteria of the uploaded file. For more details see Evaluating and modifying upload parameters.

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.

Ruby PHP v1 PHP v2 Python Node.js Java .NET iOS cURL CLI All

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

\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"))));

PHP v2:

$cloudinary->uploadApi()->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, error); });

Java:

cloudinary.uploader().explicit("sample", 
  ObjectUtils.asMap(
    "type", "upload",
    "eager", Arrays.asList(
      new EagerTransformation().width(400).height(400)
        .crop("crop").gravity("face"),
      new Transformation().width(660).height(400)
        .crop("pad").background("blue"))));

.NET:

var explicitParams = new ExplicitParams("sample"){
  Type = "upload",
  EagerTransforms = new List<Transformation>(){
    new EagerTransformation().Width(400).Height(400)
      .Crop("crop").Gravity("face"),
    new Transformation().Width(660).Height(400)
      .Crop("pad").Background("blue")}};
var explicitResult = cloudinary.Explicit(explicitParams);

iOS:

let eager1 = CLDEagerTransformation()
  .setWidth(400).setHeight(400).setCrop("crop").setGravity("face")
let eager2 = CLDEagerTransformation()
  .setWidth(660).setHeight(400).setCrop("pad").setBackround("blue")
let params = CLDExplicitRequestParams().setEager([eager1, eager2])
let result = cloudinary.createManagementApi().explicit(publicId, params: params)

cURL:

curl https://api.cloudinary.com/v1_1/demo/image/explicit -X POST --data 'type=upload&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'

CLI:

cld uploader explicit "sample" type="upload" eager='[{ "width": 400, "height": 400,"crop": "crop", "gravity": "face"},{ "width": 660, "height": 400,"crop": "pad", "background": "blue"}]'

Note

When you perform an eager transformation using explicit, the transformation is processed upon request (and counted in your transformation quota) even if an identical derived resource already exists.

Sample response

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

{
  "asset_id": "b5e6d2b39ba3e0869d67141ba7dba6cf",
  "public_id": "sample",
  "version": 1473599877,
  "version_id": "98f52566f43d8e516a486958a45c1eb9",
  "signature": "abcdefghijklmnopqrstuvwxyz12345",
  "width": 864,
  "height": 576,
  "format": "jpg",
  "resource_type": "image",
  "created_at": "2017-08-11T13:17:57Z",
  "bytes": 109669,
  "type": "upload",
  "placeholder": "false",
  "url": "http://res.cloudinary.com/demo/image/upload/v1473599877/sample.jpg",
  "secure_url": "https://res.cloudinary.com/demo/image/upload/v1473599877/sample.jpg",
  "access_mode": "public",
  "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 method

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

You could deliver individual pages of a multi-page file on-the-fly without using the explode method first: this method is useful for pre-generating all the pages of the file so that they do not need to be generated on-the-fly when first accessed by your users.

Syntax

POST /image/explode

Ruby PHP v1 PHP v2 Python Node.js Java .NET iOS CLI All

Ruby:

result = Cloudinary::Uploader.explode(public_id, options = {})

PHP v1:

$result = \Cloudinary\Uploader::explode($public_id, $options = array());

PHP v2:

$result = $cloudinary->uploadApi()->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);

.NET:

var explodeResult = cloudinary.Explode(ExplodeParams params); // params includes PublicId

iOS:

let result = cloudinary.createManagementApi().explode(publicId, params: params)

CLI:

cld uploader explode $public_id $options

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

transformation | String | A transformation to run on all the pages before storing them as derived images. This parameter is given as a comma-separated list of transformations, and separated with a slash for chained transformations.

At minimum, you must pass the page transformation with the value all. If you supply additional transformations, you must deliver the image using the same relative order of the page and the other transformations. If you use a different order when you deliver, then it is considered a different transformation, and will be generated on-the-fly as a new derived image.

SDKs: Supports a hash of transformation parameters (or an array of hashes for chained transformations).

Note: When using the SDK for a dynamically-typed language, the transformation parameters can be specified directly without using this transformation parameter, as seen in the examples for Ruby, PHP, Python, and Node.js below. signature | String | (Required for REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs, the signature is automatically generated and added to the request. If you manually generate your own POST request, you also need to manually generate this signature and add it to the request.

Optional parameters

Parameter	Type	Description
type	String	The specific file type of the asset. Valid values: `upload`, `private` and `authenticated`. Default: `upload`.
format	String	An optional format to convert the images before storing them in your Cloudinary account. Default: `png`.
notification_url	String	An HTTP or HTTPS URL to notify your application (a webhook) when the process has completed.

Example

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

Ruby PHP v1 PHP v2 Python Node.js Java .NET iOS cURL CLI All

Ruby:

Cloudinary::Uploader.explode('sample', 
  :page => 'all')

PHP v1:

\Cloudinary\Uploader::explode('sample', 
  array('page' => 'all'));

PHP v2:

$cloudinary->uploadApi()->explode('sample', 
  array('page' => 'all'));

Python:

cloudinary.uploader.explode('sample', 
    page = 'all')

Node.js:

cloudinary.v2.uploader.explode('sample', 
  { page: 'all'},
  function(error,result) {console.log(result, error) });

Java:

cloudinary.uploader().explode("sample",
  ObjectUtils.asMap("transformation", new Transformation().page("all"));

.NET:

var explodeParams = new ExplicitParams("sample", new Transformation().Path("all"));
var explodeResult = cloudinary.Explode(explodeParams);

iOS:

let transform = CLDTransformation().setPage("all")
let result = cloudinary.createManagementApi().explode("sample", transformation: transform)

cURL:

curl https://api.cloudinary.com/v1_1/demo/image/explode -X POST --data 'public_id=sample&transformation=pg_all&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'

CLI:

cld uploader explode "sample" page="all"

Sample response

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

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

Generate_archive method

The generate_archive method creates an archive file that contains all the assets meeting specified tag, public ID, or prefix criteria (or a combination thereof). The REST API method can be used to either return 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.

Important note for free accounts

By default, while you can still use this method to generate archive files, free Cloudinary accounts are blocked from delivering zip, rar, tagz, and other archive formats for security reasons.
For details or to request that this limitation be removed for your free account, see Media delivery.

The Cloudinary SDKs wrap the generate_archive REST API 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 (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.

create_zip syntax

POST /:resource_type/generate_archive

Ruby PHP v1 PHP v2 Python Node.js Java .NET CLI All

Ruby:

result = Cloudinary::Uploader.create_zip(options = {})

PHP v1:

$result = \Cloudinary\Uploader::create_zip($options = array());

PHP v2:

$result = $cloudinary->uploadApi()->createZip($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);

.NET:

var archiveResult = cloudinary.CreateZip(ArchiveParams params);

CLI:

cld uploader create_zip $options

create_archive syntax

POST /:resource_type/generate_archive

Ruby PHP v1 PHP v2 Python Node.js Java .NET CLI All

Ruby:

result = Cloudinary::Uploader.create_archive(options = {}, target_format = nil)

PHP v1:

$result = \Cloudinary\Uploader::create_archive($options = array(), $target_format = NULL);

PHP v2:

$result = $cloudinary->uploadApi()->createArchive($options = array(), $target_format = NULL);

Python:

result = cloudinary.uploader.create_archive(**options)

Node.js:

cloudinary.v2.uploader.create_archive(options, target_format = null, callback);

Java:

Map result = cloudinary.uploader().createArchive(Map options);
-Or-
Map result = createArchive(Map options, String targetFormat);

.NET:

var archiveResult = cloudinary.CreateArchive(ArchiveParams params);

CLI:

cld uploader create_archive $options

download_zip_url syntax

POST /:resource_type/generate_archive

Ruby PHP v1 PHP v2 Python Node.js Java .NET CLI All

Ruby:

url = Cloudinary::Utils.download_zip_url(options = {})

PHP v1:

$url = \Cloudinary::download_zip_url($options = array());

PHP v2:

$url = $cloudinary->uploadApi()->downloadZipUrl($options = []);

Python:

url = cloudinary.utils.download_zip_url(**options)

Node.js:

cloudinary.v2.utils.download_zip_url(options);

Java:

String url = cloudinary.downloadZip(Map options);

.NET:

string url = cloudinary.DownloadArchiveUrl(ArchiveParams params);

CLI:

cld utils download_zip_url $options

download_archive_url syntax

POST /:resource_type/generate_archive

Ruby PHP v1 PHP v2 Python Node.js Java .NET CLI All

Ruby:

url = Cloudinary::Utils.download_archive_url(options = {})

PHP v1:

$url = \Cloudinary::download_archive_url($options = array());

PHP v2:

$url = $cloudinary->uploadApi()->downloadArchiveUrl($options = []);

Python:

url = cloudinary.utils.download_archive_url(**options)

Node.js:

cloudinary.v2.utils.download_archive_url(options);

Java:

String url = cloudinary.downloadArchive(Map options);

.NET:

string url = cloudinary.DownloadArchiveUrl(ArchiveParams params);

CLI:

cld utils download_archive_url $options

Required parameters

At least one of the 'tags', 'public_ids', or 'prefixes' parameters needs to be specified, in order to tell Cloudinary which assets to include in the archive file. Specifying any combination of the three parameters is also allowed - a unique union of all the matching assets will then be included in the archive file:

Parameter	Type	Description
tags	String	A comma-separated list of tag names. All assets with the specified tags are included in the archive. Up to 20 tags are supported. For example: `animal,dog` SDKs: Supports arrays. For example: `['animal', 'dog']`
public_ids	String	A comma-separated list of public IDs for the specific assets to be included in the archive. Up to 1000 public IDs are supported. SDKs: Supports arrays.
prefixes	String	A comma-separated list of prefixes of public IDs (e.g., folders). Setting this parameter to a slash (`/`) is a shortcut for including all assets in the account for the given `resource_type` and `type` (up to the max files limit). Up to 20 prefixes are supported. SDKs: Supports arrays.
signature	String	(Required for REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs, the signature is automatically generated and added to the request. If you manually generate your own POST request, you also need to manually generate this signature and add it to the request.

Optional parameters

Parameter	Type	Description
resource_type	String	The type of asset. Only relevant as a parameter when using the SDKs (the `resource_type` is included in the endpoint URL when using the REST API). Valid values: `image`, `raw`, and `video`. Default: `image`. Note: Use the `video` resource type for all video assets as well as for audio files, such as `.mp3`.
type	String	The 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 a comma-separated list of transformations, and separated with a slash for chained transformations. If this parameter is not specified then the original assets are included in the archive. If you are including multiple asset types in your archive, make sure the transformations you specify are supported for all assets that will be included in the archive. SDKs: Supports a hash of transformation parameters (or an array of hashes for chained transformations). Note: When using the SDK for a dynamically-typed language, the transformation parameters can be specified directly without using the `transformation` parameter.
mode	String	(Only relevant when using the REST API - not for use with SDKs) 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`). Default: `create`.
target_format	String	(Only relevant when using the REST API or the 'archive' SDK methods - not for use with the 'zip' SDK methods)The format for the generated archive: `zip` or `tgz`. Default: `zip`.
target_public_id	String	The name to use for the generated file: When the `mode` parameter is set to `create` (or when using one of the create* SDK methods), this parameter defines the Public ID to assign to the generated archive. When the `mode` parameter is set to `download` (or when using one of the download* SDK methods), this parameter defines the filename of the downloaded archive file. If not specified, a random Public ID (or download filename) is generated.
flatten_folders	Boolean	Determines whether to flatten all files to be in the root of the archive file (no sub-folders). Any folder information included in the Public ID is stripped and a numeric counter is added to the file name in the case of a name conflict. Default: `false`.
flatten_transformations	Boolean	If multiple transformations are also applied, determines whether to flatten the folder structure of the derived assets and store the transformation details on the file name instead. Default: `false`.
skip_transformation_name	Boolean	Determines whether to strip all transformation details from file names and add a numeric counter to a file name in the case of a name conflict. Default: `false`.
allow_missing	Boolean	Allows generation of the archive if any of the supplied Public IDs are not found, instead of returning an error. Default: `false`.
expires_at	Integer	(Only relevant when using the 'download' SDK methods and the 'download' mode in REST API calls) The date (UNIX time in seconds) for the URL expiration (e.g., 1415060076). Default: 1 hour from the time that the URL is generated.
use_original_filename	Boolean	Whether to use the original file name of the included assets (if available) instead of the public ID. Default: `false`.
async	Boolean	(Only relevant when using the 'create' SDK methods and the 'create' mode in REST API calls) Whether to perform the archive generation in the background (asynchronously). Default: `false`.
notification_url	String	(Only relevant when using the 'create' SDK methods and the 'create' mode in REST API calls) An HTTP or HTTPS URL to notify your application (a webhook) when the archive creation process has completed. If not specified for create operations, the response is sent to the global Notification URL (if defined) in the Upload settings of your account console.
target_tags	String	(Only relevant when using the 'create' SDK methods and the 'create' mode in REST API calls) A comma-separated list of tag names to assign to the generated archive. For example: `animal,dog` SDKs: Supports arrays. For example: `['animal', 'dog']`
keep_derived	Boolean	Whether to keep the derived assets used for generating the archive. Default: `false.`

Examples

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

Ruby PHP v1 PHP v2 Python Node.js Java .NET cURL CLI All

Ruby:

Cloudinary::Uploader.create_zip(
  :tags => 'lion', 
  :resource_type => 'image')

PHP v1:

\Cloudinary\Uploader::create_zip(
  array(
    'tags' => 'lion', 
    'resource_type' => 'image'));

PHP v2:

$cloudinary->uploadApi()->createZip(
  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, error) });

Java:

cloudinary.uploader().createZip(
    ObjectUtils.asMap(
        'tags', 'lion', 
        'resource_type', 'image'));

.NET:

var archiveParams = new ArchiveParams(){
  ResourceType = "image",
  Tags = "lion"};
var archiveResult = cloudinary.CreateZip(archiveParams);

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'

CLI:

cld uploader create_zip tags="lion" resource_type="image"

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

Ruby PHP v1 PHP v2 Python Node.js Java .NET cURL CLI All

Ruby:

Cloudinary::Utils.download_zip_url(
  :public_ids => ['dog','cat','lion'], 
  :resource_type => 'image')

PHP v1:

\Cloudinary\Utils::download_zip_url(
  array(
    'public_ids' => array('dog', 'cat', 'lion'), 
    'resource_type' => 'image'));

PHP v2:

$cloudinary->uploadApi()->downloadZipUrl(
  array(
    'public_ids' => array('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'});

Java:

cloudinary.downloadZip(
  ObjectUtils.asMap(
    'public_ids', Arrays.asList('dog', 'cat', 'lion'), 
    'resource_type', 'image'));

.NET:

var archiveParams = new ArchiveParams(){
  ResourceType = "image",
  PublicIds = new List<string>(){"dog", "cat", "lion"}};
string url = cloudinary.DownloadArchiveUrl(archiveParams);

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'

CLI:

cld utils download_zip_url public_ids='["dog","cat","lion"]' resource_type="image"

Sample response

The following is a sample response based on the create_zip example above. 6 image assets with the tag 'lion' were added to the zip file. Because no target_public_id was specified in the upload, a random public_id was assigned to the zip file.

{
  "asset_id": "08e80d01729e8e238d605f6bc7aa1b92",
  "public_id": "oe5bz4vbtdg0ijr323on.zip",
  "version": 1570980108,
  "version_id": "9a048093cdbb048d0829bdb46c378e43",
  "signature": "abcdefghijklmnopqrstuvwxyz12345",
  "resource_type": "raw",
  "created_at": "2017-08-12T14:03:31Z",
  "tags": [],
  "bytes": 1153022,
  "type": "upload",
  "etag": "00e3a782aa2c390dc605d0548d067177",
  "placeholder": false,
  "url": "http://res.cloudinary.com/demo/raw/upload/v1570980108/oe5bz4vbtdg0ijr323on.zip",
  "secure_url": "https://res.cloudinary.com/demo/raw/upload/v1570980108/oe5bz4vbtdg0ijr323on.zip",
  "access_mode": "public",
  "resource_count": 6,
  "file_count": 6
}

Sprite method

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

POST /image/sprite

Ruby PHP v1 PHP v2 Python Node.js Java .NET iOS CLI All

Ruby:

result = Cloudinary::Uploader.generate_sprite(tag, options = {})

PHP v1:

$result = \Cloudinary\Uploader::generate_sprite($tag, $options = array());

PHP v2:

$result = $cloudinary->uploadApi()->generateSprite($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);

.NET:

var spriteResult = cloudinary.MakeSprite(SpriteParams params);

iOS:

let result = cloudinary.createManagementApi().generateSprite(tag, params: params)

CLI:

cld uploader generate_sprite $tag $options

Required parameters

Parameter	Type	Description
tag	String	The sprite is created from all images with this tag.
signature	String	(Required for REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs, the signature is automatically generated and added to the request. If you manually generate your own POST request, you also need to manually generate this signature and add it to the request.

Optional parameters

Parameter	Type	Description
transformation	String	A transformation to run on all the derived assets before creating the sprite. This parameter is given as a comma-separated list of transformations, and separated with a slash for chained transformations. SDKs: Supports a hash of transformation parameters (or an array of hashes for chained transformations). Note: When using the SDK for a dynamically-typed language, the transformation parameters can be specified directly without using the `transformation` parameter.
format	String	An optional format to convert the sprite before saving it in your Cloudinary 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. If not specified, the response is sent to the global Notification URL (if defined) in the Upload settings of your account console.

Example

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

Ruby PHP v1 PHP v2 Python Node.js Java .NET iOS cURL CLI All

Ruby:

Cloudinary::Uploader.generate_sprite('logo')

PHP v1:

\Cloudinary\Uploader::generate_sprite('logo');

PHP v2:

$cloudinary->uploadApi()->generateSprite('logo');

Python:

cloudinary.uploader.generate_sprite('logo')

Node.js:

cloudinary.v2.uploader.generate_sprite('logo',
  function(error,result) {console.log(result, error) });

Java:

cloudinary.uploader().generateSprite('logo', 
  ObjectUtils.emptyMap());

.NET:

var spriteParams= new SpriteParams("logo");
var spriteResult = cloudinary.MakeSprite(spriteParams);

iOS:

let result = cloudinary.createManagementApi().generateSprite("logo")

cURL:

curl https://api.cloudinary.com/v1_1/demo/image/sprite -X POST --data 'tag=logo&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'

CLI:

cld uploader generate_sprite "logo"

Sample response

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

{
  "css_url": "http://res.cloudinary.com/demo/image/sprite/v1473689611/logo.css",
  "secure_css_url": "https://res.cloudinary.com/demo/image/sprite/v1473689611/logo.css",
  "image_url": "http://res.cloudinary.com/demo/image/sprite/v1473689611/logo.png",
  "secure_image_url": "https://res.cloudinary.com/demo/image/sprite/v1473689611/logo.png",
  "json_url": "http://res.cloudinary.com/demo/image/sprite/v1473689611/logo.json",
  "secure_json_url": "https://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 },
    "https://res.cloudinary.com/demo/image/upload/v1549540112/logo2.png": {
      "width": 32,
      "height": 32,
      "x": 0,
      "y": 167 },
    "https://cloudinary.com/images/logo.png": {
      "width": 165,
      "height": 165,
      "x": 0,
      "y": 201 }
  }
}

Multi method

The multi method creates either a single animated image (GIF, PNG or WebP), video (MP4 or WebM) or a single PDF from all image assets that have been assigned a specified tag. Each asset is included as a single frame of the resulting animated image/video, or a page of the PDF (sorted alphabetically by their Public ID).

For a detailed explanation on generating animated images, see Creating animated images.

For further information about generating a PDF from a selection of images, see Creating PDF files from images.

Important note for free accounts

By default, while you can use this method to generate PDF files, free Cloudinary accounts are blocked from delivering files in PDF format for security reasons.
For details or to request that this limitation be removed for your free account, see Media delivery.

Syntax

POST /image/multi

Ruby PHP v1 PHP v2 Python Node.js Java .NET iOS CLI All

Ruby:

result = Cloudinary::Uploader.multi(tag, options = {})

PHP v1:

$result = \Cloudinary\Uploader::multi($tag, $options = array());

PHP v2:

$result = $cloudinary->uploadApi()->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);

.NET:

var multiResult = cloudinary.Multi(MultiParams params);

iOS:

let result = cloudinary.createManagementApi().multi(tag, params: params)

CLI:

cld uploader multi $tag $options

Required parameters

Parameter	Type	Description
tag	String	The animated GIF or PDF is created from all images with this tag.
signature	String	(Required for REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs, the signature is automatically generated and added to the request. If you manually generate your own POST request, you also need to manually generate this signature and add it to the request.

Optional parameters

Parameter	Type	Description
transformation	String	A transformation to run on all the derived assets before creating the animated image or PDF. This parameter is given as a comma-separated list of transformations, and separated with a slash for chained transformations. SDKs: Supports a hash of transformation parameters (or an array of hashes for chained transformations). Note: When using the SDK for a dynamically-typed language, the transformation parameters can be specified directly without using the `transformation` parameter.
async	Boolean	Tells Cloudinary whether to perform the animated image or PDF generation in the background (asynchronously). Default: `false`.
format	String	The file format of the result. Valid values: `gif`, `png`, `webp`, `mp4`, `webm` and `pdf`. Default: `gif`
delay	Integer	The delay in milleseconds between frames. Valid for animated images and video formats.
notification_url	String	An HTTP or HTTPS URL to notify your application (a webhook) when the process has completed. If not specified, the response is sent to the global Notification URL (if defined) in the Upload settings of your account console.

Examples

Generating an animated GIF from all images tagged with logo:

Ruby PHP v1 PHP v2 Python Node.js Java .NET iOS cURL CLI All

Ruby:

Cloudinary::Uploader.multi('logo')

PHP v1:

\Cloudinary\Uploader::multi('logo');

PHP v2:

$cloudinary->uploadApi()->multi('logo');

Python:

cloudinary.uploader.multi('logo')

Node.js:

cloudinary.v2.uploader.multi('logo',
  function(error,result) {console.log(result, error) });

Java:

cloudinary.uploader().multi('logo', ObjectUtils.emptyMap());

.NET:

var multiParams= new MultiParams("logo");
var multiResult = cloudinary.Multi(multiParams);

iOS:

let result = cloudinary.createManagementApi().multi("logo")

cURL:

curl https://api.cloudinary.com/v1_1/demo/image/multi -X POST --data 'tag=logo&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'

CLI:

cld uploader multi "logo"

Sample response

The following is a sample 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",
  "asset_id": "00a215ac20890831fe59daeeb2f108ec",
  "public_id": "logo",
  "version": 1473690796
}

Generating an animated webp from all images tagged with logo:

Ruby PHP Python Node.js Java .NET iOS cURL CLI All

Ruby:

Cloudinary::Uploader.multi('logo', 
  :format => 'webp')

PHP:

\Cloudinary\Uploader::multi('logo',
  array('format' => 'webp'));

Python:

cloudinary.uploader.multi('logo',
  format = 'webp')

Node.js:

cloudinary.v2.uploader.multi('logo', 
  {format: 'webp'},
  function(error,result) {console.log(result, error) });

Java:

cloudinary.uploader().multi("logo", 
  ObjectUtils.asMap("format", "webp"));

.NET:

var multiParams= new MultiParams("logo")
  {
    Format = "webp"
  };
var multiResult = cloudinary.Multi(multiParams);

iOS:

let result = cloudinary.createManagementApi().multi("logo", format: "webp")

cURL:

curl https://api.cloudinary.com/v1_1/demo/image/multi -X POST --data 'tag=logo&format=webp&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'

CLI:

cld uploader multi "logo" format="webp"

Sample response

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

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

Text method

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

Syntax

POST /image/text

Ruby PHP v1 PHP v2 Python Node.js Java .NET iOS Endpoint CLI All

Ruby:

result = Cloudinary::Uploader.text(text, options = {})

PHP v1:

$result = \Cloudinary\Uploader::text($text, $options = array());

PHP v2:

$result = $cloudinary->uploadApi()->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);

.NET:

var textResult = cloudinary.Text(TextParams params);

iOS:

let result = cloudinary.createManagementApi().text(text, params: params)

Endpoint:

https://api.cloudinary.com/v1_1/<cloud_name>/image/text

CLI:

cld uploader text $text $options

Required parameters

Parameter	Type	Description
text	String	The text string to generate an image for.
signature	String	(Required for REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs, the signature is automatically generated and added to the request. If you manually generate your own POST request, you also need to manually generate this signature and add it to the request.

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

Ruby PHP v1 PHP v2 Python Node.js Java .NET iOS cURL CLI All

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

\Cloudinary\Uploader::text("Sample text string",
  array(
    "public_id" => "sample_text_image",
    "font_family" => "Roboto", 
    "font_size" => 42,
    "font_color" => "red", 
    "font_weight" => "bold"));

PHP v2:

$cloudinary->uploadApi()->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(error, result) { console.log(result, error) });

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"));

.NET:

var textParams = new TextParams("Sample text string"){
  PublicId = "sample_text_image",
  FontFamily = "Roboto",
  FontSize = 42,
  FontColor = "red",
  FontWeight= "bold"};
var textResult = cloudinary.Text(textParams);

iOS:

let params = CLDTextRequestParams()
  .setPublicId("sample_text_image")
  .setFontFamily("Roboto")
  .setFontSize("42")
  .setFontColor("red")
  .setFontWeight(.bold)
let result = cloudinary.createManagementApi().multi("Sample text string", params: params)

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'

CLI:

cld uploader text "Sample text string" public_id="sample_text_image" font_family="Roboto" font_size=42 font_color="red" font_weight="bold"

Sample response

The following is a sample response based on the example above. A text image is created with the public_id sample_text_image based on the transformations requested in the text method.

{
  "asset_id": "f658a81a606a6b2edb164cc2f0983620",
  "public_id": "sample_text_image",
  "version": 1473692896,
  "version_id": "9b5cfabc0972be386ecb2f15aeeff920",
  "signature": ""abcdefghijklmnopqrstuvwxyz12345"",
  "width": 342,
  "height": 41,
  "format": "png",
  "resource_type": "image",
  "created_at": "2017-08-12T15:08:16Z",
  "tags": [],
  "bytes": 3670,
  "type": "text",
  "placeholder": false,
  "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",
  "access_mode": "public"
}

✔️ Feedback sent!

✖️

Error

Unfortunately there's been an error sending your feedback.

Rate this page: