Features (3)

Last updated Jun 16, 2026 Cloudflare enables developers to optimize images at scale by dynamically generating different versions in real time.

The guide describes all of the parameters that can be used to resize, crop, manipulate, and apply visual effects to images.

How to apply optimization

Use Cloudflare's image optimization capabilities through:

• URL interface — Apply parameters directly in the image URL to specify how images should be optimized when served to the browser.
• Workers — Bind the Images API directly to your Worker or set the cf.image options on a fetch subrequest to build programmatic image workflows.

URL interface

Cloudflare uses a different URL structure depending on whether you are optimizing a remote or a hosted image:

When optimizing images outside of Images, the default transformation URL uses the following structure:

https://<ZONE>/cdn-cgi/image/<OPTIONS>/<SOURCE-IMAGE>

<details>

<summary>

URL breakdown

</summary>

</details>

For images stored in Cloudflare Images, use the delivery URL with a variant or custom options:

https://imagedelivery.net/<ACCOUNT_HASH>/<IMAGE-ID>/<VARIANT-OR-OPTIONS>

<details>

<summary>

URL breakdown

</summary>

</details>

Workers

When using Images with Workers, you can:

• Apply custom logic to set the order for optimization operations. For example, by default, Images will apply flip before rotate; instead, you can use the Images binding to customize your optimization workflow to rotate the image before flipping it.
• Use a custom URL scheme instead of the default URL structure.
• Implement content negotiation to dynamically adapt image size, format, and quality based on the device and network condition.

Parameters

anim

Specifies whether to preserve animation frames from input files.

• true (default) — Outputs the animated image with all frames.
• false — Converts the first frame of an animated input to a still image.

This setting is recommended when enlarging images or processing arbitrary user-uploaded content, as animated GIFs can have large file sizes and increase page load times. When using format=json, it is also useful to set anim=false to get a quicker response without the number of frames.

Original	anim=false

anim=false

cf: {image: {anim: false}}

background

Specifies an opaque or transparent color to fill blank or transparent pixels in the image. The default is %23FFFFFF (white).

Accepts the following properties:

• A HEX color code, formatted as %23RRGGBB.
• A CSS color name, e.g. white or red.
• An rgb() or rgba() CSS color function, e.g. rgba(250,40,145,0.5).

The background color is visible in images with transparent pixels, including images that are resized with fit=pad.

Original<br> 1080 x 720	Output<br> 1080 x 900

background=%23ff0000
background=red
background=rgb%28240%2C40%2C145%29

cf: {image: {background: "#RRGGBB"}}
cf: {image: {background: "rgba(240,40,145,0)"}}

blur

Applies a blur radius to the image. Accepts an integer from 0 (no blur) to 250 (maximum blur). The default is 0.

This parameter should not be used to reliably obscure image content when optimizing via URL, as the URL can be modified to remove the blur parameter. Instead, you can restrict access to the original image through Workers.

Original	blur=50

blur=50

cf: {image: {blur: 50}}

border

Adds a border around the image.

Note

This feature is available only in Workers.

Accepts the following properties:

• color — Sets the color of the border. Accepts any valid CSS color value, for example #FF0000, rgb(0,0,0), or red.
• width — Sets the uniform border, in pixels, on all four sides.
• top, right, bottom, left — Sets the border width, in pixels, for individual sides.

The border is applied after the image has been resized. The border width automatically scales with the dpr parameter to ensure sharpness on high-resolution screens.

cf: {image: {border: {color: "rgb(0,0,0,0)", top: 5, right: 10, bottom: 5, left: 10}}}
cf: {image: {border: {color: "#FFFFFF", width: 10}}}

brightness

Adjusts the image's overall luminance using a multiplier.

• 1 (default) — No change to the original brightness.
• < 1.0 — Darkens the image, e.g. 0.5 is half as bright.
• > 1.0 — Lightens the image, e.g. 2 is twice as bright.

Original	brightness=0.5	brightness=2

brightness=0.5

cf: {image: {brightness: 0.5}}

compression

Selects the output format that is quickest to compress. Accepts fast. The default is none.

The compression=fast option prioritizes encoding speed over output quality and file size, and will usually override the format parameter to choose JPEG over more efficient formats like AVIF or WebP. This slightly reduces latency on a cache miss, but may result in increased file size and lower image quality.

This option is not recommended, except in unusual circumstances like resizing uncacheable, dynamically-generated images.

compression=fast

cf: {image: {compression: "fast"}}

contrast

Adjusts the image's overall difference between the darkest and lightest parts using a multiplier.

• 1 (default) — No change to the original contrast.
• < 1.0 — Decreases contrast, which makes shadows lighter and highlights darker.
• > 1.0 — Increases contrast, which pushes shadows toward black and highlights toward white.

Original	contrast=0.5	contrast=2

contrast=0.5

cf: {image: {contrast: 0.5}}

dpr

Scales the output resolution by a multiplier to match a user's specific screen density (for example, Retina or 4K). The default is 1, which delivers the image at the exact width and height requested. The maximum supported value is 2.

Modern devices have more physical pixels than CSS pixels. If you serve a 300px image in a 300px container on a high-DPR smartphone, then it will look blurry. Using dpr=2 tells Cloudflare to send a 600px image for the same 300px container, which results in a clearer, crisper image.

The dpr parameter can be used with srcset to serve responsive images.

width=300,height=200,dpr=1	width=300,height=200,dpr=2

dpr=1

cf: {image: {dpr: 1}}

fit

Specifies how the image is fit to the target area.

Fit is performed after setting the width and height dimensions of the image.

fit=pad

cf: {image: {fit: "pad"}}

scale-down

Resizes the image to fit within the specified dimensions while preserving its original aspect ratio, but never upscales the image. This is the default fit behavior.

When the original image is smaller than the target area, it is returned at its original dimensions. For example, a request to serve a 1080x720 image at 2000x2000 will return the image at 1080x720.

When larger, it downscales the image to fit the target area while matching the original aspect ratio.

In the example below, the 1080x720 image is resized to fit within the target 500x500 area. Since scale-down preserves the original aspect ratio (3:2), the final dimensions of the output image are 500x333.

Original<br> 1080 x 720 (3:2)	Requested<br> 500 x 500 (1:1)	Output<br> 500 x 333 (3:2)

contain

Resizes the image to be as large as possible within the target width and height dimensions while preserving its original aspect ratio.

When the original image is larger than the target area, it downscales to fit the target area (like scale-down).

When smaller, it upscales instead (like scale-up). Works with the upscale parameter to control the algorithm for enlarging an image. To avoid upscaling, use scale-down.

cover

Fills the entire target area, shrinking or enlarging the image if needed. The output area always matches the requested width and height dimensions exactly.

When the original and target aspect ratios differ, the image is resized to cover the full target area and any overflow is cropped. Use the gravity parameter to control which part of the image is preserved during cropping.

Works with the upscale parameter to control the algorithm for enlarging an image.

In the example below, the 1080×720 image is first resized to 750×500 (matching the requested height) to fit the target area, then cropped from the left and right edges to its final 500x500 dimensions.

Original<br> 1080 x 720 (3:2)	Requested<br> 500 x 500 (1:1)	Output<br> 500 x 500 (1:1)

When the original image is smaller than the target area, it upscales instead. To avoid upscaling, use crop.

crop

Resizes the image to fill the target area without upscaling.

When the original image is smaller than the target area, it keeps its original size and aspect ratio (like scale-down).