Placing layers on images

Overview

Cloudinary allows you to dynamically add layers to specific locations within your images, where the new layers are added over the base image as overlays, and can also be easily transformed to suit your needs. There are multiple options for adding a new layer to a base image, either an image uploaded to your account, a remote image, or a text string.

An image layer can also be added as an underlay instead, and there are special layer applications for using layers in combination with other Cloudinary transformations.

Here are examples of some popular use cases that you can accomplish using layers (combined with other transformations). Click each image to see the URL parameters applied in each case:

Brand or watermark your images Brand or watermark
your images
Hide all detected faces Hide all
detected faces
Add personalized text Add personalized
text
Displace images on products Displace images
on products

Note
This page describes Cloudinary transformations that apply layers to a specified base image. This differs from delivering images where the original source file has layers that you might reference in a transformation.

Image overlays

Add an image over the base image with the layer parameter (l in URLs) and the public ID of a previously uploaded image (e.g., l_logo for an image with the public ID of logo). For example, adding an overlay of the image called cloudinary_icon_blue to the jpg image named sample.

Ruby:
Copy to clipboard
cl_image_tag("sample.jpg", :overlay=>"cloudinary_icon_blue")
PHP v1:
Copy to clipboard
cl_image_tag("sample.jpg", array("overlay"=>"cloudinary_icon_blue"))
PHP v2:
Copy to clipboard
(new ImageTag('sample.jpg'))
  ->overlay(Overlay::source(Source::image('cloudinary_icon_blue')));
Python:
Copy to clipboard
CloudinaryImage("sample.jpg").image(overlay="cloudinary_icon_blue")
Node.js:
Copy to clipboard
cloudinary.image("sample.jpg", {overlay: "cloudinary_icon_blue"})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon_blue"))).imageTag("sample.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('sample.jpg', {overlay: new cloudinary.Layer().publicId("cloudinary_icon_blue")}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("sample.jpg", {overlay: new cloudinary.Layer().publicId("cloudinary_icon_blue")})
React:
Copy to clipboard
<Image publicId="sample.jpg" >
  <Transformation overlay="cloudinary_icon_blue" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="sample.jpg" >
  <cld-transformation :overlay="cloudinary_icon_blue" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="sample.jpg" >
  <cl-transformation overlay="cloudinary_icon_blue">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new Layer().PublicId("cloudinary_icon_blue"))).BuildImageTag("sample.jpg")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("cloudinary_icon_blue")).generate("sample.jpg")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon_blue"))).generate("sample.jpg");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("sample.jpg")
overlay(Overlay.source(Source.image("cloudinary_icon_blue")))}.generate()
Image with overlay

Important

  • If the public ID of an image includes a folder component (e.g., the public ID of an image is animals/dog) then replace the slash with a colon when using the image as an overlay (e.g., the public ID of the image becomes animals:dog when used as an overlay).
  • When delivering public images, you can only add other public images as overlays. See the Media access control documentation for more details on delivering private and authenticated assets.

Remote image overlays

Use a remote image as an overlay by adding the fetch (or url for some SDKs) property of the layer parameter ( l_fetch: in URLs) and the base64 encoded URL of the remote image. For example, adding an overlay of the remote image https://res.cloudinary.com/demo/image/upload/logos/cloudinary_full_logo_white_small.png to the jpg image named sample.

Ruby:
Copy to clipboard
cl_image_tag("sample.jpg", :overlay=>{:url=>"https://res.cloudinary.com/demo/image/upload/logos/cloudinary_full_logo_white_small.png"})
PHP v1:
Copy to clipboard
cl_image_tag("sample.jpg", array("overlay"=>array("url"=>"https://res.cloudinary.com/demo/image/upload/logos/cloudinary_full_logo_white_small.png")))
PHP v2:
Copy to clipboard
(new ImageTag('sample.jpg'))
  ->overlay(Overlay::source(Source::fetch('https://res.cloudinary.com/demo/image/upload/logos/cloudinary_full_logo_white_small.png')));
Python:
Copy to clipboard
CloudinaryImage("sample.jpg").image(overlay={'url': "https://res.cloudinary.com/demo/image/upload/logos/cloudinary_full_logo_white_small.png"})
Node.js:
Copy to clipboard
cloudinary.image("sample.jpg", {overlay: {url: "https://res.cloudinary.com/demo/image/upload/logos/cloudinary_full_logo_white_small.png"}})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().overlay(new FetchLayer().url("https://res.cloudinary.com/demo/image/upload/logos/cloudinary_full_logo_white_small.png"))).imageTag("sample.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('sample.jpg', {overlay: new cloudinary.FetchLayer().url("https://res.cloudinary.com/demo/image/upload/logos/cloudinary_full_logo_white_small.png")}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("sample.jpg", {overlay: new cloudinary.FetchLayer().url("https://res.cloudinary.com/demo/image/upload/logos/cloudinary_full_logo_white_small.png")})
React:
Copy to clipboard
<Image publicId="sample.jpg" >
  <Transformation overlay={{url: "https://res.cloudinary.com/demo/image/upload/logos/cloudinary_full_logo_white_small.png"}} />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="sample.jpg" >
  <cld-transformation :overlay="{url: 'https://res.cloudinary.com/demo/image/upload/logos/cloudinary_full_logo_white_small.png'}" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="sample.jpg" >
  <cl-transformation overlay="fetch:aHR0cHM6Ly9yZXMuY2xvdWRpbmFyeS5jb20vZGVtby9pbWFnZS91cGxvYWQvbG9nb3MvY2xvdWRpbmFyeV9mdWxsX2xvZ29fd2hpdGVfc21hbGwucG5n">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new FetchLayer("https://res.cloudinary.com/demo/image/upload/logos/cloudinary_full_logo_white_small.png"))).BuildImageTag("sample.jpg")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("fetch:aHR0cHM6Ly9yZXMuY2xvdWRpbmFyeS5jb20vZGVtby9pbWFnZS91cGxvYWQvbG9nb3MvY2xvdWRpbmFyeV9mdWxsX2xvZ29fd2hpdGVfc21hbGwucG5n")).generate("sample.jpg")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().overlay(new FetchLayer().url("https://res.cloudinary.com/demo/image/upload/logos/cloudinary_full_logo_white_small.png"))).generate("sample.jpg");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("sample.jpg")
overlay(Overlay.source(Source.fetch("https://res.cloudinary.com/demo/image/upload/logos/cloudinary_full_logo_white_small.png")))}.generate()
Image with overlay

Note
The Cloudinary SDKs automatically generate a base64 encoded URL for a given HTTP/S URL, but if you generate the delivery URL in your own code, then you will need to supply the URL in base64 encoding with padding.

Text overlays

Add a text overlay over the base image with the text property of the layer parameter ( l_text: in URLs). The parameter also requires specifying font family and size (separated with an underscore and followed by a colon), and the text string to display. For example, to overlay the text string "Flowers" in the Arial font with a size of 80 pixels (l_text:Arial_80:Flowers):

Ruby:
Copy to clipboard
cl_image_tag("sample.jpg", :overlay=>{:font_family=>"Arial", :font_size=>80, :text=>"Flowers"})
PHP v1:
Copy to clipboard
cl_image_tag("sample.jpg", array("overlay"=>array("font_family"=>"Arial", "font_size"=>80, "text"=>"Flowers")))
PHP v2:
Copy to clipboard
(new ImageTag('sample.jpg'))
  ->overlay(Overlay::source(Source::text('Flowers', (new TextStyle('Arial', 80)))));
Python:
Copy to clipboard
CloudinaryImage("sample.jpg").image(overlay={'font_family': "Arial", 'font_size': 80, 'text': "Flowers"})
Node.js:
Copy to clipboard
cloudinary.image("sample.jpg", {overlay: {font_family: "Arial", font_size: 80, text: "Flowers"}})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().overlay(new TextLayer().fontFamily("Arial").fontSize(80).text("Flowers"))).imageTag("sample.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('sample.jpg', {overlay: new cloudinary.TextLayer().fontFamily("Arial").fontSize(80).text("Flowers")}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("sample.jpg", {overlay: new cloudinary.TextLayer().fontFamily("Arial").fontSize(80).text("Flowers")})
React:
Copy to clipboard
<Image publicId="sample.jpg" >
  <Transformation overlay={{fontFamily: "Arial", fontSize: 80, text: "Flowers"}} />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="sample.jpg" >
  <cld-transformation :overlay="{fontFamily: 'Arial', fontSize: 80, text: 'Flowers'}" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="sample.jpg" >
  <cl-transformation overlay="text:Arial_80:Flowers">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new TextLayer().FontFamily("Arial").FontSize(80).Text("Flowers"))).BuildImageTag("sample.jpg")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("text:Arial_80:Flowers")).generate("sample.jpg")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().overlay(new TextLayer().fontFamily("Arial").fontSize(80).text("Flowers"))).generate("sample.jpg");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("sample.jpg")
overlay(Overlay.source(Source.text("Flowers", TextStyle("Arial", 80))))}.generate()
Adding dynamic text to image

In addition to the required font and size styling values, you can optionally specify a variety of other CSS-like styling parameters and to further customize your text layers by specifying text color, adding line breaks, emojis and other special characters, and other text layer options.

Layer placement (gravity)

To determine the position of the new layer, you can add the gravity parameter to define a location within the base image ('center' by default). For fine tuning the exact location of the layer, you can offset the overlay from the focus of gravity by also adding the x and y coordinate parameters. These parameters accept either integer values representing the number of pixels to displace the overlay in the horizontal or vertical directions, or real values representing a percentage-based offset relative to the containing image (e.g., 0.2 for an offset of 20%).

Tip
See the Positioning with Gravity interactive demo to experiment with gravity and coordinate parameters.

For example:

  1. Add an overlay of the image called cloudinary_icon_white to the base image with gravity set to west but with a vertical offset of -100 pixels (l_cloudinary_icon_white,g_west,y_-100):

    Ruby:
    Copy to clipboard
    cl_image_tag("sample.jpg", :overlay=>"cloudinary_icon_white", :gravity=>"west", :y=>-100, :width=>0.4)
    PHP v1:
    Copy to clipboard
    cl_image_tag("sample.jpg", array("overlay"=>"cloudinary_icon_white", "gravity"=>"west", "y"=>-100, "width"=>"0.4"))
    PHP v2:
    Copy to clipboard
    (new ImageTag('sample.jpg'))
      ->overlay(
          Overlay::source(Source::image('cloudinary_icon_white')
            ->transformation((new ImageTransformation())
              ->resize(Resize::scale()->width(0.4))))
          ->position((new Position())
            ->gravity(Gravity::compass(Compass::west()))
            ->offsetY(-100)
      ));
    Python:
    Copy to clipboard
    CloudinaryImage("sample.jpg").image(overlay="cloudinary_icon_white", gravity="west", y=-100, width="0.4")
    Node.js:
    Copy to clipboard
    cloudinary.image("sample.jpg", {overlay: "cloudinary_icon_white", gravity: "west", y: -100, width: "0.4"})
    Java:
    Copy to clipboard
    cloudinary.url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon_white")).gravity("west").y(-100).width(0.4)).imageTag("sample.jpg");
    JS:
    Copy to clipboard
    cloudinary.imageTag('sample.jpg', {overlay: new cloudinary.Layer().publicId("cloudinary_icon_white"), gravity: "west", y: -100, width: "0.4"}).toHtml();
    jQuery:
    Copy to clipboard
    $.cloudinary.image("sample.jpg", {overlay: new cloudinary.Layer().publicId("cloudinary_icon_white"), gravity: "west", y: -100, width: "0.4"})
    React:
    Copy to clipboard
    <Image publicId="sample.jpg" >
      <Transformation overlay="cloudinary_icon_white" gravity="west" y="-100" width="0.4" />
    </Image>
    Vue.js:
    Copy to clipboard
    <cld-image publicId="sample.jpg" >
      <cld-transformation :overlay="cloudinary_icon_white" gravity="west" y="-100" width="0.4" />
    </cld-image>
    Angular:
    Copy to clipboard
    <cl-image public-id="sample.jpg" >
      <cl-transformation overlay="cloudinary_icon_white" gravity="west" y="-100" width="0.4">
      </cl-transformation>
    </cl-image>
    .NET:
    Copy to clipboard
    cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new Layer().PublicId("cloudinary_icon_white")).Gravity("west").Y(-100).Width(0.4)).BuildImageTag("sample.jpg")
    iOS:
    Copy to clipboard
    imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("cloudinary_icon_white").setGravity("west").setY(-100).setWidth(0.4)).generate("sample.jpg")!, cloudinary: cloudinary)
    Android:
    Copy to clipboard
    MediaManager.get().url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon_white")).gravity("west").y(-100).width(0.4)).generate("sample.jpg");
    Kotlin:
    Copy to clipboard
    cloudinary.image {
    publicId("sample.jpg")
    overlay(Overlay.source(Source.image("cloudinary_icon_white") {
    transformation(ImageTransformation {
    resize(Resize.scale() {
    width(0.4f)
    })
    })
    }) {
    position(Position {
    gravity(Gravity.compass(Compass.west()))
    offsetY(-100)
    })
    })}.generate()
    Image with precisely placed overlay

  2. Add the text string "Welcome" in the Times font with a size of 100 pixels at a vertical distance of 5% from the bottom of the image (l_text:Times_100:Welcome,g_south,y_0.05):

    Ruby:
    Copy to clipboard
    cl_image_tag("sample.jpg", :overlay=>{:font_family=>"Times", :font_size=>100, :text=>"Welcome"}, :gravity=>"south", :y=>0.05)
    PHP v1:
    Copy to clipboard
    cl_image_tag("sample.jpg", array("overlay"=>array("font_family"=>"Times", "font_size"=>100, "text"=>"Welcome"), "gravity"=>"south", "y"=>"0.05"))
    PHP v2:
    Copy to clipboard
    (new ImageTag('sample.jpg'))
      ->overlay(Overlay::source(Source::text('Welcome', (new TextStyle('Times', 100))))
        ->position((new Position())
          ->gravity(Gravity::compass(Compass::south()))
          ->offsetY(0.05)));
    Python:
    Copy to clipboard
    CloudinaryImage("sample.jpg").image(overlay={'font_family': "Times", 'font_size': 100, 'text': "Welcome"}, gravity="south", y="0.05")
    Node.js:
    Copy to clipboard
    cloudinary.image("sample.jpg", {overlay: {font_family: "Times", font_size: 100, text: "Welcome"}, gravity: "south", y: "0.05"})
    Java:
    Copy to clipboard
    cloudinary.url().transformation(new Transformation().overlay(new TextLayer().fontFamily("Times").fontSize(100).text("Welcome")).gravity("south").y(0.05)).imageTag("sample.jpg");
    JS:
    Copy to clipboard
    cloudinary.imageTag('sample.jpg', {overlay: new cloudinary.TextLayer().fontFamily("Times").fontSize(100).text("Welcome"), gravity: "south", y: "0.05"}).toHtml();
    jQuery:
    Copy to clipboard
    $.cloudinary.image("sample.jpg", {overlay: new cloudinary.TextLayer().fontFamily("Times").fontSize(100).text("Welcome"), gravity: "south", y: "0.05"})
    React:
    Copy to clipboard
    <Image publicId="sample.jpg" >
      <Transformation overlay={{fontFamily: "Times", fontSize: 100, text: "Welcome"}} gravity="south" y="0.05" />
    </Image>
    Vue.js:
    Copy to clipboard
    <cld-image publicId="sample.jpg" >
      <cld-transformation :overlay="{fontFamily: 'Times', fontSize: 100, text: 'Welcome'}" gravity="south" y="0.05" />
    </cld-image>
    Angular:
    Copy to clipboard
    <cl-image public-id="sample.jpg" >
      <cl-transformation overlay="text:Times_100:Welcome" gravity="south" y="0.05">
      </cl-transformation>
    </cl-image>
    .NET:
    Copy to clipboard
    cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new TextLayer().FontFamily("Times").FontSize(100).Text("Welcome")).Gravity("south").Y(0.05)).BuildImageTag("sample.jpg")
    iOS:
    Copy to clipboard
    imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("text:Times_100:Welcome").setGravity("south").setY(0.05)).generate("sample.jpg")!, cloudinary: cloudinary)
    Android:
    Copy to clipboard
    MediaManager.get().url().transformation(new Transformation().overlay(new TextLayer().fontFamily("Times").fontSize(100).text("Welcome")).gravity("south").y(0.05)).generate("sample.jpg");
    Kotlin:
    Copy to clipboard
    cloudinary.image {
    publicId("sample.jpg")
    overlay(Overlay.source(Source.text("Welcome", TextStyle("Times", 100))) {
    position(Position {
    gravity(Gravity.compass(Compass.south()))
    offsetY(0.05f)
    })
    })}.generate()
    Welcome text added to image

Tip
Instead of adding your layer image to a single, specific location, you can tile your layer image over the entire base image. This is often useful when using image layers for watermarking.

Overlays on special positions

The gravity parameter can also be set to a custom region within an image, which becomes the focus when placing the overlay. These 'special positions' are locations within the image that are either automatically detected by Cloudinary (e.g., a face), custom coordinates that were previously specified (e.g., as part of the image upload method), or detected by one of the Cloudinary add-ons (e.g., eyes or text within the image).

For a full list of all the special positions available to use for placing overlays with the gravity parameter, see the <special position> section in the transformation reference guide.

