Image transformations

Whether your web application supports user uploaded images, you deliver static images, or you display profile pictures from social networks, you probably need to manipulate them to fit the graphic design of your Web site or mobile application.

Cloudinary allows you to easily transform your images on-the-fly to any required format, style and dimension, and also optimizes images for 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. You can change the required transformations at any time. All transformed images are created on-demand (lazily) and delivered to your users through a fast CDN with optimized caching.

For example, you can resize and crop images, deliver them using the image format that fits your needs, and/or apply a variety of filters and effects. You can also use our smart cropping techniques, including face-detection or auto-gravity for cropping based on the most relevant parts of uploaded photos. For complex transformations, you can use the Management Console or Admin API for defining named transformations and even run a set of chained transformations on your images. You can also use the Management Console to view delivery usage reports and optimization insights.

This page teaches you how Cloudinary transformations work and provides detailed descriptions and use‑case examples for commonly-used transformations.

Quick Example

The following dynamic URL with on-the-fly image transformation crops an image to a 400x400 circular thumbnail while automatically focusing on the face, and then scales down the result to a width of 200 pixels. Below you can see the original image (scaled down) and the dynamically created face detection based thumbnail.

cl_image_tag("lady.jpg", :transformation=>[
  {:width=>400, :height=>400, :gravity=>"face", :radius=>"max", :crop=>"crop"},
  {:width=>200, :crop=>"scale"}
  ])

cl_image_tag("lady.jpg", array("transformation"=>array(
  array("width"=>400, "height"=>400, "gravity"=>"face", "radius"=>"max", "crop"=>"crop"),
  array("width"=>200, "crop"=>"scale")
  )))

CloudinaryImage("lady.jpg").image(transformation=[
  {'width': 400, 'height': 400, 'gravity': "face", 'radius': "max", 'crop': "crop"},
  {'width': 200, 'crop': "scale"}
  ])

cloudinary.image("lady.jpg", {transformation: [
  {width: 400, height: 400, gravity: "face", radius: "max", crop: "crop"},
  {width: 200, crop: "scale"}
  ]})

cloudinary.url().transformation(new Transformation()
  .width(400).height(400).gravity("face").radius("max").crop("crop").chain()
  .width(200).crop("scale")).imageTag("lady.jpg");

cloudinary.imageTag('lady.jpg', {transformation: [
  {width: 400, height: 400, gravity: "face", radius: "max", crop: "crop"},
  {width: 200, crop: "scale"}
  ]}).toHtml();

$.cloudinary.image("lady.jpg", {transformation: [
  {width: 400, height: 400, gravity: "face", radius: "max", crop: "crop"},
  {width: 200, crop: "scale"}
  ]})

<Image publicId="lady.jpg" >
  <Transformation width="400" height="400" gravity="face" radius="max" crop="crop" />
  <Transformation width="200" crop="scale" />
</Image>

<cld-image publicId="lady.jpg" >
  <cld-transformation width="400" height="400" gravity="face" radius="max" crop="crop" />
  <cld-transformation width="200" crop="scale" />
</cld-image>

<cl-image public-id="lady.jpg" >
  <cl-transformation width="400" height="400" gravity="face" radius="max" crop="crop">
  </cl-transformation>
  <cl-transformation width="200" crop="scale">
  </cl-transformation>
</cl-image>

cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(400).Height(400).Gravity("face").Radius("max").Crop("crop").Chain()
  .Width(200).Crop("scale")).BuildImageTag("lady.jpg")

MediaManager.get().url().transformation(new Transformation()
  .width(400).height(400).gravity("face").radius("max").crop("crop").chain()
  .width(200).crop("scale")).generate("lady.jpg");

imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setWidth(400).setHeight(400).setGravity("face").setRadius("max").setCrop("crop").chain()
  .setWidth(200).setCrop("scale")).generate("lady.jpg")!, cloudinary: cloudinary)

Cloudinary's client libraries (SDKs) take care of the transformation URL building for you, and simplify the integration even further. They allow you to continue working in your preferred developer framework and provide helper methods to simplify building image tags and image transformation URLs: Rails, PHP, Django, JavaScript, jQuery, Node.js, .NET, Java, Angular, Javascript, React, Vue.js, iOS, Scala and Android.

Transforming media assets using dynamic URLs

Accessing media assets is done 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 specified when uploading the asset to your Cloudinary account, or automatically assigned by Cloudinary (see Upload images for more details on the various options for specifying the public ID).

The default Cloudinary asset delivery URL has the following structure:

Where:

• cloud_name - The name of your Cloudinary account, a unique public identifier for URL building and API access.
• asset_type - (optional) The type of asset to deliver. Default: image. Valid values: image, raw, or video.
  • The image type includes still image and photo formats, animated images, PDFs, layered files, such as TIFF and PSD, and others.
  • The video type includes video and audio files.
  • The raw type includes any file uploaded to Cloudinary that does not fit in one of the above categories. In general, transformations cannot be performed on raw assets, but they can be delivered as-is for download purposes, or in some cases, they may be used in conjunction with your image or video transformations.
• delivery_type - (optional) The storage or delivery type. Default: upload. For details on all possible types, see Delivery types.
• transformations (optional) One or more transformation parameters in a single component, or a set of chained transformations in multiple components. When the transformation URL is first accessed, the derived media file is created on-the-fly and delivered to your user. The derived file is also cached on the CDN and is immediately available to all subsequent users requesting the same asset.
• version - (optional) You can add the version to your delivery URL to bypass the cached version on the CDN and force delivery of the latest resource (in the case that a resource has been overwritten with a newer file). For simplicity, the version component is generally not included in the example URLs on this page. For details, see Asset versions.
• public_id - The unique identifier of the resource, including the folder structure if relevant.
• format - (optional) The file extension of the requested delivery format for the resource. Default: The originally uploaded format or the format determined by f_auto, when used.

