image-face-swap

Image Face Swap (image-face-swap)

Overview

Dual-image face swap/head swap compositing, replacing the face in the source image onto the target scene image. Preserves the target image's composition/body/background, automatically blends skin tone and matches lighting; used for role-playing, putting your own face onto another image, and fun compositing. Only one face is swapped at a time.

Before execution, the user should be clearly informed that: this Skill will read Meitu credentials, call the local meitu CLI, send the two face-related images to the Meitu OpenAPI for processing, and write the results to ./output/ or $VISUAL/output/image-face-swap/。

API Mapping

• Dual-image face swap/head swap compositing:image_face_swap

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

Execute

Trigger signals / routing rules

Core judgment dimensions:Number of images + head/sence role assignment。

Scenario	Judgment	Routing
Dual-image face swap	2 images provided, intent is face swap	image_face_swap, head/sence assigned according to the rules

Decision order:

1. Number of images: fewer than 2 → prompt to add images; more than 2 → take the first 2 and inform the user
2. Role assignment：
   • User explicitly specifies → assign head / sence as specified
   • Not distinguished → 1st image = head (face source), 2nd image = sence (scene base image)
   • "Use B to swap onto A" → B=head (source), A=sence
3. Single route: call image_face_swap

Single API tool: call when parameters are complete; after a failure, retry once and then return an error; do not fall back across tools. Severe profile/occlusion does not block the call, but inform the user that the effect may be limited.

Parameter definitions

Parameter	Type	Required	Default value	Description
head_image_url	STRING	Yes	--	Face source image URL
sence_image_url	STRING	Yes	--	Scene base image URL (preserves composition/body/background)
prompt	STRING	Yes	--	Additional prompt. If missing → prompt "Please describe the face swap effect requirements"

Tool invocation

meitu image-face-swap \
  --skill_name skill_image-face-swap \
  --head_image_url <head_url> \
  --sence_image_url <sence_url> \
  --prompt "<effect_description>" \
  --json \
  --download-dir {output_dir}

Error degradation

Scenario	Handling method
Fewer than 2 images	Prompt "Please provide two images: one face source image and one target scene image"
3+ images	Take the first 2 (1st=head, 2nd=sence), inform the user
head_image_url / sence_image_url inaccessible	Return an invalid image link error, do not retry
No face detected (head)	Return error: the face source image must contain a clear frontal face
image_face_swap Call failed	Retry once; if it still fails, return an error
Content compliance interception	Return a compliance prompt, do not retry
Profile face / severe occlusion	Do not block the call; inform that the result may be limited
Video face swap	Reject; only images are supported
Multiple people face swapping at the same time	This tool swaps only one face at a time

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-face-swap.jpg

Output

• Format: JPEG/PNG (keep the original format)
• Naming：{YYYY-MM-DD}_{descriptive}_image-face-swap.jpg
• Location: project → ./output/, one-time → $VISUAL/output/image-face-swap/

Baseline Task ID

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