x-fastly-imageopto-montage

The x-fastly-imageopto-montage header adds the ability to combine up to four images into a single image, based on a predefined set of layout templates.

IMPORTANT: If an x-fastly-imageopto-montage header is specified, all other IO parameters and headers are ignored. Also, unlike most IO parameters, montage must be specified using an HTTP header, rather than via the query string of the client request.

Syntax

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

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

Sub-parameters

ParamDescription
widthWidth of the output image as a whole number of pixels.
heightHeight of the output image as a whole number of pixels.
layoutA template (see template layouts below).
imagesA semicolon-separated list of root-relative image URLs.
dprDevice Pixel Ratio. (optional)
paddingAdd additional pixels to the inside edges of an image. (optional)
bg-colorBackground color of the output image, as a 3- or 6-digit hexadecimal RGB value, to use when applying padding. (optional)
formatThe output image format. (optional)
qualityOutput image quality for lossy file formats. (optional)

Template Layouts

2a
12
2b
12
3a
123
3b
123
3c
123
3d
123
4a
1234
4b
1234
4c
1234
4d
1234
4e
1234

Notes

  1. By default, all images will fill the area by cropping from the center of the image.
  2. The maximum number of images currently supported is 4.
  3. An image montage is counted as 1 image optimization request regardless of how many images the montage contains. However, on a cache miss each sub image will count as a non-IO request.

Examples

This VCL:

sub vcl_recv { ... }
Fastly VCL
set req.http.x-fastly-imageopto-montage = "" +
"width=500&height=500&layout=2a&images=/image1.jpg;/image2.jpg";

will result in:

/io-demo/montage/2a

Advanced

This VCL:

sub vcl_recv { ... }
Fastly VCL
set req.http.x-fastly-imageopto-montage = "" +
"width=500&height=500&layout=2b&images=/image1.jpg;/image2.jpg"
"&" if(req.url.qs ~ "(?:^|&)(bg-color=[^&]+)", re.group.1, "")
"&" if(req.url.qs ~ "(?:^|&)(dpr=[^&]+)", re.group.1, "")
"&" if(req.url.qs ~ "(?:^|&)(quality=[^&]+)", re.group.1, "")
"&" if(req.url.qs ~ "(?:^|&)(format=[^&]+)", re.group.1, "")
"&" if(req.url.qs ~ "(?:^|&)(padding=[^&]+)", re.group.1, "")
;

will result in:

/io-demo/montage/2b?padding=10&bg-color=000&format=png

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)