Transformation flags

Set one or more flags that alter the default transformation behavior with the flag parameter (fl in URLs). You can set multiple flags by separating the individual flags with a dot (.).

There are a large number of flags available, which can be roughly divided into the following types of flags:

For a full list of all the supported flags, see the Image transformations reference table.

Cropping and positioning flags

Parameter Description
relative fl_relative modifies percentage-based width & height parameters of overlays and underlays (e.g., 1.0) to be relative to the containing image instead of the added layer.
region_relative fl_region_relative modifies percentage-based width & height parameters of overlays and underlays (e.g., 1.0) to be relative to the overlaid region. Currently regions are only defined when using gravity set to one of the face detection settings or 'custom'.
cutter fl_cutter trims pixels according to the transparency levels of a given overlay image. Whenever the overlay image is opaque, the original is shown, and wherever the overlay is transparent, the result will be transparent as well.

Try the Custom shapes cropping cookbook receipe for a step-by-step walk through of cropping images to custom shapes using fl_cutter.
Try the Use images as text textures cookbook receipe for a step-by-step walk through of filling a text overlay with an image using fl_cutter.
Try the Turn your pictures in to old photographs cookbook receipe for a step-by-step walk through of combining the cutter flag with the sepia effect to convert any modern photo into a torn old-time style photo.
clip fl_clip trims pixels according to a clipping path included in the original image metadata (e.g., manually created using software such as Adobe PhotoShop).
ignore_aspect_ratio fl_ignore_aspect_ratio allows you to specify only width or height so the value of the second axis remains as is and is not recalculated to maintain the aspect ratio of the original image.
no_overflow fl_no_overflow prevents extending the image canvas beyond the original dimensions when overlaying text and other images.
tiled fl_tiled tiles the an overlay over the entire image.

Examples:

  • To deliver the cloudinary_icon image with a height of 150 pixels and ignoring the aspect ratio (width is not automatically adjusted):

Ruby:
cl_image_tag("cloudinary_icon.jpg", :height=>150, :flags=>"ignore_aspect_ratio", :crop=>"scale")
PHP:
cl_image_tag("cloudinary_icon.jpg", array("height"=>150, "flags"=>"ignore_aspect_ratio", "crop"=>"scale"))
Python:
CloudinaryImage("cloudinary_icon.jpg").image(height=150, flags="ignore_aspect_ratio", crop="scale")
Node.js:
cloudinary.image("cloudinary_icon.jpg", {height: 150, flags: "ignore_aspect_ratio", crop: "scale"})
Java:
cloudinary.url().transformation(new Transformation().height(150).flags("ignore_aspect_ratio").crop("scale")).imageTag("cloudinary_icon.jpg");
JS:
cloudinary.imageTag('cloudinary_icon.jpg', {height: 150, flags: "ignore_aspect_ratio", crop: "scale"}).toHtml();
jQuery:
$.cloudinary.image("cloudinary_icon.jpg", {height: 150, flags: "ignore_aspect_ratio", crop: "scale"})
React:
<Image publicId="cloudinary_icon.jpg" >
  <Transformation height="150" flags="ignore_aspect_ratio" crop="scale" />
</Image>
Angular:
<cl-image public-id="cloudinary_icon.jpg" >
  <cl-transformation height="150" flags="ignore_aspect_ratio" crop="scale">
  </cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Height(150).Flags("ignore_aspect_ratio").Crop("scale")).BuildImageTag("cloudinary_icon.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().height(150).flags("ignore_aspect_ratio").crop("scale")).generate("cloudinary_icon.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setHeight(150).setFlags("ignore_aspect_ratio").setCrop("scale")).generate("cloudinary_icon.jpg")!, cloudinary: cloudinary)
Image with width of 200 pixels

  • To add the cloudinary_icon overlay to the flower image, where the overlay is scaled to 20% of the width of the base image:

Ruby:
cl_image_tag("flower.jpg", :overlay=>"cloudinary_icon", :width=>0.2, :flags=>"relative")
PHP:
cl_image_tag("flower.jpg", array("overlay"=>"cloudinary_icon", "width"=>0.2, "flags"=>"relative"))
Python:
CloudinaryImage("flower.jpg").image(overlay="cloudinary_icon", width=0.2, flags="relative")
Node.js:
cloudinary.image("flower.jpg", {overlay: "cloudinary_icon", width: "0.2", flags: "relative"})
Java:
cloudinary.url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon")).width(0.2).flags("relative")).imageTag("flower.jpg");
JS:
cloudinary.imageTag('flower.jpg', {overlay: new cloudinary.Layer().publicId("cloudinary_icon"), width: "0.2", flags: "relative"}).toHtml();
jQuery:
$.cloudinary.image("flower.jpg", {overlay: new cloudinary.Layer().publicId("cloudinary_icon"), width: "0.2", flags: "relative"})
React:
<Image publicId="flower.jpg" >
  <Transformation overlay="cloudinary_icon" width="0.2" flags="relative" />
