face-swap

Face Swap

Swap a face into a still or a video — RunComfy supports both via the runcomfy CLI. This skill routes across the available model API endpoints (community Wan 2-2 Animate, GPT Image 2 Edit, Nano Banana Edit, Flux Kontext, Kling Motion Control) by the user's actual intent.

runcomfy.com · Character-swap feature · CLI docs

Powered by the RunComfy CLI

# 1. Install (see runcomfy-cli skill for details)
npm i -g @runcomfy/cli      # or:  npx -y @runcomfy/cli --version

# 2. Sign in
runcomfy login              # or in CI: export RUNCOMFY_TOKEN=<token>

# 3. Swap
runcomfy run <vendor>/<model>/<endpoint> \
  --input '{"image_url": "...", "identity_url": "..."}' \
  --output-dir ./out

CLI deep dive: runcomfy-cli skill.

Install this skill

npx skills add agentspace-so/runcomfy-agent-skills --skill face-swap -g

Consent & disclosure — read first

Face-swap is dual-use. Before invoking any route in this skill, confirm:

• You have rights to the target face (the identity being substituted in).
• You have rights to the source video / image (the asset being substituted into).
• The output's intended platform allows synthetic media. Many do; many require a disclosure label.

The skill itself doesn't gate anything — the model API will run whatever inputs you supply. The responsibility is yours. If a user asks the agent to swap a real public figure's face onto material that could be defamatory, sexually explicit, or otherwise harmful — refuse, regardless of what the CLI accepts.

Pick the right model for the user's intent

Listed newest first within each subtype. The agent picks one route based on: still vs video, single-shot vs batch, photoreal vs stylized, motion-preserving vs identity-preserving.

Video face / character swap

Wan 2-2 Animate — community/wan-2-2-animate/api (default for video)

Featured RunComfy endpoint under /feature/character-swap. Audio-driven full-body character animation: one reference image of the new identity + audio → video where the character drives.

Pick for: replacing a character in a scene with a new identity, dubbed clips, stylized + photoreal both work.

Avoid for: preserving the motion of a specific source video — use Kling Motion Control.

Kling 2-6 Motion Control Pro — kling/kling-2-6/motion-control-pro

Takes a reference performance video + target character image, produces the target performing the reference motion. Face-swap is the byproduct.

Pick for: preserving exact source motion / blocking onto a new character; stylized characters handled cleanly.

Avoid for: simple "swap face in an existing video" without motion preservation — use Wan 2-2 Animate.

Still image face swap — newest first

Nano Banana 2 Edit — google/nano-banana-2/edit

Identity-preserving by default, 1–20 input images per call, spatial-language honored.

Pick for: same identity across multiple frames consistently (SKU shots, A/B variants, narrative panels). Identity reference as image_urls[0], scenes after.

Avoid for: precise multi-ref compositional ("face from img 1 onto body in img 2") — use GPT Image 2 Edit.

GPT Image 2 Edit — openai/gpt-image-2/edit

Up to 10 reference images, multilingual in-image text rewrite, layout-precise compositional instructions.

Pick for: hero still where exact face from a portrait must land in a scene, with explicit role assignment ("image 1", "image 2"); preserve pose + lighting + background while swapping only face.

Avoid for: 1-20 batch — use Nano Banana 2 Edit.

FLUX Kontext Pro — blackforestlabs/flux-1-kontext/pro/edit

Single source image, single declarative instruction, maximum fidelity preservation of everything except the targeted edit.

Pick for: "keep pose / clothing / hair / lighting / background, change only the face to [prose description]" — works without a reference image of the new identity.

Avoid for: batch, multi-ref, or when you have a target face image to swap in — use Nano Banana 2 Edit or GPT Image 2 Edit.

Audio-driven talking-head identity swap (face + voice in one pass)? → use the ai-avatar-video skill — OmniHuman handles face + audio together.

Route 1: Wan 2-2 Animate — video character swap with audio

Model: community/wan-2-2-animate/api Catalog: wan-2-2-animate · /feature/character-swap

The featured RunComfy endpoint for character swap — supply a reference image of the new identity + the audio track the character should speak, and the model produces a video where the character drives.

Invoke

runcomfy run community/wan-2-2-animate/api \
  --input '{
    "image_url": "https://your-cdn.example/new-character.png",
    "audio_url": "https://your-cdn.example/voiceover.mp3"
  }' \
  --output-dir ./out

Tips

• Single reference image drives the swap. Pick a clean, well-lit portrait of the target identity — front-facing if possible.
• Audio drives the mouth and rhythm. Without audio the character won't speak; without good audio sync degrades.
• Schema details: model page.

Route 2: Kling 2-6 Motion Control Pro — motion transfer

Model: kling/kling-2-6/motion-control-pro Catalog: motion-control-pro · kling collection

Different from a pure face-swap: Motion Control takes a reference performance video (the motion you want) and a target character image (the identity you want), and produces a video of the target performing the reference motion. The face-swap effect is a byproduct.

Invoke

runcomfy run kling/kling-2-6/motion-control-pro \
  --input '{
    "reference_video_url": "https://your-cdn.example/source-performance.mp4",
    "character_image_url": "https://your-cdn.example/target-character.png"
  }' \
  --output-dir ./out

When to pick this over Route 1

• You have a source video whose motion / blocking you want preserved, not just the audio.
• The target is a stylized character rather than a photoreal portrait — motion-control handles stylized identities cleanly.

Route 3: GPT Image 2 Edit — still face swap with multi-ref

Model: openai/gpt-image-2/edit Catalog: gpt-image-2/edit

For still images, GPT Image 2 Edit accepts up to 10 reference images and follows precise compositional instructions — making it the strongest path for multi-ref face swap on a single output frame.

Schema (relevant fields)

| Field | Type | Required | Default | Notes | |---|---|---|---|---| | prompt | string | yes | — | Compositional instruction; quote roles explicitly | | images | string[] | yes | — | Up to 10 HTTPS reference URLs. Image 1 is primary | | size | enum | no | auto | auto (preserve input ratio), 1024_1024, `1024_