cloudinary-transformations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloudinary Transformation Rules

Cloudinary 转换规则

When to Use

使用场景

Building Cloudinary delivery/transformation URLs
Converting natural language requests to transformation syntax
Debugging transformation URLs that aren't working
Optimizing images or videos with Cloudinary
Applying effects, overlays, resizing, or cropping

构建Cloudinary分发/转换URL
将自然语言请求转换为转换语法
调试无法正常工作的转换URL
使用Cloudinary优化图片或视频
应用特效、叠加层、调整大小或裁剪

Quick Start

快速入门

Default Best Practice: Always Optimize

默认最佳实践：始终优化

Add
f_auto/q_auto
to the end of nearly every transformation URL (as final components):

Automatically delivers optimal format
Optimizes quality for best balance of visual quality and file size
Reduces bandwidth and improves performance

Example:

c_fill,g_auto,w_400,h_300/f_auto/q_auto

Exceptions - Don't add optimization when:

Account has "Optimize By Default" enabled (already applied automatically)
Special quality requirements (use
```
q_auto:best
```
,
```
q_auto:low
```
, or manual
```
q_N
```
instead)
Specific format required (replace
```
f_auto
```
with
```
f_png
```
,
```
f_jpg
```
, etc.)
Delivering exact original with no modifications

Examples of common transformations (with optimization):

Resize:
```
c_scale,w_400/f_auto/q_auto
```
Smart crop:
```
c_fill,g_auto,h_300,w_400/f_auto/q_auto
```
Background removal:
```
e_background_removal/f_png/q_auto
```

Text overlay:

co_yellow,l_text:Arial_40:Hello%20World/fl_layer_apply,g_south/f_auto/q_auto

Image overlay:

l_logo/c_scale,w_100/fl_layer_apply,g_north_west,x_10,y_10/f_auto/q_auto

Important: All transformation strings shown throughout this skill are illustrative examples to demonstrate syntax and concepts. When generating transformations, choose specific values (dimensions, colors, positions, etc.) based on the user's actual requirements and use case, not the example values shown.

For debugging: See references/debugging.md for detailed troubleshooting steps.

几乎所有转换URL的末尾都要添加
f_auto/q_auto
（作为最后两个参数组件）：

自动分发最优格式
优化质量，在视觉效果和文件大小之间取得最佳平衡
减少带宽占用，提升性能

示例：

c_fill,g_auto,w_400,h_300/f_auto/q_auto

例外情况——请勿添加优化参数的场景：

账号已开启「默认优化」（参数会自动生效）
有特殊质量要求（改用
```
q_auto:best
```
、
```
q_auto:low
```
或手动设置
```
q_N
```
）
需要指定格式（将
```
f_auto
```
替换为
```
f_png
```
、
```
f_jpg
```
等）
分发无修改的原始资源

常见转换示例（含优化参数）：

调整大小：
```
c_scale,w_400/f_auto/q_auto
```
智能裁剪：
```
c_fill,g_auto,h_300,w_400/f_auto/q_auto
```
背景移除：
```
e_background_removal/f_png/q_auto
```

文字叠加：

co_yellow,l_text:Arial_40:Hello%20World/fl_layer_apply,g_south/f_auto/q_auto

图片叠加：

l_logo/c_scale,w_100/fl_layer_apply,g_north_west,x_10,y_10/f_auto/q_auto

重要提示： 本Skill中展示的所有转换字符串仅为演示语法和概念的示例。生成转换规则时，请根据用户的实际需求和使用场景选择具体值（尺寸、颜色、位置等），不要直接使用示例中的值。

调试相关： 查看 references/debugging.md 获取详细的故障排查步骤。

Gathering Requirements

需求收集

Before generating a transformation URL, if not already specified, clarify these details based on the user's request:

生成转换URL前，如果用户未明确说明，请根据请求确认以下细节：

For Resize/Crop Requests

调整大小/裁剪请求

Required:

At least one dimension (width OR height)
Crop behavior if both dimensions specified (fill, pad, scale, limit, etc.)

Clarify:

Focal point/gravity (especially for cropping): Face detection? Center? Smart auto-detection?
Maintain aspect ratio? (if only one dimension, this is automatic)

Example questions:

"What dimensions do you need? (width and/or height)"
"Should this fill the space (may crop) or fit within it (no cropping)?"
"Any important focal point? (faces, center, specific area)"

必填信息：

至少一个维度（宽度 OR 高度）
如果指定了两个维度，需要确认裁剪行为（填充、内边距、缩放、限制等）

需确认的信息：

焦点/重力参数（裁剪场景尤其重要）：人脸检测？居中？智能自动检测？
是否需要保持宽高比？（如果仅指定一个维度，默认自动保持）

示例询问话术：

"你需要什么尺寸？（宽度和/或高度）"
"应该填满空间（可能会裁剪）还是适配空间（不裁剪）？"
"有需要重点保留的焦点区域吗？（人脸、居中、特定区域）"

For AI Transformation Requests

AI转换请求

Background removal:

Output format needs (PNG for transparency vs JPG with solid background)
What to do with transparent area (keep transparent, add color, or gen_fill)

Generative fill:

Target dimensions or aspect ratio
How much extension needed

Generative replace:

What object to replace (from)
What to replace it with (to)
Preserve original shape? (for clothing/objects)

Generative remove:

What object(s) to remove
Remove all instances or just one?

Generative background replace:

Describe desired background (or use auto-generation)
Need reproducibility? (consider seed parameter)

背景移除：

输出格式要求（PNG保留透明度或 JPG使用纯色背景）
透明区域的处理方式（保持透明、添加颜色、或生成填充）

生成式填充：

目标尺寸或宽高比
需要扩展的范围

生成式替换：

需要替换的对象（来源）
替换后的内容（目标）
是否保留原始形状？（服装/物品场景适用）

生成式移除：

需要移除的对象
移除所有实例还是仅单个实例？

生成式背景替换：

描述期望的背景（或使用自动生成）
是否需要可复现？（可考虑使用seed参数）

For Video Transformation Requests

视频转换请求