</Image>
Angular:
<cl-image public-id="flower.jpg" >
  <cl-transformation overlay="cloudinary_icon" width="0.2" flags="relative">
  </cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new Layer().PublicId("cloudinary_icon")).Width(0.2).Flags("relative")).BuildImageTag("flower.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon")).width(0.2).flags("relative")).generate("flower.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("cloudinary_icon").setWidth(0.2).setFlags("relative")).generate("flower.jpg")!, cloudinary: cloudinary)
Overlay added with width set to 50% of base image

Delivery and image format flags

Parameter Description
progressive[:mode] fl_progressive generates a JPEG image using the progressive (interlaced) JPEG format. This format allows the browser to quickly show a low-quality rendering of the image until the full quality image is loaded. The parameter also accepts a mode value to determine a specific progressive outcome as follows:

  • progressive:semi - a smart optimization of the decoding time, compression level and progressive rendering (less iterations). This is the default mode when using q_auto.
  • progressive:steep - delivers a preview very quickly, and in a single later phase improves the image to the required resolution.
  • progressive:none - use this to deliver a non-progressive image. This is the default mode when setting a specific value for quality.
png8 fl_png8 generates PNG images in the PNG8 format instead of the default PNG24 format, reducing the file size significantly, but limited to 256 colors.
immutable_cache fl_immutable_cache sets the cache-control to immutable for the image, which tells the browser that the image does not have to be revalidated with the server when the page is refreshed, and can be loaded directly from the cache. Currently supported only by Firefox.
awebp When converting animated GIF images to the WebP format, fl_awebp generates an Animated WebP from all the frames in the animated GIF file instead of only from the first still frame of the GIF.
lossy fl_lossy tells Cloudinary to use lossy compression when delivering animated GIF files. This flag can also be used as a conditional flag for delivering PNG files: it tells Cloudinary to deliver the image in PNG format (as requested) unless there is no transparency channel - in which case deliver in JPEG format.
attachment fl_attachment delivers the image as an attachment for download. When the image's URL is accessed, this flag instructs the browser to download and save the image instead of embedding it and displaying it on a web page.

You can optionally set the attachment file's name by appending a colon and then the new file name (e.g., attachment:new_name or fl_attachment:new_namein URLs). If omitted, the filename of the file that was originally uploaded will be used as the attachment file name (and not the public_id value) unless the discard_original_filename parameter was set during the file upload.

You can also use this flag with raw files to specify a custom filename for the download. In the flag parameter, specify only the filename without an extension. The downloaded file extension will match the raw file's extension.

Note that you can include a period (.) character as part of the filename (prior to the automatically appended extension) by double-escaping the period character: %252E. (Other special characters in the filename can be single-escaped).
getinfo fl_getinfo returns metadata of the input asset and of the transformed output asset in JSON instead of the transformed image.

When used with g_auto, returns the proposed g_auto cropping coordinates.

Examples:

  • To deliver an image scaled to a width of 300 pixels in PNG8 format instead of PNG24:

    Ruby:
    cl_image_tag("sample.png", :width=>300, :flags=>"png8", :crop=>"scale")
    PHP:
    cl_image_tag("sample.png", array("width"=>300, "flags"=>"png8", "crop"=>"scale"))
    Python:
    CloudinaryImage("sample.png").image(width=300, flags="png8", crop="scale")
    Node.js:
    cloudinary.image("sample.png", {width: 300, flags: "png8", crop: "scale"})
    Java:
    cloudinary.url().transformation(new Transformation().width(300).flags("png8").crop("scale")).imageTag("sample.png");
    JS:
    cloudinary.imageTag('sample.png', {width: 300, flags: "png8", crop: "scale"}).toHtml();
    jQuery:
    $.cloudinary.image("sample.png", {width: 300, flags: "png8", crop: "scale"})
    React:
    <Image publicId="sample.png" >
      <Transformation width="300" flags="png8" crop="scale" />
    </Image>
    Angular:
    <cl-image public-id="sample.png" >
      <cl-transformation width="300" flags="png8" crop="scale">
      </cl-transformation>
    </cl-image>
    .Net:
    cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(300).Flags("png8").Crop("scale")).BuildImageTag("sample.png")
    Android:
    MediaManager.get().url().transformation(new Transformation().width(300).flags("png8").crop("scale")).generate("sample.png");
    iOS:
    imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(300).setFlags("png8").setCrop("scale")).generate("sample.png")!, cloudinary: cloudinary)
    Image in PNG8 format

  • To deliver an image as an attachment with a custom filename (clicking the image downloads the file instead of opening the image in a new browser window).

    Ruby:
    cl_image_tag("sample.jpg", :flags=>"attachment:pretty_flower", :fetch_format=>:auto)
    PHP:
    cl_image_tag("sample.jpg", array("flags"=>"attachment:pretty_flower", "fetch_format"=>"auto"))
    Python:
    CloudinaryImage("sample.jpg").image(flags="attachment:pretty_flower", fetch_format="auto")
    Node.js:
    cloudinary.image("sample.jpg", {flags: "attachment:pretty_flower", fetch_format: "auto"})
    Java:
    cloudinary.url().transformation(new Transformation().flags("attachment:pretty_flower").fetchFormat("auto")).imageTag("sample.jpg");
    JS:
    cloudinary.imageTag('sample.jpg', {flags: "attachment:pretty_flower", fetchFormat: "auto"}).toHtml();
    jQuery:
    $.cloudinary.image("sample.jpg", {flags: "attachment:pretty_flower", fetch_format: "auto"})
    React:
    <Image publicId="sample.jpg" >
      <Transformation flags="attachment:pretty_flower" fetchFormat="auto" />
    </Image>
    Angular:
    <cl-image public-id="sample.jpg" >
      <cl-transformation flags="attachment:pretty_flower" fetch-format="auto">
      </cl-transformation>
    </cl-image>
    .Net:
    cloudinary.Api.UrlImgUp.Transform(new Transformation().Flags("attachment:pretty_flower").FetchFormat("auto")).BuildImageTag("sample.jpg")
    Android:
    MediaManager.get().url().transformation(new Transformation().flags("attachment:pretty_flower").fetchFormat("auto")).generate("sample.jpg");
    iOS:
    imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setFlags("attachment:pretty_flower").setFetchFormat("auto")).generate("sample.jpg")!, cloudinary: cloudinary)

    Note that because f_auto is used, the downloaded file extension is based on the actual delivered file format (for example, .webp in Chrome), and not the extension of the URL.

