faceswap

Face Swap（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"}}'

デフォルトのワークフロー

1. workflow_type: "FaceswapNode"、ソース顔画像、ターゲット動画を指定して POST /v1/workflows/executions を呼び出します
2. レスポンスで execution_id を受け取ります
3. ステータスが completed になるまで、10 秒ごとに GET /v1/workflows/executions/{id} をポーリングします
4. 出力に含まれる video_url を使用します

Face Swap の実行

エンドポイント

POST https://api.heygen.com/v1/workflows/executions

リクエストフィールド

フィールド	型	必須	説明
workflow_type	string	Y	"FaceswapNode" を指定する必要があります
input.source_image_url	string	Y	合成する顔画像の URL
input.target_video_url	string	Y	Face Swap を適用する動画の URL

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"]

レスポンス形式

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

ステータスの確認

エンドポイント

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"

レスポンス形式（完了時）

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

使用例

基本的な 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"
    }
  }'

アバター動画との連携

まずアバター動画を生成し、その後カスタムの顔を合成します。

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

ベストプラクティス

1. 顔がはっきり写った正面向きの写真を使用する — ソース画像には、照明が適切で顔が 1 つだけ写っている必要があります
2. Face Swap は GPU を集中的に使用します — 処理には 1〜3 分かかるため、10 秒ごとにポーリングしてください
3. ソース画像の画質が重要です — 解像度の高い顔写真ほど、より良い結果が得られます
4. ソース画像には顔を 1 つだけ含める — 合成する顔が 1 つだけ写っている必要があります
5. あらゆる動画で使用できます — ターゲット動画には、アバター動画、録画映像、または顔が見える任意の動画を使用できます
6. 他のワークフローと連携する — まずアバター動画を生成し、その後カスタムの顔を合成してパーソナライズできます