顔検出

NamiFusion ビデオ顔交換

AI ビデオ顔交換：1人の自動顔交換と複数人の精密マッピングに対応。顔検出と組み合わせて完全なビデオ顔交換ワークフローを実現。

NamiFusion ビデオ顔交換は、ソースの顔をターゲット動画に置き換える高品質 AI サービスです。1人顔交換（自動モード）と複数人顔交換（精密マッピングモード）の2種類を提供し、NamiFusion 顔検出と組み合わせることで、顔の検出から交換までの完全なワークフローを実現できます。

---

主な機能

• 1人顔交換： single_face_mode を有効にするだけで、追加設定不要で自動的に顔交換が完了します。
• 複数人精密マッピング： face_mapping でソースの顔とターゲットの顔の対応関係を正確に指定。1対1および多対多のマッピングに対応。
• 顔強調： オプションの高度な美化機能で、肌を自動的に滑らかにし、顔のシミや傷を除去し、交換後の顔の品質を向上させます。
• 非同期タスク： 送信後に task_uuid を返し、ポーリングまたは Webhook で結果を取得します。

---

技術仕様

パラメータ	詳細
モデル ID	namifusion/faceswap-video
リクエスト方式	非同期 POST（タスク送信 + ポーリング/Webhook で結果取得）
入力	ソース顔画像 URL + ターゲット動画 URL
出力	顔交換後の動画 URL
処理時間	通常 30 秒〜数分（動画の長さと解像度によって異なる）
ソース画像フォーマット	JPG、PNG；最大解像度 4K
ターゲット動画フォーマット	MP4、MOV、WEBM、AVI；最大ファイルサイズ 5 GB；最大時間 2 時間；最大解像度 4K

---

クイックスタート

API エンドポイント

エンドポイント	メソッド	説明
/api/v1/marketplace/run/namifusion/faceswap-video	POST	ビデオ顔交換タスクを送信
/api/v1/marketplace/run/tasks/{task_uuid}	GET	タスクの状態と結果を照会

認証

リクエストヘッダーに API Key を含めます：

X-API-Key: sk-your-api-key

---

シナリオ 1：1人顔交換（最もシンプルな使い方）

ソース画像とターゲット動画の両方に1つの顔のみ含まれる場合に適しています。single_face_mode を有効にすれば face_mapping の設定は不要で、サービスが自動的に顔交換を完了します。

ステップ 1：顔交換タスクを送信

curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/faceswap-video" \
  -H "X-API-Key: sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "source_url": "https://example.com/source_face.jpg",
      "target_url": "https://example.com/target_video.mp4",
      "single_face_mode": true
    }
  }'

レスポンス例：

{
  "task_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "cost_credits": 50
}

ステップ 2：タスク状態をポーリング

curl -X GET "https://www.namifusion.com/api/v1/marketplace/run/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-API-Key: sk-your-api-key"

処理中：

{
  "task_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing"
}

完了：

{
  "task_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "model_id": "namifusion/faceswap-video",
  "status": "completed",
  "output": {
    "videos": ["https://cdn.namifusion.com/result/faceswap_abc123.mp4"]
  },
  "cost_credits": 50,
  "created_at": "2026-02-27T10:00:00Z",
  "completed_at": "2026-02-27T10:01:30Z"
}

---

シナリオ 2：複数人顔交換

ターゲット動画に複数の顔が含まれており、「どのソース顔をどのターゲット顔に置き換えるか」を正確に制御したい場合は、まず顔検出 API を呼び出して動画から顔を検出し、face_mapping を構築してから顔交換タスクを送信する必要があります。

ステップ 1：ターゲット動画の顔を検出

NamiFusion 顔検出（POST /api/v1/marketplace/run/namifusion/detect_faces）を呼び出して動画から直接顔を検出し、結果をポーリングします。

検出タスクを送信：

curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/detect_faces" \
  -H "X-API-Key: sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "url": "https://example.com/target_video.mp4",
      "num_frames": 3,
      "return_face_url": true,
      "deduplicate": true
    }
  }'

num_frames は顔検出のために動画から均一にサンプリングするフレーム数を指定します。最大値：100。値が大きいほどすべての顔を検出できる可能性が高まりますが、処理時間も増加します。ほとんどの動画では 3〜10 フレームで十分です。

