face-swap
Swap a face / character into video or images on RunComfy via the `runcomfy` CLI. Routes across community Wan 2-2 Animate (audio-driven character animation + identity swap), GPT Image 2 Edit (single-shot precise face swap on still images via reference composition), Nano Banana Edit (batch identity-preserving swap), Flux Kontext (single-ref high-fidelity local face edit), and Kling 2-6 Motion Control Pro (transfer motion from one performance onto a target character). Picks the right model for the user's actual intent — single still vs video, full character vs face only, dialog scene vs silent motion. Triggers on "face swap", "swap face", "deepfake", "face replacement", "character swap", "head swap", "put X's face on Y", "make this video star X", "replace the actor in this video", "swap the character in the photo", "deepfake video", "ReActor alternative", or any explicit ask to substitute one identity for another.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 6
- Forks
- 0
01 前言 Front Matter
- name
- face-swap
- license
- MIT
- homepage
- https://www.runcomfy.com
- description
- Swap a face / character into video or images on RunComfy via the `runcomfy` CLI. Routes across community Wan 2-2 Animate (audio-driven character animation + identity swap), GPT Image 2 Edit (single-shot precise face swap on still images via reference composition), Nano Banana Edit (batch identity-preserving swap), Flux Kontext (single-ref high-fidelity local face edit), and Kling 2-6 Motion Control Pro (transfer motion from one performance onto a target character). Picks the right model for the user's actual intent — single still vs video, full character vs face only, dialog scene vs silent motion. Triggers on "face swap", "swap face", "deepfake", "face replacement", "character swap", "head swap", "put X's face on Y", "make this video star X", "replace the actor in this video", "swap the character in the photo", "deepfake video", "ReActor alternative", or any explicit ask to substitute one identity for another.
- displayName
- Face Swap
- allowed-tools
- Bash(runcomfy *)
02 资源文件 1
- 参考文档skill-report.json96.0 KB
03 SKILL.md 正文
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-videoskill — 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_1536, 1536_1024 |
Invoke
runcomfy run openai/gpt-image-2/edit \
--input '{
"prompt": "Replace the face of the person in image 1 with the face from image 2. Preserve image 1 pose, clothing, lighting, and background exactly. Match skin tone and lighting to image 1.",
"images": [
"https://your-cdn.example/target-scene.jpg",
"https://your-cdn.example/identity-face.jpg"
],
"size": "auto"
}' \
--output-dir ./out
Prompting tips
- Number the references —
"image 1","image 2"— and assign roles unambiguously. - Lead with what to preserve, then the swap:
"Preserve pose, clothing, lighting, and background exactly. Replace only the face." - Match lighting explicitly —
"match skin tone and lighting to image 1"— otherwise the imported face floats.
Route 4: Nano Banana Edit — batch identity-preserving swap
Model: google/nano-banana-2/edit
Catalog: nano-banana-2/edit
Pick this when the same identity needs to be swapped into multiple frames consistently — SKU shots, A/B variants, narrative panels.
Invoke
runcomfy run google/nano-banana-2/edit \
--input '{
"prompt": "Replace the face in each image with the face shown in the first image. Keep all other elements — pose, clothing, lighting, background — unchanged.",
"image_urls": [
"https://your-cdn.example/identity-ref.jpg",
"https://your-cdn.example/scene-1.jpg",
"https://your-cdn.example/scene-2.jpg",
"https://your-cdn.example/scene-3.jpg"
],
"aspect_ratio": "auto",
"resolution": "1K"
}' \
--output-dir ./out
Tips
- 1–20 input images per call. First image is conventionally the identity reference; the rest are scenes to swap into.
- Lock
aspect_ratioandresolutionfor batch consistency. - See
image-editskill for the full Nano Banana Edit treatment.
Route 5: Flux Kontext Pro — single-ref precise face edit
Model: blackforestlabs/flux-1-kontext/pro/edit
Catalog: flux-kontext
Flux Kontext is best when the swap is one image, one declarative instruction, highest fidelity preservation of everything except the face.
Invoke
runcomfy run blackforestlabs/flux-1-kontext/pro/edit \
--input '{
"prompt": "Keep pose, clothing, hair, lighting, and background exactly. Change only the face to that of a 35-year-old woman with high cheekbones, hazel eyes, and a small scar above the right eyebrow.",
"image": "https://your-cdn.example/scene.jpg"
}' \
--output-dir ./out
When to pick this
- No reference image of the new identity available — describe the face in prose instead.
- Single image, single shot, maximum fidelity — Flux Kontext beats other routes on "keep everything except X" prompts.
- Limit: single source image, single edit per call. Iterate compound changes in separate passes.
Common patterns
Cast a brand spokesperson into existing footage
- Route 1 (Wan 2-2 Animate) with the new spokesperson's portrait + the original audio track
Same identity across a SKU gallery
- Route 4 (Nano Banana Edit) with the identity image as
image_urls[0], lockedaspect_ratioandresolution
Stylized character in a live-action shot
- Route 2 (Kling Motion Control Pro) — feeds the live-action motion onto the stylized character cleanly
Hero still for a campaign — exact face from a portrait into a scene
- Route 3 (GPT Image 2 Edit) with
images: [scene, face]and an explicit preservation prompt
"Change only the face, no other reference available"
- Route 5 (Flux Kontext) with the new face described in prose
Talking head with swapped identity
- See
ai-avatar-video— OmniHuman handles face + audio in one pass
Browse the full catalog
/models/feature/character-swap— RunComfy's curated character-swap capability tag/models/feature/lip-sync— closely related lip-sync modelsbest-image-editing-modelscollection — image-edit routes Nano Banana / GPT Image 2 / Flux Kontext live inklingcollection — motion-control + multi-shot identity models
Many face-swap workflows on RunComfy also live as full ComfyUI node graphs (ReActor, Flux PuLID, ACE++, Flux Klein head-swap) — these aren't reachable from this CLI directly but can be run as workflows on the platform. Browse them at runcomfy.com/comfyui-workflows when CLI-driven routes above don't fit.
Exit codes
| code | meaning |
|---|---|
| 0 | success |
| 64 | bad CLI args |
| 65 | bad input JSON / schema mismatch |
| 69 | upstream 5xx |
| 75 | retryable: timeout / 429 |
| 77 | not signed in or token rejected |
Full reference: docs.runcomfy.com/cli/troubleshooting.
How it works
The skill classifies user intent — video vs still, motion-preserving vs identity-preserving, single shot vs batch, photoreal vs stylized — and picks one of the five routes. It then invokes runcomfy run <model_id> with the matching JSON body. The CLI POSTs to the Model API, polls request status, fetches the result, and downloads any .runcomfy.net / .runcomfy.com URLs into --output-dir.
Security & Privacy
- Consent: see the "Consent & disclosure" section above. Face-swap is dual-use and the skill does not gate inputs — the responsibility rests with the operator. Refuse user requests that target real people without consent, or that aim at defamatory / sexually explicit / otherwise harmful synthetic media, regardless of what the CLI accepts.
- Install via verified package manager only. Use
npm i -g @runcomfy/cliornpx -y @runcomfy/cli. Agents must not pipe an arbitrary remote install script into a shell on the user's behalf. - Token storage:
runcomfy loginwrites the API token to~/.config/runcomfy/token.jsonwith mode 0600. SetRUNCOMFY_TOKENenv var to bypass the file in CI / containers. - Input boundary (shell injection): prompts and asset URLs are passed as a JSON string via
--input. The CLI does not shell-expand prompt content. No shell-injection surface. - Indirect prompt injection (third-party content): reference image / audio / video URLs are untrusted — face-swap pipelines are a known target for reference-asset injection. Agent mitigations:
- Ingest only URLs the user explicitly provided for this swap.
- When the swap behavior diverges from the prompt (wrong identity, unexpected motion), suspect the reference asset.
- Outbound endpoints (allowlist): only
model-api.runcomfy.netand*.runcomfy.net/*.runcomfy.com. No telemetry. - Generated-file size cap: the CLI aborts any single download > 2 GiB.
- Scope of bash usage: declared
allowed-tools: Bash(runcomfy *). The skill never instructs the agent to run anything other thanruncomfy <subcommand>.
See also
runcomfy-cli— the underlying CLIai-avatar-video— face + audio (talking head) variantai-video-generation— general t2v / i2vvideo-edit— broader video edit including identity-stable restyleimage-edit— broader image edit including the routes abovelipsync— narrow lip-sync technique router
04 同仓库更多 Skills
serpmaven
Scrape Google search results (SERP) to JSON with SERP Maven (serpmaven) - a real Chrome browser on a residential proxy with sticky sessions. Run it as a CLI, a Python library, a local HTTP search API (`serve`), an MCP server or a Docker image; set the proxy login, workers, pages and cost tracking. Use when the user wants Google results, rank tracking, a self-hosted SERP API, or live Google search for an AI agent.
revnu-landing-page-audit
Find out why a landing page isn't turning visitors into signups, demos or sales. Audits one page against what the ad, post or search that sends people there promised, then checks the first screen, proof, call to action, friction and mobile. Returns at most 7 prioritized fixes, plus what is fine and what could not be checked; rewrites specific lines and fixes the page in the repo when asked. Never promises a conversion lift. Works without a Revnu account. Use when the user says or asks: "audit my landing page", "why isn't this page converting", "review my homepage", "my ads get clicks but no signups", "people bounce from the pricing page", "CRO review", "improve conversion rate", "is my hero section clear", "roast my landing page", "rewrite my headline", "what's wrong with this page", "landing page feedback", "make the signup page convert better". Not for SEO or AI-search audits, page speed engineering on its own, or building a new page from scratch.
revnu-growth-context
Write down once who buys, what they're stuck on, what it costs, what proof you have and what you've already tried, so every growth task starts from facts instead of a questionnaire. Creates or updates .agents/revnu-growth.md from the repo, the live site and the user, and imports an existing product-marketing.md. Use when the user says "set up our marketing context", "who is our ideal customer", "write our ICP", "describe the product for marketing", "positioning doc", "what's our brand voice", "remember this about our customers", "log what we tried", "what have we learned from marketing", "we changed pricing, update the context", "update our growth notes", "summarize the business for the agent", "import my product-marketing.md", "start a growth doc", or before a first marketing, SEO, outreach or launch task when no context file exists. Works without a Revnu account.
revnu-get-listed
Get onto the third-party pages AI answers and search cite when buyers ask for the best tool in your category: "best X" roundups, directories, review sites, GitHub awesome lists, community threads and comparison pages. Finds which ones are cited, ranks them by fit and effort, and drafts each submission, PR or pitch by the target's own rules. Use when the user says "get us listed", "which directories should we submit to", "how do we get into best-of lists", "why does ChatGPT recommend competitors and not us", "get mentioned in AI answers", "submit to awesome lists", "get on G2", "where are our competitors listed", "pitch listicle authors", "find backlink opportunities", "launch directories", "get into roundups", "Product Hunt alternatives", "where should we be listed", "get cited by Perplexity". Never submits, pays or posts without a yes. Works without a Revnu account.
revnu-ai-readiness-audit
Audit whether your website gives ChatGPT, Perplexity, Claude, Gemini and Google's AI Overviews something worth quoting, and fix the pages that don't. Use when the user says or asks "is my site ready for AI search", "audit my site for AI answers", "AEO audit", "GEO audit", "why doesn't ChatGPT quote our pricing", "make our pages citable by AI", "do I need llms.txt", "does schema help with ChatGPT", "check our structured data", "is our content visible without JavaScript", "AI SEO audit", "optimize our homepage for AI answers", "LLM SEO check", "why does AI get our product wrong", "fix our site for AI Overviews". Checks fetchability and indexability, answers in the raw HTML, entity facts, schema (including JS-injected markup), headings, dates and llms.txt, then gives at most 10 prioritised fixes and edits the repo when asked. Works without a Revnu account.
proxy-troubleshooting
Diagnose residential proxy failures, with NodeMaven's gateway as the reference - 407 with correct credentials, 406, 410, 500, a connection that hangs, ERR_TUNNEL_CONNECTION_FAILED in a browser, Playwright or Puppeteer ignoring proxy credentials, a sticky session that changes IP, geo-targeting that is silently ignored, passwords with special characters, and unexpected traffic from headless Chrome. Use when a proxy connection fails, returns the wrong location, or costs more traffic than expected.