Basics

You can transform images on Cloudflare’s edge platform. You can resize, adjust quality, and convert images to WebP format on demand. We will automatically cache every derived image at the edge, so you only need to store one original image at your origin. This way you can quickly and easily adapt images to your site’s layout and your visitors’ screen sizes without maintaining a server-side image processing pipeline on your servers.

Image processing integrates well with Workers, which enables advanced integrations, such as custom URL schemes, content negotiation and responsive images based on Client Hints.

Getting started

Image Resizing is available today for Business and Enterprise Customers. To enable it, login to the Cloudflare Dashboard and navigate to the Speed Tab. There you’ll find the section for Image Resizing which you can enable with one click.

There are two ways to use image resizing: via pre-defined URL format (described below) or via Workers that handle advanced use-cases.

The default URL format

You can convert and resize images by requesting them via a specially-formatted URL. This way you don’t need to write any code, only change HTML markup of your website to use the new URLs. The format is:

https://zone/cdn-cgi/image/options/source-image

e.g.

<img src="/cdn-cgi/image/width=80,quality=75/uploads/avatar1.jpg">

where:

zone
is your domain name on Cloudflare. Unlike other 3rd party image resizing services, we don’t use a separate domain name for an API. Every Cloudflare zone with image resizing enabled can handle resizing itself. In URLs used on your website this part can be omitted, so that URLs start with /cdn-cgi/image/.
/cdn-cgi/image/
is a fixed prefix that identifies that this is a special path handled by Cloudflare.
options
is a comma-separated list of options such as width, height, and quality.
source-image
is an absolute path on the origin server, or an absolute URL (starting with https:// or http://), pointing to an image to resize. The path is not URL-encoded, so the resizing URL can be safely constructed by concatenating /cdn-cgi/image/options/ and the original image URL, e.g. /cdn-cgi/image/width=100/https://s3.example.com/bucket/image.png.

Options

At least one option must be specified. Options are comma-separated (spaces are not allowed anywhere). Names of options can be specified in full or abbreviated.

width=x or w=x
Specifies maximum width of the image in pixels. Exact behavior depends on the fit mode (described below).
height=x or h=x
Specifies maximum height of the image in pixels. Exact behavior depends on the fit mode (described below).
fit=mode

Affects interpretation of width and height. All resizing modes preserve aspect ratio. Available modes are:

  • fit=scale-down The image will be shrunk in size to fully fit within the given width or height, but won’t be enlarged.

  • fit=contain The image will be resized (shrunk or enlarged) to be as large as possible within the given width or height while preserving the aspect ratio.

  • fit=cover The image will be resized to exactly fill the entire area specified by width and height, and will cropped if necessary.

gravity=side or gravity=XxY or g=XxY

When cropping with fit=cover, specifies the most important side or point in the image that shouldn’t be cropped off. It can be either a side left, right, top, bottom or coordinates specified on a scale from 0.0 (top or left) to 1.0 (bottom or right), 0.5 being the center. The X and Y coordinates are separated by lowercase x, e.g. 0x1 means left and bottom, 0.5x0.5 is the center, 0.5x0.33 is a point in the top third of the image.

quality=x or q=x

Specifies quality for images in JPEG and WebP format. The quality is in 1-100 scale, but useful values are between 50 (low quality, small file size) and 90 (high quality, large file size). 85 is the default. It doesn’t do anything for PNG.

format=auto or f=auto

Allows serving of the WebP format to browsers that support it. If this option is not specified, a standard format like JPEG or PNG will be used.

onerror=redirect

In case of a fatal error that prevents the image from being resized, redirects to the unresized source image URL. This may be useful in case some images require user authentication and cannot be fetched anonymously via worker. This option shouldn’t be used if the source images may be very large.

Supported formats and limitations

The service generates JPEG and PNG images, and optionally WebP.

The service can read JPEG, PNG, GIF and WebP images. It can read GIF animations, but only uses the first frame and converts the GIF to a still image in another format.

The service supports ICC color profiles in JPEG and PNG images.

EXIF metadata is preserved in JPEG images, if the JPEG doesn’t use EXIF rotation feature. Images saved straight from digital cameras may use EXIF rotation. Images from image editing software generally don’t use it. Metadata of WebP images is always discarded.

Ideally, images sizes should match exactly the size they are displayed on the page. If the page contains thumbnails with markup such as <img width="200" …>, then images should be resized to width=200. If the exact size is not known ahead of time, use responsive images technique.

If you can’t use the <img srcset> markup, and have to hardcode specific maximum sizes, we recommend:

  • maximum 1920 pixels for desktop browsers,
  • maximum 960 pixels for tablets,
  • maximum 640 pixels for mobile phones.
/cdn-cgi/image/fit=scale-down,width=1920/your-image.jpg

The fit=scale-down option ensures that the image won’t be enlarged unnecessarily.

You can detect device type using CF-Device-Type header enabled via Page Rule.

Image optimization and interaction with Polish

Polish won’t be applied to URLs using image resizing. Resized images already have lossy compression applied where possible, so they don’t need optimizations provided by Polish.

Caching

Resizing causes the original image to be fetched from the origin server and cached (following the usual rules of HTTP caching, Cache-Control header, etc.). Requests for multiple different image sizes are likely to reuse the cached original image, without causing extra transfers from the origin server.

Resized images follow the same caching rules as the original image they were resized from (i.e. the Cache-Control header is from the original to the resized image). We do not support purging of resized variants individually, but purging of the original image URL will also purge all of its resized variants.