For example:

  1. Add an overlay of the golden_star image over all faces detected in the couple image:

    Ruby:
    Copy to clipboard
    cl_image_tag("couple.jpg", :overlay=>"golden_star", :gravity=>"faces", :width=>50)
    PHP v1:
    Copy to clipboard
    cl_image_tag("couple.jpg", array("overlay"=>"golden_star", "gravity"=>"faces", "width"=>50))
    PHP v2:
    Copy to clipboard
    (new ImageTag('couple.jpg'))
      ->overlay(
          Overlay::source(Source::image('golden_star')
            ->transformation((new ImageTransformation())
              ->resize(Resize::scale()->width(50))))
          ->position((new Position())
            ->gravity(Gravity::focusOn(FocusOn::faces()))
      ));
    Python:
    Copy to clipboard
    CloudinaryImage("couple.jpg").image(overlay="golden_star", gravity="faces", width=50)
    Node.js:
    Copy to clipboard
    cloudinary.image("couple.jpg", {overlay: "golden_star", gravity: "faces", width: 50})
    Java:
    Copy to clipboard
    cloudinary.url().transformation(new Transformation().overlay(new Layer().publicId("golden_star")).gravity("faces").width(50)).imageTag("couple.jpg");
    JS:
    Copy to clipboard
    cloudinary.imageTag('couple.jpg', {overlay: new cloudinary.Layer().publicId("golden_star"), gravity: "faces", width: 50}).toHtml();
    jQuery:
    Copy to clipboard
    $.cloudinary.image("couple.jpg", {overlay: new cloudinary.Layer().publicId("golden_star"), gravity: "faces", width: 50})
    React:
    Copy to clipboard
    <Image publicId="couple.jpg" >
      <Transformation overlay="golden_star" gravity="faces" width="50" />
    </Image>
    Vue.js:
    Copy to clipboard
    <cld-image publicId="couple.jpg" >
      <cld-transformation :overlay="golden_star" gravity="faces" width="50" />
    </cld-image>
    Angular:
    Copy to clipboard
    <cl-image public-id="couple.jpg" >
      <cl-transformation overlay="golden_star" gravity="faces" width="50">
      </cl-transformation>
    </cl-image>
    .NET:
    Copy to clipboard
    cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new Layer().PublicId("golden_star")).Gravity("faces").Width(50)).BuildImageTag("couple.jpg")
    iOS:
    Copy to clipboard
    imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("golden_star").setGravity("faces").setWidth(50)).generate("couple.jpg")!, cloudinary: cloudinary)
    Android:
    Copy to clipboard
    MediaManager.get().url().transformation(new Transformation().overlay(new Layer().publicId("golden_star")).gravity("faces").width(50)).generate("couple.jpg");
    Kotlin:
    Copy to clipboard
    cloudinary.image {
    publicId("couple.jpg")
    overlay(Overlay.source(Source.image("golden_star") {
    transformation(ImageTransformation {
    resize(Resize.scale() {
    width(50)
    })
    })
    }) {
    position(Position {
    gravity(Gravity.focusOn(FocusOn.faces()))
    })
    })}.generate()
    Image with overlay placed over faces

  2. Use the OCR Text Detection and Extraction add-on to add an overlay with your site's contact information that covers any detected text in an uploaded image:

    Ruby:
    Copy to clipboard
    cl_image_tag("sale_sign.jpg", :overlay=>"call_text", :flags=>"region_relative", :width=>1.1, :gravity=>"ocr_text")
    PHP v1:
    Copy to clipboard
    cl_image_tag("sale_sign.jpg", array("overlay"=>"call_text", "flags"=>"region_relative", "width"=>"1.1", "gravity"=>"ocr_text"))
    PHP v2:
    Copy to clipboard
    (new ImageTag('sale_sign.jpg'))
      ->overlay(
          Overlay::source(Source::image('call_text')
            ->transformation((new ImageTransformation())
              ->resize(Resize::scale()->width(1.1)->regionRelative())))
          ->position((new Position())
            ->gravity(Gravity::focusOn(FocusOn::ocr()))
      ));
    Python:
    Copy to clipboard
    CloudinaryImage("sale_sign.jpg").image(overlay="call_text", flags="region_relative", width="1.1", gravity="ocr_text")
    Node.js:
    Copy to clipboard
    cloudinary.image("sale_sign.jpg", {overlay: "call_text", flags: "region_relative", width: "1.1", gravity: "ocr_text"})
    Java:
    Copy to clipboard
    cloudinary.url().transformation(new Transformation().overlay(new Layer().publicId("call_text")).flags("region_relative").width(1.1).gravity("ocr_text")).imageTag("sale_sign.jpg");
    JS:
    Copy to clipboard
    cloudinary.imageTag('sale_sign.jpg', {overlay: new cloudinary.Layer().publicId("call_text"), flags: "region_relative", width: "1.1", gravity: "ocr_text"}).toHtml();
    jQuery:
    Copy to clipboard
    $.cloudinary.image("sale_sign.jpg", {overlay: new cloudinary.Layer().publicId("call_text"), flags: "region_relative", width: "1.1", gravity: "ocr_text"})
    React:
    Copy to clipboard
    <Image publicId="sale_sign.jpg" >
      <Transformation overlay="call_text" flags="region_relative" width="1.1" gravity="ocr_text" />
    </Image>
    Vue.js:
    Copy to clipboard
    <cld-image publicId="sale_sign.jpg" >
      <cld-transformation :overlay="call_text" flags="region_relative" width="1.1" gravity="ocr_text" />
    </cld-image>
    Angular:
    Copy to clipboard
    <cl-image public-id="sale_sign.jpg" >
      <cl-transformation overlay="call_text" flags="region_relative" width="1.1" gravity="ocr_text">
      </cl-transformation>
    </cl-image>
    .NET:
    Copy to clipboard
    cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new Layer().PublicId("call_text")).Flags("region_relative").Width(1.1).Gravity("ocr_text")).BuildImageTag("sale_sign.jpg")
    iOS:
    Copy to clipboard
    imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("call_text").setFlags("region_relative").setWidth(1.1).setGravity("ocr_text")).generate("sale_sign.jpg")!, cloudinary: cloudinary)
    Android:
    Copy to clipboard
    MediaManager.get().url().transformation(new Transformation().overlay(new Layer().publicId("call_text")).flags("region_relative").width(1.1).gravity("ocr_text")).generate("sale_sign.jpg");
    Kotlin:
    Copy to clipboard
    cloudinary.image {
    publicId("sale_sign.jpg")
    overlay(Overlay.source(Source.image("call_text") {
    transformation(ImageTransformation {
    resize(Resize.scale() {
    width(1.1f)
    regionRelative()
    })
    })
    }) {
    position(Position {
    gravity(Gravity.focusOn(FocusOn.ocr()))
    })
    })}.generate()
    Image with overlay placed over faces

Notes

  • When gravity is set to one of the special position values, and no special position is detected in the image, then no overlay is placed at all.
  • Instead of specifying an absolute width for overlays, you can use the fl_region_relative flag to place each overlay relative to the size of each detected region.

Layer placement flags

When placing layers, there are some flags you may want to use to adjust the default behavior.

Relative layer sizing

By default, whenever you apply relative resize transformations to your overlay, the overlay image is resized relative to its own original size. However, you can use one of the following flags to resize relative to other elements.

Sizing relative to the base image

You can add the relative flag (fl_relative in URLs) to specify that percentage-based width & height parameters of overlays (e.g., w_0.5) are relative to the size of the base image instead of to the original size of the overlaying image itself.

The example below adds an overlay of the image called cloudinary_icon_blue, where the overlay is resized to 80% of the width of the base image (l_cloudinary_icon_blue,w_0.8,fl_relative):

Ruby:
Copy to clipboard
cl_image_tag("sample.jpg", :overlay=>"cloudinary_icon_blue", :width=>0.8, :flags=>"relative")
PHP v1:
Copy to clipboard
cl_image_tag("sample.jpg", array("overlay"=>"cloudinary_icon_blue", "width"=>"0.8", "flags"=>"relative"))
PHP v2:
Copy to clipboard
(new ImageTag('sample.jpg'))
  ->overlay(
      Overlay::source(Source::image('cloudinary_icon_blue')
        ->transformation((new ImageTransformation())
          ->resize(Resize::scale()->width(0.8)->relative())
  )));
Python:
Copy to clipboard
CloudinaryImage("sample.jpg").image(overlay="cloudinary_icon_blue", width="0.8", flags="relative")
Node.js:
Copy to clipboard
cloudinary.image("sample.jpg", {overlay: "cloudinary_icon_blue", width: "0.8", flags: "relative"})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon_blue")).width(0.8).flags("relative")).imageTag("sample.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('sample.jpg', {overlay: new cloudinary.Layer().publicId("cloudinary_icon_blue"), width: "0.8", flags: "relative"}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("sample.jpg", {overlay: new cloudinary.Layer().publicId("cloudinary_icon_blue"), width: "0.8", flags: "relative"})
React:
Copy to clipboard
<Image publicId="sample.jpg" >
  <Transformation overlay="cloudinary_icon_blue" width="0.8" flags="relative" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="sample.jpg" >
  <cld-transformation :overlay="cloudinary_icon_blue" width="0.8" flags="relative" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="sample.jpg" >
  <cl-transformation overlay="cloudinary_icon_blue" width="0.8" flags="relative">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new Layer().PublicId("cloudinary_icon_blue")).Width(0.8).Flags("relative")).BuildImageTag("sample.jpg")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("cloudinary_icon_blue").setWidth(0.8).setFlags("relative")).generate("sample.jpg")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon_blue")).width(0.8).flags("relative")).generate("sample.jpg");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("sample.jpg")
overlay(Overlay.source(Source.image("cloudinary_icon_blue") {
transformation(ImageTransformation {
resize(Resize.scale() {
width(0.8f)
relative()
})
})
}))}.generate()
Image with overlay resized relative to base image

Sizing relative to the detected region

You can add the region_relative flag (fl_region_relative in URLs) to instruct Cloudinary to size your layers relative to the regions detected by the specified gravity type.

  • The region can be detected faces (g_face, g_faces ), detected OCR text regions (g_ocr_text) or pre-defined custom regions (g_custom).
  • This flag must be used in conjunction with a relative (decimal value) width or height qualifier.

The example below hides all the faces in an image by covering them with an emoji overlay, where each overlay is sized at 1.3x (130%) of each detected face:

Ruby:
Copy to clipboard
cl_image_tag("rollercoaster.jpg", :overlay=>"happy_smiley", :width=>1.3, :flags=>"region_relative", :gravity=>"faces")
PHP v1:
Copy to clipboard
cl_image_tag("rollercoaster.jpg", array("overlay"=>"happy_smiley", "width"=>"1.3", "flags"=>"region_relative", "gravity"=>"faces"))
PHP v2:
Copy to clipboard
(new ImageTag('rollercoaster.jpg'))
  ->overlay(
      Overlay::source(Source::image('happy_smiley')
        ->transformation((new ImageTransformation())
          ->resize(Resize::scale()->width(1.3)->regionRelative())))
      ->position((new Position())
        ->gravity(Gravity::focusOn(FocusOn::faces()))
  ));
Python:
Copy to clipboard
CloudinaryImage("rollercoaster.jpg").image(overlay="happy_smiley", width="1.3", flags="region_relative", gravity="faces")
Node.js:
Copy to clipboard
cloudinary.image("rollercoaster.jpg", {overlay: "happy_smiley", width: "1.3", flags: "region_relative", gravity: "faces"})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().overlay(new Layer().publicId("happy_smiley")).width(1.3).flags("region_relative").gravity("faces")).imageTag("rollercoaster.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('rollercoaster.jpg', {overlay: new cloudinary.Layer().publicId("happy_smiley"), width: "1.3", flags: "region_relative", gravity: "faces"}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("rollercoaster.jpg", {overlay: new cloudinary.Layer().publicId("happy_smiley"), width: "1.3", flags: "region_relative", gravity: "faces"})
React:
Copy to clipboard
<Image publicId="rollercoaster.jpg" >
  <Transformation overlay="happy_smiley" width="1.3" flags="region_relative" gravity="faces" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="rollercoaster.jpg" >
  <cld-transformation :overlay="happy_smiley" width="1.3" flags="region_relative" gravity="faces" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="rollercoaster.jpg" >
  <cl-transformation overlay="happy_smiley" width="1.3" flags="region_relative" gravity="faces">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new Layer().PublicId("happy_smiley")).Width(1.3).Flags("region_relative").Gravity("faces")).BuildImageTag("rollercoaster.jpg")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("happy_smiley").setWidth(1.3).setFlags("region_relative").setGravity("faces")).generate("rollercoaster.jpg")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().overlay(new Layer().publicId("happy_smiley")).width(1.3).flags("region_relative").gravity("faces")).generate("rollercoaster.jpg");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("rollercoaster.jpg")
overlay(Overlay.source(Source.image("happy_smiley") {
transformation(ImageTransformation {
resize(Resize.scale() {
width(1.3f)
regionRelative()
})
})
}) {
position(Position {
gravity(Gravity.focusOn(FocusOn.faces()))
})
})}.generate()
Hide faces in an image with emojis

Layer overflow behavior

By default, if a layer (image or text) has a larger width or height than the base image, the delivered image canvas is resized to display the entire layer. If you want to ensure that the delivered size will never be larger than the base image, you can use the fl_no_overflow flag with your layer.

In the example below, the no_overflow flag prevents the logo overlay from extending the canvas of the base image:

Ruby:
Copy to clipboard
cl_image_tag("flower.jpg", :transformation=>[
  {:width=>400, :crop=>"scale"},
  {:overlay=>"cloudinary_icon_blue", :flags=>"no_overflow"}
  ])
PHP v1:
Copy to clipboard
cl_image_tag("flower.jpg", array("transformation"=>array(
  array("width"=>400, "crop"=>"scale"),
  array("overlay"=>"cloudinary_icon_blue", "flags"=>"no_overflow")
  )))
PHP v2:
Copy to clipboard
(new ImageTag('flower.jpg'))
  ->resize(Resize::scale()->width(400))
  ->overlay(Overlay::source(Source::image('cloudinary_icon_blue'))
    ->position((new Position())
      ->allowOverflow(false)));
Python:
Copy to clipboard
CloudinaryImage("flower.jpg").image(transformation=[
  {'width': 400, 'crop': "scale"},
  {'overlay': "cloudinary_icon_blue", 'flags': "no_overflow"}
  ])
Node.js:
Copy to clipboard
cloudinary.image("flower.jpg", {transformation: [
  {width: 400, crop: "scale"},
  {overlay: "cloudinary_icon_blue", flags: "no_overflow"}
  ]})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation()
  .width(400).crop("scale").chain()
  .overlay(new Layer().publicId("cloudinary_icon_blue")).flags("no_overflow")).imageTag("flower.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('flower.jpg', {transformation: [
  {width: 400, crop: "scale"},
  {overlay: new cloudinary.Layer().publicId("cloudinary_icon_blue"), flags: "no_overflow"}
  ]}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("flower.jpg", {transformation: [
  {width: 400, crop: "scale"},
  {overlay: new cloudinary.Layer().publicId("cloudinary_icon_blue"), flags: "no_overflow"}
  ]})
React:
Copy to clipboard
<Image publicId="flower.jpg" >
  <Transformation width="400" crop="scale" />
  <Transformation overlay="cloudinary_icon_blue" flags="no_overflow" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="flower.jpg" >
  <cld-transformation width="400" crop="scale" />
  <cld-transformation :overlay="cloudinary_icon_blue" flags="no_overflow" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="flower.jpg" >
  <cl-transformation width="400" crop="scale">
  </cl-transformation>
  <cl-transformation overlay="cloudinary_icon_blue" flags="no_overflow">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(400).Crop("scale").Chain()
  .Overlay(new Layer().PublicId("cloudinary_icon_blue")).Flags("no_overflow")).BuildImageTag("flower.jpg")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setWidth(400).setCrop("scale").chain()
  .setOverlay("cloudinary_icon_blue").setFlags("no_overflow")).generate("flower.jpg")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation()
  .width(400).crop("scale").chain()
  .overlay(new Layer().publicId("cloudinary_icon_blue")).flags("no_overflow")).generate("flower.jpg");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("flower.jpg")
resize(Resize.scale() {
width(400)
})
overlay(Overlay.source(Source.image("cloudinary_icon_blue")) {
position(Position {
allowOverflow(false)
})
})}.generate()
Prevent an overlay from extending the canvas of the base image

Layer transformations

Overlays can be resized and transformed like any other image uploaded to Cloudinary. For example, adding an overlay of the image called cloudinary_icon_blue to the top right corner of the base image, where the overlay is also scaled down to 50% of its original width and made into a watermark by reducing the opacity to 70% and increasing the brightness to 50% using the brightness effect (l_cloudinary_icon_blue,w_0.5,c_scale,g_north_east,o_70,e_brightness:50):

Ruby:
Copy to clipboard
cl_image_tag("sample.jpg", :overlay=>"cloudinary_icon_blue", :width=>0.5, :gravity=>"north_east", :opacity=>70, :effect=>"brightness:50", :crop=>"scale")
PHP v1:
Copy to clipboard
cl_image_tag("sample.jpg", array("overlay"=>"cloudinary_icon_blue", "width"=>"0.5", "gravity"=>"north_east", "opacity"=>70, "effect"=>"brightness:50", "crop"=>"scale"))
PHP v2:
Copy to clipboard
(new ImageTag('sample.jpg'))
  ->overlay(
      Overlay::source(Source::image('cloudinary_icon_blue')
        ->transformation((new ImageTransformation())
          ->resize(Resize::scale()->width(0.5))
          ->adjust(Adjust::opacity(70))
          ->adjust(Adjust::brightness()->level(50))))
      ->position((new Position())
        ->gravity(Gravity::compass(Compass::northEast()))
  ));
Python:
Copy to clipboard
CloudinaryImage("sample.jpg").image(overlay="cloudinary_icon_blue", width="0.5", gravity="north_east", opacity=70, effect="brightness:50", crop="scale")
Node.js:
Copy to clipboard
cloudinary.image("sample.jpg", {overlay: "cloudinary_icon_blue", width: "0.5", gravity: "north_east", opacity: 70, effect: "brightness:50", crop: "scale"})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon_blue")).width(0.5).gravity("north_east").opacity(70).effect("brightness:50").crop("scale")).imageTag("sample.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('sample.jpg', {overlay: new cloudinary.Layer().publicId("cloudinary_icon_blue"), width: "0.5", gravity: "north_east", opacity: 70, effect: "brightness:50", crop: "scale"}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("sample.jpg", {overlay: new cloudinary.Layer().publicId("cloudinary_icon_blue"), width: "0.5", gravity: "north_east", opacity: 70, effect: "brightness:50", crop: "scale"})
React:
Copy to clipboard
<Image publicId="sample.jpg" >
  <Transformation overlay="cloudinary_icon_blue" width="0.5" gravity="north_east" opacity="70" effect="brightness:50" crop="scale" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="sample.jpg" >
  <cld-transformation :overlay="cloudinary_icon_blue" width="0.5" gravity="north_east" opacity="70" effect="brightness:50" crop="scale" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="sample.jpg" >
  <cl-transformation overlay="cloudinary_icon_blue" width="0.5" gravity="north_east" opacity="70" effect="brightness:50" crop="scale">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new Layer().PublicId("cloudinary_icon_blue")).Width(0.5).Gravity("north_east").Opacity(70).Effect("brightness:50").Crop("scale")).BuildImageTag("sample.jpg")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("cloudinary_icon_blue").setWidth(0.5).setGravity("north_east").setOpacity(70).setEffect("brightness:50").setCrop("scale")).generate("sample.jpg")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon_blue")).width(0.5).gravity("north_east").opacity(70).effect("brightness:50").crop("scale")).generate("sample.jpg");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("sample.jpg")
overlay(Overlay.source(Source.image("cloudinary_icon_blue") {
transformation(ImageTransformation {
resize(Resize.scale() {
width(0.5f)
})
adjust(Adjust.opacity(70))
adjust(Adjust.brightness() {
level(50)
})
})
}) {
position(Position {
gravity(Gravity.compass(Compass.northEast()))
})
})}.generate()
Image with transformed overlay

