# AI 照片換臉 # 概述 使用 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 ``` 內容： ```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 ``` 內容： ```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** （參考）交換。 **設定：** ```json "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 ``` 內容： ```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 ``` 1. 當 `status` 為 `success` 時，回應包含生成影像的網址。 2. 從該網址下載或顯示圖片。 --- * 步驟 5：整合到您的平台 * 在 **網頁前端** ，您可以直接用 JavaScript 以 fetch 或 Axios 實作。 * 在 **後端** （Node.js、Python、Java、PHP 等），您可以使用標準 HTTP 函式庫呼叫相同的端點。 * 由於任務以非同步執行，請實作重試與錯誤處理。 --- * 除錯指南 1. **Invalid TaskId 錯誤** **原因：** 若您嘗試查詢已逾時任務的狀態，會收到 InvalidTaskId 錯誤。因此，AI 任務啟動後，您需要在 polling_interval 內輪詢其狀態，直到狀態變為 success 或 error。 **解法：** 為避免任務失效，必須實作定時迴圈，在允許的輪詢窗口內以固定間隔查詢任務狀態。 2. **為什麼我的來源圖片中有些臉部未被偵測到** **原因：** 臉部必須清晰可見，未被覆蓋或遮擋，且在圖片中足夠大 **解法：** 嘗試拍攝臉部看起來更大、且清晰可見無任何覆蓋或遮擋的照片 --- ## 輸入與輸出 * 實際範例： 多人換臉範例： ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_face_swap_S2_img_04_d4b747a41d.jpg) 單人換臉範例： ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_face_swap_S2_img_05_8e68faff2c.jpg) * 拍攝建議： ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png) ## 檔案規格與錯誤 * 支援的格式與尺寸 | AI 功能 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 | | --- | --- | --- | --- | | AI 照片換臉 | 輸入與輸出：長邊必須小於或等於 4096 像素 | < 10MB | jpg/jpeg/png | * 錯誤代碼 | 錯誤代碼 | 說明 | | --- | --- | | exceed_max_filesize | 輸入檔案大小超過上限 | | invalid_parameter | 參數值無效 | | error_download_image | 下載來源圖片時發生錯誤 | | error_download_mask | 下載遮罩圖片時發生錯誤 | | error_decode_image | 解碼來源圖片時發生錯誤 | | error_decode_mask | 解碼遮罩圖片時發生錯誤 | | error_download_video | 下載來源影片時發生錯誤 | | error_decode_video | 解碼來源影片時發生錯誤 | | error_nsfw_content_detected | 在來源圖片中偵測到 NSFW 內容 | | error_no_face | 來源圖片中未偵測到臉部 | | error_pose | 在來源圖片偵測姿勢失敗 | | error_face_parsing | 在來源圖片進行人臉解析失敗 | | error_inference | 推論流程發生錯誤 | | exceed_nsfw_retry_limits | 超過重試上限，以避免生成 NSFW 圖片 | | error_upload | 上傳結果圖片時發生錯誤 | | error_multiple_people | 人數超過上限 | | error_no_shoulder | 來源圖片中肩膀不可見 | | error_large_face_angle | 上傳圖片的臉部角度過大 | | error_unsupport_ratio | 輸入圖片的長寬比不受支援 | | unknown_internal_error | 其他內部錯誤 | --- ## 點數消耗 | AI 功能 | 消耗的點數 | | --- | --- | | AI 照片換臉 V1.0 | 1 | --- License: Privacy policy ## Servers ``` https://yce-api-01.makeupar.com ``` ## Security ### BearerAuthenticationV2 使用標準的 'Bearer authentication'。請在標頭中放入您的 'API Key'：`Authorization:Bearer YOUR_API_KEY`。請注意 'Bearer' 與 'YOUR_API_KEY' 之間有一個空格。 Type: http Scheme: bearer ## Download OpenAPI description - [AI 照片換臉](https://docs.perfectcorp.com/_bundle/@l10n/zh-TW/reference/ai_face_swap.yaml) ## V1.0 - [POST /s2s/v2.0/task/face-swap/pre-process](https://docs.perfectcorp.com/zh-tw/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1pre-process/post.md): 當來源照片可能包含超過一個有效目標，或您的整合需要明確選擇哪個被偵測到的目標接受特效時，請使用前處理任務。對於單一目標的圖片，當功能支援預設的 `index` 值，且您的應用程式不需要手動選擇目標時，可以跳過前處理。 前處理任務會偵測來源照片中的候選目標，並在 `data.results.result` 中回傳它們的座標。結果陣列中的每個項目代表一個被偵測到的目標。檢視回傳的座標，將它們對應到來源 - [GET /s2s/v2.0/task/face-swap/pre-process/{task_id}](https://docs.perfectcorp.com/zh-tw/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1pre-process~1%7Btask_id%7D/get.md) - [POST /s2s/v2.0/task/face-swap](https://docs.perfectcorp.com/zh-tw/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap/post.md): AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 `success` 或 `error` 通知後，使用收到的 `task_id` 查詢任務結果。設定與驗證細節請見 [webhook 整合指南](/develop/webhook)。 若您的整合不支援 webhook 或無法使用 - [GET /s2s/v2.0/task/face-swap/{task_id}](https://docs.perfectcorp.com/zh-tw/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1%7Btask_id%7D/get.md)