Image, text, and color overlays

Image and text overlays can be useful for customizing images on a website in various ways. For example, image overlays can be used to add branding elements like logos or watermarks to images. Text overlays can be used to add titles, descriptions, and labels to images, for instance, for page metadata.

Combined with other operations such as resize, crop, and blur, image and text overlays can help create various custom images that can be used on a website. Furthermore, you can "bake in" the applied changes and create a new file that can no longer be reverted to its original state.

Image overlay

-/overlay/:uuid/
-/overlay/:uuid/:relative_dimensions/:relative_coordinates/:opacity/

The overlay operation allows to layer images one over another.

One of the most common use cases here are watermarks: semi-transparent images layered over opaque ones to complicate their unauthorized usage, etc.

  • :uuid — UUID of an image to be layered over input. To be recognized by :uuid, that image should be related to any project of your account.
  • :relative_dimensions — linear dimensions of the overlay image. The aspect ratio of an overlay is preserved. What you set is a maximum linear size along one of the axes: -/overlay/:uuid/50%x50%/ means any linear dimension of the overlay can not exceed 50% in size. Default size setting is 100%.
  • :relative_coordinates — position of the overlay over your input. By default, an overlay is positioned in the top-left corner of an input. Coordinates represent an offset along each of the axes in either pixel or percent format. In general, the coordinate system is similar to the CSS background-position. For example, -/overlay/:uuid/10%,90%/ places overlay in bottom left corner.
  • :opacity — controls the opacity of the overlay in percent format. Your overlay may either be initially semi-transparent or made to be so by tuning :opacity.

In URLs, % is an escape character, it can’t be used as-is. Use a %25 escape sequence or a p shortcut for percent.

Every overlay parameter is optional and can be omitted. However, the order of parameter URL directives should be preserved.

Watermark with transparency
-/overlay/:uuid/50px50p/20p/
Specifying size and opacity, positioning is omitted.		Overlay, centered, good for logo
-/overlay/:uuid/50%x50%/center/
Specifying size and position, opacity is omitted.		Overlays with various positions
Adding multiple overlays with varied positions.

Self overlay

-/overlay/self/
-/overlay/self/:relative_dimensions/:relative_coordinates/:opacity/

To fit an image into a specified placeholder, you can add a stylized background from the same image. It visually extends the image appearance vertically or horizontally.

Scale and crop landscape image to center with a square aspect ratio
-/scale_crop/440x440/center/
Step 1. Scale and crop
background to size.		Blur cropped image and set gamma to dull colors
-/blur/60/-/gamma/50/
Step 2. Blur and wash out colors.		Overlay the original landscape image over its square blurred version to extend the image appearance vertically
-/overlay/self/100px100p/center/
Step 3. Place the original image.

With all steps combined, this operation will look like:

-/scale_crop/440x440/center/-/blur/60/-/gamma/50/-/overlay/self/100px100p/center/

Unlike the standard overlay, -/overlay/self/ doesn't require an image UUID. It helps when you don't have access to UUIDs when using Proxy, and when you do batch image processing.

Text overlay

-/text/:relative_dimensions/:relative_coordinates/:text/

Note: This feature is disabled by default to prevent vandalism. See how to enable it.

The text operation allows placing arbitrary text on top of an image.

  • :relative_dimensions — linear dimensions of area allocated for text placement. These dimensions are used for text alignment, and width affects line wrapping.
  • :relative_coordinates — position of text area. Coordinates represent an offset along each of the axes in either pixel or percent format. In general, the coordinate system is similar to the CSS background-position. For example, -/text/90px10p/10%,90%/... places text in bottom left corner.
  • :text — actual text to be placed. In order to use some characters in text, you need to escape them. Valid escape sequences are: ~s for /, ~n for a new line, and ~~ for ~. Also, do not forget about proper URL escaping. If you need to render "Example text🍷" it would be -/text/100px100p/0,0/Example%20text%F0%9F%8D%B7/ in the url.
Text on background
-/font/50/fff/-/text_box/fill/ff000080/-/text/100px50p/0,100p/:text/
Text with semi-transparent background.		Multiple text lines
-/text_align/left/center/-/font/30/000000/-/text_box/line/ffffff/10/-/text/90px50p/50p,100p/:text/
Multiple text lines.		Text and overlay
-/overlay/:uuid/50px50p/-/font/50/ff0000/-/text_box/fit/ffff00/10/-/text/100px50p/0,100p/:text/
Text with background and overlay.

Extra options

You can control text rendering by the following operations. These operations don't render anything, but affect how subsequent text operations render text.

Text alignment

-/text_align/:halign/:valign/

This operation sets how text is placed within dimensions, specified by :relative_dimensions in text operation.

  • :halign — horizontal alignment. Valid options are left, right, and center.
  • :valign — vertical alignment. Valid options are top, bottom, and center.

Default alignment is center for both axes.

Text in top-left corner of allocated area
-/font/50/-/text_box/fill/00ff0080/-/text_align/left/top/-/text/80px80p/50p,50p/:text/
Text in top-left corner of allocated area		Text in bottom-right corner of allocated area
-/font/50/-/text_box/fill/00ff0080/-/text_align/right/bottom/-/text/80px80p/50p,50p/:text/
Text in bottom-right corner of allocated area		Left-aligned text in allocated area
-/font/50/-/text_box/fill/00ff0080/-/text_align/left/center/-/text/80px80p/50p,50p/:text/
Left-aligned text in allocated area

Font size and color

-/font/:size/:color/

This operation sets font size and color.

  • :size — font size in pixels.
  • :color — font color in hexadecimal notation with optional transparency. Example: 99ff99, 9f9, 99ff9920.

Default size is 10, and color is solid black.

Setting font size
-/font/50/-/text/100px100p/0,0/Test/
Setting font size		Setting font color
-/font/f00/-/text/100px100p/0,0/Test/
Setting font color		Setting font size and color
-/font/50/f00/-/text/100px100p/0,0/Test/
Setting size and font in one operation

Text background box

-/text_box/:mode/:color/:padding/

This operation controls drawing solid color background behind the text.

  • :mode — how background is placed: none — disabled, fit — one rectangle, under actual text, line — separate rectangle under each line, fill — fill all space, allocated by :relative_dimensions in text operation.
  • :color — the background color in hexadecimal notation with optional transparency.
  • :padding — increase background size by specified amount in pixels.

By default, no background is rendered.

Permissions

Contact our sales team to enable this feature for your project.

Text overlay operation permits arbitrary, user provided content. This might be used for vandalism and serving of offensive and misleading messages from customer domain. Therefore, we recommend using it along with signed URLs.

Solid color overlay

-/rect/:color/:relative_dimensions/:relative_coordinates/

The rect operation allows to draw a solid color rectangle on top of an image.

  • :color — color of the rectangle. It can have alpha channel specified for transparency.
  • :relative_dimensions — linear dimensions of the rectangle.
  • :relative_coordinates — position of the rectangle over your input.

Dimensions and coordinates work the same way as for the overlay operation.

Single rectangle
-/rect/000000/50px33p/50p,50p/
Single rectangle		Multiple, semi-transparent
-/rect/ff000080/50px33p/50p,50p/
-/rect/00ff0080/33px50p/50p,50p/
Multiple, semi-transparent