{"templateId":"api_docs","sharedDataIds":{"apiDocsStore":"api-docs-@l10n/zh-TW/reference/ai_face_swap.yaml","sidebar":"sidebar-@l10n/zh-TW/reference/sidebars.yaml"},"props":{"definitionId":"@l10n/zh-TW/reference/ai_face_swap.yaml","settings":{"baseUrlPath":"/zh-tw/reference/ai_face_swap"},"disableAutoScroll":true,"seo":{"title":"AI 照片換臉","description":"YouCam API documentation by Perfect Corp. Learn how to use Skin analysis API, Virtual try-on API, Image editing API, and Video generative AI APIs.","siteUrl":"https://docs.perfectcorp.com","keywords":"AI Skin Analysis, AI Clothes, AI Hairstyle, AI Outfits","image":"/assets/favicon.cd6fa4d833b2a573b3c6dae68386b293da205b203402cb0c97b80bd2acc07ea2.8351e24f.png"},"dynamicMarkdocComponents":[],"metadata":{"type":"openapi","title":"AI 照片換臉","version":"","description":"# 概述\n使用 AI 照片換臉達到極其逼真的效果，並支援多張臉部。我們的人臉交換人工智慧支援交換一或多張臉部。無論是創造有趣的人臉照片，或需要專業工具，我們都能滿足您的需求。\n\n## 整合指南\n* 如何實作 AI 照片換臉\n\n   * 步驟 1：上傳來源與參考圖片\n\n      1. 向 API 請求上傳網址：\n\n        ```\n        POST https://yce-api-01.makeupar.com/s2s/v2.0/file\n        Authorization: Bearer YOUR_API_KEY\n        Content-Type: application/json\n        ```\n\n        內容：\n\n        ```json\n        {\n            \"files\": [\n            {\n                \"file_name\": \"target.jpg\",\n                \"file_size\": 123456,\n                \"content_type\": \"image/jpeg\"\n            }\n            ]\n        }\n        ```\n        1. 回應會提供預簽名的**上傳網址**與 `file_id`。\n        2. 使用 HTTP PUT 請求，將檔案上傳到指定的網址。\n        3. 儲存 `file_id` 以供後續使用。對**目標**與**參考**圖片都重複此步驟。\n\n      2. 將實際檔案上傳到**上傳網址**。\n\n---\n\n   * 步驟 2：前處理來源與參考圖片（臉部偵測）\n\n        1. 建立前處理任務：\n\n        ```\n        POST https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process\n        Authorization: Bearer YOUR_API_KEY\n        Content-Type: application/json\n        ```\n\n        內容：\n\n        ```json\n        {\n            \"request_id\": 1,\n            \"payload\": {\n            \"file_sets\": {\n                \"src_ids\": [\"TARGET_FILE_ID\"]\n            },\n            \"actions\": [\n                { \"id\": 0 }\n            ]\n            }\n        }\n        ```\n        1. API 回傳 `task_id`。\n        2. 在此輪詢任務狀態：\n\n        ```\n        GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process?task_id=TASK_ID\n        ```\n        1. 完成後，您會收到帶有邊界框的偵測臉部清單。\n\n---\n\n   * 步驟 3：執行換臉任務\n        1. 定義哪個參考圖片將取代每個來源圖片\n        `face_mapping` 陣列定義**來源圖片**中的臉部如何被**參考圖片**中的臉部取代。它就像一個連結清單，將來源中偵測到的臉部連接到特定的參考圖片。\n\n        * 結構\n\n            陣列中的每個元素都是包含兩個屬性的物件：\n\n            | 參數 | 類型 | 說明 |\n            | :--- | :--- | :--- |\n            | `position` | `integer` | 在**來源圖片**中偵測到的臉部索引（例如 0、1、2）。 |\n            | `index` | `integer` | 要交換的**參考圖片清單**中臉部圖片的索引。 |\n\n                * 邏輯規則\n            1.  **索引對應：** `index` 直接對應您參考清單中提供圖片的順序。\n                *   `0`：第一張參考圖片。\n                *   `1`：第二張參考圖片。\n            2.  **跳過交換：** 若要跳過交換來源中某個被偵測到的臉部，請將 `index` 與 `position` 都設為 `-1`。\n            3.  **陣列順序：** 陣列中物件的順序，應依據 `position` 對應。\n\n                * 使用範例\n\n            **情境：**\n            *   **參考清單：** 提供 2 張圖片（圖片 A、圖片 B）。\n            *   **來源圖片：** 包含 3 個被偵測到的臉部（臉 0、臉 1、臉 2）。\n\n            **目標：**\n            *   將**臉 0**（來源）與**圖片 1**（參考）交換。\n            *   跳過交換**臉 1**（來源）。\n            *   將**臉 2**（來源）與**圖片 0**（參考）交換。\n\n            **設定：**\n\n            ```json\n            \"face_mapping\": [\n                {\n                    \"index\": 1,  // 使用第二張參考圖片\n                    \"position\": 0 // 套用到來源中偵測到的第一張臉部\n                },\n                {\n                    \"index\": -1, // 跳過換臉\n                    \"position\": -1 // 跳過換臉\n                },\n                {\n                    \"index\": 0,  // 使用第一張參考圖片\n                    \"position\": 2 // 套用到來源中偵測到的第三張臉部\n                }\n            ]\n            ```\n\n        1. 發送主要任務請求：\n\n        ```\n        POST https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap\n        Authorization: Bearer YOUR_API_KEY\n        Content-Type: application/json\n        ```\n\n        內容：\n\n        ```json\n        {\n            \"request_id\": 2,\n            \"payload\": {\n            \"file_sets\": {\n                \"src_ids\": [\"TARGET_FILE_ID\"],\n                \"ref_ids\": [\"REFERENCE_FILE_ID\"]\n            },\n            \"actions\": [\n                {\n                \"id\": 0,\n                \"params\": {\n                    \"face_mapping\": [\n                    { \"index\": 0, \"position\": 0 },\n                    { \"index\": -1, \"position\": -1 }\n                    ]\n                }\n                }\n            ]\n            }\n        }\n        ```\n        1. 回應會回傳 `task_id`。\n\n---\n\n   * 步驟 4：輪詢任務狀態並取得結果\n        必須實作定時迴圈，在允許的輪詢窗口內以固定間隔查詢任務狀態。\n        1. 輪詢：\n\n        ```\n        GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap?task_id=TASK_ID\n        ```\n        2. 當 `status` 為 `success` 時，回應包含生成影像的網址。\n        3. 從該網址下載或顯示圖片。\n\n---\n\n   * 步驟 5：整合到您的平台\n\n        * 在**網頁前端**，您可以直接用 JavaScript 以 fetch 或 Axios 實作。\n        * 在**後端**（Node.js、Python、Java、PHP 等），您可以使用標準 HTTP 函式庫呼叫相同的端點。\n        * 由於任務以非同步執行，請實作重試與錯誤處理。\n\n---\n\n    * 除錯指南\n        1. **Invalid TaskId 錯誤**\n            </br>**原因：** 若您嘗試查詢已逾時任務的狀態，會收到 InvalidTaskId 錯誤。因此，AI 任務啟動後，您需要在 polling_interval 內輪詢其狀態，直到狀態變為 success 或 error。\n            </br>**解法：** 為避免任務失效，必須實作定時迴圈，在允許的輪詢窗口內以固定間隔查詢任務狀態。\n\n        2. **為什麼我的來源圖片中有些臉部未被偵測到**\n            </br>**原因：** 臉部必須清晰可見，未被覆蓋或遮擋，且在圖片中足夠大\n            </br>**解法：** 嘗試拍攝臉部看起來更大、且清晰可見無任何覆蓋或遮擋的照片\n\n---\n\n## 輸入與輸出\n\n* 實際範例：\n多人換臉範例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_face_swap_S2_img_04_d4b747a41d.jpg)\n\n單人換臉範例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_face_swap_S2_img_05_8e68faff2c.jpg)\n\n* 拍攝建議：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png)\n\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 照片換臉|輸入與輸出：長邊必須小於或等於 4096 像素|< 10MB|jpg/jpeg/png|\n\n\n* 錯誤代碼\n\n| 錯誤代碼 | 說明 |\n| ------------------ | ----------- |\n| exceed_max_filesize | 輸入檔案大小超過上限 |\n| invalid_parameter | 參數值無效 |\n| error_download_image | 下載來源圖片時發生錯誤 |\n| error_download_mask | 下載遮罩圖片時發生錯誤 |\n| error_decode_image | 解碼來源圖片時發生錯誤 |\n| error_decode_mask | 解碼遮罩圖片時發生錯誤 |\n| error_download_video | 下載來源影片時發生錯誤 |\n| error_decode_video | 解碼來源影片時發生錯誤 |\n| error_nsfw_content_detected | 在來源圖片中偵測到 NSFW 內容 |\n| error_no_face | 來源圖片中未偵測到臉部 |\n| error_pose | 在來源圖片偵測姿勢失敗 |\n| error_face_parsing | 在來源圖片進行人臉解析失敗 |\n| error_inference | 推論流程發生錯誤 |\n| exceed_nsfw_retry_limits | 超過重試上限，以避免生成 NSFW 圖片 |\n| error_upload | 上傳結果圖片時發生錯誤 |\n| error_multiple_people | 人數超過上限 |\n| error_no_shoulder | 來源圖片中肩膀不可見 |\n| error_large_face_angle | 上傳圖片的臉部角度過大 |\n| error_unsupport_ratio | 輸入圖片的長寬比不受支援 |\n| unknown_internal_error | 其他內部錯誤 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 照片換臉 V1.0 | 1 |\n\n---\n"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"docs.perfectcorp.com","port":4000,"ipAddress":"216.73.217.126"},"lang":"zh-TW","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"master"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/zh-tw/reference/ai_face_swap","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}