Additional upload API options

Alongside upload functionality, the Cloudinary Upload API provides additional methods for managing, organizing, and creating media assets. All the methods in the Upload API are not rate-limited and can be used as needed.

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

Update already uploaded assets

The explicit API method is used to apply actions on already uploaded assets. The most common usage of this method is to pre-generate transformations for assets that have already been uploaded. This is particularly useful when Strict Transformations are enabled for your account and you cannot create transformed assets on the fly (for more information, see Control access to assets). To generate these transformations, the explicit method uses the eager parameter to define the list of transformations to create for the uploaded asset of a specified Public ID (see the Image or video transformation documentation for more details on possible transformation values). The eager parameter accepts either a single transformation or an array of transformations, where each transformation is represented by a hash of parameters to create for the uploaded resource.

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 image already exists.

Examples of other uses for the explicit method include:

  • Updating the meta data parameters stored with the image, such as custom_coordinates, face_coordinates, tags, etc.
  • Invalidating cached copies of a media asset on the CDN.
  • Applying one of Cloudinary's add-ons to the image (e.g., removing the background).

The explicit API method also requires specifying the type of the resource: upload, private or authenticated. For example, the following method will explicitly generate two transformations for the already uploaded JPG private image named sample3:

  1. Scale to a width of 200 pixels.
  2. Crop to a width of 360 pixels and a height of 200 pixels with north gravity.
Ruby:
Copy to clipboard
Cloudinary::Uploader.explicit("sample3", 
  :type => "private",
  :eager => [
    {:width => 200, :crop => :scale}, 
    {:width => 360, :height => 200, 
       :crop => :crop, :gravity => :north }])
PHP:
Copy to clipboard
\Cloudinary\Uploader::explicit("sample3", 
  array(
    "type" => "private", 
    "eager" => array(
      array("width" => 200, "crop" => "scale"),
      array("width" => 360, "height" => 200, 
        "crop" => "crop", "gravity" => "north"))));
Python:
Copy to clipboard
cloudinary.uploader.explicit("sample3", 
  type = "private", 
  eager = [
    {"width": 200, "crop": "scale"},
    {"width": 360, "height": 200, 
       "crop": "crop", "gravity": "north"}])
Node.js:
Copy to clipboard
cloudinary.v2.uploader.explicit("sample3", 
  { type: "private",
    eager: [
      { width: 200, crop: "scale" }, 
      { width: 360, height: 200, 
          crop: "crop", gravity: "north"} ] }, 
  function(error, result) {console.log(result, error); } );
Java:
Copy to clipboard
cloudinary.uploader().explicit("sample3", ObjectUtils.asMap(
  "type", "private",
  "eager", Arrays.asList(
    new Transformation().width(200).crop("scale"),
    new Transformation().width(360).height(200)
      .crop("crop").gravity("north"))));
.Net:
Copy to clipboard
var explicitParams = new ExplicitParams("sample3"){
  Type = "private",
  EagerTransforms = new List<Transformation>(){
   new Transformation().Width(200).crop("scale"),
   new Transformation().Width(360).Height(200)
     .Crop("crop").Gravity("north")}};
var explicitResult = cloudinary.Explicit(explicitParams);

Asset administration

Assets can be administered through Cloudinary's API (or the Media Library web interface) which allows you to perform the following actions on an uploaded asset:

  • Delete the asset.
  • Rename the asset by changing its Public ID.
  • Invalidate a cached media asset on the CDN.
  • Add tags to the asset.

Deleting assets

Deleted media assets are immediately and permanently deleted from your cloud storage with the destroy method. However, assets and transformed assets already downloaded by visitors to your website might still be accessible through cached copies on the CDN. This method deletes a single resource at a time: to delete multiple assets see the Admin API Delete resources method.

You can set the invalidate parameter to true while deleting a media asset in order to also invalidate the copies of the asset on the CDN. Keep in mind that it usually takes a few minutes (although it might take up to an hour) for the invalidation to fully propagate through the CDN. There are also a number of other important considerations when using the invalidate functionality.

For example, deleting an image with the Public ID of "sample":

