meitu 图片换背景（image-background-replace）
Overview
对已有图片做整体背景替换/换场景，保留前景主体不变。覆盖商品换场景、人像换背景、宠物换场景、电商白底图、证件照换底色（白/蓝/红）、文字描述任意目标场景的 AI 生成。本工具不能输出透明背景。
API Mapping
- 背景替换：
image_gummy_generate_v45
Dependencies
- meitu-cli:
>=2.0.6（npm install -g meitu-cli@latest） - 凭证：CONFIG AKSK →
meitu tools update；EXEC AKSK → 实际执行（见根CONFIG.md） - 环境变量：
MEITU_OPENAPI_TOOL_TASK_MODE=command
路径别名：
$VISUAL={OPENCLAW_HOME}/workspace/visual/
Core Workflow
Preflight → Execute → Deliver
Preflight
meitu --version≥ 2.0.6（否则npm install -g meitu-cli@latest）- 确认已跑过
meitu tools update（用 CONFIG AKSK） - 当前 AKSK = EXEC，且
MEITU_OPENAPI_TOOL_TASK_MODE=command - 解析 output_dir：openclaw.yaml →
./output/｜else →$VISUAL/output/image-background-replace/；mkdir -p
Execute
触发信号 / 路由规则
| 场景 | 判定关键词 | 路由 |
|---|---|---|
| 整体背景替换 | 换背景、换场景、换底色、证件照换底 | image_gummy_generate_v45 |
决策顺序： 0. 前置拦截：prompt 含"透明"/"透明底"/"透明背景" → 不调用本工具，提示走抠图
- 参数齐全判断：
image_url缺失 → 追问；prompt缺失 → 用默认"白色背景" - 唯一路由：调用
image_gummy_generate_v45
单 API 工具：参数齐全即调用，失败重试 1 次后返回错误；不做跨工具兜底。
参数定义
| 参数 | 类型 | 必填 | 范围 | 默认值 | 说明 |
|---|---|---|---|---|---|
image_url |
STRING | 是 | -- | -- | 图片地址。缺失 → 提示"请提供需要换背景的图片" |
prompt |
STRING | 是 | -- | 白色背景 | 目标背景描述。用户未指定 → 默认"白色背景"并告知可描述具体场景 |
工具调用
meitu image-background-replace \
--skill_name skill_image-background-replace \
--image_url <image_url> \
--prompt "<target_background_description>" \
--json \
--download-dir {output_dir}
错误降级
| 场景 | 处理方式 |
|---|---|
image_url 缺失 |
提示"请提供需要换背景的图片"，不调用 API |
image_url 不可访问 |
直接返回图片链接无效错误，不重试 |
prompt 缺失 |
使用默认值"白色背景" |
| 未检测到前景主体 | 返回错误，提示需包含可识别的前景主体，不重试 |
image_gummy_generate_v45 调用失败 |
重试 1 次，仍失败返回错误 |
| 内容合规拦截 | 直接返回合规提示，不重试 |
| 生成背景与前景不协调 | 建议用户调整 prompt 后重试 |
| 用户同时说"换背景"和"透明底" | 本工具不能输出透明背景，不调用 |
| 视频换背景 | 拒绝，本工具不支持视频 |
Deliver
- 直接使用 Preflight 解析的 output_dir
- 从
downloaded_files[0].saved_path读取已下载文件路径 mv {downloaded_files[0].saved_path} {output_dir}/{YYYY-MM-DD}_{descriptive}_image-background-replace.png
Output
- 格式：PNG（非透明）
- 命名：
{YYYY-MM-DD}_{descriptive}_image-background-replace.png - 位置：项目 →
./output/，一次性 →$VISUAL/output/image-background-replace/
基线 Task ID
见 references/task-id-baseline.md 中对应行。