Programmable Media

Programmable Media glossary

Last updated: Oct-29-2024

What's an 'eager transformation'? What's an 'upload preset'? What is 'structured metadata'?

Use this glossary to find quick definitions of the terms and concepts developers should be familiar with to get the most out of Cloudinary Programmable Media.

Anything missing?

Is there a term you were looking for that's not here? Use the Rate this page option to open our feedback form and let us know what's missing, what you liked, or any other suggestions you have!

Action parameter

A transformation parameter that performs a specific transformation operation on the asset.

Learn more: Parameter types | Transformation URL API reference

See also: Transformation | Qualifier parameter

Specific functionality that extends Cloudinary's built-in capabilities. Some add-ons are based on advanced Cloudinary-developed functionality that involves complex media processing. Other add-ons provide special functionality from a variety of vision and media processing partners.

Cloudinary provides add-ons in a number of areas, including auto-tagging, special transformations, asset protection and asset analysis.

You register separately for each add-on you want to use by selecting a free or an appropriate paid tier.

Learn more: Add-ons

API key and secret

Unique auto-generated values that work together to identify and protect your product environment. Your API key (and cloud name) are passed in a variety of operations to identify your product environment. Cloudinary users with admin permissions can view and copy these values from the API Keys page of the Cloudinary Console Settings.

Your API secret can be configured in server-side applications in order to generate signatures and enable authenticated operations. Your API secret should never be exposed in client-side code or in any other way outside your organization.

Learn more: API keys

See also: Cloud name

Asset ID

An automatically generated and immutable unique identifier for each asset stored in Cloudinary.

Asset ID values are returned in many API and webhook responses and can be passed as parameters for some APIs as an alternative way to reference assets instead of using resource_type, type, and public_id together to uniquely identify an asset.

Auto-upload

A method of delivering a media file from a remote location and simultaneously uploading a copy of that file to a pre-specified (mapped) folder in your Cloudinary product environment, if it doesn't already exist.

This option is sometimes known as 'lazy uploading', and is often used as a method of migrating assets from another storage location to a Cloudinary product environment, ensuring that only assets that you are actually delivering through Cloudinary get uploaded, and minimizing the code changes you need to make in an existing app to get Cloudinary up and running.

Learn more: Auto-upload remote files | Add upload capabilities

See also: Fetch

Chained transformation

Multiple transformations grouped together as part of a single delivery request, e.g., crop an image and then add a border. You can combine single transformations to create a chained transformation when you want to perform additional transformations on the result of another transformation request.

Learn more: Chained transformations | Transformation URL syntax

See also: Transformation | Named transformation

Cloud name

A cloud name is a unique identifier name for your Cloudinary product environment. By default, a unique random cloud name is generated for each new product environment.

Your cloud name is included in all delivery URLs and is used in a variety of operations, both frontend and backend, to identify the product environment being referenced. Because your cloud name is a visible part of your delivery URLs and can impact SEO, it's recommended to change your cloud name to a meaningful descriptor as part of your account or new product environment setup.

The cloud name is a case-insensitive string comprised of between 2-128 alphanumeric and hyphen characters, starting with a letter. Note that cloud names must be unique across all Cloudinary accounts.

Important

Changing your product environment cloud name after you have more than 1000 assets stored in your product environment requires customer support involvement, will require a variety of changes in your application code, and will invalidate all cached derived assets. Thus you should define your cloud name as part of your initial setup, and in most cases, should not modify it afterwards.

Learn more: API keys

See also: API key and secret

Cloudinary Console settings

A set of options that control the way your account and active product environment behave.

The account-level settings are global and apply to all product environments.
The product-environment-level settings apply to the currently active product environment.

These options can be set only by users with a Master admin or admin role. Access the Cloudinary Console Settings via the cog icon on the bottom-left of your Cloudinary Console.

Learn more: Recommended settings for initial developer setup

Conditional transformation

An if-then style expression within a transformation URL that instructs Cloudinary to apply a transformation only if a specified condition is met.

Learn more: Conditional image transformations | Conditional video transformations

Contextual metadata

One of three types of metadata that can be stored with your assets. Contextual metadata is a custom key-value pair that you can assign to individual assets either programmatically or in the Cloudinary Console.

