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.
  • :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.

Since % is an escape char in URLs, it can’t be used as-is and should be replaced with either %25 escape sequence or the p char, which is a more readable and concise option.

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

Watermark with transparency
Specifying size and opacity, positioning is omitted.
Overlay, centered, good for logo
Specifying size and position, opacity is omitted.
Overlays with various positions
Adding multiple overlays with varied positions.