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";