Once defined, contextual metadata can be referenced in your application, for example to find assets that meet relevant criteria and for generating transformations based on the value of a particular contextual metadata key, using user-defined variables and/or conditional transformations.

Learn more: Upload API reference

Delivery URL

The HTTP or HTTPS URL used to access your Cloudinary media assets. The URL contains your cloud name and the public ID of the requested asset plus any optional transformation parameters for customizing and optimizing your assets.

When the URL is first accessed, a derived media file is created on the fly and delivered to your user. The derived file is also cached on the CDN and is immediately available to all subsequent users requesting the same asset.

Learn more: Transformation URL syntax | URLs and endpoints

See also: Invalidation

Derived asset

A new media file that Cloudinary generates by applying all the transformation parameters in a transformation URL to a specified asset from your product environment. Derived assets are either generated eagerly or generated on the fly the first time the transformation URL is requested. Derived assets are cached both on Cloudinary and on CDNs to ensure fast delivery to users each time the corresponding transformation URL is requested.

See also: Eager transformations | Transformation

Eager transformation

A transformation URL that's processed either as part of asset upload or on an existing asset in your Cloudinary product environment, so that the derived asset is fully generated before the URL is delivered in production.

Learn more: Eager transformations | Eager transformation notifications | Transformation URL API reference

Fetch

A method of delivering an image or video directly from a specified remote URL.

Learn more: Fetch remote media files

See also: Auto-upload

Gravity

A qualifier parameter that tells Cloudinary which point or area(s) within an asset to apply the requested transformation action.

For crop operations, gravity indicates which point or area is most important to keep when it is determining which parts of an image or video to crop out. For layer operations, gravity indicates where to apply the layer.

The gravity may relate to a specific compass direction (north, southeast, center, etc) or an automatically detected area of the asset (such as a face, specified object/category, text, or the most prominent subject(s)).

Learn more: Gravity positions for crops | Layer placement | Transformation reference: gravity parameter

See also: Qualifier parameter

Incoming transformation

A set of (one or more) transformation parameters that are applied to a file during the upload process. Only the generated file, after the transformation parameters were applied, is stored in the Cloudinary product environment; the originally uploaded file is discarded.

Incoming transformations are commonly used for user-generated content to limit the size, resolution or duration (for videos) of files uploaded to your product environment.

Learn more: Incoming transformations | Transformation URL API reference

Invalidation

An instruction to the CDN to remove all cached copies of an old asset or a specified derived asset URL, so that the next request for the asset will pull the latest copy from your Cloudinary storage, or will return an error if the asset no longer exists.

Learn more: Invalidating cached media assets

See also: Delivery URL

Named transformation

A pre-defined set of transformation parameters that has been assigned a custom name. This enables you to easily reference and reuse them, shorten URLs for complex transformations, hide the details of your transformation in your delivered URLs, and more. You can make named transformations more flexible and reusable by defining them with user-defined variables, such that parameter values can be passed from outside the named transformation.

You can define named transformations programmatically or using the Transformations UI.

Learn more: Named transformations | Named transformation with user-defined variable

See also: User-defined variable

Notification URL

A webhook URL that you provide where Cloudinary can send updates and data relating to operations you perform.

You can define one global notification URL to receive updates for all supported operations or multiple notification URLs to receive updates for specified types of operations at different locations.

You can also specify notification URLs for use with specific operations. In some cases, you can specify two different notification URLs in the same request in order to get updates relating to the main operation (such as upload) as well as data relating to asynchronous operations specified in the same request, such as eager transformations, which may complete at a different time.

Learn more: Notifications

See also: Eager transformation

Overlay

A transformation parameter that causes the specified asset to be applied/embedded as a layer over a specified base asset. You can overlay images on images, images on videos, and videos on videos. The placement of the overlay is specified using the gravity qualifier. The placement can be an exact location or can be automatically determined based on detected objects or other elements in the base image.

Learn more: Placing layers on images | Placing layers on videos

See also: Gravity | Underlay

Product environment

A product environment (previously known as a sub-account) is an entity within your account that includes an asset repository, some product environment-specific settings, and other elements that are stored in your product environment and help you manage it, such as upload presets, named transformations, and more.

