Video Transformations

Image & Video APIs

Last updated: Jun-03-2026

Cloudinary's dynamic URL transformations enable you to programmatically generate multiple variations of your high quality original videos on the fly, without the need for graphic designers and fancy editing tools.

You can build these URLs manually in your code, or take advantage of Cloudinary's SDKs, which enable you to write your transformation code using intuitive syntax designed for your preferred programming language or framework and let the SDK automatically build these URLs for you.

Important

Your account's pricing plan is in part dependent on the total number of transformation operations performed during a billing cycle. These are primarily counted when Cloudinary generates a new 'derived asset' from an asset based on a transformation URL. For complete details, see How are transformations counted?
If you have many subscribers or you deliver long videos (for example, over 100,000 subscribers or videos longer than 12 minutes), you may be responsible to obtain a 3rd party license as per the terms of the MPEG LA license for AVC/H.264. This obligation is not in any way related to Cloudinary and applies equally to you whether or not the videos you deliver are delivered via Cloudinary's service.

Here are just a few examples of some popular use cases that you can accomplish on the fly by combining Cloudinary transformations:

Pad with blurred background
c_pad,b_blurred:400:15

Reversed video and progress bar effects
e_reverse/e_progressbar:bar:green

Add image and text layers
l_.../l_text:

See also: Image Transformations

Overview

Cloudinary allows you to easily transform your videos on the fly to any required format, style and dimension, and apply effects and other visual enhancements. You can also optimize your videos to deliver them with minimal file size alongside high visual quality for an improved user experience and minimal bandwidth. You can do all of this by implementing dynamic video transformation and delivery URLs.

Multiple users can then stream the transformed video even while it is being encoded and delivered via CDN. You can also deliver videos that were encoded in advance with eager or explicit transformations. Furthermore, Cloudinary supports HTTP progressive download for media players capable of progressive download playback.

With video transformations, you can:

Deliver videos using the video format that fits your needs.
Resize and crop your videos to the required dimensions using different scaling and cropping techniques, or use our smart auto-gravity to ensure the main subjects remain in focus throughout a cropped video.
Generate a new video by layering other videos, images or text on your base video.
Apply a variety of effects, filters, and other enhancements to help your video achieve the desired impact.
And much more.... See Video transformation types for a listing of many different types of transformations you can apply with links to details.

Quick example

Below you can see the transformation URL and the corresponding SDK code for generating a video with several transformation parameters applied. This transformation generates and delivers a skiing video where a copy of the original video is appended to the end of the original, but in reverse, and then yet another copy is appended playing forward again, but with a slow motion (negative acceleration) effect. This 3-part video's radius is set to max in order to give a telescope-like effect. Finally, the resulting video is scaled down to a width of 400 pixels before being delivered.

Tip

You can use the Media Library to preview and manage your transformations:

Quickly test transformations in the Media Library by opening the image URL and manually adding transformations before implementing them programmatically.
Manage derived assets from the Derived Assets tab in an asset's Manage page.

Transformation URL syntax

Your Cloudinary media assets are accessed using simple delivery HTTP or HTTPS URLs, which are then delivered to users via a worldwide fast CDN. The URL contains the public ID of the requested asset plus any optional transformation parameters. The public ID is the unique identifier of the asset and is either defined when uploading the asset to Cloudinary, or automatically assigned by Cloudinary (see Uploading Assets for more details on the various options for specifying the public ID).

Generating transformation URLs with Cloudinary SDKs

Cloudinary's SDKs automatically build the transformation URL for you. They allow you to continue working in your preferred developer framework and also provide helper methods to simplify building video tags and video transformation URLs.

Tip

You can also create your transformation URLs using the Transformation Builder. Alternatively, you can take one of our transformations from the Image Home Transformations Gallery as a starting point and then further modify it in the Transformation Builder to fit your needs. The Transformation Builder generates the URL and SDK code for the transformation you define so that you can copy it in the language you require.

Transformation URL structure

The default Cloudinary asset delivery URL has the following structure:

https://res.cloudinary.com/<cloud_name>/<asset_type>/<delivery_type>/<transformations>/<version>/<public_id>.<extension>

