用自然语言构建和调试 Cloudinary 图片/视频变换…

在生成或排查 Cloudinary 交付/变换 URL（缩放裁剪、叠加、AI 特效、视频处理）时，按规则拼装参数并自检。

适用场景

解决思路

1. 默认在几乎每个变换 URL 末尾加上 `f_auto/q_auto` 作为最后两个组件，自动选择最优格式并优化质量；例外：账号已开启 Optimize By Default、有特殊质量要求（改用 `q_auto:best`、`q_auto:low` 或手动 `q_N`）、需要指定格式（用 `f_png`、`f_jpg` 等替换 `f_auto`）、或原样交付不做修改。
2. 生成前先澄清需求：缩放/裁剪需至少一个维度（宽或高），若同时给两个维度需确定裁剪模式；确认焦点/gravity（人脸、中心、智能自动）、是否保持宽高比。
3. AI 变换需澄清：背景移除的输出格式（PNG 透明还是 JPG 实底）及透明区域处理方式；生成式填充的目标尺寸/比例；生成式替换的 from/to 对象及是否保留原形状；生成式移除要移除哪些对象、是否全部实例；生成式背景替换的背景描述及是否需要可复现（seed）。
4. 视频变换需澄清：裁剪的起止时间或时长（秒或百分比）、输出格式与质量（不确定用 `vc_auto`）、是否保留音轨（自动播放建议 `ac_none`）。
5. 按 URL 结构拼装：`https://res.cloudinary.com/<cloud_name>/<asset_type>/<delivery_type>/<transformations>/<version>/<public_id>.<ext>`；逗号分隔同一组件内的参数，斜杠分隔不同变换组件，每个组件作用于前一个组件的输出。
6. 区分 action 参数（执行变换，每个组件只能有一个，用斜杠分隔）与 qualifier 参数（修饰 action，与 action 同组件用逗号分隔），不确定时查 Transformation Reference。
7. 维度值：整数为像素（`w_400`），小数为原图百分比（`w_0.5` = 50%）。
8. 按场景选择裁剪模式：保持比例只给一个维度用 `c_scale`；需精确尺寸且可裁剪用 `c_fill`（配 `g_auto` 或 `g_face`）；需完整内容不裁剪用 `c_fit`；需精确尺寸且填充空白用 `c_pad`（配 `b_<color>`、`b_auto`、`b_blurred`（仅视频）或 `b_gen_fill`）；限制最大尺寸且不放大小图用 `c_limit`；做缩略图/头像用 `c_thumb`（配 `g_face`）；让 Cloudinary 智能裁剪用 `c_auto`（配 `g_auto`）。
9. 始终显式指定裁剪模式；避免 `c_scale` 同时给宽高（比例不符会变形），优先只给一个维度。
10. Gravity 选择：`g_auto` 智能检测（多变内容推荐）、`g_face` 人脸、`g_center` 中心、`g_north`/`g_south_east` 等罗盘位置、`x_N,y_N` 自定义偏移（整数为像素，小数为百分比如 0.8=80%）。
11. 注意 `g_auto` 只适用于 `c_fill`、`c_lfill`、`c_crop`、`c_thumb`、`c_auto`；x、y、h、w 同时使用时必须全为整数或全为小数，不可混用。
12. 格式与质量：生产图片默认 `f_auto/q_auto`；需透明用 `f_png`；强制 JPEG 用 `f_jpg`；手动质量用 `q_N`（1-100，缩略图 `q_60`、主图 `q_90`）；Retina 用 `dpr_auto`（仅 Chromium 且需 Client Hints，其他浏览器回退 `dpr_1.0`，且不能在命名变换内使用）。格式与质量用 `/` 分隔为独立组件。
13. 常用特效：`e_grayscale` 黑白、`e_sepia` 复古、`e_blur:N` 模糊（N 通常 300-2000）、`e_sharpen` 锐化、`e_cartoonify` 卡通化、`co_rgb:RRGGBB,e_colorize:N` 着色（N 为 0-100 强度，颜色 `co_` 是 qualifier，须与 `e_colorize` 同组件）。
14. 叠加/底衬：用 `l_<public_id>` 图片叠加、`u_<public_id>` 图片底衬、`l_text:font_size:text` 文字叠加；模式为先声明、再可选变换（如 `/c_scale,w_100/` 或 `/o_50/`）、最后 `/fl_layer_apply,g_<position>,x_<offset>,y_<offset>`。
15. 叠加尺寸按基础图百分比时必须加 `fl_relative`：不加时尺寸相对叠加图自身原始大小，加了才相对基础图大小（如 `w_1.0` = 基础图 100% 宽）。
16. 并排/扩展画布：把叠加层偏移到基础图边缘之外，画布会自动扩展——水平用 `g_west,x_<base_width>`，垂直用 `g_north,y_<base_height>`。
17. 边框与圆角：`r_N` 圆角像素、`r_max` 正圆（配方形尺寸）、`bo_NNpx_solid_color` 边框；边框要跟随圆角时须作为 qualifier 与圆角同组件（如 `r_20,bo_5px_solid_rgb:0066ff`）。
18. 背景色：`b_color,c_pad` 纯色填充、`b_auto,c_pad` 自动取主色、`b_gen_fill,c_pad` AI 扩展背景、`b_blurred,c_pad` 模糊背景（仅视频）；背景 `b_` 是 qualifier，必须与 pad 裁剪同组件（`b_color,c_pad,w_X`），不能写成 `/b_color/`。
19. 旋转与翻转：`a_90`/`a_180`/`a_270` 直角旋转、`a_N` 任意角度（如 `a_-2` 校正倾斜）、`a_hflip` 水平镜像、`a_vflip` 垂直翻转、`a_auto_right`/`a_auto_left` 按 EXIF 自动旋转。
20. 注意资源类型：许多参数只对图片或只对视频有效，用错会静默失败（仍返回 200 且无 X-Cld-Error，只是输出错误）；视频专属如 `fl_splice`、`du_`/`so_`/`eo_`、`fps_`、`vc_`/`ac_`、`e_boomerang`、`e_progressbar`；不确定时查 Transformation Reference 并验证实际输出（尺寸、时长、帧数）。
21. 命名变换 `t_<name>` 用于跨资源复用、复杂链、昂贵操作；基线变换 `bl_<name>` 缓存昂贵的命名变换（AI 变换加变体时用 `bl_` 替代 `t_`，可把每次变体 75-230 tx 降到 1 tx，如 `bl_bg_removed/c_scale,w_500`）；注意 `f_auto`、`dpr_auto`、`w_auto` 不能在命名变换内使用，须直接写在 URL 中（如 `t_avatar/f_auto/q_auto`）。
22. AI 变换按需主动建议并告知成本（标准变换 1 tx）：`e_background_removal`（75 tx）、`b_gen_fill`（50 tx）、`e_gen_background_replace:prompt_<text>`（230 tx）、`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）；用基线变换避免重复处理昂贵操作。
23. 视频变换：必须用 `f_auto:video`（而非 `f_auto`，否则可能返回图片缩略图）；`vc_auto` 自动编码、`so_N/eo_M` 裁剪起止秒、`ac_none` 去音轨（自动播放必备）、`fps_N` 设帧率；视频缩放与图片相同的裁剪模式。
24. 变量与条件：变量如 `$size_300/c_fill,h_$size,w_$size`、`$iw/w_$iw_div_2`（算术 add/sub/mul/div，从左到右求值）；条件如 `if_w_gt_1000/c_scale,w_1000/if_end`、`if_ar_gt_1.0/.../if_else/.../if_end`；变量名须字母数字、以字母开头、不含下划线；条件必须以 `if_end` 结束。
25. 返回 URL 前自检：URL 结构完整（cloud_name、asset_type、delivery_type、public_id）；每个组件只有一个 action 参数；裁剪模式显式；叠加以 `fl_layer_apply` 独立组件结尾；文本 URL 编码（空格 `%20`）；变量名合规；`g_auto` 兼容性；背景作为 qualifier 与 pad 同组件；格式/质量放末尾；参数与资源类型匹配；参数名真实存在（对照 Transformation Reference）。
26. 调试时：检查 URL 结构各部分；查看 `X-Cld-Error` 响应头（浏览器 DevTools Network 面板或 fetch 读取 `response.headers.get('x-cld-error')`）；核对参数名；检查裁剪模式；验证 gravity 兼容性（`g_auto` 不适用于 `c_scale`、`c_fit`、`c_limit`、`c_pad`）；检查 action/qualifier 用法；验证叠加模式；检查变量名；验证 URL 编码；检查命名变换中的 auto 参数；验证 `dpr_auto`/`w_auto` 的 Client Hints；视频返回图片时改用 `f_auto:video`。
27. 常见错误修正：`w_400,h_300` → `c_scale,w_400`；`c_scale,g_auto,w_400` → `c_fill,g_auto,w_400`；`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`。
28. 始终优先把 `f_auto/q_auto` 写成独立组件而非 `f_auto,q_auto`；智能裁剪用 `g_auto`；给宽高时显式指定裁剪模式且 `c_scale` 优先只给一个维度；绝不臆造参数名，须对照文档验证。

适用边界 · 注意事项

• 账号未使用 Cloudinary 或没有 Cloudinary 账号/云名（cloud_name）时无法使用。
• 需要不依赖云厂商、纯本地或自建图片处理管线时。
• 不想承担 AI 变换的高额 transformation credits（50-230 tx）成本时，应避免或改用基线变换。