Image FaceSwap Pro

NamiFusion Image FaceSwap Pro

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

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

---

主な機能

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

---

技術仕様

パラメータ	詳細
主要入力フィールド	sourceImage、targetImage、face_enhance
画像オブジェクト構造	ImageWithKeypoints（path + opts）
単一人物モード入力	文字列URL / パス
複数人物モード入力	ImageWithKeypoints[] 配列

---

クイックスタート

APIエンドポイント

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

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

リクエストボディ内の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"
}

---

前提手順: Detect Facesを呼び出してImageWithKeypointsを組み立てる

複数人物フェイススワップのシナリオでは、まず顔検出APIを呼び出して各顔のlandmarks_strを取得し、それをFaceSwap Proが必要とするoptsフィールドに組み立てることを推奨します。

ステップ1: Detect Facesを呼び出す

検出エンドポイント（非同期）:

• POST /api/v1/marketplace/run/namifusion/detect_faces
• GET /api/v1/marketplace/run/tasks/{task_uuid}

リクエスト例（ターゲット画像の顔検出）:

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_target.jpg",
      "return_face_url": true
    }
  }'

検出完了後、output.faces_obj["0"]から以下の主要フィールドを参照できます。

• landmarks_str[i]: そのままoptsとして使用可能
• face_urls[i]: 切り出し済み単一顔画像のURLとして使用可能。source側に適しています
• region[i]: 顔のバウンディングボックス情報。調査や可視化に利用できます

検出結果スニペット例:

{
  "output": {
    "faces_obj": {
      "0": {
        "landmarks_str": [
          "402,486:614,489:511,626:506,702",
          "120,85:180,88:150,130:150,165"
        ],
        "face_urls": [
          "https://example.com/faces/source_face_0.jpg",
          "https://example.com/faces/source_face_1.jpg"
        ],
        "region": [
          [278, 219, 442, 640],
          [80, 50, 150, 180]
        ]
      }
    }
  }
}

ステップ2: ImageWithKeypointsを組み立てる

ImageWithKeypointsの構造は以下のとおりです。

{
  "path": "https://example.com/face_or_image.jpg",
  "opts": "402,486:614,489:511,626:506,702"
}

推奨される組み立てルール:

• sourceImage: 返却されたface_urls[i]をpathとして、landmarks_str[i]をoptsとして使用することを推奨します
• targetImage: 各要素のpathとして同じターゲット画像URLを使用し、対応するターゲット側のlandmarks_str[i]をoptsとして使用できます
• sourceImage[i]とtargetImage[i]が同じ置換ペアを表すようにしてください

組み立て例:

{
  "sourceImage": [
    {
      "path": "https://example.com/faces/source_face_0.jpg",
      "opts": "402,486:614,489:511,626:506,702"
    }
  ],
  "targetImage": [
    {
      "path": "https://example.com/group_target.jpg",
      "opts": "120,85:180,88:150,130:150,165"
    }
  ],
  "face_enhance": true
}

---

シナリオ1: 単一人物フェイススワップ（キーポイント自動検出）

ソース画像とターゲット画像の両方に1つの顔しか含まれないシナリオに適しています。この場合、sourceImageとtargetImageは文字列として直接渡すことができます。

リクエスト例

{
  "sourceImage": "https://example.com/source.jpg",
  "targetImage": "https://example.com/target.jpg",
  "face_enhance": false
}

動作説明

• sourceImageまたはtargetImageが文字列の場合、バリデーション層で自動的に以下へ変換されます:
  • [{"path": "<value>", "opts": ""}]
• optsが空文字列であることは、キーポイントを手動で渡していないことを意味します。
• パイプラインは自動キーポイント検出フローに入り、単一ペアの顔処理を行います。

---

シナリオ2: 複数人物フェイススワップ（手動キーポイントマッピング）

顔の対応関係を明示的に指定する必要があるシナリオに適しています。この場合、sourceImageとtargetImageの両方にオブジェクト配列を渡し、sourceImage[0]はtargetImage[0]、sourceImage[1]はtargetImage[1]というように、インデックス単位で厳密にマッピングを構築する必要があります。