Metadata and color profiles flags

Parameter Description
keep_iptc Cloudinary's default behavior is to strip all metadata when generating new image transformations. fl_keep_iptc keeps all the metadata. Note that this flag cannot be used in conjunction with the automatic quality transformation (q_auto).
keep_attribution Cloudinary's default behavior is to strip all metadata when generating new image transformations. fl_keep_attribution keeps all the copyright related fields when stripping metadata.
force_strip (Only relevant when applying an incoming transformation to an uploading image.) fl_force_striptells Cloudinary to clear all image metadata (IPTC, Exif and XMP) before storing the uploading image.
strip_profile fl_strip_profile tells Cloudinary to clear all ICC color profile data included with the image.

For example, to deliver an image scaled to a width of 300 pixels with its meta-data:

Ruby:
cl_image_tag("sample.jpg", :width=>300, :flags=>"keep_iptc", :crop=>"scale")
PHP:
cl_image_tag("sample.jpg", array("width"=>300, "flags"=>"keep_iptc", "crop"=>"scale"))
Python:
CloudinaryImage("sample.jpg").image(width=300, flags="keep_iptc", crop="scale")
Node.js:
cloudinary.image("sample.jpg", {width: 300, flags: "keep_iptc", crop: "scale"})
Java:
cloudinary.url().transformation(new Transformation().width(300).flags("keep_iptc").crop("scale")).imageTag("sample.jpg");
JS:
cloudinary.imageTag('sample.jpg', {width: 300, flags: "keep_iptc", crop: "scale"}).toHtml();
jQuery:
$.cloudinary.image("sample.jpg", {width: 300, flags: "keep_iptc", crop: "scale"})
React:
<Image publicId="sample.jpg" >
  <Transformation width="300" flags="keep_iptc" crop="scale" />
