Last updated: Aug-02-2023
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.
- Action parameter
- API key and secret
- Asset ID
- Chained transformation
- Cloud name
- Cloudinary Console settings
- Conditional transformation
- Contextual metadata
- Delivery URL
- Derived asset
- Eager transformation
- Incoming transformation
- Named transformation
- Notification URL
- Product environment
- Public ID
- Qualifier parameter
- Raw asset
- Strict transformation
- Structured metadata
- Transformation counts
- Upload preset
- Upload Widget
- User-defined variable
- Video Player
A transformation parameter that performs a specific transformation operation on the asset.
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
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 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
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
type, and public_id together to uniquely identify an asset.
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.
See also: Fetch
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.
A cloud name is a unique identifier name for your Cloudinary product environment. By default, a unqiue 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.
Learn more: Create and set up your account
See also: API key and secret
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
An if-then style expression within a transformation URL that instructs Cloudinary to apply a transformation only if a specified condition is met.
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
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.
See also: Invalidation
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.
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.
A method of delivering an image or video directly from a specified remote URL.
Learn more: Fetch remote media files
See also: Auto-upload
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)).
See also: Qualifier parameter
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.
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
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.
See also: User-defined variable
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
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.
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.
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
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
In contrast, asset IDs are completely unique and immutable asset identifiers.
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.
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.
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
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.
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 Cloudinary Console or assigned to assets programmatically using the
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
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.
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?
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
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 page of the Cloudinary Console Settings.
A variable defined within the scope of a transformation, that enables keeping value assignment separate from transformation definition.