Last updated: Oct-01-2024
The Transformation URL API enables you to deliver media assets, including a large variety of on-the-fly transformations through the use of URL parameters. This reference provides comprehensive coverage of all available URL transformation parameters, including syntax, value details, and examples.
- Overview
- .<extension>
- a (angle)
- ac (audio codec)
- af (audio frequency)
- ar (aspect ratio)
- b (background)
- bl (baseline)
- bo (border)
- br (bitrate)
- c (crop/resize)
- co (color)
- cs (color space)
- d (default image)
- dl (delay)
- dn (density)
- dpr (DPR)
- du (duration)
- e (effect)
- eo (end offset)
- f (format)
- fl (flag)
- fn (custom function)
- fps (FPS)
- g (gravity)
- h (height)
- if (if condition)
- ki (keyframe interval)
- l (layer)
- o (opacity)
- p (prefix)
- pg (page or file layer)
- q (quality)
- r (round corners)
- so (start offset)
- sp (streaming profile)
- t (named transformation)
- u (underlay)
- vc (video codec)
- vs (video sampling)
- w (width)
- x, y (x & y coordinates)
- z (zoom)
- $ (variable)
Overview
The default Cloudinary asset delivery URL has the following structure:
This reference covers the parameters and corresponding options and values that can be used in the <transformations>
element of the URL. It also covers the <extension> element.
For information on other elements of the URL, see Transformation URL syntax.
The transformation names and syntax shown in this reference refer to the URL API.
Depending on the Cloudinary SDK you use, the names and syntax for the same transformation may be different. Therefore, all of the transformation examples in this reference also include the code for generating the example delivery URL from your chosen SDK.
The SDKs additionally provide a variety of helper methods to simplify the building of the transformation URL as well as other built-in capabilities. You can find more information about these in the relevant SDK guides.
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.
See the Transformation Guide for additional guidelines and best practices regarding parameter types.
.<extension>
Although not a transformation parameter belonging to the <transformation>
element of the URL, the extension of the URL can transform the format of the delivered asset, in the same way as f_<supported format>.
If f_<supported format> or f_<auto> are not specified in the URL, the format is determined by the extension. If no format or extension is specified, then the asset is delivered in its originally uploaded format.
- If using an SDK to generate your URL, you can control the extension using the
format
parameter, or by adding the extension to the public ID. - If using a raw transformation, for example to define an eager or named transformation, you can specify the extension at the end of the transformation parameters, following a forward slash. For example,
c_pad,h_300,w_300/jpg
means that the delivery URL has transformation parameters ofc_pad,h_300,w_300
and a.jpg
extension.c_pad,h_300,w_300/
represents the same transformation parameters, but with no extension.
Syntax details
Examples
a (angle)
Rotates or flips an asset by the specified number of degrees or automatically according to its orientation or available metadata. Multiple modes can be applied by concatenating their values with a dot.
Learn more: Rotating images | Rotating videos
<degrees>
a_<degrees>
Rotates an asset by the specified angle.
See also: Arithmetic expressions
Syntax details
Examples
<mode>
a_<mode>
Rotates an image or video based on the specified mode.
Use with: To apply one of the a_auto
modes, use it as a qualifier with a cropping action that adjusts the aspect ratio, as per the syntax details and example below.
Syntax details
Examples
ac (audio codec)
af (audio frequency)
af_<frequency value>
Controls the audio sampling frequency.
As a qualifier, can be used to preserve the original frequency, overriding the default frequency behavior of vc_auto
.
As a qualifier, use with: vc_auto
Learn more: Audio frequency control
Syntax details
Example
ar (aspect ratio)
ar_<ratio value>
A qualifier that crops or resizes the asset to a new aspect ratio, for use with a crop/resize mode that determines how the asset is adjusted to the new dimensions.
Use with: c (crop/resize)
Learn more: Setting the resize dimensions
See also: h (height) | w (width) | Arithmetic expressions
Syntax details
Examples
b (background)
Applies a background to empty or transparent areas.
<color value>
b_<color value>
Applies the specified background color on transparent background areas in an image.
Can also be used as a qualifier to override the default background color for padded cropping of images and videos, text overlays and generated waveform images.
As a qualifier, use with: c_auto_pad - image only | c_fill_pad - image only | c_lpad | c_mpad - image only | c_pad | l_subtitles | l_text | fl_waveform
Learn more: Background color for images | Background color for videos
Syntax details
Examples
auto
b_auto[:<mode>][:<number>][:<direction>][:palette_<color 1>[_..._<color n>]]
A qualifier that automatically selects the background color based on one or more predominant colors in the image, for use with one of the padding crop mode transformations.
Learn more: Content-aware padding
Use with: c_auto_pad - image only | c_pad | c_lpad | c_mpad | c_fill_pad - image only
Syntax details
Examples
blurred
b_blurred[:<intensity>][:<brightness>]
A qualifier that generates a blurred version of the same video to use as the background with the corresponding padded cropping transformation.
Learn more: Pad with blurred video background
Syntax details
Example
gen_fill
b_gen_fill[:prompt_<prompt>][;ignore-foreground_<ignore foreground>][;seed_<seed>]
A qualifier that automatically fills the padded area using generative AI to extend the image seamlessly. Optionally include a prompt to guide the image generation.
Using different seeds, you can regenerate the image if you're not happy with the result. You can also use seeds to return a previously generated result, as long as any other preceding transformation parameters are the same.
- Generative fill can only be used on non-transparent images.
- There is a special transformation count for generative fill.
- Generative fill is not supported for animated images, fetched images or incoming transformations.
- If you get blurred results when using this feature, it is likely that the built-in NSFW (Not Safe For Work) check has detected something inappropriate. You can contact support to disable this check if you believe it is too sensitive.
- Initial transformation requests may result in a 423 error response while the transformation is being processed. You can prepare derived versions in advance using an eager transformation.
Learn more: Generative fill
Use with: c_auto_pad | c_pad | c_lpad | c_mpad | c_fill_pad
Syntax details
Examples
bl (baseline)
bl_<named transformation>
Establishes a baseline transformation from a named transformation. The baseline transformation is cached, so when re-used with other transformation parameters, the baseline part of the transformation does not have to be regenerated, saving processing time and cost.
- You can combine the baseline transformation with other transformation parameters, but it must be the first component in the chain and the only transformation parameter in that component.
- You must specify a supported format transformation (
f_
) in the named transformation. - Consider using
f_jxl/q_100
in the baseline transformation to prevent images suffering from loss due to double lossy encoding. - You cannot use automatic format (
f_auto
) in the named transformation, although this can be used in a subsequent component. - If the named transformation contains variables, the variables must be defined within the named transformation.
- The baseline transformation is not supported for fetched media or incoming transformations.
Syntax details
Examples
bo (border)
bo_<width>_<style>_<color>
Adds a solid border around an image or video.
As a qualifier, adds a border to an overlay.
Use with: l_<image id> | l_fetch | l_subtitles | l_text | l_video
Learn more: Adding borders
Syntax details
Examples
br (bitrate)
br_<bitrate value>[:constant]
Controls the bitrate for audio or video files in bits per second. By default, a variable bitrate (VBR) is used, with this value indicating the maximum bitrate.
Supported for video codecs: h264, h265 (MPEG-4); vp8, vp9 (WebM)
Supported for audio codecs: aac, mp3, vorbis
Learn more: Bitrate control
Syntax details
Examples
c (crop/resize)
Changes the size of the delivered asset according to the requested width & height dimensions.
Depending on the selected <crop mode>
, parts of the original asset may be cropped out and/or the asset may be resized (scaled up or down).
When using any of the modes that can potentially crop parts of the asset, the selected gravity parameter controls which part of the original asset is kept in the resulting delivered file.
Learn more: Resizing and cropping images | Resizing and cropping videos
auto
c_auto
Automatically determines the best crop based on the gravity and specified dimensions.
If the requested dimensions are smaller than the best crop, the result is downscaled. If the requested dimensions are larger than the original image, the result is upscaled. Use this mode in conjunction with the g (gravity) parameter.
Required qualifiers
And
Two of the following: w (width) | h (height) | ar (aspect ratio)
(In rare cases, you may choose to provide only one sizing qualifier)
Learn more: Automatic gravity with the automatic cropping mode
Example
auto_pad
c_auto_pad
Tries to prevent a "bad crop" by first attempting to use the auto
cropping mode, but adding some padding if the algorithm determines that more of the original image needs to be included in the final image. Especially useful if the aspect ratio of the delivered asset is considerably different from the original's aspect ratio. Supported only in conjunction with g_auto.
Required qualifiers
And
Two of the following: w (width) | h (height) | ar (aspect ratio)
(In rare cases, you may choose to provide only one sizing qualifier)
Optional qualifiers
Example
crop
c_crop
Extracts the specified size from the original image without distorting or scaling the delivered asset.
By default, the center of the image is kept (extracted) and the top/bottom and/or side edges are evenly cropped to achieve the requested dimensions. You can specify the gravity qualifier to control which part of the image to keep, either as a compass direction (such as south
or north_east
), one of the special gravity positions (such as faces
or ocr_text
), AI-based automatic region detection or AI-based object detection.
You can also specify a specific region of the original image to keep by specifying x and y qualifiers together with w (width) and h (height) qualifiers to define an exact bounding box. When using this method, and no gravity is specified, the x
and y
coordinates are relative to the top-left (north-west) corner of the original asset. You can also use percentage based numbers instead of the exact coordinates for x
, y
, w
and h
(e.g., 0.5 for 50%). Use this method only when you already have the required absolute cropping coordinates. For example, you might use this if your application allows a user to upload user-generated content, and your application allows the user to manually select a region to crop from the original image, and you pass those coordinates to build the crop URL.
Required qualifiers
Two of the following: w (width) | h (height) | ar (aspect ratio)
(In rare cases, you may choose to provide only one sizing qualifier)
Optional qualifiers
g (gravity) | x (x-coordinate) | y (y-coordinate)
Example
fill
c_fill
Creates an asset with the exact specified width and height without distorting the asset. This option first scales as much as needed to at least fill both of the specified dimensions. If the requested aspect ratio is different than the original, cropping will occur on the dimension that exceeds the requested size after scaling. You can specify which part of the original asset you want to keep if cropping occurs using the gravity (set to 'center' by default).
Required qualifiers
At least one of the following: w (width) | h (height) | ar (aspect ratio)
(In rare cases, you may choose to provide only one sizing qualifier)
Optional qualifiers
Examples
fill_pad
c_fill_pad
Tries to prevent a "bad crop" by first attempting to use the fill
mode, but adding some padding if the algorithm determines that more of the original image needs to be included in the final image, or if more content in specific frames in a video should be shown. Especially useful if the aspect ratio of the delivered asset is considerably different from the original's aspect ratio. Supported only in conjunction with g_auto.
Required qualifiers
And
Two of the following: w (width) | h (height) | ar (aspect ratio)
(In rare cases, you may choose to provide only one sizing qualifier)
Optional qualifiers
Example
fit
c_fit
Scales the asset up or down so that it takes up as much space as possible within a bounding box defined by the specified dimension parameters without cropping any of it. The original aspect ratio is retained and all of the original image is visible.
Required qualifiers
Two of the following: w (width) | h (height) | ar (aspect ratio)
(In rare cases, you may choose to provide only one sizing qualifier)
Example
imagga_crop
c_imagga_crop
Requires the Imagga Crop and Scale add-on.
The Imagga Crop and Scale add-on can be used to smartly crop your images based on areas of interest within each specific photo as automatically calculated by the Imagga algorithm.
Required qualifiers
At least one of the following: w (width) | h (height)
Optional qualifiers
Example
imagga_scale
c_imagga_scale
Requires the Imagga Crop and Scale add-on.
The Imagga Crop and Scale add-on can be used to smartly scale your images based on automatically calculated areas of interest within each specific photo.
Required qualifiers
At least one of the following: w (width) | h (height) | ar (aspect ratio)
(In rare cases, you may choose to provide only one sizing qualifier)
Example
lfill
c_lfill
The lfill
(limit fill) mode is the same as fill but only if the original image is larger than the specified resolution limits, in which case the image is scaled down to fill the specified width and height without distorting the image, and then the dimension that exceeds the request is cropped. If the original dimensions are smaller than the requested size, it is not resized at all. This prevents upscaling. You can specify which part of the original image you want to keep if cropping occurs using the gravity parameter (set to center
by default).
Required qualifiers
Two of the following: w (width) | h (height) | ar (aspect ratio)
(In rare cases, you may choose to provide only one sizing qualifier)
Optional qualifiers
Example
limit
c_limit
Same as the fit mode but only if the original asset is larger than the specified limit (width and height), in which case the asset is scaled down so that it takes up as much space as possible within a bounding box defined by the specified width and height parameters. The original aspect ratio is retained (by default) and all of the original asset is visible. This mode doesn't scale up the asset if your requested dimensions are larger than the original image size.
Required qualifiers
Two of the following: w (width) | h (height) | ar (aspect ratio)
(In rare cases, you may choose to provide only one sizing qualifier)
Example
lpad
c_lpad
The lpad
(limit pad) mode is the same as pad but only if the original asset is larger than the specified limit (width and height), in which case the asset is scaled down to fill the specified width and height while retaining the original aspect ratio (by default) and with all of the original asset visible. This mode doesn't scale up the asset if your requested dimensions are bigger than the original asset size. Instead, if the proportions of the original asset do not match the requested width and height, padding is added to the asset to reach the required size. You can also specify where the original asset is placed by using the gravity parameter (set to center
by default). Additionally, you can specify the color of the background in the case that padding is added.
Required qualifiers
Two of the following: w (width) | h (height) | ar (aspect ratio)
(In rare cases, you may choose to provide only one sizing qualifier)
Optional qualifiers
g_<gravity position> | b (background)
Example
mfit
c_mfit
The mfit
(minimum fit) mode is the same as fit but only if the original image is smaller than the specified minimum (width and height), in which case the image is scaled up so that it takes up as much space as possible within a bounding box defined by the specified width and height parameters. The original aspect ratio is retained (by default) and all of the original image is visible. This mode doesn't scale down the image if your requested dimensions are smaller than the original image's.
Required qualifiers
Two of the following: w (width) | h (height) | ar (aspect ratio)
(In rare cases, you may choose to provide only one sizing qualifier)
Example
mpad
c_mpad
The mpad
(minimum pad) mode is the same as pad but only if the original image is smaller than the specified minimum (width and height), in which case the image is unchanged but padding is added to fill the specified dimensions. This mode doesn't scale down the image if your requested dimensions are smaller than the original image's. You can also specify where the original image is placed by using the gravity parameter (set to center
by default). Additionally, you can specify the color of the background in the case that padding is added.
Required qualifiers
Two of the following: w (width) | h (height) | ar (aspect ratio)
(In rare cases, you may choose to provide only one sizing qualifier)
Optional qualifiers
g_<gravity position> | b (background)
Examples
pad
c_pad
Resizes the asset to fill the specified width and height while retaining the original aspect ratio (by default) and with all of the original asset visible. If the proportions of the original asset do not match the specified width and height, padding is added to the asset to reach the required size. You can also specify where the original asset is placed using the gravity parameter (set to center
by default). Additionally, you can specify the color of the background in the case that padding is added.
Required qualifiers
Two of the following: w (width) | h (height) | ar (aspect ratio)
(In rare cases, you may choose to provide only one sizing qualifier)
Optional qualifiers
g_<gravity position> | b (background)
Example
scale
c_scale
Resizes the asset exactly to the specified width and height. All original asset parts are visible, but might be stretched or shrunk if the dimensions you request have a different aspect ratio than the original.
If only width or only height is specified, then the asset is scaled to the new dimension while retaining the original aspect ratio (unless you also include the fl_ignore_aspect_ratio flag).
Required qualifiers
At least one of the following: w (width) | h (height) | ar (aspect ratio)
Optional qualifiers
fl_ignore_aspect_ratio | g_liquid
See also: Liquid rescaling
Examples
thumb
c_thumb
Creates image thumbnails based on a gravity position. Must always be accompanied by the g (gravity) parameter. This cropping mode generates a thumbnail of an image with the exact specified width and height dimensions and with the original proportions retained, but the resulting image might be scaled to fit in the specified dimensions. You can specify the z (zoom) parameter to determine how much to scale the resulting image within the specified width and height.
Required qualifiers
And
Two of the following: w (width) | h (height) | ar (aspect ratio)
(In rare cases, you may choose to provide only one sizing qualifier)
Optional qualifiers
Example
co (color)
co_<color value>
A qualifier that specifies the color to use with the corresponding transformation.
Use with: e_colorize | e_outline | e_make_transparent | e_shadow | l_text | l_subtitles | fl_waveform
Syntax details
Examples
cs (color space)
cs_<color space mode>
Controls the color space used for the delivered image or video.
If you don't include this parameter in your transformation, the color space of the original asset is generally retained. In some cases for videos, the color space is normalized for web delivery, unless cs_copy
is specified.
Syntax details
Examples
d (default image)
d_<image asset>
Specifies a backup placeholder image to be delivered in the case that the actual requested delivery image or social media picture does not exist. Any requested transformations are applied on the placeholder image as well.
Learn more: Using a default image placeholder
Syntax details
Example
dl (delay)
dl_<time value>
Controls the time delay between the frames of a delivered animated image. (The source asset can be an image or a video.)
Related flag: fl_animated
Syntax details
Example
dn (density)
dn_<dots per inch>
Controls the density to use when delivering an image or when converting a vector file such as a PDF or EPS document to a web image delivery format.
-
For web image formats: By default, if an image does not contain resolution information in its embedded metadata, Cloudinary normalizes any derived images for web optimization purposes and delivers them at 150 dpi. Controlling the dpi can be useful when generating a derived image intended for printing.
TipYou can take advantage of the idn (initial density) value to automatically set the density of your image to the (pre-normalized) initial density of the original image (for example,dn_idn
). This value is taken from the original image's metadata. For vector files (PDF, EPS, etc.): When you deliver a vector file in a web image format, it is delivered by default at 150 dpi.
See also: Arithmetic expressions
Learn more: Deliver a PDF page as an image
Syntax details
Example
dpr (DPR)
Sets the device pixel ratio (DPR) for the delivered image or video using a specified value or automatically based on the requesting device.
<pixel ratio>
dpr_<pixel ratio>
Delivers the image or video in the specified device pixel ratio.
1
, ensure that you also set the desired final display dimensions in your image or video tag. For example, if you set c_scale,h_300/dpr_2.0
in your delivery URL, you should also set height=300
in your image tag. Otherwise, the image will be delivered at 2.0 x the requested dimensions (a height of 600px in this example).Learn more: Set Device Pixel Ratio (DPR)
See also: Arithmetic expressions
Syntax details
Example
auto
dpr_auto
Delivers the image in a resolution that automatically matches the DPR (Device Pixel Ratio) setting of the requesting device, rounded up to the nearest integer. Only works for certain browsers and when Client-Hints are enabled.
Learn more: Automatic DPR
Example
du (duration)
du_<time value>
Sets the duration (in seconds) of a video or audio clip.
- Can be used independently to trim a video or audio clip to the specified length. This parameter is often used in conjunction with the so (start offset) and/or eo (end offset) parameters.
- Can be used as a qualifier to control the length of time for a corresponding transformation.
As a qualifier, use with: e_boomerang | l_audio | l_<image id> | l_video
Syntax details
Examples
e (effect)
Applies the specified effect to an asset.
If you specify more than one effect in a transformation component (separated by commas), only the last effect in that component is applied.
To combine effects, use separate components (separated by forward slashes) following best practice guidelines, which recommend including only one action parameter per component.
accelerate
e_accelerate[:<acceleration percentage>]
Speeds up the video playback by the specified percentage.
Syntax details
Example
adv_redeye
e_adv_redeye
Requires the Advanced Facial Attribute Detection add-on.
Automatically removes red eyes from an image.
Example
anti_removal
e_anti_removal[:<distortion level>]
A qualifier that slightly distorts the corresponding image overlay to prevent easy removal.
Use with: l_<image id> | l_fetch | l_text | u (underlay)
Learn more: Smart anti-removal
Syntax details
Example
art
e_art:<filter>
Applies the selected artistic filter.
Learn more: Artistic filter effects