タスク結果をポーリング：

curl -X GET "https://www.namifusion.com/api/v1/marketplace/run/tasks/{task_uuid}" \
  -H "X-API-Key: sk-your-api-key"

完了レスポンス（2人検出した場合）：

{
  "task_uuid": "...",
  "status": "completed",
  "output": {
    "error_code": 0,
    "error_msg": "SUCCESS",
    "faces_obj": {
      "0": {
        "region": [[50, 80, 150, 200], [250, 70, 350, 190]],
        "face_urls": [
          "https://s3.amazonaws.com/faces/target_face_0.jpg",
          "https://s3.amazonaws.com/faces/target_face_1.jpg"
        ],
        "landmarks": [[[...]], [[...]]],
        "frame_time": null,
        "crop_region": [[...], [...]],
        "landmarks_str": ["...", "..."],
        "crop_landmarks": ["...", "..."]
      },
      "1": {
        "region": [],
        "face_urls": [],
        "landmarks": [],
        "frame_time": 1.0,
        "crop_region": [],
        "landmarks_str": [],
        "crop_landmarks": []
      },
      "2": {
        "region": [],
        "face_urls": [],
        "landmarks": [],
        "frame_time": 2.0,
        "crop_region": [],
        "landmarks_str": [],
        "crop_landmarks": []
      }
    }
  }
}

これにより、ターゲット動画に2人（faces_obj["0"].region の長さが 2）いることと、それぞれの face_urls がわかります。

ステップ 2：ソース顔画像を検出

同様に顔検出を呼び出して検出タスクを送信し、結果をポーリングします（複数のソース顔画像がある場合や、正確な顔座標情報を渡す必要がある場合）。

検出タスクを送信：

curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/detect_faces" \
  -H "X-API-Key: sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "url": "https://example.com/source_face.jpg",
      "return_face_url": true
    }
  }'

完了レスポンス：

{
  "task_uuid": "...",
  "status": "completed",
  "output": {
    "error_code": 0,
    "error_msg": "SUCCESS",
    "faces_obj": {
      "0": {
        "region": [[100, 50, 200, 180]],
        "face_urls": ["https://s3.amazonaws.com/faces/source_face_0.jpg"],
        "landmarks": [[[...]]],
        "frame_time": null,
        "crop_region": [[...]],
        "landmarks_str": ["..."],
        "crop_landmarks": ["..."]
      }
    }
  }
}

ステップ 3：face_mapping を構築

検出結果に基づき、ソース顔からターゲット顔へのマッピングを構築します。

顔検出が返した face_urls を face_mapping 内の source_face_info.face_url と target_face_info.face_url として使用します：

"face_mapping": [
  {
    "source_face_info": {
      "face_url": "https://s3.amazonaws.com/faces/source_face_0.jpg"
    },
    "target_face_info": {
      "face_url": "https://s3.amazonaws.com/faces/target_face_0.jpg"
    }
  }
]

face_url の値は、ステップ 1・2 の顔検出が返した output.faces_obj["0"].face_urls[i] から直接取得します。

face_mapping は source_face_index、target_face_index、bbox などのパラメータもサポートしています。詳細は下記の「face_mapping 詳細」セクションを参照してください。

ステップ 4：複数人顔交換タスクを送信

curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/faceswap-video" \
  -H "X-API-Key: sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "source_url": "https://example.com/source_face.jpg",
      "target_url": "https://example.com/target_video.mp4",
      "single_face_mode": false,
      "face_mapping": [
        {
          "source_face_info": {
            "face_url": "https://s3.amazonaws.com/faces/source_face_0.jpg"
          },
          "target_face_info": {
            "face_url": "https://s3.amazonaws.com/faces/target_face_0.jpg"
          }
        }
      ]
    }
  }'

レスポンス：

{
  "task_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "status": "pending",
  "cost_credits": 50
}

ステップ 5：顔交換結果を取得

status が completed になるまでタスク状態をポーリングします：

curl -X GET "https://www.namifusion.com/api/v1/marketplace/run/tasks/b2c3d4e5-f6a7-8901-bcde-f12345678901" \
  -H "X-API-Key: sk-your-api-key"

