本技能用于根据自然语言指令创建和调试 Cloudinary 转换 URL,适用于构建 Cloudinary 交付/转换 URL、将自然语言请求转换为转换语法、调试不工作的转换 URL、用 Cloudinary 优化图片或视频,以及应用特效、叠加、缩放或裁剪等场景。
默认最佳实践:大多数转换 URL 末尾追加 f_auto/q_auto,自动交付最优格式并优化质量,减少带宽。例外包括账户已启用 Optimize By Default、需要特殊质量(如 q_auto:best、q_auto:low、q_N)、需要特定格式或交付未经修改的原图。
常用转换示例(含优化):缩放 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。技能说明其中值为示例,应根据实际需求选择具体值。调试细节参见 references/debugging.md。
生成转换 URL 前,若未明确,需按请求类型澄清需求。缩放/裁剪需至少一个维度;若同时指定宽高,需明确裁剪行为(fill、pad、scale、limit 等),并澄清焦点/重力、是否保持宽高比。AI 转换需澄清输出格式、目标尺寸或比例、替换/移除对象、背景描述、是否需要可复现(seed)等。视频转换需澄清裁剪起止时间或时长、编解码/格式、音频保留与否。
除非另有说明,推荐在转换 URL 末尾加 f_auto/q_auto;填充尺寸时使用 g_auto 智能裁剪;并考虑 AI 转换的费用。
URL 结构为 https://res.cloudinary.com/<cloud_name>/<asset_type>/<delivery_type>/<transformations>/<version>/<public_id>.<ext>。逗号在同一组件内分隔参数,斜杠分隔组件,每个组件作用于前一组件输出。参数分为动作参数(执行转换,每个组件一个动作)与限定参数(修改动作行为,与动作同组件,逗号分隔)。
缩放与裁剪:维度可用整数(像素)或小数(原始尺寸百分比,如 0.5=50%)。裁剪模式:c_scale 保持比例缩放(只指定一个维度);c_fill 填满精确尺寸(可裁剪,配 g_auto 或 g_face);c_fit 适应尺寸不裁剪;c_pad 适应尺寸不裁剪并填充背景色/模糊/生成像素(配 b_ 或 b_auto、b_blurred、b_gen_fill);c_limit 限制最大尺寸不放大;c_thumb 缩略图(头像,配 g_face);c_auto 智能裁剪(配 g_auto)。应始终显式指定裁剪模式,避免 c_scale 同时用两个维度导致变形。
重力:g_auto 智能检测;g_face 人脸检测;g_center 居中;g_north、g_south_east 等罗盘位置;x_N,y_N 自定义偏移(整数像素,浮点百分比)。g_auto 仅适用于 c_fill、c_lfill、c_crop、c_thumb、c_auto。x、y、h、w 同时使用时须全整数或全浮点。
格式与质量:推荐 f_auto/q_auto;需要透明用 f_png;强制 JPEG 用 f_jpg;q_N 手动质量;dpr_auto 适配 Retina(仅 Chromium,需 Client Hints,其他浏览器回退 dpr_1.0,且不支持命名转换)。响应式与框架集成参见 references/responsive-images.md。
特效:e_grayscale、e_sepia、e_blur:N、e_sharpen、e_cartoonify、co_rgb:RRGGBB,e_colorize:N(颜色为限定参数,与 e_colorize 同组件)。
叠加与下层:l_<public_id> 图片叠加、u_<public_id> 图片下层、l_text:font_size:text 文字叠加。模式为声明、可选转换、以 /fl_layer_apply,g_<position>,x_<offset>,y_<offset> 应用。以百分比设置叠加尺寸须用 fl_relative。颜色 co_ 为限定参数,与文字叠加声明同组件。并排/画布扩展可将叠加偏移到基础图边缘外,画布自动扩展。
边框与圆角:r_N 圆角、r_max 圆形、bo_NNpx_solid_color 边框,圆角边框须作为限定参数与同组件使用。
背景色:b_color,c_pad、b_auto,c_pad(自动选主色调)、b_gen_fill,c_pad(AI 扩展,见费用)、b_blurred,c_pad(仅视频)。背景 b_ 为限定参数,须与 pad 同组件。
旋转与翻转:a_90/180/270、a_N、a_hflip、a_vflip、a_auto_right/a_auto_left。
资源类型差异:许多参数仅适用于图片或视频,应用错误类型可能静默失败(返回 200 但输出错误),应验证实际输出。常见视频专属:fl_splice、du_/so_/eo_、fps_、vc_/ac_、e_boomerang、e_progressbar 等(约 35 个参数为视频专属)。不确定时应查阅转换参考。
命名转换:t_<name> 保存转换链以复用,适用于跨多资源、复杂链或昂贵操作。基线转换 bl_<name> 缓存昂贵的命名转换,AI 转换变体可将费用从每次 75-230 tx 降至初始生成后每次 1 tx。示例 bl_bg_removed/c_scale,w_500。f_auto、dpr_auto、w_auto 不支持命名转换内部,应直接写在 URL 中。详见 references/named-transformations.md。
生成式 AI 转换及转换点数消耗: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)。AI 转换费用显著高于标准转换(1 tx),应告知用户费用并考虑使用基线转换避免重复处理。