1. Home
2. Reference documentation
3. Image Optimizer

Specifies the desired output encoding for the image.

The format parameter enables the source image to be converted (a.k.a., "transcoded") from one encoded format to another. This is useful when the source image has been saved in a sub-optimal file format that hinders performance.

Syntax

format={value}

Allowed values

Notes

1. The source image can be any of the following image formats: AVIF, HEIC, JPEG, JPEGXL, PNG, GIF, WEBP.
2. JPEG, progressive JPEG, WebP (Lossy), JPEGXL, AVIF, SVG, and PNG8 have a sliding quality scale that supports the quality parameter.
3. GIF and PNG do not have a sliding quality scale. They do not support the quality parameter.
4. A progressive JPEG pjpg is an image created using the JPEG suite of compression algorithms that will "fade in" successive waves of lines until the entire image has completely arrived. For this reason, progressive JPEG images typically appear to load quicker than the Baseline JPEG jpg format.
5. For up to date image format browser support check Caniuse:
   • AVIF
   • JPEGXL
   • WebP
   • SVG
6. Lossless compression is currently supported for WebP and JPEGXL only.
7. GIF to WebP conversion does not support animated GIFs.
8. MP4 conversion is only available for animated GIF source images.
9. Using AVIF and JPEGXL encoding format requires the purchase of Image Optimizer Professional. Contact sales@fastly.com to see if you need to upgrade your account to access these features.

About the auto value

The auto behavior aims to provide the optimal output format based on client capabilities as well as information related to the source image and transform characteristics. In that regard, we may adopt different heuristics to determine the output format for different source images or transforms.

When using format=auto, the image format delivered is always compatible with the current browser regardless of the source image format. This means a JPEGXL source image can safely be used in a browser where JPEGXL is not supported, and the resulting image is always viewable. With other format parameters and with auto=webp and auto=avif, there are some cases where the original format may be used.

• auto intelligently chooses the best format to deliver to the user prioritizing:
  • JPEGXL
  • AVIF
  • WebP
  • Source image format / JPEG
• Setting the quality parameter via query string to a value other than 100 produces a lossy output image. A value of 100 produces lossless output.
• Source image formats that are lossless to begin with (such as gif and png) may preserve lossless output unless the quality parameter is set explicitly via query string.
• For any other source image format, if no quality parameter is set, the default JPEG quality specified in IO default settings is used.
• Allows the use of JPEGXL, AVIF, or WebP as the source image format in cases where that image format is not support in the viewing environment.
• Quality mapping uses an SSIM similarity score between formats.
• Takes precedence if combined with the auto parameter.

About the svg value

When using SVG there are several size and output constraints to be aware of.

• Output is automatically Gzipped or Brotli compressed based on the value of the Accept-Encoding request header.
• SVG output also supports the viewbox parameter, which removes explicit width and height declarations in the output and allows the SVG to scale within its parent HTML container.
• The maximum output size of a single dimension in the output image is 1600px. If the width or height of the image exceeds this, the image is returned in the original format with an attached Fastly-Io-Warning header on the response.
• The maximum output SVG file size is currently limited to 50MB. A 500 error is returned if the SVG exceeds this. If you hit this limit, try setting or reducing the width and height parameters. The SVG itself is still scalable beyond the specified size, but it may help to reduce the detail in the source image in order to reduce the SVG file size. Reducing the quality value may also help.

SVG output approximates edges in the source image to convert it into a scalable vector graphic, allowing you to scale it to any size after rendering without losing quality. However, the initial conversion to SVG is a lossy operation that works best for simple images with basic shapes such as icons and logos.

• SVG output works best with a lossless source image, such as png.
• The quality parameter for SVG adjusts the complexity of the tracing. A higher value results in more shapes and layers as well as better color precision. If the value is too low, you may notice parts of the image or colors disappear.
• When not specified, the quality parameter's value defaults to 80.
• In certain cases, using a lower quality may actually improve text rendering by reducing the number of shapes. This can be useful for correcting SVG output when text rendering appears blurry.

Examples

Click the links to view the transformed image using a demo Fastly IO service.