完了レスポンス：

{
  "task_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "model_id": "namifusion/faceswap-video",
  "status": "completed",
  "output": {
    "videos": ["https://cdn.namifusion.com/result/faceswap_def456.mp4"]
  },
  "cost_credits": 50,
  "created_at": "2026-02-27T10:05:00Z",
  "completed_at": "2026-02-27T10:07:30Z"
}

---

Python 完全サンプル：複数人ビデオ顔交換ワークフロー

以下のサンプルは、顔検出から複数人ビデオ顔交換までの完全なワークフローを示します：

import requests
import time

API_KEY = "sk-your-api-key"
BASE_URL = "https://www.namifusion.com/api/v1/marketplace/run"
HEADERS = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
}

source_url = "https://example.com/source_face.jpg"
target_url = "https://example.com/target_video.mp4"


def detect_faces(media_url, num_frames=None):
    """顔検出タスクを送信して結果をポーリングする。"""
    input_params = {"url": media_url, "return_face_url": True}
    if num_frames:
        input_params["num_frames"] = num_frames
    task = requests.post(
        f"{BASE_URL}/namifusion/detect_faces",
        headers=HEADERS,
        json={"input": input_params},
    ).json()

    while True:
        resp = requests.get(
            f"{BASE_URL}/tasks/{task['task_uuid']}",
            headers=HEADERS,
        ).json()

        if resp["status"] == "completed":
            return resp["output"]
        elif resp["status"] == "failed":
            raise Exception(resp.get("error_message", "不明なエラー"))

        time.sleep(3)


# ステップ 1：ターゲット動画の顔を検出
target_detect = detect_faces(target_url, num_frames=3)
target_frame = target_detect["faces_obj"]["0"]

print(f"ターゲット動画に {len(target_frame['face_urls'])} 人の顔があります")
for i, face_url in enumerate(target_frame["face_urls"]):
    print(f"  顔 {i}: region={target_frame['region'][i]}")

# ステップ 2：ソース画像の顔を検出
source_detect = detect_faces(source_url)
source_frame = source_detect["faces_obj"]["0"]

# ステップ 3：face_mapping を構築（ソース顔 0 でターゲット顔 0 を置き換え）
face_mapping = [
    {
        "source_face_info": {"face_url": source_frame["face_urls"][0]},
        "target_face_info": {"face_url": target_frame["face_urls"][0]},
    }
]

# ステップ 4：ビデオ顔交換タスクを送信
task_resp = requests.post(
    f"{BASE_URL}/namifusion/faceswap-video",
    headers=HEADERS,
    json={
        "input": {
            "source_url": source_url,
            "target_url": target_url,
            "single_face_mode": False,
            "face_mapping": face_mapping,
        }
    },
).json()

task_uuid = task_resp["task_uuid"]
print(f"タスク送信完了：{task_uuid}")

# ステップ 5：結果をポーリング
while True:
    status_resp = requests.get(
        f"{BASE_URL}/tasks/{task_uuid}",
        headers=HEADERS,
    ).json()

    status = status_resp["status"]
    print(f"状態：{status}")

    if status == "completed":
        result_url = status_resp["output"]["videos"][0]
        print(f"結果：{result_url}")
        break
    elif status == "failed":
        print(f"失敗：{status_resp.get('error_message', '不明なエラー')}")
        break

    time.sleep(10)

---

パラメータとレスポンスの詳細

リクエストパラメータ

リクエストボディは JSON 形式で、すべてのパラメータは input オブジェクト内に入れます：

{
  "input": {
    "source_url": "https://...",
    "target_url": "https://...",
    "single_face_mode": true,
    "face_enhance": false,
    "face_mapping": [],
    "model_style": "realistic"
  }
}