element	description
cloud_name	A unique public identifier for your product environment, used for URL building and API access. Note: Paid customers on the Advanced plan or higher can request to use a private CDN or custom delivery hostname (CNAME) to customize the domain name used for your delivery URLs.
asset_type	The type of asset to deliver. Valid values: `image`, `video`, or `raw`. The `image` type includes still image and photo formats, animated images, PDFs, layered files, such as TIFF and PSD, and others. The `video` type includes video and audio files. The `raw` type includes any file uploaded to Cloudinary that does not fit in one of the above categories. In general, transformations cannot be performed on `raw` assets, but they can be delivered as-is for download purposes, or in some cases, they may be used in conjunction with your image or video transformations.
delivery_type	The storage or delivery type. For details on all possible types, see Delivery types.
transformations	Optional. One or more comma-separated transformation parameters in a single URL component, or a set of chained transformations in multiple URL components (separated by slashes). When the transformation URL is first accessed, the 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.
version	Optional. You can include the version in your delivery URL to bypass the cached version on the CDN and force delivery of the latest asset (in the case that an asset has been overwritten with a newer file). For simplicity, the version component is generally not included in the example URLs on this page. For details, see Asset versions.
public_id	The unique identifier of the asset, including the folder structure if relevant.
extension	Optional. The file extension of the requested delivery format for the asset. Default: The originally uploaded format or the format determined by f_auto, when used.

In the most general case of simply delivering videos that were uploaded to your Cloudinary product environment without any transformations, the delivery URL will be in the format:

https://res.cloudinary.com/<cloud_name>/video/upload/<public_id>.<extension>

For example, delivering the video with a public ID of: glide-over-coastal-beach, from the demo product environment in mp4 format:

The following shows an example of delivering the same video, this time with transformation parameters applied, so that the video is scaled down and then cropped to fill a 250px square (aspect ratio of 1:1 = 1.0) and then a light blue border is applied:

Transformation URL tips

For customers with a Custom delivery hostname (CNAME) - available for Cloudinary's Advanced plan and above - the basic video delivery URL becomes: https://<custom delivery hostname>/video/upload....
You can convert and deliver your video in other supported video formats by simply changing the video format file extension. For details, see Delivering in a different format.
You can append an SEO-friendly suffix to your URL by replacing the video/upload element of the URL with videos and then appending the desired suffix with a slash (/) after the public ID and before the extension. For example, if you have a cooking video with a random public ID like: abc1def2, you can deliver your video as:
https://res.cloudinary.com/<cloud_name>/videos/upload/a12345/cooking.mp4

For more details, see Dynamic SEO suffixes.

Transformation URL video tutorial

The following video provides a quick demonstration of how dynamic transformation URLs work with both images and videos.

This video is brought to you by Cloudinary's video player - embed your own!
Use the controls to set the playback speed, navigate to chapters of interest and select subtitles in your preferred language.

Download Transcript

Tutorial contents

Parameter types

There are two types of transformation parameters:

Action parameters: Parameters that perform a specific transformation on the asset.
Qualifier parameters: Parameters that do not perform an action on their own, but rather alter the default behavior or otherwise adjust the outcome of the corresponding action parameter.

It's best practice to include only one action parameter per URL component.

If you want to apply multiple actions in a single transformation URL, apply them in separate chained components, where each action is performed on the result of the previous one.

Note

In some of the Cloudinary SDKs, this action separation rule is enforced.

In contrast, qualifier parameters must be included in the component with the action parameter they qualify.

Most qualifiers are optional, meaning the related action parameter can be used independently, but you can add optional qualifiers to modify the default behavior.
In some cases, an action parameter requires one or more qualifiers to fully define the transformation behavior.
There are a few parameters that can be used independently as action parameters, but can also be used in other scenarios as a qualifier for another action.

For example, the transformation below includes multiple transformation actions. The qualifier transformations included together with a particular action define additional adjustments on the transformation action's behavior:

Note

The URL tab above shows the URL as it looks when generated by an SDK. SDKs always generate the parameters within a specific URL component in alphabetical order (thus some qualifiers in the URL may come before the action that they qualify).

In this transformation:

The aspect ratio and height qualifiers control the way the fill crop action will be performed.
The duration qualifier controls the length of the boomerang effect action.
The fade effect action has an option setting, but doesn't have any qualifier parameters.

Asset versions

The version component is an optional part of Cloudinary delivery URLs that can be added to bypass the CDN cached version and force delivery of the newest asset. Cloudinary returns the value of the version parameter as part of every upload response, and the returned url and secure_url parameters also include the version component, which represents the timestamp of the upload.

Delivering the URL without a version value will deliver the cached version on the CDN if available or will request the latest version from Cloudinary if not cached (or when the cached version expires).
Delivering the URL with a version will deliver the cached CDN version only if the cached version matches the requested version number. Otherwise, it will bypass the cached CDN version and immediately request and deliver the latest version from Cloudinary.

Example video delivery URL without version:

Example video delivery URL with version:

Tip

As an alternative to using versions to ensure that a new version of an asset is delivered, you can set the invalidate parameter to true while uploading a new version of an asset. This invalidates the previous version of the media asset throughout the CDN. Note that it usually takes between a few seconds and a few minutes for the invalidation to fully propagate through the CDN. Using a new version value in a URL takes effect immediately, but requires updating your delivery URLs in your production code. For details on invalidating media assets, see Invalidating cached media assets on the CDN.

