Image transformations

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.

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:

Convert format, round,
change aspect ratio & crop to face,
add outlines & shadows Place, style, and format
image and text layers Apply special effects like
cartoonify and brightness,
rotate to any angle

Overview

Cloudinary 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:

• Deliver images using the image format that fits your needs.
• Resize and crop your images to the required dimensions using different scaling and cropping techniques, or use our smart cropping techniques, including face-detection or auto-gravity for cropping to focus on the most relevant parts of a photo.
• Generate a new image by layering other images or text on your base image.
• Apply a variety of effects, filters, and other visual enhancements to help your image achieve the desired impact.
• And much more.... See Transformation Types for a listing of many different types of transformations you can apply with links to details.

Quick example

Below you can see the transformation URL and corresponding SDK code for generating an image with several transformation parameters applied:

• Scales and tightly crops the image to fit into a 200px x 200px square, centering on the auto-detected face: /c_thumb,g_face,h_200,w_200/
• Rounds the corners to a circle: /r_max/
• Converts and delivers the image in the best transparent format for the requesting browser. For example, webp or avif: /f_auto/

Original

 

 

 

Transformed image

Transformation URL syntax

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

Generating transformation URLs with Cloudinary SDKs

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

Transformation URL structure

The default Cloudinary asset delivery URL has the following structure:

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 tips

• For customers with a Custom delivery hostname (CNAME) - available for Cloudinary's Advanced plan and above - the basic image delivery URL becomes: https://<custom delivery hostname>/image/upload....
• You can convert and deliver your image in other supported image formats by simply changing the image format file extension. For details, see Delivering in a different format.

• 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

Transformation URL video tutorial

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

Tutorial contents

Parameter types

There are two types of transformation parameters:

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

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

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

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

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

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

In this transformation:

• The aspect ratio, gravity, and width qualifiers control the way the thumbnail crop action will be performed.
• The rounding action doesn't have any qualifiers.
• The color qualifier overrides the default color of the outline effect action.
• The color qualifier overrides the default shadow effect color, while the x and y qualifiers adjust its placement.

Asset versions

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

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

Example image delivery URL without version:

Example image delivery URL with version:

Embedding images in web pages using SDKs

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

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 method

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

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

For example, the following uses 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 method

To generate a complete HTML image tag:

Use the Cloudinary image tag helper method (e.g., cl_image_tag in Ruby on Rails) to automatically generate 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:

To add HTML attributes to your image tag:

Use the Cloudinary Image Tag helper method to specify both Cloudinary transformation parameters and regular HTML image tag attributes (e.g., alt, title, width, height).

For example, the following uses 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.

Chained Transformations

Cloudinary supports powerful transformations that are applied on the fly using dynamic URLs. You can combine multiple transformation actions together as part of a single delivery request, e.g., crop 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:

1. Three chained transformations: fill to a 250px square, then round to a circle, and deliver in the optimal transparent format:

   

2. 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: