Managing individual media assets

You can display the assets in any view (Folders, Search, Collections, Moderation, etc) as a grid of square thumbnail cards (Grid View) or as an asset list (List View).

Asset card (Grid View) Asset list item (List View)

You can change between these views using the View toggle button View toggle button at the top right of the main Asset Pane.
For any asset, you can:

Operation Enables you to Details
Single-click the asset View or edit basic details in the Preview pane The Preview pane is available on the right side of the screen. If the Preview pane is closed, click the Open Preview button Preview Pane toggle button to display it.
Double-clck the asset Manage the asset Opens the Asset Management drill-down page where you can view or edit summary, metadata, and analysis data.
Click the checkmark Select one or more assets Perform any of the operations available in the displayed asset toolbar on all selected assets at once (such as delete, add tags or custom metadata, move, download or moderate).
Click the Copy URL icon Copy the asset's delivery URL Enables easy sharing of public assets.
Click the Edit icon Edit the asset Opens the Edit page where you can apply a variety of asset adjustments or generate sophisticated image or video transformations.

You can also right-click or click the 'options' icon to access many of these options.

Asset management drill-down

The asset management drill-down page enables you to:

  • View, set, or adjust Summary, Metadata, and Analysis data for a specific media asset.
  • Preview the asset with or without indications for detected elements, such as detected faces.
  • See how an image would look with a variety of pre-defined or custom transformations using the Transformation Presets bar.
  • Collaborate on the asset with other account users in the Comments Pane, including using the standard @username notation to mention (tag) other account users. When you mention a user, they receive an email with your comments and a quick link to view the comments in the Asset Management page. The Comments pane is available only for accounts with multiple users (supported for Advanced plan or higher).

Notes

  • Modifying an asset requires at least Can edit permissions. If you have a Media Library user role with Can view or Can contribute permissions for the folder where a particular asset is stored, some of the options described below will not be available to you. For details, see Folder sharing and permissions.
  • The Comments pane is currently in BETA. If you have a multi-user account, submit a support request to activate it.

You can open the asset management drill-down page by double-clicking the asset, or by clicking the Manage button Manage icon from a variety of locations, including the buttons on each asset, the Preview pane, or the Edit page.

Summary tab

Enables you to view basic details about the asset, to view or manually update the tag list, or to view or set the asset's access mode. The tags shown in this tab include both tags that were added manually and tags that were automatically added by auto-tagging add-ons, either programatically, during upload as defined by an upload preset or via the Analysis tab.

Asset Management Summary tab

Metadata tab

Enables you to view or update custom metadata for the asset.

Asset Management Metadata tab

Analysis tab

Relevant for images only. Enables you to view the results of automated AI analyses that have already been performed on the asset. Cloudinary runs some of these analyses automatically on every asset. Others require registration to an add-on. If you are not already registered for a particular add-on, you can register for the add-on's free tier and run the engine on the displayed asset directly from this pane.

Asset Management Analysis tab

All analysis data is stored with your asset and can be used as the basis for a variety of asset management features:

  • Auto-tagging - Utilizes one or more auto-tagging add-ons, each of which apply deep learning AI models to identify types of objects in your image and return the list of categories it finds. You can adjust the confidence level to view additional categories or limit the list to those with a higher confidence level. You can then mark specific categories to add them as tags on your asset, or choose the option to add all the displayed categories as tags.

  • Face and Celebrity detection - Utilizes various algorithms and AI engines to determine the number and location of faces in your image. For celebrity detection, it also indicates the names of any celebrities detected and the accuracy confidence level. Each face/celebrity detection option displays the coordinates of the faces it finds in the form of color-coded frames within the preview pane on the right. You can use the show/hide buttons for each engine to show or hide these frames. The detected faces data can be used for a number of face-detection options. For example, this data can be used to add overlays to every captured face, to blur or pixelate faces, or to apply face-detection based cropping so that you never crop out a face, and more. For the built-in face detection, you also have the option to adjust, add, or remove face coordinates (frames) and save the new face data with your image.

  • Area of interest - Enables you to define a custom-area of interest. This area will then be taken into account, or in some cases override other special areas, when Cloudinary programmatically crops, applies overlays, or performs other area-based transformations.

  • OCR - Captures text inside your images. Each phrase (line of text) that it captures is displayed in the tab and highlighted in the preview pane. Similar to face-detection, you can add overlays to cover text, blur or pixelate text, or ensure that text doesn't get cut off if your images are automatically cropped for delivery.

  • Color analysis - Gives you information about the main colors in your image. Cloudinary can use these colors to automatically add background padding to images in a color that looks good with your image. If you have access to the Image Analysis tab (premium) of the Media Library's advanced search, you can search for images based on their predominant colors. And of-course your developers can retrieve these colors to implement color-related functionality in your application.

