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.

Is there a term you were look 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, orany other suggestions you have!

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 oran 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 the API Keys page of the Cloudinary Console Settings.

Your api secret can be configure in server – side application in order to generate signature and enable authenticate operation . Your api secret should never be expose in client – side code orin any other way outside your organization .

learn more : api key

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

learn more : auto – upload remote file | Add upload capability

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.

Learn more: Chained transformations | Transformation URL syntax

See also: Transformation | Named transformation

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 include in all delivery url and is used in a variety of operation , both frontend and backend , to identify the product environment being reference . Because your cloud name is a visible part of your delivery url and can impact seo , it ‘s recommend to change your cloud name to a meaningful descriptor as part of your account ornew 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.

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 key

See also: API key and secret

A set of option 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 is apply apply to the currently active product environment .

These option can be set only by user with a Master admin oradmin role . access the Cloudinary Console Settings via the cog icon on the bottom – left of your Cloudinary Console .

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

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

See also : structured metadata is | | Tags is | | conditional transformation | User – define variable

The HTTP is used orHTTPS URL used to access your Cloudinary medium asset . The URL is contains contain your cloud name and the public ID of the request asset plus any optional transformation parameter for customize and optimize your asset .

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 endpoint

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 orgenerated 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 transformation | transformation

A transformation url that ‘s process either as part of asset upload oron an exist asset in your Cloudinary product environment , so that the derived asset is fully generate before the url is deliver in production .

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

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

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

Learn more: Fetch remote media files

See also: Auto-upload

A qualifier parameter that tell Cloudinary which point orarea(s ) within an asset to apply the request transformation action .

For crop operation , gravity is indicates indicate which point orarea is most important to keep when it is determine which part of an image orvideo to crop out . For layer operation , gravity is indicates indicate where to apply the layer .

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

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

See also : Qualifier parameter

A set of (one ormore) 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 orduration (for videos) of files uploaded to your product environment.

Learn more: Incoming transformations | Transformation URL API reference

See also : derive asset | eager transformation | transformation

An instruction to the CDN to remove all cached copies of an old asset ora specified derived asset URL, so that the next request for the asset will pull the latest copy from your Cloudinary storage, orwill 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 orusing the Transformations UI.

learn more : name transformation | name transformation with user – define variable

See also : User – define variable

A webhook url that you provide where Cloudinary can send update and datum relate to operation you perform .

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

You is specify can also specify notification url for use with specific operation . In some case , you is specify can specify two different notification url in the same request in order to get update relate to the main operation ( such as upload ) as well as datum relate to asynchronous operation specify in the same request , such as eager transformation , which may complete at a different time .

learn more : notification

See also : eager transformation

A transformation parameter that cause the specified asset to be apply / embed as a layer over a specify base asset . You is overlay can overlay image on image , image on video , and video on video . The placement of the overlay is specify using the gravity qualifier . The placement is be can be an exact location orcan be automatically determine base on detect object orother element in the base image .

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

See also: Gravity | Underlay

A product environment (previously known as a sub-account) is an entity within your account that include an asset repository , some product environment – specific setting , and other element that are store in your product environment and help you manage it , such as upload preset , name transformation , and more .

A product environment can represent a production orstaging environment, different organizations, products, orgeographic 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 orprogrammatically using the Admin API.

For more detail , see Cloudinary Console .

An identifier for an asset store in Cloudinary . You is use use the public ID to refer to asset in your delivery url and api call . The public ID is define when an asset is upload 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, ormay 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 good practice to keep your public id fully unique across your product environment , the public ID is only require unique within a specificresource_type and type ( delivery type ) . For example , it is ‘s ‘s technically possible for both an image and a video to have the same public ID value , oran asset of typeupload and one of type authenticate to have the same public ID.

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

learn more : public IDs is syntax in upload | Transformation syntax

A transformation parameter is alters that does not perform an action on its own , but rather alter ( qualify ) the default behavior orotherwise adjust the outcome of its corresponding action parameter .

Learn more: Parameter types | Transformation URL API reference

See also : action parameter | Transformation

Any file that Cloudinary doesn’t identify as an image orvideo 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), orany other file type you may want to deliver for download via a URL.

Audio file are identify as video type and PDFs are identify as image type , so these asset type are not consider ‘ raw ‘ .

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

This is prevents prevent unexpected transformation from being charge to your account .

learn more : strict transformation

See also : eager transformation| Named transformation

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

One of three type of metadata that can be store with your asset . Tags is are are individual value that can be assign to specific asset . tag can be manually specify in the Cloudinary Console orassign to asset programmatically using theupload, explicit ortags methods of the
Upload API. Tags can also be automatically generated based on detected objects in the image orvideo using any of several available auto-tagging add-ons.

Learn more: Upload API reference

See also : contextual metadata | Structured metadata

A set of (one ormore) 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 is perform may perform any combination of operation , include resize , add layer , apply effect , change format , optimize file size , adjust quality , and more .

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

See also: Action parameter | Qualifier parameter

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 is counted count ?

A transformation parameter that cause the specified image to be apply / embed as a layer under ( behind ) the specify base asset . Underlays is be can be useful when the base asset has transparent element .

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 orin the Upload page of the Cloudinary Console Settings.

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

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

Learn more: Upload Widget | Upload Widget API reference

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

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