Video transformation limits

The following limits apply to on-the-fly video transformations (durations refer to the video output):

ABR (sp_auto) - 60 minutes
Progressive (e.g. MP4) - 30 minutes

Requests for videos with a longer duration than these limits are automatically processed asynchronously and return a 423 error until processing is complete.

Note

Different plans have different file size limits, which you also need to take into consideration.

Embedding videos in web pages using SDKs

You access uploaded videos or their derived transformations with URLs. These URLs can be used as the <src> of the <video> tags in your HTML code or other frontend functions to deliver your media assets.

The easiest way to deliver them is using Cloudinary's framework SDKs to automatically generate transformation URLs and embed them using HTML video tags. The SDKs offer two main helper methods: the URL helper and the video tag helper.

Cloudinary URL helper method

To generate an asset source URL using the URL helper method:

Use the Cloudinary URL helper method (e.g., cloudinary_url in the Ruby/Rails SDK) to automatically generate the video source URL.

For example, the following uses the URL helper method to return the URL of the glide-over-coastal-beach video, padded to a scaled width and height of 300 pixels with a blue background for the padding:

This SDK code outputs the URL:

Creating a product video using Node.js

Watch this tutorial to learn how to automatically generate the source URL for a video showing products being used in different ways, using the Cloudinary URL helper method in Node.js. Step-by-step instructions are provided for chaining several different transformations together to create a unique product video.

Download Transcript

Here's the code used in the video:

Note

To run this code, set your product environment API environment variable as an environment variable. Copy the API environment variable format from the API Keys page of the Cloudinary Console Settings. Replace <your_api_key> and <your_api_secret> with your actual values, while your cloud name is already correctly included in the format.

Cloudinary video tag helper method

To generate a complete HTML video tag:

Use the Cloudinary video tag helper method (e.g., cl_video_tag in Ruby on Rails) to automatically generate an HTML video tag including the video source URL in WEBM, MP4, and OGG formats, as well as an automatically generated poster based on the center frame of the video.

The following shows the same transformations as above, but this time using the video tag to generate a complete HTML video tag.

This SDK code will output the following HTML code:

In addition to passing Cloudinary transformations parameters, the video tag helper also supports the following special options (naming may differ slightly for different SDKs), plus the option to pass any standard HTML5 video tag attributes (e.g., mute, controls, etc):

source_types: an ordered array of the video source types to include in the HTML5 tag, where the type is mapped to the mime type. Default: ['webm', 'mp4', 'ogv']
- source_transformation: to override the default transformation instructions for each specific video format. The source_type is mapped to a transformation struct. e.g., { mp4: { quality: 70}}
sources: an ordered array of video source types, codecs and transformations to include in the HTML5 tag, where the type is mapped to the mime type. For example:

would produce the following video tag:

If omitted, the source_types parameter is used. If both are specified, the source_types parameter is ignored.
poster: a URI to an image to be shown while the video is downloading or until the user hits the play button. The URI can be one of the following:
- The URL to an image, including any transformed Cloudinary image.
- Set to nil or false to use no poster.
- Default: the middle frame of the source video in jpg format.
fallback_content: an HTML string to display in the case that the browser does not support any of the video formats included.
Any attribute of the HTML5 video tag. e.g., autoplay, controls, height, loop, muted, preload (see w3schools for details on HTML5 attributes).

The example below creates an HTML5 video tag for the uploaded mp4 video named paradise_location, where the video is cropped to a width of 200 pixels and a height of 150 pixels, given a fallback string in the case that the video tag is not supported, set not to include controls, not to preload, not to use a poster image, and for the video to autoplay in a loop:

This SDK code generates the following HTML5 video tag:

For more information on these SDK helper methods, see the transformation documentation in the relevant SDK guide.

Tip

In general, when using an SDK, you will probably take advantage of the SDK parameter names for improved readability and maintenance of your code. However, you can also optionally pass a raw_transformation parameter, whose value is a literal URL transformation definition. Note that the string you pass as the raw transformation value will be appended as is (with no processing or validation) to the end of any other transformation parameters passed in the same component of the transformation chain.

For example:

Chained transformations

Cloudinary supports powerful transformations that are applied on the fly using dynamic URLs. You can combine multiple transformation actions together as part of a single delivery request, e.g., crop a video and then add a border to it.

In general, it's best practice to chain each transformation action in your URL as a separate component in the chain.

To support chained transformations, Cloudinary's transformation URLs allow you to include multiple transformation components, each separated by a slash (/), where each of the transformation components is executed on the result of the previous one. Cloudinary's SDKs can apply multiple transformation components by specifying the transformation parameter and setting it to an array of transformation maps.

For example, crop this video of a ship to a square, using automatic gravity, blur the video, then round the corners to make a circle, giving an out-of-focus telescope effect: