Features (3)·续1

In the example below, the original image (1080x720) is smaller than the target area (1296x1296), so it preserves its original size and aspect ratio.

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

When the original image is larger than the target area, it behaves like cover (fills the target area and crops the rest) instead.

aspect-crop

Crops the image to match the target aspect ratio, scaling down if needed but never upscaling.

When the original image is larger than the target area, it downscales to the smallest size that still fills the target dimensions, then is cropped to match the target aspect ratio (like cover).

When the original image is smaller than the target area, it keeps its original size but is cropped to match the target aspect ratio. Unlike crop, which preserves the original size and dimensions of smaller images, aspect-crop always enforces the target aspect ratio.

For example, a 612x613 image requested at 1920x1120 will not be upscaled. Instead, it stays at its original size and is cropped to 612x357, matching the 1920:1120 aspect ratio. Use the gravity parameter to control which part of the image is preserved during cropping.

pad

Resizes the image to be as large as possible within the dimensions. If applicable, the output area will be expanded to match the width and height dimensions exactly.

Works with the background parameter to fill any blank or transparent pixels. However, for web apps, you can often achieve the same visual result using the contain option with the CSS object-fit: contain property, which avoids encoding padding pixels into the image itself.

In the example below, the original image (1080x720) is smaller than the target area (1080x1080), so it creates space for the remaining pixels.

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

squeeze

Resizes the image to exactly match the requested width and height, without cropping the edges or constraining the portions.

When the original and target aspect ratios differ, the image will be distorted to fit the target area.

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

Original<br> 1080 x 1080	Output<br> 1080 x 540

scale-up

Resizes the image to fit within the specified dimensions while preserving its original aspect ratio, but never downscales the image. This is the inverse of scale-down.

When the original image is larger than the target area, it is returned at its original dimensions.

When the original image is smaller than the target area, it is enlarged to fit within the target dimensions. Use the upscale parameter to control the algorithm used for upscaling images — set upscale=generate for AI-powered upscaling or upscale=interpolate (default) for bicubic interpolation.

flip

Flips the image horizontally, vertically, or both.

Accepts the following values:

• h — Flips the image horizontally.
• v — Flips the image vertically.
• hv — Flips the image both horizontally and vertically.

Flip can be used with the rotate parameter to set the orientation of the image. Flip is performed before rotation. For example, if you apply flip=h,rotate=90, then the image will be flipped horizontally, then rotated by 90 degrees.

Original	flip=h	flip=v

flip=h

cf: {image: {flip: "h"}}

format | f

Specifies the output format for the image.

Accepts the following values:

• auto — Automatically serves the most efficient format that the requesting browser supports. When you serve a hosted image, this is the default format option.
• avif — Transcodes the image to AVIF, if possible. AVIF encoding can be an order of magnitude slower than encoding to other formats. If the image is too large to be quickly encoded to AVIF, then Cloudflare will fall back to WebP or JPEG.
• webp — Transcodes the image to Google WebP format. Use quality=100 to return the WebP lossless format.
• jpeg — Transcodes the image in interlaced progressive JPEG format, in which data is compressed in multiple passes of progressively higher detail.
• baseline-jpeg — Transcode the image in baseline sequential JPEG format. It should be used in cases when target devices do not support progressive JPEG or other modern file formats.
• json — Outputs information about the image as a JSON object. This contains data such as image size (before and after resizing), the source image's MIME type, and file size.

format=auto
f=auto

cf: {image: {format: "avif"}}

To use format=auto with a custom Worker, you need to parse the Accept header. Refer to this example Worker for a complete overview of how to set up an image transformation Worker.

Custom Worker for Image Resizing with format:autojs

const accept = request.headers.get("accept");
let image = {};

if (/image\/avif/.test(accept)) {
    image.format = "avif";
} else if (/image\/webp/.test(accept)) {
    image.format = "webp";
}

return fetch(url, { cf: { image } });

gamma

Adjusts the exposure of an image using a multiplier. Gamma controls the midtone brightness without affecting the darkest or lightest parts of the image.

• 0 and 1 (default) — No change to the original gamma.
• < 1.0 — Increases midtone brightness, making the image appear lighter overall.
• > 1.0 — Decreases midtone brightness, making the image appear darker overall.

Original	gamma=0.5	gamma=2

gamma=0.5

cf: {image: {gamma: 0.5}}

gravity | g

Specifies how the image should be cropped when used with fit=cover and fit=crop. By default, Cloudflare will crop toward the center point of the original image.

Accepts auto, face, a side (left, right, top, bottom), and relative coordinates (XxY).

gravity=auto
g=auto
gravity=face
gravity=left
gravity=0.5x1

cf: {image: {gravity: "auto"}}
cf: {image: {gravity: "face"}}
cf: {image: {gravity: "left"}}
cf: {image: {gravity: {x:0.5, y:0.2}}}

auto

Automatically sets the focal point by using a saliency algorithm to detect the most visually interesting pixels.

This is useful when you don't know the contents of the image ahead of time, such as with user-generated content. For large image libraries such as e-commerce product galleries, this feature eliminates the need to manually set a focal point for each image.

Original	Default crop	gravity=auto

face

Automatically sets the focal point based on faces in the image.

This can be combined with the zoom parameter to specify how closely the image should be cropped toward the face.

Original	Default crop	gravity=face

Photograph by Suad Kamardeen (@suadkamardeen) on Unsplash ↗︎

left, right, top, bottom

Sets the side of the image that should not be cropped.

In the example below, the 1080x720 image is cropped to a 1080x400 area, starting from its bottom edge:

Original	gravity=bottom

XxY

Sets the focal point (X,Y) so that the relative coordinates of the output image are positioned at the relative coordinates of the original image. Accepts a coordinate pair formatted as XxY, where X and Y are decimal values between 0.0 and 1.0.

• Horizontal value (X) — 0.0 is the left edge and 1.0 is the right edge of the image.
• Vertical value (Y) — 0.0 is the top edge and 1.0 is the bottom edge of the image.

The example below crops a 900x900 image to 300x900 using a 0.33x0.5 gravity point:

• Both the original image and target area will have gravity points set at 1/3 of the width from the left edge and 1/2 of the height from the top edge.
• The relative coordinates of the output gravity point are positioned at the relative coordinates of the original image. That is, the target area is positioned so that its gravity point sits at the same relative position in the original image (0.33, 0.5).
• The darkened parts of the image show the area outside of the requested output, which will be cropped.
• The final cropped result captures the 300x900 content that is around the gravity point (0.33, 0.5).

Original<br>	Align<br>	Crop<br>	Output<br>

When optimizing through Workers, use an object {x, y} to specify coordinates. For example, {fit: "cover", gravity: {x:0.5, y:0.2}} will crop each side to preserve as much as possible around a point at 20% of the height of the original image.

height | h

Sets the height of the output image in pixels using a positive integer value. By default, Cloudflare uses the original height of the input image.

When height is set, the exact behavior depends on the fit parameter.

height=250
h=250

cf: {image: {height: 250}}

metadata

Controls the amount of invisible metadata (EXIF) that should be preserved for a JPEG image. For all other output formats (e.g. WebP or PNG), all metadata will always be discarded.

Color profiles and EXIF rotation are applied to the image even if the metadata is discarded.

Note

If Polish is enabled, then all metadata may already be removed and this option will have no effect.

Accepts the following values:

• copyright (default) — Discards all metadata except EXIF copyright tag.
• keep — Preserves most of EXIF metadata, including GPS location, if present.
• none — Discards all invisible EXIF metadata.

metadata=none

cf: {image: {metadata: "none"}}

onerror

Redirects the end-user to the URL of the original source image when a fatal error prevents the image from being transformed. Accepts redirect. The default is none.

Note

This feature is available only when optimizing remote images through the URL interface. This is not supported for hosted images.

This option works only if the image is in the same zone (subdomains are accepted). If the original image is from a different zone, then the option does not have any effect.

This may be useful in cases where an image requires user authentication and the image cannot be fetched anonymously via Workers. However, this option is not recommended if the source image is very large.

onerror=redirect

quality | q

Specifies the output quality of an image for JPEG, WebP, and AVIF formats, expressed as a fixed value or perceptual quality level. The default is 85.

• Fixed quality — Accepts a positive integer from 1 (low quality, small file size) to 100 (high quality, large file size).
• Perceptual quality — Accepts high, medium-high, medium-low, and low.

When the output format is PNG, an explicit quality setting allows the use of PNG8 (palette) variant of the format.