Therefore, in the most general case of delivering an image that has been uploaded to your Cloudinary account, the delivery URL is given as:

https://res.cloudinary.com/<cloud_name>/image/upload/<public_id>.<format>

For example, displaying the image with a public ID of sample uploaded to Cloudinary's demo account in jpg format:

cl_image_tag("sample.jpg")

cl_image_tag("sample.jpg")

CloudinaryImage("sample.jpg").image()

cloudinary.image("sample.jpg")

cloudinary.url().imageTag("sample.jpg");

cloudinary.imageTag('sample.jpg').toHtml();

$.cloudinary.image("sample.jpg")

<Image publicId="sample.jpg" >

</Image>

<cld-image publicId="sample.jpg" >

</cld-image>

<cl-image public-id="sample.jpg" >

</cl-image>

cloudinary.Api.UrlImgUp.BuildImageTag("sample.jpg")

MediaManager.get().url().generate("sample.jpg");

imageView.cldSetImage(cloudinary.createUrl().generate("sample.jpg")!, cloudinary: cloudinary)

Any transformation (manipulation) instructions can be added before the public ID in the delivery URL. When the URL is first accessed, the derived image is created on-the-fly and delivered to your user. The derived image is also cached on the CDN and is immediately available to all subsequent users requesting the same image.

The following shows an example of delivering an image with transformation parameters, where the image with a public ID of sample is cropped to a width of 300 pixels and a height of 200 pixels, and delivered in JPEG format:

cl_image_tag("sample.jpg", :width=>300, :height=>200, :crop=>"crop")

cl_image_tag("sample.jpg", array("width"=>300, "height"=>200, "crop"=>"crop"))

CloudinaryImage("sample.jpg").image(width=300, height=200, crop="crop")

cloudinary.image("sample.jpg", {width: 300, height: 200, crop: "crop"})

cloudinary.url().transformation(new Transformation().width(300).height(200).crop("crop")).imageTag("sample.jpg");

cloudinary.imageTag('sample.jpg', {width: 300, height: 200, crop: "crop"}).toHtml();

$.cloudinary.image("sample.jpg", {width: 300, height: 200, crop: "crop"})

<Image publicId="sample.jpg" >
  <Transformation width="300" height="200" crop="crop" />
</Image>

<cld-image publicId="sample.jpg" >
  <cld-transformation width="300" height="200" crop="crop" />
</cld-image>

<cl-image public-id="sample.jpg" >
  <cl-transformation width="300" height="200" crop="crop">
  </cl-transformation>
</cl-image>

cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(300).Height(200).Crop("crop")).BuildImageTag("sample.jpg")

MediaManager.get().url().transformation(new Transformation().width(300).height(200).crop("crop")).generate("sample.jpg");

imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(300).setHeight(200).setCrop("crop")).generate("sample.jpg")!, cloudinary: cloudinary)

You can also use shortcut URLs when specifically delivering image files using the default upload type. With Cloudinary’s Root Path URL feature, the resource type and type parameters 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/w_300,h_200,c_crop/sample.jpg

The rest of this page describes the various types of available transformation and delivery options, including many detailed use-case examples. See the Transformation URL API Reference for the complete list of available transformation parameters, syntax, and examples.

Delivery types

The 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 your account.

The following delivery type values are supported:

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.

Transformation flags

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, metadata and color profiles, and overlays, PDFs, and text behaviors.

For example:

• fl_attachment alters the normal behavior of the overall transformation. Instead of delivering an image or video in a web page, it causes the transformed media file as an attachment. This flag can be used independently.

• fl_relative modifies the way overlay resize parameters are evaluated. This flag can only be used in conjunction with the overlay (l_publicid) parameter.

For details on all available transformation flags, see the flag section of the Transformation Reference.

Secure HTTPS URLs

Cloudinary supports delivering media assets using HTTPS URLs. The process for creating HTTPS delivery URLs is identical to creating HTTP URLs, with only the URL protocol changing. When using one of Cloudinary's framework SDKs, you can generate HTTPS URLs by setting the secure parameter to true, either globally (e.g., in the CLOUDINARY_URL environment variable) or locally in each call. For example, delivering the sample image with HTTPS:

cl_image_tag("sample.jpg", :secure=>true)

cl_image_tag("sample.jpg", array("secure"=>true))

CloudinaryImage("sample.jpg").image(secure=True)

cloudinary.image("sample.jpg", {secure: true})

cloudinary.url().secure(true).imageTag("sample.jpg");

cloudinary.imageTag('sample.jpg', {secure: true}).toHtml();

$.cloudinary.image("sample.jpg", {secure: true})

<Image publicId="sample.jpg" secure="true">

</Image>

<cld-image publicId="sample.jpg" secure="true">

</cld-image>

<cl-image public-id="sample.jpg" secure="true">

</cl-image>

cloudinary.Api.UrlImgUp.Secure(true).BuildImageTag("sample.jpg")

MediaManager.get().url().secure(true).generate("sample.jpg");

imageView.cldSetImage(cloudinary.createUrl().generate("sample.jpg")!, cloudinary: cloudinary)

For more information on using HTTPS to deliver your media assets, see the article on Why isn't everyone using HTTPS and how to do it with Cloudinary.

Verbose vs non-verbose URL transformation syntax

Some transformations with multiple options offer two alternative syntaxes for defining the option values:

• Verbose, unordered: Each option of the transformation (whether required or optional) is specified in the verbose format name_value and each option is separated by a colon (:).

  The options can be specified in any order, and you only need to include those that you want (or are required) to define.

  For example, the progressbar effect supports the type, color, and width parameters, but you can specify them in a different order: e_progressbar:width_5:type_frame:color_FF0000.

  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. For example: e_progressbar:width_5 will generate a progressbar with a width of 5 pixels, while applying the default values for type and frame.

• Non-verbose, ordered: Transformation options are specified only by values, and must be entered in the pre-defined option order for that transformation. All values from the syntax to the left of the value you want to supply must also be entered.

  For example, if you only need to change the default behavior of the second option, you must still specify the value to use for the first option: e_progressbar:bar:FF0000 applies the bar (default) type and a custom color, along with the default width of 10 pixels.

Transformations that support both verbose and non-verbose URL syntax are indicated as such in the Transformation Reference. SDKs always output the verbose syntax.

Delivering optimized and responsive media assets

In 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 are delivered:

• Optimizations - Deliver your media assets with the smallest possible file size while maintaining visual quality, saving bandwidth and improving performance for your website.
• Responsive images - Deliver your images to perfectly fit any device, window size, orientation, or resolution at any pixel density (DPR). Upload a single high resolution image and let Cloudinary automatically transform it.
• Remotely fetched media - Grab media assets from anywhere on the web, including support for on-the-fly manipulation and optimized delivery via a CDN.
• Paged and layered media - Deliver content from assets with multiple pages or layers such as PDFs or Photoshop files, including options for delivering or transforming only selected pages or layers.
• Access control - Control who can access your media, both the originals and transformed assets.

Embedding images in web pages

Accessing uploaded images or their derived transformations is done using simple URLs that you can use as the 'src' of the 'img' tags in your HTML code or Javascript functions. URLs for accessing resources contain the resource kind, the Public ID of the resource, and optional version and transformation parameters. You can also use Cloudinary’s web framework SDKs to aid you in adding images to your web application and simplify the creation of transformation URLs and embedding HTML image tags. Cloudinary offers two main helper methods in this regard:

The Cloudinary URL helper method (e.g., cloudinary_url in Ruby on Rails) automatically generates the image source URL for use as the 'src' of the 'img' tags in your HTML code or Javascript functions. For example, using the URL helper method to return the URL of the sample image, scaled to a width of 300 pixels and a height of 100 pixels:

cloudinary_url("sample.jpg", :width=>300, :height=>100, :crop=>"scale")

Cloudinary::cloudinary_url("sample.jpg", array("width"=>300, "height"=>100, "crop"=>"scale"))

cloudinary.utils.cloudinary_url("sample.jpg", width=300, height=100, crop="scale")

cloudinary.url("sample.jpg", {width: 300, height: 100, crop: "scale"})

cloudinary.url().transformation(new Transformation().width(300).height(100).crop("scale")).generate("sample.jpg")

cloudinary.url('sample.jpg', {width: 300, height: 100, crop: "scale"});

$.cloudinary.url("sample.jpg", {width: 300, height: 100, crop: "scale"})

cloudinary.url('sample.jpg', {width: 300, height: 100, crop: "scale"});

cloudinary.url('sample.jpg', {width: 300, height: 100, crop: "scale"});

cloudinary.url('sample.jpg', {width: 300, height: 100, crop: "scale"});

cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(300).Height(100).Crop("scale")).BuildUrl("sample.jpg")

MediaManager.get().url().transformation(new Transformation().width(300).height(100).crop("scale")).generate("sample.jpg");

cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(300).setHeight(100).setCrop("scale")).generate("sample.jpg")

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. For example, using the Image Tag helper method to create an HTML image tag for the sample image, scaled to a width of 300 pixels and a height of 100 pixels:

cl_image_tag("sample.jpg", :width=>300, :height=>100, :crop=>"scale")

cl_image_tag("sample.jpg", array("width"=>300, "height"=>100, "crop"=>"scale"))

CloudinaryImage("sample.jpg").image(width=300, height=100, crop="scale")

cloudinary.image("sample.jpg", {width: 300, height: 100, crop: "scale"})

cloudinary.url().transformation(new Transformation().width(300).height(100).crop("scale")).imageTag("sample.jpg");

cloudinary.imageTag('sample.jpg', {width: 300, height: 100, crop: "scale"}).toHtml();

$.cloudinary.image("sample.jpg", {width: 300, height: 100, crop: "scale"})

<Image publicId="sample.jpg" >
  <Transformation width="300" height="100" crop="scale" />
</Image>

<cld-image publicId="sample.jpg" >
  <cld-transformation width="300" height="100" crop="scale" />
</cld-image>

<cl-image public-id="sample.jpg" >
  <cl-transformation width="300" height="100" crop="scale">
  </cl-transformation>
</cl-image>

cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(300).Height(100).Crop("scale")).BuildImageTag("sample.jpg")

MediaManager.get().url().transformation(new Transformation().width(300).height(100).crop("scale")).generate("sample.jpg");

imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(300).setHeight(100).setCrop("scale")).generate("sample.jpg")!, cloudinary: cloudinary)

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

cl_image_tag("sample.jpg", :alt=>"A sample photo", :className=>"Samples")

cl_image_tag("sample.jpg", array("alt"=>"A sample photo", "className"=>"Samples"))

CloudinaryImage("sample.jpg").image(alt="A sample photo", className="Samples")

cloudinary.image("sample.jpg", {alt: "A sample photo", className: "Samples"})

cloudinary.url().imageTag("sample.jpg", ObjectUtils.asMap("alt","A sample photo","className","Samples"));

cl.imageTag('sample.jpg', {alt: "A sample photo", className: "Samples"}).toHtml();

$.cloudinary.image("sample.jpg", {alt: "A sample photo", className: "Samples"})

<Image publicId="sample.jpg" alt="A sample photo" className="Samples">
</Image>

<CLDImage publicId="sample.jpg" alt="A sample photo" className="Samples">
</CLDImage>

<cl-image public-id="sample.jpg" alt="A sample photo" className="Samples">
</cl-image>

@Model.Cloudinary.Api.UrlImgUp.BuildImageTag("sample.jpg", new CloudinaryDotNet.StringDictionary("alt=A sample photo", "className=Samples"));

cl_image_tag("flower.jpg", 
  :transformation=>[{:raw_transformation=> "o_90,w_1000,c_fill,g_south_east/l_my_image,fl_relative,w_1.0"}])

cl_image_tag("sample.jpg", 
  array("raw_transformation" => "w_400,c_pad"));

CloudinaryImage("sample.jpg").image(
  transformation=[{"raw_transformation":"w_400,c_pad"}])

cloudinary.image("sample.jpg", { transformation: { raw_transformation: "w_400,c_pad" }})

<cl:image src="sample.jpg" raw_transformation="w_100,h_150,c_fill"/>

// or
cloudinary.url()
  .transformation(new Transformation().rawTransformation("w_100,h_150,c_fill"))
  .imageTag("sample.jpg");

cl.imageTag("sample.jpg", { raw_transformation: "w_400,c_pad" }}).toHtml();

$.cloudinary.imageTag("sample.jpg", { raw_transformation: "w_400,c_pad" }}).toHtml();

<Image publicId="mypic">
  <Transformation rawTransformation="h_150,w_150,c_fill,e_sepia,r_20" />
</Image>

<CLDImage publicId="sample.jpg" rawTransformation="w_150,h_150,c_fill">
</CLDImage>

<cl-image 
  public-id="mypic" 
  class="thumbnail inline" 
  format="jpg"
  raw-transformation="w_150,h_150,c_fill">
</cl-image>

@Model.Cloudinary.Api.UrlImgUp.Transform(
    new Transformation().RawTransformation("w_100,h_150,c_fill")).BuildImageTag("sample.jpg");

For more information on these SDK helper methods, see the documentation for the relevant framework: Ruby on Rails, PHP, Django, Node.js, Java, .NET, Angular, Javascript, React, Vue.js, iOS, Scala and Android.

Image format support

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

• Delivering JPEGs for photos that you want to load quickly (or WebP if your users are on a Chrome browser or on a mobile app you control).
• Delivering a GIF if the image contains a drawing with only a few colors.
• Delivering a PNG (24 bit) for high quality illustrations with a transparent background.
• Delivering an image where the original format is not supported for delivery by the browser. For example, you could deliver a Photoshop (.psd) image as a JPG.

To deliver images in a different format simply specify the new format as the file extension of the delivery URL. When using our SDKs you can either specify the new format as an extension to the resource name or use the format parameter.

For example, to display a GIF version of the uploaded sample JPEG file:

cl_image_tag("sample.gif")

cl_image_tag("sample.gif")

CloudinaryImage("sample.gif").image()

cloudinary.image("sample.gif")

cloudinary.url().imageTag("sample.gif");

cloudinary.imageTag('sample.gif').toHtml();

$.cloudinary.image("sample.gif")

<Image publicId="sample.gif" >

</Image>

<cld-image publicId="sample.gif" >

</cld-image>

<cl-image public-id="sample.gif" >

</cl-image>

cloudinary.Api.UrlImgUp.BuildImageTag("sample.gif")

MediaManager.get().url().generate("sample.gif");

imageView.cldSetImage(cloudinary.createUrl().generate("sample.gif")!, cloudinary: cloudinary)

You can easily combine other image transformations with format conversion. Just make sure the format you use is supported for transformations, as per the table above. For example, to deliver a scaled down 150x100 GIF version of the sample image:

cl_image_tag("sample.gif", :width=>150, :height=>100, :crop=>"scale")

cl_image_tag("sample.gif", array("width"=>150, "height"=>100, "crop"=>"scale"))

CloudinaryImage("sample.gif").image(width=150, height=100, crop="scale")

cloudinary.image("sample.gif", {width: 150, height: 100, crop: "scale"})

cloudinary.url().transformation(new Transformation().width(150).height(100).crop("scale")).imageTag("sample.gif");

cloudinary.imageTag('sample.gif', {width: 150, height: 100, crop: "scale"}).toHtml();

$.cloudinary.image("sample.gif", {width: 150, height: 100, crop: "scale"})

<Image publicId="sample.gif" >
  <Transformation width="150" height="100" crop="scale" />
</Image>

<cld-image publicId="sample.gif" >
  <cld-transformation width="150" height="100" crop="scale" />
</cld-image>

<cl-image public-id="sample.gif" >
  <cl-transformation width="150" height="100" crop="scale">
  </cl-transformation>
</cl-image>

cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(150).Height(100).Crop("scale")).BuildImageTag("sample.gif")

MediaManager.get().url().transformation(new Transformation().width(150).height(100).crop("scale")).generate("sample.gif");

imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(150).setHeight(100).setCrop("scale")).generate("sample.gif")!, cloudinary: cloudinary)

Supported image formats

The table below summarizes the supported format types.

Fetch format

Another option for changing the format is to explicitly call the fetch_format parameter (f in URLs). This can be useful in situations where you cannot change the file extension, for example, when fetching remote images that already have a different file extension (format) as part of their URLs.

