Skip to main content

Image Resizing

Image Resizing is enabled for all Accelerated Domains currently, but will when publicly launched be a paid add-on to Accelerated Domains.

You can resize, adjust quality, and convert images to WebP or AVIF format on demand. We’ll automatically cache every derived image at the edge, so you only need to store one original image at your origin.

Image Resizing in Accelerated Domains is done at the edge in the current version, and returns a 301 redirect to the specified origin if any error occurs. The 301 redirect also includes a x-acd-status header if error occurs, with a status code to help debugging. The settings is set in the URL through query strings.

URL structure#

The Image Resizing / Optimization parameters are set in query strings, and the path to the image source is in the path after a version string.

https://[hostname running ACD]/acd-cgi/img/[version (v1 currently)]/[path to image on origin]?[resizing params]

Example#

https://audunhus.com/acd-cgi/img/v1/wp-content/uploads/2021/01/pexels-flo-maderebner-869258.jpg?width=200&rotate=180

Allowed options#

width#

Maximum width in image pixels. The value must be an integer.

If width is not set and fit is not set we fallback to default max-width per device to optimize performance and not send larger images than necessary.

height#

Maximum height in image pixels. The value must be an integer.

dpr#

Device Pixel Ratio. Default 1. Multiplier for width/height that makes it easier to specify higher-DPI sizes in <img srcset>.

fit#

Resizing mode as a string. It affects interpretation of width and height:

scale-down#

Similar to contain, but the image is never enlarged. If the image is larger than given width or height, it will be resized. Otherwise its original size will be kept. This is default behaviour.

contain#

Resizes to the maximum size that fits within the given width and height. If only a single dimension is given (e.g. only width), the image will be shrunk or enlarged to exactly match that dimension. Aspect ratio is always preserved.

cover#

Resizes (shrinks or enlarges) to fill the entire area of width and height. If the image has an aspect ratio different from the ratio of width and height, it will be cropped to fit.

crop#

The image will shrunk and cropped to fit within the area specified by width and height. The image won’t be enlarged. For images smaller than the given dimensions it’s the same as scale-down. For images larger than the given dimensions, it’s the same as cover. See also trim.

gravity#

When cropping with fit: "cover" and fit: "crop", this defines the side or point that should be left uncropped.

There are three ways of specifying gravity:

A string "left", "right", "top", "bottom" or "center" (the default). {fit: "cover", gravity: "top"} will crop bottom or left and right sides as necessary, but won’t crop anything from the top.

"auto", which selects focal point based on saliency detection (using maximum symmetric surround algorithm),

An object {x, y} containing focal point coordinates in the original image expressed as fractions ranging from 0.0 (top or left) to 1.0 (bottom or right), 0.5 being the center. {fit: "cover", gravity: {x:0.5, y:0.2}} will crop each side to preserve as much as possible around a point at 20% of the height of the source image.

trim#

An object with four properties {left, top, right, bottom} that specify a number of pixels to cut off on each side. Allows removal of borders or cutting out a specific fragment of an image. Trimming is performed before resizing or rotation. Takes dpr into account.

quality#

Quality setting from 1-100 (useful values are in 60-90 range). Lower values make images look worse, but load faster. The default is 85. Quality 100 will generate very large image files, and is not recommended.

In case of PNG images, an explicit quality setting enables use of 8-bit (palette) variant of the format, using pngquant's quality scale. Images that can't meet the requested quality with 256 colors will fall back to 24-bit PNG format or JPEG if they're opaque.

format#

Output format to generate. It can be:

avif — generate images in AVIF format.

webp — generate images in Google WebP format. Set quality to 100 to get the WebP-lossless format.

json — instead of generating an image, outputs information about the image, in JSON format. The JSON object will contain image size (before and after resizing), source image’s MIME type, file size, etc.

Other supported formats (PNG, JPEG, animated GIF) are used by default if no other format is specified.

To automatically serve WebP or AVIF formats to browsers that support them, check if the Accept header contains image/webp or image/avif, and set the format option accordingly.

anim#

Whether to preserve animation frames from input files (default true). Setting it to false reduces animations to still images. This setting is recommended when enlarging images or processing arbitrary user content, because large GIF animations can weigh tens or even hundreds of megabytes.

background#

Background color to add underneath the image. Applies only to images with transparency (e.g. PNG). Accepts any CSS HEX color (#RRGGBB etc.).

rotate#

Number of degrees (90, 180, 270) to rotate the image by. width and height options refer to axes after rotation.

sharpen#

Strength of sharpening filter to apply to the image. Floating-point number between 0 (no sharpening, default) and 10 (max). 1.0 is a recommended value for downscaled images.

Hotlink protection#

Accelerated Domains Image Resize has hotlink protection which blocks requests originating from other websites than the website containing the image.