Documentation Index

Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt

Use this file to discover all available pages before exploring further.

Image & Video APIs
Menu

Transformation URL API reference

Last updated: Aug-12-2026

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.

See also:

On this page:

Overview

The default Cloudinary asset delivery URL has the following structure:

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

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.

Important

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.

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

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.

Troubleshooting transformation errors

If you encounter errors when using transformation parameters, Cloudinary returns an X-Cld-Error header with details about the issue. Common problems include invalid syntax, unsupported parameter values, or conflicting transformation options.

Troubleshooting resources

.<extension>

For both images and videos 

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 of c_pad,h_300,w_300 and a .jpg extension. c_pad,h_300,w_300/ represents the same transformation parameters, but with no extension.

Note
As the extension is considered to be part of the transformation, be careful when defining eager transformations and transformations that are allowed when strict transformations are enabled, as the delivery URL must exactly match the transformation, including the extension.

a (angle)

For both images and videos 

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>

For both images and videos a_<degrees>

Rotates an asset by the specified angle.

See also: Arithmetic expressions

<mode>

For both images and videos 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.

ac (audio codec)

For videos only ac_<codec value>

Sets the audio codec.

af (audio frequency)

For videos only af_<frequency value>

Caps the audio sampling frequency at the specified value. If the source audio uses a higher frequency, Cloudinary downsamples it to the specified value. If the source frequency is already at or below the specified value, Cloudinary retains the original frequency and doesn't raise it.

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

ar (aspect ratio)

For both images and videos 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

b (background)

For both images and videos 

Applies a background to empty or transparent areas.

<color value>

For both images and videos 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.

When using chained transformations, we recommend that you use this parameter as a qualifier to a pad crop that doesn't change the result (like c_pad,w_1.0), rather than by itself in a component. Using background by itself can lead to unpredictable results. For example:

Convert the transparent areas of an image to the specified color

Rather than (background not applied):

Convert the transparent areas of an image to the specified color

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

auto

For images only 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

blurred

For videos only 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.

Use with: c_pad | c_lpad

Learn more: Pad with blurred video background

gen_fill

For images only b_gen_fill[:prompt_<prompt>][;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.

Notes and limitations:
  • Generative fill can only be used on non-transparent images.
  • There is a special transformation count for generative fill.
  • Generative fill isn't supported for animated images or fetched images.
  • 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's too sensitive.
  • When Cloudinary is generating a derived version, you may get a 423 response returned until the version is ready. You can prepare derived versions in advance using an eager transformation.
  • When Cloudinary is generating an incoming transformation, you may get a 420 response returned, with status pending until the asset is ready.

Learn more: Generative fill

Use with: c_auto_pad | c_pad | c_lpad | c_mpad | c_fill_pad

bl (baseline)

For both images and videos 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.

This is especially useful for transformations with special transformation counts.

Also consider eagerly generating a baseline transformation for transformations that take a long time to process. You can do that on upload, using the upload method or an upload preset, or for existing assets using the explicit method.

Notes
  • 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.

bo (border)

For both images and videos bo_<width>_<style>_<color>

Adds a solid border around an image or video.

As a qualifier, adds a border to an overlay and ensures the border follows any rounded corners applied with the r (round corners) parameter.

Use with: l_<image id> | l_fetch | l_subtitles | l_text | l_video | u_<image id> | u_fetch | r (round corners)

Learn more: Adding borders

br (bitrate)

For videos only 

Controls the bitrate for audio or video files in bits per second. Includes the option to use either variable bitrate (default), with the bitrate value indicating the maximum bitrate, or constant bitrate. If specifying just a bitrate value, the same bitrate is used for both video and audio (if both are present). To control each separately, use br_av.

Supported for video codecs: h264, h265 (MPEG-4); vp8, vp9 (WebM)
Supported for audio codecs: aac, mp3, vorbis

Learn more: Bitrate control

<bitrate value>

For videos only br_<bitrate value>[:constant]

Controls the bitrate for audio or video files in bits per second.

av

For videos only br_av:video(value_<bitrate_value>[;mode_<bitrate_mode>]);audio_(value_<bitrate_value>)

Controls the video and audio bitrate separately to allow for more fine-tuned control.

c (crop/resize)

For both images and videos 

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

For images only 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

g (gravity)

    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

auto_pad

For images only 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.

Note
Not supported for animated images.

Required qualifiers

g_auto

    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

b (background)

crop

For both images and videos 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)

