{"templateId":"api_docs","sharedDataIds":{"apiDocsStore":"api-docs-@l10n/zh-TW/reference/ai_retake.yaml","sidebar":"sidebar-@l10n/zh-TW/reference/sidebars.yaml"},"props":{"definitionId":"@l10n/zh-TW/reference/ai_retake.yaml","settings":{"baseUrlPath":"/zh-tw/reference/ai_retake"},"disableAutoScroll":true,"seo":{"title":"AI Retake","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 Retake","version":"","description":"# 概述\n保留瞬間，重建臉部。AI Retake 讓您逐張重建任何團體照片。無論是創造有趣的臉部照片，或需要專業工具，我們都能滿足您的需求。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-01-14/3d504686-8057-418e-a0cb-eba3d47ea42c.jpg)\n\n## 整合指南\n* 如何實作 AI Retake\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/retake/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/retake/pre-process?task_id=TASK_ID\n        ```\n        1. 完成後，您會收到帶有邊界框的偵測臉部清單。\n\n---\n\n   * 步驟 3：執行 AI Retake 任務\n        1. 定義哪個參考圖片將取代每個來源圖片\n        `face_mapping` 陣列定義**來源圖片**中的臉部如何被**參考圖片**中的臉部取代。它作為連結清單，將來源中偵測到的臉部連接到特定的參考圖片。 \n        \n        每次請求僅支援一次臉部替換。所有非目標臉部都必須設為 `{\"index\": -1, \"position\": -1}`。嘗試替換多於一張臉部會回傳 `error_change_too_many_faces`。回傳此錯誤的請求不會計費。僅支援參考圖片中偵測到的第一張臉部，因此 index 必須恆為 0。\n\n        * 參數\n            \n| 參數\t| 類型\t| 說明 |\n            | -- | -- | -- |\n| position\t| integer\t| 來源圖片中偵測到臉部的索引（例如 0、1、2）。\n| index\t| integer\t| 參考臉部索引。目前僅支援偵測到的第一張臉部，因此此值必須為 0。\n            \n        * 規則\n          * 單張臉部替換：每次請求僅能將一張來源臉部對應到參考臉部。\n          * 跳過某張臉部：將 index 與 position 都設為 -1。\n          * 參考臉部索引：僅支援參考圖片中偵測到的第一張臉部，因此 index 恆為 0。\n            \n        * 範例\n\n            情境\n            * 參考圖片：1 張包含單張受支援臉部的圖片。\n            * 來源圖片：偵測到 4 張臉部（Face 0、Face 1、Face 2、Face 3）。\n            * 目標：僅替換 Face 2，保持 Face 0、Face 1 與 Face 3 不變。\n            ```            \n                \"face_mapping\": [\n                    {\n                        \"index\": -1, // 跳過替換\n                        \"position\": -1 // 跳過替換\n                    },\n                    {\n                        \"index\": -1, // 跳過替換\n                        \"position\": -1 // 跳過替換\n                    },\n                    {\n                        \"index\": 0, // 恆使用第一張參考圖片\n                        \"position\": 2 // 套用到來源中偵測到的第三張臉部\n                    },\n                    {\n                        \"index\": -1, // 跳過替換\n                        \"position\": -1 // 跳過替換\n                    },\n                ]\n            ```\n        1. 發送主要任務請求：\n\n        ```\n        POST https://yce-api-01.makeupar.com/s2s/v2.0/task/retake\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\": -1, \"position\": -1},\n                    {\"index\": -1, \"position\": -1},\n                    {\"index\":  0, \"position\":  2},\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/retake?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\n        1. **為什麼我的來源圖片中有些臉部未被偵測到**\n            </br>**原因：** 臉部必須清晰可見，未被覆蓋或遮擋，且在圖片中足夠大\n            </br>**解法：** 嘗試拍攝臉部看起來更大、且清晰可見無任何覆蓋或遮擋的照片\n\n---\n\n## 輸入與輸出\n\n* 實際範例：\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-01-14/9aeab2bb-28aa-48f5-ab86-2edd897ad908.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-07-02/webp_0196a9d4-1430-4121-9680-5e81b58b66ac.webp)\n\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n| AI 功能 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 |\n| ---- | ---- | ---- | ---- |\n| AI Retake | 輸入與輸出：長邊必須小於或等於 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| error_change_too_many_faces | 每次請求僅支援一次臉部替換。所有非目標臉部都必須設為 {\"index\": -1, \"position\": -1}。嘗試替換多於一張臉部會回傳此錯誤。 |\n| unknown_internal_error | 其他內部錯誤 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI Retake V2.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_retake","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}