For example, to fetch a remote image from Wikimedia in JPEG format, and deliver the image in PNG format (also scaled down to a width of 400 pixels):

cl_image_tag("https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg", :width=>400, :crop=>"scale", :format=>"png", :type=>"fetch")

cl_image_tag("https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg", array("width"=>400, "crop"=>"scale", "format"=>"png", "type"=>"fetch"))

CloudinaryImage("https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg").image(width=400, crop="scale", format="png", type="fetch")

cloudinary.image("https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg", {width: 400, crop: "scale", format: "png", type: "fetch"})

cloudinary.url().transformation(new Transformation().width(400).crop("scale")).format("png").type("fetch").imageTag("https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg");

cloudinary.imageTag('https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg', {width: 400, crop: "scale", format: "png", type: "fetch"}).toHtml();

$.cloudinary.image("https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg", {width: 400, crop: "scale", format: "png", type: "fetch"})

<Image publicId="https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg" format="png" type="fetch">
  <Transformation width="400" crop="scale" />
</Image>

<cld-image publicId="https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg" format="png" type="fetch">
  <cld-transformation width="400" crop="scale" />
</cld-image>

<cl-image public-id="https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg" format="png" type="fetch">
  <cl-transformation width="400" crop="scale">
  </cl-transformation>
</cl-image>

cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(400).Crop("scale")).Format("png").Action("fetch").BuildImageTag("https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg")

MediaManager.get().url().transformation(new Transformation().width(400).crop("scale")).format("png").type("fetch").generate("https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg");

imageView.cldSetImage(cloudinary.createUrl().setFormat("png").setType( "fetch").setTransformation(CLDTransformation().setWidth(400).setCrop("scale")).generate("https://upload.wikimedia.org/wikipedia/commons/4/46/Jennifer_Lawrence_at_the_83rd_Academy_Awards.jpg")!, cloudinary: cloudinary)

Automatic format selection (f_auto)

There are a lot of formats for encoding images, with some formats better than others at compression and reducing the file size without impairing visual quality. Since different browsers support different image formats, the best solution to save bandwidth and optimize delivery time would be to deliver the best format according to the browser used by each of your visitors.

The fetch_format parameter can be set to auto (f_auto in URLs) in order to perform automatic format selection based on the requesting browser. For example, with the automatic format feature, in most cases Chrome users would receive a WebP (.webp), Internet Explorer users would receive a JPEG-XR (.jxr), and Safari users would receive a JPEG-2000 (.jp2). If a browser does not support any of these formats then the image is delivered in the format specified by the file extension.

For example, the uploaded jpg image named sample scaled down to a width of 500 pixels and delivered as WebP to Chrome browsers (22.4 KB), JPEG-XR to Internet Explorer browsers (48 KB), or as a regular JPEG (57.5 KB) to browsers that support neither format:

cl_image_tag("sample.jpg", :width=>500, :fetch_format=>:auto, :crop=>"scale")

cl_image_tag("sample.jpg", array("width"=>500, "fetch_format"=>"auto", "crop"=>"scale"))

CloudinaryImage("sample.jpg").image(width=500, fetch_format="auto", crop="scale")

cloudinary.image("sample.jpg", {width: 500, fetch_format: "auto", crop: "scale"})

cloudinary.url().transformation(new Transformation().width(500).fetchFormat("auto").crop("scale")).imageTag("sample.jpg");

cloudinary.imageTag('sample.jpg', {width: 500, fetchFormat: "auto", crop: "scale"}).toHtml();

$.cloudinary.image("sample.jpg", {width: 500, fetch_format: "auto", crop: "scale"})

<Image publicId="sample.jpg" >
  <Transformation width="500" fetchFormat="auto" crop="scale" />
</Image>

<cld-image publicId="sample.jpg" >
  <cld-transformation width="500" fetchFormat="auto" crop="scale" />
</cld-image>

<cl-image public-id="sample.jpg" >
  <cl-transformation width="500" fetch-format="auto" crop="scale">
  </cl-transformation>
</cl-image>

cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(500).FetchFormat("auto").Crop("scale")).BuildImageTag("sample.jpg")

MediaManager.get().url().transformation(new Transformation().width(500).fetchFormat("auto").crop("scale")).generate("sample.jpg");

imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(500).setFetchFormat("auto").setCrop("scale")).generate("sample.jpg")!, cloudinary: cloudinary)

Resizing and cropping images

You can resize and crop images in order to match the graphic design of your web site or mobile application. Whether images are uploaded in your server-side code or by your users, the original hi-res images are stored in the cloud for further processing and management. You can then dynamically create multiple resized, cropped and manipulated images on-the-fly and deliver them via dynamic URLs.

When changing the dimensions of an uploaded image by setting the image's height, width, and/or aspect ratio you need to decide how to resize or crop the image to fit into the requested size. Use the crop parameter for selecting the resize/crop mode (c in URLs). Cloudinary supports the following image resize/crop modes:

Some of the cropping modes keep only a certain part of the original image in the resulting image. By default, the center of the image is kept in the crop, but this is not always ideal. To keep the parts of the image that are important to you, you can use the gravity parameter. For example, you can specify to keep faces, text, or certain objects in the crop, or gravitate towards an automatically-determined area of interest. You can also guide the crop towards areas of your image defined by compass points, for example, north to keep the top part of the image, or south_east to keep the bottom-right part. Additionally, if you know the coordinates of the area you want to keep, you can explicitly specify these.

Setting the resize dimensions

You can set the target dimensions of your resized image by specifying width, height, and/or the target aspect ratio.

