Last updated September 22, 2020
By adding the transformation URL API query string parameters to your existing image URLs, images can be resized, cropped, rotated, compressed, and transcoded into different image formats for increased performance. Image transformations can be applied programmatically and on-demand, eliminating the need to batch process or maintain multiple copies of an image to support different sizes and characteristics of device viewing your image content.
Resize an image to 200px wide.
Although the URL API parameters can be specified in any order, we normalize the transformation sequence within our system to the following order:
Supported input and output image formats
The source image can be any of the following image formats:
The optimized output image can be any of the following image formats:
Input and output limits
- The maximum input image file size is 50 Megabytes.
- The maximum input image dimensions are 12,000x12,000 pixels.
- The maximum output image dimensions are 8,192x8,192 pixels (8K Ultra HD).
- The maximum number of frames an animated GIF can contain is 1,000.
Default quality level
quality parameter is present for
webp the output image will be returned at the default value set in the Image Optimizer User Interface.
Meta data removal
To optimize your images for delivery, all metadata (for example, EXIF, XMP, or ICC) is removed to reduce file size. If an image contains an ICC profile, the data is applied directly to the image to ensure color output is correct. If the image doesn't contain an ICC profile, a default profile is added.
WebP image support
WebP images can be delivered to supported browsers by adding the
auto=webp parameter or by applying the Auto WebP control in the Image Optimizer user interface.
Image upscaling is disabled by default and discouraged from use because it increases the file size and delivery time of the image to the user with no improvement of visual quality. We recommend handling upscaling on the client-side (e.g., web browser, css, native app) by setting the width and height attributes of the image.
To debug images served from the Image Optimizer, the following HTTP headers will be present in the response, depending on the response's result.
fastly-io-info header is added to every successfully optimized image. The header values can be used to compare the image file's size, dimensions, and format of the origin image against the optimized edge image. The header contains a string made up of 6 key and value pairs (e.g.,
ifsz=3076875 idim=4000x3000 ifmt=png ofsz=83179 odim=893x670 ofmt=jpeg). The following table defines each key:
||Input image file size|
||Input image dimensions|
||Input image format|
||Output image file size|
||Output image dimensions|
||Output image format|
fastly-io-warning header is added when issues with the source image are encountered that are not fatal enough to cause the image to error.
fastly-io-error header is added to the following error scenarios:
- Image exceeds maximum dimensions
- Image could not be parsed
- Not a supported image format
- Unsupported Content-Encoding
- Gzipped body exceeds maximum length
- Gzipped body could not be decoded
- Invalid status
- Response is pass
- Response is not cacheable