Trimming:

Start and end time, or duration
Seconds or percentage of video

Codec/format:

Output format needs (MP4, WebM, etc.)
Quality requirements (use
```
vc_auto
```
if unsure)

Audio:

Keep or remove audio track
If for autoplay, suggest removing audio (
```
ac_none
```
)

裁剪：

开始和结束时间，或时长
单位是秒还是视频百分比

编码/格式：

输出格式要求（MP4、WebM等）
质量要求（不确定的话使用
```
vc_auto
```
）

音频：

保留还是移除音轨
如果用于自动播放，建议移除音频（
```
ac_none
```
）

Always Recommend

始终建议的配置

Unless user specifies otherwise:

Add
f_auto/q_auto
at the end of transformation URLs (see Quick Start section for exceptions)
Use
```
g_auto
```
for smart cropping when filling dimensions
Consider cost for AI transformations (inform user of transformation credits)

除非用户另有说明：

在转换URL末尾添加
f_auto/q_auto
（例外情况见快速入门章节）
填充尺寸时使用
```
g_auto
```
实现智能裁剪
考虑AI转换的成本（告知用户转换credit消耗）

Quick Reference

快速参考

URL Structure

URL结构

https://res.cloudinary.com/<cloud_name>/<asset_type>/<delivery_type>/<transformations>/<version>/<public_id>.<ext>

Key Rules:

Commas (
```
,
```
) separate parameters within a component
Slashes (
```
/
```
) separate components between transformations
Each component acts on the output of the previous one

https://res.cloudinary.com/<cloud_name>/<asset_type>/<delivery_type>/<transformations>/<version>/<public_id>.<ext>

核心规则：

逗号（
```
,
```
）用于分隔同一个组件内的参数
斜杠（
```
/
```
）用于分隔不同转换之间的组件
每个组件基于前一个组件的输出生效

Parameter Types

参数类型

Action parameters: Perform transformations (one action per component: each action transformation should be separated by a slash) Qualifier parameters: Modify action behavior (in the same component as the action, using commas as separators)

Check the Transformation Reference to determine if a parameter is an action or qualifier.

动作参数：执行转换操作（每个组件仅一个动作：每个动作转换需要用斜杠分隔） 修饰参数：修改动作的行为（和对应动作放在同一个组件内，用逗号分隔）

可查看转换参考文档确认参数是动作类型还是修饰类型。

Core Transformations

核心转换

Resize & Crop

调整大小与裁剪

Dimension value formats:

Whole numbers (e.g.,
```
w_400
```
,
```
h_300
```
) = pixels
Decimal values (e.g.,
```
w_0.5
```
,
```
h_1.0
```
) = percentage of original dimensions (0.5 = 50%, 1.0 = 100%)

Choosing the right crop mode:

Use c_scale
when:

Resizing while maintaining original aspect ratio
Specify only ONE dimension (width OR height)
No cropping needed
The user intentionally wants to stretch or squash an image by changing the aspect ratio

Use c_fill
when:

Must fit exact dimensions (e.g., thumbnail grid, fixed layout)
Okay to crop parts of image
Combine with
```
g_auto
```
for smart cropping, or
```
g_face
```
for portraits

Use c_fit
when:

Image must fit within dimensions without cropping
Okay to have empty space
Maintaining full image content is critical

Use c_pad
when:

Must fit exact dimensions without cropping
Need to fill empty space with background color/blur/AI-generated pixels
Use with
```
b_<color>
```
or
```
b_auto
```
(blurred background) or
```
b_gen_fill
```

Use c_limit
when:

Set maximum dimensions but don't upscale small images
Preserving original quality of small images matters

Use c_thumb
when:

Creating thumbnails (typically avatars)
Use with
```
g_face
```
for face-centered crops

Use c_auto
when:

Cloudinary should intelligently crop to interesting content
Combine with
```
g_auto
```
for best results
Good for dynamic content where focal point varies

Examples:

c_scale,w_400                      # Resize width to 400px, maintain aspect ratio
c_scale,w_0.5                      # Resize to 50% of original width
c_fill,g_auto,h_300,w_400          # Fill 400x300px dimensions, smart crop
c_fit,h_300,w_400                  # Fit within dimensions, no crop
c_pad,b_white,h_300,w_400          # Pad to exact size with white background
c_pad,w_1.0                        # Pad to original width (100%)
c_limit,w_1000                     # Limit max width, no upscale
c_thumb,g_face,h_150,w_150         # Face-centered square thumbnail
c_auto,g_auto,w_800                # Auto crop to interesting area

Important: Always specify a crop mode explicitly. Avoid using both dimensions with

c_scale