パラメータ	型	必須	デフォルト	説明
source_url	string	必須	-	ソース顔画像 URL（ターゲットに重ねる顔）。公開アクセス可能であること。HTTP/HTTPS に対応。サポートフォーマット：JPG、PNG、最大解像度 4K。
target_url	string	必須	-	ターゲット動画 URL（顔交換対象の動画）。公開アクセス可能であること。HTTP/HTTPS に対応。サポートフォーマット：MP4、MOV、WEBM、AVI、最大 5 GB、最長 2 時間、最大解像度 4K。
single_face_mode	boolean	任意	true	1人モード。有効にすると face_mapping の設定不要で自動的に顔交換が完了します。
face_enhance	boolean	任意	false	顔強調を有効にするかどうか。有効にすると肌を自動的に滑らかにしてシミを除去し、顔の品質を高めますが、処理時間が増加します。
face_mapping	array	任意	null	顔マッピング設定。single_face_mode: false の時のみ有効。詳細は下記参照。
model_style	string	任意	"realistic"	顔交換スタイル。選択肢："realistic"、"beautify"、"lossless"。「パラメータが出力に与える影響」セクション参照。

face_mapping 詳細

face_mapping は配列で、各要素がソース顔からターゲット顔へのマッピングを定義します：

フィールド	型	必須	説明
source_face_index	integer	必須	ソース画像内の顔のインデックス（0 始まり、顔の検出ボックス左上角の x 座標で左から右に並べ替え）。
target_face_index	integer	必須	ターゲット動画内の顔のインデックス（0 始まり、顔の検出ボックス左上角の x 座標で左から右に並べ替え）。
source_face_info	object	任意	ソース顔の座標情報。指定するとバックエンドの再検出をスキップし、顔の順序の一貫性を保ちます。
target_face_info	object	任意	ターゲット顔の座標情報。指定するとマッチング精度が向上します。

source_face_info フィールド

フィールド	型	説明
face_url	string	顔検出が返したトリミング済み顔画像 URL（output.faces_obj["0"].face_urls[i]）。指定するとバックエンドがこのトリミング画像を直接使用して顔交換を行い、内部の再検出をスキップして顔の同一性を保証します。
bbox	number[]	顔検出ボックスの座標（ピクセル）、フォーマット [x1, y1, x2, y2]。(x1, y1) が左上隅、(x2, y2) が右下隅。顔検出が返す region フィールドから取得します。
kps	number[][]	5 つの顔ランドマーク座標、フォーマット [[x, y], ...]、順番：左目、右目、鼻先、左口角、右口角。顔検出が返す landmarks フィールドから取得します。指定するとバックエンドが直接使用し、再検出をスキップして顔合わせの精度を向上させます。

target_face_info フィールド

フィールド	型	説明
face_url	string	ターゲット顔のトリミング済み画像 URL、顔検出から取得（output.faces_obj["0"].face_urls[i]）。指定するとバックエンドがターゲット顔を正確にマッチングし、内部再検出による顔の順序不一致を防ぎます。
bbox	number[]	ターゲット顔の検出ボックス座標（ピクセル）、フォーマット [x1, y1, x2, y2]。(x1, y1) が左上隅、(x2, y2) が右下隅。

タスク状態

タスク送信後に状態をポーリングします。推奨ポーリング間隔：10 秒。

状態	説明
pending	タスクが作成され、処理待ちの状態。
processing	タスク処理中。
completed	タスク完了。output.videos から結果 URL を取得。
failed	タスク失敗。error_message で原因を確認。

レスポンス構造

タスク送信レスポンス

フィールド	型	説明
task_uuid	string	タスクの一意識別子。以降の状態照会に使用します。
status	string	初期状態。通常は pending。
cost_credits	number	このタスクで消費したクレジット。

タスク完了レスポンス

フィールド	型	説明
task_uuid	string	タスクの一意識別子。
model_id	string	モデル ID（namifusion/faceswap-video）。
status	string	タスク状態。
output.videos	string[]	顔交換済み結果動画 URL のリスト。
cost_credits	number	消費したクレジット。
created_at	string	タスク作成日時（ISO 8601）。
completed_at	string	タスク完了日時（ISO 8601）。
error_message	string	エラーメッセージ（failed の場合のみ返却）。

---

パラメータが出力に与える影響

パラメータ	結果への影響
single_face_mode: true	自動的に顔交換が完了。1人のシナリオに適しており、face_mapping の設定不要。
single_face_mode: false + face_mapping	交換する顔を正確に制御。マッピングで指定されていない顔はそのまま保持されます。
face_enhance: true	顔強調を有効化。肌を自動的に滑らかにしてシミを除去し、より洗練された自然な仕上がりになりますが、処理時間が約 20〜50% 増加します。
face_enhance: false	デフォルトモード。追加の顔処理なし。処理速度が速い。
model_style: "realistic"	リアルスタイル。実際の顔に近い自然な仕上がり。リアルな肌の色とテクスチャを保持。
model_style: "beautify"	ビューティースタイル。肌の自動スムージングと明るさの向上で、洗練されたなめらかな外観に。
model_style: "lossless"	無損失スタイル。究極の無損失モード。元の顔のすべての細部を完全に保持し、最高のリアリズムを実現。ほぼ見分けがつきません。

---

Webhook

ポーリングの代わりに、リクエストボディに webhook_url を指定することでタスク結果を自動受信できます。タスクが completed または failed になると、サービスが指定した URL に完全なタスク結果を POST します。

webhook_url は input と並列のトップレベルフィールドで、input の中には入れません：

curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/faceswap-video" \
  -H "X-API-Key: sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "source_url": "https://example.com/source_face.jpg",
      "target_url": "https://example.com/target_video.mp4",
      "single_face_mode": true
    },
    "webhook_url": "https://your-server.com/callback"
  }'

Webhook ペイロード

webhook_url に POST されるペイロードの構造は、タスク完了レスポンスと同じです：

{
  "task_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "model_id": "namifusion/faceswap-video",
  "status": "completed",
  "output": {
    "videos": ["https://cdn.namifusion.com/result/faceswap_abc123.mp4"]
  },
  "cost_credits": 50,
  "created_at": "2026-02-27T10:00:00Z",
  "completed_at": "2026-02-27T10:01:30Z"
}

タスク失敗時は、ペイロードに error_message フィールドが含まれ、status は "failed" になります。

webhook_url を設定してもタスク状態のポーリングは引き続き可能です。両方を同時に使用できます。

Python サンプル

webhook_url を指定してタスクを送信：

import requests

API_KEY = "sk-your-api-key"
BASE_URL = "https://www.namifusion.com/api/v1/marketplace/run"
HEADERS = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
}

# webhook_url は input と並列のトップレベルフィールドです。input の中には入れないでください
resp = requests.post(
    f"{BASE_URL}/namifusion/faceswap-video",
    headers=HEADERS,
    json={
        "input": {
            "source_url": "https://example.com/source_face.jpg",
            "target_url": "https://example.com/target_video.mp4",
            "single_face_mode": True,
        },
        "webhook_url": "https://your-server.com/callback",
    },
).json()

print(f"タスク送信完了：{resp['task_uuid']}")
# ポーリング不要 — 結果は自動的に webhook_url に配信されます

Webhook コールバックを受信（Flask）：

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/callback", methods=["POST"])
def webhook():
    payload = request.get_json()
    task_uuid = payload["task_uuid"]
    status = payload["status"]

    if status == "completed":
        video_url = payload["output"]["videos"][0]
        print(f"タスク {task_uuid} 完了：{video_url}")
    elif status == "failed":
        error = payload.get("error_message", "不明なエラー")
        print(f"タスク {task_uuid} 失敗：{error}")

    return jsonify({"received": True}), 200

if __name__ == "__main__":
    app.run(port=8080)

---

注意事項

1. URL は公開アクセス可能であること：source_url と target_url はいずれも直接ダウンロード可能な URL である必要があります。HTTP と HTTPS の両方に対応しています。
2. 顔インデックスのソートルール：source_face_index と target_face_index はいずれも 0 始まりで、顔の検出ボックス左上角の x 座標で左から右に並べ替えられます。
3. face_info の指定を強く推奨：すでに顔検出を呼び出している場合、検出された bbox を face_mapping に渡すことで、顔交換サービス内部の再検出による顔インデックスの不一致を防ぐことができます。
4. ポーリング間隔：タスク状態は 10 秒ごとにポーリングすることを推奨します。ビデオ顔交換は通常 30 秒〜数分で完了しますが、動画の長さと解像度によって異なります。
5. 結果フィールド名：出力フィールド名は output.videos で、顔交換後の動画 URL を返します。