AI リテイク

統合ガイド

• AI Retake の実装方法

  • ステップ 1: 元画像と参照画像をアップロードする

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

    Body:

    {
        "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/retake/pre-process
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

  Body:

  {
      "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/retake/pre-process?task_id=TASK_ID

  1. 完了すると、検出された顔のリストと、それぞれのバウンディングボックスが返されます。

• ステップ 3: AI Retake タスクを実行する

  1. どの参照画像で元画像の顔を置き換えるかを定義する face_mapping 配列は、元画像（Source Image）の顔を 参照画像（Reference Images）の顔でどのように置き換えるかを定義します。元画像で検出された顔と、特定の参照画像とを結ぶリンクリストとして機能します。

  • 構造

    配列の各要素は、次の 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 replacing
            "position": -1 // Skip replacing
        },
        {
            "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/retake
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

  Body:

  {
      "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/retake?task_id=TASK_ID

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

• ステップ 5: ご自身のプラットフォームに統合する

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

• デバッグガイド

  1. 元画像の一部の顔が検出されないのはなぜですか
     理由: 顔がはっきり写っており、覆われたり遮られたりしておらず、画像内で十分に大きいサイズである必要があります
     解決方法: 顔を大きく写し、覆いや遮るものなくはっきり確認できる写真で撮り直してください

入力と出力

• 実際の例：

対応ファイル仕様とエラー

• サポートされている形式と寸法

• エラーコード

ユニット消費量