About Fastly Image Optimizer

  Last updated March 04, 2021

Fastly's Image Optimizer (Fastly IO) manipulates and transforms your images in real time and caches optimized versions of them. When an image is requested from your origin server, Fastly IO can perform one or more transformation tasks before serving and caching the optimized version. For example, you can resize, adjust quality, crop and trim, serve responsive images, and more.

Before you begin

Contact sales to request access to Fastly IO. Be sure to include the Service ID of the service for which image optimization should be enabled.

Enable shielding for your origins. Services that use image optimization are required to enable shielding. Our guide to enabling shielding provides more information on how to set this up.

When setting up shielding, be sure to choose a shield location as geographically close to your image's origin as possible. Also, take special note of the step immediately following your shielding location selection in that guide. If the Host header for the service has been changed from the default, you must ensure the new hostname is added to the list of domains.

Setting up image optimization

Once we've enabled it for your service, you can set up image optimization by following this process:

  1. Add a header.
  2. Create a request condition.
  3. Test an image.

Add the Fastly Image Optimizer header

Once image optimization has been activated for your service ID and confirmed via email, configure your service by adding the Fastly Image Optimizer header.

  1. Log in to the Fastly web interface.
  2. From the All services page, select the appropriate service. You can use the search box to search by ID, name, or domain.
  3. Click the Edit configuration button and then select the option to clone the active version. The Domains page appears.
  4. Click the Content link. The Content page appears.
  5. Click the Create header button. The Create a header page appears.

    the create header window with the image optimization settings

  6. Fill out the Create a header window as follows:
    • In the Name field, enter Fastly Image Optimizer.
    • From the Type menu, select Request, and from the Action menu, select Set.
    • In the Destination field, enter http.x-fastly-imageopto-api.
    • In the Source field, enter "fastly". By default, the Fastly Image Optimizer removes any additional query string parameters that are not part of our image API. If your source image requires delivery of additional query string parameters from origin then enter "fastly; qp=*" instead.
    • From the Ignore if set menu, select No.
    • In the Priority field, enter 1.
  7. Click Create to create the new header.

Create a request condition

To ensure only your image assets are routed via the Fastly Image Optimizer, create a request condition.

  1. Click the Attach a condition link next to the Fastly Image Optimizer header. The Add a condition window appears.
  2. Click the Create a new request condition button. The Create a new request condition window appears.

    the new request condition window with the image optimization settings

  3. Fill out the Create a new request condition window as follows:
    • In the Name field, type a descriptive name for the new condition (for example, Fastly Image Optimizer Request Condition).
    • In the Apply if field, type the appropriate request condition. For example, req.url.ext ~ "(?i)^(gif|png|jpe?g|webp)$" will send all files with gif, png, jpg, jpeg, and webp extensions via the Fastly Image Optimizer. Likewise, req.url ~ "^/images/" will send all files in the images directory via the Fastly Image Optimizer.
  4. Click the Save and apply to button to create the new condition for the header.

Confirm everything is working

Once you've activated your changes, check to see if the Fastly Image Optimizer is processing your image request by typing the following command on the command line:

echo -n "Image Width: " ; curl -sI https://www.fastly.io/image.jpg?width=200 | grep -i "Fastly-Io-Info:" | cut -d' ' -f6 | cut -d= -f2 | cut -dx -f1

Replace https://www.fastly.io/image.jpg?width=200 with the full image URL and width of the image you're testing.

The command line output will display the image's width, which should match the width API parameter you added to your image. For example, the output might be:

Image Width: 200

Configuring default image settings

The Fastly Image Optimizer supports a variety of image formats and applies specific settings to all images by default. Use the Fastly web interface to review and adjust the default settings as appropriate. Changes to other image settings, including most image transformations, require issuing API calls.

the image optimizer default settings

To review and edit the default image settings via the web interface, follow the steps below:

  1. Log in to the Fastly web interface.
  2. From the All services page, select the appropriate service. You can use the search box to search by ID, name, or domain.
  3. Click the Edit configuration button and then select the option to clone the active version. The Domains page appears.
  4. Click the Image optimization link. The Image Optimizer default settings appear.

    the image optimizer default settings

  5. Click the pencil icon next to the Default settings. The Edit default settings window appears.

    the image optimizer default settings editing window

  6. Adjust the Edit default settings as follows:
    • From the Auto WebP controls, leave the settings at their default or select Yes to convert images to the WebP format in browsers that support it. When you use the default setting, No, Fastly uses the image file type instead.
    • In the Default WebP (lossy) quality field, leave the settings at their default or type the compression level for lossy file-formatted images. Fastly uses 85 for the default quality but you can specify any whole number between 1 and 100.
    • From the Default JPEG format controls, leave the settings at their default or select the JPEG type to use when delivering the image. By default, Fastly sets the JPEG type to Auto to deliver images with the output type matching the input type. You can also select Baseline to display the image line by line starting from top left and going to the bottom right, or Progressive to display a blurry image that becomes clear as it loads.
    • In the Default JPEG quality field, leave the settings at their default or type the compression level for quality of lossy file formats. Fastly uses 85 for the default quality but you can specify any whole number between 1 and 100.
    • From the Allow upscaling controls, leave the settings at their default or select Yes to return images larger than the original source file so they can fit the requested dimensions.
  7. Click the Advanced options link. The Resize filter controls appear.

    the advanced options of the image optimizer default settings editing window

  8. Adjust the Advanced options settings as follows:
    • From the Enable Animated GIF to Video controls, leave the settings at their default or select Yes to enable Animated GIF to video functionality. Each video frame will be counted and charged as an image optimizer request.
    • From the Resize filter controls, select the image quality filter to use when resizing and generating new images to use a higher or lower number of pixels. By default, Fastly uses the Lanczos3 filter. You can also choose Lanczos2, Bicubic, Bilinear, and Nearest.

Using advanced image settings

To go beyond the basic image optimization and transformation settings in the Fastly web interface, you must change your existing image URLs by adding Fastly API query string parameters. For example, if your image source existed at http://www.example.com/image.jpg, you would need to add ?<PARAMETER=VALUE> to the end of the URL to create the proper query string structure for Fastly to transform the image.

Our Fastly Image Optimizer API describes each of the available image transformations in detail and includes the exact API pattern you can add to URLs, along with a description and example of how to use each parameter and its values. These examples perform transformations and optimizations on our www.fastly.io/image.jpg URL so you can see exactly how they work before you change your image URLs. Additionally, it provides details you should know before you start adding Fastly image transformation URL API query string parameters to your existing image URLs.

Debugging

Running into problems? See our details on image optimization debugging for more information.

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