We've been making changes to how we organize and display our docs. Our work isn't done but we'd love your feedback.
Getting started
Basics
Domains & Origins
Performance

Configuration
Basics
Conditions
Dictionaries
Domains & Origins
Request settings
Cache settings
Headers
Responses
Performance
Custom VCL
Image optimization
Video

Security
Access Control Lists
Monitoring and testing
Securing communications
TLS
Web Application Firewall

Integrations
Logging endpoints
Non-Fastly services

Diagnostics
Streaming logs
Debugging techniques
Common errors

Account info
Account management
Billing
User access and control

Reference

    Serving images

      Last updated March 08, 2019

    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.

    Example transformation

    Resize an image to 200px wide.

    <img src="https://www.fastly.io/image.jpg?width=200"/>

    Transformation order

    Although the URL API parameters can be specified in any order, we normalize the transformation sequence within our system to the following order:

    1. trim
    2. crop
    3. orientation
    4. width height dpr fit resize-filter disable
    5. pad canvas bg-color
    6. overlay
    7. brightness contrast saturation
    8. sharpen
    9. blur
    10. format quality

    Supported input and output image formats

    The source image can be any of the following image formats:

    GIF, PNG, JPEG, WEBP

    The optimized output image can be any of the following image formats:

    GIF, PNG, JPEG, WEBP

    Input and output limits

    Default quality level

    If no quality parameter is present for jpg, pjpg, or 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

    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.

    Debugging

    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

    The 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 (i.e., ifsz=3076875 idim=4000x3000 ifmt=png ofsz=83179 odim=893x670 ofmt=jpeg). The following table defines each key:

    Key Description
    ifsz Input image file size
    idim Input image dimensions
    ifmt Input image format
    ofsz Output image file size
    odim Output image dimensions
    ofmt Output image format

    fastly-io-warning

    The 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

    The fastly-io-error header is added to the following error scenarios:

    This article describes a product that may use third-party cloud infrastructure to process or store content or requests for content. For more information, see our cloud infrastructure security and compliance program.
    Back to Top

    Additional resources: