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.

curl -X POST "https://api.heygen.com/v1/workflows/executions"
-H "X-Api-Key: $HEYGEN_API_KEY"
-H "Content-Type: application/json"
-d '{"workflow_type": "FaceswapNode", "input": {"source_image_url": "https://example.com/face.jpg", "target_video_url": "https://example.com/video.mp4"}}'

Default Workflow

• Call POST /v1/workflows/executions with workflow_type: "FaceswapNode" , a source face image, and a target video

• Receive a execution_id in the response

• Poll GET /v1/workflows/executions/{id} every 10 seconds until status is completed

• 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

curl -X POST "https://api.heygen.com/v1/workflows/executions"
-H "X-Api-Key: $HEYGEN_API_KEY"
-H "Content-Type: application/json"
-d '{ "workflow_type": "FaceswapNode", "input": { "source_image_url": "https://example.com/face-photo.jpg", "target_video_url": "https://example.com/original-video.mp4" } }'

TypeScript

interface FaceswapInput { source_image_url: string; target_video_url: string; }

interface ExecuteResponse { data: { execution_id: string; status: "submitted"; }; }

async function faceswap(input: FaceswapInput): Promise<string> { const response = await fetch("https://api.heygen.com/v1/workflows/executions", { method: "POST", headers: { "X-Api-Key": process.env.HEYGEN_API_KEY!, "Content-Type": "application/json", }, body: JSON.stringify({ workflow_type: "FaceswapNode", input, }), });

const json: ExecuteResponse = await response.json(); return json.data.execution_id; }

Python

import requests import os

def faceswap(source_image_url: str, target_video_url: str) -> str: payload = { "workflow_type": "FaceswapNode", "input": { "source_image_url": source_image_url, "target_video_url": target_video_url, }, }

response = requests.post(
    "https://api.heygen.com/v1/workflows/executions",
    headers={
        "X-Api-Key": os.environ["HEYGEN_API_KEY"],
        "Content-Type": "application/json",
    },
    json=payload,
)

data = response.json()
return data["data"]["execution_id"]

Response Format

{ "data": { "execution_id": "node-gw-f1s2w3p4", "status": "submitted" } }

Check Status

Endpoint

GET https://api.heygen.com/v1/workflows/executions/{execution_id}

curl

curl -X GET "https://api.heygen.com/v1/workflows/executions/node-gw-f1s2w3p4"
-H "X-Api-Key: $HEYGEN_API_KEY"

Response Format (Completed)

{ "data": { "execution_id": "node-gw-f1s2w3p4", "status": "completed", "output": { "video_url": "https://resource.heygen.ai/faceswap/output.mp4" } } }

Polling for Completion

async function faceswapAndWait( input: FaceswapInput, maxWaitMs = 600000, pollIntervalMs = 10000 ): Promise<string> { const executionId = await faceswap(input); console.log(Submitted face swap: ${executionId});

const startTime = Date.now(); while (Date.now() - startTime < maxWaitMs) { const response = await fetch( https://api.heygen.com/v1/workflows/executions/${executionId}, { headers: { "X-Api-Key": process.env.HEYGEN_API_KEY! } } ); const { data } = await response.json();

switch (data.status) {
  case "completed":
    return data.output.video_url;
  case "failed":
    throw new Error(data.error?.message || "Face swap failed");
  case "not_found":
    throw new Error("Workflow not found");
  default:
    await new Promise((r) => setTimeout(r, pollIntervalMs));
}

}

throw new Error("Face swap timed out"); }

Usage Examples

Basic Face Swap

curl -X POST "https://api.heygen.com/v1/workflows/executions"
-H "X-Api-Key: $HEYGEN_API_KEY"
-H "Content-Type: application/json"
-d '{ "workflow_type": "FaceswapNode", "input": { "source_image_url": "https://example.com/headshot.jpg", "target_video_url": "https://example.com/presentation.mp4" } }'

Chain with Avatar Video

Generate an avatar video first, then swap in a custom face:

import time

Step 1: Generate avatar video

avatar_execution_id = requests.post( "https://api.heygen.com/v1/workflows/executions", headers={"X-Api-Key": os.environ["HEYGEN_API_KEY"], "Content-Type": "application/json"}, json={ "workflow_type": "AvatarInferenceNode", "input": { "avatar": {"avatar_id": "Angela-inblackskirt-20220820"}, "audio_list": [{"audio_url": "https://example.com/speech.mp3"}], }, }, ).json()["data"]["execution_id"]

Step 2: Wait for avatar video to complete

while True: status = requests.get( f"https://api.heygen.com/v1/workflows/executions/{avatar_execution_id}", headers={"X-Api-Key": os.environ["HEYGEN_API_KEY"]}, ).json()["data"] if status["status"] == "completed": avatar_video_url = status["output"]["video"]["video_url"] break time.sleep(10)

Step 3: Swap in a custom face

faceswap_execution_id = faceswap( source_image_url="https://example.com/custom-face.jpg", target_video_url=avatar_video_url, )

Best Practices

• Use a clear, front-facing face photo — the source image should show a single face with good lighting

• Face swap is GPU-intensive — expect 1-3 minutes processing time, poll every 10 seconds

• Source image quality matters — higher resolution face photos produce better results

• One face per source image — the source should contain exactly one face to swap in

• Works with any video — the target video can be an avatar video, a recording, or any video with visible faces

• Chain with other workflows — generate an avatar video first, then swap in a custom face for personalization