Notes

  • The information in the Analysis tab relates to the original image. Therefore, the information in this tab is displayed only when the Original asset is selected in the Transformation Presets bar.
  • Data returned from the Analysis tab is also available to developers via API, which enables them to use it to implement additional functionality in your user-facing applications. For example, they can extract the detected text returned from the OCR add-on or retrieve the colors returned from the color analysis to implement color-related functionality in your application UI.

Transformation presets (images only)

When an image is displayed in the Management drill-down page, several transformation presets just below the asset preview pane enable you to see how the selected image would look with those transformations applied.

You can click the preset thumbnails to preview the transformation. For any displayed transformation preset (or for the original), you can see basic image details such as image resolution or file size, and you can perform operations such as opening the displayed image in a new tab, downloading it, copying the URL, or further editing the transformation in the transformation editor.

Several transformation presets are provided by default. Alternatively, you can set named transformations (maximum 15) to act as your account's transformation presets.

To set a transformation as a custom transformation preset:

  1. In the Transformation page of the Management console, select to display only named transformations.

  2. Select the named transformation you want to use as a transformation preset. Make sure the named transformation definition does not include any video-specific transformations or user-defined variables.

If you add one or more custom transformation presets, the default transformations are no longer displayed. To revert to the default transformations, open the Transformations page and select Remove from presets from all named transformations.

Note
When you preview a transformation preset in the Management drill-down page, it does not count against your transformation quota. However if you view the preset transformations outside the Media Library (open in a browser tab, download, etc.), a derived image is generated for your account and counts like any other image transformation.

Asset and transformation editing

The Edit page enables you to experiment with the various transformations available for the selected image or video using simple UI elements in the transformation editor and to view and edit asset details.

Using the transformation editor

Edit transformation UI

The most common transformations are displayed on the page. There are 3 additional links you can click to create more complex transformations:

  • More options: Set additional transformations or transformation flags.
  • Add overlay & watermark: Specify another asset in your Media Library to add as an overlay (or underlay) on the current asset, and specify transformations to apply to the selected overlay asset. You can also click the More options link within the overlay section to access additional transformations for the overlay.
  • Chain another transformation: Chaining enables you to define another set of transformations that will be applied on the result of the first set.

When you change settings on any of the transformation controls, a button is displayed on the preview prompting you to generate the derived resource and refresh the preview. In most cases, it makes sense to first set all the transformation settings you want to apply, and only then refresh the preview. When you refresh the preview, the transformation code displayed below the preview is also updated, enabling you to copy the transformation URL or the transformation code for any SDK.

A derived resource is one that is generated from the original asset based on applied transformations. It does not change the original asset, nor is it treated as a new asset in your Media Library. You can view all derived resources that were generated from a particular asset by clicking the View derived image/video button at the top of the Edit page.

Notes

  • Each time you modify a transformation and refresh the preview, the requested transformation is generated as a new 'derived resource'. Each of these derived resources is counted as part of the total number of transformations used during your billing cycle.
  • Because transformations do not impact the original asset, users with the Media Library user role can generate transformations, even if they have only Can View or Can Contribute permissions for the folder where the asset is stored.

For details on all available transformations and how they are used within delivery URLs, see the Image transformations and Video transformations guides.

Editing asset details

From the Edit page, users with a role that includes edit permissions for the asset can adjust data that is stored with your asset, including:

  • Rename the asset's public ID - The public ID is the filename used in delivery URLs. If you change a public ID of an asset that is currently in production, it will break all existing links to that asset.
  • Manually add or modify tags and metadata - Tags and metadata can be used in advanced searches to help you find relevant assets and may also be used in some complex transformations. For example, conditional transformations may apply one transformation if an asset has a specific tag or metadata value associated with it, and otherwise apply a different transformation. You can also automatically generate tags for assets in the Analysis tab of the Asset Management drill-down page, using one of the auto-tagging add-ons.
  • Add or edit face or custom coordinates. These coordinates are used to determine the area of focus for cropping, overlays, and other transformation features when the gravity parameter is set to face/faces or custom in a delivery URL.
  • Set an override quality level for a specific asset. The absolute quality level set here will be used for that asset instead of Cloudinary's auto-quality algorithm when quality is set to auto in a delivery URL.

