faceswap

用途

Face Swap（换脸）是基于 HeyGen API 的视频换脸技能，用于把一张源图片中的人脸替换到目标视频中。源图片提供要换入的人脸，目标视频是接收新人脸的视频。该技能适合需要替换视频中人物面部、或先对视频生成结果再做换脸个性化的场景。

主要能力

通过 HeyGen API 提交换脸工作流，工作流类型为 FaceswapNode。
输入由两部分组成：source_image_url（要换入的人脸图片 URL）与 target_video_url（应用换脸的视频 URL）。
提交后返回 execution_id，可通过轮询查询执行状态，完成后获取输出视频的 video_url。
可与头像视频（Avatar）工作流串联：先生成头像视频，再换入自定义人脸。

使用方式

认证

所有请求都需要 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 https://api.heygen.com/v1/workflows/executions

请求字段：

workflow_type（string，必填）：必须为 "FaceswapNode"。
input.source_image_url（string，必填）：要换入的人脸图片 URL。
input.target_video_url（string，必填）：应用换脸的视频 URL。

响应格式

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

检查状态

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

示例：

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

完成后的响应格式：

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

轮询完成状态（TypeScript 示例）

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

与头像视频串联（Python 示例）

先生成头像视频，再换入自定义人脸：

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,
)

适用场景

将一张人脸图片中的人脸替换到某段视频中。
先由 AvatarInferenceNode 生成头像视频，再换入自定义人脸以实现个性化。
目标视频可以是头像视频、录制视频或任何包含可见人脸的视频。

限制与最佳实践

源图片应使用清晰、正面的人脸照片，光照良好。
源图片应只包含一张人脸，用于换入。
源图片质量影响效果，更高分辨率的人脸照片通常效果更好。
换脸属于 GPU 密集处理，预计处理时间为 1-3 分钟，建议每 10 秒轮询一次。
轮询时可根据 status 判断：completed 返回 video_url；failed 抛出错误；not_found 表示工作流未找到。

暂未提供

资料未说明该技能的收费方式、价格、平台限制或调用配额等信息，相关内容暂未提供。