• Using an integer value for width or height sets the new dimension to that number in pixels. For example, w_150 sets the width to exactly 150 pixels.
• Using a decimal value for width or height sets the new dimension as a multiple of the original dimension. For example, w_0.5 sets the width to half the original width.
• Using ih or iw as values sets the dimension to the initial height or initial width of the original image respectively. For example, w_iw sets the width to the same value as the original width of the image. This may be useful when applying chained transformations or setting the dimensions of an overlay.
• Aspect ratios are specified as a decimal number, where 1.0 is a perfect square. For example, ar_0.56 defines 9:16 portrait dimensions that would work well for most mobile phones.

• In most cases, you will specify both width and height or width/height along with an aspect ratio to define the exact required dimensions. However, in rare cases, you may choose to specify only one of these 3 resize qualifiers, and Cloudinary will automatically determine the missing dimension as follows:

  • If you provide only width or only height, then the other dimension is automatically calculated to deliver the original aspect ratio. For example, if your original asset is 400*600, then specifying c_crop,w_200 is the same as specifying c_crop,w_200,h_300. Supported for all resize and crop modes.
    
  • If you provide only the aspect ratio: If ar > 1, the original width is maintained and the height is cropped to deliver the requested ratio. If ar < 1, the original height is maintained, and the width is cropped accordingly. Supported for modes that support cropping out part of the image (crop, the fill modes, the pad modes, and thumb). Not supported for imagga_crop.

Examples of applying different crop modes

The following examples show the same image resized to a width and height of 200 pixels, using different methods of cropping.

The original image is 640 x 426 pixels:

Resizing the image to 200 x 200 pixels, using crop, scale, fill and pad results in the following images:

c_crop,h_200,w_200 c_scale,h_200,w_200

c_fill,h_200,w_200 c_pad,h_200,w_200

The URL with the c_crop transformation takes this form:

cl_image_tag("docs/models.jpg", :height=>200, :width=>200, :crop=>"crop")

cl_image_tag("docs/models.jpg", array("height"=>200, "width"=>200, "crop"=>"crop"))

CloudinaryImage("docs/models.jpg").image(height=200, width=200, crop="crop")

cloudinary.image("docs/models.jpg", {height: 200, width: 200, crop: "crop"})

cloudinary.url().transformation(new Transformation().height(200).width(200).crop("crop")).imageTag("docs/models.jpg");

cloudinary.imageTag('docs/models.jpg', {height: 200, width: 200, crop: "crop"}).toHtml();

$.cloudinary.image("docs/models.jpg", {height: 200, width: 200, crop: "crop"})

<Image publicId="docs/models.jpg" >
  <Transformation height="200" width="200" crop="crop" />
</Image>

<cld-image publicId="docs/models.jpg" >
  <cld-transformation height="200" width="200" crop="crop" />
</cld-image>

<cl-image public-id="docs/models.jpg" >
  <cl-transformation height="200" width="200" crop="crop">
  </cl-transformation>
</cl-image>

cloudinary.Api.UrlImgUp.Transform(new Transformation().Height(200).Width(200).Crop("crop")).BuildImageTag("docs/models.jpg")

MediaManager.get().url().transformation(new Transformation().height(200).width(200).crop("crop")).generate("docs/models.jpg");

imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setHeight(200).setWidth(200).setCrop("crop")).generate("docs/models.jpg")!, cloudinary: cloudinary)

The following sections explain how each of the crop modes behave.

scale

Change the size of the image exactly to the given width and height without necessarily retaining the original aspect ratio: all original image parts are visible but might be stretched or shrunk. If only the width or height is given, then the image is scaled to the new dimension while retaining the original aspect ratio, unless you also include the ignore_aspect_ratio flag.

Examples of scaling the uploaded image named sample:

1. Scaled to a width of 150 pixels (maintains the aspect ratio by default):

   URLRubyPHPPythonNode.jsJavaJSjQueryReactVue.jsAngular.NETAndroidiOSAll

   URL:

   Copy to clipboard

   https://res.cloudinary.com/demo/image/upload/w_150,c_scale/sample.jpg

   Ruby:

   Copy to clipboard

   cl_image_tag("sample.jpg", :width=>150, :crop=>"scale")

   PHP:

   Copy to clipboard

   cl_image_tag("sample.jpg", array("width"=>150, "crop"=>"scale"))

   Python:

   Copy to clipboard

   CloudinaryImage("sample.jpg").image(width=150, crop="scale")

   Node.js:

   Copy to clipboard

   cloudinary.image("sample.jpg", {width: 150, crop: "scale"})

   Java:

   Copy to clipboard

   cloudinary.url().transformation(new Transformation().width(150).crop("scale")).imageTag("sample.jpg");

   JS:

   Copy to clipboard

   cloudinary.imageTag('sample.jpg', {width: 150, crop: "scale"}).toHtml();

   jQuery:

   Copy to clipboard

   $.cloudinary.image("sample.jpg", {width: 150, crop: "scale"})

   React:

   Copy to clipboard

   <Image publicId="sample.jpg" >
     <Transformation width="150" crop="scale" />
   </Image>

   Vue.js:

   Copy to clipboard

   <cld-image publicId="sample.jpg" >
     <cld-transformation width="150" crop="scale" />
   </cld-image>

   Angular:

   Copy to clipboard

   <cl-image public-id="sample.jpg" >
     <cl-transformation width="150" crop="scale">
     </cl-transformation>
   </cl-image>

   .NET:

   Copy to clipboard

   cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(150).Crop("scale")).BuildImageTag("sample.jpg")

   Android:

   Copy to clipboard

   MediaManager.get().url().transformation(new Transformation().width(150).crop("scale")).generate("sample.jpg");

   iOS:

   Copy to clipboard

   imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(150).setCrop("scale")).generate("sample.jpg")!, cloudinary: cloudinary)

   

