Cloudinary's dynamic URL transformations enable you to programmatically generate multiple variations of your high quality original images 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.
Your account's pricing plan is in part dependent on the total number of
transformation operationsperformed 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?Here are just a few examples of some popular use cases that you can accomplish on the fly by combining Cloudinary transformations. Click each image to see the URL parameters applied in each case:
Â
OverviewCloudinary allows you to easily transform your images on the fly to any required format, style and dimension, and apply effects and other visual enhancements. You can also optimize your images 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 image transformation and delivery URLs. Your transformed images are then delivered to your users through a fast CDN with optimized caching.
With image transformations, you can:
The rest of this page describes the basics of working with Cloudinary image transformations.
The other pages in this guide provide details and use-case examples on the various types of image transformations you can apply to your images.
The Transformation URL API Reference details every transformation parameter available for both images and videos.
For more information, see Derived assets on the Media Library for developers page.
Below you can see the transformation URL and corresponding SDK code for generating an image with several transformation parameters applied:
/c_thumb,g_face,h_200,w_200/
/r_max/
/f_auto/
Â
Â
Â
Transformed image Transformation URL syntaxYour 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 SDKsCloudinary'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 image tags and image transformation URLs.
You can also create your transformation URLs using the
Transformation Builder. Alternatively, you can take one of our transformations from the
Transformations Galleryas 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 structureThe 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
.
image
type includes still image and photo formats, animated images, PDFs, layered files, such as TIFF and PSD, and others.video
type includes video and audio files.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.In the most general case of simply delivering images 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>/image/upload/<public_id>.<extension>
For example, delivering the image with a public ID of: leather_bag_gray
, from the demo
product environment in jpg
format:
The following shows an example of delivering the same image, this time with transformation parameters applied, so that the image 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 tipshttps://<custom delivery hostname>/image/upload....
You can append an SEO-friendly suffix to your URL by replacing the image/upload
element of the URL with images
and then appending the desired suffix with a slash (/) after the public ID and before the extension. For example, if you have a cooking image with a random public ID like: abc1def2
, you can deliver your image as:
https://res.cloudinary.com/<cloud_name>/images/upload/a12345/cooking.jpg
For more details, see Dynamic SEO suffixes.
You can also use shortcut URLs when specifically delivering image files using the default upload
type. With Cloudinary's Root Path URL feature, the <asset_type>
and <delivery_type>
elements can be omitted from the URL (they automatically default to the values image
and upload
respectively). For example, the Root Path shortcut delivery URL for the cropped image above is:
https://res.cloudinary.com/demo/c_crop,h_200,w_300/sample.jpg
The following video provides a quick demonstration of how dynamic transformation URLs work with both images and videos.
Tutorial contents Delivery typesThe delivery type element of the URL provides an indication about the way the asset will be delivered, although in most cases, the delivery type value is determined at the time that the asset is stored in Cloudinary.
The following delivery type values are supported:
Delivery type Description Learn more upload The default delivery type for uploaded assets. In most cases, this delivery type indicates that the asset is publicly available. However, there are options you can use to restrict access to assets with anupload
delivery type. This includes strict transformations and access mode settings) Upload API private The URL for the original asset can be accessed only with a signed URL. Transformed versions of the asset are publicly available (unless strict transformations are also defined). Uploading private assets authenticated Both original and transformed versions of the asset can be accessed only with a signed URL or an authentication token. Uploading authenticated assets Delivering authenticated assets list Generates a list of assets that have a specified tag.
list
in the delivery type element of the URL. Client-side asset lists fetch Enables transforming and delivering remote assets on the fly. Fetch remote media files facebook
sync_static
command. Static files
You can search for assets by delivery type using the Advanced Search in the Media Library. The most common types can be selected directly in the
Typesection of the
Generalsearch tab. All other types can be selected from the
More typeslist.
Parameter typesThere are two types of transformation parameters:
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.
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.
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:
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:
Transformation flags alter default transformation behavior. In some cases, they alter the default behavior of the transformation URL as a whole. In other cases, they alter the behavior of one or more specific transformation parameters that must be used together in the same URL component.
In general, tens of flags are available that can alter delivery and format, cropping and positioning, overlays, metadata and color profiles, as well as PDF and text behaviors, just to name a few.
For example:
fl_attachment alters the normal behavior of the overall transformation. Instead of delivering an asset in a web page, it causes the transformed media file to be downloaded as an attachment. This flag can be used independently of other transformations.
fl_relative modifies the way overlay resize parameters are evaluated. This flag can only be used in conjunction with the overlay (l_
) parameter.
fl_layer_apply tells Cloudinary to apply all chained transformations, until a transformation component that includes this flag, on the last added overlay or underlay asset instead of applying them on the base asset. This flag acts as an indicator to close the layer section of the transformation, similar to a closing bracket. Placement definitions for how the layer should be applied, such as gravity and offsets are also defined in the component with this flag.
For details on all available transformation flags, see the flag section of the Transformation Reference.
Generating secure HTTPS URLs using SDKsFor backward compatibility reasons, some of Cloudinary's earlier SDK major versions generate http
URLs by default. When using one of these SDKs, you'll generally want to instruct the SDK to generate https
URLs by setting the secure
parameter to true
globally as part of your SDK configuration. However, you can also pass the secure
option locally in each transformation operation.
The following example shows only the SDKs and library versions that require passing secure
= true
to generate HTTPS:
Some transformation parameters with multiple options offer two alternative syntaxes for defining the option values:
name_value
and each option is separated by a colon (:
) or semicolon (;
) depending on the transformation.
The options can be specified in any order, and you only need to include those that you want (or are required) to define.
With this syntax, you can also choose to specify only the options for which you don't want to use default values and default values will be applied for the others.
Transformations that support both verbose and non-verbose URL syntax are indicated as such in the Transformation Reference. When both are supported, SDKs always output the verbose syntax.
Verbose vs non-verbose exampleThe theme effect supports the color
and photosensitivity
options, but you can specify them in a different order using verbose syntax. For example:
e_theme:photosensitivity_110:color_black
However, when using non-verbose syntax, you must specify the parameters in order. Therefore, even if you only want to change the default behavior of the photosensitivity
(last) option, you must still specify the value to use for the color
(first) option:
e_theme:black:110
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.
Example image delivery URL without version:
Example image delivery URL with version:
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.
Chained TransformationsCloudinary 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 an image 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.
Examples:
Three chained transformations: fill to a 250px square, then round to a circle, and deliver in the optimal transparent format:
Five chained transformations: Fill to a 250*400px portrait, then rotate the result by 20 degrees, then add a brown outline to the rotated image, and optimize the resulting image to deliver with the best compression that gives good visual quality and in the optimal transparent format:
A named transformation is a pre-defined set of transformation parameters that has been given a custom name for easy reference. Instead of applying each of the required transformations separately to an asset, you can apply a single named transformation to apply all the transformations defined for it. This makes it easy to:
Named transformations can include other named transformations, which allows you to define a chain of transformations to run on multiple assets more easily.
Named transformations are required for baseline transformations, which save processing time and cost by avoiding regeneration of the baseline part of the transformation.
You can create and manage named transformations via the API or in the console UI using the Transformation Builder.
Once the named transformation has been defined, you can transform an asset with the transformation
parameter (t
for URLs) and the name of your named transformation. For example t_instagram-auto-crop
.
You can include user-defined variables in your named transformations, and then pass the value for the user-defined variable into the transformation from an external source. This enables creating a named transformation 'template' with a lot of flexibility.
For example, you could define a complex named transformation that includes a text overlay as a named transformation, using a user-defined variable for the text string value.
You can also set named transformations as transformation templates, which you can apply as templates in the Media Library so that you can preview how assets will look with different named transformations applied.
For more details, see user-defined variables. For a use-case example demonstrating named transformations with user-defined variables, see Named transformation with a user-defined variable.
If you're sure you want to apply the new definition to any already derived assets with that named transformation, you must specifically invalidate those transformations or otherwise modify the other parameters in that delivery URL, so that the asset will be re-derived using the new definition on next request.
Tip: You can use the regen_derived CLI command to invalidate and then regenerate derived assets after updating the definition for a named transformation.
404
error on the next request).
If there are 1000 or more such derived assets, the delete request fails with a 403
error indicating that your named transformation has too many derived resources
or too many dependent transformations
(when the derived assets use the named transformation in combination with other parameters).
You can create a named transformation programmatically or using the Transformations UI in your Cloudinary console:
To create a named transformation programmatically, use the Transformations
Admin API method. The following example defines a named transformation called small_profile_thumbnail
that uses automatic cropping to resize assets to the required size for a particular application's thumbnail display:
For more details and examples, see the Create Transformation method in the Admin API Reference.
To create a named transformation using the UI: Expand the Transform and Customize section, accessible from the Console Product Navigation menu.
From here, there are a few ways to create a named transformation:
Names used for named transformations:
\
, /
, ?
, &
, #
, %
, .
, ,
, <
, >
Once you've saved your named transformations, you can view a list of them on the Named Transformations tab of the Manage Transformations page of the Console. From here, you can edit, copy, or enable/disable Strict Transformations.
To access the page:
You can also select to include a transformation as a preset so that it can be applied to an asset in the Download Options tab of the asset management drill-down page (available for Assets Enterprise plans).
Transformation BuilderThe Cloudinary Transformation Builder is the UI for creating and saving your transformations in a simple and easy to use way. The Transformation Builder has two modes of operation:
Converse mode is currently in Beta and may not yet be enabled for your account. Some implementation details may change before the official release. We invite you to request access and share any feedback via our
support team.
Transformation Builder video tutorialWatch this video for a quick introduction to the Transformation Builder:
Tutorial contents Create a transformation using the BuilderTo create a new transformation, open the Builder and select the mode to use.
Construct modeThe Transformation Builder in construct mode provides:
The builder supports most common transformation actions. If the transformation action you are trying to apply is not listed, you can add an Additional Transformation action and use transformation URL syntax to specify your transformation. Alternatively, you can switch to the legacy editor to create your transformation.
Converse modeThe Transformation Builder in converse mode provides:
Below are two quite different named transformations applied to the same lighthouse_reflection
image:
ar_1:1,c_fill,g_auto,w_400
, which fills (scales and crops) the image into a 400*400 square, automatically focussing on the most interesting area of the image:
Â
e_cartoonify/r_max/co_rgb:add8e6,e_outline:30/b_rgb:add8e6
, which applies a cartoonify effect, rounds it to a circle or oval shape, adds a light blue outline around the oval so that the image won't be touching the edges of the frame, and then fills the transparent background with the same color as the outline: You can chain named transformations before or after other transformations. For example, here the oval_cartoonified_frame
named transformation is applied after a grayscale effect:
Â
You can also chain multiple named transformations. For example, to chain the named transformations defined in the previous section:
Â
Chaining transformations can create long URLs, so instead you could define a named transformation that includes a chain of other transformations, including other named transformations. For example, we can create a named transformation that is a composite of the named transformations from the section above.
It is now simple to specify a single named transformation and apply it to any asset:
Where the fill_circle_cartoon
named transformation is defined as: t_fill_square_400/t_rounded_cartoonified_frame
.
The automatic format transformation parameter (f_auto
) is not effective if used in named transformations.
When f_auto
is used in a delivery URL, the CDN layer determines the best format to deliver. If this parameter is hidden in a named transformation then it is not visible to the CDN.
You can use f_auto
together with a named transformation by chaining the components, for example, t_square/f_auto
.
The automatic quality transformation parameter (q_auto
) is effective in named transformations, except in one situation.
When q_auto
is used in a delivery URL and the browser sets the Save-Data
HTTP header to on
in the request, q_auto
is translated to q_auto:eco
at the CDN level. If this parameter is hidden in a named transformation then it is not visible to the CDN, so the default level is applied, q_auto:good
.
To accommodate this situation, you may prefer to use q_auto
together with a named transformation by chaining the components, for example, t_square/q_auto
.
If you explicitly set the type of quality to apply in a named transformation, for example,
q_auto:best
, then there are no concerns as there are no dependencies on the CDN level.
Learn more: Save-Data support
Automatic widthThe automatic width transformation parameter (w_auto
) is not effective if used in named transformations.
For responsive image solutions, w_auto
must appear directly in the delivery URL. If it's hidden within a named transformation, it won't be visible to the client or CDN (depending on the solution) and therefore won't take effect.
See Responsive images using the cloudinary-core JS library and Responsive images using client hints.
Automatic device pixel ratioThe automatic device pixel ratio transformation parameter (dpr_auto
) is not effective if used in named transformations.
For responsive image solutions, dpr_auto
must appear directly in the delivery URL. If it's hidden within a named transformation, it won't be visible to the client or CDN (depending on the solution) and therefore won't take effect.
See Responsive images using the cloudinary-core JS library and Responsive images using client hints.
Named transformation video tutorialWatch this video tutorial to learn how to create re-usable named transformations with the Cloudinary Transformation Builder UI.
Tutorial contents Embedding images in web pages using SDKsYou access uploaded images or their derived transformations with URLs. These URLs can be used as the <src>
of the <img>
tags in your HTML code or other frontend functions to deliver your media assets.
But the easiest way to deliver them is using Cloudinary's framework SDKs to automatically generate transformation URLs and embed them using HTML image tags. The SDKs offer two main helper methods: the URL helper and the image tag helper.
Cloudinary URL helper methodThe Cloudinary URL helper method (e.g., cloudinary_url
in the Ruby/Rails SDK) automatically generates the image source URL itself. For example, using the URL helper method to return the URL of the leather_bag_gray
image, padded to a scaled width and height of 300 pixels with a blue background for the padding:
This SDK code outputs the URL:
Cloudinary image tag helper methodBy default, the Cloudinary image tag helper method (e.g., cl_image_tag
in Ruby on Rails) automatically generates an HTML image tag including the image source URL.
The following shows the same transformations as above, but this time using the image tag to generate a complete HTML image tag.
This SDK code will output the following HTML code:
The Cloudinary Image Tag helper method allows you to not only specify any Cloudinary transformations parameters, but also to specify regular HTML image tag attributes (e.g., alt, title, width, height). For example, using the Image Tag helper method to create an HTML image tag for the sample
image, with the 'alt' attribute set to "A sample photo" and the 'className' attribute set to "Samples":
For more information on these SDK helper methods, see the transformation documentation in the relevant SDK guide.
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_transformationparameter, whose value is a literal
URL transformationdefinition. Note that the string you pass as the raw transformation value will be appended as is (with no processing or validation) to the
endof any other transformation parameters passed in the same component of the transformation chain.
For example:
Image format supportImages can be uploaded to Cloudinary in various formats (input formats), and you can easily convert these images to other formats for displaying in your web site or application (output formats). Examples of situations where you might want to change the delivered image format:
You can convert and deliver images in any supported image format by specifying the required format as the file extension of the delivery URL. When using an SDK to build the URL, you can either append the extension of the new format to the asset's public ID or use the format
parameter.
For example, to display the uploaded woman-business-suit
JPEG image as a PNG:
Â
You can combine other image transformations with format conversion. For example, to deliver the same image as a PNG, but this time removing the background and converting the image to grayscale:
Another option for changing the format is to explicitly call the fetch_format
transformation parameter (f
in URLs). This can be useful in situations where you cannot change the file extension, for example, when fetching remote assets that already have a different file extension (format) as part of their URLs.
For example, to fetch a remote image from Wikimedia in PNG format, and deliver the image in JPEG format (also scaled down to a width of 400 pixels):
fetch_format
(f_
) transformation parameter).format
transformation parameter, instead of the fetch_format
parameter. See f (format) in the transformation reference.You can take advantage of Cloudinary's automatic format selection (f_auto
) transformation to automatically deliver images in the most optimized format that's supported by the requesting browser.
For example, if you deliver a JPEG image with f_auto
, Cloudinary might generate and deliver the image as a WebP, AVIF or JPEG XL file, depending on the requesting browser and your account setup. The f_auto
algorithm will similarly deliver the best format when the original asset is a PNG (with or without transparency), an animated GIF, etc.
For details, see Automatic format selection (f_auto) and Tips and considerations for using f_auto.
Supported image formatsThe table below summarizes the supported image formats.
Format Extensions Supported for Upload 1 Supported for Transformations 2 3DS .3ds Yes Yes AI (Adobe Illustrator) .ai Yes Yes animated AVIF .avif No Yes 6 animated GIF .gif Yes Yes animated PNG .png Yes Yes animated WebP .webp Yes Yes AVIF .avif Yes Yes 6 BMP .bmp Yes Yes BW (Browzwear file) .bw Yes Yes DjVu .djvu Yes No DNG (Digital Negative) .dng Yes No EPS (Encapsulated PostScript) .ps, .ept, .eps, .eps3 Yes Yes FBX (Filmbox) .fbx 7 Yes 5 Yes FLIF (Free Lossless Image Format) .flif Yes Yes GIF .gif Yes Yes GLB (Binary glTF) .glb Yes Yes glTF (GL Transmission Format) .gltf Yes 5 Yes HEIF .heif, .heic Yes Yes ICO .ico Yes Yes InDesign .indd Yes Yes 3 JPEG .jpg, .jpe, .jpeg Yes Yes JPEG 2000 .jp2 Yes Yes JPEG XR (JPEG eXtended Range) .wdp, .jxr, .hdp Yes Yes JXL (JPEG XL) .jxl Yes Yes OBJ .obj 7 Yes Yes PDF .pdf Yes Yes PLY .ply Yes Yes PNG .png Yes Yes PSD (Photoshop Document) .psd Yes Yes 4 Raw image files .arw, .cr2, .cr3 Yes No SVG .svg Yes Yes TARGA (Truevision TGA) .tga Yes Yes TIFF .tif, .tiff Yes Yes U3MA (Fabric file) .u3ma Yes 5 Yes USDZ .usdz Yes Yes WebP .webp Yes Yesjpg
as the delivery format to display the resulting transformation in the browser.jpg
or png
, but you cannot deliver an indd
file with transformations.page
parameter is specified.f_auto
) is used.This page walked you through the basics of how image transformations work. The rest of the pages in this guide provide details, use cases and examples of the many different types of transformations you can apply to the images you deliver:
Transformation type Description Resizing and cropping Resize (crop and/or scale) images server-side before delivering them. Placing layers on images Place image, text, or other layers on (or under) existing assets to generate new and customized creations on the fly. Effects and enhancements Apply a huge variety of effects, filters, and other artistic enhancements to any image. Background removal Use AI to remove image backgrounds. Generative AI transformations Use generative AI to transform your images, naturally extending dimensions, removing and replacing objects, generating new backgrounds and more. Face-detection based transformations Transform an image based on detected faces. Animated image transformations Create animated images from multiple images in your product environment, convert them to video, convert between animated formats, and apply animation-specific transformations. 3D models Learn how to perform transformations on 3D models. Conditional transformations Apply a transformation only if a specified condition is met. User-defined variables and arithmetic transformations Use arithmetic expressions and variables to add additional sophistication and flexibility to your transformations. Custom functions Inject a remote, lambda or WebAssembly function and apply the result as a transformation. Delivering optimized and responsive mediaIn addition to changing the appearance of your media assets by transforming them, you can also use Cloudinary URLs and a variety of parameters to control how they're delivered:
Topic Description Optimizations Deliver your media assets with the smallest possible file size while maintaining visual quality, saving bandwidth and improving performance for your website. This includes automatic quality and format selection optimizations (q_auto and f_auto). Responsive images Deliver your images to perfectly fit any device, viewport size, orientation, or resolution at any pixel density (DPR). Upload a single high resolution image and let Cloudinary automatically transform it. Deliver remote media filesaccess_control
to control who can access an asset without adjusting the URL. Advanced URL delivery options Take advantage of advanced options that make your URLs more SEO-friendly, deliver assets using private CDNs or multi-CDN solutions, use custom delivery hostnames (CNAMEs) for your URLs, define custom favicons, work with asset versions, and more. Create new images
Cloudinary provides a variety of methods to create new assets in your product environment.
These methods create new assets in your product environment with their own public IDs, as opposed to the assets that are generated (derived) when using transformations, which are cached in the CDN, but aren't stored in your product environment with their own public IDs.
Topic Description Animated images Create a single animated image from multiple image assets, where each asset is used as a single frame of the resulting animated image. PDF files from images Create a PDF from multiple image assets, where each asset is used as a single frame of the resulting PDF file. Sprites Create and deliver sprite images with their corresponding CSS based on all images with a specified tag. Image collages Create image collages from multiple image assets, combined together in a specific layout, with spacing and colors defined in a template. Images from text Create an image of a given textual string and customize the look & feel of the resulting image with various font, color and style parameters.RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4