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.

Additionaly, the Cloudinary Media Explorer bridges the gap for you between efficient asset management in code and an online user interface (UI) to your asset library.

Media Explorer

The Media Explorer is a tool for you to easily view, browse and search the assets in your media repository, and is focused on helping you to learn and onboard quickly to easily integrate Cloudinary functionality within your own code. The explorer also helps you debug and troubleshoot your code, and provides a UI that is fully visualized and reflects a developer work space.

The interface provides a robust view to easily navigate through folders to find the assets you need, perform a search, upload new images, videos, audio, or other files in virtually any format, and select multiple assets to perform bulk operations such as delete. Hovering over a specific asset displays a thumbnail preview of the asset, and you can do an advanced search for assets by clicking on the blue icon in the search bar at the top right of the page. Double-clicking on an asset opens the asset view with an overview of the properties of the asset, and enables updating the metadata, tags and public ID of the asset.

Inspect mode

The explorer provides an Inspect Mode to help you learn and onboard to Cloudinary, and see the code snippet for replicating any actions made within the UI. This snippet can then be copied to your own code to provide the same functionality programmatically. The snippet is generated for each of the Cloudinary SDKs, which are displayed on separate tabs in the code preview pane. For example in the image above, the code preview pane shows the code for the two most recent actions performed in the UI, one to rename an asset, and the other to update an asset with a new tag.

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.

Delete assets video tutorial

Watch this video tutorial to learn more about deleting assets with a deep dive into the Node.js SDK methods.

Tutorial contents

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.

Relating assets

Cloudinary's related assets functionality allows users to establish relationships between assets based on specific organizational needs and criteria. By manually configuring these associations, users can create meaningful connections between assets within their library, making it easier for other users to discover and locate similar or associated assets.

You can relate any of the assets in your product environment to each other to create groupings or bundles. Here are some use cases where you might need to use related assets:

• Relate videos and images of the same product.
• Relate a video with its peripheral assets (transcript, poster, etc).
• Relate an image with other images created using that image.
• Relate images of a product with companion assets (e.g. manual, warranty, etc).
• Relate similar product shots but from different angles or for different purposes.
• Relate logo images and other marketing assets with a 'Brand Guidelines' PDF.
• Relate an image with other assets that use it as an overlay.

Adding related assets

The add_related_assets method allows you to indicate that a specified asset is logically related to other assets in some way. This is a bidirectional process, meaning that the asset will also be added as a related_asset to all the other assets specified. The relation is also a one to many relationship, where the asset is related to all the assets specified, but those assets are not also related to each other.

The add_related_assets method accepts the following parameters:

• public_id or asset_id - Either the public ID of the asset, or its asset ID.
• assets_to_relate - Relates the asset to all the other assets specified in this array of up to 10 assets, specified by either resource_type/type/public_id or by asset_id.
  For example: ["image/upload/dog","video/authenticated/cat"] or ["e12345b0efc00c0fcf","f12345a5c7c00c0f12"]

Examples

1. Relate the image with a public ID of 'dog' to the assets with public IDs of 'image/authenticated/dog_license' and 'raw/upload/dog_subtitles.srt':

2. Relate the asset with an asset ID of 'c789c1234bbb0e' to the assets with IDs of 'f12345a5c789c' and 'bbb0efc00c0f12':

Deleting related assets

The delete_related_assets method allows you to unrelate an asset from other assets. This is a bidirectional process, meaning that the asset will also be removed as a related_asset from all the other assets specified.

The delete_related_assets method accepts the following parameters:

• public_id or asset_id - Either the public ID of the asset, or its asset ID.
• assets_to_unrelate - Unelates the asset from all the other assets specified in this array of assets, specified by either resource_type/type/public_id or by asset_id.
  For example: ["image/upload/dog","video/authenticated/cat"] or ["e12345b0efc00c0fcf","f12345a5c7c00c0f12"]

Examples

1. Unrelate the asset with a public ID of 'dog' from the assets with public IDs of 'raw/upload/dog_subtitles.srt' and 'video/authenticated/animals':

2. Unrelate the asset with a asset ID of 'c789c1234bbb0e' from the assets with IDs of 'a5c789c5c745a' and 'a1623c3b234a':

Listing related assets

The list of related assets is stored with the asset and is returned in the response when calling the Get the details of a single resource method with the related parameter set to true.

For example, to get the details of an image with the public ID of 'red_shoe' and include the list of related assets:

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.