AI 照片換臉

整合指南

• 如何實作 AI 照片換臉

  • 步驟 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/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. 在此輪詢任務狀態：
  GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process?task_id=TASK_ID

  1. 完成後，您會收到帶有邊界框的偵測臉部清單。

• 步驟 3：執行換臉任務

  1. 定義哪個參考圖片將取代每個來源圖片 face_mapping 陣列定義來源圖片中的臉部如何被參考圖片中的臉部取代。它就像一個連結清單，將來源中偵測到的臉部連接到特定的參考圖片。

  • 結構

    陣列中的每個元素都是包含兩個屬性的物件：

    參數	類型	說明
    position	integer	在來源圖片中偵測到的臉部索引（例如 0、1、2）。
    index	integer	要交換的參考圖片清單中臉部圖片的索引。

    • 邏輯規則

    1. 索引對應： index 直接對應您參考清單中提供圖片的順序。

       • 0：第一張參考圖片。
       • 1：第二張參考圖片。

    2. 跳過交換： 若要跳過交換來源中某個被偵測到的臉部，請將 index 與 position 都設為 -1。

    3. 陣列順序： 陣列中物件的順序，應依據 position 對應。

       • 使用範例

    情境：

    • 參考清單： 提供 2 張圖片（圖片 A、圖片 B）。
    • 來源圖片： 包含 3 個被偵測到的臉部（臉 0、臉 1、臉 2）。

    目標：

    • 將臉 0（來源）與圖片 1（參考）交換。
    • 跳過交換臉 1（來源）。
    • 將臉 2（來源）與圖片 0（參考）交換。

    設定：

    "face_mapping": [
        {
            "index": 1,  // 使用第二張參考圖片
            "position": 0 // 套用到來源中偵測到的第一張臉部
        },
        {
            "index": -1, // 跳過換臉
            "position": -1 // 跳過換臉
        },
        {
            "index": 0,  // 使用第一張參考圖片
            "position": 2 // 套用到來源中偵測到的第三張臉部
        }
    ]

  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. 輪詢：
  GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap?task_id=TASK_ID

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

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

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

• 除錯指南

  1. Invalid TaskId 錯誤
     原因： 若您嘗試查詢已逾時任務的狀態，會收到 InvalidTaskId 錯誤。因此，AI 任務啟動後，您需要在 polling_interval 內輪詢其狀態，直到狀態變為 success 或 error。
     解法： 為避免任務失效，必須實作定時迴圈，在允許的輪詢窗口內以固定間隔查詢任務狀態。

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

輸入與輸出

• 實際範例： 多人換臉範例：

單人換臉範例：

• 拍攝建議：

檔案規格與錯誤

• 支援的格式與尺寸

• 錯誤代碼

點數消耗