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
% is an escape character, it can’t be used as-is.
%25 escape sequence or a
p shortcut for percent.
overlay parameter is optional and can be omitted. However, the order of
parameter URL directives should be preserved.
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.
Step 1. Scale and crop
background to size.
Step 2. Blur and wash out colors.
Step 3. Place the original image.
With all steps combined, this operation will look like:
text operation allows placing arbitrary text on top of an image.
Note: This feature is disabled by default to prevent vandalism. See how to enable it.
: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:
~nfor a new line, and
~. 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.
You can control text rendering by the following operations. These operations don't render anything,
but affect how subsequent
text operations render text.
This operation sets how text is placed within dimensions, specified by
:halign— horizontal alignment. Valid options are
:valign— vertical alignment. Valid options are
Default alignment is
center for both axes.
This operation sets font size and color.
:size— font size in pixels.
:color— font color in hexadecimal notation with optional transparency. Example:
Default size is 10, and color is solid black.
This operation controls drawing solid color background behind the text.
:mode— how background is placed:
fit— one rectangle, under actual text,
line— separate rectangle under each line,
fill— fill all space, allocated by
: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.
Contact sales 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, it should be used in conjunction with signed URLs.