Overlay
The overlay
operation allows to layer images one over another.
-/overlay/:uuid/
-/overlay/:uuid/:relative_dimensions/:relative_coordinates/:opacity/
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.
Overlay the source image
-/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_crop/440x440/center/ Step 1. Scale and crop background to size. | ![]() /blur/60/-/gamma/50/ Step 2. Blur and wash out colors. | ![]() /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.