Multiple layer transformations (fl_layer_apply)

You can apply multiple transformations to overlays by adding the layer_apply flag to the 'last' transformation in the series. That is, the flag tells Cloudinary to apply 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 (it closes the layer, similar to a closing bracket).

For example, the base image scaled to a width of 500 pixels before adding the woman image as an overlay, where the overlay image is automatically cropped to include only the detected face and then scaled to a width of 150 pixels (w_500/l_woman,c_crop,g_face/w_150/fl_layer_apply):

Ruby:
Copy to clipboard
cl_image_tag("sample.jpg", :transformation=>[
  {:width=>500, :crop=>"scale"},
  {:overlay=>"woman", :gravity=>"face", :crop=>"crop"},
  {:width=>150, :crop=>"scale"},
  {:flags=>"layer_apply"}
  ])
PHP v1:
Copy to clipboard
cl_image_tag("sample.jpg", array("transformation"=>array(
  array("width"=>500, "crop"=>"scale"),
  array("overlay"=>"woman", "gravity"=>"face", "crop"=>"crop"),
  array("width"=>150, "crop"=>"scale"),
  array("flags"=>"layer_apply")
  )))
PHP v2:
Copy to clipboard
(new ImageTag('sample.jpg'))
  ->resize(Resize::scale()->width(500))
  ->overlay(
      Overlay::source(Source::image('woman')
        ->transformation((new ImageTransformation())
          ->resize(Resize::crop()->gravity(Gravity::focusOn(FocusOn::face())))
          ->resize(Resize::scale()->width(150))
  )));
Python:
Copy to clipboard
CloudinaryImage("sample.jpg").image(transformation=[
  {'width': 500, 'crop': "scale"},
  {'overlay': "woman", 'gravity': "face", 'crop': "crop"},
  {'width': 150, 'crop': "scale"},
  {'flags': "layer_apply"}
  ])
Node.js:
Copy to clipboard
cloudinary.image("sample.jpg", {transformation: [
  {width: 500, crop: "scale"},
  {overlay: "woman", gravity: "face", crop: "crop"},
  {width: 150, crop: "scale"},
  {flags: "layer_apply"}
  ]})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation()
  .width(500).crop("scale").chain()
  .overlay(new Layer().publicId("woman")).gravity("face").crop("crop").chain()
  .width(150).crop("scale").chain()
  .flags("layer_apply")).imageTag("sample.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('sample.jpg', {transformation: [
  {width: 500, crop: "scale"},
  {overlay: new cloudinary.Layer().publicId("woman"), gravity: "face", crop: "crop"},
  {width: 150, crop: "scale"},
  {flags: "layer_apply"}
  ]}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("sample.jpg", {transformation: [
  {width: 500, crop: "scale"},
  {overlay: new cloudinary.Layer().publicId("woman"), gravity: "face", crop: "crop"},
  {width: 150, crop: "scale"},
  {flags: "layer_apply"}
  ]})
React:
Copy to clipboard
<Image publicId="sample.jpg" >
  <Transformation width="500" crop="scale" />
  <Transformation overlay="woman" gravity="face" crop="crop" />
  <Transformation width="150" crop="scale" />
  <Transformation flags="layer_apply" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="sample.jpg" >
  <cld-transformation width="500" crop="scale" />
  <cld-transformation :overlay="woman" gravity="face" crop="crop" />
  <cld-transformation width="150" crop="scale" />
  <cld-transformation flags="layer_apply" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="sample.jpg" >
  <cl-transformation width="500" crop="scale">
  </cl-transformation>
  <cl-transformation overlay="woman" gravity="face" crop="crop">
  </cl-transformation>
  <cl-transformation width="150" crop="scale">
  </cl-transformation>
  <cl-transformation flags="layer_apply">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(500).Crop("scale").Chain()
  .Overlay(new Layer().PublicId("woman")).Gravity("face").Crop("crop").Chain()
  .Width(150).Crop("scale").Chain()
  .Flags("layer_apply")).BuildImageTag("sample.jpg")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setWidth(500).setCrop("scale").chain()
  .setOverlay("woman").setGravity("face").setCrop("crop").chain()
  .setWidth(150).setCrop("scale").chain()
  .setFlags("layer_apply")).generate("sample.jpg")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation()
  .width(500).crop("scale").chain()
  .overlay(new Layer().publicId("woman")).gravity("face").crop("crop").chain()
  .width(150).crop("scale").chain()
  .flags("layer_apply")).generate("sample.jpg");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("sample.jpg")
resize(Resize.scale() {
width(500)
})
overlay(Overlay.source(Source.image("woman") {
transformation(ImageTransformation {
resize(Resize.crop() {
gravity(Gravity.focusOn(FocusOn.face()))
})
resize(Resize.scale() {
width(150)
})
})
}))}.generate()
image with transformations applied to the overlay

Note how the transformations were applied in the last example as chained transformations. The first width adjustment to 500 pixels was made to the base image, and the second width adjustment to 150 pixels was made to the overlay (as was the face detection based cropping) because of the layer_apply flag.

Multiple overlays

Multiple overlays can easily be added as chained transformations to an image. The following example adds both image and text overlays to the base image as follows:

  1. An overlay of an image called couple, cropped to a 120x150 ellipse that includes only the detected faces (l_couple/c_crop,g_faces,w_120,h_150/r_max/fl_layer_apply).
  2. An overlay of an image called cloudinary_icon_white with a relative width of 80% of the base image and an opacity of 50% and a brightness of 100 (l_cloudinary_icon_white,w_0.8,fl_relative/o_50,e_brightness:100/fl_layer_apply).
  3. The text string "Sample image" in Impact bold font with a size of 40 pixels at a distance of 20 pixels from the bottom of the base image (l_text:impact_40_bold:Sample%20image/fl_layer_apply,g_south,y_20).

Ruby:
Copy to clipboard
cl_image_tag("sample.jpg", :transformation=>[
  {:overlay=>"couple"},
  {:gravity=>"faces", :width=>120, :height=>150, :crop=>"crop"},
  {:radius=>"max"},
  {:flags=>"layer_apply", :gravity=>"north_east"},
  {:overlay=>"cloudinary_icon_white", :width=>0.8, :flags=>"relative"},
  {:opacity=>50, :effect=>"brightness:100"},
  {:flags=>"layer_apply"},
  {:overlay=>{:font_family=>"impact", :font_size=>40, :font_weight=>"bold", :text=>"Sample%20image"}},
  {:flags=>"layer_apply", :gravity=>"south", :y=>20}
  ])
PHP v1:
Copy to clipboard
cl_image_tag("sample.jpg", array("transformation"=>array(
  array("overlay"=>"couple"),
  array("gravity"=>"faces", "width"=>120, "height"=>150, "crop"=>"crop"),
  array("radius"=>"max"),
  array("flags"=>"layer_apply", "gravity"=>"north_east"),
  array("overlay"=>"cloudinary_icon_white", "width"=>"0.8", "flags"=>"relative"),
  array("opacity"=>50, "effect"=>"brightness:100"),
  array("flags"=>"layer_apply"),
  array("overlay"=>array("font_family"=>"impact", "font_size"=>40, "font_weight"=>"bold", "text"=>"Sample%20image")),
  array("flags"=>"layer_apply", "gravity"=>"south", "y"=>20)
  )))
PHP v2:
Copy to clipboard
(new ImageTag('sample.jpg'))
  ->overlay(
      Overlay::source(Source::image('couple')
        ->transformation((new ImageTransformation())
          ->resize(Resize::crop()->width(120)->height(150)->gravity(Gravity::focusOn(FocusOn::faces())))
          ->roundCorners(RoundCorners::max())))
      ->position((new Position())
        ->gravity(Gravity::compass(Compass::northEast()))))
    ->overlay(
        Overlay::source(Source::image('cloudinary_icon_white')
          ->transformation((new ImageTransformation())
            ->resize(Resize::scale()->width(0.8)->relative())
            ->adjust(Adjust::opacity(50))
            ->adjust(Adjust::brightness()->level(100)))))
          ->overlay(
              Overlay::source(
                  Source::text('Sample image', (new TextStyle('impact', 40))
                    ->fontWeight(FontWeight::bold())))
                ->position((new Position())
                  ->gravity(Gravity::compass(Compass::south()))
                  ->offsetY(20)
              
            
              
              ));
Python:
Copy to clipboard
CloudinaryImage("sample.jpg").image(transformation=[
  {'overlay': "couple"},
  {'gravity': "faces", 'width': 120, 'height': 150, 'crop': "crop"},
  {'radius': "max"},
  {'flags': "layer_apply", 'gravity': "north_east"},
  {'overlay': "cloudinary_icon_white", 'width': "0.8", 'flags': "relative"},
  {'opacity': 50, 'effect': "brightness:100"},
  {'flags': "layer_apply"},
  {'overlay': {'font_family': "impact", 'font_size': 40, 'font_weight': "bold", 'text': "Sample%20image"}},
  {'flags': "layer_apply", 'gravity': "south", 'y': 20}
  ])
Node.js:
Copy to clipboard
cloudinary.image("sample.jpg", {transformation: [
  {overlay: "couple"},
  {gravity: "faces", width: 120, height: 150, crop: "crop"},
  {radius: "max"},
  {flags: "layer_apply", gravity: "north_east"},
  {overlay: "cloudinary_icon_white", width: "0.8", flags: "relative"},
  {opacity: 50, effect: "brightness:100"},
  {flags: "layer_apply"},
  {overlay: {font_family: "impact", font_size: 40, font_weight: "bold", text: "Sample%20image"}},
  {flags: "layer_apply", gravity: "south", y: 20}
  ]})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation()
  .overlay(new Layer().publicId("couple")).chain()
  .gravity("faces").width(120).height(150).crop("crop").chain()
  .radius("max").chain()
  .flags("layer_apply").gravity("north_east").chain()
  .overlay(new Layer().publicId("cloudinary_icon_white")).width(0.8).flags("relative").chain()
  .opacity(50).effect("brightness:100").chain()
  .flags("layer_apply").chain()
  .overlay(new TextLayer().fontFamily("impact").fontSize(40).fontWeight("bold").text("Sample%20image")).chain()
  .flags("layer_apply").gravity("south").y(20)).imageTag("sample.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('sample.jpg', {transformation: [
  {overlay: new cloudinary.Layer().publicId("couple")},
  {gravity: "faces", width: 120, height: 150, crop: "crop"},
  {radius: "max"},
  {flags: "layer_apply", gravity: "north_east"},
  {overlay: new cloudinary.Layer().publicId("cloudinary_icon_white"), width: "0.8", flags: "relative"},
  {opacity: 50, effect: "brightness:100"},
  {flags: "layer_apply"},
  {overlay: new cloudinary.TextLayer().fontFamily("impact").fontSize(40).fontWeight("bold").text("Sample%20image")},
  {flags: "layer_apply", gravity: "south", y: 20}
  ]}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("sample.jpg", {transformation: [
  {overlay: new cloudinary.Layer().publicId("couple")},
  {gravity: "faces", width: 120, height: 150, crop: "crop"},
  {radius: "max"},
  {flags: "layer_apply", gravity: "north_east"},
  {overlay: new cloudinary.Layer().publicId("cloudinary_icon_white"), width: "0.8", flags: "relative"},
  {opacity: 50, effect: "brightness:100"},
  {flags: "layer_apply"},
  {overlay: new cloudinary.TextLayer().fontFamily("impact").fontSize(40).fontWeight("bold").text("Sample%20image")},
  {flags: "layer_apply", gravity: "south", y: 20}
  ]})
React:
Copy to clipboard
<Image publicId="sample.jpg" >
  <Transformation overlay="couple" />
  <Transformation gravity="faces" width="120" height="150" crop="crop" />
  <Transformation radius="max" />
  <Transformation flags="layer_apply" gravity="north_east" />
  <Transformation overlay="cloudinary_icon_white" width="0.8" flags="relative" />
  <Transformation opacity="50" effect="brightness:100" />
  <Transformation flags="layer_apply" />
  <Transformation overlay={{fontFamily: "impact", fontSize: 40, fontWeight: "bold", text: "Sample%20image"}} />
  <Transformation flags="layer_apply" gravity="south" y="20" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="sample.jpg" >
  <cld-transformation :overlay="couple" />
  <cld-transformation gravity="faces" width="120" height="150" crop="crop" />
  <cld-transformation radius="max" />
  <cld-transformation flags="layer_apply" gravity="north_east" />
  <cld-transformation :overlay="cloudinary_icon_white" width="0.8" flags="relative" />
  <cld-transformation opacity="50" effect="brightness:100" />
  <cld-transformation flags="layer_apply" />
  <cld-transformation :overlay="{fontFamily: 'impact', fontSize: 40, fontWeight: 'bold', text: 'Sample%20image'}" />
  <cld-transformation flags="layer_apply" gravity="south" y="20" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="sample.jpg" >
  <cl-transformation overlay="couple">
  </cl-transformation>
  <cl-transformation gravity="faces" width="120" height="150" crop="crop">
  </cl-transformation>
  <cl-transformation radius="max">
  </cl-transformation>
  <cl-transformation flags="layer_apply" gravity="north_east">
  </cl-transformation>
  <cl-transformation overlay="cloudinary_icon_white" width="0.8" flags="relative">
  </cl-transformation>
  <cl-transformation opacity="50" effect="brightness:100">
  </cl-transformation>
  <cl-transformation flags="layer_apply">
  </cl-transformation>
  <cl-transformation overlay="text:impact_40_bold:Sample%20image">
  </cl-transformation>
  <cl-transformation flags="layer_apply" gravity="south" y="20">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Overlay(new Layer().PublicId("couple")).Chain()
  .Gravity("faces").Width(120).Height(150).Crop("crop").Chain()
  .Radius("max").Chain()
  .Flags("layer_apply").Gravity("north_east").Chain()
  .Overlay(new Layer().PublicId("cloudinary_icon_white")).Width(0.8).Flags("relative").Chain()
  .Opacity(50).Effect("brightness:100").Chain()
  .Flags("layer_apply").Chain()
  .Overlay(new TextLayer().FontFamily("impact").FontSize(40).FontWeight("bold").Text("Sample%20image")).Chain()
  .Flags("layer_apply").Gravity("south").Y(20)).BuildImageTag("sample.jpg")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setOverlay("couple").chain()
  .setGravity("faces").setWidth(120).setHeight(150).setCrop("crop").chain()
  .setRadius("max").chain()
  .setFlags("layer_apply").setGravity("north_east").chain()
  .setOverlay("cloudinary_icon_white").setWidth(0.8).setFlags("relative").chain()
  .setOpacity(50).setEffect("brightness:100").chain()
  .setFlags("layer_apply").chain()
  .setOverlay("text:impact_40_bold:Sample%20image").chain()
  .setFlags("layer_apply").setGravity("south").setY(20)).generate("sample.jpg")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation()
  .overlay(new Layer().publicId("couple")).chain()
  .gravity("faces").width(120).height(150).crop("crop").chain()
  .radius("max").chain()
  .flags("layer_apply").gravity("north_east").chain()
  .overlay(new Layer().publicId("cloudinary_icon_white")).width(0.8).flags("relative").chain()
  .opacity(50).effect("brightness:100").chain()
  .flags("layer_apply").chain()
  .overlay(new TextLayer().fontFamily("impact").fontSize(40).fontWeight("bold").text("Sample%20image")).chain()
  .flags("layer_apply").gravity("south").y(20)).generate("sample.jpg");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("sample.jpg")
overlay(Overlay.source(Source.image("couple") {
transformation(ImageTransformation {
resize(Resize.crop() {
width(120)
height(150)
gravity(Gravity.focusOn(FocusOn.faces()))
})
roundCorners(RoundCorners.max())
})
}) {
position(Position {
gravity(Gravity.compass(Compass.northEast()))
})
})
overlay(Overlay.source(Source.image("cloudinary_icon_white") {
transformation(ImageTransformation {
resize(Resize.scale() {
width(0.8f)
relative()
})
adjust(Adjust.opacity(50))
adjust(Adjust.brightness() {
level(100)
})
})
}))
overlay(Overlay.source(Source.text("Sample image", TextStyle("impact", 40) {
fontWeight(FontWeight.bold())
})) {
position(Position {
gravity(Gravity.compass(Compass.south()))
offsetY(20)
})
})}.generate()
Image with 3 overlays