2. Scaled to a width and height of 150 pixels without maintaining the aspect ratio:

   URLRubyPHPPythonNode.jsJavaJSjQueryReactVue.jsAngular.NETAndroidiOSAll

   URL:

   Copy to clipboard

   https://res.cloudinary.com/demo/image/upload/w_150,h_150,c_scale/sample.jpg

   Ruby:

   Copy to clipboard

   cl_image_tag("sample.jpg", :width=>150, :height=>150, :crop=>"scale")

   PHP:

   Copy to clipboard

   cl_image_tag("sample.jpg", array("width"=>150, "height"=>150, "crop"=>"scale"))

   Python:

   Copy to clipboard

   CloudinaryImage("sample.jpg").image(width=150, height=150, crop="scale")

   Node.js:

   Copy to clipboard

   cloudinary.image("sample.jpg", {width: 150, height: 150, crop: "scale"})

   Java:

   Copy to clipboard

   cloudinary.url().transformation(new Transformation().width(150).height(150).crop("scale")).imageTag("sample.jpg");

   JS:

   Copy to clipboard

   cloudinary.imageTag('sample.jpg', {width: 150, height: 150, crop: "scale"}).toHtml();

   jQuery:

   Copy to clipboard

   $.cloudinary.image("sample.jpg", {width: 150, height: 150, crop: "scale"})

   React:

   Copy to clipboard

   <Image publicId="sample.jpg" >
     <Transformation width="150" height="150" crop="scale" />
   </Image>

   Vue.js:

   Copy to clipboard

   <cld-image publicId="sample.jpg" >
     <cld-transformation width="150" height="150" crop="scale" />
   </cld-image>

   Angular:

   Copy to clipboard

   <cl-image public-id="sample.jpg" >
     <cl-transformation width="150" height="150" crop="scale">
     </cl-transformation>
   </cl-image>

   .NET:

   Copy to clipboard

   cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(150).Height(150).Crop("scale")).BuildImageTag("sample.jpg")

   Android:

   Copy to clipboard

   MediaManager.get().url().transformation(new Transformation().width(150).height(150).crop("scale")).generate("sample.jpg");

   iOS:

   Copy to clipboard

   imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(150).setHeight(150).setCrop("scale")).generate("sample.jpg")!, cloudinary: cloudinary)

   

3. Scaled to a width of 25% (maintains the aspect ratio by default):

   URLRubyPHPPythonNode.jsJavaJSjQueryReactVue.jsAngular.NETAndroidiOSAll

   URL:

   Copy to clipboard

   https://res.cloudinary.com/demo/image/upload/w_0.25,c_scale/sample.jpg

   Ruby:

   Copy to clipboard

   cl_image_tag("sample.jpg", :width=>0.25, :crop=>"scale")

   PHP:

   Copy to clipboard

   cl_image_tag("sample.jpg", array("width"=>"0.25", "crop"=>"scale"))

   Python:

   Copy to clipboard

   CloudinaryImage("sample.jpg").image(width="0.25", crop="scale")

   Node.js:

   Copy to clipboard

   cloudinary.image("sample.jpg", {width: "0.25", crop: "scale"})

   Java:

   Copy to clipboard

   cloudinary.url().transformation(new Transformation().width(0.25).crop("scale")).imageTag("sample.jpg");

   JS:

   Copy to clipboard

   cloudinary.imageTag('sample.jpg', {width: "0.25", crop: "scale"}).toHtml();

   jQuery:

   Copy to clipboard

   $.cloudinary.image("sample.jpg", {width: "0.25", crop: "scale"})

   React:

   Copy to clipboard

   <Image publicId="sample.jpg" >
     <Transformation width="0.25" crop="scale" />
   </Image>

   Vue.js:

   Copy to clipboard

   <cld-image publicId="sample.jpg" >
     <cld-transformation width="0.25" crop="scale" />
   </cld-image>

   Angular:

   Copy to clipboard

   <cl-image public-id="sample.jpg" >
     <cl-transformation width="0.25" crop="scale">
     </cl-transformation>
   </cl-image>

   .NET:

   Copy to clipboard

   cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(0.25).Crop("scale")).BuildImageTag("sample.jpg")

   Android:

   Copy to clipboard

   MediaManager.get().url().transformation(new Transformation().width(0.25).crop("scale")).generate("sample.jpg");

   iOS:

   Copy to clipboard

   imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(0.25).setCrop("scale")).generate("sample.jpg")!, cloudinary: cloudinary)

   

fit

The image is resized so that it takes up as much space as possible within a bounding box defined by the given width and height parameters. The original aspect ratio is retained and all of the original image is visible.

For example, the uploaded image named sample is resized to fit within a width and height of 250 pixels while retaining the aspect ratio:

cl_image_tag("sample.jpg", :width=>250, :height=>250, :crop=>"fit")

cl_image_tag("sample.jpg", array("width"=>250, "height"=>250, "crop"=>"fit"))

CloudinaryImage("sample.jpg").image(width=250, height=250, crop="fit")

cloudinary.image("sample.jpg", {width: 250, height: 250, crop: "fit"})

cloudinary.url().transformation(new Transformation().width(250).height(250).crop("fit")).imageTag("sample.jpg");

cloudinary.imageTag('sample.jpg', {width: 250, height: 250, crop: "fit"}).toHtml();

$.cloudinary.image("sample.jpg", {width: 250, height: 250, crop: "fit"})

<Image publicId="sample.jpg" >
  <Transformation width="250" height="250" crop="fit" />
</Image>

