Cloudflare Images Transform via URL

anim

是否保留输入文件的动画帧。默认为 true。设置为 false 会将动画转换为静态图片。建议在放大图片或处理任意用户内容时使用此设置，因为大型 GIF 动画可能有数十甚至数百兆字节。

示例：

• anim=false

background

在图片下方添加背景色。适用于具有透明度的图片（例如 PNG）和使用 fit=pad 调整大小的图片。接受任何 CSS 颜色，使用 CSS4 现代语法，例如 rgb(255 255 0) 和 rgba(255 255 0 100)。

示例（需配合 fit=pad 使用）：

• w=500,h=500,fit=pad,background=red
• w=500,h=500,fit=pad,background=rgb(240,40,145)

blur

模糊半径，范围 1（轻微模糊）到 250（最大模糊）。注意：不能用此选项可靠地隐藏图片内容，因为用户可以修改 URL 移除模糊选项。使用 Workers 来控制可设置的选项。

示例：

• blur=10
• blur=50
• blur=150

border

在图片周围添加边框。边框在调整大小后添加。边框宽度会考虑 dpr，可以使用单个 width 属性指定，也可以为每一侧单独指定。

注意：此参数仅在 Workers 中可用

brightness

按因子增加亮度。值 1.0 表示无变化，值 0.5 表示一半亮度，值 2.0 表示两倍亮度。忽略 0。

示例：

• brightness=0.5
• brightness=1.5
• brightness=2.0

compression

通过选择最快压缩的文件格式来略微减少缓存未命中时的延迟，代价是文件大小增加和图片质量降低。通常会覆盖 format 选项，选择 JPEG 而不是 WebP 或 AVIF。不建议使用此选项，除非在特殊情况下，如调整无法缓存的动态生成图片。

示例：

• compression=fast

contrast

按因子增加对比度。值 1.0 表示无变化，值 0.5 表示低对比度，值 2.0 表示高对比度。忽略 0。

示例：

• contrast=0.5
• contrast=1.5
• contrast=2.0

dpr

设备像素比。默认为 1。width/height 的乘数，使在 <img srcset> 中指定更高 DPI 尺寸更容易。

示例（需配合 width 或 height 使用）：

• w=200,dpr=1 - 实际宽度 200px
• w=200,dpr=2 - 实际宽度 400px

fit

影响 width 和 height 的解释。所有调整大小模式都保留宽高比。可用模式：scale-down（类似 contain 但不放大）、contain（在给定尺寸内尽可能大）、cover（填充整个区域，可能裁剪）、crop（缩小并裁剪）、pad（调整大小后填充背景色）、squeeze（拉伸到精确尺寸）。

示例（需配合 width 和 height 使用）：

• w=400,h=300,fit=scale-down
• w=400,h=300,fit=contain
• w=400,h=300,fit=cover
• w=400,h=300,fit=crop
• w=400,h=300,fit=pad

flip

水平、垂直或同时翻转图片。可与 rotate 参数一起使用来设置图片方向。翻转在旋转之前执行。可用选项：h（水平翻转）、v（垂直翻转）、hv（垂直和水平翻转）。

示例：

• flip=h
• flip=v
• flip=hv

format

auto 选项将向支持的浏览器提供 WebP 或 AVIF 格式。如果未指定此选项，将使用标准格式如 JPEG 或 PNG。由于 PNG 文件较大，Cloudflare 会在可能的情况下默认使用 JPEG。其他支持的选项：avif、webp、jpeg、baseline-jpeg、json。

示例：

• format=auto
• format=webp
• format=avif
• format=jpeg

gamma

按因子增加曝光度。值 1.0 表示无变化，值 0.5 使图片变暗，值 2.0 使图片变亮。忽略 0。

示例：

• gamma=0.5
• gamma=1.5
• gamma=2.0

gravity

指定与 fit=cover 和 fit=crop 一起使用时如何裁剪图片。可用选项：auto（基于显著性检测选择焦点）、side（left、right、top、bottom）、相对坐标（XxY，范围 0.0 到 1.0）、face（基于检测到的人脸自动设置焦点）。

