transformation-builder

转换构建器技能

了解工具的工作方式，编写精确的查询，正确排列多步骤链，然后调用 transformation_builder。

这个工具的实际工作方式（请先阅读）

transformation_builder 不是功能选择器。它只有以下输入：

transformation_builder(query, src?, previous_errors?)

• query — 对所需转换的自然语言描述。
• src — 可选的 ImageKit 托管源 URL（默认为示例图片）。
• previous_errors — 如果之前的调用失败，请传入错误文本，以便工具进行自我修正。

工具内部会：(1) 使用你的 query 搜索 ImageKit 文档；(2) 由 LLM 将其转换为经过验证的转换步骤列表；(3) 由 SDK 构建最终 URL。没有 capability 参数——下面的参数名称是应写入查询的词汇，而不是你可以直接设置的 API 字段。由于第 1 步会根据查询文本搜索文档，**在查询中使用正确的 ImageKit 参数名称和值，能显著提升结果质量。**使用错误或杜撰的名称会让搜索偏离方向。

因此，你需要将用户模糊的请求转换为精确的查询，并引用下方参考部分中的真实参数和值。

适用场景（此技能的触发条件）

• 调整尺寸、裁剪或聚焦某个区域
• 滤镜、特效、叠加层（图片／文本／视频）、水印
• 多步骤转换链
• 移除或替换背景，或生成式填充
• 任何 AI 图像编辑（更改物体／颜色／风格、提升分辨率、修饰、添加投影、生成变体）

调用 transformation_builder

• query：经过精确改写的描述（请参阅“编写查询”）。切勿原样传入用户的模糊措辞。
• src：用户提供了 ImageKit 交付 URL 时，传入要转换的 URL。必须由 ImageKit 托管。
• 将多步骤请求构造成一个查询，并按顺序描述这些步骤：
  • 用户：“1）调整为 800x600 2）裁剪到人脸”
  • 查询：“将宽度调整为 800、高度调整为 600，然后裁剪并聚焦于人脸”

编写查询

规则：将模糊请求改写为包含真实参数和值的描述。知道时使用准确的参数名称／值；不确定时再使用普通英语描述。

用户说	较弱的查询	合适的查询
“把红球变成绿色”	“把红球变绿”	“使用提示词应用 ai_edit：将红球改为绿色”
“清理一下，并把背景换成白色”	“清理、白色背景”	“先应用 ai_retouch，然后应用 ai_remove_background，并将背景颜色设为白色”
“让它看起来像一幅画”	“绘画风格”	“使用提示词应用 ai_edit：油画风格，并带有明显的笔触”
“围绕人脸裁剪”	“裁剪人脸”	“使用 focus=face 调整尺寸，以便围绕检测到的人脸进行裁剪”
“在底部添加文本‘Hello’”	“添加 hello 文本”	“添加文本叠加层，文本为 ‘Hello’，位置设在底部（focus=bottom）”
“适配移动端横幅”	“移动端横幅”	“将 width 调整为 640，并将 aspect_ratio 设为 2-1”
“宽 300px，带红色边框”	“调整尺寸并加边框”	“将 width 调整为 300，然后添加宽度为 5、颜色为红色的 border”
“提高分辨率，现在很模糊”	“修复画质”	“先应用 ai_upscale，然后应用 ai_retouch”
“移除背景并添加投影”	“移除背景 投影”	“先应用 ai_remove_background，然后应用 ai_drop_shadow”
“加宽，但不要拉伸”	“加宽”	“使用带填充的裁剪（crop_mode=pad_extract），将画布水平扩展，并将 background 设为 genfill，让 AI 填充新增区域”

意图 → 实际参数／术语

使用此内容将意图转换为查询中应使用的正确术语。这些是工具实际验证的参数名称。