補足: sourceImageには複数の異なるソース画像を渡して、複数の顔ソースを提供できます。一方で、targetImageは同じターゲット画像を維持する必要があります。最終的な出力結果はその1枚のtargetImageを基準に生成されます。

リクエスト例

{
  "sourceImage": [
    {
      "path": "https://example.com/source_face_1.jpg",
      "opts": "145.2,210.8:188.1,209.6:166.7,241.3:165.9,272.4"
    },
    {
      "path": "https://example.com/source_face_2.jpg",
      "opts": "320.4,198.2:360.8,197.0:340.2,228.1:339.7,258.6"
    }
  ],
  "targetImage": [
    {
      "path": "https://example.com/target.jpg",
      "opts": "512.1,301.4:548.9,299.8:530.0,330.2:529.0,360.5"
    },
    {
      "path": "https://example.com/target.jpg",
      "opts": "710.2,288.6:748.7,287.1:729.9,317.7:729.1,349.2"
    }
  ],
  "face_enhance": true
}

動作説明

• パイプラインはzip(sourceImage, targetImage)方式で処理を行い、2つの配列は同じインデックス同士で1対1に対応付けられます。
• 複数ペアを処理する場合、各ペアはsource側とtarget側の両方で有効なoptsを提供する必要があります。
• キーポイントが欠落している場合や形式が不正な場合、実行時バリデーションエラーが発生する可能性があります。

---

パラメータと戻り値の詳細

リクエストパラメータ

トップレベルフィールド

パラメータ	型	必須	説明
sourceImage	string | ImageWithKeypoints[]	はい	ソース画像入力。文字列は単一人物の自動モード、オブジェクト配列は複数人物の精密モードで使用します。
targetImage	string | ImageWithKeypoints[]	はい	ターゲット画像入力。文字列は単一人物の自動モード、オブジェクト配列は複数人物の精密モードで使用します。
face_enhance	boolean	いいえ	顔補正スイッチ。boolean値のみサポートします。

ImageWithKeypoints構造

フィールド	型	必須	説明
path	string	はい	画像URLまたはローカルパス。
opts	string	いいえ	キーポイント文字列。形式は"x1,y1:x2,y2:x3,y3:x4,y4"です。空文字列は手動キーポイントなしを表します。

バリデーションルールとよくあるエラー

face_enhance

• 許可: true / false
• 拒否: 任意の整数（0 / 1を含む）およびその他の非boolean型

sourceImage / targetImage

• 文字列入力をサポートし、内部で単一要素のオブジェクト配列へ自動変換されます。
• 配列入力はImageWithKeypoints構造に従う必要があります。
• 複数人物モードでは、両側の配列長を一致させ、インデックスで揃えることを推奨します。

opts

• 形式はx,y:x,y:...を満たす必要があります
• 点と点の区切りには:を使用し、各点はx,yで表現します
• 複数人物モードでは、各ペアが空でないoptsを提供する必要があります

---

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

パラメータ組み合わせ	結果への影響
sourceImage / targetImageが文字列	単一人物の自動モードに入り、システムがキーポイントを自動検出します。
sourceImage / targetImageがオブジェクト配列 + 有効なopts	複数人物の精密モードに入り、インデックス単位で1対1にフェイススワップを行います。
face_enhance: true	顔補正を有効にし、通常は顔の見た目を改善します。
face_enhance: false	追加の顔補正を有効にせず、デフォルトのフェイススワップフローを使用します。

---

注意事項

1. 複数人物モードでは配列を揃える必要があります: sourceImage[i]はtargetImage[i]とペアで処理されます。配列の長さと順序を一致させてください。
2. キーポイント形式は厳密です: optsがx,y:x,y:...に一致しない場合、解析に失敗します。
3. 文字列入力は自動的にラップされます: 顔マッピングを厳密に制御したい場合は、明示的にオブジェクト配列を使用し、optsを渡してください。
4. 公開アクセス可能なURLを推奨します: サービス側で画像リソースを安定して取得しやすくなります。