namifusion 画像 フェイススワップ

NamiFusion Image FaceSwap

AI画像フェイススワップ：単一人物の自動フェイススワップと複数人物の精密マッピングに対応し、顔検出と組み合わせて完全なフェイススワップワークフローを実現。

NamiFusion Image FaceSwapは、高品質なAI画像フェイススワップサービスで、ソース顔をターゲット画像に置き換えることができます。単一人物フェイススワップ（自動モード）と複数人物フェイススワップ（精密マッピングモード）の2つのモードを提供し、NamiFusion Detect Facesと組み合わせることで、顔検出からフェイススワップまでの完全なワークフローを実現できます。

---

主な機能

• 単一人物フェイススワップ： single_face_modeを有効にするだけで、追加設定なしに自動的にフェイススワップが完了します。
• 複数人物精密マッピング： face_mappingを使用して、ソース顔とターゲット顔の対応関係を正確に指定でき、1対1および多対多のマッピングに対応しています。
• 顔補正： オプションの高度な美顔機能で、自動的に肌を滑らかにし、顔の欠点を除去して、スワップ後の顔品質を向上させます。
• 非同期タスク： 送信後にtask_uuidを返し、ポーリングまたはWebhookで結果を取得します。

---

技術仕様

パラメータ	詳細
モデルID	namifusion/faceswap-image
リクエスト方式	非同期POST（タスク送信 + ポーリング/Webhookで結果取得）
入力	ソース顔画像URL + ターゲット画像URL
出力	フェイススワップ後の画像URL
処理時間	通常5〜15秒

---

クイックスタート

APIエンドポイント

エンドポイント	メソッド	説明
/api/v1/marketplace/run/namifusion/faceswap-image	POST	フェイススワップタスクを送信
/api/v1/marketplace/run/tasks/{task_uuid}	GET	タスクのステータスと結果を照会

認証

リクエストヘッダーにAPIキーを含めてください：

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

---

シナリオ1：単一人物フェイススワップ（最もシンプルな使い方）

ソース画像とターゲット画像の両方に顔が1つだけ含まれているシナリオに適しています。single_face_modeを有効にすると、face_mappingの設定は不要で、サービスが自動的にフェイススワップを完了します。

ステップ1：フェイススワップタスクを送信

curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/faceswap-image" \
  -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_photo.jpg",
      "single_face_mode": true
    }
  }'

レスポンス例：

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

ステップ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-image",
  "status": "completed",
  "output": {
    "videos": ["https://cdn.namifusion.com/result/faceswap_abc123.jpg"]
  },
  "cost_credits": 10,
  "created_at": "2026-02-27T10:00:00Z",
  "completed_at": "2026-02-27T10:00:12Z"
}

出力フィールド名はvideosですが、画像フェイススワップの場合は画像URLが返されます。このフィールド名はフェイススワップ結果ファイルの格納に統一的に使用されています。

---

シナリオ2：複数人物フェイススワップ

ターゲット画像に複数の顔があり、「どのソース顔でどのターゲット顔を置き換えるか」を正確に制御する必要がある場合、まずDetect Facesを呼び出して顔情報を取得し、次にface_mappingを構築してフェイススワップタスクを送信する必要があります。

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

NamiFusion Detect Faces（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/group_photo.jpg",
      "return_face_url": true
    }
  }'

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

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

完了レスポンス（3つの顔が検出された場合）：

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

これでターゲット画像に3つの顔があること（faces_obj["0"].regionの長さは3）と、それぞれのface_urlsがわかりました。

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

同様に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/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を構築

検出結果に基づいて、ソース顔からターゲット顔へのマッピング関係を構築します。ここで、source_face_info.face_urlとtarget_face_info.face_urlの画像にはそれぞれ1つの顔のみが含まれています。

Detect Facesが返した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_1.jpg"
    }
  }
]

face_urlの値は、ステップ1と2でDetect Facesが返した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-image" \
  -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/group_photo.jpg",
      "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_1.jpg"
          }
        }
      ]
    }
  }'

レスポンス：

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

ステップ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-image",
  "status": "completed",
  "output": {
    "videos": ["https://cdn.namifusion.com/result/faceswap_def456.jpg"]
  },
  "cost_credits": 10,
  "created_at": "2026-02-27T10:05:00Z",
  "completed_at": "2026-02-27T10:05:14Z"
}