Users with an Admin role or with Can Manage permissions for the relevant folder can also Delete the asset.

Tip
You can also perform most of the above editing options from the Asset management drill-down page.

Custom metadata

Custom metadata is comprised of field (key) and value pairs that can be stored with your assets. They are useful for searching assets based on a field value, or as a method of marking assets for a particular purpose in your end-user application.

For example, your developer can set up a "Specials" page in your web store to display all assets where the custom sale field is set to campaign-A.

This enables Media Library users from your creative, marketing, or sales teams to decide which assets get which field values, while your developers take advantage of custom metadata API methods to implement the application side.

Custom metadata types

Cloudinary supports two types of custom metadata: contextual metadata and structured metadata. The following table compares the two types:

Contextual Structured
Scope Fields are added individually to each asset. Fields are defined at the account level, and are available to all assets.
Created by Fields and values can be added by any user with write-level permissions for a particular asset. Fields are managed globally via the admin API. Any user with write-level permissions for a particular asset can add or edit the field values.
Value types All fields are unvalidated, free-text strings. Each metadata field is defined with a specific type (string, number, single or multi-select list, or date), and can optionally be set with rules to ensure that the values entered are valid. For example, a specific metadata value may be limited by the number of characters, by minimum or maximum numeric values, or by a specific date range.
Programmatic equivalent Add fields and values: context method of the Upload API. Manage fields: metadata_fields methods of the Admin API.
Set field values: The metadata, upload, explicit or update resource methods.
Benefits This metadata type gives more control and flexibility to individual account users. This metadata type enables more standardization across the organization.

Important

  • By default, only contextual metadata is available in the Media Library.
    Structured metadata is currently in BETA, and is available in the Media Library only by request.
  • Currently, only one type of metadata can be displayed in the Media Library. When structured metadata is enabled for display, the contextual metadata for assets is hidden. However, both types of metadata are permanently stored with your assets and are fully accessible via API.

Setting custom metadata values

You can set custom metadata values in the Media Library from the Preview pane, from the Metadata tab of the Asset Management drill-down, or from the Edit page (contextual metadata only) for a selected asset.

The process for setting custom metadata values differs depending on whether you are using contextual or structured metadata.

Setting contextual metadata values

The Preview pane and the Metadata tab of the Asset Management drill-down always show two suggested metadata fields: caption and alt. If you add values for these, then those fields are added to the asset's custom metadata with the value you set. You can additionally or alternatively add any other field names and values in the Custom metadata section.

Sample contextual metadata in Asset Management page

In the Edit page for a selected asset, you can add or set the metadata in a similar way, by clicking the Edit meta data link.

Contextual metadata in Edit page

Note
There is no technical difference between the suggested caption and alt fields and any other custom fields you add. If you don't need them, you can leave the suggested fields blank and add any other fields as needed. The suggested fields are just intended as a quick way for you to potentially add standard custom fields to your assets that your developers could use, for example, to display a title and description for the assets when they are displayed in your application.

Setting structured metadata values

If your account has been enabled for structured metadata, and your account administrator or a developer has defined structured metadata fields for your account using the metadata_fields method of the Admin API, you can set the field values for your assets in the Preview pane, from the Metadata tab of the Asset Management drill-down.

When working with structured metadata, the set of available fields is identical for all assets in your account.

  • Field types: Each field is predefined as one of the following types: free text field, multi-select list, single-selection list, number, or date.
  • Validation rules: Field values that can be manually entered, such as text, number, and date fields, may have been defined with validation rules, such as minimum or maximum values.
    If you enter a value that doesn't meet the validation rules, then when you click outside the field (which submits the value), an error message gives you information to help you correct the value.
  • Mandatory fields: Some fields may be defined as mandatory.
    • If an asset existed before your administrator defined the mandatory field, you are not immediately required to fill it in. However, if you click in a mandatory field and then click out of it (in essence submitting an empty value), you will receive a message that the value is mandatory.
    • Similarly, if a mandatory field has a value, and you delete it, you will be required to enter a new value. Otherwise, when you change views, the field will revert to its previous value.

sample structured metadata with errors

Searching for assets by custom metadata

