HeyGen API 人脸替换教程：AI 换脸视频制作与 API 调用指南

faceswap by heygen-com/skills

504 周安装量

95 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/heygen-com/skills --skill faceswap

AI/机器学习内容创作 API

🇨🇳中文介绍

人脸替换 (HeyGen API)

使用 GPU 加速的 AI 处理，将源图像中的脸部替换到目标视频中。源图像提供要替换的脸部，目标视频接收新脸部。

身份验证

所有请求都需要 X-Api-Key 请求头。请设置 HEYGEN_API_KEY 环境变量。

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"}}'

默认工作流程

调用 POST /v1/workflows/executions，指定 workflow_type: "FaceswapNode"、源脸部图像和目标视频
在响应中收到 execution_id
每隔 10 秒轮询，直到状态变为

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

字段	类型	必填	描述
`workflow_type`	string	Y	必须为 `"FaceswapNode"`
`input.source_image_url`	string	Y	要替换的脸部图像的 URL
`input.target_video_url`	string	Y	要应用人脸替换的视频的 URL

响应格式 (已完成)

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

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");
}

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"
    }
  }'

与数字人视频串联

先生成数字人视频，然后替换为自定义脸部：

import time

# 步骤 1: 生成数字人视频
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"]

# 步骤 2: 等待数字人视频完成
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)

# 步骤 3: 替换为自定义脸部
faceswap_execution_id = faceswap(
    source_image_url="https://example.com/custom-face.jpg",
    target_video_url=avatar_video_url,
)

使用清晰、正面的脸部照片 — 源图像应展示光线良好的单一人脸
人脸替换是 GPU 密集型任务 — 预计处理时间为 1-3 分钟，建议每 10 秒轮询一次
源图像质量很重要 — 更高分辨率的脸部照片能产生更好的效果
每张源图像只包含一张脸 — 源图像应恰好包含一张要替换的脸部
适用于任何视频 — 目标视频可以是数字人视频、录制视频或任何包含可见脸部的视频
与其他工作流程串联 — 先生成数字人视频，然后替换为自定义脸部以实现个性化

🇺🇸English

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

Weekly Installs

348

Repository

heygen-com/skills

GitHub Stars

First Seen

9 days ago

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

claude-code330

kimi-cli39

gemini-cli39

cursor39

github-copilot39

opencode39

AI 代码实施计划编写技能 | 自动化开发任务分解与 TDD 流程规划工具

43,400 周安装

HeyGen API 人脸替换教程：AI 换脸视频制作与 API 调用指南

🇨🇳中文介绍

人脸替换 (HeyGen API)

身份验证

默认工作流程

相关 Skills

执行人脸替换

端点

请求字段

curl

TypeScript

Python

响应格式

检查状态

端点

curl

响应格式 (已完成)

轮询等待完成

使用示例

基础人脸替换

与数字人视频串联

最佳实践

🇺🇸English

Face Swap (HeyGen API)

Authentication

Default Workflow

Execute Face Swap

Endpoint

Request Fields

curl

TypeScript

Python

Response Format

Check Status

Endpoint

curl

Response Format (Completed)

Polling for Completion

Usage Examples

Basic Face Swap

Chain with Avatar Video

Best Practices

最新 Skills