Considerations when using layer_apply

  1. When adding multiple layers, close all layers with the layer_apply flag (even if they don't use multiple components) to avoid server confusion on which transformations to apply to a particular layer.
  2. Specify any details regarding the relationship between the overlay image and the base image (i.e., anything that is relative like gravity) in the same component as the layer_apply flag. For example the base image scaled to a width of 500 pixels before adding the cloudinary_icon_blue image as an overlay, where the overlay image is scaled to a width of 150 pixels, converted to black and white, and then the entire overlay is placed in the top right corner:
    Ruby:
    Copy to clipboard
    cl_image_tag("sample.jpg", :transformation=>[
      {:width=>500, :crop=>"scale"},
      {:overlay=>"cloudinary_icon_blue", :width=>150},
      {:effect=>"blackwhite"},
      {:flags=>"layer_apply", :gravity=>"north_east"}
      ])
    PHP v1:
    Copy to clipboard
    cl_image_tag("sample.jpg", array("transformation"=>array(
      array("width"=>500, "crop"=>"scale"),
      array("overlay"=>"cloudinary_icon_blue", "width"=>150),
      array("effect"=>"blackwhite"),
      array("flags"=>"layer_apply", "gravity"=>"north_east")
      )))
    PHP v2:
    Copy to clipboard
    (new ImageTag('sample.jpg'))
      ->resize(Resize::scale()->width(500))
      ->overlay(
          Overlay::source(Source::image('cloudinary_icon_blue')
            ->transformation((new ImageTransformation())
              ->resize(Resize::scale()->width(150))
              ->effect(Effect::blackwhite())))
          ->position((new Position())
            ->gravity(Gravity::compass(Compass::northEast()))
      ));
    Python:
    Copy to clipboard
    CloudinaryImage("sample.jpg").image(transformation=[
      {'width': 500, 'crop': "scale"},
      {'overlay': "cloudinary_icon_blue", 'width': 150},
      {'effect': "blackwhite"},
      {'flags': "layer_apply", 'gravity': "north_east"}
      ])
    Node.js:
    Copy to clipboard
    cloudinary.image("sample.jpg", {transformation: [
      {width: 500, crop: "scale"},
      {overlay: "cloudinary_icon_blue", width: 150},
      {effect: "blackwhite"},
      {flags: "layer_apply", gravity: "north_east"}
      ]})
    Java:
    Copy to clipboard
    cloudinary.url().transformation(new Transformation()
      .width(500).crop("scale").chain()
      .overlay(new Layer().publicId("cloudinary_icon_blue")).width(150).chain()
      .effect("blackwhite").chain()
      .flags("layer_apply").gravity("north_east")).imageTag("sample.jpg");
    JS:
    Copy to clipboard
    cloudinary.imageTag('sample.jpg', {transformation: [
      {width: 500, crop: "scale"},
      {overlay: new cloudinary.Layer().publicId("cloudinary_icon_blue"), width: 150},
      {effect: "blackwhite"},
      {flags: "layer_apply", gravity: "north_east"}
      ]}).toHtml();
    jQuery:
    Copy to clipboard
    $.cloudinary.image("sample.jpg", {transformation: [
      {width: 500, crop: "scale"},
      {overlay: new cloudinary.Layer().publicId("cloudinary_icon_blue"), width: 150},
      {effect: "blackwhite"},
      {flags: "layer_apply", gravity: "north_east"}
      ]})
    React:
    Copy to clipboard
    <Image publicId="sample.jpg" >
      <Transformation width="500" crop="scale" />
      <Transformation overlay="cloudinary_icon_blue" width="150" />
      <Transformation effect="blackwhite" />
      <Transformation flags="layer_apply" gravity="north_east" />
    </Image>
    Vue.js:
    Copy to clipboard
    <cld-image publicId="sample.jpg" >
      <cld-transformation width="500" crop="scale" />
      <cld-transformation :overlay="cloudinary_icon_blue" width="150" />
      <cld-transformation effect="blackwhite" />
      <cld-transformation flags="layer_apply" gravity="north_east" />
    </cld-image>
    Angular:
    Copy to clipboard
    <cl-image public-id="sample.jpg" >
      <cl-transformation width="500" crop="scale">
      </cl-transformation>
      <cl-transformation overlay="cloudinary_icon_blue" width="150">
      </cl-transformation>
      <cl-transformation effect="blackwhite">
      </cl-transformation>
      <cl-transformation flags="layer_apply" gravity="north_east">
      </cl-transformation>
    </cl-image>
    .NET:
    Copy to clipboard
    cloudinary.Api.UrlImgUp.Transform(new Transformation()
      .Width(500).Crop("scale").Chain()
      .Overlay(new Layer().PublicId("cloudinary_icon_blue")).Width(150).Chain()
      .Effect("blackwhite").Chain()
      .Flags("layer_apply").Gravity("north_east")).BuildImageTag("sample.jpg")
    iOS:
    Copy to clipboard
    imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
      .setWidth(500).setCrop("scale").chain()
      .setOverlay("cloudinary_icon_blue").setWidth(150).chain()
      .setEffect("blackwhite").chain()
      .setFlags("layer_apply").setGravity("north_east")).generate("sample.jpg")!, cloudinary: cloudinary)
    Android:
    Copy to clipboard
    MediaManager.get().url().transformation(new Transformation()
      .width(500).crop("scale").chain()
      .overlay(new Layer().publicId("cloudinary_icon_blue")).width(150).chain()
      .effect("blackwhite").chain()
      .flags("layer_apply").gravity("north_east")).generate("sample.jpg");
    Kotlin:
    Copy to clipboard
    cloudinary.image {
    publicId("sample.jpg")
    resize(Resize.scale() {
    width(500)
    })
    overlay(Overlay.source(Source.image("cloudinary_icon_blue") {
    transformation(ImageTransformation {
    resize(Resize.scale() {
    width(150)
    })
    effect(Effect.blackwhite())
    })
    }) {
    position(Position {
    gravity(Gravity.compass(Compass.northEast()))
    })
    })}.generate()
    image with gravity applied to the overlay and relative to the base image
  3. Layers can be nested within layers. For example, the same image as above with another cloudinary_icon_blue image added as an overlay to the first (black and white) overlay.
    Ruby:
    Copy to clipboard
    cl_image_tag("sample.jpg", :transformation=>[
      {:width=>500, :crop=>"scale"},
      {:overlay=>"cloudinary_icon_blue", :width=>150},
      {:effect=>"blackwhite"},
      {:overlay=>"cloudinary_icon_blue", :width=>50},
      {:flags=>"layer_apply"},
      {:flags=>"layer_apply", :gravity=>"north_east"}
      ])
    PHP v1:
    Copy to clipboard
    cl_image_tag("sample.jpg", array("transformation"=>array(
      array("width"=>500, "crop"=>"scale"),
      array("overlay"=>"cloudinary_icon_blue", "width"=>150),
      array("effect"=>"blackwhite"),
      array("overlay"=>"cloudinary_icon_blue", "width"=>50),
      array("flags"=>"layer_apply"),
      array("flags"=>"layer_apply", "gravity"=>"north_east")
      )))
    PHP v2:
    Copy to clipboard
    (new ImageTag('sample.jpg'))
      ->resize(Resize::scale()->width(500))
      ->overlay(
          Overlay::source(Source::image('cloudinary_icon_blue')
            ->transformation((new ImageTransformation())
              ->resize(Resize::scale()->width(150))
              ->effect(Effect::blackwhite())
              ->overlay(
                  Overlay::source(Source::image('cloudinary_icon_blue')
                    ->transformation((new ImageTransformation())
                      ->resize(Resize::scale()->width(50)))))))
            ->position((new Position())
              ->gravity(Gravity::compass(Compass::northEast()))
          
              ));
    Python:
    Copy to clipboard
    CloudinaryImage("sample.jpg").image(transformation=[
      {'width': 500, 'crop': "scale"},
      {'overlay': "cloudinary_icon_blue", 'width': 150},
      {'effect': "blackwhite"},
      {'overlay': "cloudinary_icon_blue", 'width': 50},
      {'flags': "layer_apply"},
      {'flags': "layer_apply", 'gravity': "north_east"}
      ])
    Node.js:
    Copy to clipboard
    cloudinary.image("sample.jpg", {transformation: [
      {width: 500, crop: "scale"},
      {overlay: "cloudinary_icon_blue", width: 150},
      {effect: "blackwhite"},
      {overlay: "cloudinary_icon_blue", width: 50},
      {flags: "layer_apply"},
      {flags: "layer_apply", gravity: "north_east"}
      ]})
    Java:
    Copy to clipboard
    cloudinary.url().transformation(new Transformation()
      .width(500).crop("scale").chain()
      .overlay(new Layer().publicId("cloudinary_icon_blue")).width(150).chain()
      .effect("blackwhite").chain()
      .overlay(new Layer().publicId("cloudinary_icon_blue")).width(50).chain()
      .flags("layer_apply").chain()
      .flags("layer_apply").gravity("north_east")).imageTag("sample.jpg");
    JS:
    Copy to clipboard
    cloudinary.imageTag('sample.jpg', {transformation: [
      {width: 500, crop: "scale"},
      {overlay: new cloudinary.Layer().publicId("cloudinary_icon_blue"), width: 150},
      {effect: "blackwhite"},
      {overlay: new cloudinary.Layer().publicId("cloudinary_icon_blue"), width: 50},
      {flags: "layer_apply"},
      {flags: "layer_apply", gravity: "north_east"}
      ]}).toHtml();
    jQuery:
    Copy to clipboard
    $.cloudinary.image("sample.jpg", {transformation: [
      {width: 500, crop: "scale"},
      {overlay: new cloudinary.Layer().publicId("cloudinary_icon_blue"), width: 150},
      {effect: "blackwhite"},
      {overlay: new cloudinary.Layer().publicId("cloudinary_icon_blue"), width: 50},
      {flags: "layer_apply"},
      {flags: "layer_apply", gravity: "north_east"}
      ]})
    React:
    Copy to clipboard
    <Image publicId="sample.jpg" >
      <Transformation width="500" crop="scale" />
      <Transformation overlay="cloudinary_icon_blue" width="150" />
      <Transformation effect="blackwhite" />
      <Transformation overlay="cloudinary_icon_blue" width="50" />
      <Transformation flags="layer_apply" />
      <Transformation flags="layer_apply" gravity="north_east" />
    </Image>
    Vue.js:
    Copy to clipboard
    <cld-image publicId="sample.jpg" >
      <cld-transformation width="500" crop="scale" />
      <cld-transformation :overlay="cloudinary_icon_blue" width="150" />
      <cld-transformation effect="blackwhite" />
      <cld-transformation :overlay="cloudinary_icon_blue" width="50" />
      <cld-transformation flags="layer_apply" />
      <cld-transformation flags="layer_apply" gravity="north_east" />
    </cld-image>
    Angular:
    Copy to clipboard
    <cl-image public-id="sample.jpg" >
      <cl-transformation width="500" crop="scale">
      </cl-transformation>
      <cl-transformation overlay="cloudinary_icon_blue" width="150">
      </cl-transformation>
      <cl-transformation effect="blackwhite">
      </cl-transformation>
      <cl-transformation overlay="cloudinary_icon_blue" width="50">
      </cl-transformation>
      <cl-transformation flags="layer_apply">
      </cl-transformation>
      <cl-transformation flags="layer_apply" gravity="north_east">
      </cl-transformation>
    </cl-image>
    .NET:
    Copy to clipboard
    cloudinary.Api.UrlImgUp.Transform(new Transformation()
      .Width(500).Crop("scale").Chain()
      .Overlay(new Layer().PublicId("cloudinary_icon_blue")).Width(150).Chain()
      .Effect("blackwhite").Chain()
      .Overlay(new Layer().PublicId("cloudinary_icon_blue")).Width(50).Chain()
      .Flags("layer_apply").Chain()
      .Flags("layer_apply").Gravity("north_east")).BuildImageTag("sample.jpg")
    iOS:
    Copy to clipboard
    imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
      .setWidth(500).setCrop("scale").chain()
      .setOverlay("cloudinary_icon_blue").setWidth(150).chain()
      .setEffect("blackwhite").chain()
      .setOverlay("cloudinary_icon_blue").setWidth(50).chain()
      .setFlags("layer_apply").chain()
      .setFlags("layer_apply").setGravity("north_east")).generate("sample.jpg")!, cloudinary: cloudinary)
    Android:
    Copy to clipboard
    MediaManager.get().url().transformation(new Transformation()
      .width(500).crop("scale").chain()
      .overlay(new Layer().publicId("cloudinary_icon_blue")).width(150).chain()
      .effect("blackwhite").chain()
      .overlay(new Layer().publicId("cloudinary_icon_blue")).width(50).chain()
      .flags("layer_apply").chain()
      .flags("layer_apply").gravity("north_east")).generate("sample.jpg");
    Kotlin:
    Copy to clipboard
    cloudinary.image {
    publicId("sample.jpg")
    resize(Resize.scale() {
    width(500)
    })
    overlay(Overlay.source(Source.image("cloudinary_icon_blue") {
    transformation(ImageTransformation {
    resize(Resize.scale() {
    width(150)
    })
    effect(Effect.blackwhite())
    overlay(Overlay.source(Source.image("cloudinary_icon_blue") {
    transformation(ImageTransformation {
    resize(Resize.scale() {
    width(50)
    })
    })
    }))
    })
    }) {
    position(Position {
    gravity(Gravity.compass(Compass.northEast()))
    })
    })}.generate()
    image with nested layers

Text layer options

Text overlays are actually an image created on the fly and can be further transformed like any other image uploaded to Cloudinary. For example, adding the text string "Welcome", then applying a green outline effect, and resizing the text to be 80% of the width of the base image (l_text:Times_80:Welcome/e_outline,co_green/w_0.8,fl_relative/fl_layer_apply):

Ruby:
Copy to clipboard
cl_image_tag("sample.jpg", :transformation=>[
  {:overlay=>{:font_family=>"Times", :font_size=>80, :text=>"Welcome"}},
  {:effect=>"outline", :color=>"green"},
  {:width=>0.8, :flags=>"relative", :crop=>"scale"},
  {:flags=>"layer_apply"}
  ])
PHP v1:
Copy to clipboard
cl_image_tag("sample.jpg", array("transformation"=>array(
  array("overlay"=>array("font_family"=>"Times", "font_size"=>80, "text"=>"Welcome")),
  array("effect"=>"outline", "color"=>"green"),
  array("width"=>"0.8", "flags"=>"relative", "crop"=>"scale"),
  array("flags"=>"layer_apply")
  )))
PHP v2:
Copy to clipboard
(new ImageTag('sample.jpg'))
  ->overlay(
      Overlay::source(Source::text('Welcome', (new TextStyle('Times', 80)))
        ->transformation((new ImageTransformation())
          ->effect(Effect::outline()->color(Color::GREEN))
          ->resize(Resize::scale()->width(0.8)->relative())
  )));
Python:
Copy to clipboard
CloudinaryImage("sample.jpg").image(transformation=[
  {'overlay': {'font_family': "Times", 'font_size': 80, 'text': "Welcome"}},
  {'effect': "outline", 'color': "green"},
  {'width': "0.8", 'flags': "relative", 'crop': "scale"},
  {'flags': "layer_apply"}
  ])
Node.js:
Copy to clipboard
cloudinary.image("sample.jpg", {transformation: [
  {overlay: {font_family: "Times", font_size: 80, text: "Welcome"}},
  {effect: "outline", color: "green"},
  {width: "0.8", flags: "relative", crop: "scale"},
  {flags: "layer_apply"}
  ]})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation()
  .overlay(new TextLayer().fontFamily("Times").fontSize(80).text("Welcome")).chain()
  .effect("outline").color("green").chain()
  .width(0.8).flags("relative").crop("scale").chain()
  .flags("layer_apply")).imageTag("sample.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('sample.jpg', {transformation: [
  {overlay: new cloudinary.TextLayer().fontFamily("Times").fontSize(80).text("Welcome")},
  {effect: "outline", color: "green"},
  {width: "0.8", flags: "relative", crop: "scale"},
  {flags: "layer_apply"}
  ]}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("sample.jpg", {transformation: [
  {overlay: new cloudinary.TextLayer().fontFamily("Times").fontSize(80).text("Welcome")},
  {effect: "outline", color: "green"},
  {width: "0.8", flags: "relative", crop: "scale"},
  {flags: "layer_apply"}
  ]})
React:
Copy to clipboard
<Image publicId="sample.jpg" >
  <Transformation overlay={{fontFamily: "Times", fontSize: 80, text: "Welcome"}} />
  <Transformation effect="outline" color="green" />
  <Transformation width="0.8" flags="relative" crop="scale" />
  <Transformation flags="layer_apply" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="sample.jpg" >
  <cld-transformation :overlay="{fontFamily: 'Times', fontSize: 80, text: 'Welcome'}" />
  <cld-transformation effect="outline" color="green" />
  <cld-transformation width="0.8" flags="relative" crop="scale" />
  <cld-transformation flags="layer_apply" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="sample.jpg" >
  <cl-transformation overlay="text:Times_80:Welcome">
  </cl-transformation>
  <cl-transformation effect="outline" color="green">
  </cl-transformation>
  <cl-transformation width="0.8" flags="relative" crop="scale">
  </cl-transformation>
  <cl-transformation flags="layer_apply">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Overlay(new TextLayer().FontFamily("Times").FontSize(80).Text("Welcome")).Chain()
  .Effect("outline").Color("green").Chain()
  .Width(0.8).Flags("relative").Crop("scale").Chain()
  .Flags("layer_apply")).BuildImageTag("sample.jpg")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setOverlay("text:Times_80:Welcome").chain()
  .setEffect("outline").setColor("green").chain()
  .setWidth(0.8).setFlags("relative").setCrop("scale").chain()
  .setFlags("layer_apply")).generate("sample.jpg")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation()
  .overlay(new TextLayer().fontFamily("Times").fontSize(80).text("Welcome")).chain()
  .effect("outline").color("green").chain()
  .width(0.8).flags("relative").crop("scale").chain()
  .flags("layer_apply")).generate("sample.jpg");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("sample.jpg")
overlay(Overlay.source(Source.text("Welcome", TextStyle("Times", 80)) {
transformation(ImageTransformation {
effect(Effect.outline() {
color(Color.GREEN)
})
resize(Resize.scale() {
width(0.8f)
relative()
})
})
}))}.generate()
Text with transformations

The text layer itself can also be customized in appearance in a variety of ways, as detailed in the remainder of this section.

Styling parameters

In addition to the required font family and font size values, a variety of optional CSS-like styles are supported, such as decoration, alignment, letter spacing and more. For a full list, see the Styling parameters table in the reference guide.

The Cloudinary SDK helper methods support supplying the values as an array of mapped values or as a serialized string of values. For example, in Ruby (other frameworks use similar syntax): overlay: { text: 'Hello World', font_family: 'Arial', font_size: 18, font_weight: 'bold', font_style: 'italic', letter_spacing: 4 }

For example, to overlay the text string "Flowers" in Verdana bold with a size of 75 pixels, underlined, and with 14 pixels spacing between the letters: l_text:verdana_75_bold_underline_letter_spacing_14:Flowers:

Ruby:
Copy to clipboard
cl_image_tag("flowers.jpg", :transformation=>[
  {:width=>500, :crop=>"scale"},
  {:overlay=>{:font_family=>"Verdana", :font_size=>75, :font_weight=>"bold", :text_decoration=>"underline", :letter_spacing=>14, :text=>"Flowers"}}
  ])
PHP v1:
Copy to clipboard
cl_image_tag("flowers.jpg", array("transformation"=>array(
  array("width"=>500, "crop"=>"scale"),
  array("overlay"=>array("font_family"=>"Verdana", "font_size"=>75, "font_weight"=>"bold", "text_decoration"=>"underline", "letter_spacing"=>14, "text"=>"Flowers"))
  )))
PHP v2:
Copy to clipboard
(new ImageTag('flowers.jpg'))
  ->resize(Resize::scale()->width(500))
  ->overlay(
      Overlay::source(
          Source::text('Flowers', (new TextStyle('Verdana', 75))
            ->fontWeight(FontWeight::bold())
            ->textDecoration(TextDecoration::underline())
            ->letterSpacing(14)
      
      )));
Python:
Copy to clipboard
CloudinaryImage("flowers.jpg").image(transformation=[
  {'width': 500, 'crop': "scale"},
  {'overlay': {'font_family': "Verdana", 'font_size': 75, 'font_weight': "bold", 'text_decoration': "underline", 'letter_spacing': 14, 'text': "Flowers"}}
  ])
