image-background-replace

Image background replacement (image-background-replace)

Overview

Perform overall background replacement/scene change on an existing image while keeping the foreground subject unchanged. Covers AI generation for product scene changes, portrait background changes, pet scene changes, e-commerce white background images, ID photo background color changes (white/blue/red), and arbitrary target scenes described in text. This tool cannot output a transparent background.

API Mapping

• Background replacement:image_gummy_generate_v45

Dependencies

• meitu-cli: >=2.0.6（npm install -g meitu-cli@latest）
• Credentials：CONFIG AKSK → meitu tools update; EXEC AKSK → actual execution (see root CONFIG.md）
• Environment variables：MEITU_OPENAPI_TOOL_TASK_MODE=command

Path alias:$VISUAL = {OPENCLAW_HOME}/workspace/visual/

Core Workflow

Preflight → Execute → Deliver

Preflight

1. meitu --version ≥ 2.0.6 (otherwise npm install -g meitu-cli@latest）
2. Confirm that meitu tools updatehas been run (using CONFIG AKSK)
3. Current AKSK = EXEC, and MEITU_OPENAPI_TOOL_TASK_MODE=command
4. Resolve output_dir: openclaw.yaml → ./output/ ｜else → $VISUAL/output/image-background-replace/；mkdir -p

Execute

Trigger signals / routing rules

Scenario	Determination keywords	Route
Overall background replacement	change background, change scene, change background color, ID photo background change	image_gummy_generate_v45

Decision order: 0. Pre-interception: prompt contains "transparent"/"transparent background"/"transparent background" → do not call this tool, prompt to use cutout

1. Parameter completeness check：image_url missing → ask follow-up;prompt missing → use default "white background"
2. Unique route: call image_gummy_generate_v45

Single API tool: call when parameters are complete; after 1 retry on failure, return an error; do not perform cross-tool fallback.

Parameter definitions

Parameter	Type	Required	Range	Default value	Description
image_url	STRING	Yes	--	--	Image URL. Missing → prompt "Please provide the image whose background needs to be changed"
prompt	STRING	Yes	--	White background	Target background description. If the user does not specify → default to "white background" and inform them that a specific scene can be described

Tool invocation

meitu image-background-replace \
  --skill_name skill_image-background-replace \
  --image_url <image_url> \
  --prompt "<target_background_description>" \
  --json \
  --download-dir {output_dir}

Error degradation

Scenario	Handling method
image_url missing	Prompt "Please provide the image whose background needs to be changed", do not call the API
image_url inaccessible	Directly return an invalid image link error, do not retry
prompt missing	Use the default value "white background"
No foreground subject detected	Return an error, prompting that a recognizable foreground subject must be included, do not retry
image_gummy_generate_v45 call failed	Retry once; if it still fails, return an error
Content compliance interception	Directly return a compliance prompt, do not retry
Generated background and foreground are uncoordinated	Suggest the user adjust the prompt and retry
User says both "change background" and "transparent background"	This tool cannot output a transparent background, do not call
Video background replacement	Reject; this tool does not support video

Deliver

• Directly use the output_dir parsed by Preflight
• From downloaded_files[0].saved_path read the downloaded file path
• mv {downloaded_files[0].saved_path} {output_dir}/{YYYY-MM-DD}_{descriptive}_image-background-replace.png

Output

• Format: PNG (non-transparent)
• Naming：{YYYY-MM-DD}_{descriptive}_image-background-replace.png
• Location: Project → ./output/, one-time → $VISUAL/output/image-background-replace/

Baseline Task ID

See references/task-id-baseline.md the corresponding line in.