Managing assets

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

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

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

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.

Deleting assets

There are a number of ways to delete assets from Cloudinary:

Programmatically:

• 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_resources_by_prefix, 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.

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. 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 old_name to new_name:

For complete details on all available options, see the rename method.

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

For example:

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.