fill

For both images and videos 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

g (gravity)

fill_pad

For both images and videos 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.

Note
Not supported for animated images.

Required qualifiers

g_auto

    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

b (background) - image only

fit

For both images and videos 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)

imagga_crop

For images only 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

ar (aspect_ratio)

imagga_scale

For images only 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)

lfill

For images only 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

g (gravity)

limit

For both images and videos 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)

lpad

For both images and videos 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. See padding notes for guidance on one-qualifier behavior and width-only padding.

You can use the lpad resize mode as a way of applying padding to all sides of an asset, like a border, or frame.

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)

mfit

For images only 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)

mpad

For images only c_mpad

The mpad (minimum pad) mode applies padding to fill the whole area specified by the dimensions if those dimensions are larger than the original image's dimensions. This mode doesn't scale down the image if the requested dimensions are smaller than the original image's. In that case, the original image is delivered. 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. See padding notes for guidance on one-qualifier behavior and width-only padding.

You can use the mpad resize mode as a way of applying padding to all sides of an image, like a border, or frame.

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)

pad

For both images and videos 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.

If you're looking to apply padding to all sides of an asset, consider using c_lpad or c_mpad.

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). See also the padding notes below.

Optional qualifiers

g_<gravity position> | b (background)

Padding notes
  • Two sizing qualifiers recommended for pad resizing: c_pad (as well as c_lpad, and c_mpad) work best when you provide two of w, h, or ar. If you provide only one (for example, just w), Cloudinary derives the other dimension from the original aspect ratio. Depending on the requested canvas, this can result in padding on both axes.
  • Width-only (horizontal) padding: If you want to add padding only to the width (not height):
    • Preferred: Specify both w and h (for example, set h equal to the original height or to the desired canvas height), e.g.: .../image/upload/c_lpad,h_300,w_450/...jpg
    • Alternative: Add the fl_ignore_aspect_ratio flag to change only one dimension, then pad. For example: .../image/upload/c_lpad,fl_ignore_aspect_ratio,w_450/...jpg This keeps the original height while setting the width to 450, so padding is added horizontally only. (See also: fl_ignore_aspect_ratio).
  • Avoiding scale-down: If you want to preserve the original size and still add padding to a requested canvas, use c_mpad (minimum pad). For example: .../image/upload/c_mpad,h_120,w_160/...jpg When the original is larger than the requested size, c_mpad delivers the original and adds padding as needed.

scale

For both images and videos c_scale

Resizes the asset exactly to the specified width and height. All original asset parts are visible, but might be stretched or squashed 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

thumb

For images only 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

g (gravity)

    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

z (zoom)

co (color)

For both images and videos 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

cs (color space)

For both images and videos cs_<color space mode>

Controls the color space (RGB, sRGB, CMYK, custom ICC, etc) 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.

d (default image)

For images only 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.

