image-edit

Image-to-image (image-edit)

Overview

Apply content edits to an existing image or create a brand-new image based on a reference image (a base image is required). Covers 5 categories of scenarios: e-commerce product output (white background/scene/multi-angle/with text), portrait editing (face/makeup/hairstyle/pose), multi-image and consistency editing, general editing (replace/add/composition), reference image creation (creative visual drafts/business cards/covers). When text addition/replacement is involved, the target text content remains as-is and is not translated; "IP" refers to character patterns rather than text.

Before execution, the user should be clearly informed that: this Skill reads local Meitu credentials, invokes meitu image-edit, and sends the input image, prompt, and generation results to/writes them back to external services and the local output directory.

API Mapping

• Portrait editing:image_gummy_edit_v45
• Multi-image/consistency/general/e-commerce/reference image creation (primary):image_praline_edit_v2
• General editing (fallback):image_praline_edit_2
• In-tool fallback:image_mint_edit
• Nougat high quality (explicitly specified externally):image_nougat_edit(not recognized by routing; image_list supports at most 10 images; output_format not supported; size is an internal constant 2K; quality defaults internally to Medium by the API and is not exposed externally)

model mapping:auto(default by routing)/gummy_pro→gummy/praline_pro→v2/praline_lite→2/mint_edit→mint/nougat→nougat_edit (triggered by explicit external specification)

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-edit/；mkdir -p

Execute

Trigger signals / routing rules

Core judgment dimensions:E-commerce product output → pre-judgment (reference image creation / multi-image) → single-image scenario classification。

Decision order: 0. Pre-step 0 — E-commerce product output: product image + e-commerce intent (white background/main image/scene/multi-angle/promotional text) → image_praline_edit_v2

1. Pre-step A — Reference image creation: has reference image + intent to generate a brand-new image → image_praline_edit_v2
2. Pre-step B — Multi-image input：image_list ≥ 2 images → image_praline_edit_v2(mandatory use of image_list）
3. Single-image scenario(priority: portrait > consistency > general):
   • Portrait (face/expression/makeup/hairstyle/skin tone/pose/facial features) → image_gummy_edit_v45
   • Consistency (product fine-tuning/keep subject/text replacement in existing image) → image_praline_edit_v2
   • General (replace/add/composition) → image_praline_edit_v2

Parameter definitions

General parameters (shared by all APIs):

Parameter	Type	Required	Description
image_list	ARRAY[STRING]	Yes	Image address list, used uniformly by all APIs. If missing → prompt "Please provide an image"
prompt	STRING	Yes	Edit description. In text addition/replacement scenarios, the target text remains the user's original text and is not translated; "IP" refers to patterns/characters rather than text

image_praline_edit_v2 Additional parameters:

Parameter	Type	Required	Range	Default Value	Description
ratio	STRING	No	auto/1:1/2:3/3:2/3:4/4:3/4:5/5:4/9:16/16:9/21:9	auto	For special ratios, write at the end of the prompt Aspect ratio x:y
size	STRING	No	1K/2K/4K	--	Output resolution
output_format	STRING	No	jpeg/png/webp	jpeg	Output format

model parameter (can be explicitly specified to bypass auto routing):gummy_pro(portrait)/praline_pro(general)/praline_lite(fallback)/mint_edit(last resort)/nougat(high quality, triggered by explicit external specification, not recognized by routing).

Tool invocation

meitu image-edit \
  --skill_name skill_image-edit \
  --image_list <url1,url2> \
  --prompt "<edit_description>" \
  --json \
  --download-dir {output_dir}

Optional:--ratio 1:1 --size 2K --output_format png --model praline_pro

Error fallback

Scenario	Handling method
image_gummy_edit_v45 failure	Retry once → fall back to image_praline_edit_v2, then follow v2→2→mint
image_praline_edit_v2 failure	Retry once → fall back to image_praline_edit_2(for multiple images, take image_list[0]）
image_praline_edit_2 failure	Retry once → fall back to image_mint_edit
image_mint_edit failure	Return error
Content compliance interception	Return compliance prompt, no retry, no fallback
Multiple images + portrait intent	Force v2 (gummy only supports single image), recommend splitting into individual images for processing
prompt contains target text	Keep text content as-is, do not translate
prompt contains "IP"	Preserve the "pattern/character" semantics, must not be converted to "text"

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-edit.{jpeg|png|webp}

Output

• Format: JPEG (default)/PNG/WebP (determined by output_format )
• Naming：{YYYY-MM-DD}_{descriptive}_image-edit.jpg
• Location: project → ./output/, one-time → $VISUAL/output/image-edit/

Baseline Task ID

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