Node.js:
Copy to clipboard
cloudinary.image("flowers.jpg", {transformation: [
  {width: 500, crop: "scale"},
  {overlay: {font_family: "Verdana", font_size: 75, font_weight: "bold", text_decoration: "underline", letter_spacing: 14, text: "Flowers"}}
  ]})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation()
  .width(500).crop("scale").chain()
  .overlay(new TextLayer().fontFamily("Verdana").fontSize(75).fontWeight("bold").textDecoration("underline").letterSpacing(14).text("Flowers"))).imageTag("flowers.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('flowers.jpg', {transformation: [
  {width: 500, crop: "scale"},
  {overlay: new cloudinary.TextLayer().fontFamily("Verdana").fontSize(75).fontWeight("bold").textDecoration("underline").letterSpacing(14).text("Flowers")}
  ]}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("flowers.jpg", {transformation: [
  {width: 500, crop: "scale"},
  {overlay: new cloudinary.TextLayer().fontFamily("Verdana").fontSize(75).fontWeight("bold").textDecoration("underline").letterSpacing(14).text("Flowers")}
  ]})
React:
Copy to clipboard
<Image publicId="flowers.jpg" >
  <Transformation width="500" crop="scale" />
  <Transformation overlay={{fontFamily: "Verdana", fontSize: 75, fontWeight: "bold", textDecoration: "underline", letterSpacing: 14, text: "Flowers"}} />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="flowers.jpg" >
  <cld-transformation width="500" crop="scale" />
  <cld-transformation :overlay="{fontFamily: 'Verdana', fontSize: 75, fontWeight: 'bold', textDecoration: 'underline', letterSpacing: 14, text: 'Flowers'}" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="flowers.jpg" >
  <cl-transformation width="500" crop="scale">
  </cl-transformation>
  <cl-transformation overlay="text:Verdana_75_bold_underline_letter_spacing_14:Flowers">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(500).Crop("scale").Chain()
  .Overlay(new TextLayer().FontFamily("Verdana").FontSize(75).FontWeight("bold").TextDecoration("underline").LetterSpacing(14).Text("Flowers"))).BuildImageTag("flowers.jpg")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setWidth(500).setCrop("scale").chain()
  .setOverlay("text:Verdana_75_bold_underline_letter_spacing_14:Flowers")).generate("flowers.jpg")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation()
  .width(500).crop("scale").chain()
  .overlay(new TextLayer().fontFamily("Verdana").fontSize(75).fontWeight("bold").textDecoration("underline").letterSpacing(14).text("Flowers"))).generate("flowers.jpg");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("flowers.jpg")
resize(Resize.scale() {
width(500)
})
overlay(Overlay.source(Source.text("Flowers", TextStyle("Verdana", 75) {
fontWeight(FontWeight.bold())
textDecoration(TextDecoration.underline())
letterSpacing(14)
})))}.generate()
Adding text to image

Text color

You can control the color of the text overlay by adding the color property (co in URLs).

Opaque colors can be set as an RGB hex triplet (e.g., co_rgb:3e2222), a 3-digit RGB hex (e.g., co_rgb:777) or a named color (e.g., co_green). Cloudinary's client libraries also support a # shortcut for RGB (e.g., setting the color to #3e2222 which is then translated to co_rgb:3e2222). By default, if the color property is omitted then the text has a black color.

For example, adding the text string "Cool image" in Times bold with a size of 90 pixels at a distance of 20 pixels from the bottom of the base image, in yellow text (FFFF00):

Ruby:
Copy to clipboard
cl_image_tag("flowers.jpg", :transformation=>[
  {:width=>500, :crop=>"scale"},
  {:overlay=>{:font_family=>"Times", :font_size=>90, :font_weight=>"bold", :text=>"Cool%20image"}, :gravity=>"south", :y=>20, :color=>"#FFFF00"}
  ])
PHP v1:
Copy to clipboard
cl_image_tag("flowers.jpg", array("transformation"=>array(
  array("width"=>500, "crop"=>"scale"),
  array("overlay"=>array("font_family"=>"Times", "font_size"=>90, "font_weight"=>"bold", "text"=>"Cool%20image"), "gravity"=>"south", "y"=>20, "color"=>"#FFFF00")
  )))
PHP v2:
Copy to clipboard
(new ImageTag('flowers.jpg'))
  ->resize(Resize::scale()->width(500))
  ->overlay(
      Overlay::source(
          Source::text('Cool image', (new TextStyle('Times', 90))
            ->fontWeight(FontWeight::bold()))
          ->textColor(Color::rgb('FFFF00')))
        ->position((new Position())
          ->gravity(Gravity::compass(Compass::south()))
          ->offsetY(20)
      
      ));
Python:
Copy to clipboard
CloudinaryImage("flowers.jpg").image(transformation=[
  {'width': 500, 'crop': "scale"},
  {'overlay': {'font_family': "Times", 'font_size': 90, 'font_weight': "bold", 'text': "Cool%20image"}, 'gravity': "south", 'y': 20, 'color': "#FFFF00"}
  ])
Node.js:
Copy to clipboard
cloudinary.image("flowers.jpg", {transformation: [
  {width: 500, crop: "scale"},
  {overlay: {font_family: "Times", font_size: 90, font_weight: "bold", text: "Cool%20image"}, gravity: "south", y: 20, color: "#FFFF00"}
  ]})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation()
  .width(500).crop("scale").chain()
  .overlay(new TextLayer().fontFamily("Times").fontSize(90).fontWeight("bold").text("Cool%20image")).gravity("south").y(20).color("#FFFF00")).imageTag("flowers.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('flowers.jpg', {transformation: [
  {width: 500, crop: "scale"},
  {overlay: new cloudinary.TextLayer().fontFamily("Times").fontSize(90).fontWeight("bold").text("Cool%20image"), gravity: "south", y: 20, color: "#FFFF00"}
  ]}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("flowers.jpg", {transformation: [
  {width: 500, crop: "scale"},
  {overlay: new cloudinary.TextLayer().fontFamily("Times").fontSize(90).fontWeight("bold").text("Cool%20image"), gravity: "south", y: 20, color: "#FFFF00"}
  ]})
React:
Copy to clipboard
<Image publicId="flowers.jpg" >
  <Transformation width="500" crop="scale" />
  <Transformation overlay={{fontFamily: "Times", fontSize: 90, fontWeight: "bold", text: "Cool%20image"}} gravity="south" y="20" color="#FFFF00" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="flowers.jpg" >
  <cld-transformation width="500" crop="scale" />
  <cld-transformation :overlay="{fontFamily: 'Times', fontSize: 90, fontWeight: 'bold', text: 'Cool%20image'}" gravity="south" y="20" color="#FFFF00" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="flowers.jpg" >
  <cl-transformation width="500" crop="scale">
  </cl-transformation>
  <cl-transformation overlay="text:Times_90_bold:Cool%20image" gravity="south" y="20" color="#FFFF00">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(500).Crop("scale").Chain()
  .Overlay(new TextLayer().FontFamily("Times").FontSize(90).FontWeight("bold").Text("Cool%20image")).Gravity("south").Y(20).Color("#FFFF00")).BuildImageTag("flowers.jpg")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setWidth(500).setCrop("scale").chain()
  .setOverlay("text:Times_90_bold:Cool%20image").setGravity("south").setY(20).setColor("#FFFF00")).generate("flowers.jpg")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation()
  .width(500).crop("scale").chain()
  .overlay(new TextLayer().fontFamily("Times").fontSize(90).fontWeight("bold").text("Cool%20image")).gravity("south").y(20).color("#FFFF00")).generate("flowers.jpg");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("flowers.jpg")
resize(Resize.scale() {
width(500)
})
overlay(Overlay.source(Source.text("Cool image", TextStyle("Times", 90) {
fontWeight(FontWeight.bold())
}) {
textColor(Color.rgb("#FFFF00"))
}) {
position(Position {
gravity(Gravity.compass(Compass.south()))
offsetY(20)
})
})}.generate()
Cool image text added to image

You can also use a 4-digit or 8-digit RGBA hex quadruplet for the color, where the 4th hex value represents the alpha (opacity) value (e.g., co_rgb:3e222240 results in 25% opacity).

The example below uses the same text string "Cool image" in Times bold with a size of 90 pixels at a distance of 20 pixels from the bottom of the base image, in yellow text, but this time with an opacity of 50% (FFFF0080):

Ruby:
Copy to clipboard
cl_image_tag("flowers.jpg", :transformation=>[
  {:width=>500, :crop=>"scale"},
  {:overlay=>{:font_family=>"Times", :font_size=>90, :font_weight=>"bold", :text=>"Cool%20image"}, :gravity=>"south", :y=>20, :color=>"#FFFF0080"}
  ])
PHP v1:
Copy to clipboard
cl_image_tag("flowers.jpg", array("transformation"=>array(
  array("width"=>500, "crop"=>"scale"),
  array("overlay"=>array("font_family"=>"Times", "font_size"=>90, "font_weight"=>"bold", "text"=>"Cool%20image"), "gravity"=>"south", "y"=>20, "color"=>"#FFFF0080")
  )))
PHP v2:
Copy to clipboard
(new ImageTag('flowers.jpg'))
  ->resize(Resize::scale()->width(500))
  ->overlay(
      Overlay::source(
          Source::text('Cool image', (new TextStyle('Times', 90))
            ->fontWeight(FontWeight::bold()))
          ->textColor(Color::rgb('FFFF0080')))
        ->position((new Position())
          ->gravity(Gravity::compass(Compass::south()))
          ->offsetY(20)
      
      ));
Python:
Copy to clipboard
CloudinaryImage("flowers.jpg").image(transformation=[
  {'width': 500, 'crop': "scale"},
  {'overlay': {'font_family': "Times", 'font_size': 90, 'font_weight': "bold", 'text': "Cool%20image"}, 'gravity': "south", 'y': 20, 'color': "#FFFF0080"}
  ])
Node.js:
Copy to clipboard
cloudinary.image("flowers.jpg", {transformation: [
  {width: 500, crop: "scale"},
  {overlay: {font_family: "Times", font_size: 90, font_weight: "bold", text: "Cool%20image"}, gravity: "south", y: 20, color: "#FFFF0080"}
  ]})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation()
  .width(500).crop("scale").chain()
  .overlay(new TextLayer().fontFamily("Times").fontSize(90).fontWeight("bold").text("Cool%20image")).gravity("south").y(20).color("#FFFF0080")).imageTag("flowers.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('flowers.jpg', {transformation: [
  {width: 500, crop: "scale"},
  {overlay: new cloudinary.TextLayer().fontFamily("Times").fontSize(90).fontWeight("bold").text("Cool%20image"), gravity: "south", y: 20, color: "#FFFF0080"}
  ]}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("flowers.jpg", {transformation: [
  {width: 500, crop: "scale"},
  {overlay: new cloudinary.TextLayer().fontFamily("Times").fontSize(90).fontWeight("bold").text("Cool%20image"), gravity: "south", y: 20, color: "#FFFF0080"}
  ]})
React:
Copy to clipboard
<Image publicId="flowers.jpg" >
  <Transformation width="500" crop="scale" />
  <Transformation overlay={{fontFamily: "Times", fontSize: 90, fontWeight: "bold", text: "Cool%20image"}} gravity="south" y="20" color="#FFFF0080" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="flowers.jpg" >
  <cld-transformation width="500" crop="scale" />
  <cld-transformation :overlay="{fontFamily: 'Times', fontSize: 90, fontWeight: 'bold', text: 'Cool%20image'}" gravity="south" y="20" color="#FFFF0080" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="flowers.jpg" >
  <cl-transformation width="500" crop="scale">
  </cl-transformation>
  <cl-transformation overlay="text:Times_90_bold:Cool%20image" gravity="south" y="20" color="#FFFF0080">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(500).Crop("scale").Chain()
  .Overlay(new TextLayer().FontFamily("Times").FontSize(90).FontWeight("bold").Text("Cool%20image")).Gravity("south").Y(20).Color("#FFFF0080")).BuildImageTag("flowers.jpg")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setWidth(500).setCrop("scale").chain()
  .setOverlay("text:Times_90_bold:Cool%20image").setGravity("south").setY(20).setColor("#FFFF0080")).generate("flowers.jpg")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation()
  .width(500).crop("scale").chain()
  .overlay(new TextLayer().fontFamily("Times").fontSize(90).fontWeight("bold").text("Cool%20image")).gravity("south").y(20).color("#FFFF0080")).generate("flowers.jpg");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("flowers.jpg")
resize(Resize.scale() {
width(500)
})
overlay(Overlay.source(Source.text("Cool image", TextStyle("Times", 90) {
fontWeight(FontWeight.bold())
}) {
textColor(Color.rgb("#FFFF0080"))
}) {
position(Position {
gravity(Gravity.compass(Compass.south()))
offsetY(20)
})
})}.generate()
Cool image text added to image

Adding multi-line text

You can manually add multiple lines of text by separating each line of text with the newline character (%0A). For example, adding the text string "Cool image" in Verdana bold with a size of 50 pixels at a distance of 10 pixels from the left border of the base image, where each word appears on a new line:

Ruby:
Copy to clipboard
cl_image_tag("flowers.jpg", :transformation=>[
  {:width=>500, :crop=>"scale"},
  {:overlay=>{:font_family=>"Verdana", :font_size=>50, :font_weight=>"bold", :text=>"Cool%0Aimage"}, :gravity=>"west", :x=>10}
  ])
PHP v1:
Copy to clipboard
cl_image_tag("flowers.jpg", array("transformation"=>array(
  array("width"=>500, "crop"=>"scale"),
  array("overlay"=>array("font_family"=>"Verdana", "font_size"=>50, "font_weight"=>"bold", "text"=>"Cool%0Aimage"), "gravity"=>"west", "x"=>10)
  )))
PHP v2:
Copy to clipboard
(new ImageTag('flowers.jpg'))
  ->resize(Resize::scale()->width(500))
  ->overlay(
      Overlay::source(Source::text('Cool
image', (new TextStyle('Verdana', 50)
    )->fontWeight(FontWeight::bold())))
->position((new Position())
  ->gravity(Gravity::compass(Compass::west()))
  ->offsetX(10)));
Python:
Copy to clipboard
CloudinaryImage("flowers.jpg").image(transformation=[
  {'width': 500, 'crop': "scale"},
  {'overlay': {'font_family': "Verdana", 'font_size': 50, 'font_weight': "bold", 'text': "Cool%0Aimage"}, 'gravity': "west", 'x': 10}
  ])
Node.js:
Copy to clipboard
cloudinary.image("flowers.jpg", {transformation: [
  {width: 500, crop: "scale"},
  {overlay: {font_family: "Verdana", font_size: 50, font_weight: "bold", text: "Cool%0Aimage"}, gravity: "west", x: 10}
  ]})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation()
  .width(500).crop("scale").chain()
  .overlay(new TextLayer().fontFamily("Verdana").fontSize(50).fontWeight("bold").text("Cool%0Aimage")).gravity("west").x(10)).imageTag("flowers.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('flowers.jpg', {transformation: [
  {width: 500, crop: "scale"},
  {overlay: new cloudinary.TextLayer().fontFamily("Verdana").fontSize(50).fontWeight("bold").text("Cool%0Aimage"), gravity: "west", x: 10}
  ]}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("flowers.jpg", {transformation: [
  {width: 500, crop: "scale"},
  {overlay: new cloudinary.TextLayer().fontFamily("Verdana").fontSize(50).fontWeight("bold").text("Cool%0Aimage"), gravity: "west", x: 10}
  ]})
React:
Copy to clipboard
<Image publicId="flowers.jpg" >
  <Transformation width="500" crop="scale" />
  <Transformation overlay={{fontFamily: "Verdana", fontSize: 50, fontWeight: "bold", text: "Cool%0Aimage"}} gravity="west" x="10" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="flowers.jpg" >
  <cld-transformation width="500" crop="scale" />
  <cld-transformation :overlay="{fontFamily: 'Verdana', fontSize: 50, fontWeight: 'bold', text: 'Cool%0Aimage'}" gravity="west" x="10" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="flowers.jpg" >
  <cl-transformation width="500" crop="scale">
  </cl-transformation>
  <cl-transformation overlay="text:Verdana_50_bold:Cool%0Aimage" gravity="west" x="10">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(500).Crop("scale").Chain()
  .Overlay(new TextLayer().FontFamily("Verdana").FontSize(50).FontWeight("bold").Text("Cool%0Aimage")).Gravity("west").X(10)).BuildImageTag("flowers.jpg")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setWidth(500).setCrop("scale").chain()
  .setOverlay("text:Verdana_50_bold:Cool%0Aimage").setGravity("west").setX(10)).generate("flowers.jpg")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation()
  .width(500).crop("scale").chain()
  .overlay(new TextLayer().fontFamily("Verdana").fontSize(50).fontWeight("bold").text("Cool%0Aimage")).gravity("west").x(10)).generate("flowers.jpg");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("flowers.jpg")
resize(Resize.scale() {
width(500)
})
overlay(Overlay.source(Source.text("Cool
image", TextStyle("Verdana", 50) {
fontWeight(FontWeight.bold())
})) {
position(Position {
gravity(Gravity.compass(Compass.west()))
offsetX(10)
})
})}.generate()
Cool image text added to image

Cloudinary also supports automatic multi-line text by defining a maximum width for the text string and adding the fit crop mode, which tells Cloudinary to automatically wrap the actual text content onto a new line once the width is reached. For example, to add a long text string in bold Neucha font with a size of 26 pixels to the base image, that wraps at a width of 400 pixels:

Ruby:
Copy to clipboard
cl_image_tag("flowers.jpg", :transformation=>[
  {:width=>500, :crop=>"scale"},
  {:width=>400, :overlay=>{:font_family=>"Neucha", :font_size=>26, :font_weight=>"bold", :text=>"Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."}, :crop=>"fit"}
  ])
PHP v1:
Copy to clipboard
cl_image_tag("flowers.jpg", array("transformation"=>array(
  array("width"=>500, "crop"=>"scale"),
  array("width"=>400, "overlay"=>array("font_family"=>"Neucha", "font_size"=>26, "font_weight"=>"bold", "text"=>"Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."), "crop"=>"fit")
  )))
PHP v2:
Copy to clipboard
(new ImageTag('flowers.jpg'))
  ->resize(Resize::scale()->width(500))
  ->overlay(
      Overlay::source(
          Source::text('Lorem ipsum dolor sit amet consectetur adipisicing elit sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.', (new TextStyle('Neucha', 26))
            ->fontWeight(FontWeight::bold()))
          ->transformation((new ImageTransformation())
            ->resize(Resize::fit()->width(400))
      
      )));
Python:
Copy to clipboard
CloudinaryImage("flowers.jpg").image(transformation=[
  {'width': 500, 'crop': "scale"},
  {'width': 400, 'overlay': {'font_family': "Neucha", 'font_size': 26, 'font_weight': "bold", 'text': "Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."}, 'crop': "fit"}
  ])
Node.js:
Copy to clipboard
cloudinary.image("flowers.jpg", {transformation: [
  {width: 500, crop: "scale"},
  {width: 400, overlay: {font_family: "Neucha", font_size: 26, font_weight: "bold", text: "Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."}, crop: "fit"}
  ]})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation()
  .width(500).crop("scale").chain()
  .width(400).overlay(new TextLayer().fontFamily("Neucha").fontSize(26).fontWeight("bold").text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.")).crop("fit")).imageTag("flowers.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('flowers.jpg', {transformation: [
  {width: 500, crop: "scale"},
  {width: 400, overlay: new cloudinary.TextLayer().fontFamily("Neucha").fontSize(26).fontWeight("bold").text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."), crop: "fit"}
  ]}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("flowers.jpg", {transformation: [
  {width: 500, crop: "scale"},
  {width: 400, overlay: new cloudinary.TextLayer().fontFamily("Neucha").fontSize(26).fontWeight("bold").text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."), crop: "fit"}
  ]})
React:
Copy to clipboard
<Image publicId="flowers.jpg" >
  <Transformation width="500" crop="scale" />
  <Transformation width="400" overlay={{fontFamily: "Neucha", fontSize: 26, fontWeight: "bold", text: "Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."}} crop="fit" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="flowers.jpg" >
  <cld-transformation width="500" crop="scale" />
  <cld-transformation width="400" :overlay="{fontFamily: 'Neucha', fontSize: 26, fontWeight: 'bold', text: 'Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.'}" crop="fit" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="flowers.jpg" >
  <cl-transformation width="500" crop="scale">
  </cl-transformation>
  <cl-transformation width="400" overlay="text:Neucha_26_bold:Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat." crop="fit">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(500).Crop("scale").Chain()
  .Width(400).Overlay(new TextLayer().FontFamily("Neucha").FontSize(26).FontWeight("bold").Text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.")).Crop("fit")).BuildImageTag("flowers.jpg")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setWidth(500).setCrop("scale").chain()
  .setWidth(400).setOverlay("text:Neucha_26_bold:Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.").setCrop("fit")).generate("flowers.jpg")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation()
  .width(500).crop("scale").chain()
  .width(400).overlay(new TextLayer().fontFamily("Neucha").fontSize(26).fontWeight("bold").text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.")).crop("fit")).generate("flowers.jpg");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("flowers.jpg")
resize(Resize.scale() {
width(500)
})
overlay(Overlay.source(Source.text("Lorem ipsum dolor sit amet consectetur adipisicing elit sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.", TextStyle("Neucha", 26) {
fontWeight(FontWeight.bold())
}) {
transformation(ImageTransformation {
resize(Resize.fit() {
width(400)
})
})
}))}.generate()
Multi-line text string

To define a maximum height for the multi-line text add the height parameter: any text that does not fit within the space defined is cut and an ellipsis (...) is added to the end of the text string to indicate that the text was truncated. You can also set the text alignment and line spacing values to further control the text's appearance.

For example, to add a long text string in center aligned bold Times font with a size of 14 pixels to the base image, that wraps at a width of 200 pixels and is limited to a height of 150 pixels. The text is also rotated by 9 degrees and set 30 pixels from the north border to better align with the underlying image:

Ruby:
Copy to clipboard
cl_image_tag("envelope.jpg", :transformation=>[
  {:width=>300, :crop=>"scale"},
  {:width=>200, :y=>30, :angle=>9, :height=>150, :gravity=>"north", :overlay=>{:font_family=>"Times", :font_size=>18, :font_weight=>"bold", :text_align=>"center", :text=>"Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."}, :crop=>"fit"}
  ])
PHP v1:
Copy to clipboard
cl_image_tag("envelope.jpg", array("transformation"=>array(
  array("width"=>300, "crop"=>"scale"),
  array("width"=>200, "y"=>30, "angle"=>9, "height"=>150, "gravity"=>"north", "overlay"=>array("font_family"=>"Times", "font_size"=>18, "font_weight"=>"bold", "text_align"=>"center", "text"=>"Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."), "crop"=>"fit")
  )))
PHP v2:
Copy to clipboard
(new ImageTag('envelope.jpg'))
  ->resize(Resize::scale()->width(300))
  ->overlay(
      Overlay::source(
          Source::text('Lorem ipsum dolor sit amet consectetur adipisicing elit sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.', (new TextStyle('Times', 18))
            ->fontWeight(FontWeight::bold())
            ->textAlignment(TextAlignment::center()))
          ->transformation((new ImageTransformation())
            ->rotate(Rotate::byAngle(9))
            ->resize(Resize::fit()->width(200)->height(150))))
        ->position((new Position())
          ->gravity(Gravity::compass(Compass::north()))
          ->offsetY(30)
      
      ));
Python:
Copy to clipboard
CloudinaryImage("envelope.jpg").image(transformation=[
  {'width': 300, 'crop': "scale"},
  {'width': 200, 'y': 30, 'angle': 9, 'height': 150, 'gravity': "north", 'overlay': {'font_family': "Times", 'font_size': 18, 'font_weight': "bold", 'text_align': "center", 'text': "Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."}, 'crop': "fit"}
  ])
Node.js:
Copy to clipboard
cloudinary.image("envelope.jpg", {transformation: [
  {width: 300, crop: "scale"},
  {width: 200, y: 30, angle: 9, height: 150, gravity: "north", overlay: {font_family: "Times", font_size: 18, font_weight: "bold", text_align: "center", text: "Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."}, crop: "fit"}
  ]})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation()
  .width(300).crop("scale").chain()
  .width(200).y(30).angle(9).height(150).gravity("north").overlay(new TextLayer().fontFamily("Times").fontSize(18).fontWeight("bold").textAlign("center").text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.")).crop("fit")).imageTag("envelope.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('envelope.jpg', {transformation: [
  {width: 300, crop: "scale"},
  {width: 200, y: 30, angle: 9, height: 150, gravity: "north", overlay: new cloudinary.TextLayer().fontFamily("Times").fontSize(18).fontWeight("bold").textAlign("center").text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."), crop: "fit"}
  ]}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("envelope.jpg", {transformation: [
  {width: 300, crop: "scale"},
  {width: 200, y: 30, angle: 9, height: 150, gravity: "north", overlay: new cloudinary.TextLayer().fontFamily("Times").fontSize(18).fontWeight("bold").textAlign("center").text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."), crop: "fit"}
  ]})
React:
Copy to clipboard
<Image publicId="envelope.jpg" >
  <Transformation width="300" crop="scale" />
  <Transformation width="200" y="30" angle="9" height="150" gravity="north" overlay={{fontFamily: "Times", fontSize: 18, fontWeight: "bold", textAlign: "center", text: "Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat."}} crop="fit" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="envelope.jpg" >
  <cld-transformation width="300" crop="scale" />
  <cld-transformation width="200" y="30" angle="9" height="150" gravity="north" :overlay="{fontFamily: 'Times', fontSize: 18, fontWeight: 'bold', textAlign: 'center', text: 'Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.'}" crop="fit" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="envelope.jpg" >
  <cl-transformation width="300" crop="scale">
  </cl-transformation>
  <cl-transformation width="200" y="30" angle="9" height="150" gravity="north" overlay="text:Times_18_bold_center:Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat." crop="fit">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(300).Crop("scale").Chain()
  .Width(200).Y(30).Angle(9).Height(150).Gravity("north").Overlay(new TextLayer().FontFamily("Times").FontSize(18).FontWeight("bold").TextAlign("center").Text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.")).Crop("fit")).BuildImageTag("envelope.jpg")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setWidth(300).setCrop("scale").chain()
  .setWidth(200).setY(30).setAngle(9).setHeight(150).setGravity("north").setOverlay("text:Times_18_bold_center:Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.").setCrop("fit")).generate("envelope.jpg")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation()
  .width(300).crop("scale").chain()
  .width(200).y(30).angle(9).height(150).gravity("north").overlay(new TextLayer().fontFamily("Times").fontSize(18).fontWeight("bold").textAlign("center").text("Lorem%20ipsum%20dolor%20sit%20amet%20consectetur%20adipisicing%20elit%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Ut%20enim%20ad%20minim%20veniam%20quis%20nostrud%20exercitation%20ullamco%20laboris%20nisi%20ut%20aliquip%20ex%20ea%20commodo%20consequat.")).crop("fit")).generate("envelope.jpg");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("envelope.jpg")
resize(Resize.scale() {
width(300)
})
overlay(Overlay.source(Source.text("Lorem ipsum dolor sit amet consectetur adipisicing elit sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.", TextStyle("Times", 18) {
fontWeight(FontWeight.bold())
textAlignment(TextAlignment.center())
}) {
transformation(ImageTransformation {
rotate(Rotate.byAngle(9))
resize(Resize.fit() {
width(200)
height(150)
})
})
}) {
position(Position {
gravity(Gravity.compass(Compass.north()))
offsetY(30)
})
})}.generate()
Multi-line text limited with height

Special characters

Text strings containing special characters need to be modified (escaped) for use with the text overlay feature. This is relevant for any special characters that would not be allowed “as is” in a valid URL path, as well as other special Unicode characters. These text strings should be escaped using %-based UTF-8 encoding to ensure the text string is valid (for example, replace ? with %3F and use %20 for spaces between words). This encoding is done automatically when embedding images using the Cloudinary SDK helper methods and only needs to be done when manually building the asset delivery URL.

Additionally, to include a comma (,) forward slash (/), percent sign (%) or an emoji character in a text overlay, you must double-escape the % sign within those codes. For example:

Custom fonts

By default, only universally available fonts are supported for text overlays. However, if you want to use a non-standard font, you can upload it to your Cloudinary account as a raw, authenticated file and then specify the font's full public_id (including extension) as the font for your overlay:

Copy to clipboard
Cloudinary::Uploader.upload("AlexBrush-Regular.ttf", 
    resource_type: 'raw', # Custom fonts must be upload as 'raw'
    type: 'authenticated', # Custom fonts must be upload as 'authenticated'
    public_id: 'AlexBrush-Regular.ttf')

Ruby:
Copy to clipboard
cl_image_tag("fireworks.jpg", :overlay=>{:font_family=>"ttf", :font_size=>100, :text=>"Happy%20New%20Year%20%202017%20"}, :color=>"white", :gravity=>"north_west", :x=>30, :y=>30)
PHP v1:
Copy to clipboard
cl_image_tag("fireworks.jpg", array("overlay"=>array("font_family"=>"ttf", "font_size"=>100, "text"=>"Happy%20New%20Year%20%202017%20"), "color"=>"white", "gravity"=>"north_west", "x"=>30, "y"=>30))
PHP v2:
Copy to clipboard
(new ImageTag('fireworks.jpg'))
  ->overlay(
      Overlay::source(Source::text('Happy New Year  2017 ', (new TextStyle('AlexBrush-Regular.ttf', 100)))
        ->textColor(Color::WHITE))
      ->position((new Position())
        ->gravity(Gravity::compass(Compass::northWest()))
        ->offsetX(30)->offsetY(30)
  ));
Python:
Copy to clipboard
CloudinaryImage("fireworks.jpg").image(overlay={'font_family': "ttf", 'font_size': 100, 'text': "Happy%20New%20Year%20%202017%20"}, color="white", gravity="north_west", x=30, y=30)
Node.js:
Copy to clipboard
cloudinary.image("fireworks.jpg", {overlay: {font_family: "ttf", font_size: 100, text: "Happy%20New%20Year%20%202017%20"}, color: "white", gravity: "north_west", x: 30, y: 30})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().overlay(new TextLayer().fontFamily("ttf").fontSize(100).text("Happy%20New%20Year%20%202017%20")).color("white").gravity("north_west").x(30).y(30)).imageTag("fireworks.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('fireworks.jpg', {overlay: new cloudinary.TextLayer().fontFamily("ttf").fontSize(100).text("Happy%20New%20Year%20%202017%20"), color: "white", gravity: "north_west", x: 30, y: 30}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("fireworks.jpg", {overlay: new cloudinary.TextLayer().fontFamily("ttf").fontSize(100).text("Happy%20New%20Year%20%202017%20"), color: "white", gravity: "north_west", x: 30, y: 30})
React:
Copy to clipboard
<Image publicId="fireworks.jpg" >
  <Transformation overlay={{fontFamily: "ttf", fontSize: 100, text: "Happy%20New%20Year%20%202017%20"}} color="white" gravity="north_west" x="30" y="30" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="fireworks.jpg" >
  <cld-transformation :overlay="{fontFamily: 'ttf', fontSize: 100, text: 'Happy%20New%20Year%20%202017%20'}" color="white" gravity="north_west" x="30" y="30" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="fireworks.jpg" >
  <cl-transformation overlay="text:AlexBrush-Regular.ttf_100:Happy%20New%20Year%20%202017%20" color="white" gravity="north_west" x="30" y="30">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new TextLayer().FontFamily("ttf").FontSize(100).Text("Happy%20New%20Year%20%202017%20")).Color("white").Gravity("north_west").X(30).Y(30)).BuildImageTag("fireworks.jpg")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("text:AlexBrush-Regular.ttf_100:Happy%20New%20Year%20%202017%20").setColor("white").setGravity("north_west").setX(30).setY(30)).generate("fireworks.jpg")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().overlay(new TextLayer().fontFamily("ttf").fontSize(100).text("Happy%20New%20Year%20%202017%20")).color("white").gravity("north_west").x(30).y(30)).generate("fireworks.jpg");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("fireworks.jpg")
overlay(Overlay.source(Source.text("Happy New Year  2017 ", TextStyle("AlexBrush-Regular.ttf", 100)) {
textColor(Color.WHITE)
}) {
position(Position {
gravity(Gravity.compass(Compass.northWest()))
offsetX(30)
offsetY(30)
})
})}.generate()
Custom font overlay

Custom font guidelines

  • .ttf, .otf and .woff2 font types are supported.
  • Custom fonts must be uploaded as raw, authenticated files.

    Tip
    You can upload custom fonts via the Media Library by creating (or using an existing) signed upload preset where the Delivery type option in the preset is set as Authenticated. You can use this upload preset when uploading files to the Media Library by configuring it as the default Media library upload preset for Raw files.

    Raw, authenticated upload preset

    Alternatively, you can select the signed upload preset you create for custom fonts in the Media Library upload widget's Advanced settings while uploading assets, if that option is enabled for your account.

  • If your custom font is stored in a folder other than the root folder, specify the path using colons as separators. For example: folder1:folder2:myfont.ttf.

  • Make sure to include the file extension when referencing the public_id of the raw file. The extension must be specified in lower-case letters.

  • To make use of bold or italic font styles, upload separate font files for each emphasis style and specify the relevant file in the overlay transformation.

  • A custom font is available only to the specific account or sub-account where it was uploaded.

  • Underscores are not supported in custom font names. When uploading the font as a raw file, make sure the public_id does not include an underscore.

  • As with any asset you upload to Cloudinary, it is your responsibility to make sure you have the necessary license and redistribution rights for any custom fonts you use.

Predefined text templates

Instead of specifying the styling parameters every time you need to dynamically add a text overlay to an image, you can use the Public ID of a text image created with the text method of the upload API. The same styles that were used to create the text image will also be dynamically applied to the text overlay. The default text string of the text image is also used unless you provide a new text string, which can be useful if you don't want the text string to appear in the URL, or if the text string is very long.

For example, adding the text string "Stylish text" using the same styling applied in creating the text image named sample_text_style (Roboto font, 82 size, bold and red):

Ruby:
Copy to clipboard
cl_image_tag("flowers.jpg", :transformation=>[
  {:width=>500, :crop=>"scale"},
  {:overlay=>{:public_id=>"sample_text_style", :text=>"Stylish%20text"}, :gravity=>"south"}
  ])
PHP v1:
Copy to clipboard
cl_image_tag("flowers.jpg", array("transformation"=>array(
  array("width"=>500, "crop"=>"scale"),
  array("overlay"=>array("public_id"=>"sample_text_style", "text"=>"Stylish%20text"), "gravity"=>"south")
  )))
PHP v2:
Copy to clipboard
(new ImageTag('flowers.jpg'))
  ->resize(Resize::scale()->width(500))
  ->overlay(Overlay::source(Source::text('Stylish text', (new TextStyle('sample', 'text'))))
    ->position((new Position())
      ->gravity(Gravity::compass(Compass::south()))));
Python:
Copy to clipboard
CloudinaryImage("flowers.jpg").image(transformation=[
  {'width': 500, 'crop': "scale"},
  {'overlay': {'public_id': "sample_text_style", 'text': "Stylish%20text"}, 'gravity': "south"}
  ])
Node.js:
Copy to clipboard
cloudinary.image("flowers.jpg", {transformation: [
  {width: 500, crop: "scale"},
  {overlay: {public_id: "sample_text_style", text: "Stylish%20text"}, gravity: "south"}
  ]})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation()
  .width(500).crop("scale").chain()
  .overlay(new TextLayer().text("Stylish%20text").publicId("sample_text_style")).gravity("south")).imageTag("flowers.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('flowers.jpg', {transformation: [
  {width: 500, crop: "scale"},
  {overlay: new cloudinary.TextLayer().text("Stylish%20text").publicId("sample_text_style"), gravity: "south"}
  ]}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("flowers.jpg", {transformation: [
  {width: 500, crop: "scale"},
  {overlay: new cloudinary.TextLayer().text("Stylish%20text").publicId("sample_text_style"), gravity: "south"}
  ]})
React:
Copy to clipboard
<Image publicId="flowers.jpg" >
  <Transformation width="500" crop="scale" />
  <Transformation overlay={{text: "Stylish%20text", publicId: "sample_text_style"}} gravity="south" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="flowers.jpg" >
  <cld-transformation width="500" crop="scale" />
  <cld-transformation :overlay="{text: 'Stylish%20text', publicId: 'sample_text_style'}" gravity="south" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="flowers.jpg" >
  <cl-transformation width="500" crop="scale">
  </cl-transformation>
  <cl-transformation overlay="text:sample_text_style:Stylish%20text" gravity="south">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(500).Crop("scale").Chain()
  .Overlay(new TextLayer().Text("Stylish%20text").PublicId("sample_text_style")).Gravity("south")).BuildImageTag("flowers.jpg")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setWidth(500).setCrop("scale").chain()
  .setOverlay("text:sample_text_style:Stylish%20text").setGravity("south")).generate("flowers.jpg")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation()
  .width(500).crop("scale").chain()
  .overlay(new TextLayer().text("Stylish%20text").publicId("sample_text_style")).gravity("south")).generate("flowers.jpg");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("flowers.jpg")
resize(Resize.scale() {
width(500)
})
overlay(Overlay.source(Source.text("Stylish text", TextStyle("sample", "text"))) {
position(Position {
gravity(Gravity.compass(Compass.south()))
})
})}.generate()
Cool image text added to image

Text layer flags

The text content for text layers is often supplied in real time by your application users or another external source. You may want to use the following flags to help handle these scenarios:

  • fl_disallow_overflow: As mentioned in layer overflow behavior above, you can control whether large image or text layers will result in expanding the size of the delivered asset using the fl_no_overflow flag.

    However, for text overlays, if you don't want long text to impact the expected delivery asset size, but an unexpected trim might risk cutting off essential text, you can apply the fl_disallow_overflow flag, which will cause URLs with overflowing text layers to fail and return a 400 (bad request) error that you can check for and handle in your application.

    For more details and examples, see fl_no_overflow and fl_disallow_overflow in the Transformation Reference.

  • fl_text_no_trim: By default, text layers are tightly trimmed on all sides. In some cases, especially if you add a border around the text, or you are using a gravity for your text layer that might place the text too close to the edge of the layer behind it, you can use the fl_text_no_trim flag to add a small amount of padding around the the text overlay string. For example:

    Ruby:
    Copy to clipboard
    cl_image_tag("flower.jpg", :overlay=>{:font_family=>"Arial", :font_size=>150, :text=>"Flowers"}, :color=>"yellow", :border=>"6px_solid_red", :flags=>"text_no_trim")
    PHP v1:
    Copy to clipboard
    cl_image_tag("flower.jpg", array("overlay"=>array("font_family"=>"Arial", "font_size"=>150, "text"=>"Flowers"), "color"=>"yellow", "border"=>"6px_solid_red", "flags"=>"text_no_trim"))
    PHP v2:
    Copy to clipboard
    (new ImageTag('flower.jpg'))
      ->overlay(
          Overlay::source(Source::text('Flowers', (new TextStyle('Arial', 150)))
            ->textColor(Color::YELLOW)
            ->transformation((new ImageTransformation())
              ->border(Border::solid(6, Color::RED))
              ->addFlag(Flag::textNoTrim())
      )));
    Python:
    Copy to clipboard
    CloudinaryImage("flower.jpg").image(overlay={'font_family': "Arial", 'font_size': 150, 'text': "Flowers"}, color="yellow", border="6px_solid_red", flags="text_no_trim")
    Node.js:
    Copy to clipboard
    cloudinary.image("flower.jpg", {overlay: {font_family: "Arial", font_size: 150, text: "Flowers"}, color: "yellow", border: "6px_solid_red", flags: "text_no_trim"})
    Java:
    Copy to clipboard
    cloudinary.url().transformation(new Transformation().overlay(new TextLayer().fontFamily("Arial").fontSize(150).text("Flowers")).color("yellow").border("6px_solid_red").flags("text_no_trim")).imageTag("flower.jpg");
    JS:
    Copy to clipboard
    cloudinary.imageTag('flower.jpg', {overlay: new cloudinary.TextLayer().fontFamily("Arial").fontSize(150).text("Flowers"), color: "yellow", border: "6px_solid_red", flags: "text_no_trim"}).toHtml();
    jQuery:
    Copy to clipboard
    $.cloudinary.image("flower.jpg", {overlay: new cloudinary.TextLayer().fontFamily("Arial").fontSize(150).text("Flowers"), color: "yellow", border: "6px_solid_red", flags: "text_no_trim"})
    React:
    Copy to clipboard
    <Image publicId="flower.jpg" >
      <Transformation overlay={{fontFamily: "Arial", fontSize: 150, text: "Flowers"}} color="yellow" border="6px_solid_red" flags="text_no_trim" />
    </Image>
    Vue.js:
    Copy to clipboard
    <cld-image publicId="flower.jpg" >
      <cld-transformation :overlay="{fontFamily: 'Arial', fontSize: 150, text: 'Flowers'}" color="yellow" border="6px_solid_red" flags="text_no_trim" />
    </cld-image>
    Angular:
    Copy to clipboard
    <cl-image public-id="flower.jpg" >
      <cl-transformation overlay="text:Arial_150:Flowers" color="yellow" border="6px_solid_red" flags="text_no_trim">
      </cl-transformation>
    </cl-image>
    .NET:
    Copy to clipboard
    cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new TextLayer().FontFamily("Arial").FontSize(150).Text("Flowers")).Color("yellow").Border("6px_solid_red").Flags("text_no_trim")).BuildImageTag("flower.jpg")
    iOS:
    Copy to clipboard
    imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("text:Arial_150:Flowers").setColor("yellow").setBorder("6px_solid_red").setFlags("text_no_trim")).generate("flower.jpg")!, cloudinary: cloudinary)
    Android:
    Copy to clipboard
    MediaManager.get().url().transformation(new Transformation().overlay(new TextLayer().fontFamily("Arial").fontSize(150).text("Flowers")).color("yellow").border("6px_solid_red").flags("text_no_trim")).generate("flower.jpg");
    Kotlin:
    Copy to clipboard
    cloudinary.image {
    publicId("flower.jpg")
    overlay(Overlay.source(Source.text("Flowers", TextStyle("Arial", 150)) {
    textColor(Color.YELLOW)
    transformation(ImageTransformation {
    border(Border.solid(6, Color.RED))
    addFlag(Flag.textNoTrim())
    })
    }))}.generate()
    Text with padding

    Note
    When placing a background behind text overlays (e.g., l_text:Arial_100:Flowers,b_green), Cloudinary automatically adds this padding, so this padding flag isn't necessary.

Adding image underlays

Add an underlay image under a base partially-transparent image with the underlay parameter (u in URLs) and the public ID of a previously uploaded image (e.g., u_background for an image with the public ID of background). You can determine the dimension of the underlay using width, height, and the x and y parameters, and adjust the location of the base image over the underlay using the gravity parameter. The underlay can also be further transformed like any other image uploaded to Cloudinary, and the underlay parameter supports the same features as for overlays.

For example, adding an underlay of an image called site_bg to the base image. The underlay and base image are both resized to the same width and height, and the brightness is increased to 100 using the brightness effect:

Ruby:
Copy to clipboard
cl_image_tag("smartphone.png", :transformation=>[
  {:height=>200, :width=>200, :crop=>"fill"},
  {:effect=>"brightness:100", :height=>200, :underlay=>"site_bg", :width=>200}
  ])
PHP v1:
Copy to clipboard
cl_image_tag("smartphone.png", array("transformation"=>array(
  array("height"=>200, "width"=>200, "crop"=>"fill"),
  array("effect"=>"brightness:100", "height"=>200, "underlay"=>"site_bg", "width"=>200)
  )))
PHP v2:
Copy to clipboard
(new ImageTag('smartphone.png'))
  ->resize(Resize::fill()->width(200)->height(200))
  ->underlay(
      Underlay::source(Source::image('site_bg')
        ->transformation((new ImageTransformation())
          ->resize(Resize::scale()->width(200)->height(200))
          ->adjust(Adjust::brightness()->level(100))
  )));
Python:
Copy to clipboard
CloudinaryImage("smartphone.png").image(transformation=[
  {'height': 200, 'width': 200, 'crop': "fill"},
  {'effect': "brightness:100", 'height': 200, 'underlay': "site_bg", 'width': 200}
  ])
Node.js:
Copy to clipboard
cloudinary.image("smartphone.png", {transformation: [
  {height: 200, width: 200, crop: "fill"},
  {effect: "brightness:100", height: 200, underlay: "site_bg", width: 200}
  ]})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation()
  .height(200).width(200).crop("fill").chain()
  .effect("brightness:100").height(200).underlay(new Layer().publicId("site_bg")).width(200)).imageTag("smartphone.png");
JS:
Copy to clipboard
cloudinary.imageTag('smartphone.png', {transformation: [
  {height: 200, width: 200, crop: "fill"},
  {effect: "brightness:100", height: 200, underlay: new cloudinary.Layer().publicId("site_bg"), width: 200}
  ]}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("smartphone.png", {transformation: [
  {height: 200, width: 200, crop: "fill"},
  {effect: "brightness:100", height: 200, underlay: new cloudinary.Layer().publicId("site_bg"), width: 200}
  ]})
React:
Copy to clipboard
<Image publicId="smartphone.png" >
  <Transformation height="200" width="200" crop="fill" />
  <Transformation effect="brightness:100" height="200" underlay="site_bg" width="200" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="smartphone.png" >
  <cld-transformation height="200" width="200" crop="fill" />
  <cld-transformation effect="brightness:100" height="200" :underlay="site_bg" width="200" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="smartphone.png" >
  <cl-transformation height="200" width="200" crop="fill">
  </cl-transformation>
  <cl-transformation effect="brightness:100" height="200" underlay="site_bg" width="200">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Height(200).Width(200).Crop("fill").Chain()
  .Effect("brightness:100").Height(200).Underlay(new Layer().PublicId("site_bg")).Width(200)).BuildImageTag("smartphone.png")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setHeight(200).setWidth(200).setCrop("fill").chain()
  .setEffect("brightness:100").setHeight(200).setUnderlay("site_bg").setWidth(200)).generate("smartphone.png")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation()
  .height(200).width(200).crop("fill").chain()
  .effect("brightness:100").height(200).underlay(new Layer().publicId("site_bg")).width(200)).generate("smartphone.png");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("smartphone.png")
resize(Resize.fill() {
width(200)
height(200)
})
underlay(Underlay.source(Source.image("site_bg") {
transformation(ImageTransformation {
resize(Resize.scale() {
width(200)
height(200)
})
adjust(Adjust.brightness() {
level(100)
})
})
}))}.generate()
Image with underlay

Note
If the public ID of an image includes a folder component (e.g., the public ID of an image is layers/blue) then replace the slash with a colon when using the image as an underlay (e.g., the public ID of the image becomes layers:blue when used as an underlay).

Special layer applications

In addition to the primary use of layers for placing other assets or text on the base asset, some transformation features make use of the layer option to specify a public ID that will be applied to the base image in order to achieve a desired effect.

Watermarking

You can use a standard image layer for the purpose of applying a watermark to any delivered image. Opacity and/or brightness transformations are often applied to image layers when they are used as a watermark.

However, you can also use automatic tiling and/or the smart anti-removal effect with your layer transformation in order to achieve your watermark requirements.

Automatic tiling

Instead of adding your watermark layer to a single, specific location, you can tile layer image over the entire base image by adding the tiled qualifier (fl_tiled in URLs). For example, tiling an overlay of the image called cloudinary_icon_white on to the base image (l_cloudinary_icon_white,fl_tiled):

Ruby:
Copy to clipboard
cl_image_tag("flowers.jpg", :overlay=>"cloudinary_icon_white", :flags=>"tiled")
PHP v1:
Copy to clipboard
cl_image_tag("flowers.jpg", array("overlay"=>"cloudinary_icon_white", "flags"=>"tiled"))
PHP v2:
Copy to clipboard
(new ImageTag('flowers.jpg'))
  ->overlay(Overlay::source(Source::image('cloudinary_icon_white'))
    ->position((new Position())
      ->tiled()));
Python:
Copy to clipboard
CloudinaryImage("flowers.jpg").image(overlay="cloudinary_icon_white", flags="tiled")
Node.js:
Copy to clipboard
cloudinary.image("flowers.jpg", {overlay: "cloudinary_icon_white", flags: "tiled"})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon_white")).flags("tiled")).imageTag("flowers.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('flowers.jpg', {overlay: new cloudinary.Layer().publicId("cloudinary_icon_white"), flags: "tiled"}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("flowers.jpg", {overlay: new cloudinary.Layer().publicId("cloudinary_icon_white"), flags: "tiled"})
React:
Copy to clipboard
<Image publicId="flowers.jpg" >
  <Transformation overlay="cloudinary_icon_white" flags="tiled" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="flowers.jpg" >
  <cld-transformation :overlay="cloudinary_icon_white" flags="tiled" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="flowers.jpg" >
  <cl-transformation overlay="cloudinary_icon_white" flags="tiled">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new Layer().PublicId("cloudinary_icon_white")).Flags("tiled")).BuildImageTag("flowers.jpg")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("cloudinary_icon_white").setFlags("tiled")).generate("flowers.jpg")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().overlay(new Layer().publicId("cloudinary_icon_white")).flags("tiled")).generate("flowers.jpg");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("flowers.jpg")
overlay(Overlay.source(Source.image("cloudinary_icon_white")) {
position(Position {
tiled()
})
})}.generate()
Image with tiled overlay

Smart anti-removal

You can use the anti-removal effect (e_anti_removal in URLs) to slightly modify images overlays in a random manner, thus making them much harder to remove (e.g., adding your logo as a watermark to images). In most cases, the default level of modification is designed to be visually hard to notice, but still difficult to remove cleanly. If needed, you can optionally control the level of distortion that this transformation applies.

For example, adding the anti-removal effect (with a high level of 90 for demonstration purposes) to an overlay of the image called cloudinary_icon_blue added to the north-east corner of the image named flowers, with the overlay's opacity set to 50% and scaled to a width of 200 pixels:

Ruby:
Copy to clipboard
cl_image_tag("flowers.jpg", :transformation=>[
  {:width=>500, :crop=>"scale"},
  {:overlay=>"cloudinary_icon_blue", :gravity=>"north_east", :opacity=>50, :width=>200, :effect=>"anti_removal:90"}
  ])
PHP v1:
Copy to clipboard
cl_image_tag("flowers.jpg", array("transformation"=>array(
  array("width"=>500, "crop"=>"scale"),
  array("overlay"=>"cloudinary_icon_blue", "gravity"=>"north_east", "opacity"=>50, "width"=>200, "effect"=>"anti_removal:90")
  )))
PHP v2:
Copy to clipboard
(new ImageTag('flowers.jpg'))
  ->resize(Resize::scale()->width(500))
  ->overlay(
      Overlay::source(Source::image('cloudinary_icon_blue')
        ->transformation((new ImageTransformation())
          ->resize(Resize::scale()->width(200))
          ->adjust(Adjust::opacity(50))))
      ->position((new Position())
        ->gravity(Gravity::compass(Compass::northEast())))
      ->blendMode(BlendMode::antiRemoval(90))
  );
Python:
Copy to clipboard
CloudinaryImage("flowers.jpg").image(transformation=[
  {'width': 500, 'crop': "scale"},
  {'overlay': "cloudinary_icon_blue", 'gravity': "north_east", 'opacity': 50, 'width': 200, 'effect': "anti_removal:90"}
  ])
Node.js:
Copy to clipboard
cloudinary.image("flowers.jpg", {transformation: [
  {width: 500, crop: "scale"},
  {overlay: "cloudinary_icon_blue", gravity: "north_east", opacity: 50, width: 200, effect: "anti_removal:90"}
  ]})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation()
  .width(500).crop("scale").chain()
  .overlay(new Layer().publicId("cloudinary_icon_blue")).gravity("north_east").opacity(50).width(200).effect("anti_removal:90")).imageTag("flowers.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('flowers.jpg', {transformation: [
  {width: 500, crop: "scale"},
  {overlay: new cloudinary.Layer().publicId("cloudinary_icon_blue"), gravity: "north_east", opacity: 50, width: 200, effect: "anti_removal:90"}
  ]}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("flowers.jpg", {transformation: [
  {width: 500, crop: "scale"},
  {overlay: new cloudinary.Layer().publicId("cloudinary_icon_blue"), gravity: "north_east", opacity: 50, width: 200, effect: "anti_removal:90"}
  ]})
React:
Copy to clipboard
<Image publicId="flowers.jpg" >
  <Transformation width="500" crop="scale" />
  <Transformation overlay="cloudinary_icon_blue" gravity="north_east" opacity="50" width="200" effect="anti_removal:90" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="flowers.jpg" >
  <cld-transformation width="500" crop="scale" />
  <cld-transformation :overlay="cloudinary_icon_blue" gravity="north_east" opacity="50" width="200" effect="anti_removal:90" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="flowers.jpg" >
  <cl-transformation width="500" crop="scale">
  </cl-transformation>
  <cl-transformation overlay="cloudinary_icon_blue" gravity="north_east" opacity="50" width="200" effect="anti_removal:90">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(500).Crop("scale").Chain()
  .Overlay(new Layer().PublicId("cloudinary_icon_blue")).Gravity("north_east").Opacity(50).Width(200).Effect("anti_removal:90")).BuildImageTag("flowers.jpg")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setWidth(500).setCrop("scale").chain()
  .setOverlay("cloudinary_icon_blue").setGravity("north_east").setOpacity(50).setWidth(200).setEffect("anti_removal:90")).generate("flowers.jpg")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation()
  .width(500).crop("scale").chain()
  .overlay(new Layer().publicId("cloudinary_icon_blue")).gravity("north_east").opacity(50).width(200).effect("anti_removal:90")).generate("flowers.jpg");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("flowers.jpg")
resize(Resize.scale() {
width(500)
})
overlay(Overlay.source(Source.image("cloudinary_icon_blue") {
transformation(ImageTransformation {
resize(Resize.scale() {
width(200)
})
adjust(Adjust.opacity(50))
})
}) {
position(Position {
gravity(Gravity.compass(Compass.northEast()))
})
blendMode(BlendMode.antiRemoval(90))
})}.generate()
Image with anti-removal overlay

Note
Adding this effect generates a different result for each derived image, even if the transformation is the same. For example, every transformation URL including an overlay and the anti-removal effect, where only the public_id of the base image is changed, will result in a slightly different overlay.

See full syntax: e_anti_removal in the Transformation Reference.

3D LUTs

3D lookup tables (3D LUTs) are used to map one color space to another. They can be used to adjust colors, contrast, and/or saturation, so that you can correct contrast, fix a camera’s inability to see a particular color shade, or give a final finished look or a particular style to your image.

After uploading a .3dl file to your account as a raw file, you can apply it to any image using the lut property of the layer parameter ( l_lut: in URLs), followed by the LUT file name (including the .3dl extension).

Below you can see the laydybug_top.jpg image file in its original color, compared to the video with different LUT files applied. Below these is the code for applying one of the LUTs.

Original Original image with iwltbap_sedona LUT with 'iwltbap_sedona' LUT image with iwltbap_aspen LUT with 'iwltbap_aspen' LUT

Ruby:
Copy to clipboard
cl_image_tag("ladybug_top.jpg", :overlay=>"lut:iwltbap_aspen.3dl")
PHP v1:
Copy to clipboard
cl_image_tag("ladybug_top.jpg", array("overlay"=>"lut:iwltbap_aspen.3dl"))
PHP v2:
Copy to clipboard
(new ImageTag('ladybug_top.jpg'))
  ->adjust(Adjust::by3dLut('iwltbap_aspen.3dl'));