示例（需配合 fit=cover 或 fit=crop 使用）：

• w=400,h=300,fit=cover,gravity=auto
• w=400,h=300,fit=cover,gravity=left
• w=400,h=300,fit=cover,gravity=right
• w=400,h=300,fit=cover,gravity=top

height

指定图片的最大高度（像素）。确切行为取决于 fit 模式。

示例：

• h=200
• h=400
• h=600

metadata

控制应保留的不可见元数据（EXIF 数据）量。即使丢弃元数据，颜色配置文件和 EXIF 旋转也会应用于图片。可用选项：copyright（仅保留版权标签）、keep（保留大部分 EXIF 元数据）、none（丢弃所有不可见的 EXIF 和 C2PA 元数据）。JPEG 图片的默认值为 copyright。

示例：

• metadata=keep
• metadata=copyright
• metadata=none

onerror

如果发生阻止图片调整大小的致命错误，则重定向到未调整大小的源图片 URL。这在某些图片需要用户身份验证且无法通过 Worker 匿名获取的情况下可能很有用。如果源图片可能非常大，则不应使用此选项。如果图片来自另一个域，则忽略此选项，但可以与子域一起使用。

注意：此设置仅直接用于图片转换，不支持使用 Cloudflare Workers 调整大小。

quality

指定 JPEG、WebP 和 AVIF 格式图片的质量。质量范围为 1-100，但有用的值在 50（低质量，小文件）和 90（高质量，大文件）之间。默认值为 85。也可以设置感知质量级别：high、medium-high、medium-low、low。

示例：

• quality=50
• quality=75
• quality=90

rotate

旋转图片的角度（90、180 或 270 度）。width 和 height 选项指的是旋转后的轴。

示例：

• rotate=90
• rotate=180
• rotate=270

saturation

按因子增加饱和度。值 1.0 表示无变化，值 0.5 表示一半饱和度，值 2.0 表示两倍饱和度。值 0 将图片转换为灰度。

示例：

• saturation=0 - 灰度
• saturation=0.5
• saturation=2.0

segment

通过将背景替换为透明像素来自动隔离图片的主体。此功能通过 Workers AI 使用名为 BiRefNet 的开源模型。

示例：

• segment=foreground

sharpen

指定应用于图片的锐化滤镜强度。值为 0（无锐化，默认）到 10（最大）之间的浮点数。建议对缩小的图片使用值 1。

示例：

• sharpen=1
• sharpen=3
• sharpen=5

slow-connection-quality

允许在检测到慢速连接时覆盖 quality 值。可用选项与 quality 相同。检测慢速连接目前仅在基于 Chromium 的浏览器（如 Chrome、Edge 和 Opera）上支持。需要通过 HTTP 头启用客户端提示：accept-ch: rtt, save-data, ect, downlink。

注意：此参数需要特定的 HTTP 头支持，无法通过简单的 URL 访问演示。

trim

指定在每一侧切掉的像素数。允许移除边框或裁剪图片的特定片段。修剪在调整大小或旋转之前执行。会考虑 dpr。格式为 top;right;bottom;left 或使用单独的值 trim.width、trim.height、trim.left、trim.top。也支持基于颜色的自动边框移除：trim=border。

示例：

• trim=50;50;50;50
• trim=100;0;0;0 - 仅裁剪顶部

width

指定图片的最大宽度。确切行为取决于 fit 模式；使用 fit=scale-down 选项确保图片不会被不必要地放大。可用选项为指定的像素宽度或 auto（仅 Chromium 浏览器支持）。

示例：

• w=300
• w=500
• w=800

zoom

指定与 gravity=face 选项结合使用时图片向人脸裁剪的紧密程度。有效范围从 0（尽可能包含背景）到 1（尽可能紧密地裁剪到人脸），允许小数。默认值为 0。仅在图片中检测到人脸时生效。

示例（需配合 gravity=face 使用）：

• w=400,h=400,fit=cover,gravity=face,zoom=0
• w=400,h=400,fit=cover,gravity=face,zoom=0.5
• w=400,h=400,fit=cover,gravity=face,zoom=1