cloudflare-images（cloudflare 图片）

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

Links

• Documentation
• Changelog

Related Skills

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