Notes
  • If the requested image does not exist and the default placeholder image is delivered instead, the x_cld_error header will also be included in the response.
  • The default placeholder image must be of type upload, i.e. publicly available.
  • When a default placeholder image is served (because the requested asset doesn't exist), Cloudinary typically responds with shorter-lived, private caching so browsers and caches pick up promptly when the originally requested asset becomes available. However, this stricter caching doesn't apply when d_ is defined inside a named transformation. Learn more.

Learn more: Using a default image placeholder

dl (delay)

For both images and videos 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

dn (density)

For images only 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.

    Tip
    You 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.

Note
When automatic quality (q_auto in URLs) is applied to the delivered image, either due to the default image quality setting or as a URL transformation parameter, the DPI and resolution metadata are effectively stripped (the fields exist but you shouldn't rely on the values). This is true even if you set the dn parameter. To prevent this behavior, provide a quality value in the delivery URL, such as q_80.

See also: Arithmetic expressions

Learn more: Deliver a PDF page as an image

dpr (DPR)

For both images and videos 

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>

For both images and videos dpr_<pixel ratio>

Delivers the image or video in the specified device pixel ratio.

Note
When setting a DPR value, you must also include a crop/resize transformation specifying a certain width or height.

Important
When delivering at a DPR value larger than 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

auto

For images only 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

Tip
Using dpr_auto with native mobile apps

If you prefer to specify an explicit DPR value for your native mobile app, then instead of using dpr_auto, retrieve the device’s display scale and include it in the dpr transformation parameter.

For example:

You can also continue to use dpr_auto for automatic detection in browser contexts.

dr (dynamic range)

For videos only 

Sets the dynamic range for video output, controlling whether the video is delivered in HDR (High Dynamic Range) or SDR (Standard Dynamic Range).

Learn more: HDR video transformations

high

For videos only dr_high

Requests HDR10 (High Dynamic Range) output for the video. When combined with vc_h265, Cloudinary performs direct transcoding while preserving the HDR10 color-grading and metadata from the source video.

Learn more: HDR video transformations

Notes
  • HDR video encoding uses the HEVC video codec in Main10 profile with 10-bit pixels. You must use dr_high together with vc_h265 to request HDR output.
  • Cloudinary performs direct transcoding, preserving color-grading and HDR metadata. Conversions between different HDR formats (e.g., HDR10 to Dolby Vision) aren't supported.
  • If the source video can't be delivered as HDR (e.g., missing metadata, incorrect format, non-HLG/HDR10 compliant), Cloudinary automatically falls back to SDR output with no additional charge.

du (duration)

For videos only 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

e (effect)

For both images and videos 

Applies the specified effect to an asset.

Note

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

For videos only e_accelerate[:<acceleration percentage>]

Speeds up the video playback by the specified percentage.

adv_redeye

For images only e_adv_redeye

Requires the Advanced Facial Attribute Detection add-on.
Automatically removes red eyes from an image.

anti_removal

For images only 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_<image id> | u_fetch

Learn more: Smart anti-removal

art

For images only e_art:<filter>

Applies the selected artistic filter.

Learn more: Artistic filter effects

auto_brightness

For images only e_auto_brightness[:<blend percentage>]

Automatically adjusts the image brightness and blends the result with the original image.

auto_color

For images only e_auto_color[:<blend percentage>]

Automatically adjusts the image color balance and blends the result with the original image.

auto_contrast

For images only e_auto_contrast[:<blend percentage>]

Automatically adjusts the image contrast and blends the result with the original image.

auto_enhance

For images only e_auto_enhance[:enhance-colors_<enhance colors>]

Uses AI to automatically enhance an image by optimizing its quality based on the detected quality. If the image is already high quality, only minor adjustments are made. Otherwise, more aggressive enhancements are applied to improve the overall appearance, including noise reduction and detail enhancement.

Notes and limitations:

Learn more: Image enhancement options

assist_colorblind

For images only e_assist_colorblind[:<assist type>]

Applies stripes or color adjustment to help people with common color blind conditions to differentiate between colors that are similar for them.

Learn more: Blog post

background_removal

For images only e_background_removal[:fineedges_<enable fine edges>]

Makes the background of an image transparent.

Notes and tips

Notes:

  • There is a special transformation count for the background removal effect.
  • When Cloudinary is generating a derived version, you may get a 423 response returned until the version is ready. You can prepare derived versions in advance using an eager transformation.
  • When Cloudinary is generating an incoming transformation, you may get a 420 response returned, with status pending until the asset is ready.
  • The background removal transformation imposes a limit of 6144 x 6144 pixels on its input images. If an image exceeds this limit, the transformation first scales down the image to fit the limit, and then processes it. The scaling doesn't affect the aspect ratio of the image, but it does alter its output dimensions.
  • Background removal on the fly isn't supported for fetched images.

Tips:

  • This transformation generally gives better results than the e_bgremoval and e_make_transparent effects.
  • It works well for foreground objects with fine edges and lets you specify certain items that you expect to see as foreground objects.

Learn more: Background removal

bgremoval

For images only e_bgremoval[:screen][:<color to remove>]

Makes the background of an image transparent (or solid white for JPGs). Use when the background is a uniform color.

Tips
  • If the background is not uniform, you can also try the e_make_transparent effect.
  • If neither e_bgremoval nor e_make_transparent give the desired result, it's recommended to try the e_background_removal effect.

blackwhite

For images only e_blackwhite[:<threshold>]

Converts an image to black and white.

Note
You can also convert an image to grayscale.

blue

For images only e_blue:<level>

Adjust an image's blue channel.

blur

For both images and videos e_blur[:<strength>]

Applies a blurring filter to an asset.

blur_faces

For images only e_blur_faces[:<strength>]

Blurs all detected faces in an image.

blur_region

For images only e_blur_region[:<strength>]

Applies a blurring filter to the region of an image specified by x, y, width and height, or an area of text. If no region is specified, the whole image is blurred.

Optional qualifiers

x, y (x & y coordinates) | w (width) | h (height) | g_ocr_text

boomerang

For videos only e_boomerang

Causes a video clip to play forwards and then backwards.

Use in conjunction with trimming parameters (duration, start_offset, or end_offset and the loop effect to deliver a classic (short, repeating) boomerang clip.

Learn more: Create a boomerang video clip

brightness

For both images and videos e_brightness:<level>

Adjusts the image or video brightness.

brightness_hsb

For images only e_brightness_hsb[:<level>]

Adjusts image brightness modulation in HSB to prevent artifacts in some images.

camera

For images only e_camera[[:up_<vertical position>][;right_<horizontal position>][;zoom_<zoom amount>][;env_<environment>][;exposure_<exposure amount>][;frames_<number of frames>]]

A qualifier that lets you customize a 2D image captured from a 3D model, as if a photo is being taken by a camera.

The camera always points towards the center of the 3D model and can be rotated around it. Specify the position of the camera, the exposure, zoom and lighting to capture your perfect shot.

Use with fl_animated to create a 360 spinning animation.

Use with: f (format)

Learn more: Generating an image from a 3D model

See also: e_light

cartoonify

For images only e_cartoonify[:<line strength>][:<color reduction>]

Applies a cartoon effect to an image.

colorize

For images only e_colorize[:<level>]

Colorizes an image. By default, gray is used for colorization. You can specify a different color using the color qualifier.

Optional qualifier

color

contrast

For both images and videos e_contrast[:level_<level>][;type_<function type>]

Adjusts an image or video contrast.

Note
This transformation also supports non-verbose, ordered syntax.

cut_out

For images only e_cut_out

Trims pixels according to the transparency levels of a specified overlay image. Wherever an overlay image is transparent, the original is shown, and wherever an overlay is opaque, the resulting image is transparent.

This effect applies only when the base asset is an image, not a video.

Note
The same layer transformation syntax rules apply, including for authenticated or private assets.

Required qualifiers

l (layer)

Learn more: Shape cutouts: remove a shape

deshake

For videos only e_deshake[:<pixels>]

Removes small motion shifts from a video. Useful for non-professional (user-generated content) videos.

displace

For images only e_displace

Displaces the pixels in an image according to the color channels of the pixels in another specified image (a gradient map specified with the overlay parameter).

Note
The same layer transformation syntax rules apply, including for authenticated or private assets.

Required qualifiers

At least one of the following: x, y (x & y coordinates)

Note
Values of x and y must be between -999 and 999.

Learn more: Displacement maps

distort

Distorts an image to a new shape by either adjusting its corners or by warping it into an arc.

For images only e_distort:<x1>:<y1>:<x2>:<y2>:<x3>:<y3>:<x4>:<y4>

Distorts an image, or text overlay, to a new shape by adjusting its corners to achieve perception warping.

Learn more: Image shape changes and distortion effects

For images only e_distort:arc:<degrees>

Distorts an image, or text overlay, to an arc shape.

Learn more: Image shape changes and distortion effects

dropshadow

For images only e_dropshadow[:azimuth_<azimuth>][;elevation_<elevation>][;spread_<spread>]

Adds a shadow to the object(s) in an image. Specify the angle and spread of the light source causing the shadow.

Notes
  • Either:
    • the original image must include transparency, for example where the background has already been removed and it has been stored in a format that supports transparency, such as PNG, or
    • the dropshadow effect must be chained after the background_removal effect, for example:

Learn more: Dropshadow effect

See also: e_shadow

embed_clipping_path

For images only e_embed_clipping_path:mask_$<variable>

Converts a mask image, referenced via a user-defined variable, into a clipping path and embeds it into the output image metadata.

The mask variable must resolve to an image buffer. The effect is intended for formats that preserve clipping-path metadata in the delivered file, in particular JPEG and TIFF.

Learn more: Embed a clipping path in image metadata

See also: g_clipping_path | fl_clip

enhance

For images only e_enhance

Uses AI to analyze an image and make adjustments to enhance the appeal of the image, such as:

  • Exposure reduction: Correcting overexposed images, smartly reducing excessive brightness and reclaiming details in bright areas, bringing back a balanced exposure.
  • Exposure enhancement: Adjusting underexposed images by enhancing dim areas, thus improving overall exposure without compromising the image's natural quality.
  • Color intensification: Enriching color vividness, making hues more vibrant and lively, thus bringing a more dynamic color range to the image.
  • Color temperature correction: Adjusting the white balance, correcting color casts and ensuring that the colors in the image accurately reflect their real-world appearance.

Consider also using generative restore to revitalize poor quality images, or the improve effect to automatically adjust color, contrast and brightness. See this comparison of image enhancement options.

Notes and limitations:
  • During processing, large images are downscaled to a maximum of 4096 x 4096 pixels, then upscaled back to their original size, which may affect quality.
  • There is a special transformation count for the enhance effect.
  • The enhance effect is not supported for fetched images.
  • If you're using our Asia Pacific data center, you currently can't apply the enhance effect.

See also: e_improve | e_gen_restore

extract

For images only e_extract:prompt_(<prompt 1>[;...;<prompt n>])[;multiple_<detect multiple>][;mode_<mode>][;invert_<invert>][;preserve-alpha_<preserve alpha>]

Extracts an area or multiple areas of an image, described in natural language. You can choose to keep the content of the extracted area(s) and make the rest of the image transparent (like background removal), or make the extracted area(s) transparent, keeping the content of the rest of the image. Alternatively, you can make a grayscale mask of the extracted area(s) or everything excluding the extracted area(s), which you can use with other transformations such as e_mask, e_multiply, e_overlay and e_screen.

Notes and limitations:
  • During processing, large images are downscaled to a maximum of 2048 x 2048 pixels, then upscaled back to their original size, which may affect quality.
  • This transformation changes the image's visual appearance by adjusting only the alpha channel, which controls transparency. The underlying RGB channel data remains unchanged and fully preserved, even in areas that become fully transparent.
  • When you specify more than one prompt, all the objects specified in each of the prompts will be extracted whether or not multiple_true is specified in the URL.
  • There is a special transformation count for the extract effect.
  • The extract effect is not supported for animated images, fetched images or incoming transformations.
  • User-defined variables cannot be used for the prompt when more than one prompt is specified.
  • When Cloudinary is generating a derived version, you may get a 423 response returned until the version is ready. You can prepare derived versions in advance using an eager transformation.
  • When Cloudinary is generating an incoming transformation, you may get a 420 response returned, with status pending until the asset is ready.
  • If you're using our Asia Pacific data center, you currently can't apply the extract effect.

See also: e_background_removal

Learn more: Shape cutouts: use AI to determine what to remove or keep in an image

fade

For both images and videos e_fade[:<duration>]

Fades into, or out of, an animated GIF or video. You can chain fade effects to both fade into and out of the media.

Learn more: Fade in and out

fill_light

For images only e_fill_light[:<blend>][:<bias>]

Adjusts the fill light and optionally blends the result with the original image.

gamma

For both images and videos e_gamma[:<level>]

Adjusts the image or video gamma level.

gen_background_replace

For images only e_gen_background_replace[:prompt_<prompt>][;seed_<seed>]

Replaces the background of an image with an AI-generated background. If no prompt is specified, the background is based on the contents of the image. Otherwise, the background is based on the natural language prompt specified.

For images with transparency, the generated background replaces the transparent area. For images without transparency, the effect first determines the foreground elements and leaves those areas intact, while replacing the background.

Using different seeds, you can regenerate a background 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.

Notes and limitations:
  • The use of generative AI means that results may not be 100% accurate.
  • There's a special transformation count for the generative background replace effect.
  • If you get blurred results when using this feature, it's 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's too sensitive.
  • The generative background replace effect isn't supported for animated images or fetched images.
  • When Cloudinary is generating a derived version, you may get a 423 response returned until the version is ready. You can prepare derived versions in advance using an eager transformation.
  • When Cloudinary is generating an incoming transformation, you may get a 420 response returned, with status pending until the asset is ready.
  • If you're using our Asia Pacific data center, you currently can't apply the generative background replace effect.

Learn more: Generative background replace

gen_recolor

For images only e_gen_recolor:prompt_(<prompt 1>[;...;<prompt n>]);to-color_<to color>[;apply-to-tier_(<tier 0>[;...;<tier n>])][;multiple_<detect multiple>]

Uses generative AI to recolor parts of your image, maintaining the relative shading. Specify one or more prompts and the color to change them to. Use the multiple parameter to replace the color of all instances of the prompt when one prompt is given.

Notes and limitations:
  • The generative recolor effect can only be used on non-transparent images.
  • The use of generative AI means that results may not be 100% accurate.
  • The generative recolor effect works best on simple objects that are clearly visible, and not abstract concepts such as "background".
  • Very small objects and very large objects may not be detected.
  • During processing, large images are downscaled to a maximum of 2048 x 2048 pixels, then upscaled back to their original size, which may affect quality.
  • When you specify more than one prompt, all the objects specified in each of the prompts will be recolored whether or not multiple_true is specified in the URL.
  • There is a special transformation count for the generative recolor effect.
  • The generative recolor effect isn't supported for animated images or fetched images.
  • User-defined variables can't be used for the prompt when more than one prompt is specified.
  • When Cloudinary is generating a derived version, you may get a 423 response returned until the version is ready. You can prepare derived versions in advance using an eager transformation.
  • When Cloudinary is generating an incoming transformation, you may get a 420 response returned, with status pending until the asset is ready.
  • If you're using our Asia Pacific data center, you currently can't apply the generative recolor effect.

Tip
Consider using e_replace_color if you want to recolor everything of a particular color in your image, rather than specific elements.

Learn more: Generative recolor

See also: e_replace_color

gen_remove

For images only e_gen_remove[:prompt_(<prompt 1>[;...;<prompt n>])][;multiple_<detect multiple>][;remove-shadow_<remove shadow>]][:region_((x_<x coordinate 1>;y_<y coordinate 1>;w_<width 1>;h_<height 1>)[;...;(x_<x coordinate n>;y_<y coordinate n>;w_<width n>;h_<height n>)])]

Uses generative AI to remove unwanted parts of your image, replacing the area with realistic pixels. Specify either one or more prompts or one or more regions. Use the multiple parameter to remove all instances of the prompt when one prompt is given.

By default, shadows cast by removed objects are not removed. If you want to remove the shadow, when specifying a prompt you can set the remove-shadow parameter to true.

Notes and limitations:
  • The generative remove effect can only be used on non-transparent images.
  • The use of generative AI means that results may not be 100% accurate.
  • The generative remove effect works best on simple objects that are clearly visible.
  • Very small objects and very large objects may not be detected.
  • Don't attempt to remove faces or hands.
  • During processing, large images are downscaled to a maximum of 6140 x 6140 pixels, then upscaled back to their original size, which may affect quality.
  • When you specify more than one prompt, all the objects specified in each of the prompts will be removed whether or not multiple_true is specified in the URL.
  • There is a special transformation count for the generative remove effect.
  • If you get blurred results when using this feature, it's 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's too sensitive.
  • The generative remove effect isn't supported for animated images or fetched images.
  • User-defined variables can't be used for the prompt when more than one prompt is specified.
  • When Cloudinary is generating a derived version, you may get a 423 response returned until the version is ready. You can prepare derived versions in advance using an eager transformation.
  • When Cloudinary is generating an incoming transformation, you may get a 420 response returned, with status pending until the asset is ready.
  • If you're using our Asia Pacific data center, you currently can't apply the generative remove effect.

Learn more: Generative remove

gen_replace

For images only e_gen_replace:from_<from prompt>;to_<to prompt>[;preserve-geometry_<preserve geometry>][;multiple_<detect multiple>]

Uses generative AI to replace parts of your image with something else. Use the preserve-geometry parameter to fill exactly the same shape with the replacement.

Notes and limitations:
  • The generative replace effect can only be used on non-transparent images.
  • The use of generative AI means that results may not be 100% accurate.
  • The generative replace effect works best on simple objects that are clearly visible.
  • Very small objects and very large objects may not be detected.
  • Don't attempt to replace faces, hands or text.
  • During processing, large images are downscaled to a maximum of 2048 x 2048 pixels, then upscaled back to their original size, which may affect quality.
  • There is a special transformation count for the generative replace effect.
  • The generative replace effect isn't supported for animated images or fetched images.
  • When Cloudinary is generating a derived version, you may get a 423 response returned until the version is ready. You can prepare derived versions in advance using an eager transformation.
  • When Cloudinary is generating an incoming transformation, you may get a 420 response returned, with status pending until the asset is ready.
  • If you're using our Asia Pacific data center, you currently can't apply the generative replace effect.

Learn more: Generative replace

gen_restore

For images only e_gen_restore

Uses generative AI to restore details in poor quality images or images that may have become degraded through repeated processing and compression.

Consider also using the improve effect to automatically adjust color, contrast and brightness, or the enhance effect to improve the appeal of an image based on AI analysis. See this comparison of image enhancement options.

Notes and limitations:
  • The generative restore effect can only be used on non-transparent images.
  • The use of generative AI means that results may not be 100% accurate.
  • There is a special transformation count for the generative restore effect.
  • The generative restore effect isn't supported for animated images or fetched images.
  • When Cloudinary is generating a derived version, you may get a 423 response returned until the version is ready. You can prepare derived versions in advance using an eager transformation.
  • When Cloudinary is generating an incoming transformation, you may get a 420 response returned, with status pending until the asset is ready.

See also: e_enhance | e_improve

Learn more: Generative restore

gradient_fade

For images only e_gradient_fade[:<type>][:<strength>]

Applies a gradient fade effect from the edge of an image. Use x or y to indicate from which edge to fade and how much of the image should be faded. Values of x and y can be specified as a percentage (range: 0.0 to 1.0), or in pixels (integer values). Positive values fade from the top (y) or left (x). Negative values fade from the bottom (y) or right (x). By default, the gradient is applied to the top 50% of the image (y_0.5).

Optional qualifiers

x, y (x & y coordinates)