Cloudflare Images

End-to-end image storage, transformation, and delivery solution on Cloudflare's global network.

Quick Navigation

•Upload methods → references/upload.md
•Transformations → references/transformations.md
•Variants → references/variants.md
•Workers binding → references/binding.md
•Polish → references/polish.md
•Signed URLs → references/security.md
•Pricing → references/pricing.md

When to Use

•Storing and delivering optimized images at scale
•Transforming remote images on-the-fly
•Resizing, cropping, converting image formats
•Adding watermarks to images
•Serving responsive images with srcset
•Protecting images with signed URLs
•Optimizing images from R2 storage

Two Usage Modes

Mode	Description	Billing
Storage in Images	Upload images to Cloudflare, serve via variants	Images Stored + Images Delivered
Transform remote	Optimize images from any origin (R2, S3, etc.)	Images Transformed (unique/30d)

Quick Start

Upload an Image (API)

bash

curl --request POST \
  --url https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/images/v1 \
  --header 'Authorization: Bearer <API_TOKEN>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@./image.jpg

Transform via URL

html

<img src="/cdn-cgi/image/width=400,quality=80,format=auto/uploads/hero.jpg" />

Transform via Workers

fetch(imageURL, {
  cf: {
    image: {
      width: 800,
      height: 600,
      fit: "cover",
      format: "auto",
    },
  },
});

URL Format

code

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

•<ZONE> — your Cloudflare domain
•/cdn-cgi/image/ — fixed prefix for image transformations
•<OPTIONS> — comma-separated: width=400,quality=80,format=auto
•<SOURCE-IMAGE> — absolute path or full URL

Stored Images Delivery

code

https://imagedelivery.net/<ACCOUNT_HASH>/<IMAGE_ID>/<VARIANT_NAME>

Transformation Options

Option	Description	Example
`width`	Max width in pixels	`width=800`
`height`	Max height in pixels	`height=600`
`fit`	Resize mode	`fit=cover`
`format`	Output format	`format=auto`
`quality`	JPEG/WebP/AVIF quality 1-100	`quality=85`
`gravity`	Crop focus point	`gravity=face`, `gravity=auto`
`blur`	Blur radius 1-250	`blur=50`
`sharpen`	Sharpening 0-10	`sharpen=1`
`rotate`	Rotation degrees	`rotate=90`
`trim`	Remove pixels from edges	`trim=20;30;20;0`

Fit Modes

Mode	Behavior
`scale-down`	Shrink only, never enlarge
`contain`	Fit within dimensions, preserve aspect ratio
`cover`	Fill dimensions, crop if needed
`crop`	Like cover but never enlarges
`pad`	Fit within, add background color

Format Auto

format=auto serves WebP or AVIF based on browser support. Use with Accept header parsing in Workers.

Supported Formats

Input

•JPEG, PNG, GIF (animated), WebP (animated), SVG, HEIC

Output

•JPEG, PNG, GIF, WebP, AVIF, SVG (passthrough)

Note: HEIC must be served as AVIF/WebP/JPEG/PNG. SVG is not resized (inherently scalable).

Limits

Constraint	Limit
Max image dimension	12,000 pixels
Max image area	100 megapixels
Max file size (transformations)	70 MB
Max file size (storage)	10 MB
GIF/WebP animation	50 megapixels total
AVIF output hard limit	1,200 px (1,600 explicit)
Variants per account	100

Workers Integration

Images Binding Setup

toml

# wrangler.toml
[images]
binding = "IMAGES"

Transform with Binding

const response = (await env.IMAGES.input(stream).transform({ width: 800 }).transform({ blur: 20 }).output({ format: "image/avif" })).response();

Draw Watermark

const watermark = await fetch("https://example.com/watermark.png");
const image = await fetch("https://example.com/photo.jpg");

const response = (
  await env.IMAGES.input(image.body)
    .draw(env.IMAGES.input(watermark.body).transform({ width: 100 }), { bottom: 10, right: 10, opacity: 0.75 })
    .output({ format: "image/avif" })
).response();

Get Image Info

const info = await env.IMAGES.info(stream);
// { format, fileSize, width, height }

Recipes

Responsive Images with srcset