<cld-image publicId="sample.jpg" >
  <cld-transformation width="250" height="250" crop="fit" />
</cld-image>

<cl-image public-id="sample.jpg" >
  <cl-transformation width="250" height="250" crop="fit">
  </cl-transformation>
</cl-image>

cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(250).Height(250).Crop("fit")).BuildImageTag("sample.jpg")

MediaManager.get().url().transformation(new Transformation().width(250).height(250).crop("fit")).generate("sample.jpg");

imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(250).setHeight(250).setCrop("fit")).generate("sample.jpg")!, cloudinary: cloudinary)

limit

Same as the fit mode but only if the original image is larger than the given limit (width and height), in which case the image is scaled down so that it takes up as much space as possible within a bounding box defined by the given width and height parameters. The original aspect ratio is retained and all of the original image is visible. This mode doesn't scale up the image if your requested dimensions are larger than the original image's.

For example, the uploaded jpg image named sample limited to a width and height of 250 pixels while retaining the aspect ratio:

cl_image_tag("sample.jpg", :width=>250, :height=>250, :crop=>"limit")

cl_image_tag("sample.jpg", array("width"=>250, "height"=>250, "crop"=>"limit"))

CloudinaryImage("sample.jpg").image(width=250, height=250, crop="limit")

cloudinary.image("sample.jpg", {width: 250, height: 250, crop: "limit"})

cloudinary.url().transformation(new Transformation().width(250).height(250).crop("limit")).imageTag("sample.jpg");

cloudinary.imageTag('sample.jpg', {width: 250, height: 250, crop: "limit"}).toHtml();

$.cloudinary.image("sample.jpg", {width: 250, height: 250, crop: "limit"})

<Image publicId="sample.jpg" >
  <Transformation width="250" height="250" crop="limit" />
</Image>

<cld-image publicId="sample.jpg" >
  <cld-transformation width="250" height="250" crop="limit" />
</cld-image>

<cl-image public-id="sample.jpg" >
  <cl-transformation width="250" height="250" crop="limit">
  </cl-transformation>
</cl-image>

cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(250).Height(250).Crop("limit")).BuildImageTag("sample.jpg")

MediaManager.get().url().transformation(new Transformation().width(250).height(250).crop("limit")).generate("sample.jpg");

imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(250).setHeight(250).setCrop("limit")).generate("sample.jpg")!, cloudinary: cloudinary)

mfit (minimum fit)

Same as the fit mode but only if the original image is smaller than the given 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 given width and height parameters. The original aspect ratio is retained 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.

For example, attempting to fit the uploaded image named sample to a minimum width and height of 250 pixels while retaining the aspect ratio, results in delivering the original larger image:

cl_image_tag("sample.jpg", :width=>250, :height=>250, :crop=>"mfit")

cl_image_tag("sample.jpg", array("width"=>250, "height"=>250, "crop"=>"mfit"))

CloudinaryImage("sample.jpg").image(width=250, height=250, crop="mfit")

cloudinary.image("sample.jpg", {width: 250, height: 250, crop: "mfit"})

cloudinary.url().transformation(new Transformation().width(250).height(250).crop("mfit")).imageTag("sample.jpg");

cloudinary.imageTag('sample.jpg', {width: 250, height: 250, crop: "mfit"}).toHtml();

$.cloudinary.image("sample.jpg", {width: 250, height: 250, crop: "mfit"})

<Image publicId="sample.jpg" >
  <Transformation width="250" height="250" crop="mfit" />
</Image>

<cld-image publicId="sample.jpg" >
  <cld-transformation width="250" height="250" crop="mfit" />
</cld-image>

<cl-image public-id="sample.jpg" >
  <cl-transformation width="250" height="250" crop="mfit">
  </cl-transformation>
</cl-image>

cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(250).Height(250).Crop("mfit")).BuildImageTag("sample.jpg")

MediaManager.get().url().transformation(new Transformation().width(250).height(250).crop("mfit")).generate("sample.jpg");

imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(250).setHeight(250).setCrop("mfit")).generate("sample.jpg")!, cloudinary: cloudinary)

pad

Resize the image to fill the given width and height while retaining the original aspect ratio and with all of the original image visible. If the proportions of the original image do not match the given width and height, padding is added to the image to reach the required size. You can also specify where the original image is placed by using the gravity parameter (set to center by default), and specify the color of the background in the case that padding is added.

For example, the uploaded jpg image named sample padded with a black background to a width and height of 250 pixels:

cl_image_tag("sample.jpg", :width=>250, :height=>250, :background=>"black", :crop=>"pad")

cl_image_tag("sample.jpg", array("width"=>250, "height"=>250, "background"=>"black", "crop"=>"pad"))

CloudinaryImage("sample.jpg").image(width=250, height=250, background="black", crop="pad")

cloudinary.image("sample.jpg", {width: 250, height: 250, background: "black", crop: "pad"})

cloudinary.url().transformation(new Transformation().width(250).height(250).background("black").crop("pad")).imageTag("sample.jpg");

cloudinary.imageTag('sample.jpg', {width: 250, height: 250, background: "black", crop: "pad"}).toHtml();

$.cloudinary.image("sample.jpg", {width: 250, height: 250, background: "black", crop: "pad"})

<Image publicId="sample.jpg" >
  <Transformation width="250" height="250" background="black" crop="pad" />
</Image>

<cld-image publicId="sample.jpg" >
  <cld-transformation width="250" height="250" background="black" crop="pad" />
</cld-image>

<cl-image public-id="sample.jpg" >
  <cl-transformation width="250" height="250" background="black" crop="pad">
  </cl-transformation>
</cl-image>