---

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/group_photo.jpg"


def detect_faces(image_url):
    """Submit face detection task and poll for result."""
    task = requests.post(
        f"{BASE_URL}/namifusion/detect_faces",
        headers=HEADERS,
        json={"input": {"url": image_url, "return_face_url": True}},
    ).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", "Unknown error"))

        time.sleep(3)


# Step 1: detect faces in target image
target_detect = detect_faces(target_url)
target_frame = target_detect["faces_obj"]["0"]

print(f"Target has {len(target_frame['face_urls'])} faces")
for i, face_url in enumerate(target_frame["face_urls"]):
    print(f"  Face {i}: region={target_frame['region'][i]}")

# Step 2: detect faces in source image
source_detect = detect_faces(source_url)
source_frame = source_detect["faces_obj"]["0"]

# Step 3: build face_mapping (replace target face 1 with source face 0)
face_mapping = [
    {
        "source_face_info": {"face_url": source_frame["face_urls"][0]},
        "target_face_info": {"face_url": target_frame["face_urls"][1]},
    }
]

# Step 4: submit faceswap task
task_resp = requests.post(
    f"{BASE_URL}/namifusion/faceswap-image",
    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 submitted: {task_uuid}")

# Step 5: poll for result
while True:
    status_resp = requests.get(
        f"{BASE_URL}/tasks/{task_uuid}",
        headers=HEADERS,
    ).json()

    status = status_resp["status"]
    print(f"Status: {status}")

    if status == "completed":
        result_url = status_resp["output"]["videos"][0]
        print(f"Result: {result_url}")
        break
    elif status == "failed":
        print(f"Failed: {status_resp.get('error_message', 'Unknown error')}")
        break

    time.sleep(5)

---

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

リクエストパラメータ

リクエストボディは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（ターゲットに置き換える顔）。公開アクセス可能である必要があります。
target_url	string	はい	-	ターゲット画像URL（フェイススワップされる画像）。公開アクセス可能である必要があります。
single_face_mode	boolean	いいえ	true	単一顔モード。有効にすると、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始まり、左から右にソート）。
target_face_index	integer	はい	ターゲット画像内の顔のインデックス（0始まり、左から右にソート）。
source_face_info	object	いいえ	ソース顔の座標情報。指定すると内部の再検出をスキップし、顔の順序の一貫性を保証します。
target_face_info	object	いいえ	ターゲット顔の座標情報。指定するとマッチング精度が向上します。

source_face_infoフィールド

フィールド	型	説明
bbox	number[]	顔のバウンディングボックス [x1, y1, x2, y2]。
kps	number[][]	顔の5つのキーポイント座標。指定するとバックエンドが直接使用し、再検出をスキップします。

target_face_infoフィールド

フィールド	型	説明
bbox	number[]	ターゲット顔のバウンディングボックス [x1, y1, x2, y2]。

タスクステータス

タスク送信後、ポーリングでステータスを取得します。推奨ポーリング間隔：5秒。

ステータス	説明
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-image）。
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	自動的にフェイススワップを完了します。単一人物シナリオに適しており、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"	ロスレススタイル。究極のロスレスモードで、元の顔のすべてのディテールを完璧に保持し、最高のリアリズムでほぼ見分けがつきません。

---

注意事項

1. URLは公開アクセス可能である必要があります：source_urlとtarget_urlはどちらも直接ダウンロード可能な公開URLである必要があります。
2. 顔インデックスのソートルール：source_face_indexとtarget_face_indexはどちらも0から始まり、顔bboxの左上隅のx座標に基づいて左から右にソートされます。
3. face_infoの受け渡しを強く推奨：Detect Facesを既に呼び出している場合、検出されたbboxをface_mappingに渡すことで、フェイススワップサービス内部の再検出によるインデックスの不一致問題を回避できます。
4. ポーリング間隔：5秒ごとにタスクステータスをポーリングすることを推奨します。画像フェイススワップは通常5〜15秒で完了します。
5. 結果フィールド名：出力フィールド名はoutput.videosですが、画像フェイススワップの場合は画像URLが返されます。これはAPIの統一的な命名規則です。