Cloudinary Programmable Media glossary

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!

Account settings

A set of global options that control the way your account (or the selected sub-account) behaves. These options can be set only by users with a master admin or admin role. Access the settings via the cog icon at the top right of your console.

Learn more: Recommended settings for initial developer setup

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

Add-on

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 account. Your API key (and cloud name) are passed in a variety of operations to identify your account. Cloudinary users with admin permissions can view and copy these values from the Account Details section of your Cloudinary Dashboard.

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: Create and set up your account

See also: Cloud name

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 account, 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 account, 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 account (or sub-account). Your cloud name is included in all delivery URLs and is specified in a variety of operations, both frontend and backend, to identify the account being referenced.

You define your cloud name as part of creating your account or sub-account and in most cases this name is never changed.

Important
Changing your account or sub-account cloud name after you have more than 1000 assets stored in your account requires customer support involvement, will require a variety of changes in your application code, and will invalidate all cached derived assets.

Learn more: Create and set up your account

See also: API key and secret

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 Media Library UI.

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

See also: Structured metadata | Tags | Conditional transformation | User-defined variable

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

See also: Derived asset | Incoming transformation | Notification URL | Transformation

Fetch

A method of delivering an image directly from a specified remote URL. (Not supported for videos.)

Learn more: Fetch remote images

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

Learn more: Incoming transformations | Transformation URL API reference

See also: Derived asset | Eager transformation | Transformation

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 a global (default) notification URL and/or you can 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 | Adding overlays on videos

See also: Gravity | Underlay

Public ID

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

You can change asset Public IDs if needed (they are not immutable), but keep in mind that changing the public ID value can break asset delivery URLs in production.

Public IDs for media assets do not include file extensions. (Raw asset public IDs do include file extensions.)

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

See also: Eager transformation | Named transformation

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 account administrator can define at the account/sub-account level. The defined fields are added to all assets in the account. Once these fields are defined, values can be set for them programmatically or in the Media Library. 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 reference | Structured metadata field management UI

See also: Contextual metadata | Tags

Tags

One of three types of metadata that can be stored with your assets. Tags are individual values that can be assigned to specific assets. Tags can be manually specified in the Media Library UI or assigned to assets programmatically using the upload, explicit or tags methods of the Upload API. Tags can also be automatically generated based on detected objects in the image or video using any of several available auto-tagging add-ons.

Learn more: Upload API reference

See also: Contextual metadata | Structured metadata

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

Upload preset

A set of asset upload options you can define and reference instead of specifying those options in each upload call. You can define and manage your upload presets programmatically or in the Upload settings page of the Cloudinary console.

Learn more: Upload presets | Admin API reference: upload_presets method

Upload Widget

An interactive user interface that you can embed in your website or application with a few lines of JavaScript code, enabling users to upload files from a variety of sources via your website or application.

Learn more: Upload Widget | Upload Widget API reference

User-defined variable

A variable defined within the scope of a transformation, that enables keeping value assignment separate from transformation definition.

Learn more: User-defined variables for images | User-defined variables for videos

Video Player

The Cloudinary Video Player is a JavaScript-based HTML5 video player bundled with many valuable customization and integration capabilities. It's fully responsive and is integrated with Cloudinary's video delivery and transformation solution.

Learn more: Cloudinary Video Player | Video Player API reference

✔️ Feedback sent!

Rate this page: