Text overlay positioning

Customize text overlay's position by setting the gravity (g in URLs) and the optional offset of the x and y. While the default text positioning ('gravity') is center, you can place your text in any other area of the image (tip: even outside the image's boundaries).

Here's an example of the default center positioning:

Ruby:
cl_image_tag("face_center.jpg", :overlay=>"text:Arial_45_bold:Hello%20World")
PHP:
cl_image_tag("face_center.jpg", array("overlay"=>"text:Arial_45_bold:Hello%20World"))
Python:
CloudinaryImage("face_center.jpg").image(overlay="text:Arial_45_bold:Hello%20World")
Node.js:
cloudinary.image("face_center.jpg", {overlay: "text:Arial_45_bold:Hello%20World"})
Java:
cloudinary.url().transformation(new Transformation().overlay("text:Arial_45_bold:Hello%20World")).imageTag("face_center.jpg")
JS:
cl.imageTag('face_center.jpg', {overlay: "text:Arial_45_bold:Hello%20World"}).toHtml();
jQuery:
$.cloudinary.image("face_center.jpg", {overlay: "text:Arial_45_bold:Hello%20World"})
React:
<Image publicId="face_center.jpg" >
  <Transformation overlay="text:Arial_45_bold:Hello%20World" />
</Image>
Angular:
<cl-image public-id="face_center.jpg" >
  <cl-transformation overlay="text:Arial_45_bold:Hello%20World">
  </cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay("text:Arial_45_bold:Hello%20World")).BuildImageTag("face_center.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().overlay("text:Arial_45_bold:Hello%20World")).generate("face_center.jpg")
Default - center

Use the gravity parameter (g in URLs) to place your text in different areas of the image, for example - south:

Ruby:
cl_image_tag("face_center.jpg", :overlay=>"text:Arial_45_bold:Hello%20World", :gravity=>"south")
PHP:
cl_image_tag("face_center.jpg", array("overlay"=>"text:Arial_45_bold:Hello%20World", "gravity"=>"south"))
Python:
CloudinaryImage("face_center.jpg").image(overlay="text:Arial_45_bold:Hello%20World", gravity="south")
Node.js:
cloudinary.image("face_center.jpg", {overlay: "text:Arial_45_bold:Hello%20World", gravity: "south"})
Java:
cloudinary.url().transformation(new Transformation().overlay("text:Arial_45_bold:Hello%20World").gravity("south")).imageTag("face_center.jpg")
JS:
cl.imageTag('face_center.jpg', {overlay: "text:Arial_45_bold:Hello%20World", gravity: "south"}).toHtml();
jQuery:
$.cloudinary.image("face_center.jpg", {overlay: "text:Arial_45_bold:Hello%20World", gravity: "south"})
React:
<Image publicId="face_center.jpg" >
  <Transformation overlay="text:Arial_45_bold:Hello%20World" gravity="south" />
</Image>
Angular:
<cl-image public-id="face_center.jpg" >
  <cl-transformation overlay="text:Arial_45_bold:Hello%20World" gravity="south">
  </cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay("text:Arial_45_bold:Hello%20World").Gravity("south")).BuildImageTag("face_center.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().overlay("text:Arial_45_bold:Hello%20World").gravity("south")).generate("face_center.jpg")
South gravity

In addition, you can add the x and y parameters for even more accurate positioning. Here's an example of changing the text's location to the north-west corner, with a 20 pixels offset (for both 'x' and 'y'):

Ruby:
cl_image_tag("face_center.jpg", :overlay=>"text:Arial_45_bold:Hello%20World", :gravity=>"north_west", :x=>20, :y=>20)
PHP:
cl_image_tag("face_center.jpg", array("overlay"=>"text:Arial_45_bold:Hello%20World", "gravity"=>"north_west", "x"=>20, "y"=>20))
Python:
CloudinaryImage("face_center.jpg").image(overlay="text:Arial_45_bold:Hello%20World", gravity="north_west", x=20, y=20)
Node.js:
cloudinary.image("face_center.jpg", {overlay: "text:Arial_45_bold:Hello%20World", gravity: "north_west", x: 20, y: 20})
Java:
cloudinary.url().transformation(new Transformation().overlay("text:Arial_45_bold:Hello%20World").gravity("north_west").x(20).y(20)).imageTag("face_center.jpg")
JS:
cl.imageTag('face_center.jpg', {overlay: "text:Arial_45_bold:Hello%20World", gravity: "north_west", x: 20, y: 20}).toHtml();
jQuery:
$.cloudinary.image("face_center.jpg", {overlay: "text:Arial_45_bold:Hello%20World", gravity: "north_west", x: 20, y: 20})
React:
<Image publicId="face_center.jpg" >
  <Transformation overlay="text:Arial_45_bold:Hello%20World" gravity="north_west" x="20" y="20" />
</Image>
Angular:
<cl-image public-id="face_center.jpg" >
  <cl-transformation overlay="text:Arial_45_bold:Hello%20World" gravity="north_west" x="20" y="20">
  </cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay("text:Arial_45_bold:Hello%20World").Gravity("north_west").X(20).Y(20)).BuildImageTag("face_center.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().overlay("text:Arial_45_bold:Hello%20World").gravity("north_west").x(20).y(20)).generate("face_center.jpg")
Custom position

The text overlay can be embedded outside of the image's boundaries. This can be used, for example, for a caption text:

Ruby:
cl_image_tag("face_center.jpg", :overlay=>"text:Arial_45_bold:Hello%20World", :gravity=>"south", :y=>-40)
PHP:
cl_image_tag("face_center.jpg", array("overlay"=>"text:Arial_45_bold:Hello%20World", "gravity"=>"south", "y"=>-40))
Python:
CloudinaryImage("face_center.jpg").image(overlay="text:Arial_45_bold:Hello%20World", gravity="south", y=-40)
Node.js:
cloudinary.image("face_center.jpg", {overlay: "text:Arial_45_bold:Hello%20World", gravity: "south", y: -40})
Java:
cloudinary.url().transformation(new Transformation().overlay("text:Arial_45_bold:Hello%20World").gravity("south").y(-40)).imageTag("face_center.jpg")
JS:
cl.imageTag('face_center.jpg', {overlay: "text:Arial_45_bold:Hello%20World", gravity: "south", y: -40}).toHtml();
jQuery:
$.cloudinary.image("face_center.jpg", {overlay: "text:Arial_45_bold:Hello%20World", gravity: "south", y: -40})
React:
<Image publicId="face_center.jpg" >
  <Transformation overlay="text:Arial_45_bold:Hello%20World" gravity="south" y="-40" />
</Image>
Angular:
<cl-image public-id="face_center.jpg" >
  <cl-transformation overlay="text:Arial_45_bold:Hello%20World" gravity="south" y="-40">
  </cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay("text:Arial_45_bold:Hello%20World").Gravity("south").Y(-40)).BuildImageTag("face_center.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().overlay("text:Arial_45_bold:Hello%20World").gravity("south").y(-40)).generate("face_center.jpg")
Caption text

You can have more advanced features, like positioning the image on the automatically detected face, rotating it, and fitting the text's size to 50% (0.5) of the detected face by setting flags to region_relative (fl_region_relative in URLs) and the required percentage:

Ruby:
cl_image_tag("face_center.jpg", :overlay=>"text:Arial_45_bold:Hello%20World", :gravity=>"face", :angle=>19, :flags=>"region_relative", :width=>0.5)
PHP:
cl_image_tag("face_center.jpg", array("overlay"=>"text:Arial_45_bold:Hello%20World", "gravity"=>"face", "angle"=>19, "flags"=>"region_relative", "width"=>0.5))
Python:
CloudinaryImage("face_center.jpg").image(overlay="text:Arial_45_bold:Hello%20World", gravity="face", angle=19, flags="region_relative", width=0.5)
Node.js:
cloudinary.image("face_center.jpg", {overlay: "text:Arial_45_bold:Hello%20World", gravity: "face", angle: 19, flags: "region_relative", width: "0.5"})
Java:
cloudinary.url().transformation(new Transformation().overlay("text:Arial_45_bold:Hello%20World").gravity("face").angle(19).flags("region_relative").width(0.5)).imageTag("face_center.jpg")
JS:
cl.imageTag('face_center.jpg', {overlay: "text:Arial_45_bold:Hello%20World", gravity: "face", angle: 19, flags: "region_relative", width: "0.5"}).toHtml();
jQuery:
$.cloudinary.image("face_center.jpg", {overlay: "text:Arial_45_bold:Hello%20World", gravity: "face", angle: 19, flags: "region_relative", width: "0.5"})
React:
<Image publicId="face_center.jpg" >
  <Transformation overlay="text:Arial_45_bold:Hello%20World" gravity="face" angle="19" flags="region_relative" width="0.5" />
</Image>
Angular:
<cl-image public-id="face_center.jpg" >
  <cl-transformation overlay="text:Arial_45_bold:Hello%20World" gravity="face" angle="19" flags="region_relative" width="0.5">
  </cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay("text:Arial_45_bold:Hello%20World").Gravity("face").Angle(19).Flags("region_relative").Width(0.5)).BuildImageTag("face_center.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().overlay("text:Arial_45_bold:Hello%20World").gravity("face").angle(19).flags("region_relative").width(0.5)).generate("face_center.jpg")
Text relative to detected face

You can also set the text's dimensions to be relative to the whole image setting flags to region (fl_region in URLs) and the required percentage. For example, resize the image to be 50% in width and 20% in height relative to the base image:

Ruby:
cl_image_tag("face_center.jpg", :overlay=>"text:Arial_45_bold:Hello%20World", :flags=>"relative", :width=>0.5, :height=>0.2)
PHP:
cl_image_tag("face_center.jpg", array("overlay"=>"text:Arial_45_bold:Hello%20World", "flags"=>"relative", "width"=>0.5, "height"=>0.2))
Python:
CloudinaryImage("face_center.jpg").image(overlay="text:Arial_45_bold:Hello%20World", flags="relative", width=0.5, height=0.2)
Node.js:
cloudinary.image("face_center.jpg", {overlay: "text:Arial_45_bold:Hello%20World", flags: "relative", width: "0.5", height: "0.2"})
Java:
cloudinary.url().transformation(new Transformation().overlay("text:Arial_45_bold:Hello%20World").flags("relative").width(0.5).height(0.2)).imageTag("face_center.jpg")
JS:
cl.imageTag('face_center.jpg', {overlay: "text:Arial_45_bold:Hello%20World", flags: "relative", width: "0.5", height: "0.2"}).toHtml();
jQuery:
$.cloudinary.image("face_center.jpg", {overlay: "text:Arial_45_bold:Hello%20World", flags: "relative", width: "0.5", height: "0.2"})
React:
<Image publicId="face_center.jpg" >
  <Transformation overlay="text:Arial_45_bold:Hello%20World" flags="relative" width="0.5" height="0.2" />
</Image>
Angular:
<cl-image public-id="face_center.jpg" >
  <cl-transformation overlay="text:Arial_45_bold:Hello%20World" flags="relative" width="0.5" height="0.2">
  </cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay("text:Arial_45_bold:Hello%20World").Flags("relative").Width(0.5).Height(0.2)).BuildImageTag("face_center.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().overlay("text:Arial_45_bold:Hello%20World").flags("relative").width(0.5).height(0.2)).generate("face_center.jpg")
Text relative to image

See this blog post for more information: Adding watermarks, credits, badges and text overlays to images

by Itay Taragano