</Image>
Angular:
<cl-image public-id="sample.jpg" >
  <cl-transformation width="300" flags="keep_iptc" crop="scale">
  </cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(300).Flags("keep_iptc").Crop("scale")).BuildImageTag("sample.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(300).flags("keep_iptc").crop("scale")).generate("sample.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(300).setFlags("keep_iptc").setCrop("scale")).generate("sample.jpg")!, cloudinary: cloudinary)
Image delivered with meta-data

Overlays, PDF and text flags

Parameter Description
layer_apply fl_layer_apply applies all chained transformations, until a transformation component that includes this flag, on the last added overlay or underlay instead of applying them on the base image. See the topic on applying chained transformations to overlays for more information.
rasterize fl_rasterize reduces the image to one flat pixelated layer (as opposed to the default vector based graphic) in order to enable PDF resizing and overlay transformations.
text_no_trim text_no_trim tells Cloudinary not to automatically trim the excess space from around a dynamic text string.

For example, to add the face_left overlay to the flower image, where several components of the transformation (resize to a 200x200 circular thumbnail with face detection) need to be applied to the overlay as opposed to the base image, use fl_layer_apply:

Ruby:
cl_image_tag("flower.jpg", :transformation=>[
  {:overlay=>"face_left"},
  {:width=>200, :height=>200, :gravity=>"face", :radius=>"max", :crop=>"thumb"},
  {:flags=>"layer_apply", :gravity=>"north_east"}
  ])
PHP:
cl_image_tag("flower.jpg", array("transformation"=>array(
  array("overlay"=>"face_left"),
  array("width"=>200, "height"=>200, "gravity"=>"face", "radius"=>"max", "crop"=>"thumb"),
  array("flags"=>"layer_apply", "gravity"=>"north_east")
  )))
Python:
CloudinaryImage("flower.jpg").image(transformation=[
  {'overlay': "face_left"},
  {'width': 200, 'height': 200, 'gravity': "face", 'radius': "max", 'crop': "thumb"},
  {'flags': "layer_apply", 'gravity': "north_east"}
  ])
Node.js:
cloudinary.image("flower.jpg", {transformation: [
  {overlay: "face_left"},
  {width: 200, height: 200, gravity: "face", radius: "max", crop: "thumb"},
  {flags: "layer_apply", gravity: "north_east"}
  ]})
Java:
cloudinary.url().transformation(new Transformation()
  .overlay(new Layer().publicId("face_left")).chain()
  .width(200).height(200).gravity("face").radius("max").crop("thumb").chain()
  .flags("layer_apply").gravity("north_east")).imageTag("flower.jpg");
JS:
cloudinary.imageTag('flower.jpg', {transformation: [
  {overlay: new cloudinary.Layer().publicId("face_left")},
  {width: 200, height: 200, gravity: "face", radius: "max", crop: "thumb"},
  {flags: "layer_apply", gravity: "north_east"}
  ]}).toHtml();
jQuery:
$.cloudinary.image("flower.jpg", {transformation: [
  {overlay: new cloudinary.Layer().publicId("face_left")},
  {width: 200, height: 200, gravity: "face", radius: "max", crop: "thumb"},
  {flags: "layer_apply", gravity: "north_east"}
  ]})
React:
<Image publicId="flower.jpg" >
  <Transformation overlay="face_left" />
  <Transformation width="200" height="200" gravity="face" radius="max" crop="thumb" />
  <Transformation flags="layer_apply" gravity="north_east" />
</Image>
Angular:
<cl-image public-id="flower.jpg" >
  <cl-transformation overlay="face_left">
  </cl-transformation>
  <cl-transformation width="200" height="200" gravity="face" radius="max" crop="thumb">
  </cl-transformation>
  <cl-transformation flags="layer_apply" gravity="north_east">
  </cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Overlay(new Layer().PublicId("face_left")).Chain()
  .Width(200).Height(200).Gravity("face").Radius("max").Crop("thumb").Chain()
  .Flags("layer_apply").Gravity("north_east")).BuildImageTag("flower.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
  .overlay(new Layer().publicId("face_left")).chain()
  .width(200).height(200).gravity("face").radius("max").crop("thumb").chain()
  .flags("layer_apply").gravity("north_east")).generate("flower.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setOverlay("face_left").chain()
  .setWidth(200).setHeight(200).setGravity("face").setRadius("max").setCrop("thumb").chain()
  .setFlags("layer_apply").setGravity("north_east")).generate("flower.jpg")!, cloudinary: cloudinary)
Image with transformed overlay