Ruby:
Copy to clipboard
Cloudinary::Uploader.destroy('sample')
PHP:
Copy to clipboard
\Cloudinary\Uploader::destroy('sample');
Python:
Copy to clipboard
cloudinary.uploader.destroy('sample')
Node.js:
Copy to clipboard
cloudinary.v2.uploader.destroy('sample', 
  function(error, result) {console.log(result, error) });
Java:
Copy to clipboard
cloudinary.uploader().destroy('sample',
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
var deletionParams = new DeletionParams(){
  PublicId = "sample"};
var deletionResult = cloudinary.Destroy(deletionParams);

Renaming assets

Renamed media assets are immediately and permanently updated in your cloud storage with the rename method of the API. Any existing URLs of renamed assets and their associated derived assets are no longer valid, but assets and transformed assets already downloaded by visitors of your website might still be accessible for a certain period of time through cached copies on the CDN.

You can set the invalidate parameter to true while renaming an asset in order to also invalidate the cached copies of the asset on the CDN. Keep in mind that it usually takes a few minutes (although it might take up to an hour) for the invalidation to fully propagate through the CDN. There are also a number of other important considerations when using the invalidate functionality.

For example, renaming an image with the Public ID of old_name to new_name:

Ruby:
Copy to clipboard
Cloudinary::Uploader.rename('old_name', 'new_name')
PHP:
Copy to clipboard
\Cloudinary\Uploader::rename('old_name', 'new_name');
Python:
Copy to clipboard
cloudinary.uploader.rename('old_name', 'new_name')
Node.js:
Copy to clipboard
cloudinary.v2.uploader.rename('old_name', 'new_name', 
  function(error, result) { console.log(result, error) })
Java:
Copy to clipboard
cloudinary.uploader().rename("old_name", "new_name", 
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
var renameParams = new RenameParams(){
  FromPublicId = "old_name",
  ToPublicId = "new_name"};
var renameResult = cloudinary.Rename(renameParams);

You can also add one of the following optional parameters:

  • overwrite - (Boolean) Whether to overwrite an existing asset with the target Public ID. Default: false.
  • invalidate - (Boolean) Whether to invalidate cached copies of the asset on the CDN. Default: false.

Invalidating cached media assets on the CDN

Even after you delete, rename, or overwrite an image or video asset in your Cloudinary storage, the old cached media asset can remain on the CDN servers for up to 30 days.

To prevent users from accessing the old asset, you can send an invalidation request instructing the CDN to remove cached copies of the old asset, so that the next request for the asset will pull the newest copy from your Cloudinary storage, or will return an error if the asset no longer exists.

You can send an invalidation request by setting the invalidate parameter to true in relevant methods of the Upload API. From within the Media Library, an invalidate request is automatically included whenever you delete, rename, or overwrite media assets. You may also be able to use relevant Admin API methods to invalidate media assets if support for bulk invalidations has been added to your account (not supported by default).

The assets that will actually be invalidated during an invalidate request depend on the value set for the global Invalidate versioned URLs option in your account’s upload settings and whether the public ID of a particular URL is organized in a folder structure. The table below summarizes these considerations.

Invalidate versioned URLs Disabled (default) Enabled
Assets not in folders Only URLs without a version are invalidated. For example:

https://res.cloudinary.com/demo/image/upload/sample.jpg
Only URLs with the most recent version are invalidated. For example:

https://res.cloudinary.com/demo/image/upload/v14858684/sample.jpg
Assets in folders Only URLs delivered with the /v1/ component are invalidated. For example:

https://res.cloudinary.com/demo/image/upload/v1/folder1/folder2/sample.jpg

If you need to invalidate images or videos with a folder structure that were delivered without the /v1/ component, submit a service request
Only URLs with the most recent version are invalidated. For example:

https://res.cloudinary.com/demo/image/upload/v14858684/folder1/folder2/sample.jpg

Notes

  • By default, signed URLs (with or without versions) are not invalidated. If you need to invalidate signed URLs submit a service request.
  • It can take from a few minutes up to an hour for the invalidation to fully propagate through the CDN. To bypass the CDN cached version and force immediate delivery of the newest image or video, include versions in your delivery URLs.

Tagging assets

Tags are used to categorize and organize your assets, and can also be used to bulk delete assets, create sprites, ZIP files, JSON lists, generate PDFs and animated GIFs. Each asset can be assigned one or more tags, which is a short name that you can dynamically use (no need to predefine tags). You can assign tags to assets while uploading them by also specifying the tags parameter in the upload method.

For example, uploading the image sample.jpg and adding the tag animal to the image:

Ruby:
Copy to clipboard
Cloudinary::Uploader.upload("sample.jpg", 
  :tags => "animal")
PHP:
Copy to clipboard
\Cloudinary\Uploader::upload("sample.jpg", 
  array("tags" => "animal"));
Python:
Copy to clipboard
cloudinary.uploader.upload("sample.jpg", 
  tags = "animal")
Node.js:
Copy to clipboard
cloudinary.v2.uploader.upload("sample.jpg", 
  { tags: "animal" }, 
  function(error, result) {console.log(result, error) });
Java:
Copy to clipboard
cloudinary.uploader().upload(new File("sample.jpg"),
  ObjectUtils.asMap("tags", "animal"));
.Net:
Copy to clipboard
var uploadParams = new UploadParams(){
  Tags = "animal"};
var uploadResult = cloudinary.Upload(uploadParams);
iOS:
Copy to clipboard
let params = CLDUploadRequestParams()
  .setTags("animal")
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: "sample.jpg", params: params)

You can also use our API or Management Console for adding, removing or changing tags assigned to assets. Cloudinary's SDKs allow you to add tags to previously uploaded assets with the add_tag API method. This method accepts 2 parameters (use an array for multiple values): the tag(s) to add and the Public ID(s) of the asset(s) to be tagged. For example, adding the tag "animal" to the assets with the Public IDs of "dog" and "lion":

Ruby:
Copy to clipboard
Cloudinary::Uploader.add_tag('animal', 
  ['dog', 'lion'])
PHP:
Copy to clipboard
\Cloudinary\Uploader::add_tag('animal', 
  array('dog', 'lion'));
Python:
Copy to clipboard
cloudinary.uploader.add_tag('animal', 
  ['dog', 'lion'])
Node.js:
Copy to clipboard
cloudinary.v2.uploader.add_tag('animal', 
  [ 'dog', 'lion' ],
  function(error, result) { console.log(result, error) });
Java:
Copy to clipboard
cloudinary.uploader().addTag("animal",
  ["dog", "lion"], 
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
var tagParams = new TagParams(){
  PublicIds = new List<string>(){dog,lion},
  Tag = "animal",
  Command = TagCommand.Add};
var tagResult = cloudinary.Tag(tagParams);

Assigning tags to assets allows you to create group actions on assets that share the same tag. For example, using the resources_by_tag method of the Admin API to list all assets that share the tag "animal":

Ruby:
Copy to clipboard
Cloudinary::Api.resources_by_tag("animal")
PHP:
Copy to clipboard
$api->resources_by_tag("animal");
Python:
Copy to clipboard
cloudinary.api.resources_by_tag("animal")
Node.js:
Copy to clipboard
cloudinary.api.resources_by_tag("animal", 
  function(error, result) {console.log(result); });
Java:
Copy to clipboard
api.resourcesByTag("animal", 
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
var listResult = cloudinary.ListResourcesByTag("animal");

Monitoring tag changes using the notification_url

You can monitor for changes to the tags on your media assets, including tags that have been added or removed via API or the account console UI. These changes are sent as webhook notifications to the Notification URL specified in the Upload tab of your account settings. To capture these changes, monitor for the response parameter: resource_tags_changed. Within it, you'll find information about which resource was changed, the source of the change (UI or API), and whether tags were added, removed, or both. For example:

Copy to clipboard
{
 "notification_type": "resource_tags_changed",
 "source": "ui",
 "resources": [
   { "public_id": "sailing_angel", "resource_type": "image", "type": "upload", "added": [ "boat" ], "removed": [ "angel" ] }
 ]
}

See the documentation on Notifications for more information.

Creating images from text

Note
Cloudinary supports dynamic text overlays without predefining text images. See the documentation on Adding text captions and the blog post on How to overlay text on image easily, pixel perfect and with no CSS/HTML for more details.

You can use Cloudinary to dynamically generate an image of a given textual string using the text method of the API. For example, to create an image of the text string "Hello World":

Ruby:
Copy to clipboard
Cloudinary::Uploader.text('Hello World')
PHP:
Copy to clipboard
\Cloudinary\Uploader::text('Hello World');
Python:
Copy to clipboard
cloudinary.uploader.text('Hello World')
Node.js:
Copy to clipboard
cloudinary.v2.uploader.text('Hello World', 
  function(error, result) 
  {console.log(result, error) });
Java:
Copy to clipboard
cloudinary.uploader().text("Hello World",
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
var textParams = new TextParams("Hello World");
var textResult = cloudinary.Text(textParams);

You can also optionally include various font, color and style parameters that can be specified to customize the look & feel of the text based image as follows:

  • public_id - The identifier that is used for accessing the generated image. If not specified, a unique identifier is generated by Cloudinary.
  • font_family - The name of the font family.
  • font_size - Font size in points. Default: 12.
  • font_color - Name or RGB representation of the font's color. For example: 'red', '#ff0000'. Default: 'black'.
  • font_weight - Whether to use a 'normal' or a 'bold' font. Default: 'normal'.
  • font_style - Whether to use a 'normal' or an 'italic' font. Default: 'normal'.
  • background - Name or RGB representation of the background color of the generated image. For example: 'red', '#ff0000'. Default: 'transparent'.
  • opacity - Text opacity value between 0 (invisible) and 100. Default: 100.
  • text_decoration - Set to 'underline' to define a line below the text. Default: 'none'.

For example, to create an image of the text string "Sample Name" in 12 point, black, Arial font with 90% opacity, and the Public ID of "dark_name":

Ruby:
Copy to clipboard
Cloudinary::Uploader.text("Sample Name",
  :public_id => "dark_name",
  :font_family => "Arial", 
  :font_size => 12,
  :font_color => "black",
  :opacity => 90)
PHP:
Copy to clipboard
\Cloudinary\Uploader::text("Sample Name",
  array(
    "public_id" => "dark_name",
    "font_family" => "Arial", 
    "font_size" => 12,
    "font_color" => "black", 
    "opacity" => 90));
Python:
Copy to clipboard
cloudinary.uploader.text("Sample Name",
  public_id = 'dark_name',
  font_family = 'Arial', 
  font_size = 12,
  font_color = 'black',
  opacity = 90)
Node.js:
Copy to clipboard
cloudinary.v2.uploader.text("Sample Name",
  { public_id: "dark_name",
    font_family: "Arial", 
    font_size: 12,
    font_color: "black", 
    opacity: 90 }, 
  function(error,result) { console.log(result, error) });
Java:
Copy to clipboard
cloudinary.uploader.text("Sample Name",
  ObjectUtils.asMap(
    "public_id", "dark_name",
    "font_family", "Arial",
    "font_size", 12,
    "font_color", "black",
    "opacity", "90"));
.Net:
Copy to clipboard
var textParams = new TextParams("Sample Name"){
  PublicId = "dark_name",
  FontFamily = "Arial",
  FontSize = 12,
  FontColor = "black",
  Opacity = 90};
var textResult = cloudinary.Text(textParams);

The resulting image will also include all the styling information stored as metadata, which means the resulting image can be referred to as a "text style" base for creating text overlays on the fly. See the documentation on Text style images for more information.

The API call returns a JSON response including the URLs for accessing the generated image through a CDN, the assigned Public ID and the current version of the resource.

For example:

Copy to clipboard
{
 public_id: '12355d88728f5dc6886d96847c0c7ced',
 version: '1571216138',
 width: 124, 
 height: 15,
 url: 'http://res.cloudinary.com/demo/image/upload/v1571216138/12355d88728f5dc6886d96847c0c7ced.png',
 secure_url: 'https://res.cloudinary.com/demo/image/upload/v1571216138/12355d88728f5dc6886d96847c0c7ced.png'
}