用户意图	使用的术语	备注
修改特定对象／区域（“放大猫咪”“添加太阳镜”“把它变成一幅画”）	ai_edit（基于提示词）	由文本提示词驱动的 AI 内容编辑
替换整个背景场景（“把他们放到海滩上”）	ai_change_background（基于提示词）	保留主体，生成新场景。不适用于单纯移除背景或更改颜色
移除背景 → 透明	ai_remove_background	ImageKit 原生功能。使用外部 remove.bg 引擎时，请使用 ai_remove_background_external
扩展／外绘画布（“添加更多天空”“改成全景”）	带填充的裁剪 + background=genfill	生成式填充位于 background 参数中，并非独立的 AI 字段。不接受提示词
提高分辨率／修复低分辨率图像	ai_upscale	布尔值；无参数
清理／移除瑕疵	ai_retouch	布尔值；无参数
为抠出的主体添加逼真阴影	ai_drop_shadow	仅适用于透明图像。可选参数：azimuth、elevation、strength
生成不同版本／混编	ai_variation	布尔值；保留结构
调整大小／宽高比／裁剪	width、height、aspect_ratio、crop、crop_mode	请参阅“调整大小与裁剪”表格
智能裁剪至人脸／对象	focus（auto、face 或对象名称）+ 可选的 zoom	对象名称为 COCO 类别（person、car、dog，等等）
对所有像素统一替换一种颜色（“将所有红色替换为蓝色”）	color_replace	全局像素颜色替换，可设置 tolerance
滤镜／调整（黑白、模糊、锐化、旋转、边框、圆角）	grayscale、blur、sharpen、rotation、border、radius，等等	请参阅“效果”表格
叠加徽标／水印图像	文本／图像叠加	统一使用 overlay 概念，按类型区分（请参阅“叠加层”）
在图像上写文字	带 text 的文本叠加	请参阅“叠加层”

此工具不包含“从零开始生成图像”步骤——它始终会转换现有的 src。若要从零开始生成图像，请使用 ImageKit DAM（Digital Asset Manager）中的文生图功能；这是独立于 transformation_builder 的功能。

关键区别：ai_edit 与 color_replace 与 ai_change_background

1. 更改特定对象／区域（“把球变大”“把汽车变成红色”）→ ai_edit
2. 对所有像素统一替换一种颜色（“将所有红色替换为蓝色”）→ color_replace
3. 替换整个背景场景（“把他们放到海滩上”）→ ai_change_background

多步链的顺序

当请求涉及多个操作时，请按以下顺序在一个查询中串联这些操作：

1. 放大／修饰（优先处理质量）
2. AI 内容编辑（ai_edit）
3. 移除／替换背景（ai_remove_background、ai_change_background）
4. 调整大小／裁剪（最终尺寸）
5. 效果／叠加层（最后润色）

重要：背景移除必须在放大／修饰之后，绝不能在之前。 正确：ai_upscale → ai_remove_background。错误：ai_remove_background → ai_upscale。

示例——“清理这张照片，移除背景，并调整为 500x500”： → 查询：“依次应用 ai_retouch、ai_remove_background，然后将 width 调整为 500、height 调整为 500”。

移除背景：明确意图

• 如果用户含糊地说“移除背景”，请询问他们想要：
  1. 实时 URL——在交付 URL 中使用 ai_remove_background（不存储任何内容）。
  2. 移除并保存——应用背景移除扩展，并将结果作为新文件版本上传（这是媒体库操作，而非此工具的功能）。
• 仅当用户想要新的背景场景时，才使用 ai_change_background。如果只想抠出透明图像或设置纯色背景，请使用 ai_remove_background（之后可选地将 background 设为某种颜色）。

处理失败

1. 400 / 错误请求或验证错误：完善查询后重试，并将错误文本作为 previous_errors 传入。调用 search-docs 技能并使用 search_docs 确认支持的参数和限制。
2. 失败 3 次以上：重试前，使用 search-docs 查找支持的方法和限制条件。
3. 不支持：通过文档确认，并提供最接近的受支持替代方案。

注意事项

• 源 URL 必须托管在 ImageKit 上。
• 移除背景的顺序很重要（先放大／修饰）。
• 生成式填充 = 在经过填充／扩大的画布上设置 background=genfill；它不接受提示词。ai_change_background 才是由提示词驱动的功能。
• ai_drop_shadow 需要透明主体（先运行 ai_remove_background）。
• 负偏移量／旋转值在最终 URL 中会添加前缀 N（工具会自动处理）——只需按常规方式描述数值。

---

参数参考

以下是工具验证的实际名称／值。请将它们写入查询。

调整大小与裁剪

