用自然语言构建 ImageKit 图片/视频变换 URL…

在调用 transformation_builder 之前，把模糊的图片/视频变换需求改写成含真实 ImageKit 参数名与取值的自然语言 query，并按正确顺序串联多步操作。

适用场景

解决思路

1. 调用 transformation_builder(query, src?, previous_errors?)：query 为自然语言描述，src 为可选的 ImageKit 托管源 URL（默认用示例图），previous_errors 传入上次失败的错误文本以便自我纠正；该工具没有 capability 参数，参数名只是写进 query 的词汇。
2. 把用户的模糊说法改写成含真实参数名与取值的描述，绝不原样透传；例如把“把红球变绿”写成“Apply an AI edit (`ai_edit`) with prompt: change the red balls to green”。
3. 多步请求合并为一条 query，按顺序描述各步骤，例如“Resize to width 800 and height 600, then crop with focus on the face”。
4. 按意图选用正确词汇：改具体物体/区域用 `ai_edit`（prompt 驱动）；整体换背景场景用 `ai_change_background`（prompt 驱动）；去背景透明用 `ai_remove_background`（外部引擎用 `ai_remove_background_external`）；扩图/外绘用 padded crop + `background`=`genfill`（无 prompt）；提分辨率用 `ai_upscale`；去瑕疵用 `ai_retouch`；投影用 `ai_drop_shadow`；变体用 `ai_variation`。
5. 区分三种易混操作：改具体物体/区域用 `ai_edit`；全局像素换色（如所有红色变蓝）用 `color_replace`（配 `tolerance`）；整体换背景场景用 `ai_change_background`。
6. 尺寸与裁剪用 `width`、`height`、`aspect_ratio`、`crop`、`crop_mode`；智能裁剪用 `focus`（`auto`、`face` 或 COCO 类名如 `person`/`car`/`dog`）加可选 `zoom`。
7. 多步链按此顺序串联：1) 先 upscale/retouch（质量优先）2) AI 内容编辑（`ai_edit`）3) 去背景/换背景（`ai_remove_background`、`ai_change_background`）4) resize/crop（最终尺寸）5) 效果/叠加（收尾）。
8. 关键：去背景必须放在 upscale/retouch 之后，绝不能在前；正确为 `ai_upscale → ai_remove_background`，错误为 `ai_remove_background → ai_upscale`。
9. 用户说“remove background”含糊时，先问清是要实时 URL（`ai_remove_background`，不存储）还是去背景并保存为新文件版本（媒体库操作，非本工具）；只有要新背景场景时才用 `ai_change_background`，纯透明抠图或纯色背景用 `ai_remove_background`（可后接 `background`=某颜色）。
10. 失败处理：遇到 400/Bad Request 或校验错误时，改写 query 并把错误文本作为 `previous_errors` 重试，同时调用 `search-docs` 技能与 `search_docs` 确认支持的参数与限制；失败 3 次以上先用 `search-docs` 查支持的方法与约束再重试；不支持时经文档确认后给出最接近的替代方案。
11. 注意坑点：源 URL 必须是 ImageKit 托管；生成式填充是 padded/放大画布上的 `background`=`genfill` 且不接受 prompt，prompt 驱动的是 `ai_change_background`；`ai_drop_shadow` 需要透明主体（先跑 `ai_remove_background`）；负偏移/旋转在最终 URL 中用 `N` 前缀（工具会处理），描述时正常写数值即可。
12. 按参考表使用真实参数：resize/crop 用 `width`、`height`、`aspect_ratio`、`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`、`zoom`、`x`/`y`/`x_center`/`y_center`、`dpr`、`background`。
13. `background` 取值：颜色（hex 或 CSS 名）、`blurred`（可 `blurred_<intensity>_<brightness>`）、`dominant`、`genfill`、`gradient`（`gradient_dominant`，可选 2 或 4 色调色板）。
14. 效果与增强用 `blur`、`sharpen`、`unsharp_mask`、`grayscale`、`contrast_stretch`、`shadow`、`gradient`、`color_replace`、`colorize`、`border`、`trim`、`rotation`、`flip`、`radius`、`opacity`、`distort`。
15. 叠加用统一的 `overlay` 概念并按类型区分：文字（`text` 及 `font_size`/`font_family`/`font_color`/`inner_alignment`/`padding`/`alpha`/`typography`/`line_height`/`radius`/`rotation`/`flip`/`background`）、图片（`input`）、视频（`input` + timing）、字幕（`input` + 样式）、纯色（`color` 等）；每个 overlay 支持 `position`、视频 `timing`、`layer_mode`（`multiply`/`cutter`/`cutout`/`displace`）及嵌套 `transformation`。
16. 视频变换用 `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`。
17. 输出与交付用 `format`、`quality`、`progressive`、`lossless`、`named`、`default_image`。
18. 条件变换用自然语言描述条件（如“if width > 1000, then …”），工具会构建 `if`/`if-else`/`if-end` 链。

适用边界 · 注意事项

• 需要从零生成图片时（本工具只变换已有 src，文生图属于 ImageKit DAM 的独立功能）。
• 源 URL 不是 ImageKit 托管时。
• 需要“去背景并保存为新文件版本”的媒体库操作时（应使用背景去除扩展并上传，而非本工具）。