Last updated: Nov-27-2022
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.
Updating already uploaded assets
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 product environment 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 Transformation URL API Reference 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.
explicit method can also be used in client-side code, but it requires a signature to be generated on the server-side. See the Explicit method in the reference guide for all available parameters.
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
- 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).
explicit API method also requires specifying the
type of the resource:
authenticated. For example, the following method will explicitly generate two transformations for the already uploaded JPG
private image named
- Scale to a width of 200 pixels.
- Crop to a width of 360 pixels and a height of 200 pixels with north gravity.
There are a number of ways to delete assets from Cloudinary:
- Use the Destroy method of the Upload API to delete a single asset. This method requires a signature to be generated on the server side.
- Use the Delete resources method of the Admin API to delete multiple assets. You can specify a set of assets to be deleted using
delete_all_resources(optionally giving a type) or Delete resources by tag. These methods require your API key and secret, so are not suitable for use in client-side code.
- Delete client-side uploaded assets using a delete token returned in the upload response that is valid for 10 minutes.
Via the Media Library:
- Select and delete assets in the Media Library.
- Delete folders and their contents in the Media Library.
- Bulk delete several assets at a time using set criteria from your Console Settings.
When you delete assets, they are immediately and permanently removed from your cloud storage. However, assets and transformed assets already downloaded by visitors to your website, might still be accessible through cached copies on the CDN if they are not invalidated. From within the Media Library, an
invalidate request is automatically included whenever you delete, rename, or overwrite media assets.
If using the Destroy or Delete resources methods, you need to set the
invalidate parameter to
true to invalidate 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. There are also a number of other important considerations when using the invalidate functionality.
You can restore deleted assets from backup if you have enabled automatic backup for your product environment.
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. 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.
For example, renaming an image with the Public ID of
For complete details on all available options, see the rename method.
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. A tag is a short name (up to 255 characters) that you can dynamically use (no need to predefine tags). Each asset can be assigned up to 1000 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:
You can also use our API or Cloudinary 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":
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":
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 Cloudinary Console UI. These changes are sent as webhook notifications to the Notification URL specified in the Upload page of your Console 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:
See the documentation on Notifications for more information.
Creating images from text
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":
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":
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.
Invalidating cached media assets on the CDN
Even after you delete, rename, or overwrite an image or video asset in your Cloudinary storage, any delivered versions of the asset, with or without transformations, can remain cached on CDN servers for up to 30 days.
To prevent the old asset being delivered, 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 enabled for your account (not supported by default).
The assets and their derived versions that will actually be invalidated during an invalidate request depend on the value set for the global Invalidate versioned URLs option in the Upload page of the Console Settings, and whether the public ID of a particular URL includes slashes. The table below summarizes these considerations.
|Invalidate versioned URLs||Disabled (default)||Enabled|
|Public ID does not include slashes||Only URLs without a version are invalidated. For example:
||Only URLs with the most recent version are invalidated. For example:
|Public ID includes slashes||Only URLs delivered with the /v1/ component are invalidated. For example:
When using SDKs to generate URLs, the SDK automatically adds the /v1/ component for assets whose public IDs have slashes.
If you need to invalidate images or videos whose public IDs have slashes and were delivered without the
|Only URLs with the most recent version are invalidated. For example:
- By default, signed URLs (with or without versions) are not invalidated. If you need to invalidate signed URLs submit a service request.
- It usually takes between a few seconds and a few minutes 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.
- If you continue to see an invalidated image or video in your browser, it may be saved in your browser cache. Try opening an incognito window or clearing your browser cache.