AI Retake

整合指南

• 如何實作 AI Retake

  • 步驟 1：上傳來源與參考圖片

    1. 向 API 請求上傳網址：
    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. 回應會提供預簽名的上傳網址與 file_id。

    2. 使用 HTTP PUT 請求，將檔案上傳到指定的網址。

    3. 儲存 file_id 以供後續使用。對目標與參考圖片都重複此步驟。

    4. 將實際檔案上傳到上傳網址。

• 步驟 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

  內容：

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

  1. API 回傳 task_id。
  2. 在此輪詢任務狀態：
  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 陣列定義來源圖片中的臉部如何被參考圖片中的臉部取代。它作為連結清單，將來源中偵測到的臉部連接到特定的參考圖片。

  每次請求僅支援一次臉部替換。所有非目標臉部都必須設為 {"index": -1, "position": -1}。嘗試替換多於一張臉部會回傳 error_change_too_many_faces。回傳此錯誤的請求不會計費。僅支援參考圖片中偵測到的第一張臉部，因此 index 必須恆為 0。

  • 參數

• 規則

  • 單張臉部替換：每次請求僅能將一張來源臉部對應到參考臉部。
  • 跳過某張臉部：將 index 與 position 都設為 -1。
  • 參考臉部索引：僅支援參考圖片中偵測到的第一張臉部，因此 index 恆為 0。

• 範例

  情境

  • 參考圖片：1 張包含單張受支援臉部的圖片。
  • 來源圖片：偵測到 4 張臉部（Face 0、Face 1、Face 2、Face 3）。
  • 目標：僅替換 Face 2，保持 Face 0、Face 1 與 Face 3 不變。
      "face_mapping": [
          {
              "index": -1, // 跳過替換
              "position": -1 // 跳過替換
          },
          {
              "index": -1, // 跳過替換
              "position": -1 // 跳過替換
          },
          {
              "index": 0, // 恆使用第一張參考圖片
              "position": 2 // 套用到來源中偵測到的第三張臉部
          },
          {
              "index": -1, // 跳過替換
              "position": -1 // 跳過替換
          },
      ]

1. 發送主要任務請求：

內容：

1. 回應會回傳 task_id。

• 步驟 4：輪詢任務狀態並取得結果 必須實作定時迴圈，在允許的輪詢窗口內以固定間隔查詢任務狀態。

  1. 輪詢：
  GET https://yce-api-01.makeupar.com/s2s/v2.0/task/retake?task_id=TASK_ID

  2. 當 status 為 success 時，回應包含生成影像的網址。
  3. 從該網址下載或顯示圖片。

• 步驟 5：整合到您的平台

  • 在網頁前端，您可以直接用 JavaScript 以 fetch 或 Axios 實作。
  • 在後端（Node.js、Python、Java、PHP 等），您可以使用標準 HTTP 函式庫呼叫相同的端點。
  • 由於任務以非同步執行，請實作重試與錯誤處理。

• 除錯指南

  1. 為什麼我的來源圖片中有些臉部未被偵測到
     原因： 臉部必須清晰可見，未被覆蓋或遮擋，且在圖片中足夠大
     解法： 嘗試拍攝臉部看起來更大、且清晰可見無任何覆蓋或遮擋的照片

輸入與輸出

• 實際範例：

檔案規格與錯誤

• 支援的格式與尺寸

• 錯誤代碼

點數消耗