To search for assets by custom metadata fields, click the Advanced Search button in the Search box pane, and in the Tags & Metadata tab, select the custom metadata fields you want to include in your search criteria under the Context or Metadata title, as appropriate.

  • If working with contextual metadata, enter the full expected value for each field you include.
  • If working with structured metadata, your searches can include value conditions such as 'equals, less than' or 'greater than' for numbers, 'contains' for text values, or 'is', 'before' or 'after' for dates.
Search by contextual metadata Contextual metadata search Search by structured metadata Structured metadata search

AND vs OR metadata search conditions

In general, when you perform an advanced search in the Media Library, if you enter multiple values for a specific search criteria, you will get results for assets that have ANY of those values, meaning these are treated as OR search conditions.For example, if you enter 2 values in a search by tag, you will get assets that have either of those tags.

Conversely, if you add more than one different search criteria, such as searching by both upload time and type, your results will include only assets that match both of those criteria, meaning these are treated as AND search conditions.

All contextual metadata for an asset is stored as a single entry for that asset while the individual fields of structured metadata are stored with your assets as separate sub-entries. Therefore:

  • If you enter multiple contextual metadata fields in a search, they are considered multiple values of a single OR search condition. In the Contextual metadata search image above, your search results would include any assets that have campaign = ABC OR discount_code = blue OR aaa = aaa.

  • If you enter multiple structured metadata fields in a search, they are considered separate AND search conditions. However, if you enter more than one value WITHIN a multi-select field when searching, those are treated as OR conditions. In the Structured metadata search image above, your search results would include only assets where Product ID is less than 12345 AND Publish Date is before Aug 1, 2019 AND Categories contains either Shoes OR Gifts.

Access modes

When working with Cloudinary's API, there are a few ways you can control who can access an asset and when. These include:

  • Storing an asset with an authenticated or private delivery type.
  • Applying the access_mode parameter
  • Applying the access_control parameter (Premium feature)

If either of the first two options above is applied on an asset, the asset's current access mode is indicated in the Media Library with an icon, but you cannot apply or modify these settings via the Media Library. They can be applied or modified only programmatically via the API. For more details, see Control access to assets during upload and Media access control on delivery.

The access_control option can be set programmatically via the API or via the Media Library.

Setting access control from the Media Library

If your account is enabled for the access_control option (available to accounts with a Custom plan upon request), you can change any asset's access mode between Public and Restricted directly from the Media Library.

Setting an asset as Restricted means that people can only view that asset outside the Media Library if they have both the asset URL and an authentication token, except during an optional time-limited date range when the asset is defined as publicly accessible.

Access control settings dialog box

Time-limited restricted access can be useful if you have an image or video that's intended to be used for a special campaign or that shows a new product design, and it's imperative that the asset will not be shared outside the organization prior to an official launch date. Or conversely, you may have assets that you no longer want the public to be able to view or share after the content is obsolete.

When working with the access_control option, you can change assets from public to restricted, and add or change the time-limited access dates or times without changing the asset's URL in any way. This means that your developers don't need to change the URLs in their code when the access settings for that asset change.

To view or modify access control settings:

After the asset_control feature is enabled for your account, you can open the access control settings dialog box (shown above) by clicking the Public Public access control / Restricted Restricted access control access control button in one of the following locations:

From the dialog box that opens, you can view or change the access mode between public and restricted, or adjust the time-limited access for restricted assets.

Uploading with access control

If you want to set the same access control settings for a set of assets you are uploading to the Media Library, you (or an account administrator) can apply the required access control settings in the Upload Preset(s) you are using as your default Media Library upload presets.

Alternatively, when you upload using the Media Library upload widget, you may be able to select an Upload Preset that has been set to upload with restricted access control settings.

Note
By default, the Upload Presets option is not available in the Advanced options of the Media Library Upload Widget. If it is not available in your account's upload widget, your account administrator can submit a support request to activate it.

Authentication tokens for access control

An authentication token is a special type of validation for ensuring that a person requesting a URL is allowed to access it. This token may take the form of:

  • A generated query parameter token added to the delivery URL
  • A specially defined cookie downloaded to the user's device, for verification when that user requests the URL

If you need to allow someone access to a restricted asset via a URL, outside the time range that an asset is set as public, you will need to provide that person with the relevant authentication token. You should work with your Cloudinary account administrator or developers to generate and distribute the required token.

For details on these token methods, see Authenticated access to media assets.