A product environment can represent a production or staging environment, different organizations, products, or geographic sites that you want to manage separately within a single Cloudinary account.

You can manage the elements related to a product environment via the Cloudinary Console or programmatically using the Admin API.

For more details, see Cloudinary Console.

Public ID

An identifier for an asset stored in Cloudinary. You use the public ID to refer to assets in your delivery URLs and API calls. The public ID is defined when an asset is uploaded to your product environment.

Depending on options you set, the public ID value for an asset can be randomly generated characters, a hard-coded value specified during upload, or may be automatically set based on the original filename of the asset that you upload.
Public ID values can include non-English characters, periods (.), forward slashes (/), underscores (_), hyphens (-).
Public ID values for media assets (image, video, and audio files) do not include file extensions. Public ID values for non-media (raw) assets do include file extensions.
You can change asset public IDs if needed (they are not immutable), but keep in mind that changing public ID values can break asset delivery URLs in production.

While it's a best practice to keep your public IDs fully unique across your product environment, the public ID is only required unique within a specific resource_type and type (delivery type). For example, it's technically possible for both an image and a video to have the same public ID value, or an asset of type upload and one of type authenticated to have the same public ID.

In contrast, asset IDs are completely unique and immutable asset identifiers.

Learn more: Public IDs in uploads | Transformation syntax

Qualifier parameter

A transformation parameter that does not perform an action on its own, but rather alters (qualifies) the default behavior or otherwise adjusts the outcome of its corresponding action parameter.

Learn more: Parameter types | Transformation URL API reference

See also: Action parameter | Transformation

Raw asset

Any file that Cloudinary doesn't identify as an image or video asset type is treated as a 'raw' file. Raw files are stored as-is when uploaded to Cloudinary and you can't perform any transformations on them. However, you can deliver your raw assets through a dynamic CDN URL in the same way you deliver image and video assets. Commonly uploaded raw files include custom fonts, subtitle files (vtt, srt), or any other file type you may want to deliver for download via a URL.

Tip

Audio files are identified as video type and PDFs are identified as image type, so these asset types are not considered 'raw'.

Strict transformation

A setting that blocks users from dynamically generating transformations on the assets in your product environment or limits dynamic transformation generation to a pre-defined set of transformations. All other transformations must be generated eagerly or via an authenticated API request.

This prevents unexpected transformations from being charged to your account.

Learn more: Strict transformations

Structured metadata

One of three types of metadata that can be stored with your assets. Structured metadata fields are a set of custom fields that an administrator can define at the product environment level. The defined fields are added to all assets in the product environment. Once these fields are defined, values can be set for them programmatically or in the Cloudinary Console. This enables better searchability of your assets as well as opening up a variety of options for programmatic operations that can be performed based on the metadata values.

Learn more: Structured metadata API | Structured metadata field management UI

See also: Contextual metadata | Tags

Transformation

A set of (one or more) parameters that, when applied in a Cloudinary URL, programmatically modify a specified original media file, resulting in a newly generated (derived) media file based on the original.

Transformations may perform any combination of operations, including resizing, adding layers, applying effects, changing formats, optimizing file size, adjusting quality, and more.

Learn more: Image transformations | Video transformations | Transformation URL API reference

See also: Action parameter | Qualifier parameter

Transformation counts

Your account's monthly pricing plan is in part dependent on the total number of transformations performed during a 30-day cycle. Transformation counts are impacted by each processing of an asset. The majority of these occur when Cloudinary generates a new 'derived' asset from an original asset, based on a transformation URL (regardless of the complexity of the transformation). Most image transformations are counted as a single transformation. Video transformation counts depend on the length and definition level. Additionally, some processing-heavy transformation and asset analysis operations have special counting rules.

Learn more: How are transformations counted?

Underlay

A transformation parameter that causes the specified image to be applied/embedded as a layer under (behind) the specified base asset. Underlays can be useful when the base asset has transparent elements.

Learn more: Underlays

See also: Overlay

✔️ Feedback sent!

✖️

Error

Unfortunately there's been an error sending your feedback.

Rate this page: