name: cloudflare-images
description: "Store, transform, and deliver optimized images with Cloudflare Images. Covers image upload (API, Worker, Direct Creator Upload), variants, transformations (URL and Workers), bindings, Polish, signed URLs, formats (AVIF, WebP), R2 integration, watermarks. Keywords: Cloudflare Images, image transformations, variants, /cdn-cgi/image/, imagedelivery.net, Polish, AVIF, WebP, signed URLs, Direct Creator Upload, Images binding, R2, watermark."

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

Quick Start

Upload an Image (API)

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

<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

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

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

Transformation Options

Fit Modes

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

Workers Integration

Images Binding Setup

# 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

<img srcset="/cdn-cgi/image/width=320/photo.jpg 320w, /cdn-cgi/image/width=640/photo.jpg 640w, /cdn-cgi/image/width=1280/photo.jpg 1280w" sizes="(max-width: 640px) 100vw, 640px" src="/cdn-cgi/image/width=640/photo.jpg" alt="Responsive image" />

Face-Aware Cropping

fetch(imageURL, {
  cf: {
    image: {
      width: 200,
      height: 200,
      fit: "cover",
      gravity: "face",
      zoom: 0.5, // 0 = more background, 1 = tight crop
    },
  },
});

Direct Creator Upload

# Get one-time upload URL
curl --request POST \
  https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v2/direct_upload \
  --header "Authorization: Bearer <API_TOKEN>"

# Response: { "uploadURL": "https://upload.imagedelivery.net/..." }

Upload from Worker

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

const formData = new FormData();
formData.append("file", new File([bytes], "image.png"));

await fetch(`https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/images/v1`, {
  method: "POST",
  headers: { Authorization: `Bearer ${TOKEN}` },
  body: formData,
});

Critical Prohibitions

1. NEVER set up Image Resizing Worker for entire zone (/*) — blocks non-image requests
2. NEVER activate Polish and image transformations simultaneously — redundant compression
3. NEVER use flexible variants with signed URL tokens — incompatible
4. NEVER use custom ID paths with requireSignedURLs=true — not supported
5. NEVER expect SVG resizing — SVGs are passed through as-is
6. NEVER include resizing options in cacheKey — fragments cache

Troubleshooting

No Cf-Resized Header

• Transformations not enabled on zone
• Another Worker intercepting request
• Using dashboard preview (doesn't simulate transforms)

Common Error Codes

Related Skills

• cloudflare-workers - For serverless compute
• cloudflare-pages - For full-stack apps
• cloudflare-r2 - R2 object storage