x-fastly-imageopto-overlay

The x-fastly-imageopto-overlay header overlays one image on top of another image.

IMPORTANT: Unlike most IO parameters, overlays must be specified using an HTTP header, rather than via the query string of the client request.

Syntax

x-fastly-imageopto-overlay: {param-list}

{param-list} is a query string-encoded set of key-value pairs.

Sub-parameters

ParamDescription
overlayRoot-relative URL.
overlay-base64Base64 encoded root-relative URL.
overlay-widthWidth of the overlay image. When specified as a percentage, the width is relative to the output image.
overlay-heightHeight of the overlay image. When specified as a percentage, the height is relative to the output image.
overlay-alignThe position of the overlay relative to the image, in the form {y-align},{x-align}. For {y-align}, choose from top, middle, and bottom. For {x-align}, choose from left, center, and right. Defaults to middle,center.
overlay-padAdd padding to the edges of the overlay. Takes the same form as pad.
overlay-repeatHow the overlay should be repeated. Choose from x, y, or both.

Examples

Align the overlay to the top of the source image:

sub vcl_recv { ... }
Fastly VCL
set req.http.X-fastly-imageopto-overlay = "overlay=/img/overlay.png&overlay-align=top";

Align the overlay to the bottom-right:

sub vcl_recv { ... }
Fastly VCL
set req.http.X-fastly-imageopto-overlay = "overlay=/img/overlay.png&overlay-align=bottom,right";

Resize the overlay to be 75% the height of the output image, and pad it - on the top and bottom edge by 25px, and on the right and left edge by 50px:

sub vcl_recv { ... }
Fastly VCL
set req.http.X-fastly-imageopto-overlay = "overlay=/img/overlay.png&overlay-height=0.75&overlay-pad=25,50";

Tile an overlay across the source image:

sub vcl_recv { ... }
Fastly VCL
set req.http.X-fastly-imageopto-overlay = "overlay=/img/overlay.png&overlay-repeat=both";

User contributed notes

BETA

Do you see an error in this page? Do you have an interesting use case, example or edge case people should know about? Share your knowledge and help people who are reading this page! (Comments are moderated; for support, please contact Fastly support)