{"items":[{"type":"separator","label":"工具","labelTranslationKey":"sidebar.reference.separators.utility"},{"type":"group","fsPath":"@l10n/zh-TW/reference/unit_system.yaml","link":"/zh-tw/reference/unit_system","routeSlug":"/zh-tw/reference/unit_system","label":"單位系統","items":[{"label":"取得點數資訊","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/unit_system/paths/~1s2s~1v1.0~1client~1credit/get","routeSlug":"/zh-tw/reference/unit_system/paths/~1s2s~1v1.0~1client~1credit/get","metadata":{"seo":{"title":"取得點數資訊","description":"以小數第二位顯示可用的 API 點數"}},"httpPath":"/s2s/v1.0/client/credit"},{"label":"檢視點數紀錄","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/unit_system/paths/~1s2s~1v1.0~1client~1credit~1history/get","routeSlug":"/zh-tw/reference/unit_system/paths/~1s2s~1v1.0~1client~1credit~1history/get","metadata":{"seo":{"title":"檢視點數紀錄","description":"檢視點數紀錄"}},"httpPath":"/s2s/v1.0/client/credit/history"},{"label":"取得功能費用","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/unit_system/paths/~1s2s~1v2.0~1credit~1feature-cost/get","routeSlug":"/zh-tw/reference/unit_system/paths/~1s2s~1v2.0~1credit~1feature-cost/get","metadata":{"seo":{"title":"取得功能費用","description":"查詢每個 API 的點數消耗。這些數值與 https://yce.perfectcorp.com/ai-api/api-pricing 列出的內容一致。"}},"httpPath":"/s2s/v2.0/credit/feature-cost"}],"metadata":{"type":"openapi","title":"單位系統","version":"","description":"查詢您的點數明細與使用紀錄。請注意，Units 是 YouCam API 運作所用的計費單位；不同的 AI 功能會扣除不同數量的點數。在本文件中，Unit 的代號為「Credit」。\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/task_management.yaml","link":"/zh-tw/reference/task_management","routeSlug":"/zh-tw/reference/task_management","label":"任務管理","items":[{"label":"刪除任務及其檔案。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/task_management/paths/~1s2s~1v2.0~1task~1delete/post","routeSlug":"/zh-tw/reference/task_management/paths/~1s2s~1v2.0~1task~1delete/post","metadata":{"seo":{"title":"刪除任務及其檔案。","description":"刪除以 task_id 識別、已完成的任務，包含所有相關的輸入檔案與生成的輸出。請提供該任務執行端點回傳的 task_id。"}},"httpPath":"/s2s/v2.0/task/delete"}],"metadata":{"type":"openapi","title":"任務管理","version":""}},{"type":"group","fsPath":"@l10n/zh-TW/reference/file.yaml","link":"/zh-tw/reference/file","routeSlug":"/zh-tw/reference/file","label":"檔案管理","items":[{"label":"建立新檔案。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/file/paths/~1s2s~1v2.0~1file/post","routeSlug":"/zh-tw/reference/file/paths/~1s2s~1v2.0~1file/post","metadata":{"seo":{"title":"建立新檔案。","description":"要上傳新檔案，您必須先使用 File API。它會提供一個網址——請使用該網址上傳您的檔案。上傳完成後，您可以使用同一個回應中的 file_id，開始使用我們的 AI 功能。"}},"httpPath":"/s2s/v2.0/file"}],"metadata":{"type":"openapi","title":"檔案管理","version":""}},{"type":"separator","label":"肌膚、臉部與身體","labelTranslationKey":"sidebar.reference.separators.skinFaceBody"},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_skin_analysis.yaml","link":"/zh-tw/reference/ai_skin_analysis","routeSlug":"/zh-tw/reference/ai_skin_analysis","label":"AI 肌膚檢測 V2.1","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_skin_analysis/section/概述","routeSlug":"/zh-tw/reference/ai_skin_analysis/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_skin_analysis/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_skin_analysis/section/概述/整合指南"},{"type":"link","label":"輸入與輸出","link":"/zh-tw/reference/ai_skin_analysis/section/概述/輸入與輸出","routeSlug":"/zh-tw/reference/ai_skin_analysis/section/概述/輸入與輸出"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_skin_analysis/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_skin_analysis/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_skin_analysis/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_skin_analysis/section/概述/點數消耗"},{"type":"link","label":"JS Camera Kit","link":"/zh-tw/reference/ai_skin_analysis/section/概述/js-camera-kit","routeSlug":"/zh-tw/reference/ai_skin_analysis/section/概述/js-camera-kit"},{"type":"link","label":"Mobile Camera Kit","link":"/zh-tw/reference/ai_skin_analysis/section/概述/mobile-camera-kit","routeSlug":"/zh-tw/reference/ai_skin_analysis/section/概述/mobile-camera-kit"},{"type":"link","label":"使用案例","link":"/zh-tw/reference/ai_skin_analysis/section/概述/使用案例","routeSlug":"/zh-tw/reference/ai_skin_analysis/section/概述/使用案例"}]},{"type":"group","label":"Standard Analysis","link":"/zh-tw/reference/ai_skin_analysis/standard-analysis","routeSlug":"/zh-tw/reference/ai_skin_analysis/standard-analysis","items":[{"type":"link","label":"端點總覽","link":"/zh-tw/reference/ai_skin_analysis/standard-analysis/端點總覽","routeSlug":"/zh-tw/reference/ai_skin_analysis/standard-analysis/端點總覽"},{"label":"執行肌膚檢測 V2.1 任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_skin_analysis/standard-analysis/paths/~1s2s~1v2.1~1task~1skin-analysis/post","routeSlug":"/zh-tw/reference/ai_skin_analysis/standard-analysis/paths/~1s2s~1v2.1~1task~1skin-analysis/post","metadata":{"seo":{"title":"執行肌膚檢測 V2.1 任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.1/task/skin-analysis"},{"label":"查詢肌膚檢測 V2.1 任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_skin_analysis/standard-analysis/paths/~1s2s~1v2.1~1task~1skin-analysis~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_skin_analysis/standard-analysis/paths/~1s2s~1v2.1~1task~1skin-analysis~1{task_id}/get","metadata":{"seo":{"title":"查詢肌膚檢測 V2.1 任務的狀態。","description":"查詢肌膚檢測 V2.1 任務的狀態。"}},"httpPath":"/s2s/v2.1/task/skin-analysis/{task_id}"}]},{"type":"group","label":"Analysis + Advanced Report","link":"/zh-tw/reference/ai_skin_analysis/analysis-+-advanced-report","routeSlug":"/zh-tw/reference/ai_skin_analysis/analysis-+-advanced-report","items":[{"type":"link","label":"端點總覽","link":"/zh-tw/reference/ai_skin_analysis/analysis-+-advanced-report/端點總覽","routeSlug":"/zh-tw/reference/ai_skin_analysis/analysis-+-advanced-report/端點總覽"},{"label":"執行「肌膚檢測＋進階肌膚報告」任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_skin_analysis/analysis-+-advanced-report/paths/~1s2s~1v2.1~1task~1skin-analysis-report/post","routeSlug":"/zh-tw/reference/ai_skin_analysis/analysis-+-advanced-report/paths/~1s2s~1v2.1~1task~1skin-analysis-report/post","metadata":{"seo":{"title":"執行「肌膚檢測＋進階肌膚報告」任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.1/task/skin-analysis-report"},{"label":"查詢「肌膚檢測＋進階肌膚報告」任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_skin_analysis/analysis-+-advanced-report/paths/~1s2s~1v2.1~1task~1skin-analysis-report~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_skin_analysis/analysis-+-advanced-report/paths/~1s2s~1v2.1~1task~1skin-analysis-report~1{task_id}/get","metadata":{"seo":{"title":"查詢「肌膚檢測＋進階肌膚報告」任務的狀態。","description":"查詢「肌膚檢測＋進階肌膚報告」任務的狀態。"}},"httpPath":"/s2s/v2.1/task/skin-analysis-report/{task_id}"}]},{"type":"group","label":"Analysis + Product Recommendation","link":"/zh-tw/reference/ai_skin_analysis/analysis-+-product-recommendation","routeSlug":"/zh-tw/reference/ai_skin_analysis/analysis-+-product-recommendation","items":[{"type":"link","label":"端點總覽","link":"/zh-tw/reference/ai_skin_analysis/analysis-+-product-recommendation/端點總覽","routeSlug":"/zh-tw/reference/ai_skin_analysis/analysis-+-product-recommendation/端點總覽"},{"label":"執行「肌膚檢測＋產品推薦」任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_skin_analysis/analysis-+-product-recommendation/paths/~1s2s~1v2.1~1task~1skin-analysis-recommendation/post","routeSlug":"/zh-tw/reference/ai_skin_analysis/analysis-+-product-recommendation/paths/~1s2s~1v2.1~1task~1skin-analysis-recommendation/post","metadata":{"seo":{"title":"執行「肌膚檢測＋產品推薦」任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.1/task/skin-analysis-recommendation"},{"label":"查詢「肌膚檢測＋產品推薦」任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_skin_analysis/analysis-+-product-recommendation/paths/~1s2s~1v2.1~1task~1skin-analysis-recommendation~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_skin_analysis/analysis-+-product-recommendation/paths/~1s2s~1v2.1~1task~1skin-analysis-recommendation~1{task_id}/get","metadata":{"seo":{"title":"查詢「肌膚檢測＋產品推薦」任務的狀態。","description":"查詢「肌膚檢測＋產品推薦」任務的狀態。"}},"httpPath":"/s2s/v2.1/task/skin-analysis-recommendation/{task_id}"}]},{"type":"group","label":"Analysis + Report + Recommendation","link":"/zh-tw/reference/ai_skin_analysis/analysis-+-report-+-recommendation","routeSlug":"/zh-tw/reference/ai_skin_analysis/analysis-+-report-+-recommendation","items":[{"type":"link","label":"端點總覽","link":"/zh-tw/reference/ai_skin_analysis/analysis-+-report-+-recommendation/端點總覽","routeSlug":"/zh-tw/reference/ai_skin_analysis/analysis-+-report-+-recommendation/端點總覽"},{"label":"執行「肌膚檢測＋進階肌膚報告＋產品推薦」任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_skin_analysis/analysis-+-report-+-recommendation/paths/~1s2s~1v2.1~1task~1skin-analysis-report-recommendation/post","routeSlug":"/zh-tw/reference/ai_skin_analysis/analysis-+-report-+-recommendation/paths/~1s2s~1v2.1~1task~1skin-analysis-report-recommendation/post","metadata":{"seo":{"title":"執行「肌膚檢測＋進階肌膚報告＋產品推薦」任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.1/task/skin-analysis-report-recommendation"},{"label":"查詢「肌膚檢測＋進階肌膚報告＋產品推薦」任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_skin_analysis/analysis-+-report-+-recommendation/paths/~1s2s~1v2.1~1task~1skin-analysis-report-recommendation~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_skin_analysis/analysis-+-report-+-recommendation/paths/~1s2s~1v2.1~1task~1skin-analysis-report-recommendation~1{task_id}/get","metadata":{"seo":{"title":"查詢「肌膚檢測＋進階肌膚報告＋產品推薦」任務的狀態。","description":"查詢「肌膚檢測＋進階肌膚報告＋產品推薦」任務的狀態。"}},"httpPath":"/s2s/v2.1/task/skin-analysis-report-recommendation/{task_id}"}]},{"type":"group","label":"Product Catalogs","link":"/zh-tw/reference/ai_skin_analysis/product-catalogs","routeSlug":"/zh-tw/reference/ai_skin_analysis/product-catalogs","items":[{"type":"link","label":"端點總覽","link":"/zh-tw/reference/ai_skin_analysis/product-catalogs/端點總覽","routeSlug":"/zh-tw/reference/ai_skin_analysis/product-catalogs/端點總覽"},{"label":"上傳產品目錄。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_skin_analysis/product-catalogs/paths/~1s2s~1v2.1~1product-catalog/post","routeSlug":"/zh-tw/reference/ai_skin_analysis/product-catalogs/paths/~1s2s~1v2.1~1product-catalog/post","metadata":{"seo":{"title":"上傳產品目錄。","description":"以 CSV 檔案上傳產品目錄。檔案會在同一次請求中完成驗證：驗證通過的檔案回傳 status ready，並附上它的 catalog_id 與 sku_count；驗證失敗的檔案會回傳錯誤，同時仍會被記錄成一個 failed 目錄，「列出目錄」會把它列出來。"}},"httpPath":"/s2s/v2.1/product-catalog"},{"label":"列出產品目錄。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_skin_analysis/product-catalogs/paths/~1s2s~1v2.1~1product-catalog/get","routeSlug":"/zh-tw/reference/ai_skin_analysis/product-catalogs/paths/~1s2s~1v2.1~1product-catalog/get","metadata":{"seo":{"title":"列出產品目錄。","description":"列出您帳號下的所有目錄，最新的排在最前面，ready 與 failed 都會列出。手邊沒有某個 catalog_id 時，可以用它找回。不分頁：每個帳號可保留的目錄數量有上限（見產品目錄章節下的「限制」）。"}},"httpPath":"/s2s/v2.1/product-catalog"},{"label":"刪除產品目錄。","deprecated":false,"httpVerb":"delete","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_skin_analysis/product-catalogs/paths/~1s2s~1v2.1~1product-catalog~1{catalog_id}/delete","routeSlug":"/zh-tw/reference/ai_skin_analysis/product-catalogs/paths/~1s2s~1v2.1~1product-catalog~1{catalog_id}/delete","metadata":{"seo":{"title":"刪除產品目錄。","description":"刪除目錄立即生效且不可恢復。從那一刻起，所有使用該 catalog_id 的肌膚檢測呼叫都會失敗。已刪除的目錄無法復原。"}},"httpPath":"/s2s/v2.1/product-catalog/{catalog_id}"}]}],"metadata":{"type":"openapi","title":"AI 肌膚檢測 V2.1","version":"","description":"# 概述\n![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_demostore_skincarelive_topbanner.0cffe3a7.jpg)\n\n**AI 肌膚檢測 V2.1** 只要一張正面自拍，就能深入掌握肌膚狀態：量測皺紋、毛孔、斑點、泛紅與膚質等 16 項肌膚指標，標示每一項肌膚困擾出現在臉上的哪個位置，同時推估肌膚年齡、計算整體膚況分數。\n\nV2.1 另提供兩項加值功能，讓整合更完整：\n\n- **進階肌膚報告**：依每位使用者的檢測結果，生成個人化、容易閱讀的肌膚洞察。\n- **產品推薦**：把您的產品目錄對應到每位使用者的肌膚困擾，打造對路的購物體驗。\n\n您可以單獨使用肌膚檢測，也可以搭配加值功能一起用。想比較這幾種模式，請見[使用案例](#section/overview/use-cases)。\n\n## 整合指南\n* 如何為 AI 肌膚檢測拍攝照片\n* 正面自拍\n  - 只需一張清晰的照片，直視鏡頭。讓頭髮放下垂於胸前，並確保直視前方，取得正面視角。\n  - 或者，使用 JS Camera Kit 拍照。只需讓頭髮放下垂於胸前，不要綁起。\n\n* 工作流程\n**肌膚檢測 API 使用指南**\n本指南說明如何使用 File API 與 AI 任務 API 上傳圖片並建立肌膚檢測任務。\n\n   * **步驟 1：調整來源圖片尺寸**</br>\n  調整您的照片以符合支援的尺寸——SD 長邊最多 2560 像素、短邊至少 480 像素；HD 長邊最多 2560 像素、短邊至少 1080 像素。細節請參考**[檔案規格與錯誤](#section/overview/File-Specs-and-Errors)**\n\n   * **步驟 2：透過 File API 上傳檔案 metadata**\n- 圖片需求\n    - 細節請參考**[檔案規格與錯誤](#section/overview/File-Specs-and-Errors)**\n\n發送 POST 請求以初始化檔案上傳：\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/file \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"files\": [\n      {\n        \"content_type\": \"image/png\",\n        \"file_name\": \"skin_analysis_01_3dbd1b6683.png\",\n        \"file_size\": 547541\n      }\n    ]\n  }'\n```\n\n- ***重要***：僅呼叫 File API 並不會上傳您的檔案。您必須**額外上傳**檔案到**File API 回應中提供的網址**。該網址就是您的上傳目的地，請確保檔案成功傳輸到該處後再繼續。\n\n  > **警告：** 請注意，若您未將檔案上傳到 File API 回應中提供的網址，使用 AI API 時會得到 500 Server Error / unknown_internal_error 或 404 Not Found 錯誤。\n\n***\n\n   * **步驟 3：取得上傳網址與檔案 ID**\n\n回應包含：\n\n*   `requests.url` – 用於圖片上傳的預簽名網址。\n*   `file_id` – 用於建立 AI 任務的識別碼。\n\n**回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"files\": [\n      {\n        \"content_type\": \"image/png\",\n        \"file_name\": \"skin_analysis_01_3dbd1b6683.png\",\n        \"file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n        \"requests\": [\n          {\n            \"method\": \"PUT\",\n            \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\",\n            \"headers\": {\n              \"Content-Length\": \"547541\",\n              \"Content-Type\": \"image/png\"\n            }\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n***\n\n   * **步驟 4：上傳圖片到預簽名網址**\n\n使用提供的 `requests.url` 與標頭：\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n  --header 'Content-Type: image/png' \\\n  --header 'Content-Length: 547541' \\\n  --data-binary @'./skin_analysis_01_3dbd1b6683.png'\n```\n\n***\n\n   * **步驟 5：建立 AI 任務**\n\n使用步驟 2 的 `file_id` 建立肌膚檢測任務：\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"src_file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n    \"dst_actions\": [\"wrinkle\", \"pore\", \"texture\", \"acne\"],\n    \"miniserver_args\": {\n      \"enable_mask_overlay\": true,\n      \"enable_dark_background_hd_pore\": true,\n      \"color_dark_background_hd_pore\": \"3D3D3D\",\n      \"opacity_dark_background_hd_pore\": 0.4\n      // 為簡潔起見，省略其他參數\n    },\n    \"format\": \"json\"\n  }'\n```\n  上傳完成後，您可以使用檔案 ID 或圖片檔案網址選擇要分析的任何膚況問題。請參考**[輸入與輸出](#section/overview/Inputs-and-Outputs)**。</br>\n  接著，使用\n  檔案 ID 或圖片檔案網址執行增強任務，並取得 ***task_id***。\n  請注意，**不**支援同時使用 SD 與 HD 膚況參數。\n\n- **使用現有的公開圖片網址**\n無需上傳，您可以在啟動 AI 任務時直接提供可公開存取的圖片網址。\n\n**回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT\"\n  }\n}\n```\n\n***\n\n   * **步驟 6：輪詢任務狀態**\n\n使用 `task_id` 取得任務結果：\n\n```bash\ncurl --request GET \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis/<YOUR_TASK_ID> \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'Content-Type: application/json'\n```\n這個 ***task_id*** 用於透過輪詢 GET 'task/skin-analysis' 監控任務狀態，以取得目前的引擎狀態。在引擎完成任務之前，狀態會維持為 'running'，此階段不會消耗點數。\n\n處理後的結果在完成後保留 30 天。\n- 無需短間隔輪詢。\n- 在保留期限內可彈性設定輪詢間隔。\n\n  > **重要：** 仍需要輪詢以查詢任務狀態，因為執行時間無法保證。\n\n引擎成功處理您的輸入檔案並生成結果影像後，任務會變為 'success' 狀態。您會取得處理後影像的網址，以及一個 dst_id，讓您在無需重新上傳結果圖片的情況下串接另一個 AI 任務。\n\n點數僅在這種情況下會被消耗。若引擎處理任務失敗，任務狀態會變為 'error'，且不會消耗點數。\n扣除點數時，系統會優先使用接近到期的點數。若到期日相同，則扣除最早取得的點數。\n\n\n***\n\n   * **步驟 7：解讀結果**\n\n回應包含：\n\n*   `ui_score` – 使用者友善的分數。\n*   `raw_score` – 原始分析分數。\n*   `mask_urls` – 偵測遮罩的網址。\n\n**回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"results\": {\n      \"output\": [\n        {\n          \"type\": \"texture\",\n          \"ui_score\": 68,\n          \"raw_score\": 57.33,\n          \"mask_urls\": [\"https://yce-us.s3-accelerate.amazonaws.com/...texture_output.jpg\"]\n        },\n        {\n          \"type\": \"pore\",\n          \"ui_score\": 92,\n          \"raw_score\": 95.34,\n          \"mask_urls\": [\"https://yce-us.s3-accelerate.amazonaws.com/...pore_output.jpg\"]\n        }\n        // 為簡潔起見，省略其他結果\n      ]\n    },\n    \"task_status\": \"success\"\n  }\n}\n```\n\n\n* 除錯指南\n> **警告：** 請注意，**不**支援同時使用 SD 與 HD 膚況參數。試圖偏離這些規格會導致 ***InvalidParameters*** 錯誤。\n\n  * 若您混合使用 HD 與 SD 膚況，會得到如下錯誤：\n    ```json\n    {\n        \"status\": 400,\n        \"error\": \"cannot mix HD and SD dst_actions\",\n        \"error_code\": \"InvalidParameters\"\n    }\n    ```\n  * 若您拼寫膚況錯誤，或傳送未知的膚況，會得到如下錯誤：\n    ```json\n    {\n        \"status\": 400,\n        \"error\": \"Not available dst_action abc123\",\n        \"error_code\": \"InvalidParameters\"\n    }\n    ```\n\n---\n\n* 實際範例：\n![](https://plugins-media.makeupar.com/webconsultation/images/skincare-widget/img_webcm_skincare_service_survey_demo.jpg)\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/skin_analysis_s5_poster_3_dt_85efe14952.png)\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Skincare_Pro_Medspa_Situation_Image_6aea6046f9.jpg)\n\n## 輸入與輸出\n* 輸入參數說明\n控制 AI 肌膚檢測結果視覺輸出有兩種選項：生成多張圖片，每個膚況以獨立的遮罩呈現；或使用 ``enable_mask_overlay`` 參數產生單張混合圖片。預設情況下，系統輸出多個遮罩，讓您完全控制如何將每個膚況遮罩與圖片混合。\n\n* 預設：enable_mask_overlay false\n  ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/mask_overlay_false_1920_ea1cde0ead.png)\n\n* 將 enable_mask_overlay 設為 true\n  ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/mask_overlay_1920_0fbb4786cc.png)\n\n----\n\n* 輸出 ZIP 資料結構說明\n系統提供一個 ZIP 檔案，內含 'skinanalysisResult' 資料夾。此資料夾包含一個 'score_info.json' 檔案，涵蓋所有偵測分數與結果圖片的參考。\n\n'score_info.json' 檔案包含所有肌膚檢測偵測結果，含數值分數與對應輸出遮罩檔案的名稱。\n\nPNG 檔案是可疊加在您原始圖片上的偵測結果遮罩。只需使用這些 PNG 檔案中的 alpha 值，將其與您的原始圖片混合，即可直接在來源圖片上看見偵測結果。\n\n* 肌膚檢測結果 ZIP 中的檔案結構\n* HD 護膚 ZIP\n  * skinanalysisResult\n    - score_info.json\n    - hd_acne_output.png\n    - hd_age_spot_output.png\n    - hd_dark_circle_output.png\n    - hd_droopy_lower_eyelid_output.png\n    - hd_droopy_upper_eyelid_output.png\n    - hd_eye_bag_output.png\n    - hd_firmness_output.png\n    - hd_moisture_output.png\n    - hd_oiliness_output.png\n    - hd_radiance_output.png\n    - hd_redness_output.png\n    - hd_texture_output.png\n    - hd_pore_output_all.png\n    - hd_pore_output_cheek.png\n    - hd_pore_output_forehead.png\n    - hd_pore_output_nose.png\n    - hd_wrinkle_output_all.png\n    - hd_wrinkle_output_crowfeet.png\n    - hd_wrinkle_output_forehead.png\n    - hd_wrinkle_output_glabellar.png\n    - hd_wrinkle_output_marionette.png\n    - hd_wrinkle_output_nasolabial.png\n    - hd_wrinkle_output_periocular.png\n    - hd_tear_trough.png\n    - hd_skin_type.png\n\n* SD 護膚 ZIP\n  * skinanalysisResult\n    - score_info.json\n    - acne_output.png\n    - age_spot_output.png\n    - dark_circle_v2_output.png\n    - droopy_lower_eyelid_output.png\n    - droopy_upper_eyelid_output.png\n    - eye_bag_output.png\n    - firmness_output.png\n    - moisture_output.png\n    - oiliness_output.png\n    - pore_output.png\n    - radiance_output.png\n    - redness_output.png\n    - texture_output.png\n    - wrinkle_output.png\n    - tear_trough.png\n    - skin_type.png\n\n* JSON 資料結構（score_info.json）\n  * \"all\"：介於 1 與 100 之間的浮點值，代表整體膚況。較高的分數代表更健康、更具美感的膚況。\n  * \"skin_age\"：相對於全年齡層一般人口分布，由 AI 推得的肌膚年齡。\n  * 每個類別包含：\n    * \"raw_score\"：範圍從 1 到 100 的浮點值。較高的分數代表更健康、更具美感的膚況。\n    * \"ui_score\"：範圍從 1 到 100 的整數。UI 分數主要作為美妝評估中的心理激勵因素。我們調整原始分數以產生更理想的結果，因為理解消費者通常偏好關於其皮膚健康的正面評價。此校準旨在維持底層的美妝心理架構，同時為使用者注入更多信心。\n    * \"output_mask_name\"：對應輸出遮罩圖片的檔案名稱。\n\n  * 類別與說明\n    * HD 護膚：\n        * \"hd_redness\"：測量皮膚泛紅的嚴重程度。\n        * \"hd_oiliness\"：判定皮膚油脂程度。\n        * \"hd_age_spot\"：偵測老化斑點與色素。\n        * \"hd_radiance\"：評估皮膚光澤。\n        * \"hd_moisture\"：評估皮膚保濕程度。\n        * \"hd_dark_circle\"：分析眼下方黑眼圈的存在。\n        * \"hd_eye_bag\"：偵測眼袋。\n        * \"hd_droopy_upper_eyelid\"：測量上眼皮下垂的嚴重程度。\n        * \"hd_droopy_lower_eyelid\"：測量下眼皮下垂的嚴重程度。\n        * \"hd_firmness\"：評估皮膚緊實度與彈性。\n        * \"hd_texture\"：子類別[whole]；分析整體皮膚質地。\n        * \"hd_acne\"：子類別[whole]；偵測痤瘡的存在。\n        * \"hd_pore\"：子類別[forehead, nose, cheek, whole]；偵測並評估不同臉部區域的毛孔。\n        * \"hd_wrinkle\"：子類別[forehead, glabellar, crowfeet, periocular, nasolabial, marionette, whole]；測量各臉部區域皺紋的嚴重程度。\n        * \"hd_tear_trough\"：偵測淚溝。\n        * \"hd_skin_type\"：子類別[whole, t_zone, u_zone]，評估正常、油性、乾性、混合性、泛紅、乾性與泛紅、油性與泛紅、混合性與泛紅等膚質。\n\n    * SD 護膚：\n        * \"wrinkle\"：一般皺紋分析。\n        * \"droopy_upper_eyelid\"：測量上眼皮下垂的嚴重程度。\n        * \"droopy_lower_eyelid\"：測量下眼皮下垂的嚴重程度。\n        * \"firmness\"：評估皮膚緊實度與彈性。\n        * \"acne\"：評估痤瘡的存在。\n        * \"moisture\"：測量皮膚保濕。\n        * \"eye_bag\"：偵測眼袋。\n        * \"dark_circle_v2\"：以另一種方法分析黑眼圈。\n        * \"age_spot\"：偵測老化斑點。\n        * \"radiance\"：評估皮膚亮度。\n        * \"redness\"：測量皮膚泛紅。\n        * \"oiliness\"：判定皮膚油脂。\n        * \"pore\"：測量毛孔可見度。\n        * \"texture\"：分析整體皮膚質地。\n        * \"tear_trough\"：偵測淚溝。\n        * \"skin_type\"：子類別[whole, t_zone, u_zone]，評估正常、油性、乾性、混合性、泛紅、乾性與泛紅、油性與泛紅、混合性與泛紅等膚質。\n\n  * HD 護膚的 score_info.json 範例\n    ```json\n    {\n        \"hd_redness\": {\n            \"raw_score\": 72.011962890625,\n            \"ui_score\": 77,\n            \"output_mask_name\": \"hd_redness_output.png\"\n        },\n        \"hd_oiliness\": {\n            \"raw_score\": 60.74365234375,\n            \"ui_score\": 72,\n            \"output_mask_name\": \"hd_oiliness_output.png\"\n        },\n        \"hd_age_spot\": {\n            \"raw_score\": 83.23274230957031,\n            \"ui_score\": 77,\n            \"output_mask_name\": \"hd_age_spot_output.png\"\n        },\n        \"hd_radiance\": {\n            \"raw_score\": 76.57244205474854,\n            \"ui_score\": 79,\n            \"output_mask_name\": \"hd_radiance_output.png\"\n        },\n        \"hd_moisture\": {\n            \"raw_score\": 48.694559931755066,\n            \"ui_score\": 70,\n            \"output_mask_name\": \"hd_moisture_output.png\"\n        },\n        \"hd_dark_circle\": {\n            \"raw_score\": 80.1993191242218,\n            \"ui_score\": 76,\n            \"output_mask_name\": \"hd_dark_circle_output.png\"\n        },\n        \"hd_eye_bag\": {\n            \"raw_score\": 76.67280435562134,\n            \"ui_score\": 79,\n            \"output_mask_name\": \"hd_eye_bag_output.png\"\n        },\n        \"hd_droopy_upper_eyelid\": {\n            \"raw_score\": 79.05348539352417,\n            \"ui_score\": 80,\n            \"output_mask_name\": \"hd_droopy_upper_eyelid_output.png\"\n        },\n        \"hd_droopy_lower_eyelid\": {\n            \"raw_score\": 79.97175455093384,\n            \"ui_score\": 81,\n            \"output_mask_name\": \"hd_droopy_lower_eyelid_output.png\"\n        },\n        \"hd_firmness\": {\n            \"raw_score\": 89.66898322105408,\n            \"ui_score\": 85,\n            \"output_mask_name\": \"hd_firmness_output.png\"\n        },\n        \"hd_texture\": {\n            \"whole\": {\n                \"raw_score\": 66.3921568627451,\n                \"ui_score\": 75,\n                \"output_mask_name\": \"hd_texture_output.png\"\n            }\n        },\n        \"hd_acne\": {\n            \"whole\": {\n                \"raw_score\": 59.92677688598633,\n                \"ui_score\": 76,\n                \"output_mask_name\": \"hd_acne_output.png\"\n            }\n        },\n        \"hd_pore\": {\n            \"forehead\": {\n                \"raw_score\": 79.59770965576172,\n                \"ui_score\": 80,\n                \"output_mask_name\": \"hd_pore_output_forehead.png\"\n            },\n            \"nose\": {\n                \"raw_score\": 29.139814376831055,\n                \"ui_score\": 58,\n                \"output_mask_name\": \"hd_pore_output_nose.png\"\n            },\n            \"cheek\": {\n                \"raw_score\": 44.11081314086914,\n                \"ui_score\": 65,\n                \"output_mask_name\": \"hd_pore_output_cheek.png\"\n            },\n            \"whole\": {\n                \"raw_score\": 49.23978805541992,\n                \"ui_score\": 67,\n                \"output_mask_name\": \"hd_pore_output_all.png\"\n            }\n        },\n        \"hd_wrinkle\": {\n            \"forehead\": {\n                \"raw_score\": 55.96956729888916,\n                \"ui_score\": 67,\n                \"output_mask_name\": \"hd_wrinkle_output_forehead.png\"\n            },\n            \"glabellar\": {\n                \"raw_score\": 76.7251181602478,\n                \"ui_score\": 75,\n                \"output_mask_name\": \"hd_wrinkle_output_glabellar.png\"\n            },\n            \"crowfeet\": {\n                \"raw_score\": 83.4361481666565,\n                \"ui_score\": 78,\n                \"output_mask_name\": \"hd_wrinkle_output_crowfeet.png\"\n            },\n            \"periocular\": {\n                \"raw_score\": 67.88706302642822,\n                \"ui_score\": 72,\n                \"output_mask_name\": \"hd_wrinkle_output_periocular.png\"\n            },\n            \"nasolabial\": {\n                \"raw_score\": 74.03312683105469,\n                \"ui_score\": 74,\n                \"output_mask_name\": \"hd_wrinkle_output_nasolabial.png\"\n            },\n            \"marionette\": {\n                \"raw_score\": 71.94477319717407,\n                \"ui_score\": 73,\n                \"output_mask_name\": \"hd_wrinkle_output_marionette.png\"\n            },\n            \"whole\": {\n                \"raw_score\": 49.64699745178223,\n                \"ui_score\": 65,\n                \"output_mask_name\": \"hd_wrinkle_output_all.png\"\n            }\n        },\n        \"all\": {\n            \"score\": 75.75757575757575\n        },\n        \"skin_age\": 37\n    }\n    ```\n  * SD 護膚的 score_info.json 範例\n    ```json\n    {\n        \"wrinkle\": {\n            \"raw_score\": 36.09360456466675,\n            \"ui_score\": 60,\n            \"output_mask_name\": \"wrinkle_output.png\"\n        },\n        \"droopy_upper_eyelid\": {\n            \"raw_score\": 79.05348539352417,\n            \"ui_score\": 80,\n            \"output_mask_name\": \"droopy_upper_eyelid_output.png\"\n        },\n        \"droopy_lower_eyelid\": {\n            \"raw_score\": 79.97175455093384,\n            \"ui_score\": 81,\n            \"output_mask_name\": \"droopy_lower_eyelid_output.png\"\n        },\n        \"firmness\": {\n            \"raw_score\": 89.66898322105408,\n            \"ui_score\": 85,\n            \"output_mask_name\": \"firmness_output.png\"\n        },\n        \"acne\": {\n            \"raw_score\": 92.29713000000001,\n            \"ui_score\": 88,\n            \"output_mask_name\": \"acne_output.png\"\n        },\n        \"moisture\": {\n            \"raw_score\": 48.694559931755066,\n            \"ui_score\": 70,\n            \"output_mask_name\": \"moisture_output.png\"\n        },\n        \"eye_bag\": {\n            \"raw_score\": 76.67280435562134,\n            \"ui_score\": 79,\n            \"output_mask_name\": \"eye_bag_output.png\"\n        },\n        \"dark_circle_v2\": {\n            \"raw_score\": 80.1993191242218,\n            \"ui_score\": 76,\n            \"output_mask_name\": \"dark_circle_v2_output.png\"\n        },\n        \"age_spot\": {\n            \"raw_score\": 83.23274230957031,\n            \"ui_score\": 77,\n            \"output_mask_name\": \"age_spot_output.png\"\n        },\n        \"radiance\": {\n            \"raw_score\": 76.57244205474854,\n            \"ui_score\": 79,\n            \"output_mask_name\": \"radiance_output.png\"\n        },\n        \"redness\": {\n            \"raw_score\": 72.011962890625,\n            \"ui_score\": 77,\n            \"output_mask_name\": \"redness_output.png\"\n        },\n        \"oiliness\": {\n            \"raw_score\": 60.74365234375,\n            \"ui_score\": 72,\n            \"output_mask_name\": \"oiliness_output.png\"\n        },\n        \"pore\": {\n            \"raw_score\": 88.38014125823975,\n            \"ui_score\": 84,\n            \"output_mask_name\": \"pore_output.png\"\n        },\n        \"texture\": {\n            \"raw_score\": 80.09742498397827,\n            \"ui_score\": 76,\n            \"output_mask_name\": \"texture_output.png\"\n        },\n        \"all\": {\n            \"score\": 75.75757575757575\n        },\n        \"skin_age\": 37\n    }\n    ```\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n| AI 功能 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 |\n| ---- | ---- | ---- | ---- |\n| SD 護膚 | 短邊長度至少需 480 像素。 <br> 長邊沒有限制；但若超過 2560 像素，系統會自動調整為 2560 像素。 | < 10MB | jpg/jpeg/png |\n| HD 護膚 | 短邊長度至少需 1080 像素。 <br> 長邊沒有限制；但若超過 2560 像素，會自動調整為 2560 像素。 |< 10MB | jpg/jpeg/png |\n\n> **警告：** 雖然 API 會自動將圖片調整至最大 2560 像素，您仍需確保所有臉部清晰對焦、影像品質高、光線均勻，且臉部足夠大並正對鏡頭。在執行 AI 肌膚檢測前拍攝 HD 或 SD 護膚影像時，必須避免動態模糊與遮擋。為達到最佳結果，強烈建議使用直式長寬比，而非橫式。\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* 直視鏡頭，並將臉部保持在中央\n\n* 照片需求\n我們會檢查影像品質，確保適合 AI 肌膚檢測。請確保臉部佔圖片寬度約 60–80%，無任何疊加或遮擋。光線應明亮且均勻分布，避免過度曝光或高光溢出。姿勢應正面、中性且放鬆，嘴巴閉合、雙眼睜開。\n\n您應完全露出額頭，並將瀏海往後梳或綁起頭髮，以確保最佳品質。建議您摘下眼鏡以達到最佳的 AI 肌膚檢測效能，但這並非強制要求。\n> **警告：** 臉部寬度需大於圖片寬度的 60%。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_error_src_face_too_small_cr_725792a7fb.png)\n\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n|error_below_min_image_size|輸入圖片解析度過小|\n|error_exceed_max_image_size|輸入圖片解析度過大|\n|error_src_face_too_small|上傳圖片中的臉部區域過小。臉部寬度需大於圖片寬度的 60%。|\n|error_src_face_out_of_bound|上傳圖片中的臉部區域超出邊界|\n|error_lighting_dark|上傳圖片的光線過暗|\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n\n* AI 肌膚檢測 V2.1\n\n| AI 功能 | SD | HD | 加值：進階肌膚報告 | 加值：產品推薦 |\n|---|---|---|---|---|\n| 檢測 1~4 項肌膚困擾 | 9 | 12 | +15 點 | +10 點 |\n| 檢測 5~8 項肌膚困擾 | 12 | 16 | +25 點 | +15 點 |\n| 檢測 9~12 項肌膚困擾 | 14 | 20 | +35 點 | +20 點 |\n| 檢測 13~16 項肌膚困擾 | 16 | 22 | +40 點 | +25 點 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## Mobile Camera Kit\n{% partial file=\"/_partials/mobile-camera-kit.md\" /%}\n\n---\n\n## 使用案例\n\n**Base URL：** `https://yce-api-01.makeupar.com`\n**分析端點：** `POST /s2s/v2.1/task/skin-analysis`\n**認證：** `Authorization: Bearer YOUR_API_KEY` — 請注意 `Bearer` 與 API key 之間有一個空格。\n\n```bash\nexport API_KEY=\"your-api-key\"\nexport BASE_URL=\"https://yce-api-01.makeupar.com\"\n```\n\n每個使用案例各有自己的端點，請依您需要的加值功能選擇：\n\n| 模式 | `advanced_report` | `product_recommendation` | `llm_results.json` 會回傳什麼 |\n|---|---|---|---|\n| **[肌膚檢測（標準）](/reference/ai_skin_analysis/standard-analysis/endpoint-overview)** | 不送 | 不送 | 各檢測維度的肌膚困擾分數 |\n| **[肌膚檢測＋進階肌膚報告](/reference/ai_skin_analysis/analysis-+-advanced-report/endpoint-overview)** | 有送 | 不送 | 分數，外加一份說明成因與保養建議的個人化報告 |\n| **[肌膚檢測＋產品推薦](/reference/ai_skin_analysis/analysis-+-product-recommendation/endpoint-overview)** | 不送 | 有送 | 分數，外加從您的產品目錄比對出的產品 |\n| **[肌膚檢測＋進階肌膚報告＋產品推薦](/reference/ai_skin_analysis/analysis-+-report-+-recommendation/endpoint-overview)** | 有送 | 有送 | 一次呼叫拿到分數、報告與產品比對結果 |\n\n> **說明：** 有加值功能的模式，會在基礎點數之外產生額外的點數消耗。詳情請見[點數消耗](/reference/ai_skin_analysis/section/overview/unit-consumption)。\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_skin_analysis_v2_0.yaml","link":"/zh-tw/reference/ai_skin_analysis_v2_0","routeSlug":"/zh-tw/reference/ai_skin_analysis_v2_0","label":"AI 肌膚檢測 V2.0","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_skin_analysis_v2_0/section/概述","routeSlug":"/zh-tw/reference/ai_skin_analysis_v2_0/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_skin_analysis_v2_0/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_skin_analysis_v2_0/section/概述/整合指南"},{"type":"link","label":"輸入與輸出","link":"/zh-tw/reference/ai_skin_analysis_v2_0/section/概述/輸入與輸出","routeSlug":"/zh-tw/reference/ai_skin_analysis_v2_0/section/概述/輸入與輸出"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_skin_analysis_v2_0/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_skin_analysis_v2_0/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_skin_analysis_v2_0/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_skin_analysis_v2_0/section/概述/點數消耗"},{"type":"link","label":"JS Camera Kit","link":"/zh-tw/reference/ai_skin_analysis_v2_0/section/概述/js-camera-kit","routeSlug":"/zh-tw/reference/ai_skin_analysis_v2_0/section/概述/js-camera-kit"},{"type":"link","label":"Mobile Camera Kit","link":"/zh-tw/reference/ai_skin_analysis_v2_0/section/概述/mobile-camera-kit","routeSlug":"/zh-tw/reference/ai_skin_analysis_v2_0/section/概述/mobile-camera-kit"}]},{"type":"group","label":"V2.0","link":"/zh-tw/reference/ai_skin_analysis_v2_0/v2.0","routeSlug":"/zh-tw/reference/ai_skin_analysis_v2_0/v2.0","items":[{"label":"執行肌膚檢測任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_skin_analysis_v2_0/v2.0/paths/~1s2s~1v2.0~1task~1skin-analysis/post","routeSlug":"/zh-tw/reference/ai_skin_analysis_v2_0/v2.0/paths/~1s2s~1v2.0~1task~1skin-analysis/post","metadata":{"seo":{"title":"執行肌膚檢測任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/skin-analysis"},{"label":"查詢肌膚檢測任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_skin_analysis_v2_0/v2.0/paths/~1s2s~1v2.0~1task~1skin-analysis~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_skin_analysis_v2_0/v2.0/paths/~1s2s~1v2.0~1task~1skin-analysis~1{task_id}/get","metadata":{"seo":{"title":"查詢肌膚檢測任務的狀態。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/skin-analysis/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 肌膚檢測","version":"","description":"# 概述\n![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_demostore_skincarelive_topbanner.0cffe3a7.jpg)\nAI 護膚分析技術運用人工智慧的力量，以卓越的精準度分析皮膚的各個層面，從質地與色素到保濕與毛孔大小。運用先進的演算法與機器學習，AI 肌膚檢測能從單張正面自拍評估臉部膚況問題，提供精準的膚況分數與偵測遮罩，以實現依個人膚質與問題量身打造的產品推薦與護膚流程。\n\n這不僅提升護膚產品的有效性，也賦能使用者對其護膚方案做出明智的決策。透過 AI 肌膚檢測的整合，個人現在能在數據驅動的洞察與更有效護膚方案的承諾引導下，邁向更健康、更光采的肌膚。\n\n\n## 整合指南\n* 如何為 AI 肌膚檢測拍攝照片\n* 正面自拍\n  - 只需一張清晰的照片，直視鏡頭。讓頭髮放下垂於胸前，並確保直視前方，取得正面視角。\n  - 或者，使用 JS Camera Kit 拍照。只需讓頭髮放下垂於胸前，不要綁起。\n\n* 工作流程\n**肌膚檢測 API 使用指南**\n本指南說明如何使用 File API 與 AI 任務 API 上傳圖片並建立肌膚檢測任務。\n\n   * **步驟 1：調整來源圖片尺寸**</br>\n  調整您的照片以符合支援的尺寸——SD 長邊最多 2560 像素、短邊至少 480 像素；HD 長邊最多 2560 像素、短邊至少 1080 像素。細節請參考**[檔案規格與錯誤](#section/overview/File-Specs-and-Errors)**\n\n   * **步驟 2：透過 File API 上傳檔案 metadata**\n- 圖片需求\n    - 細節請參考**[檔案規格與錯誤](#section/overview/File-Specs-and-Errors)**\n\n發送 POST 請求以初始化檔案上傳：\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/file \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"files\": [\n      {\n        \"content_type\": \"image/png\",\n        \"file_name\": \"skin_analysis_01_3dbd1b6683.png\",\n        \"file_size\": 547541\n      }\n    ]\n  }'\n```\n\n- ***重要***：僅呼叫 File API 並不會上傳您的檔案。您必須**額外上傳**檔案到**File API 回應中提供的網址**。該網址就是您的上傳目的地，請確保檔案成功傳輸到該處後再繼續。\n\n  > **警告：** 請注意，若您未將檔案上傳到 File API 回應中提供的網址，使用 AI API 時會得到 500 Server Error / unknown_internal_error 或 404 Not Found 錯誤。\n\n***\n\n   * **步驟 3：取得上傳網址與檔案 ID**\n\n回應包含：\n\n*   `requests.url` – 用於圖片上傳的預簽名網址。\n*   `file_id` – 用於建立 AI 任務的識別碼。\n\n**回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"files\": [\n      {\n        \"content_type\": \"image/png\",\n        \"file_name\": \"skin_analysis_01_3dbd1b6683.png\",\n        \"file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n        \"requests\": [\n          {\n            \"method\": \"PUT\",\n            \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\",\n            \"headers\": {\n              \"Content-Length\": \"547541\",\n              \"Content-Type\": \"image/png\"\n            }\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n***\n\n   * **步驟 4：上傳圖片到預簽名網址**\n\n使用提供的 `requests.url` 與標頭：\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n  --header 'Content-Type: image/png' \\\n  --header 'Content-Length: 547541' \\\n  --data-binary @'./skin_analysis_01_3dbd1b6683.png'\n```\n\n***\n\n   * **步驟 5：建立 AI 任務**\n\n使用步驟 2 的 `file_id` 建立肌膚檢測任務：\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"src_file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n    \"dst_actions\": [\"wrinkle\", \"pore\", \"texture\", \"acne\"],\n    \"miniserver_args\": {\n      \"enable_mask_overlay\": true,\n      \"enable_dark_background_hd_pore\": true,\n      \"color_dark_background_hd_pore\": \"3D3D3D\",\n      \"opacity_dark_background_hd_pore\": 0.4\n      // 為簡潔起見，省略其他參數\n    },\n    \"format\": \"json\"\n  }'\n```\n  上傳完成後，您可以使用檔案 ID 或圖片檔案網址選擇要分析的任何膚況問題。請參考**[輸入與輸出](#section/overview/Inputs-and-Outputs)**。</br>\n  接著，使用\n  檔案 ID 或圖片檔案網址執行增強任務，並取得 ***task_id***。\n  請注意，**不**支援同時使用 SD 與 HD 膚況參數。\n\n- **使用現有的公開圖片網址**\n無需上傳，您可以在啟動 AI 任務時直接提供可公開存取的圖片網址。\n\n**回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT\"\n  }\n}\n```\n\n***\n\n   * **步驟 6：輪詢任務狀態**\n\n使用 `task_id` 取得任務結果：\n\n```bash\ncurl --request GET \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis/<YOUR_TASK_ID> \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'Content-Type: application/json'\n```\n這個 ***task_id*** 用於透過輪詢 GET 'task/skin-analysis' 監控任務狀態，以取得目前的引擎狀態。在引擎完成任務之前，狀態會維持為 'running'，此階段不會消耗點數。\n\n處理後的結果在完成後保留 30 天。\n- 無需短間隔輪詢。\n- 在保留期限內可彈性設定輪詢間隔。\n\n  > **重要：** 仍需要輪詢以查詢任務狀態，因為執行時間無法保證。\n\n引擎成功處理您的輸入檔案並生成結果影像後，任務會變為 'success' 狀態。您會取得處理後影像的網址，以及一個 dst_id，讓您在無需重新上傳結果圖片的情況下串接另一個 AI 任務。\n\n點數僅在這種情況下會被消耗。若引擎處理任務失敗，任務狀態會變為 'error'，且不會消耗點數。\n扣除點數時，系統會優先使用接近到期的點數。若到期日相同，則扣除最早取得的點數。\n\n\n***\n\n   * **步驟 7：解讀結果**\n\n回應包含：\n\n*   `ui_score` – 使用者友善的分數。\n*   `raw_score` – 原始分析分數。\n*   `mask_urls` – 偵測遮罩的網址。\n\n**回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"results\": {\n      \"output\": [\n        {\n          \"type\": \"texture\",\n          \"ui_score\": 68,\n          \"raw_score\": 57.33,\n          \"mask_urls\": [\"https://yce-us.s3-accelerate.amazonaws.com/...texture_output.jpg\"]\n        },\n        {\n          \"type\": \"pore\",\n          \"ui_score\": 92,\n          \"raw_score\": 95.34,\n          \"mask_urls\": [\"https://yce-us.s3-accelerate.amazonaws.com/...pore_output.jpg\"]\n        }\n        // 為簡潔起見，省略其他結果\n      ]\n    },\n    \"task_status\": \"success\"\n  }\n}\n```\n\n\n* 除錯指南\n> **警告：** 請注意，**不**支援同時使用 SD 與 HD 膚況參數。試圖偏離這些規格會導致 ***InvalidParameters*** 錯誤。\n\n  * 若您混合使用 HD 與 SD 膚況，會得到如下錯誤：\n    ```json\n    {\n        \"status\": 400,\n        \"error\": \"cannot mix HD and SD dst_actions\",\n        \"error_code\": \"InvalidParameters\"\n    }\n    ```\n  * 若您拼寫膚況錯誤，或傳送未知的膚況，會得到如下錯誤：\n    ```json\n    {\n        \"status\": 400,\n        \"error\": \"Not available dst_action abc123\",\n        \"error_code\": \"InvalidParameters\"\n    }\n    ```\n\n---\n\n* 實際範例：\n![](https://plugins-media.makeupar.com/webconsultation/images/skincare-widget/img_webcm_skincare_service_survey_demo.jpg)\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/skin_analysis_s5_poster_3_dt_85efe14952.png)\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Skincare_Pro_Medspa_Situation_Image_6aea6046f9.jpg)\n\n## 輸入與輸出\n* 輸入參數說明\n控制 AI 肌膚檢測結果視覺輸出有兩種選項：生成多張圖片，每個膚況以獨立的遮罩呈現；或使用 ``enable_mask_overlay`` 參數產生單張混合圖片。預設情況下，系統輸出多個遮罩，讓您完全控制如何將每個膚況遮罩與圖片混合。\n\n* 預設：enable_mask_overlay false\n  ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/mask_overlay_false_1920_ea1cde0ead.png)\n\n* 將 enable_mask_overlay 設為 true\n  ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/mask_overlay_1920_0fbb4786cc.png)\n\n----\n\n* 輸出 ZIP 資料結構說明\n系統提供一個 ZIP 檔案，內含 'skinanalysisResult' 資料夾。此資料夾包含一個 'score_info.json' 檔案，涵蓋所有偵測分數與結果圖片的參考。\n\n'score_info.json' 檔案包含所有肌膚檢測偵測結果，含數值分數與對應輸出遮罩檔案的名稱。\n\nPNG 檔案是可疊加在您原始圖片上的偵測結果遮罩。只需使用這些 PNG 檔案中的 alpha 值，將其與您的原始圖片混合，即可直接在來源圖片上看見偵測結果。\n\n* 肌膚檢測結果 ZIP 中的檔案結構\n* HD 護膚 ZIP\n  * skinanalysisResult\n    - score_info.json\n    - hd_acne_output.png\n    - hd_age_spot_output.png\n    - hd_dark_circle_output.png\n    - hd_droopy_lower_eyelid_output.png\n    - hd_droopy_upper_eyelid_output.png\n    - hd_eye_bag_output.png\n    - hd_firmness_output.png\n    - hd_moisture_output.png\n    - hd_oiliness_output.png\n    - hd_radiance_output.png\n    - hd_redness_output.png\n    - hd_texture_output.png\n    - hd_pore_output_all.png\n    - hd_pore_output_cheek.png\n    - hd_pore_output_forehead.png\n    - hd_pore_output_nose.png\n    - hd_wrinkle_output_all.png\n    - hd_wrinkle_output_crowfeet.png\n    - hd_wrinkle_output_forehead.png\n    - hd_wrinkle_output_glabellar.png\n    - hd_wrinkle_output_marionette.png\n    - hd_wrinkle_output_nasolabial.png\n    - hd_wrinkle_output_periocular.png\n    - hd_tear_trough.png\n    - hd_skin_type.png\n\n* SD 護膚 ZIP\n  * skinanalysisResult\n    - score_info.json\n    - acne_output.png\n    - age_spot_output.png\n    - dark_circle_v2_output.png\n    - droopy_lower_eyelid_output.png\n    - droopy_upper_eyelid_output.png\n    - eye_bag_output.png\n    - firmness_output.png\n    - moisture_output.png\n    - oiliness_output.png\n    - pore_output.png\n    - radiance_output.png\n    - redness_output.png\n    - texture_output.png\n    - wrinkle_output.png\n    - tear_trough.png\n    - skin_type.png\n\n* JSON 資料結構（score_info.json）\n  * \"all\"：介於 1 與 100 之間的浮點值，代表整體膚況。較高的分數代表更健康、更具美感的膚況。\n  * \"skin_age\"：相對於全年齡層一般人口分布，由 AI 推得的肌膚年齡。\n  * 每個類別包含：\n    * \"raw_score\"：範圍從 1 到 100 的浮點值。較高的分數代表更健康、更具美感的膚況。\n    * \"ui_score\"：範圍從 1 到 100 的整數。UI 分數主要作為美妝評估中的心理激勵因素。我們調整原始分數以產生更理想的結果，因為理解消費者通常偏好關於其皮膚健康的正面評價。此校準旨在維持底層的美妝心理架構，同時為使用者注入更多信心。\n    * \"output_mask_name\"：對應輸出遮罩圖片的檔案名稱。\n\n  * 類別與說明\n    * HD 護膚：\n        * \"hd_redness\"：測量皮膚泛紅的嚴重程度。\n        * \"hd_oiliness\"：判定皮膚油脂程度。\n        * \"hd_age_spot\"：偵測老化斑點與色素。\n        * \"hd_radiance\"：評估皮膚光澤。\n        * \"hd_moisture\"：評估皮膚保濕程度。\n        * \"hd_dark_circle\"：分析眼下方黑眼圈的存在。\n        * \"hd_eye_bag\"：偵測眼袋。\n        * \"hd_droopy_upper_eyelid\"：測量上眼皮下垂的嚴重程度。\n        * \"hd_droopy_lower_eyelid\"：測量下眼皮下垂的嚴重程度。\n        * \"hd_firmness\"：評估皮膚緊實度與彈性。\n        * \"hd_texture\"：子類別[whole]；分析整體皮膚質地。\n        * \"hd_acne\"：子類別[whole]；偵測痤瘡的存在。\n        * \"hd_pore\"：子類別[forehead, nose, cheek, whole]；偵測並評估不同臉部區域的毛孔。\n        * \"hd_wrinkle\"：子類別[forehead, glabellar, crowfeet, periocular, nasolabial, marionette, whole]；測量各臉部區域皺紋的嚴重程度。\n        * \"hd_tear_trough\"：偵測淚溝。\n        * \"hd_skin_type\"：子類別[whole, t_zone, u_zone]，評估正常、油性、乾性、混合性、泛紅、乾性與泛紅、油性與泛紅、混合性與泛紅等膚質。\n\n    * SD 護膚：\n        * \"wrinkle\"：一般皺紋分析。\n        * \"droopy_upper_eyelid\"：測量上眼皮下垂的嚴重程度。\n        * \"droopy_lower_eyelid\"：測量下眼皮下垂的嚴重程度。\n        * \"firmness\"：評估皮膚緊實度與彈性。\n        * \"acne\"：評估痤瘡的存在。\n        * \"moisture\"：測量皮膚保濕。\n        * \"eye_bag\"：偵測眼袋。\n        * \"dark_circle_v2\"：以另一種方法分析黑眼圈。\n        * \"age_spot\"：偵測老化斑點。\n        * \"radiance\"：評估皮膚亮度。\n        * \"redness\"：測量皮膚泛紅。\n        * \"oiliness\"：判定皮膚油脂。\n        * \"pore\"：測量毛孔可見度。\n        * \"texture\"：分析整體皮膚質地。\n        * \"tear_trough\"：偵測淚溝。\n        * \"skin_type\"：子類別[whole, t_zone, u_zone]，評估正常、油性、乾性、混合性、泛紅、乾性與泛紅、油性與泛紅、混合性與泛紅等膚質。\n\n  * HD 護膚的 score_info.json 範例\n    ```json\n    {\n        \"hd_redness\": {\n            \"raw_score\": 72.011962890625,\n            \"ui_score\": 77,\n            \"output_mask_name\": \"hd_redness_output.png\"\n        },\n        \"hd_oiliness\": {\n            \"raw_score\": 60.74365234375,\n            \"ui_score\": 72,\n            \"output_mask_name\": \"hd_oiliness_output.png\"\n        },\n        \"hd_age_spot\": {\n            \"raw_score\": 83.23274230957031,\n            \"ui_score\": 77,\n            \"output_mask_name\": \"hd_age_spot_output.png\"\n        },\n        \"hd_radiance\": {\n            \"raw_score\": 76.57244205474854,\n            \"ui_score\": 79,\n            \"output_mask_name\": \"hd_radiance_output.png\"\n        },\n        \"hd_moisture\": {\n            \"raw_score\": 48.694559931755066,\n            \"ui_score\": 70,\n            \"output_mask_name\": \"hd_moisture_output.png\"\n        },\n        \"hd_dark_circle\": {\n            \"raw_score\": 80.1993191242218,\n            \"ui_score\": 76,\n            \"output_mask_name\": \"hd_dark_circle_output.png\"\n        },\n        \"hd_eye_bag\": {\n            \"raw_score\": 76.67280435562134,\n            \"ui_score\": 79,\n            \"output_mask_name\": \"hd_eye_bag_output.png\"\n        },\n        \"hd_droopy_upper_eyelid\": {\n            \"raw_score\": 79.05348539352417,\n            \"ui_score\": 80,\n            \"output_mask_name\": \"hd_droopy_upper_eyelid_output.png\"\n        },\n        \"hd_droopy_lower_eyelid\": {\n            \"raw_score\": 79.97175455093384,\n            \"ui_score\": 81,\n            \"output_mask_name\": \"hd_droopy_lower_eyelid_output.png\"\n        },\n        \"hd_firmness\": {\n            \"raw_score\": 89.66898322105408,\n            \"ui_score\": 85,\n            \"output_mask_name\": \"hd_firmness_output.png\"\n        },\n        \"hd_texture\": {\n            \"whole\": {\n                \"raw_score\": 66.3921568627451,\n                \"ui_score\": 75,\n                \"output_mask_name\": \"hd_texture_output.png\"\n            }\n        },\n        \"hd_acne\": {\n            \"whole\": {\n                \"raw_score\": 59.92677688598633,\n                \"ui_score\": 76,\n                \"output_mask_name\": \"hd_acne_output.png\"\n            }\n        },\n        \"hd_pore\": {\n            \"forehead\": {\n                \"raw_score\": 79.59770965576172,\n                \"ui_score\": 80,\n                \"output_mask_name\": \"hd_pore_output_forehead.png\"\n            },\n            \"nose\": {\n                \"raw_score\": 29.139814376831055,\n                \"ui_score\": 58,\n                \"output_mask_name\": \"hd_pore_output_nose.png\"\n            },\n            \"cheek\": {\n                \"raw_score\": 44.11081314086914,\n                \"ui_score\": 65,\n                \"output_mask_name\": \"hd_pore_output_cheek.png\"\n            },\n            \"whole\": {\n                \"raw_score\": 49.23978805541992,\n                \"ui_score\": 67,\n                \"output_mask_name\": \"hd_pore_output_all.png\"\n            }\n        },\n        \"hd_wrinkle\": {\n            \"forehead\": {\n                \"raw_score\": 55.96956729888916,\n                \"ui_score\": 67,\n                \"output_mask_name\": \"hd_wrinkle_output_forehead.png\"\n            },\n            \"glabellar\": {\n                \"raw_score\": 76.7251181602478,\n                \"ui_score\": 75,\n                \"output_mask_name\": \"hd_wrinkle_output_glabellar.png\"\n            },\n            \"crowfeet\": {\n                \"raw_score\": 83.4361481666565,\n                \"ui_score\": 78,\n                \"output_mask_name\": \"hd_wrinkle_output_crowfeet.png\"\n            },\n            \"periocular\": {\n                \"raw_score\": 67.88706302642822,\n                \"ui_score\": 72,\n                \"output_mask_name\": \"hd_wrinkle_output_periocular.png\"\n            },\n            \"nasolabial\": {\n                \"raw_score\": 74.03312683105469,\n                \"ui_score\": 74,\n                \"output_mask_name\": \"hd_wrinkle_output_nasolabial.png\"\n            },\n            \"marionette\": {\n                \"raw_score\": 71.94477319717407,\n                \"ui_score\": 73,\n                \"output_mask_name\": \"hd_wrinkle_output_marionette.png\"\n            },\n            \"whole\": {\n                \"raw_score\": 49.64699745178223,\n                \"ui_score\": 65,\n                \"output_mask_name\": \"hd_wrinkle_output_all.png\"\n            }\n        },\n        \"all\": {\n            \"score\": 75.75757575757575\n        },\n        \"skin_age\": 37\n    }\n    ```\n  * SD 護膚的 score_info.json 範例\n    ```json\n    {\n        \"wrinkle\": {\n            \"raw_score\": 36.09360456466675,\n            \"ui_score\": 60,\n            \"output_mask_name\": \"wrinkle_output.png\"\n        },\n        \"droopy_upper_eyelid\": {\n            \"raw_score\": 79.05348539352417,\n            \"ui_score\": 80,\n            \"output_mask_name\": \"droopy_upper_eyelid_output.png\"\n        },\n        \"droopy_lower_eyelid\": {\n            \"raw_score\": 79.97175455093384,\n            \"ui_score\": 81,\n            \"output_mask_name\": \"droopy_lower_eyelid_output.png\"\n        },\n        \"firmness\": {\n            \"raw_score\": 89.66898322105408,\n            \"ui_score\": 85,\n            \"output_mask_name\": \"firmness_output.png\"\n        },\n        \"acne\": {\n            \"raw_score\": 92.29713000000001,\n            \"ui_score\": 88,\n            \"output_mask_name\": \"acne_output.png\"\n        },\n        \"moisture\": {\n            \"raw_score\": 48.694559931755066,\n            \"ui_score\": 70,\n            \"output_mask_name\": \"moisture_output.png\"\n        },\n        \"eye_bag\": {\n            \"raw_score\": 76.67280435562134,\n            \"ui_score\": 79,\n            \"output_mask_name\": \"eye_bag_output.png\"\n        },\n        \"dark_circle_v2\": {\n            \"raw_score\": 80.1993191242218,\n            \"ui_score\": 76,\n            \"output_mask_name\": \"dark_circle_v2_output.png\"\n        },\n        \"age_spot\": {\n            \"raw_score\": 83.23274230957031,\n            \"ui_score\": 77,\n            \"output_mask_name\": \"age_spot_output.png\"\n        },\n        \"radiance\": {\n            \"raw_score\": 76.57244205474854,\n            \"ui_score\": 79,\n            \"output_mask_name\": \"radiance_output.png\"\n        },\n        \"redness\": {\n            \"raw_score\": 72.011962890625,\n            \"ui_score\": 77,\n            \"output_mask_name\": \"redness_output.png\"\n        },\n        \"oiliness\": {\n            \"raw_score\": 60.74365234375,\n            \"ui_score\": 72,\n            \"output_mask_name\": \"oiliness_output.png\"\n        },\n        \"pore\": {\n            \"raw_score\": 88.38014125823975,\n            \"ui_score\": 84,\n            \"output_mask_name\": \"pore_output.png\"\n        },\n        \"texture\": {\n            \"raw_score\": 80.09742498397827,\n            \"ui_score\": 76,\n            \"output_mask_name\": \"texture_output.png\"\n        },\n        \"all\": {\n            \"score\": 75.75757575757575\n        },\n        \"skin_age\": 37\n    }\n    ```\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n| AI 功能 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 |\n| ---- | ---- | ---- | ---- |\n| SD 護膚 | 短邊長度至少需 480 像素。 <br> 長邊沒有限制；但若超過 2560 像素，系統會自動調整為 2560 像素。 | < 10MB | jpg/jpeg/png |\n| HD 護膚 | 短邊長度至少需 1080 像素。 <br> 長邊沒有限制；但若超過 2560 像素，會自動調整為 2560 像素。 |< 10MB | jpg/jpeg/png |\n\n> **警告：** 雖然 API 會自動將圖片調整至最大 2560 像素，您仍需確保所有臉部清晰對焦、影像品質高、光線均勻，且臉部足夠大並正對鏡頭。在執行 AI 肌膚檢測前拍攝 HD 或 SD 護膚影像時，必須避免動態模糊與遮擋。為達到最佳結果，強烈建議使用直式長寬比，而非橫式。\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* 直視鏡頭，並將臉部保持在中央\n\n* 照片需求\n我們會檢查影像品質，確保適合 AI 肌膚檢測。請確保臉部佔圖片寬度約 60–80%，無任何疊加或遮擋。光線應明亮且均勻分布，避免過度曝光或高光溢出。姿勢應正面、中性且放鬆，嘴巴閉合、雙眼睜開。\n\n您應完全露出額頭，並將瀏海往後梳或綁起頭髮，以確保最佳品質。建議您摘下眼鏡以達到最佳的 AI 肌膚檢測效能，但這並非強制要求。\n> **警告：** 臉部寬度需大於圖片寬度的 60%。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_error_src_face_too_small_cr_725792a7fb.png)\n\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n|error_below_min_image_size|輸入圖片解析度過小|\n|error_exceed_max_image_size|輸入圖片解析度過大|\n|error_src_face_too_small|上傳圖片中的臉部區域過小。臉部寬度需大於圖片寬度的 60%。|\n|error_src_face_out_of_bound|上傳圖片中的臉部區域超出邊界|\n|error_lighting_dark|上傳圖片的光線過暗|\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n* AI 肌膚檢測 V2.0\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| 1~4 項分析 | SD 9 點；HD 12 點 | \n| 5~8 項分析 | SD 12 點；HD 16 點 |\n| 9~12 項分析 | SD 14 點；HD 20 點 |\n| 13~16 項分析 | SD 16 點；HD 22 點 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## Mobile Camera Kit\n{% partial file=\"/_partials/mobile-camera-kit.md\" /%}\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_skin_simulation.yaml","link":"/zh-tw/reference/ai_skin_simulation","routeSlug":"/zh-tw/reference/ai_skin_simulation","label":"AI 膚況模擬","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_skin_simulation/section/概述","routeSlug":"/zh-tw/reference/ai_skin_simulation/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_skin_simulation/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_skin_simulation/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_skin_simulation/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_skin_simulation/section/概述/檔案規格與錯誤"},{"type":"link","label":"JS Camera Kit","link":"/zh-tw/reference/ai_skin_simulation/section/概述/js-camera-kit","routeSlug":"/zh-tw/reference/ai_skin_simulation/section/概述/js-camera-kit"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_skin_simulation/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_skin_simulation/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_skin_simulation/v1.0","routeSlug":"/zh-tw/reference/ai_skin_simulation/v1.0","items":[{"label":"執行 AI 膚況模擬任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_skin_simulation/v1.0/paths/~1s2s~1v2.0~1task~1skin-simulation/post","routeSlug":"/zh-tw/reference/ai_skin_simulation/v1.0/paths/~1s2s~1v2.0~1task~1skin-simulation/post","metadata":{"seo":{"title":"執行 AI 膚況模擬任務。","description":"這個端點啟動膚況模擬流程。您必須提供來源檔案（透過網址或檔案 ID），並指定模擬參數（皺紋、光澤等）。至少有一個參數不能為零。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/skin-simulation"},{"label":"查詢 AI 膚況模擬任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_skin_simulation/v1.0/paths/~1s2s~1v2.0~1task~1skin-simulation~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_skin_simulation/v1.0/paths/~1s2s~1v2.0~1task~1skin-simulation~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 膚況模擬任務的狀態。","description":"查詢 AI 膚況模擬任務的狀態。"}},"httpPath":"/s2s/v2.0/task/skin-simulation/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 膚況模擬","version":"","description":"# 概述\n**AI 驅動的膚況模擬：以精準與專業呈現治療進展**\n\n我們尖端的 AI 驅動膚況模擬技術，能高度準確地呈現臉部膚況的前後視覺化，讓專業人士與消費者都能客觀追蹤護膚治療隨時間的成效。此解決方案為高傳真寫實與臨床級洞察而設計，支援多達十種不同膚況問題的視覺化，包括光澤、痤瘡、油脂、眼袋、黑眼圈、斑點、毛孔、質地、皺紋與泛紅。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-04-17/4edad54f-ef6b-4842-b104-d114889318b1.jpg)\n\n透過結合精密的機器學習模型與先進的擴增實境能力，系統僅需一般智慧型手機鏡頭或桌面網路攝影機，即可提供潛在結果的真實、非侵入式預覽。每次模擬在數秒內生成，讓使用者立即獲得有科學根據的理解，了解針對性的護膚介入如何隨時間改善膚況。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-11-13/webp_27e3ad50-7769-46de-822c-c9300f87f57d.webp)\n\n此平台專為護膚品牌、皮膚科診所、醫學美容診所與美妝零售業設計，可輕鬆整合於數位與實體接觸點，包括電子商務網站、行動應用、虛擬諮詢與銷售點自助服務機。其多元性支援廣泛的使用案例，例如個人化護膚方案推薦、產品效能模擬、專業療程的治療規劃，以及強化客戶互動並建立對品牌聲明信任的互動式教育工具。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_Skin_Simulation_pores_b1e209ee58.jpg)\n\n透過客觀的視覺化與數據驅動的敘事，我們的 AI 膚況模擬讓護膚專業人士能設定切合實際的期望、客製化護理計畫，並展示可衡量的進展，最終提升客戶體驗，同時在日益競爭的市場中強化有實證根據的療效。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_Skin_Simulation_283421234a.jpg)\n\n---\n\n## 整合指南\n本指南將引導您完成：\n\nAI 膚況模擬 API 的工作流程：\n\n**端點：** `/s2s/v2.0/task/skin-simulation`\n\n**需要認證：** `Authorization: Bearer YOUR_API_KEY`\n\n**工作流程步驟：**\n\n1. **圖片上傳準備：**\n   - 流程從準備自拍圖片開始。\n\n2. **AI 膚況模擬設定**\n    針對每個膚況問題（例如皺紋、毛孔、泛紅），使用 **0.0 到 1.0** 的值調整**模擬強度**：\n\n    - **0.0**：顯示您*原始*的肌膚外觀——無變化。\n    - **1.0**：套用 AI 能針對該問題生成的*最自然、最健康外觀*的增強。\n\n    **運作方式：**\n    - 在低設定（例如 0.2–0.4）時，細紋或輕微瑕疵會被細微地柔化。\n    - 在較高設定（例如 0.7–1.0）時，改善更明顯，例如顯著減少中度或深層皺紋、更平滑的質地與更好的膚色，同時保留自然的肌膚細節。\n\n    逐步調整以達成您想要的外觀！\n\n1. **啟動 AI 任務並取得任務 ID：**\n   - 透過 HTTP POST 請求，將上傳的圖片與膚況模擬設定傳送到 `/s2s/v2.0/task/skin-simulation`。\n   - 在回應中取得唯一的任務 ID，用以識別這次互動。\n\n2. **輪詢任務狀態（持續檢查）：**\n   - 使用取得的 `task_id`，透過 HTTP GET 請求（例如 `GET /task/${task_id}`）定期輪詢任務狀態。\n   - 持續監控：\n     - `Task_status = \"success\"`（流程完成）。\n     - `Task_status = \"error\"`（視情況解決或重試）。\n   - 狀態轉為成功後，相應更新工作流程。\n\n這個結構化的工作流程確保與使用者輸入的高效整合、任務的自動化監控，以及無縫取得結果。\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n    ```\n    Authorization: Bearer YOUR_API_KEY\n    ```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n---\n\n* 上傳圖片\n\n您可以直接上傳檔案到伺服器，或在 AI 任務內容中提供有效的圖片網址。\n\n   * 上傳端點\n\n```\nPOST /s2s/v2.0/file\n```\n\n或者，若您已有公開的圖片網址，可跳過此步驟。\n\n---\n\n* 調整 AI 膚況模擬強度\n**AI 膚況模擬設定**\n\n針對每個膚況問題（例如皺紋、毛孔、泛紅），在 **0.0 到 1.0** 的尺度上調整**模擬強度**：\n\n- **0.0** → *原始外觀* — 未套用 AI 增強。\n- **1.0** → 針對該問題*最大自然、健康外觀的改善*，由我們的 AI 模型寫實地渲染。\n\n**不同強度等級的預期效果：**\n\n| 強度範圍 | 效果 |\n|-----------------|--------|\n| **0.1 – 0.3**   | 細微精修—輕度柔化細紋、細微柔化毛孔，或溫和減少泛紅。最適合自然的「清新面容」。 |\n| **0.4 – 0.6**   | 均衡增強—在保留個人肌膚特質的同時，質地與清晰度有明顯改善。 |\n| **0.7 – 1.0**   | 完整修正—顯著減少中度到深層皺紋、均勻膚色、縮小毛孔與泛紅，並提升整體光澤—*不會*看起來過度修飾或不自然。 |\n\n**專業提示：** 從低值開始（例如 0.2），逐步提高，直到達到滿意的寫實結果。\n\n---\n\n* 建立 AI 膚況模擬任務並輪詢結果\n\n上傳圖片並設定**至少一個**膚況問題的模擬強度高於 0.0 後，即可啟動任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 `success` 或 `error`。\n\n   * 建立任務端點\n\n```\nPOST /s2s/v2.0/task/skin-simulation\n```\n\n   * 輪詢端點\n\n```\nGET /s2s/v2.0/task/skin-simulation/{task_id}\n```\n\n---\n\n## 檔案規格與錯誤\n\n* AI 膚況模擬規範\n\n**攝影與影像指引**\n\n**光線條件**\n確保環境光線充足且均勻照明。避免強逆光、局部過度曝光，或臉上出現大片陰影。盡可能使用自然日光或柔和的室內光線。不要使用有色光，包括粉色、藍色或其他帶色調的光源，因為它們可能扭曲膚色的呈現。\n\n**臉部位置與遮擋**\n拍攝正對鏡頭的正面視角。頭部旋轉應盡量小；避免過度傾斜或轉向兩側。確保整張臉，包括額頭、臉頰與下巴，完全可見且無遮擋。不要使用頭髮、口罩、手、眼鏡框、手機，或其他部分覆蓋臉部特徵的物件。\n\n**臉部表情與姿勢**\n保持自然、放鬆的表情，雙眼睜開。嘴巴可保持閉合或略微張開，不要勉強或誇張姿勢。\n\n**臉部在畫面中的尺寸**\n臉部必須佔圖片寬度的至少 60%，以確保有足夠細節供精準分析。避免拍攝過小、過遠，或構圖不當的主體。\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_skin_analysis_01_5b5defd339.png)\n\n\n---\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 膚況模擬|短邊 >= 480，長邊 <= 2560|< 10MB|jpg/jpeg/png|\n\n* 錯誤代碼\n\n| **錯誤代碼**                     | **說明** |\n|------------------------------------|----------------|\n| `error_below_min_image_size`       | 輸入圖片解析度低於最小要求尺寸（例如 < 256×256 像素）。請上傳更高解析度的圖片。 |\n| `error_exceed_max_image_size`      | 輸入圖片解析度超過允許的最大尺寸（例如 > 2560×2560 像素）。請在上傳前調整或縮小圖片。 |\n| `error_invalid_params`             | 提供了無效的請求參數。 |\n| `error_src_face_too_small`         | 偵測到的臉部佔圖片寬度不到 60%——太小，無法進行精準的肌膚檢測。請使用臉部更大、更清晰且位於畫面中央的圖片。 |\n| `error_src_face_out_of_bound`      | 偵測到的臉部部分或完全在圖片邊界之外（例如臉部裁切過緊）。請確保完整臉部——包括額頭、臉頰與下巴——可見且構圖得當。 |\n| `error_lighting_dark`              | 影像中的環境光線不足以進行可靠的肌膚檢測（例如曝光不足、陰影主導臉部）。請上傳在光線充足條件下拍攝、臉部照明均勻的圖片。 |\n\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## 點數消耗\n\n* 膚況模擬\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| 1~4 項分析 | 4 |\n| 5~10 項分析 | 6 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_skin_tone_analysis.yaml","link":"/zh-tw/reference/ai_skin_tone_analysis","routeSlug":"/zh-tw/reference/ai_skin_tone_analysis","label":"AI 臉部色彩分析","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_skin_tone_analysis/section/概述","routeSlug":"/zh-tw/reference/ai_skin_tone_analysis/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_skin_tone_analysis/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_skin_tone_analysis/section/概述/整合指南"},{"type":"link","label":"輸入與輸出","link":"/zh-tw/reference/ai_skin_tone_analysis/section/概述/輸入與輸出","routeSlug":"/zh-tw/reference/ai_skin_tone_analysis/section/概述/輸入與輸出"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_skin_tone_analysis/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_skin_tone_analysis/section/概述/檔案規格與錯誤"},{"type":"link","label":"JS Camera Kit","link":"/zh-tw/reference/ai_skin_tone_analysis/section/概述/js-camera-kit","routeSlug":"/zh-tw/reference/ai_skin_tone_analysis/section/概述/js-camera-kit"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_skin_tone_analysis/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_skin_tone_analysis/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_skin_tone_analysis/v1.0","routeSlug":"/zh-tw/reference/ai_skin_tone_analysis/v1.0","items":[{"label":"執行膚色分析任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_skin_tone_analysis/v1.0/paths/~1s2s~1v2.0~1task~1skin-tone-analysis/post","routeSlug":"/zh-tw/reference/ai_skin_tone_analysis/v1.0/paths/~1s2s~1v2.0~1task~1skin-tone-analysis/post","metadata":{"seo":{"title":"執行膚色分析任務。","description":"這個端點啟動膚色分析流程。您必須提供來源檔案（透過網址或檔案 ID），並可選指定臉部角度的嚴格程度。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/skin-tone-analysis"},{"label":"查詢膚色分析任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_skin_tone_analysis/v1.0/paths/~1s2s~1v2.0~1task~1skin-tone-analysis~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_skin_tone_analysis/v1.0/paths/~1s2s~1v2.0~1task~1skin-tone-analysis~1{task_id}/get","metadata":{"seo":{"title":"查詢膚色分析任務的狀態。","description":"查詢膚色分析任務的狀態。"}},"httpPath":"/s2s/v2.0/task/skin-tone-analysis/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 臉部色彩調分析儀","version":"","description":"# 概述\nAI 臉部色彩分析偵測臉部膚色，以及眼睛、眉毛、嘴唇與頭髮的顏色。這項包容性的技術為所有族裔確保完整的客製化購物體驗。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/img_Face_Ratio_sec_02_02_enu_21a3d8d423.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/shade_finder_s5_poster_2_8a8f9307d2.png)\n\n\n## 整合指南\n* 如何為 AI 臉部色彩分析拍攝照片\n\n  正面自拍\n  - 只需一張清晰的照片，直視鏡頭。讓頭髮放下垂於胸前，並確保直視前方，取得正面視角。\n  - 或者，使用 JS Camera Kit 拍照。只需讓頭髮放下垂於胸前，不要綁起。\n\n* 如何用 AI 偵測膚況問題\n1. **調整來源圖片尺寸**</br>\n  調整您的照片以符合支援的尺寸。細節請參考**[檔案規格與錯誤](#section/overview/File-Specs-and-Errors)**\n\n2. **使用 File API 上傳檔案**</br>\n  使用 ***/s2s/v2.0/file*** API 上傳目標使用者圖片。\n    - 圖片需求\n      - 細節請參考**[檔案規格與錯誤](#section/overview/File-Specs-and-Errors)**。\n    - ***重要***：僅呼叫 File API 並不會上傳您的檔案。您必須**手動上傳**檔案到**File API 回應中提供的網址**。該網址就是您的上傳目的地，請確保檔案成功傳輸到該處後再繼續。<br>\n    在呼叫 AI API 之前，請確保您的檔案已成功上傳。使用 File API 取得上傳網址，然後將檔案上傳到該位置。上傳完成後，您會在回應中取得 ***file_id***，這個 ID 就是您用於存取該檔案相關 AI 功能的依據。\n\n      > **警告：** 請注意，若您未將檔案上傳到 File API 回應中提供的網址，使用 AI API 時會得到 500 Server Error / unknown_internal_error 或 404 Not Found 錯誤。\n\n3. **執行 AI 臉部色彩分析任務**</br>\n  上傳完成後，AI 將使用您的檔案 ID 檢查您嘴唇、眼睛、眉毛、皮膚與頭髮的色調。請參考**[輸入與輸出](#section/overview/Inputs-and-Outputs)**。</br>\n  接著，使用\n  檔案 ID 執行增強任務，並取得 ***task_id***。\n\n4. **輪詢以查詢任務狀態直到成功或錯誤**</BR>\n這個 ***task_id*** 用於透過輪詢 GET 'task/skin-tone-analysis' 監控任務狀態，以取得目前的引擎狀態。在引擎完成任務之前，狀態會維持為 'running'，此階段不會消耗點數。\n\n    **警告：** 請注意，依據任務的保留期間**輪詢**以查詢任務狀態是強制性的。若在保留期間內沒有輪詢請求，任務將被逾時，即使任務已成功處理（您的點數仍會被消耗）。\n\n    > **警告：** 一旦您查詢已逾時任務的狀態，會得到 ***InvalidTaskId*** 錯誤。因此，執行 AI 任務後，您需要在保留期間內**輪詢**以查詢狀態，直到狀態變為 *success* 或 *error*。\n\n5. **成功後取得 AI 任務的結果**</BR>\n引擎成功處理您的輸入檔案並生成結果影像後，任務會變為 'success' 狀態。您會取得處理後影像的網址，以及一個 dst_id，讓您在無需重新上傳結果圖片的情況下串接另一個 AI 任務。\n點數僅在這種情況下會被消耗。若引擎處理任務失敗，任務狀態會變為 'error'，且不會消耗點數。</BR>\n扣除點數時，系統會優先使用接近到期的點數。若到期日相同，則扣除最早取得的點數。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2022-08-19/2a1af800-7c69-44a5-a94c-70a4a9c4d2b0.jpg)\n\n---\n\n## 輸入與輸出\n* 輸入\nAI 會分析您皮膚的色調。您可以調整 `face_angle_strictness_level` 來控制輸入臉部角度的檢查嚴格程度，範圍從 strict、high、medium、low 到 flexible。嚴格程度適用於臉部角度偵測，包括 pitch、yaw 與 roll。較嚴格的等級可確保更準確的臉部特徵結果。預設設定為 high。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/shade_finder_s4_poster_399f34c6ef.jpg)\n\n* 輸出\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_status\": \"success\",\n    \"results\": {\n      \"color\": {\n        \"eye_color\": \"#293F9B\",\n        \"eye_color_name\": \"Blue\",\n        \"lip_color\": \"#D23245\",\n        \"eyebrow_color\": \"#5B2B31\",\n        \"skin_color\": \"#b9947c\",\n        \"hair_color\": \"#a0a0a0\",\n        \"hair_color_name\": \"Auburn\"\n      }\n    }\n  }\n}\n```\n\n| **結果參數** | **結果類型** |\n|  --- | --- |\n| `skin_color` | 十六進位值 |\n| `eye_color`| 十六進位值 |\n| `eye_color_name` | 琥珀色、棕色、綠色、藍色、灰色、其他 |\n| `lip_color` | 十六進位值 |\n| `eyebrow_color` | 十六進位值 |\n| `hair_color` | 十六進位值 |\n| `color.hair_color_name` | 紅棕色、黑色、金色、棕色、灰白、紅色 |\n\n\n* 拍攝建議：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png)\n\n> **警告：** 臉部寬度需大於圖片寬度的 60%。\n\n---\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n| AI 功能 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 |\n| ---- | ---- | ----  | ---- |\n| AI 臉部色彩分析 | 長邊 <= 4096，僅限單人。邊長超過 1080px 的圖片會自動調整尺寸以進行分析。 | < 10MB | jpg/jpeg/png |\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| error_below_min_image_size | 來源圖片尺寸必須至少為 320 像素。 |\n| error_face_position_invalid | 臉部必須完全可見、面向前方，並位於圖片中央。 |\n| error_face_position_too_small | 偵測到的臉部太小，無法分析。 |\n| error_face_position_out_of_boundary | 臉部超出圖片邊界。 |\n| error_face_not_forward_facing | 臉部必須正對鏡頭。 |\n| error_face_angle_upward | 臉部向上偏轉過多—請稍微低頭。 |\n| error_face_angle_downward | 臉部向下偏轉過多—請稍微抬頭。 |\n| error_face_angle_leftward | 臉部向左轉轉過多—請稍微向右轉頭。 |\n| error_face_angle_rightward | 臉部向右轉過多—請稍微向左轉頭。 |\n| error_face_angle_left_tilt | 臉部向左傾斜過多—請輕輕向右傾頭。 |\n| error_face_angle_right_tilt | 臉部向右傾斜過多—請輕輕向左傾頭。 |\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 臉部色彩分析 V1.0 | 20 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_face_analyzer.yaml","link":"/zh-tw/reference/ai_face_analyzer","routeSlug":"/zh-tw/reference/ai_face_analyzer","label":"AI 臉部特徵與比例偵測","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_face_analyzer/section/概述","routeSlug":"/zh-tw/reference/ai_face_analyzer/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_face_analyzer/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_face_analyzer/section/概述/整合指南"},{"type":"link","label":"輸入與輸出","link":"/zh-tw/reference/ai_face_analyzer/section/概述/輸入與輸出","routeSlug":"/zh-tw/reference/ai_face_analyzer/section/概述/輸入與輸出"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_face_analyzer/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_face_analyzer/section/概述/檔案規格與錯誤"},{"type":"link","label":"JS Camera Kit","link":"/zh-tw/reference/ai_face_analyzer/section/概述/js-camera-kit","routeSlug":"/zh-tw/reference/ai_face_analyzer/section/概述/js-camera-kit"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_face_analyzer/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_face_analyzer/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_face_analyzer/v1.0","routeSlug":"/zh-tw/reference/ai_face_analyzer/v1.0","items":[{"label":"執行臉部特徵分析任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_face_analyzer/v1.0/paths/~1s2s~1v2.0~1task~1face-attr-analysis/post","routeSlug":"/zh-tw/reference/ai_face_analyzer/v1.0/paths/~1s2s~1v2.0~1task~1face-attr-analysis/post","metadata":{"seo":{"title":"執行臉部特徵分析任務。","description":"這個端點啟動臉部特徵分析流程。您必須提供來源檔案（透過網址或檔案 ID），並指定要分析哪些項目。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/face-attr-analysis"},{"label":"查詢臉部特徵分析任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_face_analyzer/v1.0/paths/~1s2s~1v2.0~1task~1face-attr-analysis~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_face_analyzer/v1.0/paths/~1s2s~1v2.0~1task~1face-attr-analysis~1{task_id}/get","metadata":{"seo":{"title":"查詢臉部特徵分析任務的狀態。","description":"查詢臉部特徵分析任務的狀態。"}},"httpPath":"/s2s/v2.0/task/face-attr-analysis/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 臉部特徵與比例偵測","version":"","description":"# 概述\nAI 臉部特徵與比例偵測檢視臉部結構，辨識臉型、眼睛、眉毛、嘴唇、鼻子、顴骨形狀等特徵，旨在提供個人化的推薦。\n\n## 整合指南\n* 如何為 AI 臉部特徵與比例偵測拍攝照片\n\n* 正面自拍\n  - 只需一張清晰的照片，直視鏡頭。最好讓頭髮自然垂落，整張臉可見且無遮蓋。將頭髮往後梳以露出額頭，並確保直視前方，拍攝標準的正面視角。\n  - 或者，使用 JS Camera Kit 拍照。遵循自動臉部對齊、光線引導與臉部尺寸偵測，確保照片符合處理所需的標準。\n\n* 如何用 AI 偵測膚況問題\n\n1. **調整來源圖片尺寸**</br>\n  調整您的照片以符合支援的尺寸。細節請參考**[檔案規格與錯誤](#section/overview/File-Specs-and-Errors)**\n\n2. **使用 File API 上傳檔案**</br>\n  使用 ***/s2s/v2.0/file*** API 上傳目標使用者圖片。\n    - 圖片需求\n      - 細節請參考**[檔案規格與錯誤](#section/overview/File-Specs-and-Errors)**。\n    - ***重要***：僅呼叫 File API 並不會上傳您的檔案。您必須**手動上傳**檔案到**File API 回應中提供的網址**。該網址就是您的上傳目的地，請確保檔案成功傳輸到該處後再繼續。<br>\n    在呼叫 AI API 之前，請確保您的檔案已成功上傳。使用 File API 取得上傳網址，然後將檔案上傳到該位置。上傳完成後，您會在回應中取得 ***file_id***，這個 ID 就是您用於存取該檔案相關 AI 功能的依據。\n\n      > **警告：** 請注意，若您未將檔案上傳到 File API 回應中提供的網址，使用 AI API 時會得到 500 Server Error / unknown_internal_error 或 404 Not Found 錯誤。\n\n3. **執行 AI 臉部特徵與比例偵測任務**</br>\n  上傳完成後，您可以使用檔案 ID 選擇多個要分析的臉部特徵。請參考**[輸入與輸出](#section/overview/Inputs-and-Outputs)**。</br>\n  接著，使用\n  檔案 ID 執行增強任務，並取得 ***task_id***。\n\n4. **輪詢以查詢任務狀態直到成功或錯誤**</BR>\n這個 ***task_id*** 用於透過輪詢 GET 'task/face-attr-analysis' 監控任務狀態，以取得目前的引擎狀態。在引擎完成任務之前，狀態會維持為 'running'，此階段不會消耗點數。\n\n    **警告：** 請注意，依據任務的保留期間**輪詢**以查詢任務狀態是強制性的。若在保留期間內沒有輪詢請求，任務將被逾時，即使任務已成功處理（您的點數仍會被消耗）。\n\n    > **警告：** 一旦您查詢已逾時任務的狀態，會得到 ***InvalidTaskId*** 錯誤。因此，執行 AI 任務後，您需要在保留期間內**輪詢**以查詢狀態，直到狀態變為 *success* 或 *error*。\n\n5. **成功後取得 AI 任務的結果**</BR>\n引擎成功處理您的輸入檔案並生成結果影像後，任務會變為 'success' 狀態。您會取得處理後影像的網址，以及一個 dst_id，讓您在無需重新上傳結果圖片的情況下串接另一個 AI 任務。\n點數僅在這種情況下會被消耗。若引擎處理任務失敗，任務狀態會變為 'error'，且不會消耗點數。</BR>\n扣除點數時，系統會優先使用接近到期的點數。若到期日相同，則扣除最早取得的點數。\n\n* 實際範例：\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-01-15/10a4b980-f571-4d08-8f5d-e3ed48db77aa.jpg)\n\n## 輸入與輸出\n* 臉部特徵：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/img_Face_Ratio_sec_01_01_enu_79380baa14.jpg)\n\n| **類別**     | **子類別**   | **請求參數** | **結果參數** | **結果類型** |\n| --- | --- | --- |  --- | --- |\n| **臉** | 臉型 | `faceShape` | `faceshape` | 三角形、菱形、心形、倒三角形、長形、橢圓形、圓形、方形、未知 |\n| **年齡與性別** | 年齡 | `age` | `agegender.age` | 整數 |\n| | 性別 | `gender` | `agegender.gender` | female、male、unknown |\n| **眼睛** | 眼型 | `eyeShape` | `eyelid.left_shape`、`eyelid.right_shape` | 窄、圓、杏仁 |\n| | 眼睛大小 | `eyeSize` | `eyelid.size` | 大、小、平均 |\n| | 眼睛角度 | `eyeAngle` | `eyelid.left_angle`、`eyelid.right_angle` | 下垂、上揚、平均 |\n| | 眼睛距離 | `eyeDistance` | `eyelid.setting` | 靠近、分開、平均 |\n| | 眼皮 | `eyelid` | `eyelid.left_eyelid`、`eyelid.right_eyelid` | 遮眼型、單眼皮、雙眼皮、深邃型 |\n| **眉毛** | 眉型 | `eyebrowShape` | `eyebrow.left_shape`、`eyebrow.right_shape` | 硬角、柔角、平直、圓弧、不明顯 |\n| | 眉毛厚度 | `eyebrowThickness` | `eyebrow.left_body_thickness`、`eyebrow.right_body_thickness` | 濃密、稀疏、平均、未知 |\n| | 眉毛距離 | `eyebrowDistance` | `eyebrow.gap` | 分開、靠近、平均 |\n| | 眉毛長度 | `eyebrowShortness` | `eyebrow.left_shortness`、`eyebrow.right_shortness` | 短、正常 |\n| **嘴唇** | 唇型 | `lipShape` | `lipshape[]` | 弓形、下垂、飽滿、下唇厚、上唇厚、窄、圓、薄、寬、平均 |\n| **鼻子** | 鼻寬 | `noseWidth` | `nose.width` | 窄、寬、平均 |\n| | 鼻長 | `noseLength` | `nose.length` | 長、短、平均 |\n| **顴骨**   | 顴骨 | `cheekbones` | `cheekbone.left`、`cheekbone.right`、`cheekbone.overall` | 平坦顴骨、高顴骨、低顴骨、圓臉頰 |\n\n\n---\n\n* 臉部比例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/img_Face_Ratio_sec_01_03_2fe8f06b92.jpg)\n\n| **子類別** | **請求參數** | **結果參數** | **結果類型** | **說明** |\n| --- | --- | --- | --- | --- |\n| 水平三等分比例 | `horizontalThird` | `horizontal_third` | 三段百分比；解讀：短／均衡／長；黃金比例：33% : 33% : 33% | 臉部水平比例基於將臉部分為三個等分：從髮際線到眉毛下緣、從眉毛下緣到鼻子下緣、從鼻子下緣到下巴尖端。三者之間的黃金比例（理想比例）為 1:1:1。|\n| 垂直五等分比例 | `verticalFifth` | `vertical_fifth` | 五段百分比；解讀（眼距與眼寬）：窄／均衡／寬；黃金比例：20% : 20% : 20% : 20% : 20% | 臉部垂直比例由將臉部分為五個區塊決定：一隻眼睛的寬度、兩眼之間的距離，以及從眼睛外角到臉部邊緣的間距。這些比例的黃金比例為 1:1:1:1:1。 |\n| 臉部長寬比 | `faceAspectRatio` | `face_aspect_ratio` | `[1, r]`；解讀：短／均衡／長；黃金比例：1 : 1.46 | 臉部長寬比是臉部寬度與高度的關係，理想上遵循 1:1.46 的黃金比例，創造均衡且具美感的視覺。 |\n| 眼睛長寬比 | `eyeAspectRatio` | `left_eye_aspect_ratio` `right_eye_aspect_ratio` | `[1, r]`；解讀：圓／均衡／平；黃金比例：1 : 3 | 眼睛長寬比是眼睛高度與寬度的關係，理想上符合 1:3 的黃金比例，確保最具美感的均衡視覺。\n |\n| 眉峰比例 | `eyebrowArch` | `left_eyebrow_arch_to_eyebrow_width` `right_eyebrow_arch_to_eyebrow_width` | `[1, r]`；解讀：短眉峰／均衡／長眉峰；黃金比例：1 : 1.618 | 眉峰的理想比例取決於眉毛本身的形狀，其最高點（眉峰）符合黃金比例，創造具美感的視覺。 |\n| 眼高到眉毛距離 | `eyeHeightToEyebrowDistance` | `left_eye_height_to_eyebrow_distance` `right_eye_height_to_eyebrow_distance` `overall_eye_height_to_eyebrow_distance` | `[1, r]`；解讀：短／均衡／長；黃金比例：1 : 1.618 | 眼到眉距離是從上眼皮頂部到眉毛最高點的垂直距離。理想上，與眼高相比遵循 1.618:1 的黃金比例，達到眼睛與眉毛之間最和諧的平衡。 |\n| 鼻子長寬比 | `noseAspectRatio` | `nose_aspect_ratio` | `[1, r]`；解讀：寬／均衡／窄；黃金比例：1 : 1.618 | 鼻子長寬比是鼻子寬度與高度的關係，理想上遵循 1:1.618 的黃金比例。 |\n| 鼻寬到嘴寬 | `noseWidthToMouthWidth` | `nose_width_to_mouth_width` | `[1, r]`；解讀：小／均衡／大；黃金比例：1 : 1.618 | 鼻寬到嘴寬比例是鼻子寬度與嘴巴寬度的關係，理想上遵循 1:1.618 的黃金比例，創造均衡且具美感的視覺。 |\n| 鼻到唇到下巴 | `noseToLipToChin` | `nose_to_lip_to_chin` | `[1, r]`；解讀：短／均衡／長（下臉長度）；黃金比例：1 : 1.618 | 鼻到唇到下巴比例是指從鼻底到唇中心的距離為 1，唇中心到下巴的理想距離為 1.618。這個黃金比例遵循臉部對稱原則，創造均衡和諧的下臉。 |\n| 上唇到下唇 | `upperLipToLowerLip` | `upper_lip_to_lower_lip` | `[1, r]`；解讀：上唇飽滿／均衡／下唇飽滿；黃金比例：1 : 1.618 | 上唇到下唇的黃金比例意指下唇厚度應為上唇的 1.618 倍。這個比例創造均衡且具美感的視覺，下唇略為飽滿於上唇。 |\n\n----\n\n* 拍攝建議：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_Face_Analysis_how_to_shoot_35ca9af08e.png)\n\n> **警告：** 臉部寬度需大於圖片寬度的 60%。\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 臉部特徵與比例偵測|長邊 <= 4096，僅限單人。邊長超過 1080px 的圖片會自動調整尺寸以進行分析。|< 10MB|jpg/jpeg/png|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| error_below_min_image_size | 來源圖片尺寸必須至少為 320 像素。 |\n| error_face_position_invalid | 臉部必須完全可見、面向前方，並位於圖片中央。 |\n| error_face_position_too_small | 偵測到的臉部太小，無法分析。 |\n| error_face_position_out_of_boundary | 臉部超出圖片邊界。 |\n| error_face_not_forward_facing | 臉部必須正對鏡頭。 |\n| error_face_angle_upward | 臉部向上偏轉過多—請稍微低頭。 |\n| error_face_angle_downward | 臉部向下偏轉過多—請稍微抬頭。 |\n| error_face_angle_leftward | 臉部向左轉轉過多—請稍微向右轉頭。 |\n| error_face_angle_rightward | 臉部向右轉過多—請稍微向左轉頭。 |\n| error_face_angle_left_tilt | 臉部向左傾斜過多—請輕輕向右傾頭。 |\n| error_face_angle_right_tilt | 臉部向右傾斜過多—請輕輕向左傾頭。 |\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## 點數消耗\n\n* 臉部特徵與比例偵測\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| 1~5 項臉部結構特徵 | 10 |\n| 6~14 項臉部結構特徵 | 20 |\n| 15~28 項臉部結構特徵 | 30 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_aging_simulation.yaml","link":"/zh-tw/reference/ai_aging_simulation","routeSlug":"/zh-tw/reference/ai_aging_simulation","label":"AI 年齡模擬器","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_aging_simulation/section/概述","routeSlug":"/zh-tw/reference/ai_aging_simulation/section/概述","items":[{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_aging_simulation/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_aging_simulation/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_aging_simulation/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_aging_simulation/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_aging_simulation/v1.0","routeSlug":"/zh-tw/reference/ai_aging_simulation/v1.0","items":[{"label":"執行 AI 年齡模擬任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_aging_simulation/v1.0/paths/~1s2s~1v2.0~1task~1aging/post","routeSlug":"/zh-tw/reference/ai_aging_simulation/v1.0/paths/~1s2s~1v2.0~1task~1aging/post","metadata":{"seo":{"title":"執行 AI 年齡模擬任務。","description":"這個端點啟動年齡模擬流程。您必須提供來源檔案（透過網址或檔案 ID）。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/aging"},{"label":"查詢 AI 年齡模擬任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_aging_simulation/v1.0/paths/~1s2s~1v2.0~1task~1aging~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_aging_simulation/v1.0/paths/~1s2s~1v2.0~1task~1aging~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 年齡模擬任務的狀態。","description":"查詢 AI 年齡模擬任務的狀態。"}},"httpPath":"/s2s/v2.0/task/aging/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 年齡模擬器","version":"","description":"# 概述\nAI 年齡模擬器運用生成式 AI 模型，從單張自拍照片生成從年輕到年長的一系列照片。借助 AI 技術，它不僅能量測您目前的年齡，也能讓您看見未來或過去的自己。\n\n![AI Aging Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/f42f1504_79e3_461c_a3f1_a254623d113b_b068736afb.jpg \"AI 年齡模擬器\")\n\nAI 年齡模擬器可根據單張輸入的自拍照片生成一系列照片。下方展示生成的範例照片，作為此功能的快速參考。\n![AI Aging Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/U_2024_04_17_cr_12112b83e2.png \"AI 年齡模擬器\")\n\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n| AI 功能 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 |\n| ---- | ---- | ----  | ---- |\n| AI 老化 | 長邊 <= 4096，僅限單人。臉部姿勢限制：yaw 在 ±30° 內、roll 在 ±20° 內、pitch 在 ±20° 內。 | < 10MB | jpg/jpeg |\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| error_below_min_image_size | 來源圖片尺寸必須至少為 320 像素。 |\n| error_face_position_invalid | 臉部必須完全可見、面向前方，並位於圖片中央。 |\n| error_face_position_too_small | 偵測到的臉部太小，無法分析。 |\n| error_face_position_out_of_boundary | 臉部超出圖片邊界。 |\n| error_face_not_forward_facing | 臉部必須正對鏡頭。 |\n| error_face_angle_upward | 臉部向上偏轉過多—請稍微低頭。 |\n| error_face_angle_downward | 臉部向下偏轉過多—請稍微抬頭。 |\n| error_face_angle_leftward | 臉部向左轉轉過多—請稍微向右轉頭。 |\n| error_face_angle_rightward | 臉部向右轉過多—請稍微向左轉頭。 |\n| error_face_angle_left_tilt | 臉部向左傾斜過多—請輕輕向右傾頭。 |\n| error_face_angle_right_tilt | 臉部向右傾斜過多—請輕輕向左傾頭。 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 年齡模擬器 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_face_reshape.yaml","link":"/zh-tw/reference/ai_face_reshape","routeSlug":"/zh-tw/reference/ai_face_reshape","label":"AI 臉部塑型","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_face_reshape/section/概述","routeSlug":"/zh-tw/reference/ai_face_reshape/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_face_reshape/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_face_reshape/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_face_reshape/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_face_reshape/section/概述/檔案規格與錯誤"},{"type":"link","label":"JS Camera Kit","link":"/zh-tw/reference/ai_face_reshape/section/概述/js-camera-kit","routeSlug":"/zh-tw/reference/ai_face_reshape/section/概述/js-camera-kit"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_face_reshape/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_face_reshape/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_face_reshape/v1.0","routeSlug":"/zh-tw/reference/ai_face_reshape/v1.0","items":[{"label":"執行 AI 臉部塑型的偵測任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1pre-process/post","routeSlug":"/zh-tw/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1pre-process/post","metadata":{"seo":{"title":"執行 AI 臉部塑型的偵測任務。","description":"當來源照片可能包含超過一個有效目標，或您的整合需要明確選擇哪個被偵測到的目標接受特效時，請使用前處理任務。對於單一目標的圖片，當功能支援預設的 index 值，且您的應用程式不需要手動選擇目標時，可以跳過前處理。"}},"httpPath":"/s2s/v2.0/task/face-reshape/pre-process"},{"label":"查詢 AI 臉部塑型偵測任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1pre-process~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1pre-process~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 臉部塑型偵測任務的狀態。","description":"當來源照片可能包含超過一個有效目標，或您的整合需要明確選擇哪個被偵測到的目標接受特效時，請使用前處理任務。對於單一目標的圖片，當功能支援預設的 index 值，且您的應用程式不需要手動選擇目標時，可以跳過前處理。"}},"httpPath":"/s2s/v2.0/task/face-reshape/pre-process/{task_id}"},{"label":"執行 AI 臉部塑型任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape/post","routeSlug":"/zh-tw/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape/post","metadata":{"seo":{"title":"執行 AI 臉部塑型任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/face-reshape"},{"label":"查詢 AI 臉部塑型任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 臉部塑型任務的狀態。","description":"查詢 AI 臉部塑型任務的狀態。"}},"httpPath":"/s2s/v2.0/task/face-reshape/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 臉部塑型","version":"","description":"# 概述\nAI 臉部塑型 API 讓您可以程式化地重塑臉部特徵——眼睛、鼻子、嘴唇、下顎線，或整張臉——達到像素級的精準控制。用它為鼻整形、下巴填充、嘴唇豐唇、眉部提拉及其他美學療程工作流程，產生前後視覺化。\n\n* 鼻整形（隆鼻）\n我們的線上鼻整形模擬器提供醫療級的精準調整。不同於一般的照片編輯應用，它能全面模擬特定細節，包括鼻樑、提拉與鼻翼。透過超寫實的預覽，客戶能在諮詢前清楚呈現並探索理想的比例。\n\n* 下巴填充\n透過我們的線上模擬器，您可以預覽下巴填充達成的理想比例。微調下巴長度與下巴形狀，呈現後縮或短下巴的改善。在接受任何皮膚填充療程前，找到平衡臉部側影的最佳方案。\n\n* 嘴唇填充\n使用者可嘗試不同的嘴唇填充體積與形狀，模擬更飽滿嘴唇的外觀，幫助他們在進行療程前決定理想的結果。\n\n* 眉部提拉手術\n此功能讓使用者預覽眉部提拉的結果，透過提拉與重塑眉毛，創造更年輕、回春的外觀。\n\n\n\n## 整合指南\n本指南將引導您完成：\n\nAI 臉部塑型 API 的工作流程：\n\n**端點：** `/s2s/v2.0/file`\n\n**需要認證：** `Authorization: Bearer YOUR_API_KEY`\n\n**工作流程步驟：**\n\n1. **圖片上傳準備：**\n    - 準備要上傳的自拍圖片。\n    - 呼叫 File API `/s2s/v2.0/file` 取得上傳網址與相關的 `file_id`。\n    - 使用提供的上傳網址上傳自拍圖片。\n\n2. **多張臉部的選填前處理：**\n    - 若圖片中有多於一張臉部，請對自拍圖片進行前處理。\n\n3. **臉部塑型特效設定：**\n   - 先選擇眼睛、臉、嘴唇或鼻子的合適臉部塑型參數。\n\n4. **啟動 AI 任務並取得任務 ID：**\n   - 透過 HTTP POST 請求，將 `file_id` 與所選特效設定傳送到 `/s2s/v2.0/task/face-reshape`。\n   - 在回應中取得唯一的任務 ID，用以識別這次互動。\n\n5. **輪詢任務狀態（持續檢查）：**\n   - 使用取得的 `task_id`，透過 HTTP GET 請求（例如 `GET /s2s/v2.0/task/face-reshape/${task_id}`）定期輪詢任務狀態。\n   - 持續監控：\n     - `Task_status = \"success\"`（流程完成）。\n     - `Task_status = \"error\"`（視情況解決或重試）。\n   - 狀態轉為成功後，相應更新工作流程。\n\n這個結構化的工作流程確保與使用者輸入的高效整合、任務的自動化監控，以及無縫取得結果。\n\n---\n\n* API Playground\n\n使用我們的官方 playground 進行互動式探索與測試：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-face-reshape/](http://yce.makeupar.com/api-console/en/api-playground/ai-face-reshape/)\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n    ```\n    Authorization: Bearer YOUR_API_KEY\n    ```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n\n1. 上傳圖片\n\n    您可以直接上傳檔案到伺服器，或在 AI 任務內容中提供有效的圖片網址。\n\n    * 上傳端點\n\n        ```\n        POST /s2s/v2.0/file\n        ```\n\n    或者，若您已有公開的圖片網址，可跳過此步驟。\n\n---\n\n2. 準備特效範本\n\n   * 前處理\n        輸出以像素座標表示的偵測邊界框。使用結果的索引，在稍後建立臉部塑型 AI 任務。\n        ```\n        {\n            \"timed\": number,\n            \"result\": [\n                {\n                    \"left\": number,\n                    \"top\": number,\n                    \"width\": number,\n                    \"height\": number\n                }\n            ]\n        }\n        ```\n\n        * 特效範本 JSON Schema\n        ```\n        {\n            \"version\": \"1.0\",\n            \"index\": 0,\n            \"features\": {},\n            \"global\": {\n            \"skin_smooth_strength\": 50,\n            \"skin_smooth_color_intensity\": 50,\n            },\n        }\n        ```\n        index：來自前處理的偵測臉部索引。選填，預設 0。\n        features：必要，至少 1 個非零的臉部塑型參數，不可全為零。\n        skin_smooth_strength: 0~100\n        skin_smooth_color_intensity: 0~100\n\n        * 特效格式\n        - 臉\n        預設範圍：-100~100\n        顴骨與下顎的範圍：0~100\n        所有功能值不可同時為零，至少有一個功能值必須非零\n        ```\n        {\n            \"cheekbones\": 0,\n            \"jaw\": 0,\n            \"face_reshape_left\": 0,\n            \"face_reshape_right\": 0,\n            \"face_width\": 0,\n            \"chin_reshape_left\": 0,\n            \"chin_reshape_right\": 0,\n            \"chin_length\": 0,\n        }\n        ```\n\n        - 眼睛\n        預設範圍：-100~100\n        所有功能值不可同時為零，至少有一個功能值必須非零\n        ```\n        {\n            \"eye_size_left\": 0,\n            \"eye_size_right\": 0,\n            \"eye_distance\": 0,\n            \"eye_angle\": 0,\n            \"eye_height\": 0,\n            \"eye_width\": 0,\n        }\n        ```\n\n        - 鼻子\n        預設範圍：-100~100\n        所有功能值不可同時為零，至少有一個功能值必須非零\n        ```\n        {\n            \"nose_bridge_width\": 0,\n            \"nose_lift\": 0,\n            \"nose_size\": 0,\n            \"nose_tip\": 0,\n            \"nose_tip_width\": 0,\n            \"nose_wing\": 0\n        }\n        ```\n\n        - 嘴唇\n        預設範圍：-100~100\n        所有功能值不可同時為零，至少有一個功能值必須非零\n        ```\n        {\n            \"lip_size\": 0,\n            \"lip_width\": 0,\n            \"lip_peak\": 0,\n            \"lip_height_top\": 0,\n            \"lip_height_bottom\": 0,\n        }\n        ```\n\n        * 內容範例（可直接發送）\n        ```\n        {\n        \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/face_reshape_01_85c8ffc055.jpg\",\n        \"version\": \"1.0\",\n        \"source\": \"yco\",\n        \"features\": {\n            \"eye_size_left\": 80,\n            \"eye_size_right\": 80,\n            \"eye_width\": 0,\n            \"eye_height\": 0,\n            \"eye_distance\": 0,\n            \"eye_angle\": 0,\n            \"face_reshape_left\": 0,\n            \"face_reshape_right\": 0,\n            \"chin_reshape_left\": 20,\n            \"chin_reshape_right\": 20,\n            \"chin_length\": 0,\n            \"face_width\": -30,\n            \"cheekbones\": 0,\n            \"jaw\": 0,\n            \"lip_size\": 10,\n            \"lip_width\": 40,\n            \"lip_height_top\": 10,\n            \"lip_height_bottom\": 10,\n            \"lip_peak\": -10,\n            \"nose_size\": 30,\n            \"nose_lift\": -20,\n            \"nose_bridge_width\": 10,\n            \"nose_tip\": -10,\n            \"nose_wing\": 30,\n            \"nose_tip_width\": 30\n        },\n        \"global\": {\n            \"skin_smooth_strength\": 50,\n            \"skin_smooth_color_intensity\": 50\n        }\n        }\n        ```\n\n\n3. 建立臉部塑型 AI 任務並輪詢結果\n\n    當您取得圖片與完整的特效內容後，即可建立任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 `success` 或 `error`。\n\n   * 建立任務端點\n\n        ```\n        POST /s2s/v2.0/task/face-reshape\n        ```\n\n   * 輪詢端點\n\n        ```\n        GET /s2s/v2.0/task/face-reshape/{task_id}\n        ```\n\n---\n\n## 檔案規格與錯誤\n\n* AI 臉部塑型規範\n\n**支援的自拍視角**\n自拍照片中，臉部的寬與高需大於圖片寬度與高度的 1/20。\npitch、yaw 與 rolling 的臉部角度小於 30 度。\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_face_reshape_01_85c8ffc055.jpg)\n\n\n\n**臉部自訂參數指南**\n\n| 類別 | 參數        | 功能                             | 最小 (-100 / 0) | 最大 (100)    |\n| -------- | ---------------- | ------------------------------------ | -------------- | ------------ |\n| 眼睛     | 大小（左/右）       | 調整每隻眼睛的整體大小      | 小          | 大        |\n| 眼睛     | 寬度            | 調整水平跨度              | 窄         | 寬         |\n| 眼睛     | 高度           | 調整垂直跨度                | 窄／平  | 圓／高 |\n| 眼睛     | 距離         | 調整兩眼間的間距         | 靠近      | 分開     |\n| 眼睛     | 角度            | 調整旋轉傾斜              | 內傾    | 外傾 |\n| 臉     | 大小（左/右）       | 調整臉部每側的大小 | 小          | 大        |\n| 臉     | 下巴形狀（左/右） | 調整下巴輪廓寬度           | 窄         | 寬         |\n| 臉     | 下巴長度      | 調整下巴的垂直長度         | 短          | 長         |\n| 臉     | 寬度            | 調整整體臉部寬度         | 窄         | 寬         |\n| 臉     | 顴骨        | 調整顴骨的明顯程度         | 原始 (0)   | 內收    |\n| 臉     | 下顎              | 調整下顎線的明顯程度           | 原始 (0)   | 內收    |\n| 嘴唇     | 大小             | 調整嘴唇的整體體積            | 小          | 大        |\n| 嘴唇     | 寬度            | 調整水平跨度              | 窄         | 寬         |\n| 嘴唇     | 上唇高度     | 調整上唇厚度            | 薄           | 飽滿         |\n| 嘴唇     | 下唇高度     | 調整下唇厚度         | 薄           | 飽滿         |\n| 嘴唇     | 唇峰             | 調整丘比特弓的鮮明度        | 平滑         | 明確      |\n| 鼻子     | 大小             | 調整鼻子的整體大小             | 小          | 大        |\n| 鼻子     | 提拉             | 調整垂直位置            | 低            | 高         |\n| 鼻子     | 鼻樑           | 調整鼻樑寬度                 | 窄         | 寬         |\n| 鼻子     | 鼻尖              | 調整鼻尖的垂直角度    | 向上             | 向下         |\n| 鼻子     | 鼻翼             | 調整鼻孔寬度                | 窄         | 寬         |\n| 鼻子     | 寬度            | 調整鼻尖的寬度        | 窄         | 寬         |\n\n**說明：** *“左”與“右”指的是人物的視角，而非螢幕上觀看者的一側。*\n\n\n---\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 臉部塑型|長邊 <= 4096|< 10MB|jpg/jpeg/png|\n\n* 錯誤代碼\n\n| 錯誤代碼 | 說明 |\n|  ----  | ----  |\n| RUNTIME_ERROR | 臉部塑型執行期間發生不如預期的錯誤 |\n| PHOTO_DETECTION_FAIL | 無法正確處理使用者照片，例如未偵測到手 |\n| OBJECT_DETECTION_FAIL | 無法正確處理物件照片，例如未偵測到產品 |\n| PHOTO_CHECK_INVALID | 使用者照片的姿勢或尺寸無效 |\n| INPUT_ERROR | 輸入檔案格式不正確 |\n| INPUT_MAIN_IMAGE_EMPTY | 需要使用者圖片 |\n\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 臉部塑型 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_body_reshape.yaml","link":"/zh-tw/reference/ai_body_reshape","routeSlug":"/zh-tw/reference/ai_body_reshape","label":"AI 身形調整","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_body_reshape/section/概述","routeSlug":"/zh-tw/reference/ai_body_reshape/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_body_reshape/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_body_reshape/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_body_reshape/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_body_reshape/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_body_reshape/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_body_reshape/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_body_reshape/v1.0","routeSlug":"/zh-tw/reference/ai_body_reshape/v1.0","items":[{"label":"執行 AI 身形調整的偵測任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape~1pre-process/post","routeSlug":"/zh-tw/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape~1pre-process/post","metadata":{"seo":{"title":"執行 AI 身形調整的偵測任務。","description":"當來源照片可能包含超過一個有效目標，或您的整合需要明確選擇哪個被偵測到的目標接受特效時，請使用前處理任務。對於單一目標的圖片，當功能支援預設的 index 值，且您的應用程式不需要手動選擇目標時，可以跳過前處理。"}},"httpPath":"/s2s/v2.0/task/body-reshape/pre-process"},{"label":"查詢 AI 身形調整偵測任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape~1pre-process~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape~1pre-process~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 身形調整偵測任務的狀態。","description":"查詢 AI 身形調整偵測任務的狀態。"}},"httpPath":"/s2s/v2.0/task/body-reshape/pre-process/{task_id}"},{"label":"執行 AI 身形調整任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape/post","routeSlug":"/zh-tw/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape/post","metadata":{"seo":{"title":"執行 AI 身形調整任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/body-reshape"},{"label":"查詢 AI 身形調整任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 身形調整任務的狀態。","description":"查詢 AI 身形調整任務的狀態。"}},"httpPath":"/s2s/v2.0/task/body-reshape/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 身形調整","version":"","description":"# 概述\n用於身形調整與瘦身的 AI 身形調整 API\n用 AI 身體編輯器，在照片中充滿自信！雕塑、重塑並增強您的身體，達到自然、驚豔的比例。輕鬆重塑任何區域——腰、手臂、大腿、胸部等。輕輕一點，即可获得自然、驚豔的結果！\n\n\n## 整合指南\n本指南將引導您完成：\n\nAI 身形調整 API 的工作流程：\n\n**端點：** `/s2s/v2.0/task/body-reshape`\n\n**需要認證：** `Authorization: Bearer YOUR_API_KEY`\n\n**工作流程步驟：**\n\n1. **圖片上傳準備：**\n    - 準備要上傳的自拍圖片。\n    - 呼叫 File API `/s2s/v2.0/file` 取得上傳網址與相關的 `file_id`。\n    - 使用提供的上傳網址上傳自拍圖片。\n\n2. **團體照片的選填前處理：**\n    - 若圖片中有多於一人，請對自拍圖片進行前處理。\n\n3. **身形調整特效設定：**\n    - 先選擇合適的身形調整參數。\n\n4. **啟動 AI 任務並取得任務 ID：**\n    - 透過 HTTP POST 請求，將 `file_id` 與所選特效設定傳送到 `/s2s/v2.0/task/body-reshape`。\n    - 在回應中取得唯一的任務 ID，用以識別這次互動。\n\n5. **輪詢任務狀態（持續檢查）：**\n    - 使用取得的 `task_id`，透過 HTTP GET 請求（例如 `GET /s2s/v2.0/task/body-reshape/${task_id}`）定期輪詢任務狀態。\n    - 持續監控：\n    - `Task_status = \"success\"`（流程完成）。\n    - `Task_status = \"error\"`（視情況解決或重試）。\n    - 狀態轉為成功後，相應更新工作流程。\n\n這個結構化的工作流程確保與使用者輸入的高效整合、任務的自動化監控，以及無縫取得結果。\n\n---\n\n* API Playground\n\n使用我們的官方 playground 進行互動式探索與測試：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-body-reshape/](http://yce.makeupar.com/api-console/en/api-playground/ai-body-reshape/)\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n\n* 1. 上傳圖片\n\n您可以直接上傳檔案到伺服器，或在 AI 任務內容中提供有效的圖片網址。\n\n* 上傳端點\n\n```\nPOST /s2s/v2.0/file\n```\n\n或者，若您已有公開的圖片網址，可跳過此步驟。\n\n---\n\n* 2. 準備特效範本\n\n* 前處理\n輸出以像素座標表示的偵測邊界框。使用結果的索引，在稍後建立身形調整 AI 任務。\n```\n{\n\"timed\": number,\n\"result\": [\n{\n \"left\": number,\n \"top\": number,\n \"width\": number,\n \"height\": number\n}\n]\n}\n```\n\n* Effect Template JSON Schemas\n```\n{\n\"version\": \"1.0\",\n\"index\": 0,\n\"features\": {\n\"arm\": 0, // -100~100\n\"breast_left\": 0, // -100~100\n\"breast_right\": 0, // -100~100\n\"hip\": 0, // -100~100\n\"hip_lift\": 0, // -100~100\n\"leg\": 0, // -100~100\n\"neck_left\": 0, // 0~100\n\"neck_right\": 0, // 0~100\n\"shoulder_left\": 0, // -100~100\n\"shoulder_right\": 0, // -100~100\n\"squared_shoulder_left\": 0, // -100~100\n\"squared_shoulder_right\": 0, // -100~100\n\"slim\": 0, // -100~100\n\"taller\": 0, // 0~100\n\"waist\": 0, // -100~100\n\"belly\": 0 // -100~100\n}\n}\n```\nindex：來自前處理的偵測身體索引。選填，預設 0。\nfeatures：必要，至少 1 個非零的身形調整參數，不可全為零。\n\n\n* 內容範例（可直接發送）\n```\n{\n \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/body_reshape_02_7777218379.jpg\",\n \"version\": \"1.0\",\n \"index\": 0,\n \"features\": {\n\"arm\": 0,\n\"waist\": -20,\n\"taller\": 80,\n\"squared_shoulder_left\": 10,\n\"squared_shoulder_right\": 10,\n\"neck_left\": 0,\n\"neck_right\": 0,\n\"hip\": 10,\n\"breast_left\": 30,\n\"breast_right\": 30,\n\"slim\": -70,\n\"shoulder_left\": 30,\n\"shoulder_right\": 30,\n\"leg\": -30,\n\"hip_lift\": 0,\n\"belly\": -50\n }\n}\n```\n\n\n* 3. 建立身形調整 AI 任務並輪詢結果\n\n當您取得圖片與完整的特效內容後，即可建立任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 `success` 或 `error`。\n\n* 建立任務端點\n\n```\nPOST /s2s/v2.0/task/body-reshape\n```\n\n* 輪詢端點\n\n```\nGET /s2s/v2.0/task/body-reshape/{task_id}\n```\n\n---\n\n## 檔案規格與錯誤\n\n* AI 身形調整規範\n\n**支援的自拍視角**\n全身照，臉部表情與身體姿勢清晰可見。\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_body_reshape_02_7777218379.jpg)\n\n**可見度與姿勢需求**\n\n| **區域** | **來源圖片中必須滿足的條件** |\n|------------|---------------------------------------------------|\n| **頸部** | 頸部在來源圖片中必須可見。 |\n| **手臂** | 兩側手臂——上臂、前臂與手——都必須完整呈現。 |\n| **腿** | 整條腿必須出現在圖片中。 |\n| **臀部** | 臀部需要可見。 |\n| **臀部提拉** | 臀部需要可見。 |\n| **肩膀** | • 肩膀必須可見。<br>• 不允許舉手。<br>• 不允許 90° 側面姿勢。 |\n| **腹部** | 腹部必須可見。 |\n| **腰** | 腰部必須可見。 |\n| **胸部** | • 胸部區域必須出現在圖片中。<br>• 拍攝應包含臀部（即不是「不含半身的半個身體」）。<br>• 必須呈現胸部中央。 |\n| **瘦身** | 肩膀需要在畫面中。 |\n| **增高** | • 臀部必須出現。<br>• 半身視角應包含腿部（即腿部可見）。 |\n\n\n\n**身形調整自訂參數指南**\n\n| 類別 | 參數 | 功能 | 最小值 (-100 / 0) | 最大值 (100) |\n| -------- | --------- | -------- | -------------------- | --------------- |\n| 手臂| 強度 | 調整手臂的粗細 | 細 | 粗 |\n| 腹部| 強度 | 調整腹部突出 | 平坦 | 突出 |\n| 胸部| 強度（左/右） | 調整兩側的胸部體積 | 平坦 | 飽滿 |\n| 臀部提拉 | 強度 | 調整臀部的曲線與提拉（加入提臀效果） | 雕塑感（提拉且緊實） | 圓潤（提拉且更飽滿） |\n| 臀部大小 | 強度 | 調整臀部的整體寬度 | 窄 | 寬 |\n| 腿| 強度 | 調整腿的粗細 | 細 | 粗|\n| 頸部| 強度（左/右） | 調整兩側的頸部輪廓與雕塑| 原始 (0)| 內收 |\n| 肩膀寬度 | 強度（左/右） | 調整每側肩膀的跨度 | 窄 | 寬 |\n| 肩膀形狀 | 強度（左/右） | 調整每側肩膀的角度與斜度 | 斜肩 | 平肩 |\n| 瘦身| 強度 | 調整整體身體曲線 | 苗條 | 曲線玲瓏 |\n| 增高| 強度 | 調整整體人物身高 | 原始 (0) | 更高 |\n| 腰| 強度 | 調整腰線寬度 | 窄 | 寬 |\n\n**說明：** *“左”與“右”指的是人物的視角，而非螢幕上觀看者的一側。*\n\n\n---\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n| ---- | ---- | ---- | ---- |\n|AI 身形調整|長邊 <= 2048，短邊 >= 320|< 10MB|jpg/jpeg/png|\n\n* 錯誤代碼\n\n| 錯誤代碼 | 說明 |\n| ---- | ---- |\n| RUNTIME_ERROR | 身形調整執行期間發生不如預期的錯誤 |\n| PHOTO_DETECTION_FAIL | 無法正確處理使用者照片，例如未偵測到手 |\n| PHOTO_CHECK_INVALID | 使用者照片的姿勢或尺寸無效 |\n| INPUT_ERROR | 輸入檔案格式不正確 |\n| INPUT_MAIN_IMAGE_EMPTY | 需要使用者圖片 |\n\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>- curl >= 7.58（現代 TLS/HTTP 支援）</br>- jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>- Firefox >= 74</br>- Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 身形調整 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_breast_augmentation.yaml","link":"/zh-tw/reference/ai_breast_augmentation","routeSlug":"/zh-tw/reference/ai_breast_augmentation","label":"AI 豐胸模擬","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_breast_augmentation/section/概述","routeSlug":"/zh-tw/reference/ai_breast_augmentation/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_breast_augmentation/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_breast_augmentation/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_breast_augmentation/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_breast_augmentation/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_breast_augmentation/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_breast_augmentation/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_breast_augmentation/v1.0","routeSlug":"/zh-tw/reference/ai_breast_augmentation/v1.0","items":[{"label":"執行 AI 豐胸模擬任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_breast_augmentation/v1.0/paths/~1s2s~1v2.0~1task~1breast-shape/post","routeSlug":"/zh-tw/reference/ai_breast_augmentation/v1.0/paths/~1s2s~1v2.0~1task~1breast-shape/post","metadata":{"seo":{"title":"執行 AI 豐胸模擬任務。","description":"這個端點啟動豐胸模擬流程。您必須提供來源檔案（透過網址或檔案 ID），並指定強度等級。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/breast-shape"},{"label":"查詢 AI 豐胸模擬任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_breast_augmentation/v1.0/paths/~1s2s~1v2.0~1task~1breast-shape~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_breast_augmentation/v1.0/paths/~1s2s~1v2.0~1task~1breast-shape~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 豐胸模擬任務的狀態。","description":"查詢 AI 豐胸模擬任務的狀態。"}},"httpPath":"/s2s/v2.0/task/breast-shape/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 豐胸模擬","version":"","description":"# 概述\nAI 豐胸模擬提供強大且非侵入式的身材重塑解決方案，無需手術，也不需要恢復時間。透過先進的 AI 技術，您可以即刻呈現並探索理想的外觀，預覽前後結果，並輕鬆簡易地達成專業品質的增強。\n\n透過精修輪廓或校正視角問題，自然地增強您的照片。例如，若您尋求更平衡或更勻稱的上半身外觀，AI 豐胸模擬提供 AI 驅動的胸部輪廓增強。此功能運用智慧演算法，在需要的地方溫和地增加線條與體積，創造細緻、真實的改善，同時維持您自然的特徵與比例。結果是自信、精緻的外觀，沒有不自然的變形。\n\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-06-18/e41b8942-22e1-4846-8f81-f41171b74558.jpg)\n\n不同於常產生誇張或不真實效果的傳統濾鏡，此工具提供乾淨、真實的編輯，依據您獨有的身體結構量身打造。無論您是在為社群媒體、個人用途或創意專案準備影像，這些增強都保持栩栩如生，同時突顯您最佳的特質。\n\n要開始探索虛擬身材精修，只需建立 AI 豐胸模擬任務，並逐步調整強度以達成您想要的外觀。接著調整增強強度等參數，以符合您的審美偏好，全部都在一個易用的 API 中完成，適合初學者與經驗豐富的使用者。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-06-18/733cedfd-2e8e-4cfc-8758-6854d923664b.jpg)\n\n---\n\n## 整合指南\n本指南將引導您完成：\n\nAI 豐胸模擬 API 的工作流程：\n\n**端點：** `/s2s/v2.0/task/breast-shape`\n\n**需要認證：** `Authorization: Bearer YOUR_API_KEY`\n\n**工作流程步驟：**\n\n1. **圖片上傳準備：**\n   - 流程從準備胸部自拍開始。\n\n2. **AI 豐胸模擬設定**\n    對於 AI 豐胸模擬，透過調整強度等級來控制增強程度，範圍從 1（細微）到 3（明顯）。從較低的設定開始，逐步提高，以達成符合您審美偏好的自然結果。逐步調整有助於確保真實且比例協調的結果。\n\n3. **啟動 AI 任務並取得任務 ID：**\n   - 透過 HTTP POST 請求，將上傳的圖片與參數設定傳送到 `/s2s/v2.0/file`。\n   - 在回應中取得唯一的任務 ID，用以識別這次互動。\n\n4. **輪詢任務狀態（持續檢查）：**\n   - 使用取得的 `task_id`，透過 HTTP GET 請求（例如 `GET /task/${task_id}`）定期輪詢任務狀態。\n   - 持續監控：\n     - `Task_status = \"success\"`（流程完成）。\n     - `Task_status = \"error\"`（視情況解決或重試）。\n   - 狀態轉為成功後，相應更新工作流程。\n\n這個結構化的工作流程確保與使用者輸入的高效整合、任務的自動化監控，以及無縫取得結果。\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n    ```\n    Authorization: Bearer YOUR_API_KEY\n    ```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n---\n\n* 上傳圖片\n\n您可以直接上傳檔案到伺服器，或在 AI 任務內容中提供有效的圖片網址。\n\n   * 上傳端點\n\n```\nPOST /s2s/v2.0/file\n```\n\n或者，若您已有公開的圖片網址，可跳過此步驟。\n\n---\n\n* 調整 AI 豐胸模擬強度\n**AI 豐胸模擬設定**\n\n對於 AI 豐胸模擬，透過將強度等級設在 **1 到 3** 之間來控制修改程度：\n- **等級 1** 提供細微、自然的外觀調整，最適合輕微精修。\n- **等級 2** 提供適度增強，在真實感與明顯改善之間取得平衡。\n- **等級 3** 帶來最明顯的效果，適合顯著重塑，同時維持解剖學的合理性。\n\n選擇最符合您審美目標與理想外觀的強度等級。\n\n---\n\n* 建立 AI 豐胸模擬任務並輪詢結果\n\n上傳圖片並選擇您偏好的強度等級後，即可開始增強任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 `success` 或 `error`。\n\n   * 建立任務端點\n\n```\nPOST /s2s/v2.0/task/breast-shape\n```\n\n   * 輪詢端點\n\n```\nGET /s2s/v2.0/task/breast-shape/{task_id}\n```\n\n---\n\n## 檔案規格與錯誤\n\n* AI 豐胸模擬規範\n**圖片需求與最佳結果建議**\n\n- **解析度指引**：\n  輸入圖片的最長邊不得超過 4096 像素。為獲得最佳效能，請確保上半身區域——定義為從頭頂到包含胸部在內的區域——以至少 1024 × 768 像素的解析度呈現。\n\n- **主體需求**：\n  - 圖片必須包含至少一位可完整偵測的人物。兩側肩膀都應在畫面中清晰可見。\n  - 胸部區域必須可見。這包括穿著與未穿著的情況，只要主體主要面向前方（即 yaw 角度介於 −90° 與 +90° 之間）。強烈建議使用正面視角，而非斜向或側面姿勢。\n\n- **提升效果的建議做法**：\n  - 優先採用上半身構圖：圖片應專注於上半身，或若包含完整身形，上半身區域應佔畫面相當大的比例，其最長維度超過 1024 像素。\n  - 僅使用正面姿勢；避免側面或大幅旋轉的位置，因為這些會降低偵測準確度與結果品質。\n  - 為了讓胸部輪廓獲得最自然的增強，請選擇在胸部周圍露出部分皮膚的服裝——例如泳裝、低領上衣或 V 領服飾。這些風格讓 AI 更能推斷底層結構，並產生細緻、逼真的效果。\n  - 系統僅支援單人主體的圖片。若畫面中出現多人，處理程序會自動針對可見肩膀跨度最大的人（即最接近鏡頭或最居中對齊鏡頭的人）。\n  - 避免胸部區域的遮擋。包包、背包帶、圍巾、項鍊或其他配件可能被錯誤移除，或在編輯時產生偽影。\n  - 服裝外觀可能與原始圖片不同。修改程度取決於強度設定：較高的增強等級會產生更明顯的變化，包括服裝形狀、合身度與胸部周圍垂墜感的可見改變。\n\n遵循這些指引可確保最佳的輸入品質，並最大化 AI 生成增強的真實度、寫實性與一致性。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_02-1_2dfe3418c2.jpg)\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_02-2_a88356deeb.jpg)\n\n---\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 豐胸模擬|最小：512x384 <BR>最大：長邊 < 4096|< 10MB|jpg/jpeg/png/heic |\n\n* 錯誤代碼\n\n| 錯誤代碼                      | 說明 |\n|----------------------------------|-------------|\n| `invalid_parameter`             | 提供的參數無效——具體來說，必要欄位（`src_keys`、`dst_keys` 或 `acts`）中有一個或多個缺失、格式錯誤，或包含不支援的值。 |\n| `exceed_max_filesize`           | 輸入圖片超過允許的最大檔案大小（10 MB）。請在提交前壓縮或調整圖片尺寸。 |\n| `error_download_image`          | 系統下載來源圖片失敗，可能因網路問題、網址無效，或資源權限無法存取。 |\n| `error_decode_image`            | 下載的圖片無法解碼——可能因檔案損毀、格式不支援，或二元資料無效。 |\n| `error_nsfw_content_detected`   | 在來源圖片或生成的輸出圖片中偵測到潛在的 NSFW（不適合工作場合）內容。基於合規與安全考量，處理已中止。 |\n| `error_pose`                    | 人體姿勢估計失敗；無法可靠偵測全身或上半身骨架，導致後續的解剖分析無法進行。 |\n| `error_breast_region_detection` | 系統嘗試依據姿勢與分割線索偵測胸部區域，但無法找到有效、可辨識的胸部區域（例如因遮擋、極端角度，或可見度不足）。 |\n\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 豐胸模擬 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_face_lift.yaml","link":"/zh-tw/reference/ai_face_lift","routeSlug":"/zh-tw/reference/ai_face_lift","label":"AI 臉部拉提","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_face_lift/section/概述","routeSlug":"/zh-tw/reference/ai_face_lift/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_face_lift/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_face_lift/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_face_lift/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_face_lift/section/概述/檔案規格與錯誤"},{"type":"link","label":"JS Camera Kit","link":"/zh-tw/reference/ai_face_lift/section/概述/js-camera-kit","routeSlug":"/zh-tw/reference/ai_face_lift/section/概述/js-camera-kit"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_face_lift/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_face_lift/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_face_lift/v1.0","routeSlug":"/zh-tw/reference/ai_face_lift/v1.0","items":[{"label":"執行 AI 臉部拉提的偵測任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift~1pre-process/post","routeSlug":"/zh-tw/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift~1pre-process/post","metadata":{"seo":{"title":"執行 AI 臉部拉提的偵測任務。","description":"當來源照片可能包含超過一個有效目標，或您的整合需要明確選擇哪個被偵測到的目標接受特效時，請使用前處理任務。對於單一目標的圖片，當功能支援預設的 index 值，且您的應用程式不需要手動選擇目標時，可以跳過前處理。"}},"httpPath":"/s2s/v2.0/task/face-lift/pre-process"},{"label":"查詢 AI 臉部拉提偵測任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift~1pre-process~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift~1pre-process~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 臉部拉提偵測任務的狀態。","description":"查詢 AI 臉部拉提偵測任務的狀態。"}},"httpPath":"/s2s/v2.0/task/face-lift/pre-process/{task_id}"},{"label":"執行 AI 臉部拉提任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift/post","routeSlug":"/zh-tw/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift/post","metadata":{"seo":{"title":"執行 AI 臉部拉提任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/face-lift"},{"label":"查詢 AI 臉部拉提任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 臉部拉提任務的狀態。","description":"查詢 AI 臉部拉提任務的狀態。"}},"httpPath":"/s2s/v2.0/task/face-lift/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 臉部拉提","version":"","description":"# 概述\nAI 臉部拉提是生成式 AI 的臉部增強功能，透過可調整的參數達成精準自然的臉部精修。系統不是套用濾鏡，而是智慧地分析臉部結構、膚質與比例，然後重建影像，產生保留個人特徵的寫實改善。\n\n使用者可用 0 到 100 的數值控制特定的臉部區域，例如眼袋、臉頰、額頭、整體臉型與嘴巴。每個參數逐步提升增強程度，依使用者偏好達成細微修飾或更精緻的結果。所有調整都設計為維持自然與平衡，避免誇張或不自然的結果。\n\nAI 臉部拉提提供彈性、功能層級的控制，創造清新、自信且專業的外觀，適合社群媒體、個人頭像、創意內容或商務用途。\n\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/01_1_6c0d97eb51.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/01_2_8c428a25dc.jpg)\n\n\n## 整合指南\n本指南將引導您完成：\n\nAI 臉部拉提 API 的工作流程：\n\n**端點：** `/s2s/v2.0/task/face-lift`\n\n**需要認證：** `Authorization: Bearer YOUR_API_KEY`\n\n**工作流程步驟：**\n\n1. **圖片上傳準備：**\n  - 準備要上傳的自拍圖片。\n  - 呼叫 File API `/s2s/v2.0/file` 取得上傳網址與相關的 `file_id`。\n  - 使用提供的上傳網址上傳自拍圖片。\n\n2. **多張臉部的選填前處理：**\n    - 若圖片中有多於一張臉部，請對自拍圖片進行前處理。\n\n3. **臉部拉提特效設定：**\n   - 先選擇合適的臉部拉提參數。\n\n4. **啟動 AI 任務並取得任務 ID：**\n   - 透過 HTTP POST 請求，將 `file_id` 與所選特效設定傳送到 `/s2s/v2.0/task/face-lift`。\n   - 在回應中取得唯一的任務 ID，用以識別這次互動。\n\n5. **輪詢任務狀態（持續檢查）：**\n   - 使用取得的 `task_id`，透過 HTTP GET 請求（例如 `GET /s2s/v2.0/task/face-lift${task_id}`）定期輪詢任務狀態。\n   - 持續監控：\n     - `Task_status = \"success\"`（流程完成）。\n     - `Task_status = \"error\"`（視情況解決或重試）。\n   - 狀態轉為成功後，相應更新工作流程。\n\n這個結構化的工作流程確保與使用者輸入的高效整合、任務的自動化監控，以及無縫取得結果。\n\n\n---\n\n1.  認證\n    - 使用 **Bearer Token** 在請求標頭中納入您的 API key：\n        ```\n        Authorization: Bearer YOUR_API_KEY\n        ```\n    您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n\n2.  上傳圖片\n\n    您可以直接上傳檔案到伺服器，或在 AI 任務內容中提供有效的圖片網址。\n\n    * 上傳端點\n\n        ```\n        POST /s2s/v2.0/file\n        ```\n\n    或者，若您已有公開的圖片網址，可跳過此步驟。\n\n---\n\n3. 透過前處理選擇要增強的目標臉部\n\n   * 呼叫前處理 API\n    輸出以像素座標表示的偵測邊界框。使用結果的索引，在稍後建立臉部拉提 AI 任務。\n        ```\n        POST /s2s/v2.0/task/face-lift/pre-process\n        ```\n\n        ```\n        {\n            \"timed\": number,\n            \"result\": [\n                {\n                    \"left\": number,\n                    \"top\": number,\n                    \"width\": number,\n                    \"height\": number\n                }\n            ]\n        }\n        ```\n\n4. 建立臉部拉提 AI 任務並輪詢結果\n\n    當您取得圖片與完整的特效內容後，即可建立任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 `success` 或 `error`。\n\n   * 建立任務端點\n\n        ```\n        POST /s2s/v2.0/task/face-lift\n        ```\n\n   * 輪詢端點\n\n        ```\n        GET /s2s/v2.0/task/face-lift/{task_id}\n        ```\n\n---\n\n## 檔案規格與錯誤\n\n* AI 臉部拉提規範\n\n**支援的自拍視角**\n圖片不得大於 1920 x 1920，在長邊為 640 時須包含清晰可見且足夠大的臉部（超過 32 x 32 像素），且拍攝的 roll 角度在正負 75 度內、yaw 角度在正負 90 度內，以確保可靠的臉部偵測。\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_face_reshape_01_85c8ffc055.jpg)\n\n\n---\n\n* 支援的格式與尺寸\n\n| AI 功能 | 支援的尺寸 | 支援的檔案大小 | 支援的格式|\n|  ----  | ----  | ----  | ----  |\n| AI 臉部拉提 | 長邊 <= 1920 | < 10MB | jpg/jpeg/png |\n\n* 錯誤代碼\n\n| 錯誤代碼 | 說明 |\n|  ----  | ----  |\n| RUNTIME_ERROR | 臉部拉提執行期間發生不如預期的錯誤 |\n| PHOTO_DETECTION_FAIL | 無法正確處理使用者照片，例如未偵測到手 |\n| OBJECT_DETECTION_FAIL | 無法正確處理物件照片，例如未偵測到產品 |\n| PHOTO_CHECK_INVALID | 使用者照片的姿勢或尺寸無效 |\n| INPUT_ERROR | 輸入檔案格式不正確 |\n| INPUT_MAIN_IMAGE_EMPTY | 需要使用者圖片 |\n\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 臉部拉提 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_smile.yaml","link":"/zh-tw/reference/ai_smile","routeSlug":"/zh-tw/reference/ai_smile","label":"AI 微笑","items":[{"type":"group","label":"總覽","link":"/zh-tw/reference/ai_smile/section/總覽","routeSlug":"/zh-tw/reference/ai_smile/section/總覽","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_smile/section/總覽/整合指南","routeSlug":"/zh-tw/reference/ai_smile/section/總覽/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_smile/section/總覽/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_smile/section/總覽/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_smile/section/總覽/點數消耗","routeSlug":"/zh-tw/reference/ai_smile/section/總覽/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_smile/v1.0","routeSlug":"/zh-tw/reference/ai_smile/v1.0","items":[{"label":"執行 AI 微笑任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_smile/v1.0/paths/~1s2s~1v2.0~1task~1ai-smile/post","routeSlug":"/zh-tw/reference/ai_smile/v1.0/paths/~1s2s~1v2.0~1task~1ai-smile/post","metadata":{"seo":{"title":"執行 AI 微笑任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/ai-smile"},{"label":"查詢 AI 微笑任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_smile/v1.0/paths/~1s2s~1v2.0~1task~1ai-smile~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_smile/v1.0/paths/~1s2s~1v2.0~1task~1ai-smile~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 微笑任務的狀態。","description":"查詢 AI 微笑任務的狀態。"}},"httpPath":"/s2s/v2.0/task/ai-smile/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 微笑","version":"","description":"# 總覽\n介紹生成式 AI 微笑 API，輕鬆把愁容翻轉成笑容。這方便的 AI 微笑生成器在瞬間將悲傷或中性的臉部表情轉化為快樂、自然的外觀微笑。由先進的生成式 AI 驅動，它以簡單輕鬆的流程，為任何照片帶來溫暖與正面感。上傳圖片，讓 AI 施展魔法，即刻將您的愁容轉化為歡樂的笑臉，在所分享之處傳遞幸福。\n\nAI 微笑生成器支援兩種不同的微笑風格，讓使用者對最終表情有更多控制。\n\n1.  **smile_with_teeth_visible**  \n    此選項創造明亮、愉悅的微笑，自然可見牙齒。最適合開朗的人像照、社群媒體照片，以及需要溫暖且富表現力外觀的場合。\n\n2.  **closed_mouth_smile**  \n    此選項產生閉唇的細微、溫柔微笑。非常適合專業照片、正式個人檔案，或偏好沉穩自然表情時。\n\n使用者可輕鬆選擇最符合其照片、心情或預期用途的微笑類型，每次都能確保寫實且吸引人的結果。\n\n無論您是在編輯照片、創作有趣的內容，或只是想增添一點正面感，生成式 AI 微笑都能輕鬆傳遞幸福，一次一個微笑。\n\n上傳一張臉。點擊一次。即刻微笑。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2024-03-22/5f25b0f7-5d43-421b-ae50-5def0de69f2a.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2024-12-16/4f4397e0-9e87-429a-8e39-a9d399b6602b.jpg)\n\n## 整合指南\n本指南將引導您完成：\n\nAI 微笑 API 的工作流程：\n\n**端點：** `/s2s/v2.0/task/ai-smile`\n\n**需要認證：** `Authorization: Bearer YOUR_API_KEY`\n\n**工作流程步驟：**\n\n1. **圖片上傳準備：**\n    - 準備要上傳的自拍圖片。\n    - 呼叫 File API `/s2s/v2.0/file` 取得上傳網址與相關的 `file_id`。\n    - 使用提供的上傳網址上傳自拍圖片。\n\n2. **啟動 AI 任務並取得任務 ID：**\n    - 透過 HTTP POST 請求，將 `file_id` 與所選特效設定傳送到 `/s2s/v2.0/task/ai-smile`。\n    - 在回應中取得唯一的任務 ID，用以識別這次互動。\n\n3. **輪詢任務狀態（持續檢查）：**\n    - 使用取得的 `task_id`，透過 HTTP GET 請求（例如 `GET /s2s/v2.0/task/ai-smile/${task_id}`）定期輪詢任務狀態。\n    - 持續監控：\n        - `Task_status = \"success\"`（流程完成）。\n        - `Task_status = \"error\"`（視情況解決或重試）。\n    - 狀態轉為成功後，相應更新工作流程。\n\n這個結構化的工作流程確保與使用者輸入的高效整合、任務的自動化監控，以及無縫取得結果。\n\n\n---\n\n1. 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n    ```\n    Authorization: Bearer YOUR_API_KEY\n    ```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n\n2. 上傳圖片\n\n    您可以直接上傳檔案到伺服器，或在 AI 任務內容中提供有效的圖片網址。\n\n   * 上傳端點\n\n        ```\n        POST /s2s/v2.0/file\n        ```\n\n    或者，若您已有公開的圖片網址，可跳過此步驟。\n\n---\n\n3. 建立 AI 微笑任務並輪詢結果\n\n    當您取得圖片與完整的特效設定後，即可建立任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 `success` 或 `error`。\n\n    * 建立任務端點\n\n        ```\n        POST /s2s/v2.0/task/ai-smile\n        ```\n\n    * 輪詢端點\n\n        ```\n        GET /s2s/v2.0/task/ai-smile/{task_id}\n        ```\n\n---\n\n## 檔案規格與錯誤\n\n* AI 微笑規範\n\n**支援的自拍視角**\n僅支援單人圖片，在長邊為 640 時圖片須包含清晰可見且足夠大的臉部（超過 32 x 32 像素），且拍攝的 roll 角度在正負 75 度內、yaw 角度在正負 90 度內，以避免臉部偵測失敗。\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_face_reshape_01_85c8ffc055.jpg)\n\n\n---\n\n* 支援的格式與尺寸\n\n| AI 功能 | 支援的尺寸 | 支援的檔案大小 | 支援的格式|\n|  ----  | ----  | ----  | ----  |\n| AI 微笑 | 長邊 <= 4096 | < 10MB | jpg/jpeg/png/heic |\n\n\n* 錯誤代碼\n\n| 錯誤代碼 | 說明 |\n| ---------- | ----------- |\n| EXCEED_MAX_FILESIZE  | 輸入檔案超過允許的最大尺寸。 |\n| INVALID_PARAMETER     | 有一個或多個必要參數缺失、為空，或格式不當。  |\n| ERROR_DOWNLOAD_IMAGE | 無法下載來源圖片。 |\n| ERROR_NO_FACE        | 在提供的圖片中未偵測到臉部。 |\n| ERROR_INFERENCE       | 推論過程失敗，原因可能是流程問題、執行錯誤、編碼錯誤，或缺少輸出圖片。 |\n| UNKNOWN_INTERNAL_ERROR | 發生不如預期的內部錯誤。 |\n\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 微笑 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_fitzpatrick_skin_type.yaml","link":"/zh-tw/reference/ai_fitzpatrick_skin_type","routeSlug":"/zh-tw/reference/ai_fitzpatrick_skin_type","label":"AI Fitzpatrick 膚色類型分析","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_fitzpatrick_skin_type/section/概述","routeSlug":"/zh-tw/reference/ai_fitzpatrick_skin_type/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_fitzpatrick_skin_type/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_fitzpatrick_skin_type/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_fitzpatrick_skin_type/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_fitzpatrick_skin_type/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_fitzpatrick_skin_type/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_fitzpatrick_skin_type/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_fitzpatrick_skin_type/v1.0","routeSlug":"/zh-tw/reference/ai_fitzpatrick_skin_type/v1.0","items":[{"label":"執行 AI Fitzpatrick 膚色量表分析儀的偵測任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_fitzpatrick_skin_type/v1.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer~1pre-process/post","routeSlug":"/zh-tw/reference/ai_fitzpatrick_skin_type/v1.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer~1pre-process/post","metadata":{"seo":{"title":"執行 AI Fitzpatrick 膚色量表分析儀的偵測任務。","description":"當來源照片可能包含超過一個有效目標，或您的整合需要明確選擇哪個被偵測到的目標接受特效時，請使用前處理任務。對於單一目標的圖片，當功能支援預設的 index 值，且您的應用程式不需要手動選擇目標時，可以跳過前處理。"}},"httpPath":"/s2s/v2.0/task/fitzpatrick-scale-analyzer/pre-process"},{"label":"查詢 AI Fitzpatrick 膚色量表分析儀偵測任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_fitzpatrick_skin_type/v1.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer~1pre-process~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_fitzpatrick_skin_type/v1.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer~1pre-process~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI Fitzpatrick 膚色量表分析儀偵測任務的狀態。","description":"查詢 AI Fitzpatrick 膚色量表分析儀偵測任務的狀態。"}},"httpPath":"/s2s/v2.0/task/fitzpatrick-scale-analyzer/pre-process/{task_id}"},{"label":"執行 AI Fitzpatrick 膚色量表分析儀任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_fitzpatrick_skin_type/v1.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer/post","routeSlug":"/zh-tw/reference/ai_fitzpatrick_skin_type/v1.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer/post","metadata":{"seo":{"title":"執行 AI Fitzpatrick 膚色量表分析儀任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/fitzpatrick-scale-analyzer"},{"label":"查詢 AI Fitzpatrick 膚色量表分析儀任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_fitzpatrick_skin_type/v1.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_fitzpatrick_skin_type/v1.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI Fitzpatrick 膚色量表分析儀任務的狀態。","description":"查詢 AI Fitzpatrick 膚色量表分析儀任務的狀態。"}},"httpPath":"/s2s/v2.0/task/fitzpatrick-scale-analyzer/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Fitzpatrick 膚色類型分析","version":"","description":"# 概述\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2026-01-28/webp_a00e88ca-e20a-4082-89c2-9d486b03b8e8.webp)\n\n**AI Fitzpatrick 膚色類型分析**\n\n將 AI 驅動的 Fitzpatrick 膚色類型偵測整合到您的應用，透過攝影輸入準確分類膚質。這個 API 讓開發者為電子商務與數位健康平台建立個人化的護膚、防曬與產品推薦工作流程。\n\n**膚色類型偵測**\n\nAPI 使用電腦視覺與機器學習模型分析皮膚特徵，並在單次請求中回傳 Fitzpatrick 分類。它提供結構化、客觀的資料，可由前端應用、推薦引擎或臨床系統直接消費。\n\n由 Thomas B. Fitzpatrick 醫師提出的 Fitzpatrick 分級，依據黑色素程度與對紫外線曝露的反應定義六種膚色類型，讓系統能預測曬傷或曬黑的傾向。\n\n**分類輸出**\n\nAPI 依據紫外線反應模型，回傳從 Type I 到 Type VI 六種標準化膚色類型之一。\n\n此輸出讓開發者提供客製化的產品推薦、自動化護膚工作流程，並強化跨使用者體驗的個人化邏輯，同時維持一致性與可擴展性。\n\n| Fitzpatrick 分級 | 膚色類型 | 皮膚對太陽的反應 |\n|  ----  | ----  | ---- |\n| Type I | 白色 | 幾乎總是曬傷，從不曬黑 |\n| Type II |  米色 | 通常曬傷，輕微曬黑 |\n| Type III | 淺棕色 | 偶爾曬傷，逐漸曬黑 |\n| Type V | 中棕色 | 罕見曬傷，容易曬黑 |\n| Type V | 深棕色 | 極罕見曬傷 |\n| Type VI | 極深棕色 | 幾乎從不曬傷 |\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/fitapatrick_skin_type_S_02_enu_5e4343e801.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2026-03-10/webp_b9ca4198-1a9e-44df-9551-ac3ad8b65d17.webp)\n\n---\n\n## 整合指南\n\n**1. 拍攝圖片**\n在充足光線下拍攝正面圖片。確保臉部清晰可見，並佔畫面足夠的比例。\n\n\n**2. 上傳圖片**\n透過以下方式請求上傳網址與檔案 ID：\n\n```\nPOST /s2s/v2.0/file\n```\n\n使用回傳的網址上傳圖片。\n或者，提供託管在您自有儲存空間、可公開存取的圖片網址。\n\n\n**3. 選填前處理**\n\n```\nPOST /s2s/v2.0/task/fitzpatrick-scale-analyzer/pre-process\n```\n\n當圖片包含多張臉部，或需要明確選擇目標時使用此步驟。對於單張臉部的圖片，若預設索引已足夠，可跳過此步驟。\n\n\n**4. 取得前處理結果**\n\n```\nGET /s2s/v2.0/task/fitzpatrick-scale-analyzer/pre-ocess\n```\n\n設定 [webhook](/develop/webhook.md) 或實作輪詢以取得任務結果。使用 webhook 時，您的應用會在任務完成時自動收到通知。使用輪詢時，您的系統會重複呼叫任務端點，直到狀態從 running 變為 success 或 error。\n\n**5. 執行分析任務**\n\n```\nPOST /s2s/v2.0/task/fitzpatrick-scale-analyzer\n```\n\n使用檔案 ID 或圖片網址作為輸入提交任務。回應會回傳 task_id 用於追蹤與取得結果。\n\n\n**6. 取得任務結果**\n\n```\nGET /s2s/v2.0/task/fitzpatrick-scale-analyzer/{task_id}\n```\n\n使用務  追蹤狀態並取得結果。\n\n可設定 [Webhooks](/develop/webhook.md) 在任務完成時接收非同步通知，狀態為 success 或 error。也支援輪詢，重複呼叫任務端點直到狀態從 running 更新為 success 或 error。\n\n僅在任務成功完成時才計費。\n\n---\n\n## 檔案規格與錯誤\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n| AI Fitzpatrick 膚色類型分析 | 較長邊不得超過 4096 像素，較短邊不得少於 320 像素。 | < 10MB | jpg/jpeg |\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| error_below_min_image_size | 來源圖片尺寸必須至少為 320 像素。 |\n|error_face_position_invalid|您的臉部必須在圖片中完全可見，不可有任何部分被裁切|\n|error_face_position_too_small|您照片中的臉部太小，無法妥善分析|\n|error_face_position_out_of_boundary|您的臉部過大，或部分超出照片邊緣|\n|error_insufficient_lighting|光線過暗，導致難以分析|\n|error_face_angle_invalid|您的臉部角度不太正確。正面拍攝時，請讓頭部偏離直線不超過 10 度。側面拍攝時，角度應超過 15 度|\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI Fitzpatrick 膚色類型分析 V1.0 | 10 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_abs_filter.yaml","link":"/zh-tw/reference/ai_abs_filter","routeSlug":"/zh-tw/reference/ai_abs_filter","label":"AI 腹肌濾鏡","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_abs_filter/section/概述","routeSlug":"/zh-tw/reference/ai_abs_filter/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_abs_filter/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_abs_filter/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_abs_filter/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_abs_filter/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_abs_filter/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_abs_filter/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_abs_filter/v1.0","routeSlug":"/zh-tw/reference/ai_abs_filter/v1.0","items":[{"label":"執行 AI 腹肌濾鏡任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_abs_filter/v1.0/paths/~1s2s~1v2.0~1task~1abs-shape/post","routeSlug":"/zh-tw/reference/ai_abs_filter/v1.0/paths/~1s2s~1v2.0~1task~1abs-shape/post","metadata":{"seo":{"title":"執行 AI 腹肌濾鏡任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/abs-shape"},{"label":"查詢 AI 腹肌濾鏡任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_abs_filter/v1.0/paths/~1s2s~1v2.0~1task~1abs-shape~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_abs_filter/v1.0/paths/~1s2s~1v2.0~1task~1abs-shape~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 腹肌濾鏡任務的狀態。","description":"查詢 AI 腹肌濾鏡任務的狀態。"}},"httpPath":"/s2s/v2.0/task/abs-shape/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 腹肌濾鏡","version":"","description":"# 概述\n\n**AI 腹肌濾鏡 API** 可讓您為照片加入逼真的腹部線條，以最少的力氣生成運動感的塑形結果。上傳全身或上半身圖片，選擇想要的增強模式，設定強度等級，即可獲得編輯後的輸出圖片。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2024-09-27/daf70f5e-a350-46a3-8b6c-f63bd60c6cf0.jpg)\n\n支援的模式：\n\n- `Six-pack`：加入可見的六塊肌，呈現更結實的軀幹外觀。\n- `Vest-line`：強化腹部中央肌肉線條，呈現健體、運動的外觀。\n\n---\n\n## 整合指南\n\n**輸入需求與處理標準：**\n\n- 上傳全身或上半身圖片。\n- 選擇增強模式：`Six-pack` 或 `Vest-line`。\n- 選擇想要的腹部增強強度等級。\n- 長邊影像解析度上限不得超過 **4096 px**。\n- 來源檔案大小必須低於 **10 MB**。\n- 至少需要一位可偵測的人物，且兩側肩膀都可見。\n- 腹部必須可見，穿著或未穿著皆可。\n- 支援的姿勢範圍：`−45° < yaw < 45°`。\n- 支援單人處理。若圖片中出現多人，API 會自動選擇可見肩膀面積最大的人。\n\n**工作流程：**\n\n1. 使用 File API 上傳檔案 metadata。\n2. 從回應中取得簽名的上傳網址。\n3. 將實際圖片上傳到回傳的網址。\n4. 建立腹部塑形增強的 AI 任務。\n5. 設定 Webhook 或輪詢任務狀態直到完成。\n6. 處理成功後下載生成的結果圖片。\n\n---\n\n**步驟 1 — 使用 File API 上傳檔案 metadata**\n\n使用 `POST /s2s/v2.0/file` 建立檔案記錄，並取得來源圖片的上傳細節。\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/file \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"files\": [\n      {\n        \"content_type\": \"image/jpg\",\n        \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\n        \"file_size\": 547541\n      }\n    ]\n  }'\n```\n\n**File API 回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"files\": [\n      {\n        \"content_type\": \"image/jpg\",\n        \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\n        \"file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n        \"requests\": [\n          {\n            \"method\": \"PUT\",\n            \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\",\n            \"headers\": {\n              \"Content-Length\": \"547541\",\n              \"Content-Type\": \"image/jpg\"\n            }\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n---\n\n**步驟 2 — 取得 File API 回應細節**\n\n回應包含：\n\n| 欄位 | 說明 |\n| --- | --- |\n| `file_id` | 用於建立 AI 任務的識別碼。 |\n| `requests.url` | 用於上傳實際圖片檔案的簽名網址。 |\n| `requests.method` | 上傳方法，通常為 `PUT`。 |\n| `requests.headers` | 上傳請求所需的標頭。 |\n\n---\n\n**步驟 3 — 上傳圖片到提供的網址**\n\n使用 File API 回應中的 `requests.url` 上傳來源圖片。\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n  --header 'Content-Type: image/jpg' \\\n  --header 'Content-Length: 547541' \\\n  --data-binary @'./full_body_photo_01_3dbd1b6683.jpg'\n```\n\n---\n\n**步驟 4 — 建立 AI 任務**\n\n使用 `POST /s2s/v2.0/task/abs-shape` 建立腹部增強任務。\n\n| 參數 | 說明 | 範例 |\n| --- | --- | --- |\n| `src_file_id` | 從 File API 上傳流程回傳的檔案 ID。使用上傳檔案工作流程時為必要。 | `\"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\"` |\n| `src_file_url` | 來源圖片的直接網址。作為 `src_file_id` 的替代方案。 | `\"https://example.com/selfie.jpg\"` |\n| `mode` | 增強模式。支援的值為 `Six-pack` 與 `Vest-line`。 | `\"Six-pack\"` |\n| `intensity` | 腹部增強強度等級。 | `1` |\n\n**請求範例：**\n\n```javascript\nconst resp = await fetch(\n  'https://yce-api-01.makeupar.com/s2s/v2.0/task/abs-shape',\n  {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/json',\n      Authorization: 'Bearer <YOUR_TOKEN_HERE>'\n    },\n    body: JSON.stringify({\n      src_file_url: 'https://example.com/selfie.jpg',\n      mode: 'Six-pack',\n      intensity: 1\n    })\n  }\n);\n\nconst data = await resp.json();\nconsole.log(data);\n```\n\n**AI 任務 API 回應：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT\"\n  }\n}\n```\n\n---\n\n**步驟 5 — 設定 W/ook 或輪詢任務結果**\n\n設定與驗證細節請參考 [webhook 整合指南](/develop/webhook.md)。\n\n輪詢時，使用回傳的 `task_id` 查詢任務狀態。\n\n```bash\ncurl --request GET \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/abs-shape/<YOUR_TASK_ID> \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json'\n```\n\n---\n\n**步驟 6 — 取得結果圖片**\n\n處理成功時，回應會在 `data.results.url` 中包含下載網址。\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"error\": null,\n    \"results\": {\n      \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n    },\n    \"task_status\": \"success\"\n  }\n}\n```\n\n**API Key 無效的回應：**\n\n若 access token 無效，API 會回傳 `401` 回應。\n\n```json\n{\n  \"status\": 401,\n  \"error\": \"Unauthorized\",\n  \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n應用案例：\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-08-21/307f87b4-d31c-481c-86f1-478c93265a95.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-08-21/8ab8eca4-b825-4692-aef0-6ffd6176e272.jpg)\n\n---\n\n## 檔案規格與錯誤\n\n**檔案規格：**\n\n| 規格 | 需求 |\n| --- | --- |\n| 圖片類型 | 全身或上半身圖片。 |\n| 來源主體 | 一位可偵測的人物，兩側肩膀與腹部都可見。 |\n| 姿勢需求 | 支援的姿勢範圍為 `−45° < yaw < 45°`。 |\n| 多人處理 | 若偵測到多人，API 會自動選擇可見肩膀面積最大的人。 |\n| 長邊解析度上限 | 長邊不得超過 **4096 px**。 |\n| 檔案大小限制 | 必須低於 **10 MB**。 |\n| 支援的格式 | `jpg`、`png`。 |\n\n**錯誤代碼：**\n\n| 錯誤代碼 | 說明 |\n| --- | --- |\n| `exceed_max_filesize` | 來源圖片超過允許的最大尺寸或檔案大小。長邊不得超過 4096 px，檔案大小必須低於 10 MB。 |\n| `error_pose` | 姿勢偵測失敗，原因可能是未偵測到人物、肩膀可見度問題、腹部可見度問題、腰部區域偵測失敗、臀部關鍵點偵測失敗，或不受支援的姿勢範圍。 |\n| `error_nsfw_content_detected` | 在來源圖片或生成的結果圖片中偵測到潛在的 NSFW 內容。 |\n| `invalid_parameter` | 來源鍵、目標鍵、動作、模式值、強度等級或任務設定提供了無效的參數。 |\n| `error_download_image` | 無法成功下載來源圖片。 |\n| `error_decode_image` | 無法成功解碼來源圖片。 |\n\n**環境與相依性：**\n\n| 工具 / 語言 | 建議的執行環境版本 |\n| --- | --- |\n| cURL | Bash ≥ 3.2；curl ≥ 7.58（具現代 TLS/HTTP 支援）；jq ≥ 1.6（穩健的 JSON 解析）。 |\n| Node.js | Node ≥ 18（支援全域 `fetch`）。 |\n| JavaScript 瀏覽器支援 | Chrome / Edge ≥ 80、Firefox ≥ 74、Safari ≥ 13.1。 |\n| PHP | PHP ≥ 7.4（具現代 TLS 相容性）；建議 ext-curl，或 `allow_url_fopen=On` 並具備 OpenSSL 與 JSON 支援。 |\n| Python | Python ≥ 3.10（支援 f-strings）；requests ≥ 2.20.0。 |\n| Java | Java 11+（支援 HttpClient）；Jackson Databind ≥ 2.12.0。 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 腹肌濾鏡 V1.0 | 1 |\n\n---\n"}},{"type":"separator","label":"彩妝造型","labelTranslationKey":"sidebar.reference.separators.beauty"},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_makeup_transfer.yaml","link":"/zh-tw/reference/ai_makeup_transfer","routeSlug":"/zh-tw/reference/ai_makeup_transfer","label":"AI 仿妝","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_makeup_transfer/section/概述","routeSlug":"/zh-tw/reference/ai_makeup_transfer/section/概述","items":[{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_makeup_transfer/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_makeup_transfer/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_makeup_transfer/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_makeup_transfer/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_makeup_transfer/v1.0","routeSlug":"/zh-tw/reference/ai_makeup_transfer/v1.0","items":[{"label":"執行 AI 仿妝任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_makeup_transfer/v1.0/paths/~1s2s~1v2.0~1task~1mu-transfer/post","routeSlug":"/zh-tw/reference/ai_makeup_transfer/v1.0/paths/~1s2s~1v2.0~1task~1mu-transfer/post","metadata":{"seo":{"title":"執行 AI 仿妝任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/mu-transfer"},{"label":"查詢 AI 仿妝任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_makeup_transfer/v1.0/paths/~1s2s~1v2.0~1task~1mu-transfer~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_makeup_transfer/v1.0/paths/~1s2s~1v2.0~1task~1mu-transfer~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 仿妝任務的狀態。","description":"查詢 AI 仿妝任務的狀態。"}},"httpPath":"/s2s/v2.0/task/mu-transfer/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 仿妝","version":"","description":"# 概述\n只需上傳您喜愛的造型照片！AI 仿妝讓嘗試不同造型變得輕鬆有趣，您可以上傳想要的照片逐一試試。現在有想嘗試的彩妝造型嗎？讓 AI 仿妝帶給您驚喜！\n\n首先，上傳一張您本人的照片作為目標圖片，臉部與其特徵需清晰可見。\n\n接著，上傳您最喜愛的彩妝造型照片作為參考圖片。 \n\n完成了——一張 AI 仿妝的照片。 \n\n範例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/YCE_web_Makeup_Transfer_s1_img_be53c5c345.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2024-06-24/fda62e5d-ba58-4ecf-838a-c7d5f804c77b.jpg)\n\n---\n\n## 檔案規格與錯誤\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 仿妝|1024x1024（長邊 <= 1024），僅限單張臉部，需呈現完整臉部|< 10MB|jpg/jpeg/png|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n|error_src_no_face\t|在使用者圖片中未偵測到臉部\n|error_ref_no_face\t|在參考圖片中未偵測到臉部\n|error_src_face_too_small\t|使用者圖片中的臉部太小\n|error_ref_face_too_small\t|參考圖片中的臉部太小\n|error_src_large_face_angle\t|使用者圖片需要正面臉部\n|error_ref_large_face_angle\t|參考圖片需要正面臉部\n|error_src_eye_closed\t|使用者圖片中眼睛閉著\n|error_ref_eye_closed\t|參考圖片中眼睛閉著\n|error_src_eye_occluded\t|使用者圖片中眼睛被遮擋\n|error_ref_eye_occluded\t|參考圖片中眼睛被遮擋\n|error_src_lip_occluded\t|使用者圖片中嘴唇被遮擋\n|error_ref_lip_occluded\t|參考圖片中嘴唇被遮擋\n|error_inappropriate_ref_case01\t|在參考圖片中，雙眼周圍頭髮離眼睛太近，或眼尾旁的皮膚區域不夠大\n|error_inappropriate_ref_case02\t|在參考圖片中，單眼周圍頭髮離眼睛太近，或眼尾旁的皮膚區域不夠大。另一眼在參考圖片中不夠正面\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 仿妝 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/makeup_vto.yaml","link":"/zh-tw/reference/makeup_vto","routeSlug":"/zh-tw/reference/makeup_vto","label":"AI 虛擬試妝","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/makeup_vto/section/概述","routeSlug":"/zh-tw/reference/makeup_vto/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/makeup_vto/section/概述/整合指南","routeSlug":"/zh-tw/reference/makeup_vto/section/概述/整合指南"},{"type":"link","label":"輸入與輸出","link":"/zh-tw/reference/makeup_vto/section/概述/輸入與輸出","routeSlug":"/zh-tw/reference/makeup_vto/section/概述/輸入與輸出"},{"type":"link","label":"內容範例","link":"/zh-tw/reference/makeup_vto/section/概述/內容範例","routeSlug":"/zh-tw/reference/makeup_vto/section/概述/內容範例"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/makeup_vto/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/makeup_vto/section/概述/檔案規格與錯誤"},{"type":"link","label":"JS Camera Kit","link":"/zh-tw/reference/makeup_vto/section/概述/js-camera-kit","routeSlug":"/zh-tw/reference/makeup_vto/section/概述/js-camera-kit"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/makeup_vto/section/概述/點數消耗","routeSlug":"/zh-tw/reference/makeup_vto/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/makeup_vto/v1.0","routeSlug":"/zh-tw/reference/makeup_vto/v1.0","items":[{"label":"執行 AI 虛擬試妝任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/makeup_vto/v1.0/paths/~1s2s~1v2.0~1task~1makeup-vto/post","routeSlug":"/zh-tw/reference/makeup_vto/v1.0/paths/~1s2s~1v2.0~1task~1makeup-vto/post","metadata":{"seo":{"title":"執行 AI 虛擬試妝任務。","description":"這個端點啟動彩妝虛擬試妝流程。您必須提供來源檔案（透過網址或檔案 ID），並使用定義的特效 schema 指定要套用的特效。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/makeup-vto"},{"label":"查詢 AI 虛擬試妝任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/makeup_vto/v1.0/paths/~1s2s~1v2.0~1task~1makeup-vto~1{task_id}/get","routeSlug":"/zh-tw/reference/makeup_vto/v1.0/paths/~1s2s~1v2.0~1task~1makeup-vto~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 虛擬試妝任務的狀態。","description":"查詢 AI 虛擬試妝任務的狀態。"}},"httpPath":"/s2s/v2.0/task/makeup-vto/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 虛擬試妝","version":"","description":"# 概述\nAI 虛擬試妝 API 以我們專利的臉部分析技術為基礎，提供強大且極其逼真的虛擬改造型體驗。此服務讓您的應用程式能以前所未有的自訂能力，在使用者提供的自拍圖片上套用栩栩如生的彩妝特效。\n\n**主要功能：**\n*   **極其逼真的渲染：** 運用革命性的 3D 人臉 AI 技術，達成最真實的改造型效果。\n*   **專利技術：** 由無抖動、無延遲的深度學習演算法驅動，針對所有年齡與族裔最佳化。\n*   **即時精準：** 超精準的臉部追蹤，可適應各種光線條件。\n*   **栩栩如生的對應：** 精確對應現實產品的顏色、質地（從 matte 到 metallic）與妝效。\n\n* 核心概念\n\n   * 色彩混合\n我們的 AI 使用深度學習，精確對應現實彩妝產品的顏色。這確保消費者能確信他們看到的虛擬顏色，就是他們打算購買產品的真實顏色。\n\n   * 質地與妝效對應\n此技術模擬逼真的質地與妝效，提供高度準確的改造型體驗。從 matte 到 metallic、shimmer 到 satin，AI 運用先進演算法即時無縫渲染這些特效。\n\n   * 光線平衡\n智慧 3D AI 引擎會偵測使用者照片或影片串流中的光線條件。它會校正圖片以達到栩栩如生的彩妝套用，無論環境如何，都確保一致且高品質的結果。\n\n---\n\n## 整合指南\n\n彩妝虛擬試戴服務以非同步任務運作。您必須先提供圖片網址與期望特效清單，啟動彩妝處理任務。伺服器會回傳 `task_id`。接著您定期輪詢狀態端點，以取得最終結果或任何錯誤。\n\n*   **端點：** `/v2.0/task/makeup-vto`\n*   **認證：** 所有請求都需要 `Authorization: Bearer <TOKEN>`\n*   **工作流程：**\n    1.  **準備自拍：** 上傳圖片，或使用既有臉部圖片的檔案網址。\n    1.  **啟動任務（`POST`）：** 提交您的圖片 id/網址與彩妝設定。\n    1.  **取得任務 ID：** 從回應中取得 `task_id`。\n    1.  **輪詢狀態（`GET`）：** 使用 `task_id` 查詢任務狀態。持續輪詢，直到 `task_status` 為 `\"success\"` 或 `\"error\"`。\n\n\n* API Playground\n\n使用我們的官方 playground 進行互動式探索與測試：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-makeup-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-makeup-virtual-try-on/)\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n    ```\n    Authorization: Bearer <API Key>\n    ```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n* 1. 上傳自拍\n  您可以透過兩種方式之一提供來源圖片：\n\n  - **使用現有的公開圖片網址**\n    無需上傳，您可以在啟動 AI 任務時直接提供可公開存取的圖片網址。\n\n  - **透過 File API 上傳**\n    使用端點：\n    ```\n    POST /s2s/v2.0/file\n    ```\n    這會回傳用於後續任務執行的 `file_id`。\n\n    - ***重要***：僅呼叫 File API 並不會上傳您的檔案。您必須**手動上傳**檔案到**File API 回應中提供的網址**。該網址就是您的上傳目的地，請確保檔案成功傳輸到該處後再繼續。<br></br>\n    在呼叫 AI API 之前，請確保您的檔案已成功上傳。使用 File API 取得上傳網址，然後將檔案上傳到該位置。上傳完成後，您會在回應中取得 ***file_id***，這個 ID 就是您用於存取該檔案相關 AI 功能的依據。\n\n      > **警告：** 請注意，若您未將檔案上傳到 File API 回應中提供的網址，使用 AI API 時會得到 500 Server Error / unknown_internal_error 或 404 Not Found 錯誤。\n\n\n* 2. 啟動彩妝任務\n\n`POST /s2s/v2.0/task/makeup-vto`\n\n在提供的圖片上啟動新的虛擬彩妝任務。這個端點為非同步，會回傳 `task_id`。\n\n   * 請求標頭\n\n| 標頭 | 值 |\n|--------|-------|\n| Content-Type | `application/json` |\n| Authorization | `Bearer YOUR_API_KEY` |\n\n   * 請求內容範例\n```json\n{\n  \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/sample_Image_1_202b6bf6e6.jpg\",\n  \"effects\": [\n    {\n      \"category\": \"blush\",\n      \"pattern\": { \"name\": \"2colors6\" },\n      \"palettes\": [\n        { \"color\": \"#FF0000\", \"texture\": \"matte\", \"colorIntensity\": 50 },\n        { \"color\": \"#F2A53E\", \"texture\": \"matte\", \"colorIntensity\": 50 }\n      ]\n    },\n    {\n      \"category\": \"eye_liner\",\n      \"pattern\": { \"name\": \"3colors5\" },\n      \"palettes\": [\n        { \"color\": \"#000000\", \"texture\": \"matte\", \"colorIntensity\": 50 },\n        { \"color\": \"#BA0656\", \"texture\": \"matte\", \"colorIntensity\": 50 },\n        { \"color\": \"#089085\", \"texture\": \"matte\", \"colorIntensity\": 50 }\n      ]\n    }\n  ],\n  \"version\": \"1.0\"\n}\n```\n\n   * 請求內容 Schema\n\n| 欄位 | 類型 | 說明 |\n|-------|------|---------|\n| `src_file_url` | string（URL） | 要處理的自拍圖片之可公開存取的網址。 |\n| `effects` | Effect 陣列 | 要套用的彩妝特效物件陣列。細節請參考[彩妝特效 Schema](#makeup-effect-schemas)。 |\n| `version` | string | 特效內容結構的 API 版本。請使用 `\"1.0\"`。 |\n\n   * 成功的回應（`200 OK`）\n回傳包含任務識別碼的 JSON 物件。\n\n**回應內容 Schema：**\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_id\": \"<string>\"\n  }\n}\n```\n\n**回應範例：**\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_id\": \"grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe\"\n  }\n}\n```\n\n   * 錯誤回應（`400 Bad Request`、`401 InvalidApiKey` 等）\n會回傳標準的錯誤物件，並附帶描述失敗原因的訊息。\n\n**錯誤回應範例：**\n```json\n{\n  \"status\": 400,\n  \"error\": \"The operation could not be completed\",\n  \"error_code\": \"CreditInsufficiency\"\n}\n```\n\n---\n\n* 3. 取得任務狀態與結果\n\n`GET /s2s/v2.0/task/makeup-vto/<task_id>`\n\n取得進行中或已完成任務的目前狀態與結果。\n\n   * 請求標頭\n\n| 標頭 | 值 |\n|--------|-------|\n| Authorization | `Bearer YOUR_API_KEY` |\n\n   * 路徑參數\n\n| 參數 | 類型 | 說明 |\n|-----------|------|---------|\n| task_id | string | 從啟動任務端點回傳的識別碼。 |\n\n   * 成功的回應（`200 OK`）\n包含狀態的 JSON 物件，若已完成則包含結果。\n\n**回應內容 Schema：**\n```json\n{\n  \"data\": {\n    \"task_status\": \"<string>\", // 'success', 'error', or a processing state (e.g., 'queued', 'processing')\n    \"results\": [ // 僅在 task_status 為 'success' 時出現\n      {\n        \"download_url\": \"<string>\" // 下載處理後影像的 URL\n      }\n    ],\n    \"failure_reason\": \"<string>\" // 僅在 task_status 為 'error' 時出現\n  }\n}\n```\n\n**成功回應範例：**\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_status\": \"success\",\n    \"results\": {\n      \"url\": \"https://s3.storage.prod/processed/image_123.jpg?token=...\"\n    }\n  }\n}\n```\n\n**引擎錯誤回應範例：**\nAPI 查詢已成功送出；然而，執行 AI 任務時發生錯誤。\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_status\": \"error\",\n    \"error\": \"exceed_max_filesize\",\n    \"error_message\": \"string\",\n  }\n}\n```\n  > 請注意，若發生錯誤，無論是查詢錯誤或引擎錯誤，都不會消耗點數。\n\n**進行中回應範例：**\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_status\": \"running\"\n  }\n}\n```\n\n   * 錯誤回應\n*   `404 InvalidTaskId`：`task_id` 不存在或無效。\n*   `401 InvalidApiKey`：API key 無效或缺失。\n*   `500 TaskTimeout`：任務已成功完成或失敗，且已超過保留期限。\n\n**查詢錯誤回應範例：**\n```json\n{\n  \"status\": 401,\n  \"error_code\": \"InvalidApiKey\"\n}\n```\n  > 請注意，若發生錯誤，無論是查詢錯誤或引擎錯誤，都不會消耗點數。\n\n---\n\n## 輸入與輸出\n* 彩妝特效 Schema\n\n本節定義 AI 彩妝任務請求內容的完整結構與限制。每個特效都是上層 `effects` 陣列中的一個物件。\n\n* 特效容器（上層）\n\n```json\n{\n  \"version\": \"1.0\",\n  \"effects\": []                    // array<Effect> — Contains makeup effect objects\n}\n```\n\n* 彩妝特效類別\n\n   * `skin_smooth`\n```json\n{\n  \"category\": \"skin_smooth\",           // string, const \"skin_smooth\"\n  \"skinSmoothStrength\": 50,            // integer, range: 0..100\n  \"skinSmoothColorIntensity\": 50       // integer, range: 0..100\n}\n```\n  > **注意！** 若請求中未包含 ``skin_smooth`` 特效，AI 彩妝引擎會自動套用預設的 Skin Smooth 值 50。\n  若您希望套用彩妝但不進行肌膚平滑，請將所有 ``skinSmoothStrength`` 與 ``skinSmoothColorIntensity`` 參數設為 0。不過，為了獲得最佳結果與最高品質的融合，建議保留預設啟用的肌膚平滑。\n\n   * `blush`\n```json\n{\n  \"category\": \"blush\",                 // string, const \"blush\"\n  \"pattern\": {                         // object\n    \"name\": \"\"                         // string — 必須等於 blush.json 中的 `label`\n  },\n  \"palettes\": [                        // array<BlushPalette>, minItems: (see colorNum in pattern)\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"texture\": \"matte\",              // string, enum [\"matte\",\"satin\",\"shimmer\"]\n      \"glowStrength\": 50,              // integer, range: 0..100 — REQUIRED if texture=\"satin\"\n      \"shimmerColor\": \"#fc288f\",       // string, hex color \"#RRGGBB\" — REQUIRED if texture=\"shimmer\"\n      \"shimmerDensity\": 50,            // integer, range: 0..100 — REQUIRED if texture=\"shimmer\"\n      \"colorIntensity\": 50             // integer, range: 0..100\n    }\n  ]\n}\n```\n\n**完整圖樣目錄：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/blush.json\n\n**各彩妝圖樣類別：**\n```json\n[\n  {\n    \"category\": \"1 color\",\n    \"label\": \"1color1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/483/a53cd4f4-43b6-4e19-b85a-ec7a95c6a47f.jpg\",\n    \"tags\": [\n      { \"id\": 100, \"name\": \"Blush 3D\" },\n      { \"id\": 103, \"name\": \"Oblong\" }\n    ],\n    \"colorNum\": 1\n  },\n  {\n    \"category\": \"2 colors\",\n    \"label\": \"2colors1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/147/a8d86a4b-8aa0-48d7-a716-63ec78dfb30b.jpg\",\n    \"tags\": [\n      { \"id\": 100, \"name\": \"Blush 3D\" }\n    ],\n    \"colorNum\": 2\n  },\n  {\n    \"category\": \"3 colors\",\n    \"label\": \"3colors1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/734/af8b625b-ae3a-4211-9413-f22c16a5f174.jpg\",\n    \"tags\": [\n      { \"id\": 100, \"name\": \"Blush 3D\" },\n      { \"id\": 104, \"name\": \"Round\" }\n    ],\n    \"colorNum\": 3\n  }\n]\n```\n\n\n   * `bronzer`\n```json\n{\n  \"category\": \"bronzer\",               // string, const \"bronzer\"\n  \"pattern\": { \"name\": \"\" },           // object — name 必須等於 bronzer.json 中的 `label`\n  \"palettes\": [\n    { \"color\": \"#ff0000\", \"colorIntensity\": 50 }  // hex color, int range: 0..100\n  ]\n}\n```\n\n**完整圖樣目錄：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/bronzer.json\n\n**各彩妝圖樣類別：**\n```json\n[\n  {\n    \"category\": \"Bronzer\",\n    \"label\": \"Bronzer1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/973/22ff2c07-d584-4ae6-8281-c095cd121a52.jpg\",\n    \"tags\": [],\n    \"colorNum\": 1\n  }\n]\n```\n\n   * `concealer`\n```json\n{\n  \"category\": \"concealer\",             // string, const \"concealer\"\n  \"palettes\": [\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"colorIntensity\": 50,            // integer, range: 0..100\n      \"colorUnderEyeIntensity\": 50,    // integer, range: 0..100\n      \"coverageLevel\": 50              // integer, range: 0..100\n    }\n  ]\n}\n```\n\n   * `contour`\n```json\n{\n  \"category\": \"contour\",               // string, const \"contour\"\n  \"pattern\": { \"name\": \"\" },           // object — name 必須等於 contour.json 中的 `label`\n  \"palettes\": [\n    { \"color\": \"#ff0000\", \"colorIntensity\": 50 }  // hex color, int range: 0..100\n  ]\n}\n```\n\n**完整圖樣目錄：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/contour.json\n\n**各彩妝圖樣類別：**\n```json\n[\n  {\n    \"category\": \"Heart face\",\n    \"label\": \"HeartFace2\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/731/49a1b3b9-b393-4bf4-b486-1493fe468436.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Invtriangle\",\n    \"label\": \"Invtriangle1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/858/a94c8cca-5f8c-4b8b-a02d-94edb6a4ad7f.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Oval face\",\n    \"label\": \"OvalFace6\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/906/644368a3-7eee-4ad9-829e-e2b3d4320fec.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Round face\",\n    \"label\": \"RoundFace4\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/106/3e455b5f-7e2d-46f7-8627-dc137051c144.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Triangle face\",\n    \"label\": \"TriangleFace2\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/528/18765180-c254-4411-a25c-c1d78f5c3d77.jpg\",\n    \"tags\": []\n  }\n]\n```\n\n   * `eyebrows`\n```json\n{\n  \"category\": \"eyebrows\",              // string, const \"eyebrows\"\n  \"pattern\": {\n    \"type\": \"shape\",                   // string, enum [\"shape\",\"color\"], default: \"shape\"\n    \"name\": \"\",                        // string，type=\"shape\" 時必要 — eyebrows.json 的 label\n    \"curvature\": 0,                    // integer, range: -100..100 (shape only)\n    \"thickness\": 0,                    // integer, range: -100..100 (shape only)\n    \"definition\": 0                    // integer, range: 0..100 (shape only)\n  },\n  \"palettes\": [\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"colorIntensity\": 50,            // integer, range: 0..100\n      \"texture\": \"matte\",              // string, enum [\"matte\",\"shimmer\"]\n      \"shimmerColor\": \"#fc288f\",       // string, hex color \"#RRGGBB\" — REQUIRED if texture=\"shimmer\"\n      \"shimmerIntensity\": 50,          // integer, range: 0..100 — REQUIRED if texture=\"shimmer\"\n      \"shimmerSize\": 50,               // integer, range: 0..100 — REQUIRED if texture=\"shimmer\"\n      \"shimmerDensity\": 50             // integer, range: 0..100 — REQUIRED if texture=\"shimmer\"\n    }\n  ]\n}\n```\n\n**完整圖樣目錄：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/eyebrows.json\n\n**各彩妝圖樣類別：**\n```json\n[\n  {\n    \"category\": \"Arrow\",\n    \"label\": \"Arrow1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/490/1fb96bf9-979e-4327-a8c4-8c503f541f1a.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Curved\",\n    \"label\": \"Curved1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/389/1ccb300e-c7ed-4995-920e-7d1bf8da1fad.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Drama\",\n    \"label\": \"Drama2\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/196/5fb14bec-553d-4841-bba7-ca7e5e27c12e.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"High Arch\",\n    \"label\": \"HighArch1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/609/7a8676dc-6f6a-4b12-aab0-c50328e448c5.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Original\",\n    \"label\": \"Original2\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/300/123551e9-ca94-4732-89ed-5b3866678555.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Soft Arch\",\n    \"label\": \"SoftArch1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/121/2552ebf0-2705-43f7-b295-4fac21e18009.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Straight\",\n    \"label\": \"Straight1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/1/7734e777-8e51-41f1-abaf-205f0ed5e3b4.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Thin\",\n    \"label\": \"Thin1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/734/6ee10843-a251-4aa0-9183-db7f981d714d.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Upward\",\n    \"label\": \"Upward4\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/751/76578317-f475-49c7-bd96-910ccad617ef.jpg\",\n    \"tags\": []\n  }\n]\n```\n\n   * `eye_liner`\n```json\n{\n  \"category\": \"eye_liner\",             // string, const \"eye_liner\"\n  \"pattern\": { \"name\": \"\" },           // object — name 必須等於 eyeliner.json 中的 label\n  \"palettes\": [\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"texture\": \"matte\",              // string, enum [\"matte\",\"shimmer\",\"metallic\"]\n      \"shimmerColor\": \"#fc288f\",       // string, hex color \"#RRGGBB\" — REQUIRED if texture in [\"shimmer\",\"metallic\"]\n      \"shimmerIntensity\": 50,          // integer, range: 0..100 — REQUIRED if texture in [\"shimmer\",\"metallic\"]\n      \"metallicIntensity\": 50,         // integer, range: 0..100 — REQUIRED if texture=\"metallic\"\n      \"colorIntensity\": 50             // integer, range: 0..100\n    }\n  ]\n}\n```\n\n**完整圖樣目錄：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/eyeliner.json\n\n**各彩妝圖樣類別：**\n```json\n[\n  {\n    \"category\": \"2 colors\",\n    \"label\": \"2colors1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/419/71d9429a-dc08-4e80-9c46-6e55631ef766.jpg\",\n    \"tags\": [\n      {\n        \"id\": 28,\n        \"name\": \"Drama\"\n      }\n    ],\n    \"colorNum\": 2\n  },\n  {\n    \"category\": \"3 colors\",\n    \"label\": \"3colors2\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/208/056aa6cd-8678-470c-b111-b7653d7ddf93.jpg\",\n    \"tags\": [\n      {\n        \"id\": 28,\n        \"name\": \"Drama\"\n      }\n    ],\n    \"colorNum\": 3\n  },\n  {\n    \"category\": \"1 color\",\n    \"label\": \"Arabic3\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/726/1919aad4-21a2-493a-a5f8-48bc99a61ba5.jpg\",\n    \"tags\": [\n      {\n        \"id\": 26,\n        \"name\": \"Arabic\"\n      }\n    ],\n    \"colorNum\": 1\n  }\n]\n```\n\n   * `eye_shadow`\n```json\n{\n  \"category\": \"eye_shadow\",            // string, const \"eye_shadow\"\n  \"pattern\": { \"name\": \"\" },           // object — name 必須等於 eyeshadow.json 中的 label\n  \"palettes\": [\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"texture\": \"matte\",              // string, enum [\"matte\",\"shimmer\",\"metallic\"]\n      \"shimmerColor\": \"#fc288f\",       // string, hex color \"#RRGGBB\" — REQUIRED if texture in [\"shimmer\",\"metallic\"]\n      \"shimmerIntensity\": 50,          // integer, range: 0..100 — REQUIRED if texture in [\"shimmer\",\"metallic\"]\n      \"metallicIntensity\": 50,         // integer, range: 0..100 — REQUIRED if texture=\"metallic\"\n      \"colorIntensity\": 50             // integer, range: 0..100\n    }\n  ]                                    // minItems: (see colorNum in pattern)\n}\n```\n\n**完整圖樣目錄：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/eyeshadow.json\n\n**各彩妝圖樣類別：**\n```json\n[\n  {\n    \"category\": \"1 color\",\n    \"label\": \"1color1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/188/0322c4f9-e54d-4a6b-8072-6bb76560121a.jpg\",\n    \"tags\": [\n      {\n        \"id\": 12,\n        \"name\": \"Artistic\"\n      },\n      {\n        \"id\": 14,\n        \"name\": \"Dream\"\n      },\n      {\n        \"id\": 15,\n        \"name\": \"Trend\"\n      }\n    ],\n    \"colorNum\": 1\n  },\n  {\n    \"category\": \"2 colors\",\n    \"label\": \"2colors1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/938/3348211c-1b83-4ab2-9c6a-ce06e4aa3528.jpg\",\n    \"tags\": [\n      {\n        \"id\": 1,\n        \"name\": \"Fan shape\"\n      },\n      {\n        \"id\": 8,\n        \"name\": \"Only upper lid\"\n      }\n    ],\n    \"colorNum\": 2\n  },\n  {\n    \"category\": \"3 colors\",\n    \"label\": \"3colors1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/542/55e1b0fd-b888-47ff-bd3a-3dc1af2a7b69.jpg\",\n    \"tags\": [\n      {\n        \"id\": 1,\n        \"name\": \"Fan shape\"\n      },\n      {\n        \"id\": 8,\n        \"name\": \"Only upper lid\"\n      }\n    ],\n    \"colorNum\": 3\n  },\n  {\n    \"category\": \"4 colors\",\n    \"label\": \"4colors1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/429/29cd5839-464b-4a7a-a5c1-c7b40e9464d7.jpg\",\n    \"tags\": [\n      {\n        \"id\": 4,\n        \"name\": \"Closed banana\"\n      },\n      {\n        \"id\": 10,\n        \"name\": \"Whole eye\"\n      }\n    ],\n    \"colorNum\": 4\n  },\n  {\n    \"category\": \"5 colors\",\n    \"label\": \"5colors1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/2/824dcf7c-1273-4a30-8f1f-2137926057d6.jpg\",\n    \"tags\": [\n      {\n        \"id\": 4,\n        \"name\": \"Closed banana\"\n      },\n      {\n        \"id\": 10,\n        \"name\": \"Whole eye\"\n      }\n    ],\n    \"colorNum\": 5\n  }\n]\n```\n\n   * `eyelashes`\n```json\n{\n  \"category\": \"eyelashes\",             // string, const \"eyelashes\"\n  \"pattern\": { \"name\": \"\" },           // object — name 必須等於 eyelashes.json 中的 label\n  \"palettes\": [\n    { \"color\": \"#ff0000\", \"colorIntensity\": 50 }  // hex color, int range: 0..100\n  ]\n}\n```\n\n**完整圖樣目錄：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/eyelashes.json\n\n**各彩妝圖樣類別：**\n```json\n[\n  {\n    \"category\": \"Artistic\",\n    \"label\": \"Artistic1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/146/7a8ed606-1c27-4d91-9320-c40a904f621f.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Natural\",\n    \"label\": \"Natural1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/287/cd5cae75-a1b3-48f8-8537-e6e259213901.png\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Upper&Lower\",\n    \"label\": \"Upper&Lower1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/18/2689ea2d-725e-4fa0-8563-df874ae1a83f.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Upper\",\n    \"label\": \"Upper1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/982/c99bf74e-545f-4da7-a314-f3bd84b82156.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"UpperDense\",\n    \"label\": \"UpperDense1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/888/452ec863-f0a8-40e7-aa33-31c0c39f57e2.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Winged\",\n    \"label\": \"Winged1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/825/36ab3859-eae5-49e4-9d97-161698bbb8bb.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Wispies\",\n    \"label\": \"Wispies1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/722/a2a727f6-748c-41e7-8ac0-c9c57c18c05a.png\",\n    \"tags\": []\n  }\n]\n```\n\n   * `foundation`\n```json\n{\n  \"category\": \"foundation\",            // string, const \"foundation\"\n  \"palettes\": [\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"colorIntensity\": 50,            // integer, range: 0..100\n      \"glowIntensity\": 50,             // integer, range: 0..100\n      \"coverageIntensity\": 50          // integer, range: 0..100\n    }\n  ]\n}\n```\n\n   * `highlighter`\n```json\n{\n  \"category\": \"highlighter\",           // string, const \"highlighter\"\n  \"pattern\": { \"name\": \"\" },           // object — name 必須等於 highlighter.json 中的 label\n  \"palettes\": [\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"glowIntensity\": 50,             // integer, range: 0..100\n      \"shimmerIntensity\": 50,          // integer, range: 0..100\n      \"shimmerDensity\": 50,            // integer, range: 0..100\n      \"shimmerSize\": 50,               // integer, range: 0..100\n      \"colorIntensity\": 50             // integer, range: 0..100\n    }\n  ]\n}\n```\n\n**完整圖樣目錄：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/highlighter.json\n\n**各彩妝圖樣類別：**\n```json\n[\n  {\n    \"category\": \"Heart face\",\n    \"label\": \"HeartFace4\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/246/6ca40279-79cc-4918-b48a-64306009b365.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Invtriangle\",\n    \"label\": \"Invtriangle2\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/7/6b0b9760-612c-4319-bd81-855d262d8e89.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Oblong\",\n    \"label\": \"Oblong11\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/862/b7279f4e-edf2-43f3-8156-561fe5a52ec3.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Oval face\",\n    \"label\": \"OvalFace2\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/369/91097a05-9fd2-43cb-82e9-dd45e72b613b.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Round face\",\n    \"label\": \"RoundFace3\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/520/2d3ccbe2-36c3-43df-9e78-4c2c931fa431.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Square face\",\n    \"label\": \"SquareFace3\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/989/2959777b-19ca-4f4a-a023-3c8927191497.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Triangle face\",\n    \"label\": \"TriangleFace3\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/765/221c1f12-c621-4567-a8ee-1433038ee8a2.jpg\",\n    \"tags\": []\n  }\n]\n```\n\n   * `lip_color`\n```json\n{\n  \"category\": \"lip_color\",             // string, const \"lip_color\"\n  \"shape\": {                           // object — driven by lipshape.json\n    \"name\": \"original\"                 // string — 必須等於 lipshape.json 中的 `label`\n  },\n  \"morphology\": {                      // optional object\n    \"fullness\": 50,                    // integer, range: 0..100 (default: 0)\n    \"wrinkless\": 50                    // integer, range: 0..100 (default: 0)\n  },\n  \"palettes\": [                        // minItems depends on style; often ≥1\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"texture\": \"matte\",              // string, enum [\"matte\",\"gloss\",\"holographic\",\"metallic\",\"satin\",\"sheer\",\"shimmer\"]\n      \"colorIntensity\": 50,            // integer, range: 0..100\n      \"gloss\": 50,                     // int, range: 0..100 — REQUIRED if texture in [\"gloss\",\"holographic\",\"metallic\",\"sheer\",\"shimmer\"]\n      \"shimmerColor\": \"#ff0000\",       // string, hex color \"#RRGGBB\" — REQUIRED if texture in [\"holographic\",\"metallic\",\"shimmer\"]\n      \"shimmerIntensity\": 50,          // integer, range: 0..100 — REQUIRED if texture in [\"holographic\",\"metallic\",\"shimmer\"]\n      \"shimmerDensity\": 50,            // integer, range: 0..100 — REQUIRED if texture in [\"holographic\",\"metallic\",\"shimmer\"]\n      \"shimmerSize\": 50,               // integer, range: 0..100 — REQUIRED if texture in [\"holographic\",\"metallic\",\"shimmer\"]\n      \"transparencyIntensity\": 50      // integer, range: 0..100 — REQUIRED if texture in [\"gloss\",\"sheer\",\"shimmer\"]\n    }\n  ],\n  \"style\": {\n    \"type\": \"full\",                    // string, enum [\"full\",\"ombre\",\"twoTone\"]\n    \"innerRatio\": 50,                  // int, range: 0..100 — REQUIRED if type=\"ombre\"\n    \"featherStrength\": 50              // int, range: 0..100 — REQUIRED if type=\"ombre\"\n  }\n}\n```\n\n**完整圖樣目錄：**\nhttps://plugins-media.makeupar.com/wcm-saas/shapes/lipshape.json\n\n**各彩妝圖樣類別：**\n```json\n[{\n        \"category\": \"general\",\n        \"label\": \"original\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/original.png\",\n        \"tags\": [\n        ]\n    }, {\n        \"category\": \"general\",\n        \"label\": \"heart-shaped\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/heart-shaped.jpg\",\n        \"tags\": [\n        ]\n    }, {\n        \"category\": \"general\",\n        \"label\": \"m-shaped\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/m-shaped.jpg\",\n        \"tags\": [\n        ]\n    }, {\n        \"category\": \"general\",\n        \"label\": \"petal\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/petal.jpg\",\n        \"tags\": [\n        ]\n    }, {\n        \"category\": \"general\",\n        \"label\": \"plump\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/plump.jpg\",\n        \"tags\": [\n        ]\n    }, {\n        \"category\": \"general\",\n        \"label\": \"pouty\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/pouty.jpg\",\n        \"tags\": [\n        ]\n    }, {\n        \"category\": \"general\",\n        \"label\": \"smile\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/smile.jpg\",\n        \"tags\": [\n        ]\n    }, {\n        \"category\": \"general\",\n        \"label\": \"vintage\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/vintage.jpg\",\n        \"tags\": [\n        ]\n    }\n]\n```\n\n   * `lip_liner`\n```json\n{\n  \"category\": \"lip_liner\",             // string, const \"lip_liner\"\n  \"pattern\": { \"name\": \"\" },           // object — name 必須等於 lipliner.json 中的 label\n  \"palettes\": [\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"texture\": \"matte\",              // string, enum [\"matte\",\"satin\"]\n      \"colorIntensity\": 50,            // integer, range: 0..100\n      \"thickness\": 50,                 // integer, range: 0..100\n      \"smoothness\": 50                 // integer, range: 0..100\n    }\n  ]\n}\n```\n\n**完整圖樣目錄：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/lipliner.json\n\n**各彩妝圖樣類別：**\n```json\n[\n  {\n    \"category\": \"Large & Full\",\n    \"label\": \"Large&Full1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/417/7ac66cb2-2c7b-451c-8284-cc77791b7001.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Larger Lower\",\n    \"label\": \"LargerLower1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/878/84b2ef48-3af4-4851-86d2-b01d10db82b2.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Larger Upper\",\n    \"label\": \"LargerUpper1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/867/674f9f4c-7961-462e-8cc9-9a8acaad4168.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Natural\",\n    \"label\": \"Natural1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/258/7533c08a-cc9c-45ab-9294-5d5a8114037d.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Rosebud\",\n    \"label\": \"Rosebud1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/47/eb95e91f-6ef1-41f7-bc4f-aecd7d780c42.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Small\",\n    \"label\": \"Small1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/396/6b78e461-24a6-4c6d-afb4-88beb71f1732.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Wider\",\n    \"label\": \"Wider1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/867/21f92b70-72b5-4a57-b4d7-81c5cce757a6.jpg\",\n    \"tags\": []\n  }\n]\n```\n\n---\n\n## 內容範例\n\n以下是一個套用多個特效的有效 `effectJson` 內容完整範例。\n\n```json\n{\n  \"version\": \"1.0\",\n  \"effects\": [\n    {\n      \"category\": \"skin_smooth\",\n      \"skinSmoothStrength\": 55,\n      \"skinSmoothColorIntensity\": 45\n    },\n    {\n      \"category\": \"blush\",\n      \"pattern\": { \"name\": \"2colors1\" },\n      \"palettes\": [\n        {\n          \"color\": \"#e19f9f\",\n          \"texture\": \"matte\",\n          \"colorIntensity\": 60,\n          \"shimmerColor\": \"#d63252\",\n          \"shimmerDensity\": 50\n        },\n        {\n          \"color\": \"#c98a8a\",\n          \"texture\": \"satin\",\n          \"glowStrength\": 40,\n          \"colorIntensity\": 70\n        }\n      ]\n    },\n    {\n        \"category\": \"lip_color\",\n        \"shape\": { \"name\": \"plump\" },\n        \"morphology\": { \"fullness\": 30, \"wrinkless\": 25 },\n        \"style\": { \"type\": \"full\" },\n        \"palettes\": [\n            {\n                \"color\": \"#e11c43\",\n                \"texture\": \"gloss\",\n                \"colorIntensity\": 80,\n                \"gloss\": 75\n            }\n        ]\n    }\n  ]\n}\n```\n在此範例中，`blush` 使用來自 `blush.json` 的 `2colors1` 圖樣，需要恰好兩個調色盤。`lip_color` 特效使用來自 `lipshape.json` 的 `plump` 形狀。\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 虛擬試妝|長邊 < 1920，臉寬 >= 100|< 10MB|jpg/jpeg/png|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n|error_below_min_image_size|來源圖片尺寸小於最小值（期望：寬 >= 100px，高 >= 100px）\n|error_exceed_max_image_size|來源圖片尺寸大於最大值（期望：寬 < 1920px，高 < 1080px）\n|error_face_position_invalid |請確保您的整張臉在圖片中完全可見|\n|error_face_position_too_small|偵測到的臉部過小。請靠近鏡頭|\n|error_face_position_out_of_boundary|臉部過大或部分在畫面之外。請調整您的位置|\n|error_face_angle_invalid|臉部角度不正確。正面照片請將頭部保持在 10° 內。側面照片請確保超過 15°。|\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 虛擬試妝 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_look_vto.yaml","link":"/zh-tw/reference/ai_look_vto","routeSlug":"/zh-tw/reference/ai_look_vto","label":"AI 完整妝容虛擬試妝","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_look_vto/section/概述","routeSlug":"/zh-tw/reference/ai_look_vto/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_look_vto/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_look_vto/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_look_vto/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_look_vto/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_look_vto/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_look_vto/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_look_vto/v1.0","routeSlug":"/zh-tw/reference/ai_look_vto/v1.0","items":[{"label":"列出預先定義的範本。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1template~1look-vto/get","routeSlug":"/zh-tw/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1template~1look-vto/get","metadata":{"seo":{"title":"列出預先定義的範本。","description":"列出預先定義的範本。"}},"httpPath":"/s2s/v2.0/task/template/look-vto"},{"label":"執行 AI 完整妝容虛擬試妝任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1look-vto/post","routeSlug":"/zh-tw/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1look-vto/post","metadata":{"seo":{"title":"執行 AI 完整妝容虛擬試妝任務。","description":"這個端點使用範本與來源照片啟動完整妝容虛擬試妝流程。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/look-vto"},{"label":"查詢 AI 完整妝容虛擬試妝任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1look-vto~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1look-vto~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 完整妝容虛擬試妝任務的狀態。","description":"查詢 AI 完整妝容虛擬試妝任務的狀態。"}},"httpPath":"/s2s/v2.0/task/look-vto/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 完整妝容虛擬試妝","version":"","description":"# 概述\nAI 完整妝容虛擬試妝 API 提供完整的工作流程，將專業設計的臉部造型套用到使用者照片。每個造型都由美妝專家打造，可透過 API 即刻套用。\n\n## 整合指南\n本指南將引導您完成：\n\n*   **端點：** `/s2s/v2.0/task/look-vto`\n*   **認證：** 所有請求都需要 `Authorization: Bearer <TOKEN>`\n*   **工作流程：**\n    1.  **準備自拍：** 上傳圖片，或提供有效的圖片網址\n    1.  **列出造型範本：** 列出可用的 AI 完整妝容範本\n    1.  **啟動任務（`POST`）：** 提交您的圖片 id/網址與造型 ``template_id``。\n    1.  **取得任務 ID：** 從回應中取得 `task_id`。\n    1.  **輪詢狀態（`GET`）：** 使用 `task_id` 查詢任務狀態。持續輪詢，直到 `task_status` 為 `\"success\"` 或 `\"error\"`。\n\n---\n\n* API Playground\n\n使用我們的官方 playground 進行互動式探索與測試：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-look-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-look-virtual-try-on/)\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n    ```\n    Authorization: Bearer <API Key>\n    ```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n\n* 1. 上傳圖片\n\n您可以直接上傳檔案到伺服器，或在 VTO 任務內容中提供有效的圖片網址。\n\n   * 上傳端點\n\n```\nPOST /s2s/v2.0/file\n```\n\n或者，若您已有公開的圖片網址，可跳過此步驟。\n\n---\n\n* 2. 列出可用的造型風格\n\n取得所有可用於虛擬試妝的 AI 彩妝造型範本。\n\n   * 端點\n\n```\nGET /s2s/v2.0/task/template/look-vto\n```\n\n   * 查詢參數\n\n| 參數        | 說明                     |\n| ---------------- | ------------------------------- |\n| `page_size`      | 每頁的項目數量        |\n| `starting_token` | 用於分頁的令牌（選填） |\n\n   * JavaScript 請求範例\n\n```javascript\nconst data = null;\n\nconst xhr = new XMLHttpRequest();\nxhr.withCredentials = true;\n\nxhr.addEventListener('readystatechange', function () {\n    if (this.readyState === this.DONE) {\n        console.log(this.responseText);\n    }\n});\n\nxhr.open('GET', 'https://yce-api-01.makeupar.com/s2s/v2.0/task/template/look-vto?page_size=20&starting_token=73a3c9e69b89');\nxhr.setRequestHeader('Authorization', 'Bearer <access_token for v1, API Key for v2>');\n\nxhr.send(data);\n```\n\n   * 成功回應範例\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"templates\": [\n      {\n        \"id\": \"good_template_001\",\n        \"thumb\": \"縮略圖預覽圖片網址\",\n        \"title\": \"Berry Smooth\",\n        \"category_name\": \"Daily\"\n      }\n    ],\n    \"next_token\": 73a3c9e69b89\n  }\n}\n```\n\n> **注意：** 在建立造型 VTO 任務時，使用 `id` 值（`template_id`）。\n\n---\n\n* 3. 建立造型 VTO 任務並輪詢結果\n\n當您取得圖片與範本 ID 後，即可建立任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 `success` 或 `error`。\n\n   * 建立任務端點\n\n```\nPOST /s2s/v2.0/task/look-vto\n```\n\n   * 輪詢端點\n\n```\nGET /s2s/v2.0/task/look-vto/{task_id}\n```\n\n---\n\n   * JavaScript 實作範例\n\n```javascript\nconst BASE_URL = 'https://yce-api-01.makeupar.com/s2s/v2.0/task/look-vto';\nconst START_METHOD = 'POST';\nconst HEADERS = {\n  \"Content-Type\": \"application/json\",\n  \"Authorization\": \"Bearer YOUR_API_KEY\"\n};\n\nconst sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));\n\nasync function startTask() {\n  const init = {\n    method: START_METHOD,\n    headers: HEADERS,\n    body: JSON.stringify({\n      \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/sample_Image_7_fa28b2618a.jpg\",\n      \"template_id\": \"all_rosy_chic\"\n    })\n  };\n\n  const res = await fetch(BASE_URL, init);\n  if (!res.ok) throw new Error(`Start request failed: ${res.status} ${res.statusText}`);\n\n  const payload = await res.json().catch(() => ({}));\n  const taskId = payload?.data?.task_id;\n  if (!taskId) throw new Error('task_id missing: ' + JSON.stringify(payload));\n\n  console.log('[startTask] Task started, id =', taskId);\n  return taskId;\n}\n\nasync function pollTask(taskId, { intervalMs = 2000, maxAttempts = 300 } = {}) {\n  for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n    const pollUrl = `${BASE_URL}/${taskId}`;\n    const res = await fetch(pollUrl, { method: 'GET', headers: HEADERS });\n\n    if (!res.ok) throw new Error(`Polling failed: ${res.status} ${res.statusText}`);\n\n    const payload = await res.json().catch(() => ({}));\n    const status = payload?.data?.task_status;\n    console.log(`[pollTask] Attempt ${attempt} status = ${status}`);\n\n    if (status === 'success') {\n      console.log('[pollTask] Success results:', payload?.data?.results);\n      return payload;\n    }\n\n    if (status === 'error') {\n      throw new Error('Task failed: ' + JSON.stringify(payload));\n    }\n\n    await sleep(intervalMs);\n  }\n\n  throw new Error('Polling timeout: Max attempts exceeded');\n}\n\n(async () => {\n  try {\n    const taskId = await startTask();\n    const final = await pollTask(taskId);\n    console.log('[main] Final response:', final);\n  } catch (e) {\n    console.error('[main] Flow error:', e);\n  }\n})();\n```\n\n---\n\n   * 成功回應範例\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"results\": {\n      \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/.../result.jpg?...\"\n    },\n    \"task_status\": \"success\"\n  }\n}\n```\n\n`results.url` 欄位包含最終渲染的虛擬彩妝影像。\n\n---\n\n* 摘要\n\n| 步驟                       | 說明                              |\n| -------------------------- | ---------------------------------------- |\n| **1. 上傳圖片**        | 直接上傳，或提供圖片網址。 |\n| **2. 列出造型範本** | 取得可用的造型風格及其 ID。 |\n| **3. 建立 VTO 任務**     | 提交圖片網址 + 範本 ID。          |\n| **4. 輪詢至完成** | 取得最終結果圖片網址。     |\n\n這個工作流程確保可靠、開發者友善的整合，用於即時虛擬彩妝試色體驗。\n\n---\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 完整妝容虛擬試妝|長邊 < 1920，臉寬 >= 100|< 10MB|jpg/jpeg/png|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n|error_below_min_image_size|來源圖片尺寸小於最小值（期望：寬 >= 100px，高 >= 100px）\n|error_exceed_max_image_size|來源圖片尺寸大於最大值（期望：寬 < 1920px，高 < 1080px）\n|error_face_position_invalid |請確保您的整張臉在圖片中完全可見|\n|error_face_position_too_small|偵測到的臉部過小。請靠近鏡頭|\n|error_face_position_out_of_boundary|臉部過大或部分在畫面之外。請調整您的位置|\n|error_face_angle_invalid|臉部角度不正確。正面照片請將頭部保持在 10° 內。側面照片請確保超過 15°。|\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 完整妝容虛擬試妝 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_nail_transfer.yaml","link":"/zh-tw/reference/ai_nail_transfer","routeSlug":"/zh-tw/reference/ai_nail_transfer","label":"AI 美甲移轉","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_nail_transfer/section/概述","routeSlug":"/zh-tw/reference/ai_nail_transfer/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_nail_transfer/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_nail_transfer/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_nail_transfer/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_nail_transfer/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_nail_transfer/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_nail_transfer/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_nail_transfer/v1.0","routeSlug":"/zh-tw/reference/ai_nail_transfer/v1.0","items":[{"label":"執行 AI 美甲移轉任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_nail_transfer/v1.0/paths/~1s2s~1v2.0~1task~1ai-nail/post","routeSlug":"/zh-tw/reference/ai_nail_transfer/v1.0/paths/~1s2s~1v2.0~1task~1ai-nail/post","metadata":{"seo":{"title":"執行 AI 美甲移轉任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/ai-nail"},{"label":"查詢 AI 美甲移轉任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_nail_transfer/v1.0/paths/~1s2s~1v2.0~1task~1ai-nail~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_nail_transfer/v1.0/paths/~1s2s~1v2.0~1task~1ai-nail~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 美甲移轉任務的狀態。","description":"查詢 AI 美甲移轉任務的狀態。"}},"httpPath":"/s2s/v2.0/task/ai-nail/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 美甲移轉","version":"","description":"# 概述\nAI 美甲移轉 API 是強大的生成式 AI 解決方案，用於虛擬美甲試色體驗。由 YouCam API 先進的 AI 模型與影像轉換技術驅動，使用者可從參考照片，即刻將任何理想的美甲設計移轉到自己的手上，具備卓越的真實感與精準度。\n\n從凝膠指甲、美甲藝術與指甲油妝效，到亮片、貝殼點綴與金屬質地等精緻裝飾，AI 精準重現廣泛的美甲風格，呈現自然、高解析度的虛擬預覽。這讓消費者能在購買前自信地探索與呈現設計。\n\n對美妝品牌、沙龍與美甲師而言，AI 美甲移轉 API 提供快速且引人入勝的方式，向客戶展示美甲設計，透過沉浸式的虛擬體驗，協助提升顧客互動、改善滿意度，並提高轉換率。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2022-11-24/8821ab6e-9852-4401-89df-dd6005fb81fc.jpg)\n\n## 整合指南\n本指南將引導您完成：\n\nAI 美甲移轉 API 的工作流程：\n\n**端點：** `/s2s/v2.0/task/ai-nail`\n\n**需要認證：** `Authorization: Bearer YOUR_API_KEY`\n\n**工作流程步驟：**\n\n1. **圖片上傳準備：**\n- 流程從透過 File API 準備手部圖片開始，傳送到 `/s2s/v2.0/file`。\n\n2. **參考照片上傳：**\n- 透過 File API 上傳展示您理想美甲設計的參考照片到 `/s2s/v2.0/file`。為獲得最佳結果，請確保所有指甲都清晰可見。\n\n1. **啟動 AI 任務並取得任務 ID：**\n- 透過 HTTP POST 請求，將上傳的圖片傳送到 `/s2s/v2.0/task/ai-nail`。\n- 在回應中取得唯一的 `task_id`，用以識別這次互動。\n\n1. **輪詢任務狀態（持續檢查）：**\n- 使用取得的 `task_id`，透過 HTTP GET 請求（例如 `GET /task/${task_id}`）定期輪詢任務狀態。\n- 持續監控：\n- `Task_status = \"success\"`（流程完成）。\n- `Task_status = \"error\"`（視情況解決或重試）。\n- 狀態轉為成功後，相應更新工作流程。\n\n這個結構化的工作流程確保與使用者輸入的高效整合、任務的自動化監控，以及無縫取得結果。\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n\n* 1. 上傳圖片\n\n您可以直接上傳檔案到伺服器，或在 AI 任務內容中提供有效的圖片網址。\n\n* 上傳端點\n\n```\nPOST /s2s/v2.0/file\n```\n\n或者，若您已有公開的圖片網址，可跳過此步驟。\n\n---\n\n* 2. 上傳參考照片\n\n您可以直接上傳檔案到伺服器，或在 AI 任務內容中提供有效的圖片網址。請確保所有指甲可見，以獲得最精準的虛擬試色體驗。\n\n* 上傳端點\n\n```\nPOST /s2s/v2.0/file\n```\n\n---\n\n* 3. 建立 AI 美甲移轉任務並輪詢結果\n\n當您取得圖片與完整的特效內容後，即可建立任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 `success` 或 `error`。\n\n* 建立任務端點\n\n```\nPOST /s2s/v2.0/task/ai-nail\n```\n\n* 輪詢端點\n\n```\nGET /s2s/v2.0/task/ai-nail/{task_id}\n```\n\n---\n\n## 檔案規格與錯誤\n\n* AI 美甲移轉規範\n\n    **支援的手部視角**\n\n    每張圖片最多支援兩隻手。額外的手會被忽略。為獲得最佳偵測效果，每隻手應佔圖片面積至少 0.5%（在 FHD 約為 102×102 px，2K 約為 139×139 px，4K 約為 204×204 px）。\n\n    ![](https://plugins-media.makeupar.com/strapi/assets/small_webp_bare_nails_014_f6451b0343.png)\n\n\n    **支援的參考圖片**\n\n    ![](https://plugins-media.makeupar.com/strapi/assets/small_webp_ref_6_341b11df3d.png)\n\n    ![](https://plugins-media.makeupar.com/strapi/assets/small_webp_ref_2_86a47c1c26.png)\n\n---\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n| ---- | ---- | ---- | ---- |\n| AI 美甲移轉 | 長邊 <= 4096 | < 10MB | jpg/jpeg/png |\n\n* 錯誤代碼\n\n| 錯誤代碼 | 說明 |\n| ---- | ---- |\n| exceed_max_filesize | 圖片檔案過大 |\n| invalid_parameter | 輸入參數缺失或格式錯誤 |\n| error_download_image | 檔案上傳未完成，或圖片網址無效 |\n| error_inference | 推論失敗，請確認輸入與參考圖片是否受支援 |\n| no_hand_detected | 來源圖片中未偵測到手 |\n\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>- curl >= 7.58（現代 TLS/HTTP 支援）</br>- jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>- Firefox >= 74</br>- Safarin b\\\n| PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) orn b\\_fopen=On + ext-openssl, ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 美甲移轉 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_nail_vto.yaml","link":"/zh-tw/reference/ai_nail_vto","routeSlug":"/zh-tw/reference/ai_nail_vto","label":"AI 虛擬美甲","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_nail_vto/section/概述","routeSlug":"/zh-tw/reference/ai_nail_vto/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_nail_vto/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_nail_vto/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_nail_vto/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_nail_vto/section/概述/檔案規格與錯誤"},{"type":"link","label":"JS Camera Kit","link":"/zh-tw/reference/ai_nail_vto/section/概述/js-camera-kit","routeSlug":"/zh-tw/reference/ai_nail_vto/section/概述/js-camera-kit"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_nail_vto/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_nail_vto/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_nail_vto/v1.0","routeSlug":"/zh-tw/reference/ai_nail_vto/v1.0","items":[{"label":"執行 AI 虛擬美甲任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_nail_vto/v1.0/paths/~1s2s~1v2.0~1task~1nail-vto/post","routeSlug":"/zh-tw/reference/ai_nail_vto/v1.0/paths/~1s2s~1v2.0~1task~1nail-vto/post","metadata":{"seo":{"title":"執行 AI 虛擬美甲任務。","description":"這個端點啟動虛擬美甲流程。您必須提供來源檔案與參考圖片（透過網址或檔案 ID），以及特定的美甲特效設定。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/nail-vto"},{"label":"查詢 AI 虛擬美甲任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_nail_vto/v1.0/paths/~1s2s~1v2.0~1task~1nail-vto~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_nail_vto/v1.0/paths/~1s2s~1v2.0~1task~1nail-vto~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 虛擬美甲任務的狀態。","description":"查詢 AI 虛擬美甲任務的狀態。"}},"httpPath":"/s2s/v2.0/task/nail-vto/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 虛擬美甲","version":"","description":"# 概述\nAI 虛擬美甲 API 為對美甲感興趣的顧客提供了創新的線上體驗提升方式。它讓購物者虛擬呈現多種美甲風格，從人造與壓克力指甲、穿戴式指甲到凝膠設計。憑藉無限的顏色與質地選項，使用者可輕鬆在自然與人造指甲上探索不同外觀。此平台支援個人化的試戴，讓使用者輕鬆在風格間切換，並看見前後對比。這種無縫整合簡化了產品發現流程，並在購買前提供精準、互動的預覽，提升顧客信心。\n\n## 整合指南\n本指南將引導您完成：\n\nAI 虛擬美甲 API 的工作流程：\n\n**需要認證：** `Authorization: Bearer YOUR_API_KEY`\n\n**工作流程步驟：**\n\n1. **圖片上傳準備：**\n    - 流程從準備手背圖片開始。\n    - 呼叫 File API `/s2s/v2.0/file` 取得上傳網址與相關的 `file_id`。\n    - 使用提供的上傳網址，上傳含指甲的手背圖片。\n\n2. **美甲設計設定選項：**\n    - 先選擇合適的指甲顏色。您也可以依自己的喜好選擇自訂形狀。\n\n3. **啟動 AI 任務並取得任務 ID：**\n    - 透過 HTTP POST 請求，將上傳的圖片與所選特效設定傳送到 `/s2s/v2.0/task/nail-vto`。\n    - 在回應中取得唯一的任務 ID，用以識別這次互動。\n\n4. **輪詢任務狀態（持續檢查）：**\n    - 使用取得的 `task_id`，透過 HTTP GET 請求（例如 `GET /s2s/v2.0/task/nail-vto/${task_id}`）定期輪詢任務狀態。\n    - 持續監控：\n        - `Task_status = \"success\"`（流程完成）。\n        - `Task_status = \"error\"`（視情況解決或重試）。\n    - 狀態轉為成功後，相應更新工作流程。\n\n這個結構化的工作流程確保與使用者輸入的高效整合、任務的自動化監控，以及無縫取得結果。\n\n---\n\n* API Playground\n\n使用我們的官方 playground 進行互動式探索與測試：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-nail-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-nail-virtual-try-on/)\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n    ```\n    Authorization: Bearer YOUR_API_KEY\n    ```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n\n1. 上傳圖片\n\n    您可以直接上傳檔案到伺服器，或在 VTO 任務內容中提供有效的圖片網址。\n\n    * 上傳端點\n\n        ```\n        POST /s2s/v2.0/file\n        ```\n\n    或者，若您已有公開的圖片網址，可跳過此步驟。\n\n---\n\n2. 準備特效範本\n\n    * 有四種不同的設定模式可用於此目的：\n        1. 自訂顏色，並與您目前的指甲外觀對齊\n        2. 使用預設設計與特定形狀，創造您的願景\n        3. 加入穿戴式指甲，並與您既有的原始指甲圖片連結\n        4. 提供符合的穿戴式指甲產品圖片連結 \n\n    * 特效範本 JSON Schema\n        ```\n        {\n            \"version\": \"1.0\",\n            \"effect_type\": \"nail_polish\", // valid values: ['nail_polish', 'press_on_nails']\n            \"effects\": [],\n            \"ref_file_ids\": []\n        }\n        ```\n\n        * 特效格式\n            - 指甲油 - 顏色\n            ```\n            {\n                \"sub_type\": \"color\",\n                \"finger\": \"index\", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']\n                \"color\": \"#ff0000\",\n                \"texture\": \"cream\", // valid values: ['matte', 'cream', 'metallic', 'jelly', 'sheer', 'pearl', 'textured', 'shimmer_coarse', 'shimmer_fine']\n                \"transparency\": 0, // 0-100，適用於金屬以外的質感\n                \"reflection\": 0, // 0-100\n                \"contrast\": 0, // 0-100\n                \"roughness\": 0, // 0-100\n                \"shimmer_opacity\": 0, // 0-100，適用於珍珠質感\n                \"shimmer_size\": 0, // 0-100，適用於 shimmer_coarse 與 shimmer_fine 質感\n                \"textured_size\": 0, // 0-100，適用於 textured 質感\n            }\n            ```\n\n            - 指甲油 - 設計\n            ```\n            {\n                \"sub_type\": \"design\",\n                \"finger\": \"index\", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']\n                \"ref_file_url\": \"\",  // 選填；ref_file_id 或 ref_file_url 必須填寫其一，但只能選擇一項。\n                \"ref_file_index\": 0, // 除非選擇上傳，此欄位為選填。對應根節點下 ref_file_ids 的索引\n                \"texture\": \"cream\", // valid values: ['matte', 'cream', 'metallic', 'jelly', 'sheer', 'pearl', 'textured', 'shimmer_coarse', 'shimmer_fine']\n                \"transparency\": 0, // 0-100，僅適用於金屬以外的質感\n                \"reflection\": 0, // 0-100\n                \"contrast\": 0, // 0-100\n                \"roughness\": 0, // 0-100\n                \"shimmer_opacity\": 0, // 0-100，適用於珍珠質感\n                \"shimmer_size\": 0, // 0-100，適用於 shimmer_coarse 與 shimmer_fine 質感\n                \"textured_size\": 0, // 0-100，適用於 textured 質感\n            }\n\n            ```\n\n            - 穿戴式指甲 - 顏色\n            * 最新的形狀值可在以下網址找到：https://plugins-media.makeupar.com/wcm-saas/shapes/nails.json\n            ```\n            {\n                \"sub_type\": \"color\",\n                \"finger\": \"index\", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']\n                \"shape\": \"square_oval\", // 請查閱 nails.json。有效值：['square_oval','square_square','square_squoval','squoval_oval','squoval_square','squoval_squoval','oval_oval','oval_square','oval_squoval','almond_oval','almond_square','almond_squoval','stiletto_oval','stiletto_square','stiletto_squoval],\n                \"length\": 1.0, // 0.8-2.15，適用於 original 以外的形狀\n                \"color\": \"#ff0000\",\n                \"texture\": \"cream\", // 其他形狀的有效值：['matte', 'cream', 'metallic']\n                \"reflection\": 0, // 0-100\n                \"contrast\": 0, // 0-100\n                \"roughness\": 0 // 0-100\n            }\n            ```\n\n            - 穿戴式指甲 - 設計\n            ```\n            {\n                \"sub_type\": \"design\",\n                \"finger\": \"index\", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']\n                \"ref_file_url\": \"\",  // 選填；ref_file_id 或 ref_file_url 必須填寫其一，但只能選擇一項。\n                \"ref_file_index\": 0, // 除非選擇上傳，此欄位為選填。對應根節點下 ref_file_ids 的索引\n                \"texture\": \"cream\", // valid values: ['matte', 'cream', 'metallic']\n                \"reflection\": 0, // 0-100\n                \"contrast\": 0, // 0-100\n                \"roughness\": 0, // 0-100\n            }\n\n            ```\n\n   * 特效範本設計邏輯\n\n        1. **偵測特效類型**（`press_on_nails` 與 `nail_polish`）。\n        2. **遍歷 `effects` 中的每個條目：**\n\n        *若 `sub_type === \"color\"`* → 直接對應欄位，以預設值填入缺失的質地相關鍵。\n        *若 `sub_type === \"design\"`* →\n        - 若使用者提供了 `ref_file_url`，保留它並**省略** `ref_file_index`。\n        - 若使用者提供了索引（`ref_file_index`），確保 `ref_file_ids` 存在且索引有效；然後設定 `\"ref_file_id\": ref_file_ids[index]`（選填——某些後端期望原始索引，而非 id）。\n\n        1. **正規化數值範圍** – 將任何超出範圍的值限制在 0‑100 或長度限制內。\n        2. **加入缺失的選填鍵**並設預設值，讓 schema 驗證通過。\n        3. 將最終物件**序列化**為 JSON（精簡格式，或為除錯使用美化格式）。\n\n   * 內容範例（可直接發送）\n        ```\n        {\n        \"version\": \"1.0\",\n        \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/nail_user_photo_01_27d4260646.jpg\",\n        \"effect_type\": \"press_on_nails\",\n        \"ref_file_ids\": [\n            \"Ks3kh+1nPpVNm8iJb5374CWtBzkT4B44NPJwXbBKqVxfjK3xgCQ+hRt9MJXBFaud\",\n            \"+Z7PSjuzigvsc3S/Yli1A4WN7c3J6NJHFqK2iUlqD2BfjK3xgCQ+hRt9MJXBFaud\"\n        ],\n        \"effects\": [\n            {\n            \"sub_type\": \"design\",\n            \"finger\": \"thumb\",\n            \"texture\": \"cream\",\n            \"reflection\": 100,\n            \"contrast\": 50,\n            \"roughness\": 0,\n            \"ref_file_index\": 0\n            },\n            {\n            \"sub_type\": \"design\",\n            \"finger\": \"index\",\n            \"texture\": \"cream\",\n            \"reflection\": 100,\n            \"contrast\": 50,\n            \"roughness\": 0,\n            \"ref_file_index\": 1\n            },\n            {\n            \"sub_type\": \"design\",\n            \"finger\": \"middle\",\n            \"texture\": \"cream\",\n            \"reflection\": 100,\n            \"contrast\": 50,\n            \"roughness\": 0,\n            \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_3_9ce2ddc47a.png\"\n            },\n            {\n            \"sub_type\": \"design\",\n            \"finger\": \"pinky\",\n            \"texture\": \"cream\",\n            \"reflection\": 100,\n            \"contrast\": 50,\n            \"roughness\": 0,\n            \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_5_f6e46dd56f.png\"\n            },\n            {\n            \"sub_type\": \"design\",\n            \"finger\": \"ring\",\n            \"texture\": \"cream\",\n            \"reflection\": 100,\n            \"contrast\": 50,\n            \"roughness\": 0,\n            \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_4_2103ca8cac.png\"\n            }\n        ]\n        }\n        ```\n\n\n3. 建立美甲 VTO 任務並輪詢結果\n\n    當您取得圖片與完整的特效內容後，即可建立任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 `success` 或 `error`。\n\n    * 建立任務端點\n\n        ```\n        POST /s2s/v2.0/task/nail-vto\n        ```\n\n    * 輪詢端點\n\n        ```\n        GET /s2s/v2.0/task/nail-vto/{task_id}\n        ```\n\n---\n\n## 檔案規格與錯誤\n\n* AI 虛擬美甲規範\n\n**支援的指甲視角**\n單張指甲圖片，正面視角清晰且無遮擋。\n\n| 項目 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 |\n| --- | --- | --- | --- |\n| 美甲設計圖片 - 指甲油 | *   271 px ≤ 寬度 ≤ 542 px<br>*   522 px ≤ 高度 ≤ 1044 px<br>*   至少 72ppi<br>圖片會從中心套用，虛擬試色效果會依使用者指甲長度而變化。 | ≤ 1MB | png |\n| 美甲設計圖片 - 穿戴式指甲 | *   271 px ≤ 寬度 ≤ 542 px<br>*   522 px ≤ 高度 ≤ 1044 px<br>*   0.5 ≤ 圖片長寬比 (H/W) ≤ 3.5<br>*   至少 72ppi<br>圖片的內容、形狀與長度設定都用於生成虛擬試色效果。<br>由於會偵測使用者指甲寬度以確保正確的圖片縮放，建議為每根指甲建立具有正確長寬比的個別圖片。<br>請下載穿戴式指甲設計圖片範例，並參考圖片指引以取得更多細節。下載：[Nail_Design_Image_Guidelines.pdf](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/You_Cam_API_AI_Nail_Virtual_Try_On_Press_on_Nail_Design_Image_Guidelines_a229b51750.pdf) | ≤ 1MB​ | png（具透明背景） |\n\n穿戴式指甲設計圖片範例：\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_press_on_nail_06_5_f6e46dd56f.png)\n\n[<img src=\"https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/youcamapi_press_on_nail_design_image_sample_de6bd64f20.png\" width=\"60\"/>](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/youcamapi_press_on_nail_design_image_sample_de6bd64f20.png)\n\n---\n\n**支援的手部視角**\n\n| 項目 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 |\n| --- | --- | --- | --- |\n| 使用者照片 | *   長邊 ≤ 2048<br>*   短邊 ≥ 256 | ≤ 10MB | jpg/jpeg/png |\n* 輸入圖片僅支援一隻手\n* 手掌面積最好至少為輸入圖片面積的一半\n* 輸入圖片的長寬比最好為 1:1、3:4、4:3\n* 手指的指甲不應被遮擋\n* 指甲上最好沒有指甲貼片與指甲油\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_nail_user_photo_02_fdba1848d6.jpg)\n\n---\n\n* 錯誤代碼\n\n| 錯誤代碼 | 說明 |\n|  ----  | ----  |\n| error_nail_too_small | 指甲區域過小。 |\n| error_no_nail\t| 來源圖片中未偵測到指甲。 |\n\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 虛擬美甲 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_eye_color_lens.yaml","link":"/zh-tw/reference/ai_eye_color_lens","routeSlug":"/zh-tw/reference/ai_eye_color_lens","label":"AI 虛擬美瞳變色片","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_eye_color_lens/section/概述","routeSlug":"/zh-tw/reference/ai_eye_color_lens/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_eye_color_lens/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_eye_color_lens/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_eye_color_lens/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_eye_color_lens/section/概述/檔案規格與錯誤"},{"type":"link","label":"JS Camera Kit","link":"/zh-tw/reference/ai_eye_color_lens/section/概述/js-camera-kit","routeSlug":"/zh-tw/reference/ai_eye_color_lens/section/概述/js-camera-kit"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_eye_color_lens/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_eye_color_lens/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_eye_color_lens/v1.0","routeSlug":"/zh-tw/reference/ai_eye_color_lens/v1.0","items":[{"label":"執行 AI 虛擬美瞳變色片任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_eye_color_lens/v1.0/paths/~1s2s~1v2.0~1task~1eye-color-vto/post","routeSlug":"/zh-tw/reference/ai_eye_color_lens/v1.0/paths/~1s2s~1v2.0~1task~1eye-color-vto/post","metadata":{"seo":{"title":"執行 AI 虛擬美瞳變色片任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/eye-color-vto"},{"label":"查詢 AI 虛擬美瞳變色片任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_eye_color_lens/v1.0/paths/~1s2s~1v2.0~1task~1eye-color-vto~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_eye_color_lens/v1.0/paths/~1s2s~1v2.0~1task~1eye-color-vto~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 虛擬美瞳變色片任務的狀態。","description":"查詢 AI 虛擬美瞳變色片任務的狀態。"}},"httpPath":"/s2s/v2.0/task/eye-color-vto/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 虛擬美瞳變色片","version":"","description":"# 概述\nAI 虛擬美瞳變色片虛擬模擬透過精準偵測虹膜、保留自然反射、精確模擬鏡片在不虹膜顏色上的不透明度與混合，並讓使用者探索從細微變化到鮮豔藍色轉變的各種色調，全部整合在單一專業級 AI API 中，提供即時且極其逼真的隱形眼鏡試戴體驗。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2022-01-25/2a348e5b-6a2b-4f08-bc54-1d16a0777e87.jpg)\n\n**隱形眼鏡虛擬模擬**\n\n使用我們的 AI 驅動虛擬試戴工具，即時改變眼色。AI 虛擬美瞳變色片透過精準偵測虹膜並套用自然、逼真的色彩調整，帶來極其逼真的結果，讓購物者無需實體樣品即可探索新風格。\n\n**極其逼真的輸出**  \n系統保留自然的眼部反射以呈現真實結果，確保每次色彩變化都栩栩如生。\n\n**進階隱形眼鏡濾鏡模擬**  \n隱形眼鏡濾鏡能精確重現不同虹膜底色下的不透明度與混合效果，讓顧客以逼真的層次與色調虛擬試戴全系列鏡片。\n\n**不僅僅是改變眼色**  \n這項技術超越了簡單的濾鏡，提供專業級的虛擬鏡片體驗，提升顧客信心並提高轉換率。\n\n---\n\n## 整合指南\n\n* 拍攝自拍\n\n    *   在適當光線下正對鏡頭。\n    *   使用 JS Camera Kit 拍攝照片。\n\n* 準備您的鏡片風格圖\n\n*   提供**一張清晰的鏡片風格圖片**：\n\n    *   格式：**PNG**（建議：已移除背景）\n    *   尺寸：**200 × 200 ≤ W × H ≤ 600 × 600**\n    *   檔案大小：**< 10 MB**\n\n    **範例：**\n\n    ![](https://d3ss46vukfdtpo.cloudfront.net/static/media/01.00ccf3ac.png)\n    ![](https://d3ss46vukfdtpo.cloudfront.net/static/media/02.c8beb3fc.png)\n\n* 透過 ***/s2s/v2.0/file*** API 取得上傳網址與檔案 ID\n\n    使用檔案 API 回應中回傳的上傳網址，上傳下列檔案：\n    *   您的自拍照片\n    *   鏡片風格圖片\n\n* 執行 AI 任務 ***/s2s/v2.0/task/eye-color-vto***\n\n    使用檔案 ID 或圖片網址作為輸入來源執行 AI 任務。依需求設定特效參數。\n\n* 輪詢任務狀態\n\n    使用回傳的 **task\\_id** 監控任務進度。  \n    輪詢 **GET /task/eye-color-vto** 以查詢引擎狀態。  \n    任務會維持在**「執行中」**狀態，直到完成。任務執行期間不會消耗點數。\n\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_9535461b-69fc-4432-b56b-2d7c4cd0bf3b_b1ef78e813.jpg)\n\n\n\n* **應用情境範例**\n\n    AI 虛擬美瞳變色片虛擬模擬改變了顧客選購彩色隱形眼鏡的方式。流程簡單直觀、具互動性，且使用者幾乎不需費力。\n\n    - 步驟 1：選擇您喜愛的顏色\n    顧客抵達您的網站並瀏覽您的商品後，即可選擇他們想試戴的色調。無論是細微的淡褐、鮮豔的綠色，或冰涼的藍色，他們都能探索多種顏色。\n\n    - 步驟 2：開啟虛擬試戴鏡頭\n    只需一點擊，虛擬試戴工具即啟動。無需複雜的設定說明或額外下載。\n\n    - 步驟 3：使用即時鏡頭或上傳照片\n    使用者可選擇即時鏡頭體驗，或上傳照片來虛擬試戴彩色隱形眼鏡。此功能以精準的準確度重現現實效果，確保他們看見每個色調在自然環境中的樣子。\n\n    ![](https://plugins-media.makeupar.com/smb/blog/post/2025-03-28/2732a9f0-9cae-4639-b765-15866550b109.jpg)\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n|類型|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 虛擬美瞳變色片虛擬模擬|自拍圖片：<br>    *   長邊 ≤ 1920 px <br>    *   短邊 ≥ 320 px <br><br>鏡片風格圖片：<br>    *   檔案格式：PNG <br>    *   解析度：200 × 200 ≤ W × H ≤ 600 × 600 px|< 10MB|jpg/png|\n\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n|error_below_min_image_size|若您的圖片寬或高小於 320 像素，尺寸過小無法使用|\n|error_face_position_invalid|您的臉部必須在圖片中完全可見，不可有任何部分被裁切|\n|error_face_position_too_small|您照片中的臉部太小，無法妥善分析|\n|error_face_position_out_of_boundary|您的臉部過大，或部分超出照片邊緣|\n|error_insufficient_lighting|光線過暗，導致難以分析|\n|error_face_angle_invalid|您的臉部角度不太正確。正面拍攝時，請讓頭部偏離直線不超過 10 度。側面拍攝時，角度應超過 15 度|\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 虛擬美瞳變色片 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_teeth_whitening.yaml","link":"/zh-tw/reference/ai_teeth_whitening","routeSlug":"/zh-tw/reference/ai_teeth_whitening","label":"AI 牙齒美白","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_teeth_whitening/section/概述","routeSlug":"/zh-tw/reference/ai_teeth_whitening/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_teeth_whitening/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_teeth_whitening/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_teeth_whitening/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_teeth_whitening/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_teeth_whitening/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_teeth_whitening/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_teeth_whitening/v1.0","routeSlug":"/zh-tw/reference/ai_teeth_whitening/v1.0","items":[{"label":"執行 AI 牙齒美白的偵測任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten~1pre-process/post","routeSlug":"/zh-tw/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten~1pre-process/post","metadata":{"seo":{"title":"執行 AI 牙齒美白的偵測任務。","description":"當來源照片可能包含超過一個有效目標，或您的整合需要明確選擇哪個被偵測到的目標接受特效時，請使用前處理任務。對於單一目標的圖片，當功能支援預設的 index 值，且您的應用程式不需要手動選擇目標時，可以跳過前處理。"}},"httpPath":"/s2s/v2.0/task/teeth-whiten/pre-process"},{"label":"查詢 AI 牙齒美白偵測任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten~1pre-process~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten~1pre-process~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 牙齒美白偵測任務的狀態。","description":"查詢 AI 牙齒美白偵測任務的狀態。"}},"httpPath":"/s2s/v2.0/task/teeth-whiten/pre-process/{task_id}"},{"label":"執行 AI 牙齒美白任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten/post","routeSlug":"/zh-tw/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten/post","metadata":{"seo":{"title":"執行 AI 牙齒美白任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/teeth-whiten"},{"label":"查詢 AI 牙齒美白任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 牙齒美白任務的狀態。","description":"查詢 AI 牙齒美白任務的狀態。"}},"httpPath":"/s2s/v2.0/task/teeth-whiten/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 牙齒美白","version":"","description":"# 概述\n**AI 牙齒美白 API**\n\nAI 牙齒美白 API 提供先進的自動化解決方案，用於提升照片中笑容的品質。透過智慧影像處理，它自然且精確地讓牙齒變亮，在數秒內創造精緻、專業的結果。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2023-07-28/f05fda4d-8ca8-4661-b4b5-135067280a10.jpg)\n\n\n\n\n**它如何移除照片中的黃牙**\n\n**智慧美白**  \nAPI 自動偵測牙齒並套用自然的外觀美白效果，不會讓影像看起來不自然。\n\n**可調整的等級**  \n內建的調整功能讓使用者控制美白的程度，從細微的變化到更明顯、適合上鏡的妝效。\n\n\n\n**主要功能**\n\n**快速簡易的增強**  \n在數秒內獲得明顯更明亮的笑容。\n\n**精準的 AI 偵測**  \n先進的偵測確保只修改牙齒，維持真實且平衡的外觀。\n\n**可調整的美白強度**  \n使用者可微調美白強度，以符合他們喜愛的風格。\n\n**以先進演算法達成的自然結果**\n\nAI 牙齒美白 API 使用精密的演算法，精準辨識牙齒並套用栩栩如生的美白效果。使用者可調整強度以達成細微、自然的改善，確保最終結果看起來真實且具視覺吸引力。\n\n---\n\n## 整合指南\n\n* 拍攝自拍\n\n    *   在適當光線下正對鏡頭。\n    *   使用 JS Camera Kit 拍攝照片。\n\n* 透過 ***/s2s/v2.0/file*** API 取得上傳網址與檔案 ID\n\n    使用檔案 API 回應中回傳的上傳網址，上傳下列檔案：\n    *   您的自拍照片\n\n* 執行 AI 任務 ***/s2s/v2.0/task/teeth-whiten***\n\n    使用檔案 ID 或圖片網址作為輸入來源執行 AI 任務。依需求設定特效參數。\n\n* 輪詢任務狀態\n\n    使用回傳的 **task\\_id** 監控任務進度。  \n    輪詢 **GET /s2s/v2.0/task/teeth-whiten/{task_id}** 以查詢引擎狀態。  \n    任務會維持在**「執行中」**狀態，直到完成。任務執行期間不會消耗點數。\n\n\n\n* **使用示範**\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2022-05-13/26c04462-d183-4392-937b-f6173ff9e814.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-07-01/webp_a4cd3779-2966-4b8f-888e-032dffc003c0.webp)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-11-13/webp_5824c85f-813e-4c14-b036-38cba206ee0b.webp)\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n|類型|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 牙齒美白|自拍圖片：<br>    *   長邊 ≤ 1920 px <br>    *   短邊 ≥ 320 px |< 10MB|jpg/png|\n\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| error_exceed_max_image_size | 若圖片較長邊超過 1920 像素 |\n|error_below_min_image_size|若您的圖片寬或高小於 320 像素，尺寸過小無法使用|\n|error_face_position_invalid|您的臉部必須在圖片中完全可見，不可有任何部分被裁切|\n|error_face_position_too_small|您照片中的臉部太小，無法妥善分析|\n|error_face_position_out_of_boundary|您的臉部過大，或部分超出照片邊緣|\n|error_insufficient_lighting|光線過暗，導致難以分析|\n|error_face_angle_invalid|您的臉部角度不太正確。正面拍攝時，請讓頭部偏離直線不超過 10 度。側面拍攝時，角度應超過 15 度|\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 牙齒美白 V1.0 | 1 |\n\n---\n"}},{"type":"separator","label":"髮型與鬍鬚造型","labelTranslationKey":"sidebar.reference.separators.hairBeard"},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_hairstyle.yaml","link":"/zh-tw/reference/ai_hairstyle","routeSlug":"/zh-tw/reference/ai_hairstyle","label":"AI 虛擬髮型","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_hairstyle/section/概述","routeSlug":"/zh-tw/reference/ai_hairstyle/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_hairstyle/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_hairstyle/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_hairstyle/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_hairstyle/section/概述/檔案規格與錯誤"},{"type":"link","label":"常見問題","link":"/zh-tw/reference/ai_hairstyle/section/概述/常見問題","routeSlug":"/zh-tw/reference/ai_hairstyle/section/概述/常見問題"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_hairstyle/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_hairstyle/section/概述/點數消耗"}]},{"type":"group","label":"V2.1","link":"/zh-tw/reference/ai_hairstyle/v2.1","routeSlug":"/zh-tw/reference/ai_hairstyle/v2.1","items":[{"label":"列出預先定義的範本 v2.1。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hairstyle/v2.1/paths/~1s2s~1v2.1~1task~1template~1hair-transfer/get","routeSlug":"/zh-tw/reference/ai_hairstyle/v2.1/paths/~1s2s~1v2.1~1task~1template~1hair-transfer/get","metadata":{"seo":{"title":"列出預先定義的範本 v2.1。","description":"列出預先定義的範本 v2.1。"}},"httpPath":"/s2s/v2.1/task/template/hair-transfer"},{"label":"執行 AI 髮型生成 v2.1 任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hairstyle/v2.1/paths/~1s2s~1v2.1~1task~1hair-transfer/post","routeSlug":"/zh-tw/reference/ai_hairstyle/v2.1/paths/~1s2s~1v2.1~1task~1hair-transfer/post","metadata":{"seo":{"title":"執行 AI 髮型生成 v2.1 任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.1/task/hair-transfer"},{"label":"查詢 AI 髮型生成 v2.1 任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hairstyle/v2.1/paths/~1s2s~1v2.1~1task~1hair-transfer~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_hairstyle/v2.1/paths/~1s2s~1v2.1~1task~1hair-transfer~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 髮型生成 v2.1 任務的狀態。","description":"查詢 AI 髮型生成 v2.1 任務的狀態。"}},"httpPath":"/s2s/v2.1/task/hair-transfer/{task_id}"}]},{"type":"group","label":"V2.0","link":"/zh-tw/reference/ai_hairstyle/v2.0","routeSlug":"/zh-tw/reference/ai_hairstyle/v2.0","items":[{"label":"執行帶參考圖片的 AI 髮型生成任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hairstyle/v2.0/paths/~1s2s~1v2.0~1task~1hair-transfer/post","routeSlug":"/zh-tw/reference/ai_hairstyle/v2.0/paths/~1s2s~1v2.0~1task~1hair-transfer/post","metadata":{"seo":{"title":"執行帶參考圖片的 AI 髮型生成任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/hair-transfer"},{"label":"查詢帶參考圖片的 AI 髮型生成任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hairstyle/v2.0/paths/~1s2s~1v2.0~1task~1hair-transfer~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_hairstyle/v2.0/paths/~1s2s~1v2.0~1task~1hair-transfer~1{task_id}/get","metadata":{"seo":{"title":"查詢帶參考圖片的 AI 髮型生成任務的狀態。","description":"查詢帶參考圖片的 AI 髮型生成任務的狀態。"}},"httpPath":"/s2s/v2.0/task/hair-transfer/{task_id}"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_hairstyle/v1.0","routeSlug":"/zh-tw/reference/ai_hairstyle/v1.0","items":[{"label":"列出預先定義的範本。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hairstyle/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-style/get","routeSlug":"/zh-tw/reference/ai_hairstyle/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-style/get","metadata":{"seo":{"title":"列出預先定義的範本。","description":"列出預先定義的範本。"}},"httpPath":"/s2s/v2.0/task/template/hair-style"},{"label":"執行 AI 髮型生成任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hairstyle/v1.0/paths/~1s2s~1v2.0~1task~1hair-style/post","routeSlug":"/zh-tw/reference/ai_hairstyle/v1.0/paths/~1s2s~1v2.0~1task~1hair-style/post","metadata":{"seo":{"title":"執行 AI 髮型生成任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/hair-style"},{"label":"查詢 AI 髮型生成任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hairstyle/v1.0/paths/~1s2s~1v2.0~1task~1hair-style~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_hairstyle/v1.0/paths/~1s2s~1v2.0~1task~1hair-style~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 髮型生成任務的狀態。","description":"查詢 AI 髮型生成任務的狀態。"}},"httpPath":"/s2s/v2.0/task/hair-style/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 虛擬髮型","version":"","description":"# 概述\n使用最新的 AI 技術嘗試多種髮型，同時滿足女性與男性，符合不同的性別與風格偏好。\n探索風格的世界：捲髮、長髮、平頭等。我們 AI 驅動的髮型變換器讓您可以輕鬆嘗試。現在就找到您的理想髮型！\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_style_v3_poster_bb1c7aad10.jpg)\n\n---\n\n## 整合指南\n\n* API Playground\n您可以使用 API Playground 測試 AI 虛擬髮型功能。這讓您可以實驗自己的想法，並更深入了解試戴流程。\n\n在此存取 API Playground：\n<https://yce.makeupar.com/api-console/en/api-playground/ai-hair-style-generator/>\n\n---\n\n* API 工作流程\n本指南將引導您完成：\n\nAI 虛擬髮型 API 的工作流程：\n\n**端點：** `/s2s/v2.1/task/hair-transfer`\n\n**需要認證：** `Authorization: Bearer YOUR_API_KEY`\n\n**工作流程步驟：**\n\n1. **圖片上傳準備：**\n   - 流程從準備自拍開始。\n\n2. **列出預先定義的範本，或使用您自己的參考照片**\n    **選擇參考來源**\n造型參考有兩種選項：\n\n| 選項 | 使用情境 | 實作建議 |\n|-------|-----------|---------------------|\n| **預先定義的範本**（`template_id`） | 快速開始（例如「捲髮短髮」、「側分瀏海」） | 呼叫 `/s2s/v2.1/task/template/hair-transfer` 並選擇 `template_id`。 |\n| **自訂參考圖片**（`ref_file_url` / `ref_file_id`） | 使用者上傳自己的風格照片，或使用提供的圖片連結 | 透過相同的檔案 API 上傳；<BR>若您的參考圖片已託管在線上，請使用 `ref_file_url`。 |\n\n3. **啟動 AI 任務並取得任務 ID：**\n   - 透過 HTTP POST 請求，將上傳的圖片與風格設定傳送到 `/s2s/v2.0/file`。\n   - 在回應中取得唯一的任務 ID，用以識別這次互動。\n\n4. **輪詢任務狀態（持續檢查）：**\n   - 使用取得的 `task_id`，透過 HTTP GET 請求（例如 `GET /task/${task_id}`）定期輪詢任務狀態。\n   - 持續監控：\n     - `Task_status = \"success\"`（流程完成）。\n     - `Task_status = \"error\"`（視情況解決或重試）。\n   - 狀態轉為成功後，相應更新工作流程。\n\n這個結構化的工作流程確保與使用者輸入的高效整合、任務的自動化監控，以及無縫取得結果。\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n    ```\n    Authorization: Bearer YOUR_API_KEY\n    ```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n---\n\n* API 使用指南\n\n本指南說明如何使用 AI 虛擬髮型 API 上傳圖片、準備參考圖片，以及建立虛擬試戴任務。\n\n***\n\n   * 步驟 1. 使用 File API 上傳檔案，或提供有效的圖片網址\n\n使用 **File API**（`/s2s/v2.0/file`）上傳目標使用者圖片。\n\n或者，若您已有公開的圖片網址，可跳過步驟 1 到 3。\n\n**圖片需求：**\n\n*   上傳高解析度的自拍照片。\n*   確保照片清楚呈現整個身體。\n*   避免有多人干擾的物件背景。\n\n**請求範例：**\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/file \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"files\": [\n      {\n        \"content_type\": \"image/jpg\",\n        \"file_name\": \"selfie_01_3dbd1b6683.jpg\",\n        \"file_size\": 547541\n      }\n    ]\n  }'\n```\n\n***\n\n   * 步驟 2. 取得 File API 回應\n\n回應包含：\n\n*   用於建立 AI 任務的 `file_id`。\n*   用於上傳實際圖片檔案的 `requests.url`。\n\n**回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"files\": [\n      {\n        \"content_type\": \"image/jpg\",\n        \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\n        \"file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n        \"requests\": [\n          {\n            \"method\": \"PUT\",\n            \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\",\n            \"headers\": {\n              \"Content-Length\": \"547541\",\n              \"Content-Type\": \"image/jpg\"\n            }\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n***\n\n   * 步驟 3. 上傳圖片到提供的網址\n\n使用 File API 回應中的 `requests.url` 上傳圖片：\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n  --header 'Content-Type: image/jpg' \\\n  --header 'Content-Length: 547541' \\\n  --data-binary @'./full_body_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n   * 步驟 4. 準備參考圖片\n\n     * 4.1 取得預先定義的圖片範本\n\n使用 **範本 API**（`/s2s/v2.1/task/template/hair-transfer`）取得預先定義的參考範本清單：\n\n```bash\ncurl --request GET \\\n  --url 'https://yce-api-01.makeupar.com/s2s/v2.1/task/template/hair-transfer?page_size=20&starting_token=73a3c9e69b89' \\\n  --header 'Authorization: Bearer YOUR_API_KEY'\n```\n\n     * 4.2 上傳參考圖片\n\n您可以：\n\n*   使用 File API（`/s2s/v2.0/file`）上傳參考圖片，或\n*   提供有效的圖片網址。\n\n**支援的圖片：**\n\n*   另一張自拍照片作為參考圖片。\n\n詳細規格請參考 **[檔案規格與錯誤](#section/overview/File-Specs-and-Errors)**。\n\n***\n\n   * 步驟 5. 建立 AI 虛擬髮型任務\n\n使用 **AI 任務 API**（`/s2s/v2.1/task/hair-transfer`）建立虛擬試戴任務。\n\n**參數：**\n\n*   使用者圖片：`src_file_id` 或 `src_file_url`。\n*   參考圖片：`ref_file_id`、`ref_file_url` 或 `template_id`。\n\n**請求範例：**\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.1/task/hair-transfer \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/selfie_03_cccd5d4803.jpeg\",\n    \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/style_reference_full_body_01_5a000d999f.png\"\n  }'\n```\n\n**回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT\"\n  }\n}\n```\n\n***\n\n   * 步驟 6. 輪詢任務結果\n\n使用任務 ID 查詢狀態：\n\n```bash\ncurl --request GET \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.1/task/hair-transfer/<YOUR_TASK_ID> \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json'\n```\n\n***\n\n   * 步驟 7. 取得結果\n\n成功的回應會包含結果圖片的下載網址：\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"error\": null,\n    \"results\": {\n      \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n    },\n    \"task_status\": \"success\"\n  }\n}\n```\n\nAPI Key 無效的錯誤回應：\n\n```json\n{\n  \"status\": 401,\n  \"error\": \"Unauthorized\",\n  \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\n應用案例：\n應用案例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_style_v1_video_08513beb46.jpg)\n\n拍攝建議：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png)\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 虛擬髮型|長邊 <= 1024，臉寬 >= 128，臉部姿勢：-10 < pitch < +10，-45 < yaw < +45，-15 < roll < +15，僅限單張臉部，需呈現完整臉部|< 10MB|jpg/jpeg|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n|error_no_shoulder\t|來源圖片中肩膀不可見\n|error_large_face_angle\t|上傳圖片的臉部角度過大\n|error_insufficient_landmarks\t|無法在來源圖片偵測足夠的臉部或身體標記點\n|error_hair_too_short\t|輸入的頭髮過短\n|error_face_pose\t|來源圖片的臉部姿勢不受支援\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 常見問題\n**問：我可以試戴自訂的髮型嗎？**\n\n**答：** 完全可以，您可以使用自己的參考照片試戴自訂髮型。AI 虛擬髮型支援兩種指定理想髮型的方法：\n\n1. **上傳您自己的參考圖片**\n   您可以透過 File API（`/s2s/v2.0/file`）上傳高解析度的自拍或風格照片（例如展示目標髮型的人）。上傳後，在建立 AI 任務時，使用回傳的 `file_id` 或公開網址作為參考來源。\n\n2. **提供有效的圖片網址**\n   若您的參考圖片已託管在線上（例如在您自己的伺服器或 CDN 上），您可以直接在請求內容的 `ref_file_url` 欄位提供其 HTTPS 網址。\n\n透過 `/s2s/v2.1/task/hair-transfer` 提交任務時，請包含以下其中之一：\n- `src_file_id`（您的自拍）與 `ref_file_id`（您的自訂參考圖片），\n或\n- `src_file_url` 與 `ref_file_url`。\n\n請確保兩張圖片都符合指定的需求：\n- 支援的格式：僅限 JPG/JPEG\n- 檔案大小低於 10 MB\n- 長邊 ≤ 1024 像素\n- 臉寬 ≥ 128 像素\n- 頭部姿勢在允許範圍內（pitch：−10° 到 +10°，yaw：−45° 到 +45°，roll：−15° 到 +15°）\n- 可見單張臉部，完整正面視角且頭髮清晰可見\n\n這種彈性讓您可以從照片參考套用幾乎任何髮型，而不僅限於預先定義的範本。\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 虛擬髮型 V2.0 | 預設模式 1 點 <br> 自訂模式 2 點 |\n| AI 虛擬髮型 V2.1 | 預設模式 2 點 <br> 自訂模式 2 點 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_hair_color.yaml","link":"/zh-tw/reference/ai_hair_color","routeSlug":"/zh-tw/reference/ai_hair_color","label":"AI 虛擬染髮","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_hair_color/section/概述","routeSlug":"/zh-tw/reference/ai_hair_color/section/概述","items":[{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_hair_color/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_hair_color/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_hair_color/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_hair_color/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_hair_color/v1.0","routeSlug":"/zh-tw/reference/ai_hair_color/v1.0","items":[{"label":"執行染髮任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hair_color/v1.0/paths/~1s2s~1v2.0~1task~1hair-color/post","routeSlug":"/zh-tw/reference/ai_hair_color/v1.0/paths/~1s2s~1v2.0~1task~1hair-color/post","metadata":{"seo":{"title":"執行染髮任務。","description":"這個端點啟動染髮流程。您必須提供來源檔案（透過網址或檔案 ID），並指定色彩設定（preset、pattern 或 palettes）。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/hair-color"},{"label":"查詢染髮任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hair_color/v1.0/paths/~1s2s~1v2.0~1task~1hair-color~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_hair_color/v1.0/paths/~1s2s~1v2.0~1task~1hair-color~1{task_id}/get","metadata":{"seo":{"title":"查詢染髮任務的狀態。","description":"查詢染髮任務的狀態。"}},"httpPath":"/s2s/v2.0/task/hair-color/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 虛擬染髮","version":"","description":"# 概述\n用我們的染髮工具探索多種髮色！嘗試您一直夢寐以求的髮色，並實驗從未試過的新色調。輕鬆用滑桿調整您所選顏色的強度，打造客製化的外觀。\n\n   * 上傳您的圖片\n\n上傳您想改變髮色的照片。\n\n   * 選擇預設顏色，或以圖樣與調色盤自訂\n\n從預先定義的顏色預設中選擇，或透過調整漸層覆蓋與混合進行微調，創造無限可能！\n\n> **警告：** 若同時指定 preset 與 pattern + palettes，preset 將優先。\n\n> **警告：** 您的來源圖片必須包含要染色的頭髮區域，請在套用前再次確認。請確保來源圖片包含您想染的頭髮區域——正確與否由您負責。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_color_s2_poster_dt_v2_49198cabc0.png)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/01_1_1_8365c3b503.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/01_2_1_abfcdb7eba.jpg)\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 虛擬染髮|長邊 < 1920，臉寬 >= 100|< 10MB|jpg/jpeg/png|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n|error_below_min_image_size|來源圖片尺寸小於最小值（期望：寬 >= 320px，高 >= 320px）\n|error_exceed_max_image_size|來源圖片尺寸大於最大值（期望：寬 < 1920px，高 < 1080px）\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 虛擬染髮 V1.0 | 全染模式 1 點 <br> 漸層模式 1 點 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_hair_extension.yaml","link":"/zh-tw/reference/ai_hair_extension","routeSlug":"/zh-tw/reference/ai_hair_extension","label":"AI 虛擬接髮","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_hair_extension/section/概述","routeSlug":"/zh-tw/reference/ai_hair_extension/section/概述","items":[{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_hair_extension/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_hair_extension/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_hair_extension/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_hair_extension/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_hair_extension/v1.0","routeSlug":"/zh-tw/reference/ai_hair_extension/v1.0","items":[{"label":"列出預先定義的範本。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hair_extension/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-ext/get","routeSlug":"/zh-tw/reference/ai_hair_extension/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-ext/get","metadata":{"seo":{"title":"列出預先定義的範本。","description":"列出預先定義的範本。"}},"httpPath":"/s2s/v2.0/task/template/hair-ext"},{"label":"執行 AI 虛擬接髮任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hair_extension/v1.0/paths/~1s2s~1v2.0~1task~1hair-ext/post","routeSlug":"/zh-tw/reference/ai_hair_extension/v1.0/paths/~1s2s~1v2.0~1task~1hair-ext/post","metadata":{"seo":{"title":"執行 AI 虛擬接髮任務。","description":"這個端點使用範本與來源照片啟動接髮生成流程。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/hair-ext"},{"label":"查詢 AI 虛擬接髮任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hair_extension/v1.0/paths/~1s2s~1v2.0~1task~1hair-ext~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_hair_extension/v1.0/paths/~1s2s~1v2.0~1task~1hair-ext~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 虛擬接髮任務的狀態。","description":"查詢 AI 虛擬接髮任務的狀態。"}},"httpPath":"/s2s/v2.0/task/hair-ext/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 虛擬接髮","version":"","description":"# 概述\n用 AI 找到最適合您的接髮搭配​\n從您的裝置上舒適地嘗試各種長度——從長到超長——風格、顏色與瀏海。不再需要猜測——透過先進的生成式 AI，精確看見每種接髮風格在您身上的樣子。在決定新造型前做出明智的造型選擇。​\n透過先進的接髮試戴，它能與您目前的髮長自然混合，正是嘗試超長風格的最佳時機。\n\n應用案例：\n![AI Hair Extension](https://bcw-media.s3.ap-northeast-1.amazonaws.com/YCE_web_Hair_Extension_Filter_S2_img_07_098b6e08c4.jpg \"AI 虛擬接髮\")\n\n![AI Hair Extension](https://bcw-media.s3.ap-northeast-1.amazonaws.com/YCE_web_Hair_Extension_Filter_S1_img_01_eab88fe3e2.jpg \"AI 虛擬接髮\")\n\n拍攝建議：\n![拍攝建議](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png \"拍攝建議\")\n\n---\n\n## 檔案規格與錯誤\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 虛擬接髮|長邊 <= 1024，臉寬 >= 128，臉部姿勢：-10 < pitch < +10，-45 < yaw < +45，-15 < roll < +15，僅限單張臉部，需呈現完整臉部|< 10MB|jpg/jpeg|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n|error_no_shoulder\t|來源圖片中肩膀不可見\n|error_large_face_angle\t|上傳圖片的臉部角度過大\n|error_insufficient_landmarks\t|無法在來源圖片偵測足夠的臉部或身體標記點\n|error_hair_too_short\t|輸入的頭髮過短\n|error_face_pose\t|來源圖片的臉部姿勢不受支援\n|error_bald_image\t|輸入的髮型為禿頭\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 虛擬接髮 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_bangs.yaml","link":"/zh-tw/reference/ai_bangs","routeSlug":"/zh-tw/reference/ai_bangs","label":"AI 虛擬瀏海","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_bangs/section/概述","routeSlug":"/zh-tw/reference/ai_bangs/section/概述","items":[{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_bangs/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_bangs/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_bangs/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_bangs/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_bangs/v1.0","routeSlug":"/zh-tw/reference/ai_bangs/v1.0","items":[{"label":"列出預先定義的範本。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_bangs/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-bang/get","routeSlug":"/zh-tw/reference/ai_bangs/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-bang/get","metadata":{"seo":{"title":"列出預先定義的範本。","description":"列出預先定義的範本。"}},"httpPath":"/s2s/v2.0/task/template/hair-bang"},{"label":"執行 AI 瀏海生成任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_bangs/v1.0/paths/~1s2s~1v2.0~1task~1hair-bang/post","routeSlug":"/zh-tw/reference/ai_bangs/v1.0/paths/~1s2s~1v2.0~1task~1hair-bang/post","metadata":{"seo":{"title":"執行 AI 瀏海生成任務。","description":"這個端點使用範本與來源照片啟動瀏海生成流程。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/hair-bang"},{"label":"查詢 AI 瀏海生成任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_bangs/v1.0/paths/~1s2s~1v2.0~1task~1hair-bang~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_bangs/v1.0/paths/~1s2s~1v2.0~1task~1hair-bang~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 瀏海生成任務的狀態。","description":"查詢 AI 瀏海生成任務的狀態。"}},"httpPath":"/s2s/v2.0/task/hair-bang/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 虛擬瀏海","version":"","description":"# 概述\n用 AI 試出您完美的瀏海\n逼真的外觀：嘗試逼真的瀏海，發現最適合您臉型的風格。​\n多元的造型選擇：探索多種瀏海風格，適合各種個性與場合。​\n輕鬆的體驗：享受易用的介面，讓嘗試新瀏海變得簡單有趣​。\n\n想看到更多瀏海風格？請參考 https://yce.makeupar.com/bangs-filter。\n\n應用案例：\n\n![AI Hair Bang Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_style_v1_video_1200x674px_1_259f619dfd.png \"AI 虛擬瀏海\")\n\n![AI Hair Bang Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_style_v1_video_1200x674px_2_7146754733.png \"AI 虛擬瀏海\")\n\n\n拍攝建議：\n![拍攝建議](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png \"拍攝建議\")\n\n---\n\n## 檔案規格與錯誤\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 虛擬瀏海|長邊 <= 1024，臉寬 >= 128，臉部姿勢：-10 < pitch < +10，-45 < yaw < +45，-15 < roll < +15，僅限單張臉部，需呈現完整臉部|< 10MB|jpg/jpeg/png|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n|error_no_shoulder\t|來源圖片中肩膀不可見\n|error_large_face_angle\t|上傳圖片的臉部角度過大\n|error_insufficient_landmarks\t|無法在來源圖片偵測足夠的臉部或身體標記點\n|error_hair_too_short\t|輸入的頭髮過短\n|error_face_pose\t|來源圖片的臉部姿勢不受支援\n|error_bald_image\t|輸入的髮型為禿頭\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 虛擬瀏海 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_hair_volume.yaml","link":"/zh-tw/reference/ai_hair_volume","routeSlug":"/zh-tw/reference/ai_hair_volume","label":"AI 髮量模擬","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_hair_volume/section/概述","routeSlug":"/zh-tw/reference/ai_hair_volume/section/概述","items":[{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_hair_volume/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_hair_volume/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_hair_volume/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_hair_volume/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_hair_volume/v1.0","routeSlug":"/zh-tw/reference/ai_hair_volume/v1.0","items":[{"label":"列出預先定義的範本。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hair_volume/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-vol/get","routeSlug":"/zh-tw/reference/ai_hair_volume/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-vol/get","metadata":{"seo":{"title":"列出預先定義的範本。","description":"列出預先定義的範本。"}},"httpPath":"/s2s/v2.0/task/template/hair-vol"},{"label":"執行 AI 髮量模擬生成任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hair_volume/v1.0/paths/~1s2s~1v2.0~1task~1hair-vol/post","routeSlug":"/zh-tw/reference/ai_hair_volume/v1.0/paths/~1s2s~1v2.0~1task~1hair-vol/post","metadata":{"seo":{"title":"執行 AI 髮量模擬生成任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/hair-vol"},{"label":"查詢 AI 髮量模擬生成任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hair_volume/v1.0/paths/~1s2s~1v2.0~1task~1hair-vol~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_hair_volume/v1.0/paths/~1s2s~1v2.0~1task~1hair-vol~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 髮量模擬生成任務的狀態。","description":"查詢 AI 髮量模擬生成任務的狀態。"}},"httpPath":"/s2s/v2.0/task/hair-vol/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 髮量模擬","version":"","description":"# 概述\n立即讓您的外觀更出色，擁有更豐盈、更蓬鬆的頭髮！​\n為細髮或稀疏的頭髮增添自然的蓬度。用 AI 無縫填補空隙或增加髮量。適用於所有髮質：直髮、捲髮、細髮。最適合交友檔案、履歷等。\n我們的 AI 工具幫助您在所有照片中達到完美的髮量與密度，無論是個人、專業或社群用途。告別照片中糟糕的頭髮日，每次都以清新蓬鬆的頭髮亮相。\n\n應用案例：\n![AI Hair Volume Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/YCE_web_Hair_Volume_Filter_S4_img_01_836436ca00.jpg \"AI 髮量模擬\")\n\n![AI Hair Volume Generator](https://plugins-media.makeupar.com/smb/blog/post/2024-08-26/51eadc51-aaa7-4ebc-ac78-e389be5e16b0.jpg \"AI 髮量模擬\")\n\n拍攝建議：\n![拍攝建議](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png \"拍攝建議\")\n\n---\n\n## 檔案規格與錯誤\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 髮量模擬|長邊 <= 1024，臉寬 >= 128，臉部姿勢：-10 < pitch < +10，-45 < yaw < +45，-15 < roll < +15，僅限單張臉部，需呈現完整臉部|< 10MB|jpg/jpeg/png|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n|error_no_shoulder\t|來源圖片中肩膀不可見\n|error_large_face_angle\t|上傳圖片的臉部角度過大\n|error_insufficient_landmarks\t|無法在來源圖片偵測足夠的臉部或身體標記點\n|error_hair_too_short\t|輸入的頭髮過短\n|error_face_pose\t|來源圖片的臉部姿勢不受支援\n|error_bald_image\t|輸入的髮型為禿頭\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 髮量模擬 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_wavy_hair.yaml","link":"/zh-tw/reference/ai_wavy_hair","routeSlug":"/zh-tw/reference/ai_wavy_hair","label":"AI 波浪捲髮模擬","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_wavy_hair/section/概述","routeSlug":"/zh-tw/reference/ai_wavy_hair/section/概述","items":[{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_wavy_hair/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_wavy_hair/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_wavy_hair/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_wavy_hair/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_wavy_hair/v1.0","routeSlug":"/zh-tw/reference/ai_wavy_hair/v1.0","items":[{"label":"列出預先定義的範本。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_wavy_hair/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-curl/get","routeSlug":"/zh-tw/reference/ai_wavy_hair/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-curl/get","metadata":{"seo":{"title":"列出預先定義的範本。","description":"列出預先定義的範本。"}},"httpPath":"/s2s/v2.0/task/template/hair-curl"},{"label":"執行 AI 波浪捲髮模擬任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_wavy_hair/v1.0/paths/~1s2s~1v2.0~1task~1hair-curl/post","routeSlug":"/zh-tw/reference/ai_wavy_hair/v1.0/paths/~1s2s~1v2.0~1task~1hair-curl/post","metadata":{"seo":{"title":"執行 AI 波浪捲髮模擬任務。","description":"查詢任務狀態請參考輪詢指南。"}},"httpPath":"/s2s/v2.0/task/hair-curl"},{"label":"查詢 AI 波浪捲髮模擬任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_wavy_hair/v1.0/paths/~1s2s~1v2.0~1task~1hair-curl~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_wavy_hair/v1.0/paths/~1s2s~1v2.0~1task~1hair-curl~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 波浪捲髮模擬任務的狀態。","description":"查詢 AI 波浪捲髮模擬任務的狀態。"}},"httpPath":"/s2s/v2.0/task/hair-curl/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 波浪捲髮模擬","version":"","description":"# 概述\n無論您夢想的是富有彈性的捲圈、鬆弛的波浪，或大膽的捲髮宣言，YouCam API 的捲髮濾鏡讓您在數秒內嘗試全新出色的髮型——全部在家就能完成。\n\n無論您嘗試柔和的波浪或大膽的非洲捲，YouCam 都提供與眾不同的精準度與真實感。它是您在下次前往沙龍前，自信探索新髮型的理想工具。\n\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-04-01/webp_03963789-fb1e-4ad8-be4d-48932e247376.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-03-20/b25b228a-259b-4efb-a7c1-31d200b62e8c.jpg)\n\n拍攝建議：\n![拍攝建議](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png \"拍攝建議\")\n\n---\n\n## 檔案規格與錯誤\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 波浪捲髮模擬|長邊 <= 1024，臉寬 >= 128，臉部姿勢：-10 < pitch < +10，-45 < yaw < +45，-15 < roll < +15，僅限單張臉部，需呈現完整臉部|< 10MB|jpg/jpeg/png|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n|error_no_shoulder\t|來源圖片中肩膀不可見\n|error_large_face_angle\t|上傳圖片的臉部角度過大\n|error_insufficient_landmarks\t|無法在來源圖片偵測足夠的臉部或身體標記點\n|error_hair_too_short\t|輸入的頭髮過短\n|error_face_pose\t|來源圖片的臉部姿勢不受支援\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 波浪捲髮模擬 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_beard_style.yaml","link":"/zh-tw/reference/ai_beard_style","routeSlug":"/zh-tw/reference/ai_beard_style","label":"AI 虛擬鬍鬚造型","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_beard_style/section/概述","routeSlug":"/zh-tw/reference/ai_beard_style/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_beard_style/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_beard_style/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_beard_style/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_beard_style/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_beard_style/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_beard_style/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_beard_style/v1.0","routeSlug":"/zh-tw/reference/ai_beard_style/v1.0","items":[{"label":"列出預先定義的範本。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1template~1beard-style/get","routeSlug":"/zh-tw/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1template~1beard-style/get","metadata":{"seo":{"title":"列出預先定義的範本。","description":"列出預先定義的範本。"}},"httpPath":"/s2s/v2.0/task/template/beard-style"},{"label":"執行 AI 虛擬鬍鬚造型任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1beard-style/post","routeSlug":"/zh-tw/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1beard-style/post","metadata":{"seo":{"title":"執行 AI 虛擬鬍鬚造型任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/beard-style"},{"label":"查詢 AI 虛擬鬍鬚造型任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1beard-style~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1beard-style~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 虛擬鬍鬚造型任務的狀態。","description":"查詢 AI 虛擬鬍鬚造型任務的狀態。"}},"httpPath":"/s2s/v2.0/task/beard-style/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 虛擬鬍鬚造型","version":"","description":"# 概述\n男士鬍型生成的 AI 模擬\n\nAI 演算法也賦能男性完全自由地，以高度精緻的鬍型模擬技術虛擬嘗試不同的鬍型，包括整齊短鬍、短鬚、全鬍、圓鬍、八字鬍、山羊鬍等。\n\n購物者也能看見前後結果，無需承擔動刀的承諾。\n鬍型濾鏡包括八字鬍、短方鬍、鴨尾鬍、圓鬍等十余種。\n\n## 整合指南\n\n1. **上傳自拍**\n  您可以透過兩種方式之一提供來源圖片：\n\n  - **使用現有的公開圖片網址**\n    無需上傳，您可以在啟動 AI 任務時直接提供可公開存取的圖片網址。\n\n  - **透過 File API 上傳**\n    使用端點：\n    ```\n    POST /s2s/v2.0/file\n    ```\n    這會回傳用於後續任務執行的 `file_id`。\n\n    - ***重要***：僅呼叫 File API 並不會上傳您的檔案。您必須**手動上傳**檔案到**File API 回應中提供的網址**。該網址就是您的上傳目的地，請確保檔案成功傳輸到該處後再繼續。<br></br>\n    在呼叫 AI API 之前，請確保您的檔案已成功上傳。使用 File API 取得上傳網址，然後將檔案上傳到該位置。上傳完成後，您會在回應中取得 ***file_id***，這個 ID 就是您用於存取該檔案相關 AI 功能的依據。\n\n      > **警告：** 請注意，若您未將檔案上傳到 File API 回應中提供的網址，使用 AI API 時會得到 500 Server Error / unknown_internal_error 或 404 Not Found 錯誤。\n\n2.  **列出預先定義的風格**\n    *   使用 /s2s/v2.0/task/template/beard-style 取得預先定義的範本清單，並選擇 ``template_id`` 執行 AI 任務。\n\n3.  **執行 AI 任務以取得任務 ID**\n    使用 /s2s/v2.0/task/beard-style 執行 AI 任務。對於目標使用者圖片，提供 ``src_file_url`` 或 ``src_file_id``。並提供要套用的 ``template_id`` 以取得 ``task_id``。\n\n4.  **輪詢以查詢任務狀態直到成功或失敗**\n    使用 ``task_id``，透過輪詢 GET /s2s/v2.0/task/beard-style 監控任務狀態，以取得目前的引擎狀態。在引擎完成任務之前，狀態會維持為 running，此階段不會消耗點數。\n    您也可以實作 webhook，在 AI 任務成功或失敗時接收通知。細節請參考 **[Webhook](../../../develop/webhook)** 章節。\n\n    > **警告：** 必須在任務的保留期間內輪詢以查詢任務狀態。若在保留期間內沒有輪詢請求，任務將會逾時，即使任務已成功處理。您的點數仍會被消耗。\n\n    > **警告：** 若您查詢已逾時任務的狀態，會收到 InvalidTaskId 錯誤。因此，執行 AI 任務後，您必須在保留期間內輪詢以查詢狀態，直到狀態變為 success 或 error。\n\n5.  **成功後取得 AI 任務的結果**\n    引擎處理您的輸入檔案並生成結果影像後，任務狀態會變為 success。您會取得處理後圖片的網址。\n\n---\n\n## 檔案規格與錯誤\n   * 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 虛擬鬍鬚造型|解析度：長邊 < 1024 <br>臉寬 > 256 <br>臉部姿勢：-30 < yaw < 30, <br>僅限單張臉部, <br>需呈現完整臉部|< 10MB|jpg/jpeg|\n\n   * 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n|error_no_face\t|來源圖片中臉部不可見\n|error_src_face_too_small\t|臉部過小\n|error_inference\t|鬍型移除錯誤或鬍型生成錯誤\n|error_face_pose\t|來源圖片的臉部姿勢不受支援\n\n   * 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 虛擬鬍鬚造型 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_hair_type_detection.yaml","link":"/zh-tw/reference/ai_hair_type_detection","routeSlug":"/zh-tw/reference/ai_hair_type_detection","label":"AI 髮質檢測","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_hair_type_detection/section/概述","routeSlug":"/zh-tw/reference/ai_hair_type_detection/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_hair_type_detection/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_hair_type_detection/section/概述/整合指南"},{"type":"link","label":"髮質類型分類","link":"/zh-tw/reference/ai_hair_type_detection/section/概述/髮質類型分類","routeSlug":"/zh-tw/reference/ai_hair_type_detection/section/概述/髮質類型分類"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_hair_type_detection/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_hair_type_detection/section/概述/檔案規格與錯誤"},{"type":"link","label":"JS Camera Kit","link":"/zh-tw/reference/ai_hair_type_detection/section/概述/js-camera-kit","routeSlug":"/zh-tw/reference/ai_hair_type_detection/section/概述/js-camera-kit"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_hair_type_detection/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_hair_type_detection/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_hair_type_detection/v1.0","routeSlug":"/zh-tw/reference/ai_hair_type_detection/v1.0","items":[{"label":"執行髮質類型偵測任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hair_type_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-type-detection/post","routeSlug":"/zh-tw/reference/ai_hair_type_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-type-detection/post","metadata":{"seo":{"title":"執行髮質類型偵測任務。","description":"查詢任務狀態請參考輪詢指南。"}},"httpPath":"/s2s/v2.0/task/hair-type-detection"},{"label":"查詢髮質類型偵測任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hair_type_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-type-detection~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_hair_type_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-type-detection~1{task_id}/get","metadata":{"seo":{"title":"查詢髮質類型偵測任務的狀態。","description":"查詢髮質類型偵測任務的狀態。"}},"httpPath":"/s2s/v2.0/task/hair-type-detection/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 髮質檢測","version":"","description":"# 概述\n想像您的口袋裡有一位 AI 頭髮專家。我們的技術深入分析您頭髮的質地、厚度與捲曲模式，從十種獨特的捲曲形狀中挑選，並歸類為九種明確的類型，從 Straight（直髮）到 Super Kinky（極度捲曲）。您會獲得完整的頭髮檔案，品牌也能運用這些洞察，為您提供精準的產品推薦與建議。\n\n## 整合指南\n* 如何為 AI 髮質檢測拍攝照片\n* 從左側、正面、右側拍攝 3 張照片。\n  - 只需快速拍攝三張自拍。一張正對前方，一張向左轉約 45 度，一張向右轉 45 度。我們要從各角度捕捉您頭髮的完整外觀。請確保每張照片中，您的整張臉與頭髮的上緣都清晰可見。您的臉部應佔圖片寬度的約 50% 到 80%。不要太遠，也不要太近。這樣才足夠清晰供分析。拍攝側面照片時，請像說「不」一樣左右轉動頭部（這稱為 yaw 旋轉）。保持頭部水平，不要上下或左右傾斜。請避免背面或俯視角度，因為那些角度無法使用。\n  - 您可以使用 JS Camera Kit 拍攝照片。請確保頭髮未綁起，讓它垂在胸前。向右轉頭並保持靜止，再向左轉，取得 3 張待分析的照片。\n\n* 如何用 AI 偵測髮質類型\n* 使用 ***/s2s/v2.0/file*** API，請上傳以下資產：\n  - 正面、右側與左側的照片。\n\n* 執行 AI 任務 ***/s2s/v2.0/task/hair-type-detection*** </br>\n傳送三張圖片執行髮質類型偵測任務：一張正面、一張右側、一張左側。使用它們的檔案 ID 作為 AI 的來源輸入。\n\n* 輪詢以查詢任務狀態直到成功或錯誤</br>\n這個 ***task_id*** 用於透過輪詢 GET 'task/hair-type-detection' 監控任務狀態，以取得目前的引擎狀態。在引擎完成任務之前，狀態會維持為 'running'，此階段不會消耗點數。\n\n## 髮質類型分類\n|類別|縮略圖|髮質類型分類|說明|\n|  ----  | ----  | ----  | ----  |\n|1|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t1.b19d4657.jpg)|Straight（直髮）| 此髮質類型的特徵是髮絲缺乏自然捲曲，通常從髮根到髮梢直直垂下|\n|2A|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t2A.351ef0a6.jpg)|Slight Wavy（微波浪）| 此髮質類型具有細微、細緻的波浪，質地平滑且略帶凌亂感，但髮根缺乏蓬度|\n|2B|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t2B.daac62f4.jpg)|Medium Wavy（中等波浪）| 此髮質類型展現自然的 S 形波浪，通常從髮桿中段開始，細緻地貼合頭部，創造細膩而精緻的層次|\n|2C|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t2C.10ef2132.jpg)|Thick Wavy（厚波浪）| 此髮質類型的波浪質地較粗，形狀如字母「S」，從髮根開始並沿頭髮長度向下延伸。此髮質容易毛躁|\n|3A|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t3A.073b6767.jpg)|Loose Curls（鬆散捲曲）| 這些捲曲大而放鬆、富有彈性，從髮根到髮梢都有明顯的光澤|\n|3B|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t3B.06bf109b.jpg)|Medium Curls（中等捲曲）| 此髮質類型由粗而富有彈性的圓圈狀捲曲組成，容易毛躁|\n|3C|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t3C.9091ea1e.jpg)|緊密捲曲| 這些捲曲具有密集緊實的開瓶器形形狀，帶來充足的蓬度|\n|4A|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t4A.cf742771.jpg)|Kinky Soft（柔軟極捲）| 此髮質類型的特徵是緊密排列、富有彈性的 S 形螺旋|\n|4B|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t4B.4a6300fe.jpg)|Coily（螺旋髮）| 密集排列的螺旋緊密纏繞成銳利的鋸齒角度|\n|4C|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t4C.4ed5a7f8.jpg)|極度螺旋| 此髮質類型的特徵是緊密蓬鬆的螺旋，較容易斷裂|\n\n* 結果參數\n* mapping：結果為字串，顯示偵測到的髮質類型類別。以下以陣列列出所有可能的結果字串：\n  ```json\n  [\"1 to 2a\", \"2a to 2b\", \"2b to 2c\", \"2c to 3a\", \"3a to 3b\", \"3b to 3c\", \"3c to 4a\", \"4a to 4b\", \"4b to 4c\"]\n  ```\n* term：髮質類型類別與其分類之間一比一對應的字串。以下以陣列列出所有可能的結果字串：\n  ```json\n  [\"Straight to Slight Wavy\", \"Slight to Medium Wavy\", \"Medium to Thick Wavy\", \"Thick Wavy to Loose Curls\", \"Loose to Medium Curls\", \"Medium to Tight Curls\", \"Tight Curls to Kinky Soft\", \"Kinky Soft to Coily\", \"Coily to Extremely Coily\"]\n  ```\n\n* 拍攝建議\n![拍攝建議](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Hair%20Type%20Detection_how%20to%20shoot.png \"拍攝建議\")\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Skin%20Analysis_camera.png)\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n|類型|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 髮質檢測|圖片寬與高必須至少 320 像素，且任一維度不得超過 4096 像素。若您的圖片其中一邊超過 1080 像素，會自動調整尺寸至該限制內以進行分析。|< 10MB|jpg/png|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n|error_mismatch_image_size|請確保您所有的臉部照片（正面、左側、右側）尺寸相同|\n|error_below_min_image_size|若您的圖片寬或高小於 320 像素，尺寸過小無法使用|\n|error_face_position_invalid|您的臉部必須在圖片中完全可見，不可有任何部分被裁切|\n|error_face_position_too_small|您照片中的臉部太小，無法妥善分析|\n|error_face_position_out_of_boundary|您的臉部過大，或部分超出照片邊緣|\n|error_insufficient_lighting|光線過暗，導致難以分析|\n|error_face_angle_invalid|您的臉部角度不太正確。正面拍攝時，請讓頭部偏離直線不超過 10 度。側面拍攝時，角度應超過 15 度|\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 髮質檢測 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_hair_length_detection.yaml","link":"/zh-tw/reference/ai_hair_length_detection","routeSlug":"/zh-tw/reference/ai_hair_length_detection","label":"AI 頭髮長度分析","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_hair_length_detection/section/概述","routeSlug":"/zh-tw/reference/ai_hair_length_detection/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_hair_length_detection/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_hair_length_detection/section/概述/整合指南"},{"type":"link","label":"髮長分類","link":"/zh-tw/reference/ai_hair_length_detection/section/概述/髮長分類","routeSlug":"/zh-tw/reference/ai_hair_length_detection/section/概述/髮長分類"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_hair_length_detection/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_hair_length_detection/section/概述/檔案規格與錯誤"},{"type":"link","label":"JS Camera Kit","link":"/zh-tw/reference/ai_hair_length_detection/section/概述/js-camera-kit","routeSlug":"/zh-tw/reference/ai_hair_length_detection/section/概述/js-camera-kit"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_hair_length_detection/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_hair_length_detection/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_hair_length_detection/v1.0","routeSlug":"/zh-tw/reference/ai_hair_length_detection/v1.0","items":[{"label":"執行髮長偵測任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hair_length_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-length-detection/post","routeSlug":"/zh-tw/reference/ai_hair_length_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-length-detection/post","metadata":{"seo":{"title":"執行髮長偵測任務。","description":"查詢任務狀態請參考輪詢指南。"}},"httpPath":"/s2s/v2.0/task/hair-length-detection"},{"label":"查詢髮長偵測任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hair_length_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-length-detection~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_hair_length_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-length-detection~1{task_id}/get","metadata":{"seo":{"title":"查詢髮長偵測任務的狀態。","description":"查詢髮長偵測任務的狀態。"}},"httpPath":"/s2s/v2.0/task/hair-length-detection/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 頭髮長度分析","version":"","description":"# 概述\nAI 頭髮長度分析為護膚品牌與沙龍提供快速分析與測量髮長的解決方案，讓個人化產品與服務做出明智的決策。\n我們的 AI 經過大量多元圖片資料集的嚴謹訓練，確保精準可靠的髮長偵測。透過分析數千張各種髮質與風格的圖片，它以卓越準確度精準辨識並分類五種不同的髮長，從耳上到背部中段。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_length_S1_01_enu_b03bd393af.jpg)\n\n## 整合指南\n* 如何為 AI 頭髮長度分析拍攝照片\n* 正面自拍\n  - 只需一張清晰的照片，直視鏡頭。讓頭髮放下垂於胸前，並確保直視前方，取得正面視角。\n  - 或者，使用 JS Camera Kit 拍照。只需讓頭髮放下垂於胸前，不要綁起。\n\n* 如何用 AI 偵測髮長\n* 使用 ***/s2s/v2.0/file*** API，請上傳以下資產：\n  - 您的自拍照片。\n\n* 執行 AI 任務 ***/s2s/v2.0/task/hair-length-detection*** </br>\n傳送一張正面自拍圖片來執行髮長偵測任務。使用其檔案 ID 作為 AI 的來源輸入。\n\n* 輪詢以查詢任務狀態直到成功或錯誤</br>\n這個 ***task_id*** 用於透過輪詢 GET 'task/hair-length-detection' 監控任務狀態，以取得目前的引擎狀態。在引擎完成任務之前，狀態會維持為 'running'，此階段不會消耗點數。\n\n## 髮長分類\n|縮略圖|髮長分類|說明|\n| ----  | ----  | ----  |\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_above_the_ears.b41525da.png)|耳上長度|頭髮剛好落在耳朵上方，呈現流線時尚的外觀，完美修飾臉型。|\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_ear_length.0740b805.png)|耳長|頭髮長度達到耳垂，提供時尚且多變、易於維護的造型。|\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_short_hair.d7f24ddb.png)|短髮|頭髮剪在肩膀以上，最適合清新現代的造型，既大膽又易於打理。|\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_above_chest.1b624c17.png)|中長|頭髮落在鎖骨周圍，提供均衡的造型，最適合盤髮與鬆弛波浪。|\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_longer_hair.7fbcc9d0.png)|長髮|散發優雅氣質的長髮，提供經典外觀與多種造型選擇。|\n\n* 結果參數\n* term：結果為字串，顯示偵測到的髮長類型。以下以陣列列出所有可能的結果字串：\n  ```json\n  [\"above the ears\", \"ear length\", \"ear length or longer\", \"short hair\", \"short hair or longer\", \"above chest\", \"above chest or longer\", \"long hair\"]\n  ```\n\n* 拍攝建議\n![拍攝建議](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Hair%20Length%20Detection_how%20to%20shoot.png \"拍攝建議\")\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Skin%20Analysis_camera.png)\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n|類型|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 頭髮長度分析|圖片寬與高必須至少 320 像素，且任一維度不得超過 4096 像素。若您的圖片其中一邊超過 1080 像素，會自動調整尺寸至該限制內以進行分析。|< 10MB|jpg/png|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n|error_below_min_image_size|若您的圖片寬或高小於 320 像素，尺寸過小無法使用|\n|error_face_position_invalid|您的臉部必須在圖片中完全可見，不可有任何部分被裁切|\n|error_face_position_too_small|您照片中的臉部太小，無法妥善分析|\n|error_face_position_out_of_boundary|您的臉部過大，或部分超出照片邊緣|\n|error_insufficient_lighting|光線過暗，導致難以分析|\n|error_face_angle_invalid|您的臉部角度不太正確。正面拍攝時，請讓頭部偏離直線不超過 10 度。側面拍攝時，角度應超過 15 度|\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 頭髮長度分析 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_hair_frizziness_detection.yaml","link":"/zh-tw/reference/ai_hair_frizziness_detection","routeSlug":"/zh-tw/reference/ai_hair_frizziness_detection","label":"AI 毛躁髮質分析","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_hair_frizziness_detection/section/概述","routeSlug":"/zh-tw/reference/ai_hair_frizziness_detection/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_hair_frizziness_detection/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_hair_frizziness_detection/section/概述/整合指南"},{"type":"link","label":"輸入與輸出","link":"/zh-tw/reference/ai_hair_frizziness_detection/section/概述/輸入與輸出","routeSlug":"/zh-tw/reference/ai_hair_frizziness_detection/section/概述/輸入與輸出"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_hair_frizziness_detection/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_hair_frizziness_detection/section/概述/檔案規格與錯誤"},{"type":"link","label":"JS Camera Kit","link":"/zh-tw/reference/ai_hair_frizziness_detection/section/概述/js-camera-kit","routeSlug":"/zh-tw/reference/ai_hair_frizziness_detection/section/概述/js-camera-kit"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_hair_frizziness_detection/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_hair_frizziness_detection/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_hair_frizziness_detection/v1.0","routeSlug":"/zh-tw/reference/ai_hair_frizziness_detection/v1.0","items":[{"label":"執行髮絲毛躁度偵測任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hair_frizziness_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-frizziness-detection/post","routeSlug":"/zh-tw/reference/ai_hair_frizziness_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-frizziness-detection/post","metadata":{"seo":{"title":"執行髮絲毛躁度偵測任務。","description":"查詢任務狀態請參考輪詢指南。"}},"httpPath":"/s2s/v2.0/task/hair-frizziness-detection"},{"label":"查詢髮絲毛躁度偵測任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hair_frizziness_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-frizziness-detection~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_hair_frizziness_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-frizziness-detection~1{task_id}/get","metadata":{"seo":{"title":"查詢髮絲毛躁度偵測任務的狀態。","description":"查詢髮絲毛躁度偵測任務的狀態。"}},"httpPath":"/s2s/v2.0/task/hair-frizziness-detection/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 毛躁髮質分析","version":"","description":"# 概述\n僅用 3 張照片進行 180° 全視角髮絲毛躁度分析\n\n我們的 AI 毛躁髮質分析只需上傳 3 張照片——頭髮的正面、左側與右側視角——即可在數秒內提供精準的髮絲毛躁度分析。\n\n這高效的流程在數秒內提供準確結果，讓企業能依據髮絲毛躁度提供客製化的頭髮解決方案與抗毛躁產品，無需耗時的面對面諮詢、複雜的頭髮測驗，或專用硬體安裝。\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_frizzy_S_02_enu_b80c238858.jpg)\n\n## 整合指南\n\n1. **上傳自拍**\n  您可以透過兩種方式之一提供來源圖片：\n\n  - **使用現有的公開圖片網址**\n    無需上傳，您可以在啟動 AI 任務時直接提供可公開存取的圖片網址。\n\n  - **透過 File API 上傳**\n    使用端點：\n    ```\n    POST /s2s/v2.0/file\n    ```\n    這會回傳用於後續任務執行的 `file_id`。\n\n    - ***重要***：僅呼叫 File API 並不會上傳您的檔案。您必須**手動上傳**檔案到**File API 回應中提供的網址**。該網址就是您的上傳目的地，請確保檔案成功傳輸到該處後再繼續。\n\n    在呼叫 AI API 之前，請確保您的檔案已成功上傳。使用 File API 取得上傳網址，然後將檔案上傳到該位置。上傳完成後，您會在回應中取得 ***file_id***，這個 ID 就是您用於存取該檔案相關 AI 功能的依據。\n\n      > **警告：** 請注意，若您未將檔案上傳到 File API 回應中提供的網址，使用 AI API 時會得到 500 Server Error / unknown_internal_error 或 404 Not Found 錯誤。\n\n2.  **執行 AI 任務以取得任務 ID**\n    使用 /s2s/v2.0/task/hair-frizziness-detection 執行 AI 任務。對於目標使用者圖片，提供 ``src_file_url`` 或 ``src_file_id``。並提供要套用的 ``template_id`` 以取得 ``task_id``。\n\n3.  **輪詢以查詢任務狀態直到成功或失敗**\n    使用 ``task_id``，透過輪詢 GET /s2s/v2.0/task/hair-frizziness-detection 監控任務狀態，以取得目前的引擎狀態。在引擎完成任務之前，狀態會維持為 running，此階段不會消耗點數。\n    您也可以實作 webhook，在 AI 任務成功或失敗時接收通知。細節請參考 **[Webhook](../../../../develop/webhook)** 章節。\n\n    > **警告：** 必須在任務的保留期間內輪詢以查詢任務狀態。若在保留期間內沒有輪詢請求，任務將會逾時，即使任務已成功處理。您的點數仍會被消耗。\n\n    > **警告：** 若您查詢已逾時任務的狀態，會收到 InvalidTaskId 錯誤。因此，執行 AI 任務後，您必須在保留期間內輪詢以查詢狀態，直到狀態變為 success 或 error。\n\n4.  **成功後取得 AI 任務的結果**\n    引擎處理您的輸入檔案並生成結果影像後，任務狀態會變為 success。您會取得處理後圖片的網址。\n\n## 輸入與輸出\n* 輸入格式\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_frizzy_step_01_ac5c651ea4.png)\n上傳 3 張照片——頭髮的正面、左側與右側視角。\n您可以使用 JS Camera Kit 實作 JavaScript 攝影模組，拍攝 3 張合格的照片。\n\n\n* 輸出格式\nAI 毛躁髮質分析評估髮質類型，並辨識 4 種不同的髮絲毛躁程度——從平滑頭髮到極度毛躁的頭髮，提供關於髮絲毛躁狀況的精準洞察。\n\n| **對應（0–3）** | **術語**            | **說明**                                           |\n| ----------------- | ------------------- | --------------------------------------------------------- |\n| 0             | 不毛躁      | 頭髮看起來平滑，幾乎或完全沒有可見的毛躁。     |\n| 1            | 輕微毛躁 | 可見輕微毛躁；表面質地有輕微的不規則。 |\n| 2             | 毛躁         | 頭髮各處有明顯毛躁；質地明顯紊亂。   |\n| 3             | 極度毛躁  | 強烈且廣泛的毛躁；頭髮質地高度不規則。  |\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_frizzy_S_01_enu_fcd10905ff.jpg)\n\n* 輸出範例\n```json\n{\n  \"mapping\": 1, // number；結果對應的鍵，選項：[0, 1, 2, 3]\n  \"term\": \"Slightly Frizzy\" // string；與 \"mapping\" 一一對應，選項：[\"Not Frizzy\", \"Slightly Frizzy\", \"Frizzy\", \"Extreme Frizzy\"]\n}\n```\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n|類型|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 毛躁髮質分析|圖片寬與高至少 320 像素，任一維度不超過 4096 像素。若您的圖片其中一邊超過 1080 像素，會自動調整尺寸以符合該限制進行分析。|< 10MB|jpg/png|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n|error_mismatch_image_size|請確保您所有的臉部照片（正面、左側、右側）尺寸相同|\n|error_below_min_image_size|若您的圖片寬或高小於 320 像素，尺寸過小無法使用|\n|error_face_position_invalid|您的臉部必須在圖片中完全可見，不可有任何部分被裁切|\n|error_face_position_too_small|您照片中的臉部太小，無法妥善分析|\n|error_face_position_out_of_boundary|您的臉部過大，或部分超出照片邊緣|\n|error_insufficient_lighting|光線過暗，導致難以分析|\n|error_face_angle_invalid|您的臉部角度不太正確。正面拍攝時，請讓頭部偏離直線不超過 10 度。側面拍攝時，角度應超過 15 度|\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 毛躁髮質分析 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_hair_density_detection.yaml","link":"/zh-tw/reference/ai_hair_density_detection","routeSlug":"/zh-tw/reference/ai_hair_density_detection","label":"AI 頭髮密度分析","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_hair_density_detection/section/概述","routeSlug":"/zh-tw/reference/ai_hair_density_detection/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_hair_density_detection/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_hair_density_detection/section/概述/整合指南"},{"type":"link","label":"髮量密度分級","link":"/zh-tw/reference/ai_hair_density_detection/section/概述/髮量密度分級","routeSlug":"/zh-tw/reference/ai_hair_density_detection/section/概述/髮量密度分級"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_hair_density_detection/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_hair_density_detection/section/概述/檔案規格與錯誤"},{"type":"link","label":"JS Camera Kit","link":"/zh-tw/reference/ai_hair_density_detection/section/概述/js-camera-kit","routeSlug":"/zh-tw/reference/ai_hair_density_detection/section/概述/js-camera-kit"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_hair_density_detection/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_hair_density_detection/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_hair_density_detection/v1.0","routeSlug":"/zh-tw/reference/ai_hair_density_detection/v1.0","items":[{"label":"執行 AI 頭髮密度分析任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hair_density_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-density-detection/post","routeSlug":"/zh-tw/reference/ai_hair_density_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-density-detection/post","metadata":{"seo":{"title":"執行 AI 頭髮密度分析任務。","description":"必須輪詢以檢查任務狀態。細節請參考輪詢指南。"}},"httpPath":"/s2s/v2.0/task/hair-density-detection"},{"label":"查詢 AI 頭髮密度分析任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hair_density_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-density-detection~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_hair_density_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-density-detection~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 頭髮密度分析任務的狀態。","description":"查詢 AI 頭髮密度分析任務的狀態。"}},"httpPath":"/s2s/v2.0/task/hair-density-detection/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 頭髮密度分析","version":"","description":"# 概述\nAI 頭髮密度分析提供快速、專業、以照片為基礎的評估，透過評估頭皮可見度與頭髮分布模式，將髮量密度精準分為四個等級，提供源自毛髮鏡的洞察而無需實體工具，並賦能企業僅從單張上傳的圖片，大規模提供專家級的個人化服務。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_hair_density_S3_02_b34f2db2ce.jpg)\n\n## 整合指南\n* 如何為 AI 頭髮密度分析拍攝照片\n* 自拍\n  - 請在適當光線下正對鏡頭，然後將頭低下至 45 度角。保持頭髮未綁起，並確保您的整條髮際線清晰可見。\n\n  ![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_popup_step_animated_02.aadf7a34.png)\n\n  - 或者，使用 JS Camera Kit 拍照。\n\n* 如何用 AI 偵測髮量密度\n* 使用 ***/s2s/v2.0/file*** API，請上傳以下資產：\n  - 您的自拍照片。\n\n* 執行 AI 任務 ***/s2s/v2.0/task/hair-density-detection*** </br>\n傳送一張正面、低頭 45 度的自拍圖片來執行偵測任務。使用其檔案 ID 作為 AI 的來源輸入。\n\n* 輪詢以查詢任務狀態直到成功或錯誤</br>\n這個 ***task_id*** 用於透過輪詢 GET 'task/hair-density-detection' 監控任務狀態，以取得目前的引擎狀態。在引擎完成任務之前，狀態會維持為 'running'，此階段不會消耗點數。\n\n\n## 髮量密度分級\n\n|縮略圖|髮量密度分級|說明|\n| ----  | ----  | ----  |\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/dt_classification_LV01.5097a6c2.png)|等級 1<br>極低密度|頭髮明顯稀疏，大面積可見頭皮。髮絲細薄且覆蓋極少。|\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/dt_classification_LV02.7966983d.png)|等級 2<br>低密度|明顯稀疏，頭皮清晰可見，尤其是頭頂與分線處。頭髮可能缺乏蓬度與支撐感。|\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/dt_classification_LV03.c49dbfb7.png)|等級 3<br>中等密度|在直射光下頭皮部分可見，但頭髮仍維持適度的蓬度與覆蓋。頭髮可能感覺較細，但相對健康。|\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/dt_classification_LV04.e467f2aa.png)|等級 4<br>高密度|頭髮看起來豐厚濃密，頭皮幾乎不可見。髮絲緊密排列，提供豐盈的蓬度與自然的覆蓋。|\n\n\n* 拍攝建議\n\n![拍攝建議](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/icon_S2_step1_20d0a161da.png \"拍攝建議\")\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_hair_density_S1_02_f60369b14d.jpg)\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n|類型|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 頭髮密度分析|圖片寬與高至少 100 像素，任一維度不超過 4096 像素。若您的圖片其中一邊超過 1080 像素，會自動調整尺寸以符合該限制進行分析。|< 10MB|jpg/png|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n|error_below_min_image_size|若您的圖片寬度或高度小於 100 像素，則太小無法使用|\n|error_face_position_invalid|您的臉部必須在圖片中完全可見，不可有任何部分被裁切|\n|error_face_position_too_small|您照片中的臉部太小，無法妥善分析|\n|error_face_position_out_of_boundary|您的臉部過大，或部分超出照片邊緣|\n|error_insufficient_lighting|光線過暗，導致難以分析|\n|error_face_angle_invalid|您的臉部角度不太正確。正面拍攝時，請讓頭部偏離直線不超過 10 度。側面拍攝時，角度應超過 15 度|\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 頭髮密度分析 V1.0 | 1 |\n\n---\n"}},{"type":"separator","label":"服飾","labelTranslationKey":"sidebar.reference.separators.fashion"},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_clothes.yaml","link":"/zh-tw/reference/ai_clothes","routeSlug":"/zh-tw/reference/ai_clothes","label":"AI 虛擬換裝","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_clothes/section/概述","routeSlug":"/zh-tw/reference/ai_clothes/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_clothes/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_clothes/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_clothes/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_clothes/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_clothes/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_clothes/section/概述/點數消耗"}]},{"type":"group","label":"V4.0","link":"/zh-tw/reference/ai_clothes/v4.0","routeSlug":"/zh-tw/reference/ai_clothes/v4.0","items":[{"label":"執行 AI 虛擬換裝 V4 任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_clothes/v4.0/paths/~1s2s~1v2.0~1task~1cloth-v4/post","routeSlug":"/zh-tw/reference/ai_clothes/v4.0/paths/~1s2s~1v2.0~1task~1cloth-v4/post","metadata":{"seo":{"title":"執行 AI 虛擬換裝 V4 任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/cloth-v4"},{"label":"查詢 AI 虛擬換裝 V4 任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_clothes/v4.0/paths/~1s2s~1v2.0~1task~1cloth-v4~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_clothes/v4.0/paths/~1s2s~1v2.0~1task~1cloth-v4~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 虛擬換裝 V4 任務的狀態。","description":"查詢 AI 虛擬換裝 V4 任務的狀態。"}},"httpPath":"/s2s/v2.0/task/cloth-v4/{task_id}"}]},{"type":"group","label":"V3.0","link":"/zh-tw/reference/ai_clothes/v3.0","routeSlug":"/zh-tw/reference/ai_clothes/v3.0","items":[{"label":"執行 AI 虛擬換裝 V3 任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_clothes/v3.0/paths/~1s2s~1v2.0~1task~1cloth-v3/post","routeSlug":"/zh-tw/reference/ai_clothes/v3.0/paths/~1s2s~1v2.0~1task~1cloth-v3/post","metadata":{"seo":{"title":"執行 AI 虛擬換裝 V3 任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/cloth-v3"},{"label":"查詢 AI 虛擬換裝 V3 任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_clothes/v3.0/paths/~1s2s~1v2.0~1task~1cloth-v3~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_clothes/v3.0/paths/~1s2s~1v2.0~1task~1cloth-v3~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 虛擬換裝 V3 任務的狀態。","description":"查詢 AI 虛擬換裝 V3 任務的狀態。"}},"httpPath":"/s2s/v2.0/task/cloth-v3/{task_id}"}]},{"type":"group","label":"V2.0","link":"/zh-tw/reference/ai_clothes/v2.0","routeSlug":"/zh-tw/reference/ai_clothes/v2.0","items":[{"label":"列出預先定義的範本。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1template~1cloth/get","routeSlug":"/zh-tw/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1template~1cloth/get","metadata":{"seo":{"title":"列出預先定義的範本。","description":"列出預先定義的範本。"}},"httpPath":"/s2s/v2.0/task/template/cloth"},{"label":"執行 AI 虛擬換裝任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1cloth/post","routeSlug":"/zh-tw/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1cloth/post","metadata":{"seo":{"title":"執行 AI 虛擬換裝任務。","description":"這個端點啟動服飾虛擬試穿流程。您可以使用範本 ID，或提供參考圖片（來源與參考檔案）。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/cloth"},{"label":"查詢 AI 虛擬換裝任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1cloth~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1cloth~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 虛擬換裝任務的狀態。","description":"查詢 AI 虛擬換裝任務的狀態。"}},"httpPath":"/s2s/v2.0/task/cloth/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 虛擬換裝","version":"","description":"# 概述\nAI 虛擬換裝是虛擬試衣間，讓使用者無需實際穿著即可試穿服裝。運用 AI 與照片編輯技術，這些應用將穿搭疊加到您的圖片上，讓你看見不同風格與合身度在您身形上的樣子。非常適合線上購物、風格靈感，或單純玩味時尚想法。用 AI 虛擬換裝服裝。上傳任何服飾參考，與您的照片交換穿搭，即刻完成虛擬衣櫃的轉換。\n\n---\n\n## 整合指南\n\n* API Playground\n您可以使用 API Playground 測試 AI 虛擬換裝功能。這讓您可以實驗自己的想法，並更深入了解試穿流程。\n\n在此存取 API Playground：\n<https://yce.makeupar.com/api-console/en/api-playground/ai-clothes/>\n\n---\n\n* AI 虛擬換裝 API 使用指南\n\n本指南說明如何使用 AI 虛擬換裝 API 上傳圖片、準備參考穿搭，以及建立虛擬試穿任務。\n\n***\n\n   * 步驟 1. 使用 File API 上傳檔案\n\n使用 **File API**（`/s2s/v2.0/file`）上傳目標使用者圖片。\n\n**圖片需求：**\n\n*   上傳高解析度的全身照片。\n*   確保照片清楚呈現整個身體。\n*   避免有多人干擾的物件背景。\n\n**請求範例：**\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/file \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"files\": [\n {\n   \"content_type\": \"image/jpg\",\n   \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\n   \"file_size\": 547541\n }\n    ]\n  }'\n```\n\n***\n\n   * 步驟 2. 取得 File API 回應\n\n回應包含：\n\n*   用於建立 AI 任務的 `file_id`。\n*   用於上傳實際圖片檔案的 `requests.url`。\n\n**回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"files\": [\n {\n   \"content_type\": \"image/jpg\",\n   \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\n   \"file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n   \"requests\": [\n {\n  \"method\": \"PUT\",\n  \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\",\n  \"headers\": {\n    \"Content-Length\": \"547541\",\n    \"Content-Type\": \"image/jpg\"\n  }\n }\n   ]\n }\n    ]\n  }\n}\n```\n\n***\n\n   * 步驟 3. 上傳圖片到提供的網址\n\n使用 File API 回應中的 `requests.url` 上傳圖片：\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n  --header 'Content-Type: image/jpg' \\\n  --header 'Content-Length: 547541' \\\n  --data-binary @'./full_body_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n   * 步驟 4. 準備參考穿搭\n\n * 4.1 上傳參考穿搭圖片\n\n您可以：\n\n*   使用 File API（`/s2s/v2.0/file`）上傳穿搭圖片，或\n*   提供有效的圖片網址。\n\n**支援的穿搭圖片：**\n\n*   服裝的產品圖片。\n*   全身照片作為穿搭參考。\n\n詳細規格請參考 **[檔案規格與錯誤](#section/overview/File-Specs-and-Errors)**。\n\n***\n\n   * 步驟 5. 建立 AI 任務\n\n使用 **AI 任務 API**（`/s2s/v2.0/task/cloth-v4`）建立虛擬試穿任務。\n\n**參數：**\n\n*   使用者圖片：`src_file_id` 或 `src_file_url`。\n*   穿搭圖片：`ref_file_id`、`ref_file_url` 或 `template_id`。\n\n**請求範例：**\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/cloth-v4 \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/clothes_03_cccd5d4803.jpeg\",\n    \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/clothes_reference_full_body_01_5a000d999f.png\",\n    \"garment_category\": \"full_body\"\n  }'\n```\n\n**回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT\"\n  }\n}\n```\n\n***\n\n   * 步驟 6. 輪詢任務結果\n\n使用任務 ID 查詢狀態：\n\n```bash\ncurl --request GET \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/cloth-v4/<YOUR_TASK_ID> \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json'\n```\n\n***\n\n   * 步驟 7. 取得結果\n\n成功的回應會包含結果圖片的下載網址：\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"error\": null,\n    \"results\": {\n \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n    },\n    \"task_status\": \"success\"\n  }\n}\n```\n\nAPI Key 無效的錯誤回應：\n\n```json\n{\n  \"status\": 401,\n  \"error\": \"Unauthorized\",\n  \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\n應用案例：\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-05-08/b80f4ae1-c905-4ec0-b491-e42c15e65575.gif)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/01%20ai%20clothes%20changer.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2023-12-01/45f451aa-4b4f-466d-9da7-4538573c92af.jpg)\n\n拍攝建議：\n![拍攝建議](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI-Cloth-Guideline.png \"拍攝建議\")\n\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n|類型|支援的尺寸|支援的檔案大小|支援的格式|\n|  ---- | ---- | ---- | ---- |\n|目標使用者圖片|建議 1024×768，最小 512×384，最大邊 4096 px。</br></br> - 僅限單人。</br> - 為達到最佳結果，人物應佔畫面至少 80%。</br> - 圖片應僅包含上半身，從胸部往上。無需呈現腹部，但肩膀應可見。</br> - 臉部必須完全可見，無遮擋。</br> - 身體必須面向前方並採站姿（不可坐著或蹲著）。 |< 10MB|jpg/png|\n|服裝參考圖片 |建議 1024×768，最小 512×384，最大邊 4096 px。</br></br> - 若使用真人服裝照片作為參考</br>&nbsp;&nbsp;&nbsp;- 必須僅包含一人。</br>&nbsp;&nbsp;&nbsp;- 可見的服裝區域必須完整覆蓋預期的試穿區域。</br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;- 範例：全身試穿時，半身服裝圖片不可接受。</br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;- 範例：下半身試穿時，部分褲子不可接受。</br>&nbsp;&nbsp;&nbsp;- 服裝不得被嚴重遮擋（例如被長髮或手臂覆蓋）。</br>&nbsp;&nbsp;&nbsp;- 臉部必須完全可見，無遮擋。</br>&nbsp;&nbsp;&nbsp;- 身體必須面向前方並採站姿（不可坐著或蹲著）。 </br></br> - 若使用產品圖片作為參考</br>&nbsp;&nbsp;&nbsp;- 必須是單一服飾的正面產品照。</br>&nbsp;&nbsp;&nbsp;- 不要使用合成圖片（例如上下裝在同一張照片）。</br>&nbsp;&nbsp;&nbsp;- 下半身僅支援實際穿著的穿搭，不支援獨立的產品圖片。|< 10MB|jpg/png|\n\n* 錯誤代碼\n\n* 錯誤代碼（前處理）\n\n| 錯誤代碼 | 說明 |\n| ---------- | ----------- |\n| exceed_max_filesize | SRC 或 REF 圖片過大。長邊不得超過 4096 像素。 |\n| error_below_min_image_size | SRC 或 REF 圖片過小。長邊至少需 128 像素。 |\n| error_pose | 無法從上傳的人物 SRC 圖片偵測姿勢。 |\n| error_invalid_ref | REF 圖片無效，例如為空，或主體未完全可見。 |\n| error_apply_region_mismatch | SRC 圖片的套用區域與 REF 圖片不符，因此無法套用任何編輯。 |\n| error_invalid_src | 當來源圖片僅顯示下半身或僅顯示腳部時。 |\n\n* 錯誤代碼（引擎）\n\n| 錯誤代碼 | 說明 |\n| ---------- | ----------- |\n| invalid_parameter | - 服飾類別無效。 <br> - Style_id 不在 inference_style_list 中。 <br> - src_keys、dst_keys 或 acts 無效。 <br> - ref_keys 或 template_ref_image 無效。 <br> - 必須提供其中恰好一項。 |\n| error_download_image | 無法下載 SRC 或 REF 圖片。 |\n| exceed_max_filesize | SRC 或 REF 圖片過大。檔案大小不得超過 10 MB。 |\n| error_nsfw_content_detected | 在結果圖片中偵測到潛在的 NSFW 內容。 |\n| error_editing_failed | 編輯過程失敗，因為結果圖片與來源圖片過於相似。 |\n| unknown_internal_error | - 載入模型失敗。 <br> - 排程演算法類型無效。 <br> - 未載入引擎。 <br> - 檔案不在上傳結果中。 |\n| error_multi_person | 在「normal」或「strict」多人篩選設定下，系統在來源或參考圖片中偵測到多人。 |\n\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 虛擬換裝 V2.0 | 2 |\n| AI 虛擬換裝 V3.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_hat.yaml","link":"/zh-tw/reference/ai_hat","routeSlug":"/zh-tw/reference/ai_hat","label":"AI 虛擬帽子","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_hat/section/概述","routeSlug":"/zh-tw/reference/ai_hat/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_hat/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_hat/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_hat/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_hat/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_hat/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_hat/section/概述/點數消耗"}]},{"type":"group","label":"V2.0","link":"/zh-tw/reference/ai_hat/v2.0","routeSlug":"/zh-tw/reference/ai_hat/v2.0","items":[{"label":"執行 AI 帽子任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hat/v2.0/paths/~1s2s~1v2.0~1task~1hat/post","routeSlug":"/zh-tw/reference/ai_hat/v2.0/paths/~1s2s~1v2.0~1task~1hat/post","metadata":{"seo":{"title":"執行 AI 帽子任務。","description":"這個端點啟動帽子虛擬試戴流程。您必須提供來源檔案、參考檔案（網址或 ID），並指定性別與風格參數。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/hat"},{"label":"查詢 AI 帽子任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_hat/v2.0/paths/~1s2s~1v2.0~1task~1hat~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_hat/v2.0/paths/~1s2s~1v2.0~1task~1hat~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 帽子任務的狀態。","description":"查詢 AI 帽子任務的狀態。"}},"httpPath":"/s2s/v2.0/task/hat/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 虛擬帽子","version":"","description":"# 概述\n透過我們由尖端 AI 技術驅動的極其逼真 AR 頭飾試戴，步入時尚的未來。這創新的解決方案將線上購物轉變為沉浸式體驗，讓顧客以無與倫比的精準度與真實感虛擬試戴頭飾。\n從即時的風格發現到栩栩如生的視覺呈現，我們的 AR 技術確保每頂帽子與髮帶看起來與感覺都真實。幫助購物者在購買前找到完美的尺寸與風格。提升互動、增強信心，並重新定義顧客與您產品互動的方式。\n\n## 整合指南\n本指南將引導您完成：\n\n*   **端點：** `/s2s/v2.0/task/hat`\n*   **認證：** 所有請求都需要 `Authorization: Bearer YOUR_API_KEY`\n*   **工作流程：**\n    1.  **準備自拍圖片：** 上傳圖片，或提供您本人的有效圖片網址作為虛擬試戴目標。\n    1.  **準備帽子圖片：** 上傳帽子產品圖片，或戴帽子的人物照片。\n    1.  **選擇風格與性別：** 選擇您偏好的風格，以及您希望呈現的性別。\n    1.  **啟動 AI 任務並取得任務 ID：** 從回應中取得 `task_id`。\n    1.  **輪詢狀態（`GET`）：** 使用 `task_id` 查詢任務狀態。持續輪詢，直到 `task_status` 為 `\"success\"` 或 `\"error\"`。\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n---\n\n* AI 帽子 API 使用指南\n\n本指南說明如何使用 AI 帽子 API 上傳圖片、準備參考帽子，以及建立虛擬試戴任務。\n\n***\n\n   * 步驟 1. 準備自拍圖片\n\n您可以：\n*   使用 File API（`/s2s/v2.0/file`）上傳自拍圖片，或\n*   提供有效的圖片網址。\n\n     * 步驟 1.1 使用 File API 上傳檔案\n\n使用 **File API**（`/s2s/v2.0/file`）上傳目標使用者圖片。\n\n**圖片需求：**\n\n*   上傳一張自拍照片。\n*   確保照片清楚呈現上半身。\n*   避免有多人干擾的物件背景。\n\n**請求範例：**\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/file \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"files\": [\n      {\n        \"content_type\": \"image/jpg\",\n        \"file_name\": \"selfie_photo_01_3dbd1b6683.jpg\",\n        \"file_size\": 547541\n      }\n    ]\n  }'\n```\n\n***\n\n     * 步驟 1.2. 取得 File API 回應\n\n回應包含：\n\n*   用於建立 AI 任務的 `file_id`。\n*   用於上傳實際圖片檔案的 `requests.url`。\n\n**回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"files\": [\n      {\n        \"content_type\": \"image/jpg\",\n        \"file_name\": \"selfie_photo_01_3dbd1b6683.jpg\",\n        \"file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n        \"requests\": [\n          {\n            \"method\": \"PUT\",\n            \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\",\n            \"headers\": {\n              \"Content-Length\": \"547541\",\n              \"Content-Type\": \"image/jpg\"\n            }\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n***\n\n     * 步驟 1.3. 上傳圖片到提供的網址\n\n使用 File API 回應中的 `requests.url` 上傳圖片：\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n  --header 'Content-Type: image/jpg' \\\n  --header 'Content-Length: 547541' \\\n  --data-binary @'./selfie_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n   * 步驟 2. 準備參考帽子圖片\n\n您可以：\n\n*   使用 File API（`/s2s/v2.0/file`）上傳帽子圖片，或\n*   提供有效的圖片網址。\n\n**支援的帽子圖片：**\n\n*   帽子產品圖片。\n*   戴帽子的人物照片。\n\n詳細規格請參考 **[檔案規格與錯誤](#section/overview/File-Specs-and-Errors)**。\n\n***\n\n   * 步驟 3. 建立 AI 任務\n\n選擇您偏好的風格，以及您希望呈現的性別。\n使用 **AI 任務 API**（`/s2s/v2.0/task/hat`）建立虛擬試戴任務。\n\n**參數：**\n\n*   使用者圖片：`src_file_id` 或 `src_file_url`。\n*   帽子圖片：`ref_file_id` 或 `ref_file_url`。\n\n**請求範例：**\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/hat \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"src_file_url\": \"https://example.com/selfie.jpg\",\n    \"ref_file_url\": \"https://example.com/accessory.jpg\",\n    \"gender\": \"female\",\n    \"style\": \"random\"\n}'\n```\n\n**回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT\"\n  }\n}\n```\n\n***\n\n   * 步驟 4. 輪詢任務結果\n\n使用任務 ID 查詢狀態：\n\n```bash\ncurl --request GET \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/hat/SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json'\n```\n\n***\n\n   * 步驟 5. 取得結果\n\n成功的回應會包含結果圖片的下載網址：\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"error\": null,\n    \"results\": {\n      \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n    },\n    \"task_status\": \"success\"\n  }\n}\n```\n\nAPI Key 無效的錯誤回應：\n\n```json\n{\n  \"status\": 401,\n  \"error\": \"Unauthorized\",\n  \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\n## 檔案規格與錯誤\n\n* AI 虛擬帽子規範\n\n   * 圖片需求\n\n| 類型   | 最低解析度 | 備註 |\n| ------ | ------------------ | ----- |\n| 自拍 | 512 × 512 | 臉部可見，建議頭到胸 |\n| 帽子  | 512 × 512（產品）<br>800 × 800（佩戴） | 清晰、無遮擋的帽子視角 |\n\n**支援的帽子圖片**\n\n* 產品圖片需求\n    * 最低解析度：512 × 512 像素\n    * 每張圖片僅限一個產品\n    * 產品應覆蓋圖片高度的 25% 以上\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/026_thumb_dca334af3c.jpg)\n\n* 佩戴圖片需求\n    * 最低解析度：800 × 800 像素\n    * 單件物品要求：模特必須佩戴恰好一件物品。不可有多件物品或配件。\n    * 覆蓋比例：佩戴的物品必須佔整體圖片高度的 20% 以上。這確保物品在畫面中清晰可見且突出。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/010_thumb_51490eebeb.jpg)\n\n**支援的自拍視角**\n\n* 建議圖片解析度：至少 512 × 512 像素。\n* 建議臉部覆蓋範圍：超過圖片高度的 15%。\n* 單人主體要求：圖片必須包含恰好一位人物主體。不可有額外人物或局部身影。\n* 臉部可見性：主體的臉部必須完全可見且無遮擋。頭髮、配件或物件不應覆蓋關鍵臉部特徵。\n* 構圖：圖片至少需包含半身頭像，涵蓋從頭頂到胸部區域。為獲得最佳分析效果，建議使用半身照（頭到腰）。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/lashana_lynch_thumb_7a900b811e.jpg)\n\n**試戴風格**\n\n* 共有五種預先定義的風格用於生成虛擬試戴輸出：\"style_sporty_casual\"、\"style_urban_fashion\"、\"style_vacation_casual\"、\"style_warm_cozy\" 與 \"style_bohemian\"。您可以在建立 AI 任務時指定此風格參數，或讓系統預設隨機選擇風格。\n\n![style_vacation_casual](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/5f42385b_6aef_44cd_b576_2ec10e31305d_824cc2019b.jpg)\n\n---\n\n* 支援的格式與尺寸\n\n| AI 功能 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 |\n|  ----  | ----  | ----  | ----  |\n| AI 虛擬帽子 | 輸入：長邊 <= 4096 <br>輸出：896 x 1152 | < 10MB | jpg/jpeg/png/heic |\n\n* 錯誤代碼\n\n| 錯誤代碼 | 說明 |\n| ------------------------------ | -------------------------------------------- |\n| error\\_download\\_image         | 下載來源或參考圖片失敗 |\n| error\\_inference               | 推論流程錯誤                     |\n| error\\_no\\_face                | 來源圖片未偵測到臉部             |\n| error\\_nsfw\\_content\\_detected | 在結果中偵測到 NSFW 內容         |\n| exceed\\_max\\_filesize          | 檔案大小超過 10 MB               |\n| invalid\\_parameter             | 性別或風格值無效                 |\n| unknown\\_internal\\_error       | 其他內部錯誤                     |\n\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jquery >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 虛擬帽子 V2.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_scarf.yaml","link":"/zh-tw/reference/ai_scarf","routeSlug":"/zh-tw/reference/ai_scarf","label":"AI 虛擬試圍巾","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_scarf/section/概述","routeSlug":"/zh-tw/reference/ai_scarf/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_scarf/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_scarf/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_scarf/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_scarf/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_scarf/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_scarf/section/概述/點數消耗"}]},{"type":"group","label":"V2.0","link":"/zh-tw/reference/ai_scarf/v2.0","routeSlug":"/zh-tw/reference/ai_scarf/v2.0","items":[{"label":"執行 AI 虛擬試圍巾任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_scarf/v2.0/paths/~1s2s~1v2.0~1task~1scarf/post","routeSlug":"/zh-tw/reference/ai_scarf/v2.0/paths/~1s2s~1v2.0~1task~1scarf/post","metadata":{"seo":{"title":"執行 AI 虛擬試圍巾任務。","description":"這個端點啟動圍巾虛擬試戴流程。您必須提供來源檔案、參考檔案（網址或 ID），並指定性別與風格參數。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/scarf"},{"label":"查詢 AI 虛擬試圍巾任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_scarf/v2.0/paths/~1s2s~1v2.0~1task~1scarf~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_scarf/v2.0/paths/~1s2s~1v2.0~1task~1scarf~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 虛擬試圍巾任務的狀態。","description":"查詢 AI 虛擬試圍巾任務的狀態。"}},"httpPath":"/s2s/v2.0/task/scarf/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 虛擬試圍巾","version":"","description":"# 概述\n透過線上 AR 圍巾虛擬試戴，提升您的時尚體驗。購物者可即刻將圍巾披掛在穿搭上，看見圖案在現實中的流動感。\n這互動式的虛擬圍巾功能讓顧客在線上探索不同風格與顏色，重現店內購物體驗。由高傳真 AR 模擬驅動，使用者隨時隨地都能享受細緻的圍巾視覺化。\n\n## 整合指南\n本指南將引導您完成：\n\n*   **端點：** `/s2s/v2.0/task/scarf`\n*   **認證：** 所有請求都需要 `Authorization: Bearer YOUR_API_KEY`\n*   **工作流程：**\n    1.  **準備自拍圖片：** 上傳圖片，或提供您本人的有效圖片網址作為虛擬試戴目標。\n    1.  **準備圍巾圖片：** 上傳圖片，或提供圍巾產品、或清楚可見且無遮擋地圍著圍巾的人物之有效圖片網址。\n    1.  **選擇風格與性別：** 選擇您偏好的風格，以及您希望呈現的性別。\n    1.  **啟動 AI 任務並取得任務 ID：** 從回應中取得 `task_id`。\n    1.  **輪詢狀態（`GET`）：** 使用 `task_id` 查詢任務狀態。持續輪詢，直到 `task_status` 為 `\"success\"` 或 `\"error\"`。\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n---\n\n* AI 虛擬試圍巾 API 使用指南\n\n本指南說明如何使用 AI 虛擬試圍巾 API 上傳圖片、準備參考圍巾，以及建立虛擬試戴任務。\n\n***\n\n   * 步驟 1. 準備自拍圖片\n\n您可以：\n*   使用 File API（`/s2s/v2.0/file`）上傳自拍圖片，或\n*   提供有效的圖片網址。\n\n     * 步驟 1.1 使用 File API 上傳檔案\n\n使用 **File API**（`/s2s/v2.0/file`）上傳目標使用者圖片。\n\n**圖片需求：**\n\n*   上傳一張自拍照片。\n*   確保照片清楚呈現上半身。\n*   避免有多人干擾的物件背景。\n\n**請求範例：**\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/file \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"files\": [\n      {\n        \"content_type\": \"image/jpg\",\n        \"file_name\": \"selfie_photo_01_3dbd1b6683.jpg\",\n        \"file_size\": 547541\n      }\n    ]\n  }'\n```\n\n***\n\n     * 步驟 1.2. 取得 File API 回應\n\n回應包含：\n\n*   用於建立 AI 任務的 `file_id`。\n*   用於上傳實際圖片檔案的 `requests.url`。\n\n**回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"files\": [\n      {\n        \"content_type\": \"image/jpg\",\n        \"file_name\": \"selfie_photo_01_3dbd1b6683.jpg\",\n        \"file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n        \"requests\": [\n          {\n            \"method\": \"PUT\",\n            \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\",\n            \"headers\": {\n              \"Content-Length\": \"547541\",\n              \"Content-Type\": \"image/jpg\"\n            }\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n***\n\n     * 步驟 1.3. 上傳圖片到提供的網址\n\n使用 File API 回應中的 `requests.url` 上傳圖片：\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n  --header 'Content-Type: image/jpg' \\\n  --header 'Content-Length: 547541' \\\n  --data-binary @'./selfie_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n   * 步驟 2. 準備參考圍巾圖片\n\n您可以：\n\n*   使用 File API（`/s2s/v2.0/file`）上傳圍巾圖片，或\n*   提供有效的圖片網址。\n\n**支援的圍巾圖片：**\n\n*   圍巾的產品圖片。\n*   無遮擋地圍著圍巾的人物，作為圍巾參考。\n\n詳細規格請參考 **[檔案規格與錯誤](#section/overview/File-Specs-and-Errors)**。\n\n***\n\n   * 步驟 3. 建立 AI 任務\n\n選擇您偏好的風格，以及您希望呈現的性別。\n使用 **AI 任務 API**（`/s2s/v2.0/task/scarf`）建立虛擬試戴任務。\n\n**參數：**\n\n*   使用者圖片：`src_file_id` 或 `src_file_url`。\n*   圍巾圖片：`ref_file_id` 或 `ref_file_url`。\n\n**請求範例：**\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/scarf \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"src_file_url\": \"https://example.com/selfie.jpg\",\n    \"ref_file_url\": \"https://example.com/accessory.jpg\",\n    \"gender\": \"female\",\n    \"style\": \"random\"\n}'\n```\n\n**回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT\"\n  }\n}\n```\n\n***\n\n   * 步驟 4. 輪詢任務結果\n\n使用任務 ID 查詢狀態：\n\n```bash\ncurl --request GET \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/scarf/SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json'\n```\n\n***\n\n   * 步驟 5. 取得結果\n\n成功的回應會包含結果圖片的下載網址：\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"error\": null,\n    \"results\": {\n      \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n    },\n    \"task_status\": \"success\"\n  }\n}\n```\n\nAPI Key 無效的錯誤回應：\n\n```json\n{\n  \"status\": 401,\n  \"error\": \"Unauthorized\",\n  \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\n## 檔案規格與錯誤\n\n* AI 虛擬試圍巾規範\n\n   * 圖片需求\n\n| 類型   | 最低解析度 | 備註 |\n| ------ | ------------------ | ----- |\n| 自拍 | 512 × 512 | 臉部可見，建議頭到胸 |\n| 圍巾  | 512 × 512（產品）<br>800 × 800（佩戴） | 清晰、無遮擋的圍巾視角 |\n\n**支援的圍巾圖片**\n\n* 產品圖片需求\n    * 最低解析度：512 × 512 像素\n    * 每張圖片僅限一個產品\n    * 產品應覆蓋圖片高度的 25% 以上\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/021_thumb_e356d121b3.jpg)\n\n* 佩戴圖片需求\n    * 最低解析度：800 × 800 像素\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/008_thumb_5dd8b1be93.jpg)\n\n**支援的自拍視角**\n\n* 建議圖片解析度：至少 512 × 512 像素。\n* 建議臉部覆蓋範圍：超過圖片高度的 15%。\n* 圖片必須清楚呈現單一人物主體，臉部完全可見，且畫面至少包含從頭到胸的半身照。建議使用半身照。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/lashana_lynch_thumb_7a900b811e.jpg)\n\n**試戴風格**\n\n* 共有五種預先定義的風格用於生成虛擬試戴輸出：\"style_french_elegance\"、\"style_light_luxury\"、\"style_cottagecore\"、\"style_modern_chic\" 與 \"style_bohemian\"。您可以在建立 AI 任務時指定此風格參數，或讓系統預設隨機選擇風格。\n\n![style_french_elegance](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/3d88ad75_41ca_4bf8_b81d_f52adf5db263_4a06b3e174.jpg)\n\n---\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 虛擬試圍巾|輸入：長邊 <= 4096 <br>輸出：896 x 1152 |< 10MB|jpg/jpeg/png/heic|\n\n* 錯誤代碼\n\n| 錯誤代碼 | 說明 |\n| ------------------------------ | -------------------------------------------- |\n| error\\_download\\_image         | 下載來源或參考圖片失敗 |\n| error\\_inference               | 推論流程錯誤                     |\n| error\\_no\\_face                | 來源圖片未偵測到臉部             |\n| error\\_nsfw\\_content\\_detected | 在結果中偵測到 NSFW 內容         |\n| exceed\\_max\\_filesize          | 檔案大小超過 10 MB               |\n| invalid\\_parameter             | 性別或風格值無效                 |\n| unknown\\_internal\\_error       | 其他內部錯誤                     |\n\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jquery >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 虛擬試圍巾 V2.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_bag.yaml","link":"/zh-tw/reference/ai_bag","routeSlug":"/zh-tw/reference/ai_bag","label":"AI 虛擬試包","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_bag/section/概述","routeSlug":"/zh-tw/reference/ai_bag/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_bag/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_bag/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_bag/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_bag/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_bag/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_bag/section/概述/點數消耗"}]},{"type":"group","label":"V2.0","link":"/zh-tw/reference/ai_bag/v2.0","routeSlug":"/zh-tw/reference/ai_bag/v2.0","items":[{"label":"執行 AI 包包任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_bag/v2.0/paths/~1s2s~1v2.0~1task~1bag/post","routeSlug":"/zh-tw/reference/ai_bag/v2.0/paths/~1s2s~1v2.0~1task~1bag/post","metadata":{"seo":{"title":"執行 AI 包包任務。","description":"這個端點啟動包包虛擬試背流程。您必須提供來源檔案、參考檔案（網址或 ID），並指定性別與風格參數。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/bag"},{"label":"查詢 AI 包包任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_bag/v2.0/paths/~1s2s~1v2.0~1task~1bag~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_bag/v2.0/paths/~1s2s~1v2.0~1task~1bag~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 包包任務的狀態。","description":"查詢 AI 包包任務的狀態。"}},"httpPath":"/s2s/v2.0/task/bag/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 虛擬試包","version":"","description":"# 概述\nAR 讓奢華包包購物成為可感知的體驗！AR 技術讓品牌以無與倫比的真實感展示手提包。從背帶長度到包包搭配，顧客都能透過鏡頭即時呈現產品。\n\n## 整合指南\n本指南將引導您完成：\n\n*   **端點：** `/s2s/v2.0/task/bag`\n*   **認證：** 所有請求都需要 `Authorization: Bearer YOUR_API_KEY`\n*   **工作流程：**\n    1.  **準備自拍圖片：** 上傳圖片，或提供您本人的有效圖片網址作為虛擬試戴目標。\n    1.  **準備包包圖片：** 上傳圖片，或提供包包產品、或無遮擋地背著包包的人物有效圖片網址。\n    1.  **選擇風格與性別：** 選擇您偏好的風格，以及您希望呈現的性別。\n    1.  **啟動 AI 任務並取得任務 ID：** 從回應中取得 `task_id`。\n    1.  **輪詢狀態（`GET`）：** 使用 `task_id` 查詢任務狀態。持續輪詢，直到 `task_status` 為 `\"success\"` 或 `\"error\"`。\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n---\n\n* AI 包包 API 使用指南\n\n本指南說明如何使用 AI 包包 API 上傳圖片、準備參考包包，以及建立虛擬試戴任務。\n\n***\n\n   * 步驟 1. 使用 File API 上傳檔案\n\n使用 **File API**（`/s2s/v2.0/file`）上傳目標使用者圖片。\n\n**圖片需求：**\n\n*   上傳一張自拍照片。\n*   確保照片清楚呈現上半身。\n*   避免有多人干擾的物件背景。\n\n**請求範例：**\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/file \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"files\": [\n      {\n        \"content_type\": \"image/jpg\",\n        \"file_name\": \"selfie_photo_01_3dbd1b6683.jpg\",\n        \"file_size\": 547541\n      }\n    ]\n  }'\n```\n\n***\n\n   * 步驟 2. 取得 File API 回應\n\n回應包含：\n\n*   用於建立 AI 任務的 `file_id`。\n*   用於上傳實際圖片檔案的 `requests.url`。\n\n**回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"files\": [\n      {\n        \"content_type\": \"image/jpg\",\n        \"file_name\": \"selfie_photo_01_3dbd1b6683.jpg\",\n        \"file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n        \"requests\": [\n          {\n            \"method\": \"PUT\",\n            \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\",\n            \"headers\": {\n              \"Content-Length\": \"547541\",\n              \"Content-Type\": \"image/jpg\"\n            }\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n***\n\n   * 步驟 3. 上傳圖片到提供的網址\n\n使用 File API 回應中的 `requests.url` 上傳圖片：\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n  --header 'Content-Type: image/jpg' \\\n  --header 'Content-Length: 547541' \\\n  --data-binary @'./selfie_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n   * 步驟 4. 準備參考包包圖片\n\n您可以：\n\n*   使用 File API（`/s2s/v2.0/file`）上傳包包圖片，或\n*   提供有效的圖片網址。\n\n**支援的包包圖片：**\n\n*   包包的產品圖片。\n*   無遮擋地背著包包的人物，作為包包參考。\n\n詳細規格請參考 **[檔案規格與錯誤](#section/overview/File-Specs-and-Errors)**。\n\n***\n\n   * 步驟 5. 建立 AI 任務\n\n選擇您偏好的風格，以及您希望呈現的性別。\n使用 **AI 任務 API**（`/s2s/v2.0/task/bag`）建立虛擬試戴任務。\n\n**參數：**\n\n*   使用者圖片：`src_file_id` 或 `src_file_url`。\n*   包包圖片：`ref_file_id` 或 `ref_file_url`。\n\n**請求範例：**\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/bag \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"src_file_url\": \"https://example.com/selfie.jpg\",\n    \"ref_file_url\": \"https://example.com/accessory.jpg\",\n    \"gender\": \"female\",\n    \"style\": \"random\"\n}'\n```\n\n**回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT\"\n  }\n}\n```\n\n***\n\n   * 步驟 6. 輪詢任務結果\n\n使用任務 ID 查詢狀態：\n\n```bash\ncurl --request GET \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/bag/SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json'\n```\n\n***\n\n   * 步驟 7. 取得結果\n\n成功的回應會包含結果圖片的下載網址：\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"error\": null,\n    \"results\": {\n      \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n    },\n    \"task_status\": \"success\"\n  }\n}\n```\n\nAPI Key 無效的錯誤回應：\n\n```json\n{\n  \"status\": 401,\n  \"error\": \"Unauthorized\",\n  \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\n## 檔案規格與錯誤\n\n* AI 包包虛擬試戴規範\n\n**支援的包包圖片**\n\n* 產品圖片需求\n    * 最低解析度：512 × 512 像素\n    * 每張圖片僅限一個產品\n    * 產品應覆蓋圖片高度的 25% 以上\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/040_thumb_c5f4d2af8e.jpg)\n\n* 佩戴圖片需求\n    * 最低解析度：800 × 800 像素\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/003_thumb_c73b207cae.jpg)\n\n**支援的自拍視角**\n\n* 建議圖片解析度：至少 512 × 512 像素。\n* 建議臉部覆蓋範圍：超過圖片高度的 15%。\n* 圖片必須清楚呈現單一人物主體，臉部完全可見，且畫面至少包含從頭到胸的半身照。建議使用半身照。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/lashana_lynch_thumb_7a900b811e.jpg)\n\n**試戴風格**\n\n* 共有四種預先定義的風格用於生成虛擬試戴輸出：\"style_parisian_chic\"、\"style_urban_chic\"、\"style_mediterranean_chic\" 與 \"style_art_deco_style\"。您可以在建立 AI 任務時指定此風格參數，或讓系統預設隨機選擇風格。\n\n![style_parisian_chic](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/fca6a904_b13a_4c90_bc52_d9200a473c70_4d994afa3e.jpg)\n\n---\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 包包虛擬試戴|輸入：長邊 <= 4096 <br>輸出：1104 x 1472 |< 10MB|jpg/jpeg/png/heic|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| error_download_image | 下載 srcKeys/refKeys 錯誤 |\n| error_inference            | 推論流程錯誤 |\n| error_no_face              | 來源圖片未偵測到臉部 |\n| error_nsfw_content_detected| 在結果圖片中偵測到 NSFW 內容 |\n| exceed_max_filesize        | 輸入檔案大小超過上限（10 MB） |\n| invalid_parameter          | 性別選項值無效 <br>風格選項值無效 |\n| unknown_internal_error     | 其他 |\n\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 包包虛擬試戴 V2.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_shoes.yaml","link":"/zh-tw/reference/ai_shoes","routeSlug":"/zh-tw/reference/ai_shoes","label":"AI 虛擬試鞋","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_shoes/section/概述","routeSlug":"/zh-tw/reference/ai_shoes/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_shoes/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_shoes/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_shoes/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_shoes/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_shoes/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_shoes/section/概述/點數消耗"}]},{"type":"group","label":"V3.0","link":"/zh-tw/reference/ai_shoes/v3.0","routeSlug":"/zh-tw/reference/ai_shoes/v3.0","items":[{"label":"執行 AI 虛擬試鞋 V3.0 任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_shoes/v3.0/paths/~1s2s~1v2.0~1task~1shoes-transfer/post","routeSlug":"/zh-tw/reference/ai_shoes/v3.0/paths/~1s2s~1v2.0~1task~1shoes-transfer/post","metadata":{"seo":{"title":"執行 AI 虛擬試鞋 V3.0 任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/shoes-transfer"},{"label":"查詢 AI 虛擬試鞋 V3.0 任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_shoes/v3.0/paths/~1s2s~1v2.0~1task~1shoes-transfer~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_shoes/v3.0/paths/~1s2s~1v2.0~1task~1shoes-transfer~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 虛擬試鞋 V3.0 任務的狀態。","description":"查詢 AI 虛擬試鞋 V3.0 任務的狀態。"}},"httpPath":"/s2s/v2.0/task/shoes-transfer/{task_id}"}]},{"type":"group","label":"V2.0","link":"/zh-tw/reference/ai_shoes/v2.0","routeSlug":"/zh-tw/reference/ai_shoes/v2.0","items":[{"label":"執行 AI 鞋子任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_shoes/v2.0/paths/~1s2s~1v2.0~1task~1shoes/post","routeSlug":"/zh-tw/reference/ai_shoes/v2.0/paths/~1s2s~1v2.0~1task~1shoes/post","metadata":{"seo":{"title":"執行 AI 鞋子任務。","description":"這個端點啟動虛擬試鞋流程。您必須提供來源檔案、參考檔案（網址或 ID），並指定性別與風格參數。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/shoes"},{"label":"查詢 AI 鞋子任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_shoes/v2.0/paths/~1s2s~1v2.0~1task~1shoes~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_shoes/v2.0/paths/~1s2s~1v2.0~1task~1shoes~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 鞋子任務的狀態。","description":"查詢 AI 鞋子任務的狀態。"}},"httpPath":"/s2s/v2.0/task/shoes/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 虛擬試鞋","version":"","description":"# 概述\n透過我們的 AR 鞋履虛擬試穿，步入購物未來的時代。即刻從您的螢幕看見您喜愛的風格如何呈現與合腳。由尖端 AI 技術驅動，這體驗提供完美的視覺合腳度，幫助您自信購物並減少退貨。\n在家中舒適地探索無盡的風格與顏色。我們高傳真的 AR 模擬讓每個細節栩栩如生，讓您隨時隨地享受店內體驗的興奮感。今天就試試，找到符合您風格的完美一對。\n\n## 整合指南\n本指南將引導您完成：\n\n*   **端點：** `/s2s/v2.0/task/shoes-transfer`\n*   **認證：** 所有請求都需要 `Authorization: Bearer YOUR_API_KEY`\n*   **工作流程：**\n    1.  **準備自拍圖片：** 上傳圖片，或提供您本人的有效圖片網址作為虛擬試戴目標。\n    1.  **準備鞋履圖片：** 上傳鞋履產品圖片，或穿著鞋履的人物照片。\n    1.  **選擇風格與性別：** 選擇您偏好的風格，以及您希望呈現的性別。\n    1.  **啟動 AI 任務並取得任務 ID：** 從回應中取得 `task_id`。\n    1.  **輪詢狀態（`GET`）：** 使用 `task_id` 查詢任務狀態。持續輪詢，直到 `task_status` 為 `\"success\"` 或 `\"error\"`。\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n---\n\n* AI 虛擬試鞋 API 使用指南\n\n本指南說明如何使用 AI 虛擬試鞋 API 上傳圖片、準備參考鞋履，以及建立虛擬試穿任務。\n\n***\n\n   * 步驟 1. 準備自拍圖片\n\n您可以：\n*   使用 File API（`/s2s/v2.0/file`）上傳自拍圖片，或\n*   提供有效的圖片網址。\n\n     * 步驟 1.1 使用 File API 上傳檔案\n\n使用 **File API**（`/s2s/v2.0/file`）上傳目標使用者圖片。\n\n**圖片需求：**\n\n*   上傳一張自拍照片。\n*   確保照片清晰呈現您的鞋履。\n*   避免有多人干擾的物件背景。\n\n**請求範例：**\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/file \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"files\": [\n      {\n        \"content_type\": \"image/jpg\",\n        \"file_name\": \"selfie_photo_01_3dbd1b6683.jpg\",\n        \"file_size\": 547541\n      }\n    ]\n  }'\n```\n\n***\n\n     * 步驟 1.2. 取得 File API 回應\n\n回應包含：\n\n*   用於建立 AI 任務的 `file_id`。\n*   用於上傳實際圖片檔案的 `requests.url`。\n\n**回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"files\": [\n      {\n        \"content_type\": \"image/jpg\",\n        \"file_name\": \"selfie_photo_01_3dbd1b6683.jpg\",\n        \"file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n        \"requests\": [\n          {\n            \"method\": \"PUT\",\n            \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\",\n            \"headers\": {\n              \"Content-Length\": \"547541\",\n              \"Content-Type\": \"image/jpg\"\n            }\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n***\n\n     * 步驟 1.3. 上傳圖片到提供的網址\n\n使用 File API 回應中的 `requests.url` 上傳圖片：\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n  --header 'Content-Type: image/jpg' \\\n  --header 'Content-Length: 547541' \\\n  --data-binary @'./selfie_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n   * 步驟 2. 準備參考鞋履圖片\n\n您可以：\n\n*   使用 File API（`/s2s/v2.0/file`）上傳鞋履圖片，或\n*   提供有效的圖片網址。\n\n**支援的鞋履圖片：**\n\n*   鞋履的產品圖片。\n*   穿著鞋履的人物照片。\n\n詳細規格請參考 **[檔案規格與錯誤](#section/overview/File-Specs-and-Errors)**。\n\n***\n\n   * 步驟 3. 建立 AI 任務\n\n選擇您偏好的風格，以及您希望呈現的性別。\n使用 **AI 任務 API**（`/s2s/v2.0/task/shoes-transfer`）建立虛擬試穿任務。\n\n**參數：**\n\n*   使用者圖片：`src_file_id` 或 `src_file_url`。\n*   鞋履圖片：`ref_file_id` 或 `ref_file_url`。\n\n**請求範例：**\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/shoes-transfer \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"src_file_url\": \"https://example.com/selfie.jpg\",\n    \"ref_file_url\": \"https://example.com/accessory.jpg\",\n    \"gender\": \"female\",\n    \"style\": \"random\"\n}'\n```\n\n**回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT\"\n  }\n}\n```\n\n***\n\n   * 步驟 4. 輪詢任務結果\n\n使用任務 ID 查詢狀態：\n\n```bash\ncurl --request GET \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/shoes-transfer/SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json'\n```\n\n***\n\n   * 步驟 5. 取得結果\n\n成功的回應會包含結果圖片的下載網址：\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"error\": null,\n    \"results\": {\n      \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n    },\n    \"task_status\": \"success\"\n  }\n}\n```\n\nAPI Key 無效的錯誤回應：\n\n```json\n{\n  \"status\": 401,\n  \"error\": \"Unauthorized\",\n  \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\n## 檔案規格與錯誤\n\n* AI 虛擬試鞋規範\n\n   * 圖片需求\n\n| 類型   | 最低解析度 | 備註 |\n| ------ | ------------------ | ----- |\n| 自拍 | 512 × 512 | 腳部可見，建議全身 |\n| 鞋履  | 512 × 512（產品）<br>800 × 800（穿著） | 清晰、無遮擋的鞋履視角 |\n\n**支援的鞋履圖片**\n\n* 產品圖片需求\n    * 最低解析度：512 × 512 像素\n    * 每張圖片僅限一個產品\n    * 產品應覆蓋圖片高度的 25% 以上\n\n![](https://plugins-media.makeupar.com/strapi/assets/small_Shoes_3_428e8dddb1.jpg)\n\n* 佩戴圖片需求\n    * 最低解析度：800 × 800 像素\n    * 單件物品要求：模特必須佩戴恰好一件物品。不可有多件物品或配件。\n    * 覆蓋比例：佩戴的物品必須佔整體圖片高度的 20% 以上。這確保物品在畫面中清晰可見且突出。\n\n![](https://plugins-media.makeupar.com/strapi/assets/small_Shoes_2_ec3578c5c2.jpg)\n\n![](https://plugins-media.makeupar.com/strapi/assets/small_Shoes_9_52a61e0935.jpg)\n\n\n**支援的自拍視角**\n\n* 建議圖片解析度：至少 512 × 512 像素。\n* 單人主體要求：圖片必須包含恰好一位人物主體。不可有額外人物或局部身影。\n* 腳部可見度：主體的腳必須完全可見且無遮擋。\n\n![](https://plugins-media.makeupar.com/strapi/assets/small_clothes_04_441e848298.png)\n\n---\n\n* 支援的格式與尺寸\n\n| AI 功能 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 |\n|  ----  | ----  | ----  | ----  |\n| AI 虛擬試鞋 | 輸入：長邊 <= 4096 <br>輸出：1008 x 1344 | < 10MB | jpg/jpeg/png/heic |\n\n* 錯誤代碼\n\n| 錯誤代碼 | 說明 |\n| ------------------------------ | -------------------------------------------- |\n| error\\_download\\_image         | 下載來源或參考圖片失敗 |\n| error\\_inference               | 推論流程錯誤                     |\n| error\\_no\\_face                | 來源圖片未偵測到臉部             |\n| error\\_nsfw\\_content\\_detected | 在結果中偵測到 NSFW 內容         |\n| exceed\\_max\\_filesize          | 檔案大小超過 10 MB               |\n| invalid\\_parameter             | 性別或風格值無效                 |\n| unknown\\_internal\\_error       | 其他內部錯誤                     |\n\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jquery >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 虛擬試鞋 V2.0 | 2 |\n| AI 虛擬試鞋 V3.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_fabric.yaml","link":"/zh-tw/reference/ai_fabric","routeSlug":"/zh-tw/reference/ai_fabric","label":"AI 布料替換","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_fabric/section/概述","routeSlug":"/zh-tw/reference/ai_fabric/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_fabric/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_fabric/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_fabric/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_fabric/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_fabric/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_fabric/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_fabric/v1.0","routeSlug":"/zh-tw/reference/ai_fabric/v1.0","items":[{"label":"列出預先定義的範本。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_fabric/v1.0/paths/~1s2s~1v2.0~1task~1template~1fabric/get","routeSlug":"/zh-tw/reference/ai_fabric/v1.0/paths/~1s2s~1v2.0~1task~1template~1fabric/get","metadata":{"seo":{"title":"列出預先定義的範本。","description":"列出預先定義的範本。"}},"httpPath":"/s2s/v2.0/task/template/fabric"},{"label":"執行布料任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_fabric/v1.0/paths/~1s2s~1v2.0~1task~1fabric/post","routeSlug":"/zh-tw/reference/ai_fabric/v1.0/paths/~1s2s~1v2.0~1task~1fabric/post","metadata":{"seo":{"title":"執行布料任務。","description":"查詢任務狀態請參考輪詢指南。"}},"httpPath":"/s2s/v2.0/task/fabric"},{"label":"查詢布料任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_fabric/v1.0/paths/~1s2s~1v2.0~1task~1fabric~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_fabric/v1.0/paths/~1s2s~1v2.0~1task~1fabric~1{task_id}/get","metadata":{"seo":{"title":"查詢布料任務的狀態。","description":"查詢布料任務的狀態。"}},"httpPath":"/s2s/v2.0/task/fabric/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 布料替換","version":"","description":"# 概述\n以令人驚嘆的真實感改變您的造型！透過照片模式探索獨特的布料風格——無論是絲滑質地的優雅，或大膽圖案的鮮豔，AI 布料 API 讓材質活起來！開發者可以打造沉浸式的體驗，讓使用者前所未有地看見並感受布料。而且，全新的布料更新隨時到來！\n\n---\n\n## 整合指南\n\n* AI 布料 API 使用指南\n\n本指南說明如何使用 AI 布料 API 上傳圖片、取得預先定義的布料風格，以及建立虛擬試戴任務。\n\n***\n\n   * 步驟 1. 使用 File API 上傳檔案\n\n使用 **File API**（`/s2s/v2.0/file`）上傳目標使用者圖片。\n\n**圖片需求：**\n\n*   上傳高解析度的全身照片。\n*   確保照片清楚呈現整個身體。\n*   避免有多人干擾的物件背景。\n\n**請求範例：**\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/file \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"files\": [\n      {\n        \"content_type\": \"image/jpg\",\n        \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\n        \"file_size\": 547541\n      }\n    ]\n  }'\n```\n\n***\n\n   * 步驟 2. 取得 File API 回應\n\n回應包含：\n\n*   用於建立 AI 任務的 `file_id`。\n*   用於上傳實際圖片檔案的 `requests.url`。\n\n**回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"files\": [\n      {\n        \"content_type\": \"image/jpg\",\n        \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\n        \"file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n        \"requests\": [\n          {\n            \"method\": \"PUT\",\n            \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\",\n            \"headers\": {\n              \"Content-Length\": \"547541\",\n              \"Content-Type\": \"image/jpg\"\n            }\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n***\n\n   * 步驟 3. 上傳圖片到提供的網址\n\n使用 File API 回應中的 `requests.url` 上傳圖片：\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n  --header 'Content-Type: image/jpg' \\\n  --header 'Content-Length: 547541' \\\n  --data-binary @'./full_body_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n   * 步驟 4. 取得預先定義的布料範本\n\n使用 **範本 API**（`/s2s/v2.0/task/template/fabric`）取得預先定義的布料範本清單：\n\n```bash\ncurl --request GET \\\n    --url 'https://yce-api-01.makeupar.com/s2s/v2.0/task/template/fabric?page_size=20&starting_token=73a3c9e69b89' \\\n    --header 'Authorization: Bearer YOUR_API_KEY'\n```\n\n***\n\n   * 步驟 5. 建立 AI 任務\n\n使用 **AI 任務 API**（`/s2s/v2.0/task/fabric`）建立虛擬試戴任務。\n\n**參數：**\n\n*   使用者圖片：`src_file_id` 或 `src_file_url`。\n*   布料風格：`template_id`。\n\n**請求範例：**\n\n```bash\ncurl --request POST \\\n    --url https://yce-api-01.makeupar.com/s2s/v2.0/task/fabric \\\n    --header 'Authorization: Bearer YOUR_API_KEY' \\\n    --header 'content-type: application/json' \\\n    --data '{\n    \"template_id\":\"good_template_001\",\n    \"src_file_url\":\"https://example.com/selfie.jpg\"\n    }'\n```\n\n**回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT\"\n  }\n}\n```\n\n***\n\n   * 步驟 6. 輪詢任務結果\n\n使用任務 ID 查詢狀態：\n\n```bash\ncurl --request GET \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/fabric/<YOUR_TASK_ID> \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json'\n```\n\n***\n\n   * 步驟 7. 取得結果\n\n成功的回應會包含結果圖片的下載網址：\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"error\": null,\n    \"results\": {\n      \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n    },\n    \"task_status\": \"success\"\n  }\n}\n```\n\nAPI Key 無效的錯誤回應：\n\n```json\n{\n  \"status\": 401,\n  \"error\": \"Unauthorized\",\n  \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\n\n應用案例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Fabric.png)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2024-05-07/b103976d-1b0e-4bed-aab4-9307308b84d7.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/03%20ai%20clothes%20changer.jpg)\n\n拍攝建議：\n![拍攝建議](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI-Cloth-Guideline.png \"拍攝建議\")\n\n---\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 布料|長邊 <= 4096，僅限單人，腹部、臉部與肩膀都必須可見。臉部不可被遮擋。身體應直立並面向前方，不可有坐姿或蹲姿等特殊姿勢。|< 10MB|jpg/jpeg|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n|error_apply_region_not_detected|服裝區域過小，或在輸入圖片中未被偵測到\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 布料替換 V1.0 | 2 |\n\n---\n"}},{"type":"separator","label":"精品珠寶與腕錶","labelTranslationKey":"sidebar.reference.separators.jewelryWatches"},{"type":"group","fsPath":"@l10n/zh-TW/reference/ring_vto.yaml","link":"/zh-tw/reference/ring_vto","routeSlug":"/zh-tw/reference/ring_vto","label":"AI 虛擬戒指","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ring_vto/section/概述","routeSlug":"/zh-tw/reference/ring_vto/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ring_vto/section/概述/整合指南","routeSlug":"/zh-tw/reference/ring_vto/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ring_vto/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ring_vto/section/概述/檔案規格與錯誤"},{"type":"link","label":"JS Camera Kit","link":"/zh-tw/reference/ring_vto/section/概述/js-camera-kit","routeSlug":"/zh-tw/reference/ring_vto/section/概述/js-camera-kit"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ring_vto/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ring_vto/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ring_vto/v1.0","routeSlug":"/zh-tw/reference/ring_vto/v1.0","items":[{"label":"建立新檔案。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1file~12d-vto~1ring/post","routeSlug":"/zh-tw/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1file~12d-vto~1ring/post","metadata":{"seo":{"title":"建立新檔案。","description":"要上傳新檔案，您必須先使用 File API。它會提供一個網址——請使用該網址上傳您的檔案。上傳完成後，您可以使用同一個回應中的 file_id，開始使用我們的 AI 功能。"}},"httpPath":"/s2s/v2.0/file/2d-vto/ring"},{"label":"執行 AI 2D 戒指虛擬試戴任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1ring/post","routeSlug":"/zh-tw/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1ring/post","metadata":{"seo":{"title":"執行 AI 2D 戒指虛擬試戴任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/2d-vto/ring"},{"label":"查詢 AI 2D 戒指虛擬試戴任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1ring~1{task_id}/get","routeSlug":"/zh-tw/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1ring~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 2D 戒指虛擬試戴任務的狀態。","description":"查詢 AI 2D 戒指虛擬試戴任務的狀態。"}},"httpPath":"/s2s/v2.0/task/2d-vto/ring/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 虛擬戒指","version":"","description":"# 概述\n輕鬆建立您的 AR 戒指或訂婚戒指試戴體驗。您只需上傳圖片。選擇 2D 圖片，以最少的力氣達成輕鬆卻高品質的虛擬試戴體驗。\n\n## 整合指南\n本指南將引導您完成：\n\n*   **端點：** `/s2s/v2.0/task/2d-vto/ring`\n*   **認證：** 所有請求都需要 `Authorization: Bearer YOUR_API_KEY`\n*   **工作流程：**\n    1.  **準備手部圖片：** 上傳圖片，或提供您手部的有效圖片網址\n    1.  **準備戒指圖片：** 上傳圖片，或提供戒指產品的有效圖片網址\n    1.  **啟動 AI 任務並取得任務 ID：** 從回應中取得 `task_id`。\n    1.  **輪詢狀態（`GET`）：** 使用 `task_id` 查詢任務狀態。持續輪詢，直到 `task_status` 為 `\"success\"` 或 `\"error\"`。\n\n---\n\n* API Playground\n\n使用我們的官方 playground 進行互動式探索與測試：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-ring-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-ring-virtual-try-on/)\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n    ```\n    Authorization: Bearer YOUR_API_KEY\n    ```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n\n* 1. 上傳圖片\n\n您可以直接上傳檔案到伺服器，或在 VTO 任務內容中提供有效的圖片網址。\n\n   * 上傳端點\n\n```\nPOST /s2s/v2.0/file\n```\n\n或者，若您已有公開的圖片網址，可跳過此步驟。\n\n您可以直接上傳檔案到 File API 回應中提供的網址，然後使用 File API 回傳的對應 `src_file_id`，在後續呼叫 AI 任務。或在 VTO 任務內容中提供有效的圖片網址作為 `src_file_url`。`src_file_id` 或 `src_file_url` 將作為虛擬試戴的目標。\n\n您也必須使用 `ref_file_ids` 或 `ref_file_urls` 提供另一張戒指產品圖片作為參考，以套用到您的 `src_file_id` 或 `src_file_url`。\n\nAI 引擎支援為您的戒指產品圖片自動移除背景。不過，您可以為您的手部（`srcmsk_file_id` 或 `srcmsk_file_url`）或戒指產品（`refmsk_file_ids` 或 `refmsk_file_urls`）提供遮擋遮罩圖片檔案，以微調分割結果。\n\n---\n\n* 2. 建立戒指 VTO 任務並輪詢結果\n\n當您取得圖片與範本 ID 後，即可建立任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 `success` 或 `error`。\n\n   * 建立任務端點\n\n```\nPOST /s2s/v2.0/task/2d-vto/ring\n```\n\n   * 輪詢端點\n\n```\nGET /s2s/v2.0/task/2d-vto/ring/{task_id}\n```\n\n---\n\n## 檔案規格與錯誤\n\n* AI 虛擬戒指規範\n\n**支援的戒指視角**\n戒指圖片必須以四分之三正面視角（約 45 度）提供。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_product_01_9a4d0680f2_b46afe9a53.jpg)\n\n**支援的手部視角**\n手背應完全可見，五根手指都清楚呈現且無任何遮擋。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_user_01_6d9893abd0_c7427cdb78.jpg)\n\n**ring\\_wearing\\_finger：integer（0–4）**\n指定戒指戴在哪根手指：\n0 = 拇指\n1 = 食指\n2 = 中指\n3 = 無名指\n4 = 小指\n\n**ring\\_wearing\\_location：float（0.0–1.0）**\n指示沿著手指的位置：\n0.0 = 接近 MCP 關節（大指節）\n1.0 = 接近 PIP 關節（中間關節）\n\n![ring_wearing_location](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_wearing_location_59567be4af.jpg)\n\n**ring\\_shadow\\_intensity：float（0.0–1.0）**\n控制陰影強度：\n0.0 = 無陰影\n1.0 = 最大陰影\n預設：0.15\n\n**ring\\_ambient\\_light\\_intensity：float（0.0–1.0）**\n定義光線參考目標手部圖片的程度：\n0.0 = 忽略手部圖片的光線\n1.0 = 完全配合手部圖片的光線與陰影渲染\n預設：1.0\n\n**ring\\_anchor\\_point：以像素座標表示的兩個點的陣列（選填）**\n標示戒指接觸手指的內緣，指定左與右的點。這對於寬版或厚版戒指特別有用。\n若未提供此參數，AI 引擎會自動偵測錨點。\n\n![ring_anchor_point](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_anchor_point_e6eb241ef8.jpg)\n\n\n---\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 虛擬戒指|長邊 <= 4096 |< 10MB|jpg/jpeg/png|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| RUNTIME_ERROR | 執行期間發生不如預期的錯誤 |\n| PHOTO_DETECTION_FAIL | 無法正確處理使用者照片，例如未偵測到手 |\n| OBJECT_DETECTION_FAIL | 無法正確處理物件照片，例如未偵測到產品 |\n| PHOTO_CHECK_INVALID | 使用者照片的姿勢或尺寸無效 |\n| INPUT_ERROR | 輸入檔案格式不正確 |\n| INPUT_MAIN_IMAGE_EMPTY | 需要使用者圖片 |\n\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 虛擬戒指 V1.0 | 單件佩戴 1 點 <br> 疊戴 2 點 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_bracelet.yaml","link":"/zh-tw/reference/ai_bracelet","routeSlug":"/zh-tw/reference/ai_bracelet","label":"AI 虛擬手環","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_bracelet/section/概述","routeSlug":"/zh-tw/reference/ai_bracelet/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_bracelet/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_bracelet/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_bracelet/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_bracelet/section/概述/檔案規格與錯誤"},{"type":"link","label":"JS Camera Kit","link":"/zh-tw/reference/ai_bracelet/section/概述/js-camera-kit","routeSlug":"/zh-tw/reference/ai_bracelet/section/概述/js-camera-kit"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_bracelet/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_bracelet/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_bracelet/v1.0","routeSlug":"/zh-tw/reference/ai_bracelet/v1.0","items":[{"label":"執行 AI 2D 手環虛擬試戴任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_bracelet/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1bracelet/post","routeSlug":"/zh-tw/reference/ai_bracelet/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1bracelet/post","metadata":{"seo":{"title":"執行 AI 2D 手環虛擬試戴任務。","description":"這個端點啟動手環虛擬試戴流程。您必須提供來源檔案與參考圖片（透過網址或檔案 ID），以及對位與陰影的特定參數。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/2d-vto/bracelet"},{"label":"查詢 AI 2D 手環虛擬試戴任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_bracelet/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1bracelet~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_bracelet/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1bracelet~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 2D 手環虛擬試戴任務的狀態。","description":"查詢 AI 2D 手環虛擬試戴任務的狀態。"}},"httpPath":"/s2s/v2.0/task/2d-vto/bracelet/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 虛擬手環","version":"","description":"# 概述\n終極的 AI 虛擬手環\n採用 AI 驅動的解決方案，協助您的顧客進行線上購物，每次都能確保完美的佩戴效果與極佳的購物滿意度。只需一張 2D 圖片。\n\n以極其逼真的手環虛擬試戴體驗，創造吸引人的購物流程。我們的解決方案滿足各種規模珠寶品牌的需求。選擇 2D 圖片，以最少的力氣達成輕鬆卻高品質的虛擬試戴體驗。這項獨特的功能讓我們在電子商務領域脫穎而出，讓顧客比以往任何時候都更容易體驗您的產品。\n\n## 整合指南\n本指南將引導您完成：\n\n*   **端點：** `/s2s/v2.0/task/2d-vto/bracelet`\n*   **認證：** 所有請求都需要 `Authorization: Bearer YOUR_API_KEY`\n*   **工作流程：**\n    1.  **準備手腕圖片：** 上傳圖片，或提供您手腕的有效圖片網址\n    1.  **準備手環圖片：** 上傳圖片，或提供手環產品的有效圖片網址\n    1.  **啟動 AI 任務並取得任務 ID：** 從回應中取得 `task_id`。\n    1.  **輪詢狀態（`GET`）：** 使用 `task_id` 查詢任務狀態。持續輪詢，直到 `task_status` 為 `\"success\"` 或 `\"error\"`。\n\n---\n\n* API Playground\n\n使用我們的官方 playground 進行互動式探索與測試：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-bracelet-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-bracelet-virtual-try-on/)\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n    ```\n    Authorization: Bearer YOUR_API_KEY\n    ```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n\n* 1. 上傳圖片\n\n您可以直接上傳檔案到伺服器，或在 VTO 任務內容中提供有效的圖片網址。\n\n   * 上傳端點\n\n```\nPOST /s2s/v2.0/file\n```\n\n或者，若您已有公開的圖片網址，可跳過此步驟。\n\n您可以直接上傳檔案到 File API 回應中提供的網址，然後使用 File API 回傳的對應 `src_file_id`，在後續呼叫 AI 任務。或在 VTO 任務內容中提供有效的圖片網址作為 `src_file_url`。`src_file_id` 或 `src_file_url` 將作為虛擬試戴的目標。\n\n您也必須使用 `ref_file_ids` 或 `ref_file_urls` 提供另一張手環產品圖片作為參考，以套用到您的 `src_file_id` 或 `src_file_url`。\n\nAI 引擎支援為您的手環產品圖片自動移除背景。不過，您可以為您的手部（`srcmsk_file_id` 或 `srcmsk_file_url`）或手環產品（`refmsk_file_ids` 或 `refmsk_file_urls`）提供遮擋遮罩圖片檔案，以微調分割結果。\n\n---\n\n* 2. 建立手環 VTO 任務並輪詢結果\n\n當您取得圖片與範本 ID 後，即可建立任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 `success` 或 `error`。\n\n   * 建立任務端點\n\n```\nPOST /s2s/v2.0/task/2d-vto/bracelet\n```\n\n   * 輪詢端點\n\n```\nGET /s2s/v2.0/task/2d-vto/bracelet/{task_id}\n```\n\n---\n\n## 檔案規格與錯誤\n\n* AI 虛擬手環規範\n\n**支援的手環視角**\n手環圖片必須以四分之三正面視角（約 45 度）提供。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/bracelet_product_09_2cb9721d77_2f8d90ab9f.jpg)\n\n**支援的手腕視角**\n手腕背面應完全可見，五根手指都清楚呈現且無任何遮擋。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/watch_and_bracelet_user_01_09f16603cb_878dc89179.jpg)\n\n**bracelet\\_wearing\\_location：float（−0.3 到 1.0）**\n指示沿著手腕的位置：\n−0.3 代表接近主要手腕關節\n1.0 代表遠離主要手腕關節\n預設值：null（使用引擎預設）\n\n![bracelet_wearing_location](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/bracelet_wearing_location_01ac0a048e.jpg)\n\n**bracelet\\_shadow\\_intensity：float（0.0 到 1.0）**\n控制陰影的強度：\n0.0 代表無陰影\n1.0 代表最大陰影\n預設值：0.15\n\n**bracelet\\_ambient\\_light\\_intensity：float（0.0 到 1.0）**\n定義光線參考目標手部圖片的程度：\n0.0 忽略手部圖片的光線\n1.0 完全配合手部圖片的光線與陰影渲染\n預設值：1.0\n\n**手環錨點：以像素座標表示的 2 個點的陣列（選填）**\n標示手環接觸手腕的內緣，指定左與右的點。\n若未提供此參數，AI 引擎會自動偵測錨點。\n![bracelet_anchor_point](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/bracelet_anchor_point_c353245edc.jpg)\n\n---\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 虛擬手環|長邊 <= 4096 |< 10MB|jpg/jpeg/png|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| RUNTIME_ERROR | 執行期間發生不如預期的錯誤 |\n| PHOTO_DETECTION_FAIL | 無法正確處理使用者照片，例如未偵測到手 |\n| OBJECT_DETECTION_FAIL | 無法正確處理物件照片，例如未偵測到產品 |\n| PHOTO_CHECK_INVALID | 使用者照片的姿勢或尺寸無效 |\n| INPUT_ERROR | 輸入檔案格式不正確 |\n| INPUT_MAIN_IMAGE_EMPTY | 需要使用者圖片 |\n\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 虛擬手環 V1.0 | 單件佩戴 1 點 <br> 疊戴 2 點 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_watch.yaml","link":"/zh-tw/reference/ai_watch","routeSlug":"/zh-tw/reference/ai_watch","label":"AI 虛擬腕錶","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_watch/section/概述","routeSlug":"/zh-tw/reference/ai_watch/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_watch/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_watch/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_watch/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_watch/section/概述/檔案規格與錯誤"},{"type":"link","label":"JS Camera Kit","link":"/zh-tw/reference/ai_watch/section/概述/js-camera-kit","routeSlug":"/zh-tw/reference/ai_watch/section/概述/js-camera-kit"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_watch/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_watch/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_watch/v1.0","routeSlug":"/zh-tw/reference/ai_watch/v1.0","items":[{"label":"執行 AI 2D 手錶虛擬試戴任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_watch/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1watch/post","routeSlug":"/zh-tw/reference/ai_watch/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1watch/post","metadata":{"seo":{"title":"執行 AI 2D 手錶虛擬試戴任務。","description":"這個端點啟動手錶虛擬試戴流程。您必須提供來源檔案與參考圖片（透過網址或檔案 ID），以及對位、陰影與佩戴位置的特定參數。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/2d-vto/watch"},{"label":"查詢 AI 2D 手錶虛擬試戴任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_watch/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1watch~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_watch/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1watch~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 2D 手錶虛擬試戴任務的狀態。","description":"查詢 AI 2D 手錶虛擬試戴任務的狀態。"}},"httpPath":"/s2s/v2.0/task/2d-vto/watch/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 虛擬腕錶","version":"","description":"# 概述\n輕鬆虛擬試戴 AR 手錶！只需一張 2D 圖片。\n\n只需上傳單張 2D 圖片，使用者即可透過我們創新的 AR 手錶應用，即刻虛擬試戴頂級手錶。這項獨特的功能讓我們在電子商務領域脫穎而出，讓顧客比以往任何時候都更容易體驗您的產品。\n\n## 整合指南\n本指南將引導您完成：\n\n*   **端點：** `/s2s/v2.0/task/2d-vto/watch`\n*   **認證：** 所有請求都需要 `Authorization: Bearer YOUR_API_KEY`\n*   **工作流程：**\n    1.  **準備手腕圖片：** 上傳圖片，或提供您手腕的有效圖片網址\n    1.  **準備手錶圖片：** 上傳圖片，或提供手錶產品的有效圖片網址\n    1.  **啟動 AI 任務並取得任務 ID：** 從回應中取得 `task_id`。\n    1.  **輪詢狀態（`GET`）：** 使用 `task_id` 查詢任務狀態。持續輪詢，直到 `task_status` 為 `\"success\"` 或 `\"error\"`。\n\n---\n\n* API Playground\n\n使用我們的官方 playground 進行互動式探索與測試：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-watch-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-watch-virtual-try-on/)\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n    ```\n    Authorization: Bearer YOUR_API_KEY\n    ```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n\n* 1. 上傳圖片\n\n您可以直接上傳檔案到伺服器，或在 VTO 任務內容中提供有效的圖片網址。\n\n   * 上傳端點\n\n```\nPOST /s2s/v2.0/file\n```\n\n或者，若您已有公開的圖片網址，可跳過此步驟。\n\n您可以直接上傳檔案到 File API 回應中提供的網址，然後使用 File API 回傳的對應 `src_file_id`，在後續呼叫 AI 任務。或在 VTO 任務內容中提供有效的圖片網址作為 `src_file_url`。`src_file_id` 或 `src_file_url` 將作為虛擬試戴的目標。\n\n您也必須使用 `ref_file_ids` 或 `ref_file_urls` 提供另一張手錶產品圖片作為參考，以套用到您的 `src_file_id` 或 `src_file_url`。\n\nAI 引擎支援為您的手錶產品圖片自動移除背景。不過，您可以為您的手部（`srcmsk_file_id` 或 `srcmsk_file_url`）或手錶產品（`refmsk_file_ids` 或 `refmsk_file_urls`）提供遮擋遮罩圖片檔案，以微調分割結果。\n\n---\n\n* 2. 建立手錶 VTO 任務並輪詢結果\n\n當您取得圖片與範本 ID 後，即可建立任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 `success` 或 `error`。\n\n   * 建立任務端點\n\n```\nPOST /s2s/v2.0/task/2d-vto/watch\n```\n\n   * 輪詢端點\n\n```\nGET /s2s/v2.0/task/2d-vto/watch/{task_id}\n```\n\n---\n\n## 檔案規格與錯誤\n\n* AI 虛擬腕錶規範\n\n**支援的手錶視角**\n\n手錶圖片需為清晰正面視角，錶面無遮擋。錶帶應裁切以呈現真實的佩戴長度。\n    * 手錶必須直立且面向前方——平放（水平放置）會產生錯誤的結果。\n    * 錶帶背面（例如錶扣）不得出現在圖片中——僅應可見面向前方的錶帶。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/watch_product_01_aab8053028_50ab7fe9a5.jpg)\n\n***\n\n**支援的手腕視角**\n\n手腕背面應完全可見，五根手指都清楚呈現且無任何遮擋。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/watch_and_bracelet_user_01_09f16603cb_878dc89179.jpg)\n\n**watch\\_wearing\\_location：float（−0.3 到 1.0）**\n指示沿著手腕的位置：\n−0.3 代表接近主要手腕關節\n1.0 代表遠離主要手腕關節\n預設值：null（使用引擎預設）\n\n![watch_wearing_location](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/bracelet_wearing_location_01ac0a048e.jpg)\n\n**watch\\_shadow\\_intensity：float（0.0 到 1.0）**\n控制陰影的強度：\n0.0 代表無陰影\n1.0 代表最大陰影\n預設值：0.15\n\n**watch\\_ambient\\_light\\_intensity：float（0.0 到 1.0）**\n定義光線參考目標手部圖片的程度：\n0.0 忽略手部圖片的光線\n1.0 完全配合手部圖片的光線與陰影渲染\n預設值：1.0\n\n**手錶錨點：以像素座標表示的 4 個點的陣列（選填）**\n前兩個點標示佩戴時錶帶的起點與終點。\n其餘兩個點標示錶殼的上緣與下緣。\n\n![watch_anchor_point](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Product_anchors_ece6851c88.jpg)\n\n---\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 虛擬腕錶|長邊 <= 4096 |< 10MB|jpg/jpeg/png|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| RUNTIME_ERROR | 手錶執行期間發生不如預期的錯誤 |\n| PHOTO_DETECTION_FAIL | 無法正確處理使用者照片，例如未偵測到手 |\n| OBJECT_DETECTION_FAIL | 無法正確處理物件照片，例如未偵測到產品 |\n| PHOTO_CHECK_INVALID | 使用者照片的姿勢或尺寸無效 |\n| INPUT_ERROR | 輸入檔案格式不正確 |\n| INPUT_MAIN_IMAGE_EMPTY | 需要使用者圖片 |\n\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 虛擬腕錶 V1.0 | 單件佩戴 1 點 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_earrings.yaml","link":"/zh-tw/reference/ai_earrings","routeSlug":"/zh-tw/reference/ai_earrings","label":"AI 虛擬耳環","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_earrings/section/概述","routeSlug":"/zh-tw/reference/ai_earrings/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_earrings/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_earrings/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_earrings/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_earrings/section/概述/檔案規格與錯誤"},{"type":"link","label":"JS Camera Kit","link":"/zh-tw/reference/ai_earrings/section/概述/js-camera-kit","routeSlug":"/zh-tw/reference/ai_earrings/section/概述/js-camera-kit"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_earrings/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_earrings/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_earrings/v1.0","routeSlug":"/zh-tw/reference/ai_earrings/v1.0","items":[{"label":"執行 AI 2D 耳環虛擬試戴任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1earring/post","routeSlug":"/zh-tw/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1earring/post","metadata":{"seo":{"title":"執行 AI 2D 耳環虛擬試戴任務。","description":"這個端點啟動耳環虛擬試戴流程。您必須提供來源檔案與參考圖片（透過網址或檔案 ID），以及對位、陰影與佩戴位置的特定參數。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/2d-vto/earring"},{"label":"查詢 AI 2D 耳環虛擬試戴任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1earring~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1earring~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 2D 耳環虛擬試戴任務的狀態。","description":"查詢 AI 2D 耳環虛擬試戴任務的狀態。"}},"httpPath":"/s2s/v2.0/task/2d-vto/earring/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 虛擬耳環","version":"","description":"# 概述\n終極的 AI 虛擬耳環\n頂尖的 AI 耳洞模擬器，用於虛擬耳環試戴與虛擬穿孔試戴\n\n從 2D 圖片創造寫實且動態的耳環虛擬試戴，無需昂貴的 3D 建模。我們先進的演算法以精緻的光線效果與物理精確的動作，創造栩栩如生的虛擬試戴耳環 SKU。\n\n## 整合指南\n本指南將引導您完成：\n\n*   **端點：** `/s2s/v2.0/task/2d-vto/earring`\n*   **認證：** 所有請求都需要 `Authorization: Bearer YOUR_API_KEY`\n*   **工作流程：**\n    1.  **準備自拍圖片：** 上傳圖片，或提供有效的圖片網址\n    2.  **準備耳環圖片：** 上傳圖片，或提供耳環產品的有效圖片網址\n    3.  **啟動 AI 任務並取得任務 ID：** 從回應中取得 `task_id`。\n    4.  **輪詢狀態（`GET`）：** 使用 `task_id` 查詢任務狀態。持續輪詢直到 `task_status` 為 `\"success\"` 或 `\"error\"`。\n\n---\n\n* API Playground\n\n使用我們的官方 playground 進行互動式探索與測試：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-earring-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-earring-virtual-try-on/)\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n    ```\n    Authorization: Bearer YOUR_API_KEY\n    ```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n\n* 1. 上傳圖片\n\n您可以直接上傳檔案到伺服器，或在 VTO 任務內容中提供有效的圖片網址。\n\n   * 上傳端點\n\n```\nPOST /s2s/v2.0/file\n```\n\n或者，若您已有公開的圖片網址，可跳過此步驟。\n\n您可以直接上傳檔案到 File API 回應中提供的網址，然後使用 File API 回傳的對應 `src_file_id`，在後續呼叫 AI 任務。或在 VTO 任務內容中提供有效的圖片網址作為 `src_file_url`。`src_file_id` 或 `src_file_url` 將作為虛擬試戴的目標。\n\n您也必須使用 `ref_file_ids` 或 `ref_file_urls` 提供另一張耳環產品圖片作為參考，以套用到您的 `src_file_id` 或 `src_file_url`。\n\nAI 引擎支援為您的耳環產品圖片自動移除背景。不過，您可以為您的手部（`srcmsk_file_id` 或 `srcmsk_file_url`）或耳環產品（`refmsk_file_ids` 或 `refmsk_file_urls`）提供遮擋遮罩圖片檔案，以微調分割結果。\n\n---\n\n* 2. 建立耳環 VTO 任務並輪詢結果\n\n當您取得圖片與範本 ID 後，即可建立任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 `success` 或 `error`。\n\n   * 建立任務端點\n\n```\nPOST /s2s/v2.0/task/2d-vto/earring\n```\n\n   * 輪詢端點\n\n```\nGET /s2s/v2.0/task/2d-vto/earring/{task_id}\n```\n\n---\n\n## 檔案規格與錯誤\n\n* AI 虛擬耳環規範\n\n**支援的耳環參考圖片**\n* 單個耳環的圖片，正面視角清晰且無遮擋。\n*   所有參數（包括錨點、遮罩、位置等）**僅**在參考圖片展示**單個耳環**佩戴時適用。\n*   若試戴參考圖片展示**兩邊耳環**，所有參數將使用**自動偵測與預設設定**。\n*   試戴**兩邊耳環**時，較清晰的耳朵將作為來源，另一邊則以其鏡像生成。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/earring_product_01_41c943f9fc_037ffb1241.jpg) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/earring_product_07_5476e0a156_a69e8e6549.jpg)\n\n**支援的自拍視角**\n\n*   AI 虛擬耳環支援正面圖片，但側面圖片可達到最佳結果。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Earring_restriction_cdf1de3c7b.png)\n\n**earring\\_wearing\\_location：長度為 2 的整數陣列**\n指定自拍中耳環應放置的目標位置。\n預設值：null（引擎預設）\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/wearing_location_b4f6f4453a.jpg)\n\n**earring\\_scale：大於 0 的數值**\n以公分控制耳環尺寸。\n預設值：null（引擎預設）\n\n**earring\\_is\\_right\\_ear：boolean**\nindicating 耳環是否佩戴在右耳。預設佩戴在右耳。\n預設值：true\n\n**earring\\_occluded\\_type：number（Enum：0、1、2）**\n指定遮擋類型：\n0 代表自動偵測\n1 代表被遮擋\n2 代表無遮擋\n預設值：0\n\n**earring\\_shadow\\_intensity：float（0.0 到 1.0）**\n控制陰影強度：\n0.0 代表無陰影\n1.0 代表最大陰影\n預設值：0.15\n\n**earring\\_ambient\\_light\\_intensity：float（0.0 到 1.0）**\n定義光線參考自拍圖片的程度：\n0.0 忽略自拍圖片的光線\n1.0 完全符合自拍圖片的光線與陰影渲染\n預設值：1.0\n\n**earring\\_anchor\\_point：以像素座標表示的一點陣列（選填）**\n指定耳環產品圖片中的佩戴位置。\n預設值：null（引擎預設）\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/anchor_point_787282aa19.jpg)\n\n\n---\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 虛擬耳環|長邊 <= 4096 |< 10MB|jpg/jpeg/png|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| RUNTIME_ERROR | 耳環執行期間發生不如預期的錯誤 |\n| PHOTO_DETECTION_FAIL | 無法正確處理使用者照片，例如未偵測到手 |\n| OBJECT_DETECTION_FAIL | 無法正確處理物件照片，例如未偵測到產品 |\n| PHOTO_CHECK_INVALID | 使用者照片的姿勢或尺寸無效 |\n| INPUT_ERROR | 輸入檔案格式不正確 |\n| INPUT_MAIN_IMAGE_EMPTY | 需要使用者圖片 |\n\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 虛擬耳環 V1.0 | 單件佩戴 1 點 <br> 疊戴 2 點 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_necklace.yaml","link":"/zh-tw/reference/ai_necklace","routeSlug":"/zh-tw/reference/ai_necklace","label":"AI 虛擬項鍊","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_necklace/section/概述","routeSlug":"/zh-tw/reference/ai_necklace/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_necklace/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_necklace/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_necklace/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_necklace/section/概述/檔案規格與錯誤"},{"type":"link","label":"JS Camera Kit","link":"/zh-tw/reference/ai_necklace/section/概述/js-camera-kit","routeSlug":"/zh-tw/reference/ai_necklace/section/概述/js-camera-kit"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_necklace/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_necklace/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_necklace/v1.0","routeSlug":"/zh-tw/reference/ai_necklace/v1.0","items":[{"label":"執行 AI 2D 項鍊虛擬試戴任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_necklace/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1necklace/post","routeSlug":"/zh-tw/reference/ai_necklace/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1necklace/post","metadata":{"seo":{"title":"執行 AI 2D 項鍊虛擬試戴任務。","description":"這個端點啟動項鍊虛擬試戴流程。您必須提供來源檔案與參考圖片（透過網址或檔案 ID），以及對位、陰影與佩戴位置的特定參數。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/2d-vto/necklace"},{"label":"查詢 AI 2D 項鍊虛擬試戴任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_necklace/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1necklace~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_necklace/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1necklace~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 2D 項鍊虛擬試戴任務的狀態。","description":"查詢 AI 2D 項鍊虛擬試戴任務的狀態。"}},"httpPath":"/s2s/v2.0/task/2d-vto/necklace/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 虛擬項鍊","version":"","description":"# 概述\n以最先進的項鍊虛擬試戴，呈現奢華的外觀與感受\n精準的 AI 頸部與鎖骨追蹤為使用者提供超寫實的 AR 試戴體驗，重現實體項試試戴的奢華外觀與感受。\n\n從 2D 圖片創造寫實且動態的項鍊虛擬試戴，無需昂貴的 3D 建模。我們先進的演算法以精緻的光線效果與物理精確的動作，創造栩栩如生的虛擬試戴項鍊 SKU。\n\n## 整合指南\n本指南將引導您完成：\n\n*   **端點：** `/s2s/v2.0/task/2d-vto/necklace`\n*   **認證：** 所有請求都需要 `Authorization: Bearer YOUR_API_KEY`\n*   **工作流程：**\n    1.  **準備自拍圖片：** 上傳圖片，或提供有效的圖片網址\n    2.  **準備項鍊圖片：** 上傳圖片，或提供項鍊產品的有效圖片網址\n    3.  **啟動 AI 任務並取得任務 ID：** 從回應中取得 `task_id`。\n    4.  **輪詢狀態（`GET`）：** 使用 `task_id` 查詢任務狀態。持續輪詢直到 `task_status` 為 `\"success\"` 或 `\"error\"`。\n\n---\n\n* API Playground\n\n使用我們的官方 playground 進行互動式探索與測試：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-necklace-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-necklace-virtual-try-on/)\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n    ```\n    Authorization: Bearer YOUR_API_KEY\n    ```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n\n* 1. 上傳圖片\n\n您可以直接上傳檔案到伺服器，或在 VTO 任務內容中提供有效的圖片網址。\n\n   * 上傳端點\n\n```\nPOST /s2s/v2.0/file\n```\n\n或者，若您已有公開的圖片網址，可跳過此步驟。\n\n您可以直接上傳檔案到 File API 回應中提供的網址，然後使用 File API 回傳的對應 `src_file_id`，在後續呼叫 AI 任務。或在 VTO 任務內容中提供有效的圖片網址作為 `src_file_url`。`src_file_id` 或 `src_file_url` 將作為虛擬試戴的目標。\n\n您也必須使用 `ref_file_ids` 或 `ref_file_urls` 提供另一張項鍊產品圖片作為參考，以套用到您的 `src_file_id` 或 `src_file_url`。\n\nAI 引擎支援為您的自拍自動移除背景。不過，您可以為您的頸部（`srcmsk_file_id` 或 `srcmsk_file_url`）提供遮擋遮罩圖片檔案，以微調分割結果。\n\n---\n\n* 2. 建立項鍊 VTO 任務並輪詢結果\n\n當您取得圖片與範本 ID 後，即可建立任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 `success` 或 `error`。\n\n   * 建立任務端點\n\n```\nPOST /s2s/v2.0/task/2d-vto/necklace\n```\n\n   * 輪詢端點\n\n```\nGET /s2s/v2.0/task/2d-vto/necklace/{task_id}\n```\n\n---\n\n## 檔案規格與錯誤\n\n* AI 虛擬項鍊規範\n\n**支援的項鍊視角**\n佩戴項鍊的正面圖片，並移除背景。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/necklace_product_01_124206cfbe_3993a2128d.jpg)\n\n**支援的自拍視角**\n頸部清晰可見且無遮擋的正面自拍。支援水平頭部旋轉在 20 度內。頭部尺寸應比例得當，頸部寬度應佔圖片寬度的至少 15%。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Necklace_restriction_83410fb6c1.png)\n\n**necklace\\_wearing\\_location：兩點的陣列（選填）**\n指定照片中項鍊應放置的目標位置。\n預設：null（引擎預設）\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/wearing_location_874264bb70.jpg)\n\n**necklace\\_shadow\\_intensity：float（0.0 到 1.0）**\n控制陰影強度：\n0.0 代表無陰影\n1.0 代表最大陰影\n預設值：0.15\n\n**necklace\\_ambient\\_light\\_intensity：float（0.0 到 1.0）**\n定義光線參考自拍圖片的程度：\n0.0 忽略自拍圖片的光線\n1.0 完全符合自拍圖片的光線與陰影渲染\n預設值：1.0\n\n**necklace\\_anchor\\_point：以像素座標表示的兩點陣列（選填）**\n指定產品圖片中項鍊鏈左右可見末端的錨點，用於對齊。\n預設：null（引擎預設）\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/anchor_point_7f9b254ca4.jpg)\n\n---\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 虛擬項鍊|長邊 <= 4096 |< 10MB|jpg/jpeg/png|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| RUNTIME_ERROR | 執行期間發生不如預期的錯誤 |\n| PHOTO_DETECTION_FAIL | 使用者照片無法正確處理，例如未偵測到頸部 |\n| OBJECT_DETECTION_FAIL | 無法正確處理物件照片，例如未偵測到產品 |\n| PHOTO_CHECK_INVALID | 使用者照片的姿勢或尺寸無效 |\n| INPUT_ERROR | 輸入檔案格式不正確 |\n| INPUT_MAIN_IMAGE_EMPTY | 需要使用者圖片 |\n\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 虛擬項鍊 V1.0 | 單件佩戴 1 點 |\n\n---\n"}},{"type":"separator","label":"圖片編輯","labelTranslationKey":"sidebar.reference.separators.image"},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_face_swap.yaml","link":"/zh-tw/reference/ai_face_swap","routeSlug":"/zh-tw/reference/ai_face_swap","label":"AI 照片換臉","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_face_swap/section/概述","routeSlug":"/zh-tw/reference/ai_face_swap/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_face_swap/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_face_swap/section/概述/整合指南"},{"type":"link","label":"輸入與輸出","link":"/zh-tw/reference/ai_face_swap/section/概述/輸入與輸出","routeSlug":"/zh-tw/reference/ai_face_swap/section/概述/輸入與輸出"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_face_swap/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_face_swap/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_face_swap/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_face_swap/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_face_swap/v1.0","routeSlug":"/zh-tw/reference/ai_face_swap/v1.0","items":[{"label":"執行 AI 照片換臉的臉部偵測任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1pre-process/post","routeSlug":"/zh-tw/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1pre-process/post","metadata":{"seo":{"title":"執行 AI 照片換臉的臉部偵測任務。","description":"當來源照片可能包含超過一個有效目標，或您的整合需要明確選擇哪個被偵測到的目標接受特效時，請使用前處理任務。對於單一目標的圖片，當功能支援預設的 index 值，且您的應用程式不需要手動選擇目標時，可以跳過前處理。"}},"httpPath":"/s2s/v2.0/task/face-swap/pre-process"},{"label":"查詢 AI 照片換臉的臉部偵測任務狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1pre-process~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1pre-process~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 照片換臉的臉部偵測任務狀態。","description":"查詢 AI 照片換臉的臉部偵測任務狀態。"}},"httpPath":"/s2s/v2.0/task/face-swap/pre-process/{task_id}"},{"label":"執行 AI 照片換臉任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap/post","routeSlug":"/zh-tw/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap/post","metadata":{"seo":{"title":"執行 AI 照片換臉任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/face-swap"},{"label":"查詢 AI 照片換臉任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 照片換臉任務的狀態。","description":"查詢 AI 照片換臉任務的狀態。"}},"httpPath":"/s2s/v2.0/task/face-swap/{task_id}"}]}],"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"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_image_extender.yaml","link":"/zh-tw/reference/ai_image_extender","routeSlug":"/zh-tw/reference/ai_image_extender","label":"AI 擴圖","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_image_extender/section/概述","routeSlug":"/zh-tw/reference/ai_image_extender/section/概述","items":[{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_image_extender/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_image_extender/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_image_extender/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_image_extender/section/概述/點數消耗"}]},{"type":"group","label":"V2.0","link":"/zh-tw/reference/ai_image_extender/v2.0","routeSlug":"/zh-tw/reference/ai_image_extender/v2.0","items":[{"label":"執行 AI 擴圖任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_image_extender/v2.0/paths/~1s2s~1v2.0~1task~1out-paint/post","routeSlug":"/zh-tw/reference/ai_image_extender/v2.0/paths/~1s2s~1v2.0~1task~1out-paint/post","metadata":{"seo":{"title":"執行 AI 擴圖任務。","description":"查詢任務狀態請參考輪詢指南。這個 API 需要 3 個關鍵參數：輸入圖片、支點與輸出圖片。"}},"httpPath":"/s2s/v2.0/task/out-paint"},{"label":"查詢 AI 擴圖任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_image_extender/v2.0/paths/~1s2s~1v2.0~1task~1out-paint~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_image_extender/v2.0/paths/~1s2s~1v2.0~1task~1out-paint~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 擴圖任務的狀態。","description":"查詢 AI 擴圖任務的狀態。"}},"httpPath":"/s2s/v2.0/task/out-paint/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 擴圖","version":"","description":"# 概述\n透過我們尖端的 AI 擴圖，體驗生動的 AI Outpainting。以任何比例無縫擴展圖片，用我們先進的 AI 技術激發您的創意。在擴展照片時維持最高品質，不犧牲風格或美感。透過我們易用的 AI 工具，一鍵自動放大背景，即刻轉換您的照片。得益於先進的情境感知技術，我們為每位觀眾確保無縫且引人入勝的體驗。\n\n![AI Image Extender](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_outpainting_S1_img_03_cf19a018d9.jpg \"AI 擴圖\")\n\n無論您是想在 Instagram 上脫穎而出，或構圖數位傑作，都能從多種尺寸與比例中選擇，達到完美的契合。當您調整與轉換時，我們的 AI 無縫施展魔法，確保擴展的區域與您的原始照片完美融合。\n\n![AI Image Extender](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_outpainting_S1_img_01_1876fb85a5.jpg \"AI 擴圖\")\n\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n| AI 功能 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 |\n| ---- | ---- | ----  | ---- |\n| AI 擴圖 | 長邊 <= 4096 | < 10MB | jpg/jpeg |\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| exceed_max_filesize |\t輸入檔案大小超過上限 |\n| invalid_parameter |\t參數值無效 |\n| error_download_image\t| 下載來源圖片錯誤 |\n| error_decode_image\t| 解碼來源圖片錯誤 |\n| error_nsfw_content_detected\t| 在來源圖片中偵測到 NSFW 內容 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 擴圖 V2.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_object_removal_pro.yaml","link":"/zh-tw/reference/ai_object_removal_pro","routeSlug":"/zh-tw/reference/ai_object_removal_pro","label":"AI 物件移除","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_object_removal_pro/section/概述","routeSlug":"/zh-tw/reference/ai_object_removal_pro/section/概述","items":[{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_object_removal_pro/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_object_removal_pro/section/概述/點數消耗"}]},{"type":"group","label":"V4.0","link":"/zh-tw/reference/ai_object_removal_pro/v4.0","routeSlug":"/zh-tw/reference/ai_object_removal_pro/v4.0","items":[{"label":"執行 AI 物件移除 任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_object_removal_pro/v4.0/paths/~1s2s~1v2.0~1task~1generative-fill/post","routeSlug":"/zh-tw/reference/ai_object_removal_pro/v4.0/paths/~1s2s~1v2.0~1task~1generative-fill/post","metadata":{"seo":{"title":"執行 AI 物件移除 任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/generative-fill"},{"label":"查詢 AI 物件移除 任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_object_removal_pro/v4.0/paths/~1s2s~1v2.0~1task~1generative-fill~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_object_removal_pro/v4.0/paths/~1s2s~1v2.0~1task~1generative-fill~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 物件移除 任務的狀態。","description":"查詢 AI 物件移除 任務的狀態。"}},"httpPath":"/s2s/v2.0/task/generative-fill/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 物件移除","version":"","description":"# 概述\n透過我們先進的 AI 物件移除 技術，體驗完美無瑕的照片編輯。\n移除人物、倒影與陰影等不想要的元素，同時保留每一處細緻細節。\n上傳您的照片並附上一張簡單的灰階遮罩，即可獲得乾淨自然的外觀結果，提升您的視覺內容品質。\n\n使用範例：\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/YCE_web_relayout_sign_in_index_Object_Removal_b93ad75683.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2026-02-26/webp_6b27a29f-eab0-4205-a69d-d001fffd12ea.jpg)\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 物件移除 | 標準 1 點 <br> 專業 2 點 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_photo_enhance.yaml","link":"/zh-tw/reference/ai_photo_enhance","routeSlug":"/zh-tw/reference/ai_photo_enhance","label":"AI 照片修復","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_photo_enhance/section/概述","routeSlug":"/zh-tw/reference/ai_photo_enhance/section/概述","items":[{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_photo_enhance/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_photo_enhance/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_photo_enhance/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_photo_enhance/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_photo_enhance/v1.0","routeSlug":"/zh-tw/reference/ai_photo_enhance/v1.0","items":[{"label":"執行 AI 照片修復任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_photo_enhance/v1.0/paths/~1s2s~1v2.0~1task~1enhance/post","routeSlug":"/zh-tw/reference/ai_photo_enhance/v1.0/paths/~1s2s~1v2.0~1task~1enhance/post","metadata":{"seo":{"title":"執行 AI 照片修復任務。","description":"這個端點啟動照片修復流程。您必須提供從檔案上傳 API 取得的檔案 ID。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/enhance"},{"label":"查詢 AI 照片修復任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_photo_enhance/v1.0/paths/~1s2s~1v2.0~1task~1enhance~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_photo_enhance/v1.0/paths/~1s2s~1v2.0~1task~1enhance~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 照片修復任務的狀態。","description":"查詢 AI 照片修復任務的狀態。"}},"httpPath":"/s2s/v2.0/task/enhance/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 照片修復","version":"","description":"# 概述\nAI 照片修復運用先進的 AI 與深度學習來分析影像細節並提升解析度，讓低解析度影像變清晰，並修復動態模糊。\n * 不再有顆粒感：消除像素化，獲得更平滑、更明確的影像。\n * 修復模糊照片：移除模糊，呈現更銳利、更清晰的細節。\n * 增強品質：呈現更細緻的細節，讓影像每個部分都突出。\n * 銳化影像：提升清晰度，獲得更清楚、更生動的影像。\n * 改善清晰度：提升整體清晰度，讓照片看起來清新且專業。\n * 臉部增強：精修臉部特徵，在動態影像中獲得更栩栩如生的增強人像。\n\n之前範例：\n![AI Photo Enhance](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_s5_poster_1_0779bbdbdb.jpg \"AI 照片修復\")\n\n之後範例：\n![AI Photo Enhance](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_s5_poster_2_a2e15250ef.jpg \"AI 照片修復\")\n\n\n之前範例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_s2_poster_1_4cd6425807.jpg)\n\n之後範例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_s2_poster_2_7674281362.jpg)\n\n---\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n| AI 功能 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 |\n| ---- | ---- | ----  | ---- |\n| AI 照片修復 | 長邊 <= 4096 | < 10MB | jpg/jpeg/png |\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| exceed_max_filesize |\t輸入檔案大小超過上限 |\n| invalid_parameter |\t參數值無效 |\n| error_download_image\t| 下載來源圖片錯誤 |\n| error_decode_image\t| 解碼來源圖片錯誤 |\n| error_nsfw_content_detected\t| 在來源圖片中偵測到 NSFW 內容 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 照片修復 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_background_removal.yaml","link":"/zh-tw/reference/ai_background_removal","routeSlug":"/zh-tw/reference/ai_background_removal","label":"AI 照片去背","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_background_removal/section/概述","routeSlug":"/zh-tw/reference/ai_background_removal/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_background_removal/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_background_removal/section/概述/整合指南"},{"type":"link","label":"輸入與輸出","link":"/zh-tw/reference/ai_background_removal/section/概述/輸入與輸出","routeSlug":"/zh-tw/reference/ai_background_removal/section/概述/輸入與輸出"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_background_removal/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_background_removal/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_background_removal/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_background_removal/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_background_removal/v1.0","routeSlug":"/zh-tw/reference/ai_background_removal/v1.0","items":[{"label":"執行 AI 照片去背任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_background_removal/v1.0/paths/~1s2s~1v2.0~1task~1sod/post","routeSlug":"/zh-tw/reference/ai_background_removal/v1.0/paths/~1s2s~1v2.0~1task~1sod/post","metadata":{"seo":{"title":"執行 AI 照片去背任務。","description":"這個端點啟動背景移除流程。您必須提供從檔案上傳 API 取得的檔案 ID。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/sod"},{"label":"查詢 AI 照片去背任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_background_removal/v1.0/paths/~1s2s~1v2.0~1task~1sod~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_background_removal/v1.0/paths/~1s2s~1v2.0~1task~1sod~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 照片去背任務的狀態。","description":"查詢 AI 照片去背任務的狀態。"}},"httpPath":"/s2s/v2.0/task/sod/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 照片去背","version":"","description":"# 概述\n以無可挑剔的精準度移除照片背景，確保影像的高品質。\n* 自動背景偵測：：使用 AI 辨識並將主體與背景分離。\n* 高精度編輯：：在主體周圍提供乾淨且精準的邊緣。\n* 支援多種類別：人物、產品、動物、汽車、圖形等。\n* 易於串接其他 AI 任務：輸出的檔案 ID 可即刻串接到其他 AI 任務。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2023-11-03/54285311-7c65-4658-9e27-11bf5c8dfe56.jpg)\n\n## 整合指南\n* 如何執行 AI 照片去背\n1. **調整來源圖片尺寸**</br>\n  調整您的照片以符合支援的尺寸。細節請參考**[檔案規格與錯誤](#section/overview/File-Specs-and-Errors)**\n\n2. **使用 File API 上傳檔案**</br>\n  使用 ***/s2s/v2.0/file*** API 上傳目標使用者圖片。\n    - 圖片需求\n      - 細節請參考**[檔案規格與錯誤](#section/overview/File-Specs-and-Errors)**。\n    - ***重要***：僅呼叫 File API 並不會上傳您的檔案。您必須**手動上傳**檔案到**File API 回應中提供的網址**。該網址就是您的上傳目的地，請確保檔案成功傳輸到該處後再繼續。<br>\n    在呼叫 AI API 之前，請確保您的檔案已成功上傳。使用 File API 取得上傳網址，然後將檔案上傳到該位置。上傳完成後，您會在回應中取得 ***file_id***，這個 ID 就是您用於存取該檔案相關 AI 功能的依據。\n    \n      > **警告：** 請注意，若您未將檔案上傳到 File API 回應中提供的網址，使用 AI API 時會得到 500 Server Error / unknown_internal_error 或 404 Not Found 錯誤。\n\n3. **執行 AI 任務**</br>\n  上傳完成後，使用檔案 ID 呼叫 POST 'task/sod' 執行 AI 任務，並取得用於監控的 ***task_id***。\n\n4. **設定 webhook 或輪詢，以查詢任務狀態直到成功或錯誤**</BR>\n***task_id*** 用於設定 webhook 或實作輪詢，在整個保留期間監控任務狀態。在 AI 引擎完成任務之前，狀態會維持為 running。任務處於執行狀態時不會消耗點數。處理完成後，任務狀態會變為 success 或 error。\n\n1. **成功後取得 AI 任務的結果**</BR>\n引擎成功處理您的輸入檔案並生成結果影像後，任務會變為 'success' 狀態。您會取得處理後影像的網址，以及一個 dst_id，讓您在無需重新上傳結果圖片的情況下串接另一個 AI 任務。\n點數僅在這種情況下會被消耗。若引擎處理任務失敗，任務狀態會變為 'error'，且不會消耗點數。</BR>\n扣除點數時，系統會優先使用接近到期的點數。若到期日相同，則扣除最早取得的點數。\n\n* 示範情境：\n常見實作案例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Transparen_Background_aca3cdbd83.jpg)\n\n## 輸入與輸出\n* 輸入\n   * `Image`\n- **類型：** `image`\n- **說明：** 具有清晰前景的影像。\n\n實際應用（輸入）： \n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_removal_bg_s4_poster_1_289b8eaf81.png)\n\n---\n\n* 輸出\n   * `前景圖片`\n- **類型：** `image`\n- **說明：** 已移除背景的影像。\n\n實際應用（輸出）：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_removal_bg_s4_poster_2_a6bc3c5f6a.png)\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|檔案大小|接受的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 照片去背|輸入與輸出圖片的建議與限制如下：</br>解析度：4096 × 4096 像素（最長邊不得超過 4096 像素）|<10MB|JPG 與 PNG|\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_hair_too_short|輸入的頭髮過短|\n|error_unexpected_video_duration|影片長度等於 dstDuration|\n|error_bald_image|輸入的髮型為禿頭|\n|error_unsupport_ratio|輸入圖片的長寬比不受支援|\n|unknown_internal_error|其他|\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 照片去背 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_photo_colorize.yaml","link":"/zh-tw/reference/ai_photo_colorize","routeSlug":"/zh-tw/reference/ai_photo_colorize","label":"AI 照片上色","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_photo_colorize/section/概述","routeSlug":"/zh-tw/reference/ai_photo_colorize/section/概述","items":[{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_photo_colorize/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_photo_colorize/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_photo_colorize/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_photo_colorize/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_photo_colorize/v1.0","routeSlug":"/zh-tw/reference/ai_photo_colorize/v1.0","items":[{"label":"執行 AI 照片上色任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_photo_colorize/v1.0/paths/~1s2s~1v2.0~1task~1colorize/post","routeSlug":"/zh-tw/reference/ai_photo_colorize/v1.0/paths/~1s2s~1v2.0~1task~1colorize/post","metadata":{"seo":{"title":"執行 AI 照片上色任務。","description":"查詢任務狀態請參考輪詢指南。"}},"httpPath":"/s2s/v2.0/task/colorize"},{"label":"查詢 AI 照片上色任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_photo_colorize/v1.0/paths/~1s2s~1v2.0~1task~1colorize~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_photo_colorize/v1.0/paths/~1s2s~1v2.0~1task~1colorize~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 照片上色任務的狀態。","description":"查詢 AI 照片上色任務的狀態。"}},"httpPath":"/s2s/v2.0/task/colorize/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 照片上色","version":"","description":"# 概述\n使用最新的 AI 技術為黑白照片、舊影像上色，或進行修復。透過 AI 照片上色，您可以即刻生成 4 種不同上色版本的照片，每種都有從暖到冷的獨特色調。運用深度學習技術，此工具在數秒內將您的黑白照片轉化為鮮豔的彩色影像。\n\n![AI Photo Colorize](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_colorize_s4_poster_11c0bdfead.jpg \"AI 照片上色\")\n\n---\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n| AI 功能 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 |\n| ---- | ---- | ----  | ---- |\n| AI 照片上色 | 長邊 <= 4096 | < 10MB | jpg/jpeg/png |\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| exceed_max_filesize |\t輸入檔案大小超過上限 |\n| invalid_parameter |\t參數值無效 |\n| error_download_image\t| 下載來源圖片錯誤 |\n| error_decode_image\t| 解碼來源圖片錯誤 |\n| error_nsfw_content_detected\t| 在來源圖片中偵測到 NSFW 內容 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 照片上色 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_photo_lighting.yaml","link":"/zh-tw/reference/ai_photo_lighting","routeSlug":"/zh-tw/reference/ai_photo_lighting","label":"AI 照片打光","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_photo_lighting/section/概述","routeSlug":"/zh-tw/reference/ai_photo_lighting/section/概述","items":[{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_photo_lighting/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_photo_lighting/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_photo_lighting/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_photo_lighting/section/概述/點數消耗"}]},{"type":"group","label":"V2.0","link":"/zh-tw/reference/ai_photo_lighting/v2.0","routeSlug":"/zh-tw/reference/ai_photo_lighting/v2.0","items":[{"label":"執行 AI 照片打光任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_photo_lighting/v2.0/paths/~1s2s~1v2.0~1task~1lighting/post","routeSlug":"/zh-tw/reference/ai_photo_lighting/v2.0/paths/~1s2s~1v2.0~1task~1lighting/post","metadata":{"seo":{"title":"執行 AI 照片打光任務。","description":"查詢任務狀態請參考輪詢指南。"}},"httpPath":"/s2s/v2.0/task/lighting"},{"label":"查詢 AI 照片打光任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_photo_lighting/v2.0/paths/~1s2s~1v2.0~1task~1lighting~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_photo_lighting/v2.0/paths/~1s2s~1v2.0~1task~1lighting~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 照片打光任務的狀態。","description":"查詢 AI 照片打光任務的狀態。"}},"httpPath":"/s2s/v2.0/task/lighting/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 照片打光","version":"","description":"# 概述\n用我們的 AI 影像增亮工具輕鬆提升影像亮度。憑藉卓越的 AI 技術，點亮您選擇的任何影像。\n用我們的 AI 照片打光工具提亮您昏暗的照片或影像，瞬間點亮您的回憶。\n\n之前\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_lighting_v3_poster_1_b7d976b686.jpg)\n之後\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_lighting_v3_poster_2_79d3be33bc.jpg)\n用 AI 工具輕鬆提亮低光照片，呈現令人驚豔的細節與鮮豔色彩。\n\n\n\n之前\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_lighting_v6_poster_1_2422530612.jpg)\n之後\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_lighting_v6_poster_2_63f1ecc244.jpg)\n用 AI 光影工具提亮您的產品照片，呈現引人入勝且令人驚豔的效果。\n\n---\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n| AI 功能 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 |\n| ---- | ---- | ----  | ---- |\n| AI 照片打光 | 長邊 <= 4096 | < 10MB | jpg/jpeg/png |\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| exceed_max_filesize |\t輸入檔案大小超過上限 |\n| invalid_parameter |\t參數值無效 |\n| error_download_image\t| 下載來源圖片錯誤 |\n| error_decode_image\t| 解碼來源圖片錯誤 |\n| error_nsfw_content_detected\t| 在來源圖片中偵測到 NSFW 內容 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 照片打光 V2.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_color_correction.yaml","link":"/zh-tw/reference/ai_color_correction","routeSlug":"/zh-tw/reference/ai_color_correction","label":"AI 色彩校正","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_color_correction/section/概述","routeSlug":"/zh-tw/reference/ai_color_correction/section/概述","items":[{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_color_correction/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_color_correction/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_color_correction/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_color_correction/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_color_correction/v1.0","routeSlug":"/zh-tw/reference/ai_color_correction/v1.0","items":[{"label":"執行 AI 照片色彩校正任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_color_correction/v1.0/paths/~1s2s~1v2.0~1task~1colorize~1color-correct/post","routeSlug":"/zh-tw/reference/ai_color_correction/v1.0/paths/~1s2s~1v2.0~1task~1colorize~1color-correct/post","metadata":{"seo":{"title":"執行 AI 照片色彩校正任務。","description":"查詢任務狀態請參考輪詢指南。"}},"httpPath":"/s2s/v2.0/task/colorize/color-correct"},{"label":"查詢 AI 照片色彩校正任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_color_correction/v1.0/paths/~1s2s~1v2.0~1task~1colorize~1color-correct~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_color_correction/v1.0/paths/~1s2s~1v2.0~1task~1colorize~1color-correct~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 照片色彩校正任務的狀態。","description":"查詢 AI 照片色彩校正任務的狀態。"}},"httpPath":"/s2s/v2.0/task/colorize/color-correct/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 色彩校正","version":"","description":"# 概述\n完善的 AI 色彩校正可讓您輕鬆自動調整照片的飽和度、色溫與色調。調整白平衡以校正色溫、增強飽和度使其鮮豔、校正曝光以平衡亮度、移除色偏或色調、改善膚色以呈現自然的肖像、強化陰影與高光細節、去除雜訊並提升清晰度，甚至一鍵套用創意的調色效果。使用 AI 色彩校正，您可以在數秒內立即生成 4 種不同調色版本的照片，每種都有從暖到冷的獨特色調。\n\n範例\n之前：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/color_correction_topbanner_before_dt_100_45429e8625.jpg)\n\n之後：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/color_correction_topbanner_after_dt_100_ef9f9c48ed.jpg)\n\n\n\n之前：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/color_correction_s1_image_before_dt_fa73b5d41a.jpg)\n\n之後\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/color_correction_s1_image_after_dt_a3e88a101b.jpg)\n\n\n---\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n| AI 功能 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 |\n| ---- | ---- | ----  | ---- |\n| AI 色彩校正 | 長邊 <= 4096 | < 10MB | jpg/jpeg/png |\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| exceed_max_filesize |\t輸入檔案大小超過上限 |\n| invalid_parameter |\t參數值無效 |\n| error_download_image\t| 下載來源圖片錯誤 |\n| error_decode_image\t| 解碼來源圖片錯誤 |\n| error_nsfw_content_detected\t| 在來源圖片中偵測到 NSFW 內容 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 色彩校正 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_photo_background_change.yaml","link":"/zh-tw/reference/ai_photo_background_change","routeSlug":"/zh-tw/reference/ai_photo_background_change","label":"AI 圖片換背景","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_photo_background_change/section/概述","routeSlug":"/zh-tw/reference/ai_photo_background_change/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_photo_background_change/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_photo_background_change/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_photo_background_change/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_photo_background_change/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_photo_background_change/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_photo_background_change/section/概述/點數消耗"}]},{"type":"group","label":"V2.0","link":"/zh-tw/reference/ai_photo_background_change/v2.0","routeSlug":"/zh-tw/reference/ai_photo_background_change/v2.0","items":[{"label":"列出預先定義的 AI 圖片換背景 V2 範本。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_photo_background_change/v2.0/paths/~1s2s~1v2.0~1task~1template~1bg-replace/get","routeSlug":"/zh-tw/reference/ai_photo_background_change/v2.0/paths/~1s2s~1v2.0~1task~1template~1bg-replace/get","metadata":{"seo":{"title":"列出預先定義的 AI 圖片換背景 V2 範本。","description":"列出預先定義的 AI 圖片換背景 V2 範本。"}},"httpPath":"/s2s/v2.0/task/template/bg-replace"},{"label":"執行 AI 圖片換背景 V2 任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_photo_background_change/v2.0/paths/~1s2s~1v2.0~1task~1bg-replace/post","routeSlug":"/zh-tw/reference/ai_photo_background_change/v2.0/paths/~1s2s~1v2.0~1task~1bg-replace/post","metadata":{"seo":{"title":"執行 AI 圖片換背景 V2 任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/bg-replace"},{"label":"查詢 AI 圖片換背景 V2 任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_photo_background_change/v2.0/paths/~1s2s~1v2.0~1task~1bg-replace~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_photo_background_change/v2.0/paths/~1s2s~1v2.0~1task~1bg-replace~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 圖片換背景 V2 任務的狀態。","description":"查詢 AI 圖片換背景 V2 任務的狀態。"}},"httpPath":"/s2s/v2.0/task/bg-replace/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 圖片換背景","version":"","description":"# 概述\nAI 圖片換背景 API 透過將主體與原始背景隔離來增強影像，支援廣泛的應用，包括商業中以產品為中心的應用案例。\n\n這個 API 讓開發者使用自訂提示詞或預先定義的範本更換背景。\n\n**使用範例**\n\n之前：\n![](https://yce.makeupar.com/assets/images/sod/banner/change/yce-topbanner-dt-before.jpg)\n\n之後：\n![](https://yce.makeupar.com/assets/images/sod/banner/change/yce-topbanner-dt-after.jpg)\n\n\n之前：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_change_bg_s5_poster_before_0753db3e02.jpg)\n\n之後：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_change_bg_s5_poster_after_7fb288fde2.jpg)\n\n---\n\n## 整合指南\n\n**1. 上傳圖片**\n\n透過以下方式請求上傳網址與檔案 ID：\n\n```\nPOST /s2s/v2.0/file\n```\n\n使用回傳的網址上傳圖片。\n或者，提供託管在您自有儲存空間、可公開存取的圖片網址。\n\n\n**2. 準備背景描述提示詞，或選擇背景範本。**\n\n```\nGET /s2s/v2.0/task/template/bg-replace\n```\n\n取得預先定義的背景範本清單，並以其 template_id 選擇其一。使用 prompt（預設）時，背景會依據提供的提示詞生成。使用 template 時，背景會由 template_id 指定的預先定義範本生成，prompt 參數將被忽略。\n\n\n**3. 執行分析任務**\n\n```\nPOST /s2s/v2.0/task/bg-replace\n```\n\n使用檔案 ID 或圖片網址作為輸入，並附上理想的背景提示詞，提交任務。\n回應會回傳 task_id 用於追蹤與取得結果。\n\n\n**4. 取得任務結果**\n\n```\nGET /s2s/v2.0/task/bg-replace/{task_id}\n```\n\n使用任務 ID 追蹤狀態並得結\n\n可設定 [Webhooks](/develop/webhook.md) 在任務完成時接收非同步通知，狀態為 success 或 error。也支援輪詢，重複呼叫任務端點直到狀態從 running 更新為 success 或 error。\n\n僅在任務成功完成時才計費。\n\n---\n\n## 檔案規格與錯誤\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n| AI 圖片換背景 | 較長邊不得超過 4096 像素。 | < 10MB | jpg/jpeg/png |\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| exceed_max_filesize |\t輸入檔案大小超過允許的上限。 |\n| size_mismatch_on_input_image_and_mask | 輸入圖片尺寸必須與輸入遮罩圖片的尺寸相符。 |\n| invalid_parameter | 參數值無效。請求參數缺失、格式無效，或包含不支援的值。|\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 圖片換背景 V2.0 | 4 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_photo_background_blur.yaml","link":"/zh-tw/reference/ai_photo_background_blur","routeSlug":"/zh-tw/reference/ai_photo_background_blur","label":"AI 模糊背景","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_photo_background_blur/section/概述","routeSlug":"/zh-tw/reference/ai_photo_background_blur/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_photo_background_blur/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_photo_background_blur/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_photo_background_blur/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_photo_background_blur/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_photo_background_blur/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_photo_background_blur/section/概述/點數消耗"}]},{"type":"group","label":"V2.0","link":"/zh-tw/reference/ai_photo_background_blur/v2.0","routeSlug":"/zh-tw/reference/ai_photo_background_blur/v2.0","items":[{"label":"執行 AI 模糊背景任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_photo_background_blur/v2.0/paths/~1s2s~1v2.0~1task~1bg-blur/post","routeSlug":"/zh-tw/reference/ai_photo_background_blur/v2.0/paths/~1s2s~1v2.0~1task~1bg-blur/post","metadata":{"seo":{"title":"執行 AI 模糊背景任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/bg-blur"},{"label":"查詢 AI 模糊背景任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_photo_background_blur/v2.0/paths/~1s2s~1v2.0~1task~1bg-blur~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_photo_background_blur/v2.0/paths/~1s2s~1v2.0~1task~1bg-blur~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 模糊背景任務的狀態。","description":"查詢 AI 模糊背景任務的狀態。"}},"httpPath":"/s2s/v2.0/task/bg-blur/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 模糊背景","version":"","description":"# 概述\n淺景深（bokeh）效果是一種受歡迎的攝影技術，用於模糊照片背景並讓主體對焦。它為照片增添藝術氣息，使其看起來更專業且吸睛。\n\n用 AI 模糊背景 API 創造專業外觀的照片，它自動隔離主體並套用自然的背景模糊，將注意力引導到最重要的地方。\n\n\n**使用情境範例：**\n\n* 人像增強\n套用自然的淺景深效果，讓主體突出，並提升個人頭像或人像照片的視覺品質。\n\n    之前：\n    ![](https://yce.makeupar.com/assets/images/sod/banner/blur/yce-topbanner-dt-before.jpg)\n\n    之後：\n    ![](https://yce.makeupar.com/assets/images/sod/banner/blur/yce-topbanner-dt-after.jpg)\n\n* 專業形象照\n從一般照片創造類攝影棚的背景模糊效果，用於商務個人檔案與企業目錄。\n\n    之前：\n    ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_blur_bg_s3_poster_1_50a314e3f9.jpg)\n\n    之後：\n    ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_blur_bg_s3_poster_2_afb0548cb7.jpg)\n\n---\n\n## 整合指南\n\n**輸入需求與處理標準：**\n\n- 上傳包含清晰、顯著前景主體的圖片。\n- 圖片最長邊不得超過 **4,096 px**。\n- 來源檔案大小必須低於 **10 MB**。\n- 至少需要一位清晰可見的前景主體。\n- 僅支援單主體分析。若出現多人，API 會自動選擇可見面積最大的主體。\n\n\n**工作流程：**\n\n1. 呼叫 File API。\n2. 從回應中取得簽名的上傳網址。\n3. 將實際圖片上傳到回傳的網址。\n4. 建立 AI 任務。\n5. 設定 Webhook 或輪詢任務狀態直到完成。\n6. 處理成功後下載生成的結果圖片。\n\n---\n\n**步驟 1 — 使用 File API 上傳檔案 metadata**\n\n使用 `POST /s2s/v2.0/file` 建立檔案記錄，並取得來源圖片的上傳細節。\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/file \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"files\": [\n      {\n        \"content_type\": \"image/jpg\",\n        \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\n        \"file_size\": 547541\n      }\n    ]\n  }'\n```\n\n**File API 回應範例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"files\": [\n      {\n        \"content_type\": \"image/jpg\",\n        \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\n        \"file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n        \"requests\": [\n          {\n            \"method\": \"PUT\",\n            \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\",\n            \"headers\": {\n              \"Content-Length\": \"547541\",\n              \"Content-Type\": \"image/jpg\"\n            }\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n---\n\n**步驟 2 — 取得 File API 回應細節**\n\n回應包含：\n\n| 欄位 | 說明 |\n| --- | --- |\n| `file_id` | 用於建立 AI 任務的識別碼。 |\n| `requests.url` | 用於上傳實際圖片檔案的簽名網址。 |\n| `requests.method` | 上傳方法，通常為 `PUT`。 |\n| `requests.headers` | 上傳請求所需的標頭。 |\n\n---\n\n**步驟 3 — 上傳圖片到提供的網址**\n\n使用 File API 回應中的 `requests.url` 上傳來源圖片。\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n  --header 'Content-Type: image/jpg' \\\n  --header 'Content-Length: 547541' \\\n  --data-binary @'./full_body_photo_01_3dbd1b6683.jpg'\n```\n\n---\n\n**步驟 4 — 建立 AI 任務**\n\n使用 `POST /s2s/v2.0/task/bg-blur` 建立 AI 任務。\n\n| 參數 | 說明 | 範例 |\n| --- | --- | --- |\n| `src_file_id` | 從 File API 上傳流程回傳的檔案 ID。使用上傳檔案工作流程時為必要。 | `\"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\"` |\n| `src_file_url` | 來源圖片的直接網址。作為 `src_file_id` 的替代方案。 | `\"https://example.com/selfie.jpg\"` |\n| `intensity` | 模糊強度。0 代表不模糊，100 代表最大模糊。 | 50 |\n\n**請求範例：**\n\n```javascript\nconst resp = await fetch(\n  'https://yce-api-01.makeupar.com/s2s/v2.0/task/bg-blur',\n  {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/json',\n      Authorization: 'Bearer <YOUR_TOKEN_HERE>'\n    },\n    body: JSON.stringify({\n      src_file_url: 'https://example.com/selfie.jpg',\n      intensity: 50\n    })\n  }\n);\n\nconst data = await resp.json();\nconsole.log(data);\n```\n\n**AI 任務 API 回應：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT\"\n  }\n}\n```\n\n---\n\n**步驟 5 — 設定ebhook 或輪詢任務結果**\n\n設定與驗證細節請參考 [webhook 整合指南](/develop/webhook.md)。\n\n輪詢時，使用回傳的 `task_id` 查詢任務狀態。\n\n```bash\ncurl --request GET \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/bg-blur/<YOUR_TASK_ID> \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json'\n```\n\n---\n\n**步驟 6 — 取得結果圖片**\n\n處理成功時，回應會在 `data.results.url` 中包含下載網址。\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"error\": null,\n    \"results\": {\n      \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n    },\n    \"task_status\": \"success\"\n  }\n}\n```\n\n**API Key 無效的回應：**\n\n若 access token 無效，API 會回傳 `401` 回應。\n\n```json\n{\n  \"status\": 401,\n  \"error\": \"Unauthorized\",\n  \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\n## 檔案規格與錯誤\n\n**檔案規格：**\n\n| 規格 | 需求 |\n| --- | --- |\n| 圖片類型 | 圖片必須包含一位清晰且顯著的前景主體或人物。 |\n| 長邊解析度上限 | 長邊不得超過 **4096 px**。 |\n| 檔案大小限制 | 必須低於 **10 MB**。 |\n| 支援的格式 | `jpg`、`png`。 |\n\n**錯誤代碼：**\n\n| 錯誤代碼 | 說明 |\n| --- | --- |\n| `exceed_max_filesize` | 來源圖片超過允許的最大尺寸或檔案大小。長邊不得超過 4096 px，檔案大小必須低於 10 MB。 |\n| `error_nsfw_content_detected` | 在來源圖片或生成的結果圖片中偵測到潛在的 NSFW 內容。 |\n| `invalid_parameter` | 來源鍵、目標鍵、動作、模式值、強度等級或任務設定提供了無效的參數。 |\n| `error_download_image` | 無法成功下載來源圖片。 |\n| `error_decode_image` | 無法成功解碼來源圖片。 |\n\n**環境與相依性：**\n\n| 工具 / 語言 | 建議的執行環境版本 |\n| --- | --- |\n| cURL | Bash ≥ 3.2；curl ≥ 7.58（具現代 TLS/HTTP 支援）；jq ≥ 1.6（穩健的 JSON 解析）。 |\n| Node.js | Node ≥ 18（支援全域 `fetch`）。 |\n| JavaScript 瀏覽器支援 | Chrome / Edge ≥ 80、Firefox ≥ 74、Safari ≥ 13.1。 |\n| PHP | PHP ≥ 7.4（具現代 TLS 相容性）；建議 ext-curl，或 `allow_url_fopen=On` 並具備 OpenSSL 與 JSON 支援。 |\n| Python | Python ≥ 3.10（支援 f-strings）；requests ≥ 2.20.0。 |\n| Java | Java 11+（支援 HttpClient）；Jackson Databind ≥ 2.12.0。 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 模糊背景 V2.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_replace.yaml","link":"/zh-tw/reference/ai_replace","routeSlug":"/zh-tw/reference/ai_replace","label":"AI 替換物件","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_replace/section/概述","routeSlug":"/zh-tw/reference/ai_replace/section/概述","items":[{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_replace/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_replace/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_replace/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_replace/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_replace/v1.0","routeSlug":"/zh-tw/reference/ai_replace/v1.0","items":[{"label":"執行 AI 替換物件任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_replace/v1.0/paths/~1s2s~1v2.0~1task~1obj-replace/post","routeSlug":"/zh-tw/reference/ai_replace/v1.0/paths/~1s2s~1v2.0~1task~1obj-replace/post","metadata":{"seo":{"title":"執行 AI 替換物件任務。","description":"查詢任務狀態請參考輪詢指南。這個 API 需要來源照片、遮罩檔案，以及描述應替換遮罩區域內容的提示。"}},"httpPath":"/s2s/v2.0/task/obj-replace"},{"label":"查詢 AI 替換物件任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_replace/v1.0/paths/~1s2s~1v2.0~1task~1obj-replace~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_replace/v1.0/paths/~1s2s~1v2.0~1task~1obj-replace~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 替換物件任務的狀態。","description":"查詢 AI 替換物件任務的狀態。"}},"httpPath":"/s2s/v2.0/task/obj-replace/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 替換物件","version":"","description":"# 概述\n使用 AI 替換物件，以新物件取代不想要的元素。透過這個 API，您可以僅用文字，即刻從照片中移除不想要的物件並換成新的。從包包到汽車，任何物件都能移除。​\n\n範例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_replace_S3_feature_img_02_a73a26bcc3.jpg)\n\n\n對於力求完善社群媒體表現的內容創作者，AI 替換物件提供了輕鬆無礙的方式，來潤飾旅行照片或宣傳圖片。輕鬆移除並替換元素，確保您的內容脫穎而出。\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_replace_S3_feature_img_03_42c9cd98d0.jpg)\n\n\n使用 AI 替換物件創造令人驚豔的房間模擬圖，以具美感的家具與物件填滿空閒空間，改變任何空間的視覺感受。\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_replace_S3_feature_img_04_4d2d82f76e.jpg)\n\n---\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n| AI 功能 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 |\n| ---- | ---- | ----  | ---- |\n| AI 替換物件 | 長邊 <= 2048 | < 10MB | jpg/jpeg/png |\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| exceed_max_filesize |\t輸入檔案大小超過上限 |\n| invalid_parameter |\t參數值無效 |\n| error_download_image\t| 下載來源圖片錯誤 |\n| error_decode_image\t| 解碼來源圖片錯誤 |\n| error_nsfw_content_detected\t| 在來源圖片中偵測到 NSFW 內容 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 替換物件 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_avatar_generator.yaml","link":"/zh-tw/reference/ai_avatar_generator","routeSlug":"/zh-tw/reference/ai_avatar_generator","label":"AI 虛擬化身","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_avatar_generator/section/概述","routeSlug":"/zh-tw/reference/ai_avatar_generator/section/概述","items":[{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_avatar_generator/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_avatar_generator/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_avatar_generator/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_avatar_generator/section/概述/點數消耗"}]},{"type":"group","label":"V3.0","link":"/zh-tw/reference/ai_avatar_generator/v3.0","routeSlug":"/zh-tw/reference/ai_avatar_generator/v3.0","items":[{"label":"列出預先定義的範本。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_avatar_generator/v3.0/paths/~1s2s~1v2.0~1task~1template~1ai-avatar/get","routeSlug":"/zh-tw/reference/ai_avatar_generator/v3.0/paths/~1s2s~1v2.0~1task~1template~1ai-avatar/get","metadata":{"seo":{"title":"列出預先定義的範本。","description":"列出預先定義的範本。"}},"httpPath":"/s2s/v2.0/task/template/ai-avatar"},{"label":"執行 AI 頭像任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_avatar_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-avatar/post","routeSlug":"/zh-tw/reference/ai_avatar_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-avatar/post","metadata":{"seo":{"title":"執行 AI 頭像任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/ai-avatar"},{"label":"查詢 AI 頭像任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_avatar_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-avatar~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_avatar_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-avatar~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 頭像任務的狀態。","description":"查詢 AI 頭像任務的狀態。"}},"httpPath":"/s2s/v2.0/task/ai-avatar/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 虛擬化身","version":"","description":"# 概述\nAI 魔法頭像工具使用 image-to-image 技術，也就是頭像根據您的照片生成。當使用者選取照片後，應用中內嵌的技術便開始分析並學習使用者的臉部特徵。\n\n更多頭像風格，請參考 https://yce.makeupar.com/avatar\n\n應用案例：\n![AI Avatar Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Christmas_Avatar_b861c35edf.jpg \"AI 虛擬化身\")\n\n![AI Avatar Generator](https://plugins-media.makeupar.com/smb/blog/post/2023-04-06/fc2c3b2e-2b7f-48c9-96c1-cdb780f9dc1d.jpg \"AI 虛擬化身\")\n\n\n拍攝建議：\n![拍攝建議](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png \"拍攝建議\")\n\n---\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n| AI 功能 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 |\n| ---- | ---- | ----  | ---- |\n| AI 虛擬化身 | 輸入：長邊 <= 4096，輸出：長邊 <= 1024 | < 10MB | jpg/jpeg/png |\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| exceed_max_filesize |\t輸入檔案大小超過上限 |\n| invalid_parameter |\t參數值無效 |\n| error_download_image\t| 下載來源圖片錯誤 |\n| error_decode_image\t| 解碼來源圖片錯誤 |\n| error_nsfw_content_detected\t| 在來源圖片中偵測到 NSFW 內容 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 虛擬化身 V3.0 | 4 張圖片 1 點 * |\n\n    > *若圖片數量或影片長度無法整除，點數無條件進位。\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_headshot_generator.yaml","link":"/zh-tw/reference/ai_headshot_generator","routeSlug":"/zh-tw/reference/ai_headshot_generator","label":"AI 形象照","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_headshot_generator/section/概述","routeSlug":"/zh-tw/reference/ai_headshot_generator/section/概述","items":[{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_headshot_generator/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_headshot_generator/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_headshot_generator/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_headshot_generator/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_headshot_generator/v1.0","routeSlug":"/zh-tw/reference/ai_headshot_generator/v1.0","items":[{"label":"列出預先定義的範本。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_headshot_generator/v1.0/paths/~1s2s~1v2.0~1task~1template~1headshot/get","routeSlug":"/zh-tw/reference/ai_headshot_generator/v1.0/paths/~1s2s~1v2.0~1task~1template~1headshot/get","metadata":{"seo":{"title":"列出預先定義的範本。","description":"列出預先定義的範本。"}},"httpPath":"/s2s/v2.0/task/template/headshot"},{"label":"執行 AI 形象照任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_headshot_generator/v1.0/paths/~1s2s~1v2.0~1task~1headshot/post","routeSlug":"/zh-tw/reference/ai_headshot_generator/v1.0/paths/~1s2s~1v2.0~1task~1headshot/post","metadata":{"seo":{"title":"執行 AI 形象照任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/headshot"},{"label":"查詢 AI 形象照任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_headshot_generator/v1.0/paths/~1s2s~1v2.0~1task~1headshot~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_headshot_generator/v1.0/paths/~1s2s~1v2.0~1task~1headshot~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 形象照任務的狀態。","description":"查詢 AI 形象照任務的狀態。"}},"httpPath":"/s2s/v2.0/task/headshot/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 形象照","version":"","description":"# 概述\n用我們的 AI 形象照，將您的照片轉換為令人驚豔的專業形象照。運用我們強大的 AI 工具，快速有效地提升您的形象照，提供專業品質的結果。\n* 多元風格：從精緻的 LinkedIn 形象照、專業商務形象照，到創意模特兒形象照，我們的 AI 形象照幫助您選擇最適合需求的完美外觀。\n* 專業結果：運用 AI 確保您的形象照自然且得體，給潛在雇主與客戶留下深刻印象。\n* 便利：隨時隨地生成多張 AI 形象照，無需攝影師。最適合忙碌的專業人士。\n\n更多 AI 商務形象照風格，請參考 https://yce.makeupar.com/ai-headshot-generator。\n\n應用案例：\n![AI Headshot Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_headshot_s2_img_03_4b55742358.jpg \"AI 形象照\")\n\n![AI Headshot Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_headshot_s1_img_1_d03183d7e0.jpg \"AI 形象照\")\n\n\n拍攝建議：\n![拍攝建議](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png \"拍攝建議\")\n\n\n---\n\n## 檔案規格與錯誤\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n| AI 形象照 | 請確保輸入圖片包含單人，且 OpenPose 可見兩側肩膀點與完整臉部，短邊 ≤ 1024 像素——否則引擎會自動調整為 1024。輸出：長邊 <= 1024 | < 10MB | jpg/jpeg/png |\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| exceed_max_filesize |\t輸入檔案大小超過上限 |\n| invalid_parameter |\t參數值無效 |\n| error_download_image\t| 下載來源圖片錯誤 |\n| error_decode_image\t| 解碼來源圖片錯誤 |\n| error_nsfw_content_detected\t| 在來源圖片中偵測到 NSFW 內容 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 形象照 V1.0 | 2 張圖片 1 點 * |\n\n    > *若圖片數量或影片長度無法整除，點數無條件進位。\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_studio_generator.yaml","link":"/zh-tw/reference/ai_studio_generator","routeSlug":"/zh-tw/reference/ai_studio_generator","label":"AI 攝影棚","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_studio_generator/section/概述","routeSlug":"/zh-tw/reference/ai_studio_generator/section/概述","items":[{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_studio_generator/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_studio_generator/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_studio_generator/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_studio_generator/section/概述/點數消耗"}]},{"type":"group","label":"V3.0","link":"/zh-tw/reference/ai_studio_generator/v3.0","routeSlug":"/zh-tw/reference/ai_studio_generator/v3.0","items":[{"label":"列出預先定義的範本。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_studio_generator/v3.0/paths/~1s2s~1v2.0~1task~1template~1ai-studio/get","routeSlug":"/zh-tw/reference/ai_studio_generator/v3.0/paths/~1s2s~1v2.0~1task~1template~1ai-studio/get","metadata":{"seo":{"title":"列出預先定義的範本。","description":"列出預先定義的範本。"}},"httpPath":"/s2s/v2.0/task/template/ai-studio"},{"label":"執行 AI 攝影棚任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_studio_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-studio/post","routeSlug":"/zh-tw/reference/ai_studio_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-studio/post","metadata":{"seo":{"title":"執行 AI 攝影棚任務。","description":"查詢任務狀態請參考輪詢指南。需要來源照片、範本 ID 與輸出數量設定。"}},"httpPath":"/s2s/v2.0/task/ai-studio"},{"label":"查詢 AI 攝影棚任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_studio_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-studio~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_studio_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-studio~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 攝影棚任務的狀態。","description":"查詢 AI 攝影棚任務的狀態。"}},"httpPath":"/s2s/v2.0/task/ai-studio/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 攝影棚","version":"","description":"# 概述\n體驗 AI 攝影棚的卓越品質。瞬間將您的自拍轉化為攝影棚級別的人像照​。\n* 免攝影棚的便利：無需攝影師或前往攝影棚——隨時隨地創造攝影棚級別的藝術照片​\n* 快速照片轉換：快速處理，立即獲得高品質的藝術照片結果，最適合快速更新\n* 高品質藝術輸出：提供專業標準的藝術照片，細節清晰、光線完美，就像您在攝影棚拍攝一樣 \n\n應用案例：\n![AI Studio Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_studio_S1_img_19b627b6af.jpg \"AI 攝影棚\")\n\n![AI Studio Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_studio_S2_img_01_2e318817e9.jpg \"AI 攝影棚\")\n\n\n拍攝建議：\n![拍攝建議](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png \"拍攝建議\")\n\n\n---\n\n## 檔案規格與錯誤\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n|AI 攝影棚|請確保輸入圖片有一張臉部，短邊至少 200 像素，長邊不超過 1920 像素；若有多張臉部，引擎會選擇最大的臉部，輸出解析度不會超過 960×1280（W×H）|< 10MB|jpg/jpeg/png|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n|error_below_min_image_size\t|輸入圖片解析度過小|\n|error_exceed_max_image_size\t|輸入圖片解析度過大|\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 攝影棚 V3.0 | 2 張圖片 1 點 * |\n\n    > *若圖片數量或影片長度無法整除，點數無條件進位。\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_image_generator.yaml","link":"/zh-tw/reference/ai_image_generator","routeSlug":"/zh-tw/reference/ai_image_generator","label":"AI 文字生成圖片","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_image_generator/section/概述","routeSlug":"/zh-tw/reference/ai_image_generator/section/概述","items":[{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_image_generator/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_image_generator/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_image_generator/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_image_generator/section/概述/點數消耗"}]},{"type":"group","label":"V2.0","link":"/zh-tw/reference/ai_image_generator/v2.0","routeSlug":"/zh-tw/reference/ai_image_generator/v2.0","items":[{"label":"執行用於文字轉影像的 AI 文字生成圖片任務 V2。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-image~1youcam/post","routeSlug":"/zh-tw/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-image~1youcam/post","metadata":{"seo":{"title":"執行用於文字轉影像的 AI 文字生成圖片任務 V2。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/text-to-image/youcam"},{"label":"查詢用於文字轉影像的 AI 文字生成圖片任務 V2 的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-image~1youcam~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-image~1youcam~1{task_id}/get","metadata":{"seo":{"title":"查詢用於文字轉影像的 AI 文字生成圖片任務 V2 的狀態。","description":"查詢用於文字轉影像的 AI 文字生成圖片任務 V2 的狀態。"}},"httpPath":"/s2s/v2.0/task/text-to-image/youcam/{task_id}"},{"label":"執行用於影像轉影像的 AI 文字生成圖片任務 V2。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-image~1youcam/post","routeSlug":"/zh-tw/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-image~1youcam/post","metadata":{"seo":{"title":"執行用於影像轉影像的 AI 文字生成圖片任務 V2。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/image-to-image/youcam"},{"label":"查詢用於影像轉影像的 AI 文字生成圖片任務 V2 的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-image~1youcam~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-image~1youcam~1{task_id}/get","metadata":{"seo":{"title":"查詢用於影像轉影像的 AI 文字生成圖片任務 V2 的狀態。","description":"查詢用於影像轉影像的 AI 文字生成圖片任務 V2 的狀態。"}},"httpPath":"/s2s/v2.0/task/image-to-image/youcam/{task_id}"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_image_generator/v1.0","routeSlug":"/zh-tw/reference/ai_image_generator/v1.0","items":[{"label":"列出預先定義的範本。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_image_generator/v1.0/paths/~1s2s~1v2.0~1task~1template~1text-to-image/get","routeSlug":"/zh-tw/reference/ai_image_generator/v1.0/paths/~1s2s~1v2.0~1task~1template~1text-to-image/get","metadata":{"seo":{"title":"列出預先定義的範本。","description":"列出預先定義的範本。"}},"httpPath":"/s2s/v2.0/task/template/text-to-image"},{"label":"執行 AI 文字生成圖片任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_image_generator/v1.0/paths/~1s2s~1v2.0~1task~1text-to-image/post","routeSlug":"/zh-tw/reference/ai_image_generator/v1.0/paths/~1s2s~1v2.0~1task~1text-to-image/post","metadata":{"seo":{"title":"執行 AI 文字生成圖片任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/text-to-image"},{"label":"查詢 AI 文字生成圖片任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_image_generator/v1.0/paths/~1s2s~1v2.0~1task~1text-to-image~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_image_generator/v1.0/paths/~1s2s~1v2.0~1task~1text-to-image~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 文字生成圖片任務的狀態。","description":"查詢 AI 文字生成圖片任務的狀態。"}},"httpPath":"/s2s/v2.0/task/text-to-image/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 文字生成圖片","version":"","description":"# 概述\n透過我們創新的文字生成圖片，發現 AI 的力量！立即將您的想法轉化為令人驚豔的視覺，實驗提示詞，探索卡通、油畫或素描等獨特風格，讓您的創意發光發熱。無論您是藝術家、設計師，或富有創意的人，我們的工具提供無限可能，讓您的願景成真。加入圖片作為參考，激發新的藝術方向，同時讓 AI 將它們精煉成完全原創的傑作。\n\n想要更多靈感？請參考 https://yce.makeupar.com/ai-art-generator。\n\n應用案例：\n![AI Image Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_v3_video_02f161f909.jpg \"AI 文字生成圖片\")\n\n![AI Image Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_v4_poster_092d2fbb9f.jpg \"AI 文字生成圖片\")\n\n輸出範例：\n![AI Image Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_topbanner_dt_2_e325681588.jpg \"AI 文字生成圖片\")\n\n![AI Image Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_topbanner_dt_5_8b4fa13c6a.jpg \"AI 文字生成圖片\")\n\n## 檔案規格與錯誤\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n| ---- | ---- | ---- | ---- |\n| V1.0 文字轉影像 | 輸出：長邊 1024 像素。 | 提示詞不得超過 500 字元 | N/A |\n| V2.0 文字轉影像 | 輸出：預設解析度為 1664 × 928，支援的解析度為 1664 × 928（16:9）、1472 × 1104（4:3）、1328 × 1328（1:1）、1104 × 1472（3:4）與 928 × 1664（9:16）。 | 提示詞不得超過 800 字元 | N/A |\n| V2.0 影像轉影像 | 輸入：寬與高都必須落在 384 到 3072 像素的範圍內。 <br>輸出：可自訂的寬與高範圍為 512 到 2,048 像素，預設配置維持約 1,024 × 1,024 的總像素數，長寬比依輸入圖片而定。 | <10MB<br> 提示詞不得超過 800 字元 | JPG、JPEG、PNG、BMP、TIFF、WEBP 與 GIF。 <br>動畫 GIF 僅處理第一影格。 |\n\n* 錯誤代碼\n\n| 錯誤代碼 | 說明 |\n| ---------- | ----------- |\n| exceed_max_filesize | 上傳的檔案大小超過允許的上限。 |\n| invalid_parameter | 有一個或多個參數缺失或無效 |\n| error_download_image | 下載來源圖片失敗。 |\n| error_decode_image | 解碼或解析來源圖片失敗。 |\n| error_nsfw_content_detected | 在來源圖片中偵測到不適合工作場合（NSFW）的內容。 |\n| error_unsupport_ratio | 輸入圖片的長寬比不受支援。 |\n| unknown_internal_error | 發生未指明的內部錯誤。 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 文字生成圖片 V1.0 | 2 |\n| AI 文字生成圖片 V2.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_watermark_removal.yaml","link":"/zh-tw/reference/ai_watermark_removal","routeSlug":"/zh-tw/reference/ai_watermark_removal","label":"AI 浮水印移除","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_watermark_removal/section/概述","routeSlug":"/zh-tw/reference/ai_watermark_removal/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_watermark_removal/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_watermark_removal/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_watermark_removal/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_watermark_removal/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_watermark_removal/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_watermark_removal/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_watermark_removal/v1.0","routeSlug":"/zh-tw/reference/ai_watermark_removal/v1.0","items":[{"label":"執行 AI 浮水印移除任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_watermark_removal/v1.0/paths/~1s2s~1v2.0~1task~1wmk-removal/post","routeSlug":"/zh-tw/reference/ai_watermark_removal/v1.0/paths/~1s2s~1v2.0~1task~1wmk-removal/post","metadata":{"seo":{"title":"執行 AI 浮水印移除任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/wmk-removal"},{"label":"查詢 AI 浮水印移除任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_watermark_removal/v1.0/paths/~1s2s~1v2.0~1task~1wmk-removal~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_watermark_removal/v1.0/paths/~1s2s~1v2.0~1task~1wmk-removal~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 浮水印移除任務的狀態。","description":"查詢 AI 浮水印移除任務的狀態。"}},"httpPath":"/s2s/v2.0/task/wmk-removal/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 浮水印移除","version":"","description":"# 概述\nAI 驅動的浮水印移除\n\n可靠地偵測並移除浮水印、標誌與其他標記，同時保留影像的原始品質與細節。\n\n    > 請負責地使用此工具，避免不道德的應用，例如為未經授權的商業用途移除浮水印。尊重影像的預期用途，並遵循合理使用原則。\n\n![](https://d32qvgpd29lguw.cloudfront.net/Watermark_Remover_BA_Image_24bf9f2ed1.png)\n\n---\n\n## 整合指南\n\n* AI 浮水印移除使用指南\n\n本指南說明如何使用 AI 浮水印移除上傳圖片、準備參考物件，以及建立任務。\n\n***\n\n   * 步驟 1. 使用 File API 上傳檔案\n\n使用 **File API**（`/s2s/v2.0/file`）上傳目標圖片。\n\n***\n\n   * 步驟 2. 取得 File API 回應\n\n回應包含：\n\n*   用於建立 AI 任務的 `file_id`。\n*   用於上傳實際圖片檔案的 `requests.url`。\n\n***\n\n   * 步驟 3. 上傳圖片到提供的網址\n\n使用 File API 回應中的 `requests.url` 上傳圖片：\n\n***\n\n   * 步驟 4. 建立 AI 任務\n\n使用 **AI 任務 API**（`/s2s/v2.0/task/wmk-removal`）建立 AI 任務。\n\n***\n\n   * 步驟 5. 輪詢任務結果\n\n使用任務 ID 查詢狀態：\n\n```bash\ncurl --request GET \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/wmk-removal/<YOUR_TASK_ID> \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json'\n```\n\n***\n\n   * 步驟 6. 取得結果\n\n成功的回應會包含結果圖片的下載網址：\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"error\": null,\n    \"results\": {\n \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n    },\n    \"task_status\": \"success\"\n  }\n}\n```\n\nAPI Key 無效的錯誤回應：\n\n```json\n{\n  \"status\": 401,\n  \"error\": \"Unauthorized\",\n  \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\n應用案例：\n![](https://d32qvgpd29lguw.cloudfront.net/Watermark_Remover_BA_2_c8bbf561af.png)\n\n\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n|類型|支援的尺寸|支援的檔案大小|支援的格式|\n|  ---- | ---- | ---- | ---- |\n| AI 浮水印移除 | 最大邊 4096 px | < 10MB | jpg/png |\n\n    > 若未經版權所有者同意，或為未經授權的目的移除浮水印，可能違法。請務必確保您對該影像擁有適當的權利。\n\n* 錯誤代碼\n\n| 錯誤代碼 | 說明 |\n| ---------- | ----------- |\n| invalid_parameter |參數缺失或無效。 |\n| error_download_image | 無法下載圖片。 |\n| exceed_max_filesize | 圖片過大。檔案大小不得超過 10 MB。長邊不得超過 4096 像素。 |\n| error_below_min_image_size | 圖片過小。長邊至少需 128 像素。 |\n| error_nsfw_content_detected | 在結果圖片中偵測到潛在的 NSFW 內容。 |\n| error_editing_failed | 編輯過程失敗，因為結果圖片與來源圖片過於相似。 |\n| unknown_internal_error | 處理此請求時，我們這端發生問題。 |\n\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 浮水印移除 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_retake.yaml","link":"/zh-tw/reference/ai_retake","routeSlug":"/zh-tw/reference/ai_retake","label":"AI Retake","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_retake/section/概述","routeSlug":"/zh-tw/reference/ai_retake/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_retake/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_retake/section/概述/整合指南"},{"type":"link","label":"輸入與輸出","link":"/zh-tw/reference/ai_retake/section/概述/輸入與輸出","routeSlug":"/zh-tw/reference/ai_retake/section/概述/輸入與輸出"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_retake/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_retake/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_retake/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_retake/section/概述/點數消耗"}]},{"type":"group","label":"V2.0","link":"/zh-tw/reference/ai_retake/v2.0","routeSlug":"/zh-tw/reference/ai_retake/v2.0","items":[{"label":"執行 AI Retake 的臉部偵測任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_retake/v2.0/paths/~1s2s~1v2.0~1task~1retake~1pre-process/post","routeSlug":"/zh-tw/reference/ai_retake/v2.0/paths/~1s2s~1v2.0~1task~1retake~1pre-process/post","metadata":{"seo":{"title":"執行 AI Retake 的臉部偵測任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/retake/pre-process"},{"label":"查詢 AI Retake 臉部偵測任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_retake/v2.0/paths/~1s2s~1v2.0~1task~1retake~1pre-process~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_retake/v2.0/paths/~1s2s~1v2.0~1task~1retake~1pre-process~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI Retake 臉部偵測任務的狀態。","description":"查詢 AI Retake 臉部偵測任務的狀態。"}},"httpPath":"/s2s/v2.0/task/retake/pre-process/{task_id}"},{"label":"執行 AI Retake 任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_retake/v2.0/paths/~1s2s~1v2.0~1task~1retake/post","routeSlug":"/zh-tw/reference/ai_retake/v2.0/paths/~1s2s~1v2.0~1task~1retake/post","metadata":{"seo":{"title":"執行 AI Retake 任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/retake"},{"label":"查詢 AI Retake 任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_retake/v2.0/paths/~1s2s~1v2.0~1task~1retake~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_retake/v2.0/paths/~1s2s~1v2.0~1task~1retake~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI Retake 任務的狀態。","description":"查詢 AI Retake 任務的狀態。"}},"httpPath":"/s2s/v2.0/task/retake/{task_id}"}]}],"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"}},{"type":"separator","label":"影片編輯","labelTranslationKey":"sidebar.reference.separators.video"},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_video_generator.yaml","link":"/zh-tw/reference/ai_video_generator","routeSlug":"/zh-tw/reference/ai_video_generator","label":"AI 照片轉影片","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_video_generator/section/概述","routeSlug":"/zh-tw/reference/ai_video_generator/section/概述","items":[{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_video_generator/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_video_generator/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_video_generator/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_video_generator/section/概述/點數消耗"}]},{"type":"group","label":"V2.0","link":"/zh-tw/reference/ai_video_generator/v2.0","routeSlug":"/zh-tw/reference/ai_video_generator/v2.0","items":[{"label":"執行 AI 影像轉影片生成器 V2 任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-video~1youcam/post","routeSlug":"/zh-tw/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-video~1youcam/post","metadata":{"seo":{"title":"執行 AI 影像轉影片生成器 V2 任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/image-to-video/youcam"},{"label":"查詢 AI 影像轉影片生成器 V2 任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-video~1youcam~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-video~1youcam~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 影像轉影片生成器 V2 任務的狀態。","description":"查詢 AI 影像轉影片生成器 V2 任務的狀態。"}},"httpPath":"/s2s/v2.0/task/image-to-video/youcam/{task_id}"},{"label":"執行 AI 文字轉影片任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-video~1youcam/post","routeSlug":"/zh-tw/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-video~1youcam/post","metadata":{"seo":{"title":"執行 AI 文字轉影片任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/text-to-video/youcam"},{"label":"查詢 AI 文字轉影片任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-video~1youcam~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-video~1youcam~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 文字轉影片任務的狀態。","description":"查詢 AI 文字轉影片任務的狀態。"}},"httpPath":"/s2s/v2.0/task/text-to-video/youcam/{task_id}"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_video_generator/v1.0","routeSlug":"/zh-tw/reference/ai_video_generator/v1.0","items":[{"label":"列出預先定義的範本。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_video_generator/v1.0/paths/~1s2s~1v2.0~1task~1template~1image-to-video/get","routeSlug":"/zh-tw/reference/ai_video_generator/v1.0/paths/~1s2s~1v2.0~1task~1template~1image-to-video/get","metadata":{"seo":{"title":"列出預先定義的範本。","description":"列出預先定義的範本。"}},"httpPath":"/s2s/v2.0/task/template/image-to-video"},{"label":"執行影像轉影片任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_video_generator/v1.0/paths/~1s2s~1v2.0~1task~1image-to-video/post","routeSlug":"/zh-tw/reference/ai_video_generator/v1.0/paths/~1s2s~1v2.0~1task~1image-to-video/post","metadata":{"seo":{"title":"執行影像轉影片任務。","description":"這個端點啟動影像轉影片的轉換流程。您必須提供範本 ID 與來源檔案（透過網址或檔案 ID）。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。"}},"httpPath":"/s2s/v2.0/task/image-to-video"},{"label":"查詢影像轉影片任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_video_generator/v1.0/paths/~1s2s~1v2.0~1task~1image-to-video~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_video_generator/v1.0/paths/~1s2s~1v2.0~1task~1image-to-video~1{task_id}/get","metadata":{"seo":{"title":"查詢影像轉影片任務的狀態。","description":"查詢影像轉影片任務的狀態。"}},"httpPath":"/s2s/v2.0/task/image-to-video/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 照片轉影片","version":"","description":"# 概述\nYouCam AI 照片轉影片輕鬆將文字提示與圖片轉化為引人入勝的影片。由先進 AI 技術驅動，它創造逼真的動態效果，讓您的想法與照片活起來。透過大量專業最佳化的範本，您可以快速將靜態圖片轉為引人入勝的高品質影片內容。\n\n要從圖片建立 AI 影片，請先使用一張背景乾淨、人像清晰可見的照片。只需上傳您的圖片，讓 YouCam AI 照片轉影片完成其餘工作，在瞬間將您的文字提示與照片轉化為動態影片。\n\n應用案例：\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_Animate%20Photo_047_d9e1cff579.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Dance_Video_61cf4c58d1.png)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/241216_AI_Kiss_image05_c3b7f1ac5b.jpg)\n\n\n## 檔案規格與錯誤\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n| V1.0 影像轉影片（標準）|輸入：>= 300*300px，長寬比介於 1:2.5 ~ 2.5:1。輸出：最高 720p 30fps|輸入：<10MB。輸出：5 秒或 10 秒|jpg/jpeg/png|\n| V1.0 影像轉影片（專業）|輸入：>= 300*300px，長寬比介於 1:2.5 ~ 2.5:1。輸出：最高 1080p 30fps|輸入：<10MB。輸出：5 秒或 10 秒|jpg/jpeg/png|\n| V2.0 影像轉影片 | 輸入圖片的長邊不得超過 4096 像素，長寬比介於 1:2.5 與 2.5:1 之間。 <br> 支援的輸出解析度為 480p、720p 與 1080p。若輸入圖片的短邊超過所選解析度，或其長邊小於目標，圖片會自動調整尺寸，使短邊符合所選解析度。 |輸入：<10MB。輸出：5 秒或 10 秒|jpg/jpeg/png|\n\n* 錯誤代碼\n\n| 錯誤類別 | 情境 / 說明 | 建議動作 |\n| -------------- | ---------------------- | ---------------- |\n| 請求參數無效 | 請求參數無效或缺失 | 確認所有請求參數皆正確 |\n| | 參數值無效（例如鍵錯誤或非法值） | 檢查回應中的錯誤訊息欄位，並更新請求參數 |\n| | 請求方法無效 | 查閱 API 文件並使用正確的 HTTP 方法 |\n| | 請求的資源不存在（例如找不到模型） | 參考回應中的錯誤訊息欄位並修正請求參數|\n| 觸發策略 | 已觸發平台政策 | 檢查是否違反任何平台政策 |\n| | 觸發內容安全政策  | 檢查並修改輸入內容，然後重新發送請求 |\n| | 請求頻率過高（超過速率限制）| 降低請求頻率、稍後重試，或聯絡客服以提高限制 |\n| | 並行數或 QPS 超過配額   | 降低請求頻率，或稍後重試 |\n| 內部錯誤  | 內部伺服器錯誤 | 稍後重試或聯絡客服 |\n| | 伺服器暫時不可用 | 稍後重試或聯絡客服 |\n| | 因請求積壓導致內部逾時| 稍後重試或聯絡客服 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 照片轉影片（標準）V1.0 | 3（1 秒）* |\n| AI 照片轉影片（專業）V1.0 | 6（1 秒）* |\n| AI 照片轉影片（影像轉影片）V2.0 | 1 點（480p / 1 秒）* <br> 2 點（720p / 1 秒）* <br> 3 點（1080p / 1 秒）* |\n| AI 照片轉影片（文字轉影片）V2.0 | 2 點（720p / 1 秒）* <br> 3 點（1080p / 1 秒）* |\n\n    > *若圖片數量或影片長度無法整除，點數無條件進位。\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_video_enhancer.yaml","link":"/zh-tw/reference/ai_video_enhancer","routeSlug":"/zh-tw/reference/ai_video_enhancer","label":"AI 影片修復","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_video_enhancer/section/概述","routeSlug":"/zh-tw/reference/ai_video_enhancer/section/概述","items":[{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_video_enhancer/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_video_enhancer/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_video_enhancer/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_video_enhancer/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_video_enhancer/v1.0","routeSlug":"/zh-tw/reference/ai_video_enhancer/v1.0","items":[{"label":"執行 AI 影片修復任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_video_enhancer/v1.0/paths/~1s2s~1v2.0~1task~1video-sr/post","routeSlug":"/zh-tw/reference/ai_video_enhancer/v1.0/paths/~1s2s~1v2.0~1task~1video-sr/post","metadata":{"seo":{"title":"執行 AI 影片修復任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/video-sr"},{"label":"查詢 AI 影片修復任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_video_enhancer/v1.0/paths/~1s2s~1v2.0~1task~1video-sr~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_video_enhancer/v1.0/paths/~1s2s~1v2.0~1task~1video-sr~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 影片修復任務的狀態。","description":"查詢 AI 影片修復任務的狀態。"}},"httpPath":"/s2s/v2.0/task/video-sr/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 影片修復","version":"","description":"# 概述\n\nAI 影片修復 API 讓開發者以最少的力氣自動提升影片品質。它使用先進的 AI 處理來修復模糊、調整清晰度、最佳化亮度，並將低解析度影像向上取樣。透過簡單的 API 呼叫，影片就能從低解析度影像與舊影片轉變為乾淨清晰的 HD 品質。\n\n此解決方案專為快速整合而設計，不需要影片編輯或機器學習的先前經驗。非常適合處理使用者生成內容、媒體平台、行銷工具與內容自動化系統的應用。\n\n\n**核心能力**\n\n1. 模糊修復\n   API 偵測動態模糊與柔和細節，然後使用 AI 增強模型重建更清晰的影格。\n\n2. 清晰度最佳化\n   邊緣與質地會被強化，創造更明確、視覺更鮮明的影片。\n\n3. 亮度與曝光調整\n   自動校正光線不一致，以改善可見度與色彩平衡。\n\n4. AI 向上取樣\n   解析度被智慧地從 480p 等較低品質格式提升至 HD 品質，同時保留細節。\n\n5. 品質提升\n   套用雜訊減少與偽影移除，以產生乾淨且專業的結果。\n\n使用案例範例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_video_enhancer_S2_feature_video_03_S_0_10169a6902.jpg)\n\n---\n\n## 檔案規格與錯誤\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n| AI 影片修復 | 輸入影片長度不得超過 60 秒，解析度不超過 2K，影格率為每秒 30 影格或以下。 | 長度限制：60 秒 | 容器：mov, mp4 <br>影像：MPEG-4, MPEG-4 AVC, <br>音訊：aac, amr, mp3 |\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| error_download_video | 下載來源影片錯誤 |\n| error_decode_video | 解碼來源影片錯誤 |\n| error_unsupported_video | 不支援的影片格式 |\n| exceed_max_filesize | 輸入檔案大小超過上限|\n| error_nsfw_content_detected | 在來源檔案中偵測到 NSFW 內容 |\n| error_decode_mask | 解碼遮罩圖片錯誤 |\n| invalid_parameter | 參數值無效|\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 影片修復 V1.0 | 1（2 秒）* |\n\n    > *若圖片數量或影片長度無法整除，點數無條件進位。\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_video_face_swap.yaml","link":"/zh-tw/reference/ai_video_face_swap","routeSlug":"/zh-tw/reference/ai_video_face_swap","label":"AI 影片換臉","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_video_face_swap/section/概述","routeSlug":"/zh-tw/reference/ai_video_face_swap/section/概述","items":[{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_video_face_swap/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_video_face_swap/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_video_face_swap/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_video_face_swap/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_video_face_swap/v1.0","routeSlug":"/zh-tw/reference/ai_video_face_swap/v1.0","items":[{"label":"執行 AI 照片換臉（影片）任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_video_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap-vid/post","routeSlug":"/zh-tw/reference/ai_video_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap-vid/post","metadata":{"seo":{"title":"執行 AI 照片換臉（影片）任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/face-swap-vid"},{"label":"查詢 AI 照片換臉（影片）任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_video_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap-vid~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_video_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap-vid~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 照片換臉（影片）任務的狀態。","description":"查詢 AI 照片換臉（影片）任務的狀態。"}},"httpPath":"/s2s/v2.0/task/face-swap-vid/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 影片換臉","version":"","description":"# 概述\n影片換臉是 AI 驅動的流程，使用 YouCam 的 AI 影片換臉 API，在影片中將一個人的臉換成另一個人的臉。\n透過先進的 AI 技術，AI 影片換臉帶來極為逼真的結果。臉部表情、光線與膚色都經過精細調校，確保換後的臉部與原始影像無縫融合。\n\n> **注意：** 這個 API 僅支援單人臉的影片。若需要可自訂的解決方案，請  [聯絡我們](mailto:YouCamOnlineEditor_API@perfectcorp.com)。\n\n使用案例範例：\n![](https://plugins-media.makeupar.com/smb/blog/post/2024-08-23/b1f96100-37d6-4c28-b467-d397e9c3a25d.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_video_face_swap_S3_video_03_28785ebe0c.jpg)\n\n![](https://plugins-media.makeupar.com/smb/story/2024-09-12/3582f617-e88e-4219-9e72-43d4c26791cd.png)\n\n---\n\n## 檔案規格與錯誤\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n| AI 影片換臉 | 輸入影片不得超過 30 秒、4K 解析度或 30 FPS，輸出限制為長邊 1280 解析度、30 FPS，最長 30 秒。 | 長度限制：30 秒 | 容器：mov, mp4 <br>影像：MPEG-4, MPEG-4 AVC, <br>音訊：aac, amr, mp3 |\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| error_download_video | 下載來源影片錯誤 |\n| error_decode_video | 解碼來源影片錯誤 |\n| error_unsupported_video | 不支援的影片格式 |\n| exceed_max_filesize | 輸入檔案大小超過上限|\n| error_nsfw_content_detected | 在來源檔案中偵測到 NSFW 內容 |\n| error_decode_mask | 解碼遮罩圖片錯誤 |\n| invalid_parameter | 參數值無效|\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 影片換臉 V1.0 | 1（5 秒）* |\n\n    > *若圖片數量或影片長度無法整除，點數無條件進位。\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_video_style_transfer.yaml","link":"/zh-tw/reference/ai_video_style_transfer","routeSlug":"/zh-tw/reference/ai_video_style_transfer","label":"AI 影片風格轉換","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_video_style_transfer/section/概述","routeSlug":"/zh-tw/reference/ai_video_style_transfer/section/概述","items":[{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_video_style_transfer/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_video_style_transfer/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_video_style_transfer/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_video_style_transfer/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_video_style_transfer/v1.0","routeSlug":"/zh-tw/reference/ai_video_style_transfer/v1.0","items":[{"label":"列出預先定義的範本。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_video_style_transfer/v1.0/paths/~1s2s~1v2.0~1task~1template~1video-trans/get","routeSlug":"/zh-tw/reference/ai_video_style_transfer/v1.0/paths/~1s2s~1v2.0~1task~1template~1video-trans/get","metadata":{"seo":{"title":"列出預先定義的範本。","description":"列出預先定義的範本。"}},"httpPath":"/s2s/v2.0/task/template/video-trans"},{"label":"執行 AI 風格移轉（影片）任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_video_style_transfer/v1.0/paths/~1s2s~1v2.0~1task~1video-trans/post","routeSlug":"/zh-tw/reference/ai_video_style_transfer/v1.0/paths/~1s2s~1v2.0~1task~1video-trans/post","metadata":{"seo":{"title":"執行 AI 風格移轉（影片）任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/video-trans"},{"label":"查詢 AI 風格移轉（影片）任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_video_style_transfer/v1.0/paths/~1s2s~1v2.0~1task~1video-trans~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_video_style_transfer/v1.0/paths/~1s2s~1v2.0~1task~1video-trans~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 風格移轉（影片）任務的狀態。","description":"查詢 AI 風格移轉（影片）任務的狀態。"}},"httpPath":"/s2s/v2.0/task/video-trans/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 影片風格移轉","version":"","description":"# 概述\n用我們的 AI 影片濾鏡與特效創造獨特的影片。輕鬆以驚豔的 AI 風格增強每段影片。AI 影片濾鏡即刻轉換。體驗 AI 影片濾鏡帶來的無縫轉換，即刻套用驚豔的效果。從多種獨特風格中選擇，包括普普藝術、復古、動漫等，為每一影格增添深度與創意。\n\n使用案例範例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_video_style_transfer_S1_video_1_0_6d571a8bbb.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_video_style_transfe_S2_feature_03_0_6dd652a6f2.jpg)\n\n---\n\n## 檔案規格與錯誤\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n| AI 影片風格轉換 | 輸入影片不得超過 30 秒、4K 解析度或 30 FPS，輸出限制為長邊 1280 解析度、16 FPS，最長 30 秒。 | 長度限制：30 秒 | 容器：mov, mp4 <br>影像：MPEG-4, MPEG-4 AVC, <br>音訊：aac, amr, mp3 |\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| error_download_video | 下載來源影片錯誤 |\n| error_decode_video | 解碼來源影片錯誤 |\n| error_unsupported_video | 不支援的影片格式 |\n| exceed_max_filesize | 輸入檔案大小超過上限|\n| error_nsfw_content_detected | 在來源檔案中偵測到 NSFW 內容 |\n| error_decode_mask | 解碼遮罩圖片錯誤 |\n| invalid_parameter | 參數值無效|\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 影片風格轉換 V1.0 | 4（1 秒）* |\n\n    > *若圖片數量或影片長度無法整除，點數無條件進位。\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_video_object_removal.yaml","link":"/zh-tw/reference/ai_video_object_removal","routeSlug":"/zh-tw/reference/ai_video_object_removal","label":"AI 影片物件移除","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_video_object_removal/section/概述","routeSlug":"/zh-tw/reference/ai_video_object_removal/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_video_object_removal/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_video_object_removal/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_video_object_removal/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_video_object_removal/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_video_object_removal/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_video_object_removal/section/概述/點數消耗"}]},{"type":"group","label":"V2.1","link":"/zh-tw/reference/ai_video_object_removal/v2.1","routeSlug":"/zh-tw/reference/ai_video_object_removal/v2.1","items":[{"label":"建立新檔案。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_video_object_removal/v2.1/paths/~1s2s~1v2.0~1file~1obj-rem-vid/post","routeSlug":"/zh-tw/reference/ai_video_object_removal/v2.1/paths/~1s2s~1v2.0~1file~1obj-rem-vid/post","metadata":{"seo":{"title":"建立新檔案。","description":"要上傳新檔案，您必須先使用 File API。它會提供一個網址——請使用該網址上傳您的檔案。上傳完成後，您可以使用同一個回應中的 file_id，開始使用我們的 AI 功能。"}},"httpPath":"/s2s/v2.0/file/obj-rem-vid"},{"label":"執行 AI 影片物件移除任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_video_object_removal/v2.1/paths/~1s2s~1v2.0~1task~1obj-rem-vid/post","routeSlug":"/zh-tw/reference/ai_video_object_removal/v2.1/paths/~1s2s~1v2.0~1task~1obj-rem-vid/post","metadata":{"seo":{"title":"執行 AI 影片物件移除任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/obj-rem-vid"},{"label":"查詢 AI 影片物件移除任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_video_object_removal/v2.1/paths/~1s2s~1v2.0~1task~1obj-rem-vid~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_video_object_removal/v2.1/paths/~1s2s~1v2.0~1task~1obj-rem-vid~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 影片物件移除任務的狀態。","description":"查詢 AI 影片物件移除任務的狀態。"}},"httpPath":"/s2s/v2.0/task/obj-rem-vid/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 影片物件移除","version":"","description":"# 概述\n\n**AI 影片物件移除**\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-02-04/webp_537ec670-48c0-49fc-b96b-8073de21a64b.webp)\n\nAI 影片物件移除 API 能無縫移除影片內容中不想要的元素。無論是擠滿遊客的擁擠背景、雜亂的環境（如放著衛生紙與瓶子的桌面），或玻璃表面上令人分心的倒影，API 都能以高準確度與一致性，精準可靠地消除遮罩區域。\n\n\n---\n\n## 整合指南\n\n**1. 準備來源影片與遮罩圖片**\n輸入影片長度不得超過 60 秒，輸出影片的長軸須為 1920 像素或以下，影格率為每秒 30 影格或以下。\n\n\n**2. 上傳檔案**\n透過以下方式請求上傳網址與檔案 ID：\n\n```\nPOST /s2s/v2.0/file\n```\n\n輸入影片：\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_video_object_removal_input_edd43a2470.png)\n\n\n參考輸入遮罩：\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_video_object_removal_mask_4a1c9fb658.png)\n\n\n**3. 執行 AI 任務**\n\n```\nPOST /s2s/v2.0/task/obj-rem-vid\n```\n\n使用檔案 ID 或圖片網址作為輸入提交任務。回應會回傳 task_id 用於追蹤與取得結果。\n\n\n**4. 取得任務結果**\n\n```\nGET /s2s/v2.0/task/obj-rem-vid/{task_id}\n```\n\n使用任務 ID 追蹤狀態並取得結果。\n\n可設定 [Webhooks](/develop/webhook.md) 在任務完成時接收非同步通知，狀態為 success 或 error。也支援輪詢，重複呼叫任務端點直到狀態從 running 更新為 success 或 error。\n\n僅在任務成功完成時才計費。\n\n\n輸出影片範例：\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_video_object_removal_output_eb7670cd9e.png)\n\n\n---\n\n## 檔案規格與錯誤\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n| AI 影片物件移除 | 輸入影片長度不得超過 60 秒，輸出影片的長軸須為 1920 像素或以下，影格率為每秒 30 影格或以下。 | 長度限制：60 秒 | 容器：mov, mp4 <br>影像：MPEG-4, MPEG-4 AVC, <br>音訊：aac, amr, mp3 |\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| error_download_video | 下載來源影片錯誤 |\n| error_decode_video | 解碼來源影片錯誤 |\n| error_unsupported_video | 不支援的影片格式 |\n| exceed_max_filesize | 輸入檔案大小超過上限|\n| error_nsfw_content_detected | 在來源檔案中偵測到 NSFW 內容 |\n| error_decode_mask | 解碼遮罩圖片錯誤 |\n| invalid_parameter | 參數值無效|\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 影片物件移除 V2.1 | 2（1 秒）* |\n\n    > *若圖片數量或影片長度無法整除，點數無條件進位。\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-TW/reference/ai_video_background_replace.yaml","link":"/zh-tw/reference/ai_video_background_replace","routeSlug":"/zh-tw/reference/ai_video_background_replace","label":"AI 影片背景更換","items":[{"type":"group","label":"概述","link":"/zh-tw/reference/ai_video_background_replace/section/概述","routeSlug":"/zh-tw/reference/ai_video_background_replace/section/概述","items":[{"type":"link","label":"整合指南","link":"/zh-tw/reference/ai_video_background_replace/section/概述/整合指南","routeSlug":"/zh-tw/reference/ai_video_background_replace/section/概述/整合指南"},{"type":"link","label":"檔案規格與錯誤","link":"/zh-tw/reference/ai_video_background_replace/section/概述/檔案規格與錯誤","routeSlug":"/zh-tw/reference/ai_video_background_replace/section/概述/檔案規格與錯誤"},{"type":"link","label":"點數消耗","link":"/zh-tw/reference/ai_video_background_replace/section/概述/點數消耗","routeSlug":"/zh-tw/reference/ai_video_background_replace/section/概述/點數消耗"}]},{"type":"group","label":"V1.0","link":"/zh-tw/reference/ai_video_background_replace/v1.0","routeSlug":"/zh-tw/reference/ai_video_background_replace/v1.0","items":[{"label":"執行 AI 影片背景更換任務。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_video_background_replace/v1.0/paths/~1s2s~1v2.0~1task~1bg-replace-vid/post","routeSlug":"/zh-tw/reference/ai_video_background_replace/v1.0/paths/~1s2s~1v2.0~1task~1bg-replace-vid/post","metadata":{"seo":{"title":"執行 AI 影片背景更換任務。","description":"AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 success 或 error 通知後，使用收到的 task_id 查詢任務結果。設定與驗證細節請見 webhook 整合指南。"}},"httpPath":"/s2s/v2.0/task/bg-replace-vid"},{"label":"查詢 AI 影片背景更換任務的狀態。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-tw/reference/ai_video_background_replace/v1.0/paths/~1s2s~1v2.0~1task~1bg-replace-vid~1{task_id}/get","routeSlug":"/zh-tw/reference/ai_video_background_replace/v1.0/paths/~1s2s~1v2.0~1task~1bg-replace-vid~1{task_id}/get","metadata":{"seo":{"title":"查詢 AI 影片背景更換任務的狀態。","description":"查詢 AI 影片背景更換任務的狀態。"}},"httpPath":"/s2s/v2.0/task/bg-replace-vid/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 影片背景更換","version":"","description":"# 概述\n\n**AI 影片背景更換**\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Green_Screen_ddb7892393.png)\n\nAI 影片背景更換 API 讓您無縫加入任何您選擇的背景。您可以從廣泛的選項中選擇，包括風景、自訂圖片，甚至輕鬆的視覺，給予您完全的創作控制，為您的內容設計理想的場景。\n無需攝影棚或綠幕。您可以輕鬆更換影片背景，達到乾淨且專業的外觀。無論您想引入新的環境，或移除不想要的干擾，這解決方案非常適合製作引人入勝的影片與教學，無需昂貴的設備。\n\n\n---\n\n## 整合指南\n\n**1. 準備來源影片與背景圖片**\n輸出必須為 MP4 格式，解析度與輸入相同，影格率上限為每秒 30 影格（若輸入超過此限制會自動轉換），最大長度 600 秒（若輸入影片更長，僅保留前 600 秒）。\n\n背景圖片必須為 JPG 或 PNG 格式，最大解析度 4096 x 4096 像素，長邊不超過 4096 像素，檔案大小限制為 10 MB。\n\n\n**2. 上傳檔案**\n透過以下方式請求上傳網址與檔案 ID：\n\n```\nPOST /s2s/v2.0/file\n```\n\n\n**3. 執行 AI 任務**\n\n```\nPOST /s2s/v2.0/task/bg-replace-vid\n```\n\n使用檔案 ID 或圖片網址作為輸入提交任務。回應會回傳 task_id 用於追蹤與取得結果。\n\n\n**4. 取得任務結果**\n\n```\nGET /s2s/v2.0/task/bg-replace-vid/{task_id}\n```\n\n使用任務 ID 追蹤狀態並取得結果。k\n可 [Webhooks](/develop/webhook.md) 在任務完成時接收非同步通知，狀態為 success 或 error。也支援輪詢，重複呼叫任務端點直到狀態從 running 更新為 success 或 error。\n\n僅在任務成功完成時才計費。\n\n\n\n---\n\n## 檔案規格與錯誤\n\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n|  ----  | ----  | ----  | ----  |\n| AI 影片背景更換 | 輸出必須為 MP4 格式，解析度與輸入相同，影格率上限為每秒 30 影格（若輸入超過此限制會自動轉換），最大長度 600 秒（若輸入影片更長，僅保留前 600 秒）。 <br>背景圖片必須為 JPG 或 PNG 格式，最大解析度 4096 x 4096 像素，長邊不超過 4096 像素，檔案大小限制為 10 MB。 | 影片長度限制：600 秒 <br> 背景圖片：<10MB | 容器：mp4 <br>影像：MPEG-4, MPEG-4 AVC, <br>音訊：aac, amr, mp3 |\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n|  ----  | ----  |\n| error_download_video | 下載來源影片錯誤 |\n| error_decode_video | 解碼來源影片錯誤 |\n| error_unsupported_video | 不支援的影片格式 |\n| exceed_max_filesize | 輸入檔案大小超過上限|\n| error_nsfw_content_detected | 在來源檔案中偵測到 NSFW 內容 |\n| error_decode_mask | 解碼遮罩圖片錯誤 |\n| invalid_parameter | 參數值無效|\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58（現代 TLS/HTTP 支援）</br>   - jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 影片背景更換 V1.0 | 2（1 秒）* |\n\n    > *若圖片數量或影片長度無法整除，點數無條件進位。\n\n---\n"}}]}