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
Here’s a breakdown of each part of the URL:
zone
- 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/
.
- 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/
- A fixed prefix that identifies that this is a special path handled by Cloudflare.
options
- A comma-separated list of options such as
width
,height
, andquality
.
- A comma-separated list of options such as
source-image
- An absolute path on the origin server, or an absolute URL (starting with
https://
orhttp://
), 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
.
- An absolute path on the origin server, or an absolute URL (starting with
Here’s an example of a URL with options
set to width=80,quality=75
and a source-image
of uploads/avatar1.jpg
.
<img src="/cdn-cgi/image/width=80,quality=75/uploads/avatar1.jpg">
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
orw=x
- Specifies maximum width of the image in pixels. Exact behavior depends on the
fit
mode (described below).
- Specifies maximum width of the image in pixels. Exact behavior depends on the
height=x
orh=x
- Specifies maximum height of the image in pixels. Exact behavior depends on the
fit
mode (described below).
- Specifies maximum height of the image in pixels. Exact behavior depends on the
dpr=x
- Device Pixel Ratio. Default
1
. Multiplier forwidth
/height
that makes it easier to specify higher-DPI sizes in<img srcset>
.
- Device Pixel Ratio. Default
fit
Affects interpretation of
width
andheight
. All resizing modes preserve aspect ratio. Available modes are:fit=scale-down
- Image will be shrunk in size to fully fit within the given
width
orheight
, but won’t be enlarged.
- Image will be shrunk in size to fully fit within the given
fit=contain
- Image will be resized (shrunk or enlarged) to be as large as possible within the given
width
orheight
while preserving the aspect ratio.
- Image will be resized (shrunk or enlarged) to be as large as possible within the given
fit=cover
- Image will be resized to exactly fill the entire area specified by
width
andheight
, and will cropped if necessary.
- Image will be resized to exactly fill the entire area specified by
fit=crop
- Image will be shrunk and cropped to fit within the area specified by
width
andheight
. The image won’t be enlarged. For images smaller than the given dimensions it’s the same asscale-down
. For images larger than the given dimensions, it’s the same ascover
.
- Image will be shrunk and cropped to fit within the area specified by
fit=pad
- Image will be resized (shrunk or enlarged) to be as large as possible within the given
width
orheight
while preserving the aspect ratio, and the extra area will be filled with abackground
color (white by default). Transparent background may be very expensive, and it’s better to usefit=contain
and CSSobject-fit: contain
property instead.
- Image will be resized (shrunk or enlarged) to be as large as possible within the given
gravity
org
When cropping with
fit=cover
, specifies the most important side or point in the image that shouldn’t be cropped off.gravity=auto
- The point will be guessed by looking for areas that stand out the most from image background
gravity=side
andgravity=XxY
- If a side (
left
,right
,top
,bottom
) or coordinates specified on a scale from0.0
(top or left) to1.0
(bottom or right),0.5
being the center. The X and Y coordinates are separated by lowercasex
, 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.
- If a side (
quality=x
orq=x
- Specifies quality for images in JPEG, WebP and AVIF formats. 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
orf=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.
sharpen=x
- Specifies strength of sharpening filter. The value is a floating-point number between 0 (no sharpening) and 10 (max). 1 is a recommended value.
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. This option is ignored if the image is from another domain (subdomains are OK).
metadata
Controls amount of invisible metadata (EXIF data) that should be preserved. Color profiles and EXIF rotation are applied to the image even if the metadata is discarded. Note that if the Polish feature is enabled, all metadata may have been removed already and this option may have no effect.
metadata=keep
- Preserve most of the image metadata (including GPS location) when possible.
metadata=copyright
- Discard all metadata except EXIF copyright tag. This is the default for JPEG images.
metadata=none
- Discard all invisible metadata.
Supported formats and limitations
The service generates JPEG and PNG images, and optionally AVIF or WebP. It can save animations as GIF or animated WebP.
The service can read JPEG, PNG, GIF (including animations), and WebP images.
The service supports ICC color profiles in JPEG and PNG images. JPEG metadata can be preserved. Metadata of other formats is discarded.
Recommended image sizes
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, except the minimum cache time is 1 hour. If you need images to be updated more frequently, add must-revalidate
to the Cache-Control
header. Resizing supports cache revalidation, so we recommend serving images with the Etag
header.
We do not support purging of resized variants individually. URLs starting with /cdn-cgi/
can't be purged. However, purging of the original image's URL will also purge all of its resized variants.