AI 顔交換

統合ガイド

• AI 顔交換の実装方法

  • ステップ 1: ソース画像と参照画像のアップロード

    1. API からアップロード URL をリクエストします:
    POST https://yce-api-01.makeupar.com/s2s/v2.0/file
    Authorization: Bearer YOUR_API_KEY
    Content-Type: application/json

    ボディ:

    {
        "files": [
        {
            "file_name": "target.jpg",
            "file_size": 123456,
            "content_type": "image/jpeg"
        }
        ]
    }

    1. レスポンスには、事前署名付きの アップロード URL と file_id が含まれます。

    2. 指定された URL に対して HTTP PUT リクエストでファイルをアップロードします。

    3. 後で使用するために file_id を保存します。ターゲット画像と参照画像の両方に対してこの手順を繰り返します。

    4. 実際のファイルを アップロード URL にアップロードします。

• ステップ 2: ソース画像と参照画像の前処理（顔検出）

  1. 前処理タスクを作成します:
  POST https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

  ボディ:

  {
      "request_id": 1,
      "payload": {
      "file_sets": {
          "src_ids": ["TARGET_FILE_ID"]
      },
      "actions": [
          { "id": 0 }
      ]
      }
  }

  1. API は task_id を返します。
  2. タスクのステータスを次の URL でポーリングします:
  GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process?task_id=TASK_ID

  1. 完了すると、バウンディングボックス付きの検出された顔のリストを受け取ります。

• ステップ 3: 顔交換タスクの実行

  1. どの参照画像が各ソース画像を置き換えるかを定義します face_mapping 配列は、ソース画像内の顔が参照画像内の顔によってどのように置き換えられるかを定義します。これは、ソース内で検出された顔を特定の参照画像に接続するリンクリストとして機能します。

  • 構造

    配列内の各要素は、2 つのプロパティを含むオブジェクトです:

    パラメータ	型	説明
    position	integer	ソース画像内で検出された顔のインデックス（例: 0, 1, 2）。
    index	integer	交換対象となる参照画像リスト内の顔画像のインデックス。

    • ロジックルール

    1. インデックスマッピング: index は、参照リストに提供された画像の順序に直接対応します。

       • 0: 1 番目の参照画像。
       • 1: 2 番目の参照画像。

    2. 交換のスキップ: ソース内で検出された特定の顔の交換をスキップするには、index と position の両方を -1 に設定します。

    3. 配列の順序: 配列内のオブジェクトの順序は、position に基づいて一致させる必要があります。

       • 使用例

    シナリオ:

    • 参照リスト: 2 枚の画像を提供（画像 A、画像 B）。
    • ソース画像: 3 つの顔が検出される（顔 0、顔 1、顔 2）。

    目標:

    • 顔 0（ソース）を画像 1（参照）と交換する。
    • 顔 1（ソース）の交換をスキップする。
    • 顔 2（ソース）を画像 0（参照）と交換する。

    設定:

    "face_mapping": [
        {
            "index": 1,  // Use the second reference image
            "position": 0 // Apply to the first detected face in source
        },
        {
            "index": -1, // Skip swapping
            "position": -1 // Skip swapping
        },
        {
            "index": 0,  // Use the first reference image
            "position": 2 // Apply to the third detected face in source
        }
    ]

  1. メインタスクリクエストを送信します:
  POST https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

  ボディ:

  {
      "request_id": 2,
      "payload": {
      "file_sets": {
          "src_ids": ["TARGET_FILE_ID"],
          "ref_ids": ["REFERENCE_FILE_ID"]
      },
      "actions": [
          {
          "id": 0,
          "params": {
              "face_mapping": [
              { "index": 0, "position": 0 },
              { "index": -1, "position": -1 }
              ]
          }
          }
      ]
      }
  }

  1. レスポンスには task_id が返されます。

• ステップ 4: タスクステータスのポーリングと結果の取得 許可されたポーリングウィンドウ内で、一定の間隔でタスクステータスを照会するタイミングループを実装する必要があります。

  1. 次の URL でポーリングします:
  GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap?task_id=TASK_ID

  2. status が success になると、レスポンスには生成された画像の URL が含まれます。
  3. その URL から画像をダウンロードまたは表示します。

• ステップ 5: プラットフォームへの統合

  • Web フロントエンドでは、fetch または Axios を使用して JavaScript で直接実装できます。
  • バックエンド（Node.js、Python、Java、PHP など）では、標準的な HTTP ライブラリを使用して同じエンドポイントを使用できます。
  • タスクは非同期で実行されるため、リトライとエラーハンドリングを実装してください。

• デバッグガイド

  1. Invalid TaskId エラー
     理由: タイムアウトしたタスクのステータスを確認しようとすると、InvalidTaskId エラーが発生します。したがって、AI タスクが開始されたら、ステータスが success または error に変わるまで、polling_interval 内でステータスをポーリングする必要があります。
     解決策: タスクが無効になるのを避けるために、許可されたポーリングウィンドウ内で一定の間隔でタスクステータスを照会するタイミングループを実装する必要があります。

  2. ソース画像で一部の顔が検出されない理由
     理由: 顔がはっきりと見えており、覆われたり遮られたりしておらず、画像内で十分に大きい必要があります。
     解決策: 顔が大きく写っており、覆いや遮りがなくはっきりと見える写真を撮影してみてください。

入力と出力

• 実際の例: 複数顔交換サンプル:

単一顔交換サンプル:

• 撮影方法の提案:

ファイル仕様とエラー

• 対応フォーマットと寸法

• エラーコード

ユニット消費量