Image FaceSwap Pro API の使い方：顔交換統合ガイド（2026）

AI画像FaceSwap Pro: 単一人物の自動フェイススワップと複数人物のキーポイント精密マッピングに対応し、高い制御性が求められるフェイススワップシナリオに適しています。

NamiFusion Image FaceSwap Proは、高精度なシナリオ向けに設計された画像フェイススワップAPIです。単一人物の自動モード（文字列URL）と複数人物の精密モード（オブジェクト配列 + キーポイント）の2種類の入力方式をサポートしており、さまざまな業務シナリオで使いやすさと制御性のバランスを取ることができます。

主な機能

• 単一人物の自動フェイススワップ: sourceImageとtargetImageを文字列URLとして直接渡すと、システムが顔のキーポイントを自動検出します。
• 複数人物の精密マッピング: ImageWithKeypoints[]を使用し、optsにキーポイントを渡すことで、インデックスごとに1対1で対応付けて処理します。
• オプションの顔補正: face_enhanceはboolean値のみをサポートします。有効にすると、顔の欠点を除去し、見た目を改善します。
• 統一された入力構造: 文字列形式とオブジェクト配列形式の両方をサポートします。

技術仕様

クイックスタート

APIエンドポイント

リクエストパラメータ概要

リクエストボディ内のFaceSwap Pro関連の主要フィールドは以下のとおりです。

{
  "sourceImage": "string | ImageWithKeypoints[]",
  "targetImage": "string | ImageWithKeypoints[]",
  "face_enhance": "boolean"
}

認証

サービスゲートウェイで必要な場合は、リクエストヘッダーにAPI Keyを含めてください。

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

標準的な呼び出しフロー

FaceSwap Proは非同期タスク方式を採用しています。

1. POST /api/v1/marketplace/run/namifusion/faceswap-image-pro を呼び出してタスクを送信します。
2. レスポンスから task_uuid を取得します。
3. GET /api/v1/marketplace/run/tasks/{task_uuid} を呼び出してタスクのステータスをポーリングします。
4. status が completed になったらレスポンス内の output から結果を取得し、failed の場合は error_message を確認します。

ステップ1: タスクを送信

curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/faceswap-image-pro" \
  -H "X-API-Key: sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "sourceImage": "https://example.com/source.jpg",
      "targetImage": "https://example.com/target.jpg",
      "face_enhance": false
    }
  }'

送信成功レスポンス例:

{
  "task_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "estimated_time": 150,
  "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",
  "model_id": "namifusion/faceswap-image-pro",
  "status": "processing",
  "output": null,
  "error_message": null,
  "created_at": "2026-04-13T10:00:00Z",
  "completed_at": null
}

完了レスポンス例:

{
  "task_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "model_id": "namifusion/faceswap-image-pro",
  "status": "completed",
  "output": {
    "image_url": "https://cdn.namifusion.com/result/faceswap_pro_abc123.jpg"
  },
  "cost_credits": 10,
  "error_message": null,
  "created_at": "2026-04-13T10:00:00Z",
  "completed_at": "2026-04-13T10:00:12Z"
}

失敗レスポンス例:

{
  "task_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "model_id": "namifusion/faceswap-image-pro",
  "status": "failed",
  "output": null,
  "cost_credits": 10,
  "error_message": "Face swap failed because no valid face was detected in targetImage.",
  "created_at": "2026-04-13T10:00:00Z",
  "completed_at": "2026-04-13T10:00:08Z"
}