cloudflare-images

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloudflare Images

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

基于Cloudflare全球网络的端到端图片存储、转换与交付解决方案。

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
```

上传方式 →
```
references/upload.md
```
图片转换 →
```
references/transformations.md
```
变体 →
```
references/variants.md
```
Workers绑定 →
```
references/binding.md
```
Polish →
```
references/polish.md
```
签名URL →
```
references/security.md
```
定价 →
```
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

大规模存储并交付经过优化的图片
实时转换远程图片
调整图片大小、裁剪、转换图片格式
为图片添加水印
使用
```
srcset
```
提供响应式图片
用签名URL保护图片
优化来自R2存储的图片

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)

模式	描述	计费方式
存储至Images	将图片上传至Cloudflare，通过变体交付	存储图片量 + 交付图片量
转换远程图片	优化来自任意源（R2、S3等）的图片	图片转换量（30天内唯一请求）

Quick Start

快速开始

Upload an Image (API)

通过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

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

通过URL转换图片

html

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

html

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

Transform via Workers

通过Workers转换图片

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

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

URL Format

URL格式

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

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

```
<ZONE>
```
— 你的Cloudflare域名
```
/cdn-cgi/image/
```
— 图片转换的固定前缀

<OPTIONS>

— 逗号分隔的参数：

width=400,quality=80,format=auto

```
<SOURCE-IMAGE>
```
— 绝对路径或完整URL

Stored Images Delivery

已存储图片的交付格式

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

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`

选项	描述	示例
`width`	最大宽度（像素）	`width=800`
`height`	最大高度（像素）	`height=600`
`fit`	缩放模式	`fit=cover`
`format`	输出格式	`format=auto`
`quality`	JPEG/WebP/AVIF质量（1-100）	`quality=85`
`gravity`	裁剪焦点	`gravity=face` , `gravity=auto`
`blur`	模糊半径（1-250）	`blur=50`
`sharpen`	锐化程度（0-10）	`sharpen=1`
`rotate`	旋转角度（度）	`rotate=90`
`trim`	移除边缘像素	`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

模式	行为
`scale-down`	仅缩小，绝不放大
`contain`	适配尺寸，保留宽高比
`cover`	填充尺寸，必要时裁剪
`crop`	类似cover，但绝不放大
`pad`	适配尺寸，添加背景色

Format Auto

自动格式

format=auto

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

format=auto

会根据浏览器支持情况提供WebP或AVIF格式。可结合Workers中的Accept头解析使用。

Supported Formats

支持的格式

Input

输入格式

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

JPEG、PNG、GIF（动图）、WebP（动图）、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).

JPEG、PNG、GIF、WebP、AVIF、SVG（直接透传）

注意： HEIC必须转换为AVIF/WebP/JPEG/PNG格式后交付。SVG不会被调整大小（本身是矢量图，可缩放）。

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

约束条件	限制值
最大图片尺寸	12,000像素
最大图片面积	1亿像素
转换时最大文件大小	70 MB
存储时最大文件大小	10 MB
GIF/WebP动图	总像素不超过5000万
AVIF输出硬限制	1200像素（显式设置为1600）
每个账户的变体数量	100

Workers Integration

Workers集成

Images Binding Setup

Images绑定设置

toml

undefined

toml

undefined

wrangler.toml

[images] binding = "IMAGES"

undefined

[images] binding = "IMAGES"

undefined

Transform with Binding

通过绑定转换图片

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

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();

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 }

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

Recipes

实践方案

Responsive Images with srcset

使用srcset实现响应式图片

html

<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" />

html

<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
    },
  },
});

fetch(imageURL, {
  cf: {
    image: {
      width: 200,
      height: 200,
      fit: "cover",
      gravity: "face",
      zoom: 0.5, // 0 = 保留更多背景，1 = 紧密裁剪
    },
  },
});

Direct Creator Upload

bash

undefined

bash

undefined

Get one-time upload URL

获取一次性上传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/..." }

响应：{ "uploadURL": "https://upload.imagedelivery.net/..." }

undefined

undefined

Upload from Worker

通过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,
});

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

重要禁忌

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

切勿为整个域名（
```
/*
```
）设置图片重定向Worker —— 会阻止非图片请求
切勿同时启用Polish和图片转换 —— 重复压缩
切勿将灵活变体与签名URL令牌配合使用 —— 不兼容
切勿在
```
requireSignedURLs=true
```
时使用自定义ID路径 —— 不支持
切勿期望SVG能被调整大小 —— SVG会直接透传
切勿在
```
cacheKey
```
中包含重定向选项 —— 会碎片化缓存

Troubleshooting

故障排查

Cf-Resized

Header

无

Cf-Resized

响应头

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

域名未启用图片转换
其他Worker拦截了请求
使用了控制台预览（不会模拟转换效果）

Common Error Codes

常见错误码

Code	Meaning
9401	Invalid transformation options
9402	Image too large
9403	Request loop detected
9422	Free tier limit exceeded (5,000/month)
9520	Unsupported format

错误码	含义
9401	无效的转换选项
9402	图片过大
9403	检测到请求循环
9422	免费版限额已超出（每月5000次）
9520	不支持的格式

cloudflare-images

Original

Translation

Cloudflare Images

Cloudflare Images

Quick Navigation

快速导航

When to Use

适用场景

Two Usage Modes

两种使用模式

Quick Start

快速开始

Upload an Image (API)

通过API上传图片

Transform via URL

通过URL转换图片

Transform via Workers

通过Workers转换图片

URL Format

URL格式

Stored Images Delivery

已存储图片的交付格式

Transformation Options

转换选项

Fit Modes

缩放模式

Format Auto

自动格式

Supported Formats

支持的格式

Input

输入格式

Output

输出格式

Limits

限制条件

Workers Integration

Workers集成

Images Binding Setup

Images绑定设置

wrangler.toml

wrangler.toml

Transform with Binding

通过绑定转换图片

Draw Watermark

添加水印

Get Image Info

获取图片信息

Recipes

实践方案

Responsive Images with srcset

使用srcset实现响应式图片

Face-Aware Cropping

人脸识别裁剪

Direct Creator Upload

Direct Creator Upload

Get one-time upload URL

获取一次性上传URL

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

响应：{ "uploadURL": "https://upload.imagedelivery.net/..." }

Upload from Worker

通过Worker上传图片

Critical Prohibitions

重要禁忌

Troubleshooting

故障排查

No Cf-Resized Header

无Cf-Resized响应头

Common Error Codes

常见错误码

Related Skills

相关技能

No
`Cf-Resized`
Header

无
`Cf-Resized`
响应头