(will distort if aspect ratios don't match) - prefer one dimension to maintain aspect ratio.

维度值格式：

整数（例如
```
w_400
```
、
```
h_300
```
）= 像素值
小数（例如
```
w_0.5
```
、
```
h_1.0
```
）= 原始尺寸的百分比（0.5 = 50%，1.0 = 100%）

选择合适的裁剪模式：

使用**

c_scale

**的场景：

调整大小同时保持原始宽高比
仅指定一个维度（宽度 OR 高度）
无需裁剪
用户明确希望通过修改宽高比拉伸或压缩图片

使用**

c_fill

**的场景：

必须适配精确尺寸（例如缩略图网格、固定布局）
可以接受裁剪图片的部分内容
搭配
```
g_auto
```
实现智能裁剪，或搭配
```
g_face
```
用于人像场景

使用**

c_fit

**的场景：

图片必须适配尺寸且不裁剪
可以接受留白
保留完整图片内容是核心需求

使用**

c_pad

**的场景：

必须适配精确尺寸且不裁剪
需要用背景色/模糊/AI生成像素填充留白
搭配
```
b_<color>
```
、
```
b_auto
```
（模糊背景）或
```
b_gen_fill
```
使用

使用**

c_limit

**的场景：

设置最大尺寸但不对小图片进行放大
保留小图片的原始质量非常重要

使用**

c_thumb

**的场景：

创建缩略图（通常是头像）
搭配
```
g_face
```
实现人脸居中裁剪

使用**

c_auto

**的场景：

需要Cloudinary智能裁剪出有趣的内容
搭配
```
g_auto
```
使用效果最佳
适用于焦点不固定的动态内容

示例：

c_scale,w_400                      # 宽度调整为400px，保持宽高比
c_scale,w_0.5                      # 调整为原始宽度的50%
c_fill,g_auto,h_300,w_400          # 填充400x300px尺寸，智能裁剪
c_fit,h_300,w_400                  # 适配尺寸，不裁剪
c_pad,b_white,h_300,w_400          # 用白色背景填充到精确尺寸
c_pad,w_1.0                        # 填充到原始宽度（100%）
c_limit,w_1000                     # 限制最大宽度，不放大
c_thumb,g_face,h_150,w_150         # 人脸居中的正方形缩略图
c_auto,g_auto,w_800                # 自动裁剪到感兴趣的区域

重要提示： 始终明确指定裁剪模式。避免给

c_scale

同时指定两个维度（如果宽高比不匹配会导致变形）——优先指定一个维度来保持宽高比。

Gravity (Focal Point)

重力参数（焦点）

Gravity determines which part of the image to focus on when cropping:

g_auto
- Smart detection (recommended for varied content; detects faces, objects, contrast)
g_face
- Face detection (portraits, avatars)
g_center
- Center position (centered subjects, logos)
g_north
,
g_south_east
, etc. - Compass positions (fixed locations, overlay positioning)
x_N,y_N
- Custom offsets (integers = pixels, floats = percentage: 0.8 = 80%)

Examples:

c_fill,g_auto,w_400,h_300                      # Smart crop
c_thumb,g_face,w_200,h_200                     # Face-centered
l_logo/fl_layer_apply,g_south_east,x_10,y_10  # Logo bottom-right

Important:

```
g_auto
```
only works with
```
c_fill
```
,
```
c_lfill
```
,
```
c_crop
```
,
```
c_thumb
```
,
```
c_auto
```
When using x, y, h, w together, use all integers OR all floats (don't mix)

重力参数决定裁剪时图片的焦点区域：

g_auto
- 智能检测（推荐用于内容多样的场景；可检测人脸、物体、对比度）
g_face
- 人脸检测（人像、头像场景）
g_center
- 居中位置（居中主体、Logo场景）
g_north
、
g_south_east
等 - 方位位置（固定位置、叠加层定位）
x_N,y_N
- 自定义偏移（整数=像素，小数=百分比：0.8 = 80%）

示例：

c_fill,g_auto,w_400,h_300                      # 智能裁剪
c_thumb,g_face,w_200,h_200                     # 人脸居中
l_logo/fl_layer_apply,g_south_east,x_10,y_10  # Logo放在右下角

重要提示：

```
g_auto
```
仅支持
```
c_fill
```
、
```
c_lfill
```
、
```
c_crop
```
、
```
c_thumb
```
、
```
c_auto
```
裁剪模式
同时使用x、y、h、w时，要么全部用整数要么全部用小数（不要混合使用）

Format & Quality

格式与质量

Recommended defaults:

f_auto/q_auto
- Use for most production images (WebP to supported browsers, optimized file size)

Specific formats (when requirements dictate):

f_png
- Transparency needed (e.g., after background removal)
f_jpg
- Force JPEG (remove transparency)
q_N
- Manual quality 1-100 (e.g.,
```
q_60
```
for thumbnails,
```
q_90
```
for hero images)
dpr_auto
- Retina displays (Chromium-only, requires Client Hints - see limitations below)

Examples:

f_auto/q_auto           # Recommended default
f_png/q_auto            # PNG with transparency
q_80                    # Manual 80% quality

Best Practice: Use

to separate format and quality as distinct components.

推荐默认配置：

f_auto/q_auto
- 适用于大多数生产环境图片（给支持的浏览器返回WebP格式，优化文件大小）

特定格式（有明确要求时使用）：

f_png
- 需要透明度的场景（例如背景移除后）
f_jpg
- 强制输出JPEG（移除透明度）
q_N
- 手动设置1-100的质量（例如缩略图用
```
q_60
```
，首屏大图用
```
q_90
```
）
dpr_auto
- 适配视网膜屏幕（仅支持Chromium内核，需要Client Hints支持——见下方限制）

示例：

f_auto/q_auto           # 推荐默认配置
f_png/q_auto            # 带透明度的PNG
q_80                    # 手动设置80%质量

最佳实践： 用

将格式和质量作为独立组件分隔开。

Responsive Images (

dpr_auto

w_auto

)

响应式图片（

dpr_auto

、

w_auto

）

dpr_auto
- Automatically adapts to device pixel ratio (Retina displays)

Chromium-only (Chrome, Edge, Opera, Samsung Internet)
Requires Client Hints configuration
Falls back to
```
dpr_1.0
```
on other browsers
Does NOT work inside named transformations

Alternative for universal support: Use explicit

dpr_2.0

<img srcset>

with 1x/2x variants

For Client Hints configuration, browser compatibility, responsive breakpoints, and framework integration, see references/responsive-images.md

dpr_auto
- 自动适配设备像素比（视网膜屏幕）

仅支持Chromium内核（Chrome、Edge、Opera、三星互联网）
需要配置Client Hints
其他浏览器自动降级为
```
dpr_1.0
```
不支持在命名转换内部使用

全浏览器兼容的替代方案： 显式指定

dpr_2.0

，或使用

<img srcset>

提供1x/2x变体

Client Hints配置、浏览器兼容性、响应式断点和框架集成相关内容，查看references/responsive-images.md

Effects

特效

Common effects:

e_grayscale
- Black and white (artistic, accessibility)
e_sepia
- Vintage/nostalgic feel
e_blur:N
- Blur (privacy, placeholders; N typically 300-2000)
e_sharpen
- Enhance clarity (useful after resizing)
e_cartoonify
- Illustrated style
co_rgb:RRGGBB,e_colorize:N
- Color tint (N = intensity 0-100, for brand theming)
e_background_removal
- See AI Transformations section

Examples:

e_blur:800                       # Blur effect
e_sharpen                        # Enhance clarity
co_rgb:0044ff,e_colorize:40      # Blue tint at 40%

Note: Color (

co_

) is a qualifier - use in same component as

e_colorize

常用特效：

e_grayscale
- 黑白效果（艺术风格、无障碍场景）
e_sepia
- 复古怀旧效果
e_blur:N
- 模糊效果（隐私保护、占位图；N通常为300-2000）
e_sharpen
- 增强清晰度（调整大小后使用效果好）
e_cartoonify
- 卡通插画风格
co_rgb:RRGGBB,e_colorize:N
- 色彩 tint（N=0-100的强度，用于品牌主题化）
e_background_removal
- 见AI转换章节

示例：

e_blur:800                       # 模糊效果
e_sharpen                        # 增强清晰度
co_rgb:0044ff,e_colorize:40      # 40%强度的蓝色 tint

注意： 颜色（

co_

）是修饰参数——需要和

e_colorize

放在同一个组件内。

Overlays & Underlays

叠加层与底层

Use for:

l_<public_id>
- Image overlays (logos, watermarks, badges)
u_<public_id>
- Image underlays (custom backgrounds behind transparent subjects)
l_text:font_size:text
- Text overlays (labels, social cards, dynamic text)

Pattern:

Declare:

l_<public_id>

u_<public_id>

l_text:Arial_40:Hello%20World

Transform (optional): e.g.
```
/c_scale,w_100/
```
or
```
/o_50/
```
(opacity)

Apply:

/fl_layer_apply,g_<position>,x_<offset>,y_<offset>

Critical: Using
fl_relative
for overlay dimensions:

Without
fl_relative
: Dimensions are relative to the overlay's original size
- Example:
```
w_1.0
```
  = 100% of the overlay image's width (not useful for small images)
With
fl_relative
: Dimensions are relative to the base image's size
- Example:
```
w_1.0
```
  = 100% of the base image's width (covers entire width)
- Always use
  fl_relative
  when sizing overlays as a percentage of the base image

Examples:

l_logo/c_scale,w_100/fl_layer_apply,g_north_west,x_10,y_10                # Logo at 100px
l_logo/c_scale,fl_relative,w_0.25/fl_layer_apply,g_north_west,x_10,y_10  # Logo at 25% of image width
l_docs:one_black_pixel/c_scale,fl_relative,h_1.0,w_1.0/o_50/fl_layer_apply # Full-image semi-transparent overlay
co_yellow,l_text:Arial_40:Hello%20World/fl_layer_apply,g_south            # Text overlay
u_background/e_background_removal                                          # Custom background

Important:

Color (
```
co_
```
) is a qualifier — use in the same component as text overlay declaration
Always use
fl_relative
when you want overlay dimensions as a percentage of the base image

适用场景：

l_<public_id>
- 图片叠加层（Logo、水印、徽章）
u_<public_id>
- 图片底层（透明主体背后的自定义背景）
l_text:font_size:text
- 文字叠加层（标签、社交卡片、动态文字）

使用模式：

声明：

l_<public_id>

或

u_<public_id>

或

l_text:Arial_40:Hello%20World

转换（可选）：例如
```
/c_scale,w_100/
```
或
```
/o_50/
```
（透明度）

应用：

/fl_layer_apply,g_<position>,x_<offset>,y_<offset>

关键：叠加层尺寸使用
fl_relative
的区别：

不使用
fl_relative
：尺寸相对于叠加层的原始大小
- 示例：
```
w_1.0
```
  = 叠加层图片宽度的100%（小图片场景不适用）
使用
fl_relative
：尺寸相对于基础图片的大小
- 示例：
```
w_1.0
```
  = 基础图片宽度的100%（覆盖整个宽度）
- 当你需要将叠加层尺寸设置为基础图片的百分比时，始终使用
  fl_relative

示例：

l_logo/c_scale,w_100/fl_layer_apply,g_north_west,x_10,y_10                # Logo尺寸为100px
l_logo/c_scale,fl_relative,w_0.25/fl_layer_apply,g_north_west,x_10,y_10  # Logo尺寸为图片宽度的25%
l_docs:one_black_pixel/c_scale,fl_relative,h_1.0,w_1.0/o_50/fl_layer_apply # 全屏半透明叠加层
co_yellow,l_text:Arial_40:Hello%20World/fl_layer_apply,g_south            # 文字叠加层
u_background/e_background_removal                                          # 自定义背景

重要提示：

颜色（
```
co_
```
）是修饰参数——需要和文字叠加层声明放在同一个组件内
当你需要将叠加层尺寸设置为基础图片的百分比时，始终使用
fl_relative

Borders & Rounding

边框与圆角

r_N
- Rounded corners (N = radius in pixels; for modern UI, cards)
r_max
- Perfect circle (use with square dimensions; avatars, icons)
bo_NNpx_solid_color
- Border (frame images, separate from background)

Examples:

r_20                           # 20px rounded corners
r_max                          # Perfect circle
bo_5px_solid_black             # 5px black border
r_20,bo_5px_solid_rgb:0066ff   # Rounded with border (same component)

Important: For borders that follow rounded corners, use border as qualifier in same component.

r_N
- 圆角（N=像素半径；用于现代UI、卡片场景）
r_max
- 正圆形（搭配正方形尺寸使用；头像、图标场景）
bo_NNpx_solid_color
- 边框（给图片加边框，和背景区分）

示例：

r_20                           # 20px圆角
r_max                          # 正圆形
bo_5px_solid_black             # 5px黑色边框
r_20,bo_5px_solid_rgb:0066ff   # 圆角加边框（同一个组件）

重要提示： 如果需要边框跟随圆角，将边框作为修饰参数放在同一个组件内。

Background Color

背景色

b_color,c_pad
- Fill empty space with solid color (product images, letterboxing)
b_auto,c_pad
- Blurred original as background (elegant alternative to solid)
b_gen_fill,c_pad
- AI-extended background (change aspect ratio without cropping; see AI Transformations for cost)

Examples:

b_lightblue,c_pad,w_1.0         # Light blue background
b_auto,c_pad,ar_16:9            # Blurred background, 16:9
b_gen_fill,c_pad,ar_1:1         # AI-extended to square

Critical: Background (

b_

) is a qualifier - use with pad crop in same component:

b_color,c_pad,w_X

, NOT

/b_color/

b_color,c_pad
- 用纯色填充留白（商品图、信箱模式场景）
b_auto,c_pad
- 用原始图片的模糊效果作为背景（比纯色背景更美观）
b_gen_fill,c_pad
- AI扩展背景（无需裁剪即可修改宽高比；成本相关见AI转换章节）

示例：

b_lightblue,c_pad,w_1.0         # 浅蓝色背景
b_auto,c_pad,ar_16:9            # 模糊背景，16:9宽高比
b_gen_fill,c_pad,ar_1:1         # AI扩展为正方形

关键： 背景（

b_

）是修饰参数——需要和pad裁剪放在同一个组件内使用：

b_color,c_pad,w_X

，而不是

/b_color/

。

Rotation & Flips

旋转与翻转

a_90
,
a_180
,
a_270
- Rotate in 90° increments (correct orientation)
a_N
- Rotate by degrees (e.g.,
```
a_-2
```
to straighten crooked photos)
a_hflip
- Horizontal flip (mirror selfies, directional images)
a_vflip
- Vertical flip (reflections)
a_auto_right
/
a_auto_left
- Auto-rotate based on EXIF orientation

Examples:

a_90                    # Rotate 90° clockwise
a_-2                    # Straighten slight tilt
a_hflip                 # Mirror horizontally
a_auto_right            # Auto-fix from EXIF

a_90
、
a_180
、
a_270
- 90°增量旋转（修正方向）
a_N
- 按度数旋转（例如
```
a_-2
```
用于校正倾斜的照片）
a_hflip
- 水平翻转（镜像自拍、方向图片场景）
a_vflip
- 垂直翻转（倒影效果）
a_auto_right
/
a_auto_left
- 基于EXIF方向自动旋转

示例：

a_90                    # 顺时针旋转90°
a_-2                    # 校正轻微倾斜
a_hflip                 # 水平镜像
a_auto_right            # 基于EXIF自动修正方向

Named Transformations

命名转换

Named transformations (

t_<name>

) save transformation chains for reuse. Suggest for:

Transformations used across multiple assets
Complex transformation chains
Expensive operations (to enable baseline transformations and reduce costs)

Baseline transformations (

bl_<name>

) cache expensive named transformations so they don't need to be regenerated. Use

bl_

instead of

t_

for AI transformations (background removal, generative AI) that will have variations applied. This can reduce costs from 75-230 tx per variation down to 1 tx each after the initial baseline is generated.

Example:

bl_bg_removed/c_scale,w_500

- Uses cached background removal result, only pays for resize (1 tx instead of 75 tx)

Important:

f_auto

dpr_auto

, and

w_auto

don't work inside named transformations - use them directly in URLs:

t_avatar/f_auto/q_auto

For complete details, limitations, and baseline transformation examples, see references/named-transformations.md

命名转换（

t_<name>

）可将转换链保存下来复用。推荐以下场景使用：

多个资源共用的转换规则
复杂的转换链
高成本操作（用于启用基线转换，降低成本）

基线转换（

bl_<name>

）会缓存高成本的命名转换结果，避免重复生成。对于会衍生多个变体的AI转换（背景移除、生成式AI），使用

bl_

替代

t_

。初始基线生成后，每个变体的成本可从75-230 tx降低到1 tx。

示例：

bl_bg_removed/c_scale,w_500

- 使用缓存的背景移除结果，仅需为调整大小付费（1 tx，而非75 tx）

重要提示：

f_auto

、

dpr_auto

和

w_auto

不支持在命名转换内部使用——请直接在URL中使用：

t_avatar/f_auto/q_auto

完整细节、限制和基线转换示例，查看references/named-transformations.md

Generative AI Transformations

生成式AI转换

Proactively suggest these AI transformations when appropriate:

Note: Numbers in parentheses (e.g., 75 tx) indicate additional transformation credits consumed per use. Standard transformations = 1 tx.

e_background_removal
(75 tx) - Remove backgrounds (e-commerce, profiles; combine with
```
f_png
```
or
```
b_color,c_pad
```
)
b_gen_fill
(50 tx) - Extend backgrounds (change aspect ratio without cropping; use with
```
c_pad
```
)
e_gen_background_replace:prompt_<text>
(230 tx) - AI-generated backgrounds (custom environments, seasonal variations; high cost)
e_gen_replace:from_<obj>;to_<new>
(120 tx) - Swap objects (product variations, colors; use
```
;preserve_geometry_true
```
for clothing)
e_gen_remove:prompt_<text>
(50 tx) - Remove objects (clean up distractions)
e_auto_enhance
(100 tx) - Improve quality (fix poor lighting/exposure)
e_upscale
(10-100 tx) - Enlarge without quality loss (low-res to high-res)

Important: AI transformations cost significantly more (50-230 tx vs 1 tx). Inform users of costs and consider baseline transformations (e.g.,

bl_bg_removed/c_scale,w_500

) to avoid re-processing expensive operations - see references/named-transformations.md and references/transformation-costs.md for details.

For complete details, syntax, and powerful combinations, see references/ai-transformations.md

合适的场景下可主动推荐以下AI转换：

注意： 括号中的数字（例如75 tx）表示每次使用额外消耗的转换credit。标准转换为1 tx。

e_background_removal
（75 tx）- 移除背景（电商、个人资料场景；搭配
```
f_png
```
或
```
b_color,c_pad
```
使用）
b_gen_fill
（50 tx）- 扩展背景（无需裁剪即可修改宽高比；搭配
```
c_pad
```
使用）
e_gen_background_replace:prompt_<text>
（230 tx）- AI生成背景（自定义环境、季节变化；成本较高）
e_gen_replace:from_<obj>;to_<new>
（120 tx）- 替换物体（商品变体、颜色；服装场景使用
```
;preserve_geometry_true
```
）
e_gen_remove:prompt_<text>
（50 tx）- 移除物体（清理干扰元素）
e_auto_enhance
（100 tx）- 提升质量（修复不佳的光线/曝光）
e_upscale
（10-100 tx）- 无损放大（低分辨率转高分辨率）

重要提示： AI转换的成本远高于标准转换（50-230 tx vs 1 tx）。请告知用户成本，并考虑使用基线转换（例如

bl_bg_removed/c_scale,w_500

）避免重复处理高成本操作——详情见references/named-transformations.md和references/transformation-costs.md。

完整细节、语法和强大的组合用法，查看references/ai-transformations.md

Video-Specific Transformations

视频专属转换

Critical: Use

f_auto:video

(not just

f_auto

) to ensure video output - plain

f_auto

may return an image thumbnail.

vc_auto
- Automatic codec (recommended; optimal for browser/device)
so_N/eo_M
- Trim (start/end in seconds; create clips, remove intro/outro)
ac_none
- Remove audio (essential for autoplay; reduces file size)
fps_N
- Set frame rate (lower = smaller file; standardize rates)
Video resizing - Same crop modes as images (
```
c_fill
```
,
```
c_scale
```
,
```
c_pad
```
)

Common patterns:

vc_auto/ac_none/f_auto:video/q_auto                      # Autoplay-ready
so_0/du_10/vc_auto/f_auto:video/q_auto                   # First 10 seconds
c_scale,w_720/vc_auto/f_auto:video/q_auto                # Resize to 720p width
c_fill,g_auto,h_720,w_1280/vc_auto/f_auto:video/q_auto  # 720p HD, smart crop

For complete details including codecs, trimming strategies, and video concatenation, see references/video-transformations.md

关键： 使用

f_auto:video

（而非仅

f_auto

）确保输出为视频——仅用

f_auto

可能会返回图片缩略图。

vc_auto
- 自动编码（推荐使用；针对浏览器/设备做最优适配）
so_N/eo_M
- 裁剪（开始/结束时间单位为秒；创建片段、移除片头/片尾）
ac_none
- 移除音频（自动播放场景必备；减小文件大小）
fps_N
- 设置帧率（帧率越低文件越小；统一帧率）
视频调整大小 - 和图片使用相同的裁剪模式（
```
c_fill
```
、
```
c_scale
```
、
```
c_pad
```
）

常用模式：

vc_auto/ac_none/f_auto:video/q_auto                      # 适用于自动播放
so_0/du_10/vc_auto/f_auto:video/q_auto                   # 取前10秒
c_scale,w_720/vc_auto/f_auto:video/q_auto                # 宽度调整为720p
c_fill,g_auto,h_720,w_1280/vc_auto/f_auto:video/q_auto  # 720p HD，智能裁剪

完整细节包括编码、裁剪策略和视频拼接，查看references/video-transformations.md

Variables & Conditionals

变量与条件

Variables reuse values and create templates:

$size_300/c_fill,h_$size,w_$size        # Reuse value
$iw/w_$iw_div_2                         # Half original width (arithmetic)

Conditionals adapt transformations dynamically:

if_w_gt_1000/c_scale,w_1000/if_end                          # Responsive sizing
if_ar_gt_1.0/c_fill,w_800,h_450/if_else/c_fill,w_450,h_800/if_end  # Orientation handling

Key rules:

Variable names: alphanumeric, start with letter, no underscores
Conditionals: Must close with
```
if_end
```
Arithmetic:
```
add
```
,
```
sub
```
,
```
mul
```
,
```
div
```
(left-to-right evaluation)

For complete syntax, arithmetic operations, nested conditionals, and real-world patterns, see references/advanced-features.md

变量可复用值并创建模板：

$size_300/c_fill,h_$size,w_$size        # 复用值
$iw/w_$iw_div_2                         # 原始宽度的一半（算术运算）

条件可动态适配转换规则：

if_w_gt_1000/c_scale,w_1000/if_end                          # 响应式大小调整
if_ar_gt_1.0/c_fill,w_800,h_450/if_else/c_fill,w_450,h_800/if_end  # 适配横竖屏

核心规则：

变量名：字母数字组合，以字母开头，不含下划线
条件：必须以
```
if_end
```
闭合
算术运算：
```
add
```
（加）、
```
sub
```
（减）、
```
mul
```
（乘）、
```
div
```
（除）（从左到右计算）

完整语法、算术运算、嵌套条件和实际场景模式，查看references/advanced-features.md

Self-Validation Checklist

自检清单

Before returning a transformation URL, verify:

✅ URL structure is complete (cloud_name, asset_type
```
/image/
```
or
```
/video/
```
or
```
/raw/
```
, delivery_type, public_id)
✅ Each component has only one action parameter (e.g., one crop mode per component)
✅ Crop mode is explicit (don't rely on defaults; avoid both dimensions with
```
c_scale
```
)
✅ Overlays end with
fl_layer_apply
in separate component
✅ Text strings are URL-encoded (spaces =
```
%20
```
, special chars encoded)
✅ Variable names follow rules (alphanumeric, start with letter, no underscores)
✅ g_auto
compatibility (only works with
```
c_fill
```
,
```
c_lfill
```
,
```
c_crop
```
,
```
c_thumb
```
,
```
c_auto
```
)
✅ Background as qualifier (use with pad crop:
```
b_color,c_pad,w_X
```
, not
```
/b_color/
```
)
✅ Format/quality at end (prefer
```
f_auto/q_auto
```
as final components)

Quick syntax check:

Commas separate parameters within a component:
```
c_fill,g_auto,w_400
```
Slashes separate components:
```
c_fill,w_400/f_auto/q_auto
```
Actions vs qualifiers: Only one action per component, qualifiers modify that action

See references/debugging.md for detailed examples of each check.

返回转换URL前，请确认：

✅ URL结构完整（cloud_name、资源类型
```
/image/
```
/
```
/video/
```
/
```
/raw/
```
、分发类型、public_id）
✅ 每个组件仅包含一个动作参数（例如每个组件仅一个裁剪模式）
✅ 裁剪模式明确（不依赖默认值；避免给
```
c_scale
```
同时指定两个维度）
✅ 叠加层以独立组件
fl_layer_apply
结尾
✅ 字符串已URL编码（空格替换为
```
%20
```
，特殊字符已编码）
✅ 变量名符合规则（字母数字组合，以字母开头，不含下划线）
✅ g_auto
兼容（仅支持
```
c_fill
```
、
```
c_lfill
```
、
```
c_crop
```
、
```
c_thumb
```
、
```
c_auto
```
）
✅ 背景作为修饰参数（搭配pad裁剪使用：
```
b_color,c_pad,w_X
```
，而非
```
/b_color/
```
）
✅ 格式/质量放在末尾（优先将
```
f_auto/q_auto
```
作为最后两个组件）

快速语法检查：

逗号分隔同一个组件内的参数：
```
c_fill,g_auto,w_400
```
斜杠分隔不同组件：
```
c_fill,w_400/f_auto/q_auto
```
动作vs修饰：每个组件仅一个动作，修饰参数用于修改该动作

每个检查的详细示例见references/debugging.md

Debugging Checklist

调试清单

When a transformation isn't working:

Verify URL structure: Check that all required URL parts are present:
- Cloud name:
```
/<cloud_name>/
```
- Asset type:
```
/image/
```
  or
```
/video/
```
  or
```
/raw/
```
- Delivery type:
```
/upload/
```
  or
```
/fetch/
```
  etc.
- Public ID at the end
Check the X-Cld-Error header: Cloudinary reports errors in the
```
X-Cld-Error
```
HTTP response header
Check parameter names against Transformation Reference
Check crop mode: Specify crop mode explicitly; avoid both dimensions with
```
c_scale
```
(causes distortion if aspect ratios don't match)
Verify gravity compatibility:
```
g_auto
```
doesn't work with
```
c_scale
```
,
```
c_fit
```
,
```
c_limit
```
,
```
c_pad
```
Check action vs qualifier: Only one action per component, qualifiers in same component
Verify overlay pattern: Must end with
```
fl_layer_apply
```
component
Check variable names: No underscores, must start with letter
Verify URL encoding: Text overlays need URL-encoded strings (spaces =
```
%20
```
)
Check auto parameters in named transformations:
```
f_auto
```
,
```
dpr_auto
```
, and
```
w_auto
```
don't work inside named transformations - use them directly in URLs
Verify Client Hints for
dpr_auto
/
w_auto
: These only work on Chromium browsers with Client Hints enabled; fallback to
```
dpr_1.0
```
otherwise (see references/responsive-images.md for configuration)
Video returns image instead of video: Use
```
f_auto:video
```
(not just
```
f_auto
```
) for video transformations - plain
```
f_auto
```
may return an image thumbnail

转换无法正常工作时：

验证URL结构：检查所有必填URL部分是否存在：
- Cloud名称：
```
/<cloud_name>/
```
- 资源类型：
```
/image/
```
  、
```
/video/
```
  或
```
/raw/
```
- 分发类型：
```
/upload/
```
  或
```
/fetch/
```
  等
- 末尾的Public ID
检查X-Cld-Error header：Cloudinary会在
```
X-Cld-Error
```
HTTP响应头中返回错误信息
对照转换参考文档检查参数名
检查裁剪模式：显式指定裁剪模式；避免给
```
c_scale
```
同时指定两个维度（宽高比不匹配时会导致变形）
验证重力参数兼容性：
```
g_auto
```
不支持
```
c_scale
```
、
```
c_fit
```
、
```
c_limit
```
、
```
c_pad
```
检查动作vs修饰参数：每个组件仅一个动作，修饰参数放在同一个组件内
验证叠加层模式：必须以
```
fl_layer_apply
```
组件结尾
检查变量名：不含下划线，必须以字母开头
验证URL编码：文字叠加层的字符串需要URL编码（空格替换为
```
%20
```
）
检查命名转换中的自动参数：
```
f_auto
```
、
```
dpr_auto
```
和
```
w_auto
```
不支持在命名转换内部使用——请直接在URL中使用
验证
dpr_auto
/
w_auto
的Client Hints配置：仅在启用Client Hints的Chromium浏览器中生效；其他浏览器降级为
```
dpr_1.0
```
（配置见references/responsive-images.md）
视频返回图片而非视频：视频转换使用
```
f_auto:video
```
（而非仅
```
f_auto
```
）——仅用
```
f_auto
```
可能返回图片缩略图

Checking X-Cld-Error Header

检查X-Cld-Error Header

The

X-Cld-Error

header contains error details when a transformation fails. To check it:

Using browser DevTools:

Open Developer Tools (Network tab)
Request the transformation URL
Look for
```
X-Cld-Error
```
in Response Headers

Using code (fetch the URL):

javascript

fetch('https://res.cloudinary.com/demo/image/upload/w_abc/sample.jpg')
  .then(response => {
    const error = response.headers.get('x-cld-error');
    if (error) {
      console.log('Cloudinary Error:', error);
    }
  });

Common X-Cld-Error messages:

```
Invalid width - abc
```
- Width parameter expects a number
```
Invalid transformation syntax
```
- Malformed transformation string
```
Resource not found
```
- Asset doesn't exist or public ID is incorrect
```
Transformation limit exceeded
```
- Account transformation quota reached

Online tool: Use the X-Cld-Error Inspector to check any Cloudinary URL

For more details, see Error Handling

转换失败时，

X-Cld-Error

header包含错误详情。检查方法：

使用浏览器开发者工具：

打开开发者工具（网络面板）
请求转换URL
在响应头中查找
```
X-Cld-Error
```

使用代码（请求URL）：

javascript

fetch('https://res.cloudinary.com/demo/image/upload/w_abc/sample.jpg')
  .then(response => {
    const error = response.headers.get('x-cld-error');
    if (error) {
      console.log('Cloudinary Error:', error);
    }
  });

常见X-Cld-Error消息：

```
Invalid width - abc
```
- 宽度参数需要数字
```
Invalid transformation syntax
```
- 转换字符串格式错误
```
Resource not found
```
- 资源不存在或Public ID错误
```
Transformation limit exceeded
```
- 账号转换配额已用完

在线工具： 使用X-Cld-Error检查器检查任意Cloudinary URL

更多详情见错误处理

Transformation Costs

转换成本

Important: Warn users about high-cost transformations before generating URLs. AI effects cost significantly more than standard transformations (50-230 tx vs 1 tx).

For complete cost details and cost reduction strategies, see references/transformation-costs.md

重要提示： 生成URL前请告知用户高成本转换的费用。AI特效的成本远高于标准转换（50-230 tx vs 1 tx）。

完整成本细节和降本策略，查看references/transformation-costs.md

Additional Resources

额外资源

Skill References (Progressive Disclosure)

Skill参考（渐进式披露）

references/debugging.md - Use when transformations return errors or unexpected results
references/ai-transformations.md - Use when you need AI transformation prompt syntax, cost details, or complex AI combinations
references/video-transformations.md - Use when working with video codecs, trimming strategies, or concatenation
references/advanced-features.md - Use when building complex logic with variables, conditionals, or arithmetic
references/responsive-images.md - Use when implementing responsive images, configuring Client Hints, or using dpr_auto/w_auto
references/transformation-costs.md - Use when optimizing for cost or explaining cost implications to users
references/named-transformations.md - Use when creating reusable transformations or reducing costs for repeated operations
references/examples.md - Use when you need real-world examples beyond the Quick Start (social cards, e-commerce, responsive images)

references/debugging.md - 转换返回错误或结果不符合预期时使用
references/ai-transformations.md - 需要AI转换提示词语法、成本细节或复杂AI组合时使用
references/video-transformations.md - 处理视频编码、裁剪策略或拼接时使用
references/advanced-features.md - 构建包含变量、条件或算术运算的复杂逻辑时使用
references/responsive-images.md - 实现响应式图片、配置Client Hints或使用dpr_auto/w_auto时使用
references/transformation-costs.md - 优化成本或向用户说明成本影响时使用
references/named-transformations.md - 创建可复用转换或降低重复操作成本时使用
references/examples.md - 需要快速入门之外的实际场景示例时使用（社交卡片、电商、响应式图片）

Core Cloudinary Documentation

Cloudinary核心文档

Transformation Reference - All parameters

转换参考 - 所有参数说明

Image Transformations

图片转换

Video Transformations

视频转换

Common Mistakes & Best Practices

常见错误与最佳实践

Avoid:

❌
```
w_400,h_300
```
→ ✅
```
c_scale,w_400
```
(both dimensions with c_scale distorts image; prefer one dimension)
❌
```
c_scale,g_auto,w_400
```
→ ✅
```
c_fill,g_auto,w_400
```
(g_auto doesn't work with c_scale)

❌

l_logo/fl_layer_apply,g_north_west

→ ✅

l_logo/c_scale,w_100/fl_layer_apply,g_north_west

❌

b_lightblue/e_trim

→ ✅

b_lightblue,c_pad,w_1.0/e_trim

(background as qualifier)

Always:

Prefer
```
f_auto/q_auto
```
in separate components over
```
f_auto,q_auto
```
Use
```
g_auto
```
for smart cropping unless specific focal point needed
Specify crop mode with width/height; prefer one dimension with
```
c_scale
```
Never guess parameter names - verify against documentation

避免：

❌
```
w_400,h_300
```
→ ✅
```
c_scale,w_400
```
（给c_scale同时指定两个维度会导致图片变形；优先指定一个维度）
❌
```
c_scale,g_auto,w_400
```
→ ✅
```
c_fill,g_auto,w_400
```
（g_auto不支持c_scale）

❌

l_logo/fl_layer_apply,g_north_west

→ ✅

l_logo/c_scale,w_100/fl_layer_apply,g_north_west

❌

b_lightblue/e_trim

→ ✅

b_lightblue,c_pad,w_1.0/e_trim

（背景作为修饰参数使用）

始终遵循：

优先将
```
f_auto/q_auto
```
作为独立组件使用，而非
```
f_auto,q_auto
```
除非需要特定焦点，否则使用
```
g_auto
```
实现智能裁剪
指定宽高时明确裁剪模式；
```
c_scale
```
优先仅指定一个维度
不要猜测参数名——对照文档确认

cloudinary-transformations

Original

Translation

Cloudinary Transformation Rules

Cloudinary 转换规则

When to Use

使用场景

Quick Start

快速入门

Default Best Practice: Always Optimize

默认最佳实践：始终优化

Gathering Requirements

需求收集

For Resize/Crop Requests

调整大小/裁剪请求

For AI Transformation Requests

AI转换请求

For Video Transformation Requests

视频转换请求

Always Recommend

始终建议的配置

Quick Reference

快速参考

URL Structure

URL结构

Parameter Types

参数类型

Core Transformations

核心转换

Resize & Crop

调整大小与裁剪

Gravity (Focal Point)

重力参数（焦点）

Format & Quality

格式与质量

Responsive Images (dpr_auto, w_auto)

响应式图片（dpr_auto、w_auto）

Effects

特效

Overlays & Underlays

叠加层与底层

Borders & Rounding

边框与圆角

Background Color

背景色

Rotation & Flips

旋转与翻转

Named Transformations

命名转换

Generative AI Transformations

生成式AI转换

Video-Specific Transformations

视频专属转换

Variables & Conditionals

变量与条件

Self-Validation Checklist

自检清单

Debugging Checklist

调试清单

Checking X-Cld-Error Header

检查X-Cld-Error Header

Transformation Costs

转换成本

Additional Resources

额外资源

Skill References (Progressive Disclosure)

Skill参考（渐进式披露）

Core Cloudinary Documentation

Cloudinary核心文档

Image Transformations

图片转换

Video Transformations

视频转换

Common Mistakes & Best Practices

常见错误与最佳实践

Responsive Images (
`dpr_auto`
,
`w_auto`
)

响应式图片（
`dpr_auto`
、
`w_auto`
）