参数	功能
width	输出宽度。整数 px、小数 0–1（原始尺寸的比例）或算术表达式。
height	输出高度。格式与 width 相同。
aspect_ratio	宽高比（例如 16-9）。与 width 或 height 配合使用；如果两者都设置，则会忽略此参数。
crop	调整大小策略：force、at_max、at_max_enlarge、at_least、maintain_ratio、maintain_ratio_no_enlarge。
crop_mode	填充／提取行为：pad_resize、extract、pad_extract、pad_resize_no_enlarge、pad_extract_no_shrink。
focus	焦点：auto、face、custom、方向位置（center、top、left、bottom_right 等）或对象名称（COCO 类别，例如 person、car、dog）。
zoom	围绕焦点区域的缩放因子（用于人脸／对象焦点）。
x、y、x_center、y_center	extract 裁剪的区域坐标（基于左上角或中心）。
dpr	高像素密度显示屏的设备像素比（数值或 auto）。
background	填充区域的填充方式——参见背景模式。

背景模式（background）

值	含义
颜色	十六进制值（FFFFFF）或 CSS 颜色名称（white、red 等）。
blurred	图像的模糊版本（可选 blurred_<intensity>_<brightness>）。
dominant	图像的主色。
genfill	对填充区域进行 AI 生成式填充（扩图）。不接受提示词。
gradient	根据主色生成渐变（gradient_dominant，可选调色板大小 2 或 4）。

AI 变换

参数	功能
ai_remove_background	使用 ImageKit 原生功能移除背景 → 透明。
ai_remove_background_external	通过外部提供商（remove.bg）移除背景。
ai_edit	基于提示词编辑图像内容。
ai_change_background	基于提示词替换背景场景（保留主体）。
ai_drop_shadow	AI 投影（仅限透明图像）。可选 azimuth（0–360）、elevation（0–90）、strength（0–100）。
ai_upscale	AI 超分辨率放大。不接受参数。
ai_retouch	AI 画质增强／瑕疵去除。不接受参数。
ai_variation	生成图像的结构变体。不接受参数。

效果与增强

参数	作用
blur	高斯模糊，0–100。
sharpen	锐化，0–100。
unsharp_mask	高级锐化（radius、sigma、amount、threshold）。
grayscale	转换为灰度图。
contrast_stretch	自动增强对比度。
shadow	在不透明像素下方添加投影（需要透明度）。可选参数：blur、saturation、x_offset、y_offset。
gradient	线性渐变叠加（linear_direction、from_color、to_color、stop_point）。
color_replace	替换一种颜色及其相似色调：to_color、tolerance（0–100），以及可选的 from_color。
colorize	为图像着色：color、intensity（0–100）。
border	添加指定 border_width 和 color 的边框。
trim	裁掉主体周围的纯色边缘。
rotation	按角度旋转（或根据 EXIF 设为 auto）。负数表示逆时针旋转。
flip	h、v、h_v 或 v_h。
radius	圆角处理（整数、表示圆形的 max，或按角设置的 20_40_80_160）。
opacity	图层不透明度，0–100。
distort	透视变形（4 组坐标对）或弧形变形（角度）。

叠加层（overlay）

统一使用一种 overlay 概念，并搭配类型化形状。每个叠加层均支持 position（x、y、x_center、y_center、focus、anchor_point）、用于视频的 timing（start、end、duration）、layer_mode（multiply、cutter、cutout、displace），以及嵌套的 transformation 列表。

叠加层类型	关键字段
文本	text，以及样式设置：font_size、font_family、font_color、inner_alignment、padding、alpha（1–9）、typography、line_height、radius、rotation、flip、background。
图像	input（叠加图像的媒体库路径）；允许嵌套变换。
视频	input（视频路径）；允许嵌套变换和计时设置。
字幕	input（字幕文件）；样式设置：font_size、font_family、color、typography、font_outline、font_shadow、background。
纯色	color，以及 width、height、radius、alpha、background、gradient。

视频变换

参数	作用
start_offset、end_offset、duration	裁剪片段（秒数或算术表达式）。
audio_codec	aac、opus 或 none（用于静音／移除音频）。
video_codec	h264、vp9、av1 或 none。
streaming_resolutions	自适应码率梯级，例如 [360, 720, 1080]。
rotation、radius、border、flip	与图像效果相同，应用于视频帧。

输出与交付

参数	作用
format	auto、webp、avif、jpg、png、gif、mp4、webm、orig 等。
quality	0–100。
progressive	渐进式 JPEG。
lossless	无损 WebP／PNG。
named	应用已保存的命名变换。
default_image	源图像缺失时使用的备用图像。

条件判断

变换可根据图像属性（例如宽度／高度／宽高比）设置条件——用自然语言描述条件（“如果宽度 > 1000，则……”），工具会构建 if／if-else／if-end 链。