Python:
Copy to clipboard
CloudinaryImage("ladybug_top.jpg").image(overlay="lut:iwltbap_aspen.3dl")
Node.js:
Copy to clipboard
cloudinary.image("ladybug_top.jpg", {overlay: "lut:iwltbap_aspen.3dl"})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().overlay(new Layer().publicId("lut:iwltbap_aspen.3dl"))).imageTag("ladybug_top.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('ladybug_top.jpg', {overlay: new cloudinary.Layer().publicId("lut:iwltbap_aspen.3dl")}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("ladybug_top.jpg", {overlay: new cloudinary.Layer().publicId("lut:iwltbap_aspen.3dl")})
React:
Copy to clipboard
<Image publicId="ladybug_top.jpg" >
  <Transformation overlay="lut:iwltbap_aspen.3dl" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="ladybug_top.jpg" >
  <cld-transformation :overlay="lut:iwltbap_aspen.3dl" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="ladybug_top.jpg" >
  <cl-transformation overlay="lut:iwltbap_aspen.3dl">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new Layer().PublicId("lut:iwltbap_aspen.3dl"))).BuildImageTag("ladybug_top.jpg")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setOverlay("lut:iwltbap_aspen.3dl")).generate("ladybug_top.jpg")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().overlay(new Layer().publicId("lut:iwltbap_aspen.3dl"))).generate("ladybug_top.jpg");
Kotlin:
Copy to clipboard
cloudinary.image {
publicId("ladybug_top.jpg")
adjust(Adjust.by3dLut("iwltbap_aspen.3dl"))}.generate()

See full syntax: l_lut in the Transformation Reference.

Displacement maps

You can displace pixels in a source image based on the intensity of pixels in a displacement map image using the e_displace effect in conjunction with a displacement map image specified as an overlay. This can be useful to create interesting effects in a select area of an image or to warp the entire image to fit a needed design or texture. For example, to make an image wrap around a coffee cup or appear to be printed on a textured canvas.

The displace effect (e_displace in URLs) algorithm displaces the pixels in an image according to the color channels of the pixels in another specified image (a gradient map specified with the overlay parameter). The red channel controls horizontal displacement, green controls vertical displacement, and the blue channel is ignored. The final displacement of each pixel in the base image is determined by a combination of the red and green color channels, together with the configured x and/or y parameters. For example, for a given x value of 20 and a pixel with a red value of 255 (highest), the corresponding base image pixel would be displaced by 20 pixels horizontally, while a red value of 25 (10%) would only displace the base image pixel by 2 pixels horizontally.

This is a standard displacement map algorithm used by popular image editing tools, so you can upload existing displacement maps found on the internet or created by your graphic artists to your account and specify them as the overlay asset, enabling you to dynamically apply the displacement effect on other images in your account or those uploaded by your end users.

Several sample use-case of this layer-based effect are shown in the sections below.

See full syntax: e_displace in the Transformation Reference.

Use case: Warp an image to fit a 3-dimensional product

Use a displacement map to warp the perspective of an overlay image for final placement as an overlay on a mug

displacement map for image overlay

Ruby:
Copy to clipboard
cl_image_tag("sample", :overlay=>"radialize", :effect=>"displace", :x=>50, :y=>50, :use_root_path=>true)
PHP v1:
Copy to clipboard
cl_image_tag("sample", array("overlay"=>"radialize", "effect"=>"displace", "x"=>50, "y"=>50, "use_root_path"=>true))
PHP v2:
Copy to clipboard
# This code example is not currently available.
Python:
Copy to clipboard
CloudinaryImage("sample").image(overlay="radialize", effect="displace", x=50, y=50, use_root_path=True)
Node.js:
Copy to clipboard
cloudinary.image("sample", {overlay: "radialize", effect: "displace", x: 50, y: 50, use_root_path: true})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().overlay(new Layer().publicId("radialize")).effect("displace").x(50).y(50)).useRootPath(true).imageTag("sample");
JS:
Copy to clipboard
cloudinary.imageTag('sample', {overlay: new cloudinary.Layer().publicId("radialize"), effect: "displace", x: 50, y: 50, useRootPath: true}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("sample", {overlay: new cloudinary.Layer().publicId("radialize"), effect: "displace", x: 50, y: 50, use_root_path: true})
React:
Copy to clipboard
<Image publicId="sample" useRootPath="true">
  <Transformation overlay="radialize" effect="displace" x="50" y="50" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="sample" useRootPath="true">
  <cld-transformation :overlay="radialize" effect="displace" x="50" y="50" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="sample" use-root-path="true">
  <cl-transformation overlay="radialize" effect="displace" x="50" y="50">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new Layer().PublicId("radialize")).Effect("displace").X(50).Y(50)).UseRootPath(true).BuildImageTag("sample")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setUseRootPath( true).setTransformation(CLDTransformation().setOverlay("radialize").setEffect("displace").setX(50).setY(50)).generate("sample")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().overlay(new Layer().publicId("radialize")).effect("displace").x(50).y(50)).useRootPath(true).generate("sample");
Kotlin:
Copy to clipboard
// This code example is not currently available.

Using this overlay transformation for placement on a mug:

Zoom displacement map

Ruby:
Copy to clipboard
cl_image_tag("left_mug", :use_root_path=>true, :transformation=>[
  {:width=>500, :crop=>"scale"},
  {:overlay=>"sample.png", :width=>250, :height=>250, :crop=>"pad"},
  {:overlay=>"radialize"},
  {:flags=>"layer_apply", :effect=>"displace", :y=>-8},
  {:flags=>"layer_apply", :x=>10, :background=>"transparent"}
  ])
PHP v1:
Copy to clipboard
cl_image_tag("left_mug", array("use_root_path"=>true, "transformation"=>array(
  array("width"=>500, "crop"=>"scale"),
  array("overlay"=>"sample.png", "width"=>250, "height"=>250, "crop"=>"pad"),
  array("overlay"=>"radialize"),
  array("flags"=>"layer_apply", "effect"=>"displace", "y"=>-8),
  array("flags"=>"layer_apply", "x"=>10, "background"=>"transparent")
  )))
PHP v2:
Copy to clipboard
# This code example is not currently available.
Python:
Copy to clipboard
CloudinaryImage("left_mug").image(use_root_path=True, transformation=[
  {'width': 500, 'crop': "scale"},
  {'overlay': "sample.png", 'width': 250, 'height': 250, 'crop': "pad"},
  {'overlay': "radialize"},
  {'flags': "layer_apply", 'effect': "displace", 'y': -8},
  {'flags': "layer_apply", 'x': 10, 'background': "transparent"}
  ])
Node.js:
Copy to clipboard
cloudinary.image("left_mug", {use_root_path: true, transformation: [
  {width: 500, crop: "scale"},
  {overlay: "sample.png", width: 250, height: 250, crop: "pad"},
  {overlay: "radialize"},
  {flags: "layer_apply", effect: "displace", y: -8},
  {flags: "layer_apply", x: 10, background: "transparent"}
  ]})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation()
  .width(500).crop("scale").chain()
  .overlay(new Layer().publicId("sample.png")).width(250).height(250).crop("pad").chain()
  .overlay(new Layer().publicId("radialize")).chain()
  .flags("layer_apply").effect("displace").y(-8).chain()
  .flags("layer_apply").x(10).background("transparent")).useRootPath(true).imageTag("left_mug");
JS:
Copy to clipboard
cloudinary.imageTag('left_mug', {useRootPath: true, transformation: [
  {width: 500, crop: "scale"},
  {overlay: new cloudinary.Layer().publicId("sample.png"), width: 250, height: 250, crop: "pad"},
  {overlay: new cloudinary.Layer().publicId("radialize")},
  {flags: "layer_apply", effect: "displace", y: -8},
  {flags: "layer_apply", x: 10, background: "transparent"}
  ]}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("left_mug", {use_root_path: true, transformation: [
  {width: 500, crop: "scale"},
  {overlay: new cloudinary.Layer().publicId("sample.png"), width: 250, height: 250, crop: "pad"},
  {overlay: new cloudinary.Layer().publicId("radialize")},
  {flags: "layer_apply", effect: "displace", y: -8},
  {flags: "layer_apply", x: 10, background: "transparent"}
  ]})
React:
Copy to clipboard
<Image publicId="left_mug" useRootPath="true">
  <Transformation width="500" crop="scale" />
  <Transformation overlay="sample.png" width="250" height="250" crop="pad" />
  <Transformation overlay="radialize" />
  <Transformation flags="layer_apply" effect="displace" y="-8" />
  <Transformation flags="layer_apply" x="10" background="transparent" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="left_mug" useRootPath="true">
  <cld-transformation width="500" crop="scale" />
  <cld-transformation :overlay="sample.png" width="250" height="250" crop="pad" />
  <cld-transformation :overlay="radialize" />
  <cld-transformation flags="layer_apply" effect="displace" y="-8" />
  <cld-transformation flags="layer_apply" x="10" background="transparent" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="left_mug" use-root-path="true">
  <cl-transformation width="500" crop="scale">
  </cl-transformation>
  <cl-transformation overlay="sample.png" width="250" height="250" crop="pad">
  </cl-transformation>
  <cl-transformation overlay="radialize">
  </cl-transformation>
  <cl-transformation flags="layer_apply" effect="displace" y="-8">
  </cl-transformation>
  <cl-transformation flags="layer_apply" x="10" background="transparent">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(500).Crop("scale").Chain()
  .Overlay(new Layer().PublicId("sample.png")).Width(250).Height(250).Crop("pad").Chain()
  .Overlay(new Layer().PublicId("radialize")).Chain()
  .Flags("layer_apply").Effect("displace").Y(-8).Chain()
  .Flags("layer_apply").X(10).Background("transparent")).UseRootPath(true).BuildImageTag("left_mug")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setUseRootPath( true).setTransformation(CLDTransformation()
  .setWidth(500).setCrop("scale").chain()
  .setOverlay("sample.png").setWidth(250).setHeight(250).setCrop("pad").chain()
  .setOverlay("radialize").chain()
  .setFlags("layer_apply").setEffect("displace").setY(-8).chain()
  .setFlags("layer_apply").setX(10).setBackground("transparent")).generate("left_mug")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation()
  .width(500).crop("scale").chain()
  .overlay(new Layer().publicId("sample.png")).width(250).height(250).crop("pad").chain()
  .overlay(new Layer().publicId("radialize")).chain()
  .flags("layer_apply").effect("displace").y(-8).chain()
  .flags("layer_apply").x(10).background("transparent")).useRootPath(true).generate("left_mug");
Kotlin:
Copy to clipboard
// This code example is not currently available.

Use case: Create a zoom effect

To displace the sample image by using a displacement map, creating a zoom effect:

displacement map for a zoom effect
Ruby:
Copy to clipboard
cl_image_tag("sample", :overlay=>"docs:zoom_map", :effect=>"displace", :x=>50, :y=>50, :use_root_path=>true)
PHP v1:
Copy to clipboard
cl_image_tag("sample", array("overlay"=>"docs:zoom_map", "effect"=>"displace", "x"=>50, "y"=>50, "use_root_path"=>true))
PHP v2:
Copy to clipboard
# This code example is not currently available.
Python:
Copy to clipboard
CloudinaryImage("sample").image(overlay="docs:zoom_map", effect="displace", x=50, y=50, use_root_path=True)
Node.js:
Copy to clipboard
cloudinary.image("sample", {overlay: "docs:zoom_map", effect: "displace", x: 50, y: 50, use_root_path: true})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation().overlay(new Layer().publicId("docs:zoom_map")).effect("displace").x(50).y(50)).useRootPath(true).imageTag("sample");
JS:
Copy to clipboard
cloudinary.imageTag('sample', {overlay: new cloudinary.Layer().publicId("docs:zoom_map"), effect: "displace", x: 50, y: 50, useRootPath: true}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("sample", {overlay: new cloudinary.Layer().publicId("docs:zoom_map"), effect: "displace", x: 50, y: 50, use_root_path: true})
React:
Copy to clipboard
<Image publicId="sample" useRootPath="true">
  <Transformation overlay="docs:zoom_map" effect="displace" x="50" y="50" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="sample" useRootPath="true">
  <cld-transformation :overlay="docs:zoom_map" effect="displace" x="50" y="50" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="sample" use-root-path="true">
  <cl-transformation overlay="docs:zoom_map" effect="displace" x="50" y="50">
  </cl-transformation>
</cl-image>
.NET:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay(new Layer().PublicId("docs:zoom_map")).Effect("displace").X(50).Y(50)).UseRootPath(true).BuildImageTag("sample")
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setUseRootPath( true).setTransformation(CLDTransformation().setOverlay("docs:zoom_map").setEffect("displace").setX(50).setY(50)).generate("sample")!, cloudinary: cloudinary)
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().overlay(new Layer().publicId("docs:zoom_map")).effect("displace").x(50).y(50)).useRootPath(true).generate("sample");
Kotlin:
Copy to clipboard
// This code example is not currently available.

You could take this a step further by applying this displacement along with another overlay component that adds a magnifying glass. In this example, the same displacement map as above is used on a different base image and offset to a different location.

Ruby:
Copy to clipboard
cl_image_tag("woman.jpg", :use_root_path=>true, :transformation=>[
  {:width=>500, :height=>500, :crop=>"fill"},
  {:overlay=>"woman", :width=>500, :height=>500, :crop=>"fill"},
  {:width=>200, :height=>200, :x=>20, :y=>20, :crop=>"crop"},
  {:width=>200, :height=>200, :overlay=>"docs:zoom_map", :crop=>"fill"},
  {:flags=>"layer_apply", :effect=>"displace", :x=>20, :y=>20},
  {:flags=>"layer_apply", :gravity=>"north_west", :x=>20, :y=>20},
  {:overlay=>"mag-glass.png", :width=>330, :height=>215, :gravity=>"north_west", :x=>38, :y=>38, :flags=>"no_overflow"}
  ])
PHP v1:
Copy to clipboard
cl_image_tag("woman.jpg", array("use_root_path"=>true, "transformation"=>array(
  array("width"=>500, "height"=>500, "crop"=>"fill"),
  array("overlay"=>"woman", "width"=>500, "height"=>500, "crop"=>"fill"),
  array("width"=>200, "height"=>200, "x"=>20, "y"=>20, "crop"=>"crop"),
  array("width"=>200, "height"=>200, "overlay"=>"docs:zoom_map", "crop"=>"fill"),
  array("flags"=>"layer_apply", "effect"=>"displace", "x"=>20, "y"=>20),
  array("flags"=>"layer_apply", "gravity"=>"north_west", "x"=>20, "y"=>20),
  array("overlay"=>"mag-glass.png", "width"=>330, "height"=>215, "gravity"=>"north_west", "x"=>38, "y"=>38, "flags"=>"no_overflow")
  )))
PHP v2:
Copy to clipboard
# This code example is not currently available.
Python:
Copy to clipboard
CloudinaryImage("woman.jpg").image(use_root_path=True, transformation=[
  {'width': 500, 'height': 500, 'crop': "fill"},
  {'overlay': "woman", 'width': 500, 'height': 500, 'crop': "fill"},
  {'width': 200, 'height': 200, 'x': 20, 'y': 20, 'crop': "crop"},
  {'width': 200, 'height': 200, 'overlay': "docs:zoom_map", 'crop': "fill"},
  {'flags': "layer_apply", 'effect': "displace", 'x': 20, 'y': 20},
  {'flags': "layer_apply", 'gravity': "north_west", 'x': 20, 'y': 20},
  {'overlay': "mag-glass.png", 'width': 330, 'height': 215, 'gravity': "north_west", 'x': 38, 'y': 38, 'flags': "no_overflow"}
  ])
Node.js:
Copy to clipboard
cloudinary.image("woman.jpg", {use_root_path: true, transformation: [
  {width: 500, height: 500, crop: "fill"},
  {overlay: "woman", width: 500, height: 500, crop: "fill"},
  {width: 200, height: 200, x: 20, y: 20, crop: "crop"},
  {width: 200, height: 200, overlay: "docs:zoom_map", crop: "fill"},
  {flags: "layer_apply", effect: "displace", x: 20, y: 20},
  {flags: "layer_apply", gravity: "north_west", x: 20, y: 20},
  {overlay: "mag-glass.png", width: 330, height: 215, gravity: "north_west", x: 38, y: 38, flags: "no_overflow"}
  ]})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation()
  .width(500).height(500).crop("fill").chain()
  .overlay(new Layer().publicId("woman")).width(500).height(500).crop("fill").chain()
  .width(200).height(200).x(20).y(20).crop("crop").chain()
  .width(200).height(200).overlay(new Layer().publicId("docs:zoom_map")).crop("fill").chain()
  .flags("layer_apply").effect("displace").x(20).y(20).chain()
  .flags("layer_apply").gravity("north_west").x(20).y(20).chain()
  .overlay(new Layer().publicId("mag-glass.png")).width(330).height(215).gravity("north_west").x(38).y(38).flags("no_overflow")).useRootPath(true).imageTag("woman.jpg");
JS:
Copy to clipboard
cloudinary.imageTag('woman.jpg', {useRootPath: true, transformation: [
  {width: 500, height: 500, crop: "fill"},
  {overlay: new cloudinary.Layer().publicId("woman"), width: 500, height: 500, crop: "fill"},
  {width: 200, height: 200, x: 20, y: 20, crop: "crop"},
  {width: 200, height: 200, overlay: new cloudinary.Layer().publicId("docs:zoom_map"), crop: "fill"},
  {flags: "layer_apply", effect: "displace", x: 20, y: 20},
  {flags: "layer_apply", gravity: "north_west", x: 20, y: 20},
  {overlay: new cloudinary.Layer().publicId("mag-glass.png"), width: 330, height: 215, gravity: "north_west", x: 38, y: 38, flags: "no_overflow"}
  ]}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("woman.jpg", {use_root_path: true, transformation: [
  {width: 500, height: 500, crop: "fill"},
  {overlay: new cloudinary.Layer().publicId("woman"), width: 500, height: 500, crop: "fill"},
  {width: 200, height: 200, x: 20, y: 20, crop: "crop"},
  {width: 200, height: 200, overlay: new cloudinary.Layer().publicId("docs:zoom_map"), crop: "fill"},
  {flags: "layer_apply", effect: "displace", x: 20, y: 20},
  {flags: "layer_apply", gravity: "north_west", x: 20, y: 20},
  {overlay: new cloudinary.Layer().publicId("mag-glass.png"), width: 330, height: 215, gravity: "north_west", x: 38, y: 38, flags: "no_overflow"}
  ]})
React:
Copy to clipboard
<Image publicId="woman.jpg" useRootPath="true">
  <Transformation width="500" height="500" crop="fill" />
  <Transformation overlay="woman" width="500" height="500" crop="fill" />
  <Transformation width="200" height="200" x="20" y="20" crop="crop" />
  <Transformation width="200" height="200" overlay="docs:zoom_map" crop="fill" />
  <Transformation flags="layer_apply" effect="displace" x="20" y="20"