faceswap
Swap faces in a video using AI via the HeyGen API. Use when: (1) Replacing a face in a video with another face, (2) Face swapping from a source image onto a target video, (3) Creating personalized videos by swapping in a person's face, (4) Working with HeyGen's /v1/workflows/executions endpoint for
By calesthio · 671 installs
npx skills add calesthio/openmontage --skill faceswap
Source repository · Upstream listing
Face Swap (HeyGen API)
Swap a face from a source image into a target video using GPU accelerated AI processing. The source image provides the face to swap in, and the target video receives the new face.
Authentication
All requests require the X Api Key header. Set the HEYGEN API KEY environment variable.
Default Workflow
1. Call POST /v1/workflows/executions with workflow type: "FaceswapNode" , a source face image, and a target video
2. Receive a execution id in the response
3. Poll GET /v1/workflows/executions/{id} every 10 seconds until status is completed
4. Use the returned video url from the output
Execute Face Swap
Endpoint
POST https://api.heygen.com/v1/workflows/executions
Request Fields
Field Type Req Description
: :
workflow type string Y Must be "FaceswapNode"
input.source image url string Y URL of the face image to swap in
input.target video url string Y URL of the video to apply the face swap to
curl
TypeScript
Python
Response Format
Check Status
Endpoint
GET https://api.heygen.com/v1/workflows/executions/{execution id}
curl
Response Format (Completed)
Polling for Completion
Usage Examples
Basic Face Swap
Chain with Avatar Video
Generate an avatar video first, then swap in a custom face:
Best Practices
1. Use a clear, front facing face photo — the source image should show a single face with good lighting
2. Face swap is GPU intensive — expect 1 3 minutes processing time, poll every 10 seconds
3. Source image quality matters — higher resolution face photos produce better results
4. One face per source image — the source should contain exactly one face to swap in
5. Works with any video — the target video can be an avatar video, a recording, or any video with visible faces
6. Chain with other workflows — generate an avatar video first, then swap in a custom face for personalization