{
  "openapi": "3.0.0",
  "info": {
    "title": "AI 肌膚檢測 V2.1",
    "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",
    "version": "",
    "termsOfService": "https://www.makeupar.com/perfectbeauty/youcam/terms-of-service-api",
    "contact": {
      "email": "YouCamOnlineEditor_API@perfectcorp.com"
    },
    "license": {
      "name": "Privacy policy",
      "url": "https://www.makeupar.com/perfectbeauty/youcam/privacy-policy-api"
    }
  },
  "servers": [
    {
      "url": "https://yce-api-01.makeupar.com"
    }
  ],
  "tags": [
    {
      "name": "Standard Analysis",
      "description": "## 端點總覽\n\n**這是什麼。** 標準肌膚檢測針對您選定的肌膚困擾，給出客觀、可量化的分數，並附上精準的偵測遮罩與熱圖。 \n\n運用先進的 AI 深度學習與臉部區域分割技術，Perfect Corp AI 肌膚檢測不必接觸皮膚，就能從數位影像評估可見的肌膚狀況。方案會輸出量化分數、偵測遮罩、熱圖與 AR 疊加效果，用個人化的肌膚洞察幫使用者更了解自己的膚況，並據此打造屬於每個人的護膚流程。\n\n* 支援的肌膚困擾包括：\n\n  * 皺紋\n  * 含水量\n  * 緊實度\n  * 上眼皮下垂\n  * 下眼皮下垂\n  * 毛孔\n  * 質地\n  * 痤瘡\n  * 油脂\n  * 斑點\n  * 黑眼圈\n  * 光澤\n  * 泛紅\n  * 眼袋\n  * 淚溝\n\n此外還會輸出膚質、推估的肌膚年齡與整體膚況分數。所有結果都是出自影像的指標，僅供護膚參考，不構成臨床測量、診斷或醫學評估。\n\n\n* 建立 AI 任務\n\n```bash\n# Standard Skin Analysis V2.1\ncurl -sS -X POST \"$BASE_URL/s2s/v2.1/task/skin-analysis\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"src_file_url\": \"https://your-cdn.example.com/customer-001.jpg\",\n    \"dst_actions\": [\"hd_wrinkle\", \"hd_pore\", \"hd_texture\", \"hd_acne\"],\n    \"format\": \"zip\",\n    \"pf_camera_kit\": true\n  }'\n```\n\n---\n\n* 輪詢取得報告與推薦\n\n每次呼叫都會立刻回傳一個 `BasicRunTaskResponseV2`；用回傳的 id 輪詢任務就行，報告與推薦結果都放在 **`llm_results.json`** 裡。\n\n```bash\n# 1. Run the task and capture the task id\nTASK_ID=$(curl -sS -X POST \"$BASE_URL/s2s/v2.1/task/skin-analysis\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ ... }' | jq -r '.data.task_id')\n\n# 2. Poll until task_status is \"success\"\ncurl -sS -H \"Authorization: Bearer $API_KEY\" \\\n  \"$BASE_URL/s2s/v2.1/task/skin-analysis/$TASK_ID\"\n```\n\n`task_status` 會從 `running` 走到 `success` | `error`。用 `format: zip` 時，`results.url` 是一條有效期限 **2 小時**的下載連結，ZIP 裡有一個 `skinanalysisResult` 資料夾，包含 `score_info.json` 與所有偵測結果圖片。用 `format: json` 時，`results.output` 會把分數直接回傳在回應內容中。\n\n---\n\n* 請求欄位速查\n\n| 欄位 | 必填 | 說明 |\n|---|---|---|\n| `src_file_id` / `src_file_url` | 是（二者其一） | 輸入圖片，規則依 `BasicRunTaskV2` |\n| `dst_actions` | **是** | 要全選 HD 功能，**或**全選 SD 功能——不可混用 |\n| `format` | 否 | `zip`（預設）\\| `json`——兩者的回應 schema 不同 |\n| `pf_camera_kit` | 否 | V2.1 新增；臉部輪廓與五官定位 |\n| `miniserver_args` | 否 | 遮罩疊加，以及 HD 毛孔／皺紋的背景控制項 |\n| `advanced_report` | 否 | 有送就出報告；`{}` 表示全採預設值；不送就沒有報告 |\n| `product_recommendation` | 否 | 有送就出推薦；需要 `catalog_id` |\n\n**解析度。** 所有輸出圖片的長邊都以 **2560 px** 為上限，輸入圖片會自動調整尺寸。若 `enable_mask_overlay` 為 `false`，您拿到的是原始遮罩 `.png`，必須自行合成——請先確認輸入解析度，長邊超過 2560 px 時，就以 2560 px 來設定您的顯示尺寸。\n\n---\n"
    },
    {
      "name": "Analysis + Advanced Report",
      "description": "## 端點總覽\n\n**這是什麼。** 一份由大型語言模型撰寫、用自然語言呈現的全方位肌膚報告。模型的輸入是您的**精準 AI 肌膚檢測結果**，再加上一個**專業護膚參考資料庫**。模型不是在猜您的膚況——它解讀的是實測、量化的肌膚指標與真實的偵測遮罩，把這些結果對照專業護膚資料之後，才在 `llm_results.json` 回傳一份完整的報告。\n\n**報告的各面向由哪些 `dst_actions` 支撐。** 報告能寫多豐富，取決於您要求了哪些功能。`dst_actions` 為必填，而且**同一個請求不可混用 HD 與 SD 功能**——請選定其中一族。\n\n| 報告面向 | V2.1 功能 | 回傳的區域 |\n|---|---|---|\n| 臉部輪廓與五官定位 | `pf_camera_kit: true` | — |\n| 膚質 | `hd_skin_type` | `whole`, `t_zone`, `u_zone` |\n| T 區與 U 區對比 | `hd_skin_type` | `t_zone`, `u_zone` |\n| 額頭紋與眉間紋 | `hd_wrinkle` | `forehead`, `glabellar` |\n| 魚尾紋與法令紋 | `hd_wrinkle` | `crowfeet`, `nasolabial` |\n| 毛孔分佈 | `hd_pore` | `forehead`, `nose`, `cheek`, `whole` |\n| 肌膚平滑度 | `hd_texture` | `whole` |\n\n**參數**\n\n| 欄位 | 類型 | 預設值 | 說明 |\n|---|---|---|---|\n| `language` | string enum | `enu` | `enu` `cht` `jpn` `kor` `fra` `deu` `esn` `ita` `ptb` `ind` `ara` |\n| `tone` | string enum | `warm` | `warm` \\| `direct`——兩種語氣都維持專業 |\n| `country` | string | — | 為報告加入氣候與季節脈絡 |\n| `city` | string | — | 為報告加入氣候與季節脈絡 |\n\n想全採預設值，就送 `\"advanced_report\": {}`；完全不要報告，就把整個物件省掉。\n\n\n* 建立 AI 任務\n\n```bash\n# Skin Analysis with Advanced Skin Report\ncurl -sS -X POST \"$BASE_URL/s2s/v2.1/task/skin-analysis-report\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"src_file_url\": \"https://your-cdn.example.com/customer-001.jpg\",\n    \"dst_actions\": [\"hd_skin_type\", \"hd_wrinkle\", \"hd_pore\", \"hd_texture\"],\n    \"format\": \"zip\",\n    \"pf_camera_kit\": true,\n    \"advanced_report\": {\n      \"language\": \"cht\",\n      \"tone\": \"direct\",\n      \"country\": \"Taiwan\",\n      \"city\": \"Taipei\"\n    }\n  }'\n```\n\n```bash\n# Same call, every report default (enu / warm, no climate context)\ncurl -sS -X POST \"$BASE_URL/s2s/v2.1/task/skin-analysis-report\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"src_file_id\": \"your-uploaded-file-id\",\n    \"dst_actions\": [\"hd_skin_type\", \"hd_wrinkle\", \"hd_pore\", \"hd_texture\"],\n    \"pf_camera_kit\": true,\n    \"advanced_report\": {}\n  }'\n```\n\n---\n\n* 輪詢取得報告與推薦\n\n每次呼叫都會立刻回傳一個 `BasicRunTaskResponseV2`；用回傳的 id 輪詢任務就行，報告與推薦結果都放在 **`llm_results.json`** 裡。\n\n```bash\n# 1. Run the task and capture the task id\nTASK_ID=$(curl -sS -X POST \"$BASE_URL/s2s/v2.1/task/skin-analysis-report\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ ... }' | jq -r '.data.task_id')\n\n# 2. Poll until task_status is \"success\"\ncurl -sS -H \"Authorization: Bearer $API_KEY\" \\\n  \"$BASE_URL/s2s/v2.1/task/skin-analysis-report/$TASK_ID\"\n```\n\n`task_status` 會從 `running` 走到 `success` | `error`。用 `format: zip` 時，`results.url` 是一條有效期限 **2 小時**的下載連結，ZIP 裡有一個 `skinanalysisResult` 資料夾，包含 `score_info.json` 與所有偵測結果圖片。用 `format: json` 時，`results.output` 會把分數直接回傳在回應內容中。\n\n---\n\n* 請求欄位速查\n\n| 欄位 | 必填 | 說明 |\n|---|---|---|\n| `src_file_id` / `src_file_url` | 是（二者其一） | 輸入圖片，規則依 `BasicRunTaskV2` |\n| `dst_actions` | **是** | 要全選 HD 功能，**或**全選 SD 功能——不可混用 |\n| `format` | 否 | `zip`（預設）\\| `json`——兩者的回應 schema 不同 |\n| `pf_camera_kit` | 否 | V2.1 新增；臉部輪廓與五官定位 |\n| `miniserver_args` | 否 | 遮罩疊加，以及 HD 毛孔／皺紋的背景控制項 |\n| `advanced_report` | 否 | 有送就出報告；`{}` 表示全採預設值；不送就沒有報告 |\n| `product_recommendation` | 否 | 有送就出推薦；需要 `catalog_id` |\n\n**解析度。** 所有輸出圖片的長邊都以 **2560 px** 為上限，輸入圖片會自動調整尺寸。若 `enable_mask_overlay` 為 `false`，您拿到的是原始遮罩 `.png`，必須自行合成——請先確認輸入解析度，長邊超過 2560 px 時，就以 2560 px 來設定您的顯示尺寸。\n\n---\n"
    },
    {
      "name": "Analysis + Product Recommendation",
      "description": "## 端點總覽\n\n**這是什麼。** 把您的產品目錄交給一次精準的肌膚檢測來比對。上傳您在售的護膚產品及其說明，呼叫時傳入目錄的 id，端點就會在 `llm_results.json` 裡，為每一項偵測到的肌膚困擾回傳最契合的產品。\n\n它與一般 LLM 推薦的差別在於輸入。一般 LLM 靠機率與先驗知識推薦；Perfect AI 肌膚檢測會先產出**科學、量化的肌膚指標與真實的偵測遮罩**，模型再把產品對照實測出來的肌膚狀況——可靠、快速、說得出理由，而不是統計意義上的猜測。\n\n**參數**\n\n| 欄位 | 類型 | 必填 | 預設值 | 說明 |\n|---|---|---|---|---|\n| `catalog_id` | string | **是** | — | 取自「上傳產品目錄」。該目錄必須為 `ready` 狀態，且屬於您的帳號。 |\n| `top_n` | integer | 否 | `3` | 每一**項肌膚困擾**要推薦的產品數。最小 `1`；不得超過目錄的 `sku_count`。 |\n\n\n* 前置作業——上傳您的產品目錄\n\n產品目錄就是肌膚檢測進行推薦時所用的產品清單。上傳一次，記住它的 `catalog_id`，之後每次肌膚檢測都傳入這個 id。目錄歸屬您的**帳號**，而不是某一個 API key——帳號下的每個 key（包含專案 key）看到的都是同一批目錄，輪換或刪除 key 都不會影響它們。上傳與儲存目錄是免費的。\n\n**目錄檔案需求**\n\n| 項目 | 值 |\n|---|---|\n| 格式 | 含標題列的 CSV |\n| 編碼 | UTF-8，可含或不含 BOM（Excel 的「CSV UTF-8」會加上 BOM） |\n| 最大檔案大小 | 5 MB |\n| 最大 SKU 數量 | 除檔案大小外無限制 |\n| 必要欄位 | `product_id`、`product_name`、`product_description` |\n\n其他欄位會被忽略，但仍計入 5 MB 限制。含逗號或換行的值請加上引號。每個非空的資料列計為一個 SKU。\n\n```csv\nproduct_id,product_name,product_description\nSKU-001,Hydrating Serum,\"A lightweight serum for dry skin.\"\nSKU-002,Brightening Cream,\"Evens out skin tone, for daily use.\"\nSKU-003,Barrier Repair Cream,\"Rich cream for dry, redness-prone skin.\"\n```\n\n```bash\n# Upload a catalog — validated in the same request\ncurl -sS -X POST \"$BASE_URL/s2s/v2.1/product-catalog\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -F \"file=@catalog.csv\" \\\n  -F \"name=Summer skincare\"\n```\n\n通過驗證的檔案會回傳 `status: ready`，並附上它的 `catalog_id` 與 `sku_count`——請保留這個 id：\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"catalog_id\": \"1662043585118399001\",\n    \"name\": \"Summer skincare\",\n    \"status\": \"ready\",\n    \"created_time\": 1760256000000,\n    \"sku_count\": 3\n  }\n}\n```\n\n```bash\n# List every catalog of your account, newest first (ready and failed alike)\ncurl -sS -H \"Authorization: Bearer $API_KEY\" \"$BASE_URL/s2s/v2.1/product-catalog\"\n\n# Delete a catalog — immediate and permanent\ncurl -sS -X DELETE -H \"Authorization: Bearer $API_KEY\" \\\n  \"$BASE_URL/s2s/v2.1/product-catalog/1662043585118399001\"\n```\n\n**目錄狀態與限制**\n\n| 狀態 | 意義 | 可用於肌膚檢測 |\n|---|---|---|\n| `ready` | 已上傳並通過驗證 | 是 |\n| `failed` | 已上傳，但檔案驗證失敗 | 否 |\n\n驗證失敗的上傳會回傳錯誤，而且**仍會被記錄成一個 `failed` 目錄**，在「列出目錄」中看得到它；錯誤內容不會帶出它的 `catalog_id`。每個帳號最多可保留 **10 個目錄**，`ready` 與 `failed` 合併計算——上傳新目錄前請先刪掉一個。要更新目錄，請上傳新檔案：每次上傳都會建立新的 `catalog_id`，舊目錄在您刪除前仍可使用，因此可以先確認新目錄再切換。\n\n---\n\n* 建立 AI 任務\n\n```bash\n# Skin Analysis with Product Recommendation\ncurl -sS -X POST \"$BASE_URL/s2s/v2.1/task/skin-analysis-recommendation\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"src_file_url\": \"https://your-cdn.example.com/customer-001.jpg\",\n    \"dst_actions\": [\n      \"hd_skin_type\", \"hd_wrinkle\", \"hd_pore\", \"hd_texture\",\n      \"hd_acne\", \"hd_redness\", \"hd_oiliness\", \"hd_moisture\",\n      \"hd_age_spot\", \"hd_radiance\", \"hd_dark_circle\"\n    ],\n    \"format\": \"zip\",\n    \"pf_camera_kit\": true,\n    \"product_recommendation\": {\n      \"catalog_id\": \"1662043585118399001\",\n      \"top_n\": 3\n    }\n  }'\n```\n\n**驗證。** 下列每種情況都會回傳 `400` 與 `error_code: InvalidParameters`，而且**不扣點數**：\n\n| 原因 | `error` 訊息 |\n|---|---|\n| 有 `product_recommendation` 卻沒有 `catalog_id` | `catalog_id is required when product_recommendation is provided.` |\n| 目錄不存在、已被刪除，或屬於其他帳號 | `No catalog was found with this catalog_id.` |\n| 目錄上傳時驗證失敗（`status: failed`） | `This catalog failed validation when it was uploaded and can't be used. Upload the catalog again.` |\n| `top_n` 不是至少為 1 的整數 | *（常見的 `InvalidParameters` 狀況）* |\n| `top_n` 大於目錄中的產品數量 | `product_recommendation.top_n can't be more than the 3 products in this catalog.` |\n\n最後一則訊息是動態產生的——它會報出目錄實際的 `sku_count`。請從「列出目錄」讀取 `sku_count`，在您的端把 `top_n` 收斂到它的範圍內。\n\n---\n\n* 輪詢取得報告與推薦\n\n每次呼叫都會立刻回傳一個 `BasicRunTaskResponseV2`；用回傳的 id 輪詢任務就行，報告與推薦結果都放在 **`llm_results.json`** 裡。\n\n```bash\n# 1. Run the task and capture the task id\nTASK_ID=$(curl -sS -X POST \"$BASE_URL/s2s/v2.1/task/skin-analysis-recommendation\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ ... }' | jq -r '.data.task_id')\n\n# 2. Poll until task_status is \"success\"\ncurl -sS -H \"Authorization: Bearer $API_KEY\" \\\n  \"$BASE_URL/s2s/v2.1/task/skin-analysis-recommendation/$TASK_ID\"\n```\n\n`task_status` 會從 `running` 走到 `success` | `error`。用 `format: zip` 時，`results.url` 是一條有效期限 **2 小時**的下載連結，ZIP 裡有一個 `skinanalysisResult` 資料夾，包含 `score_info.json` 與所有偵測結果圖片。用 `format: json` 時，`results.output` 會把分數直接回傳在回應內容中。\n\n---\n\n* 請求欄位速查\n\n| 欄位 | 必填 | 說明 |\n|---|---|---|\n| `src_file_id` / `src_file_url` | 是（二者其一） | 輸入圖片，規則依 `BasicRunTaskV2` |\n| `dst_actions` | **是** | 要全選 HD 功能，**或**全選 SD 功能——不可混用 |\n| `format` | 否 | `zip`（預設）\\| `json`——兩者的回應 schema 不同 |\n| `pf_camera_kit` | 否 | V2.1 新增；臉部輪廓與五官定位 |\n| `miniserver_args` | 否 | 遮罩疊加，以及 HD 毛孔／皺紋的背景控制項 |\n| `advanced_report` | 否 | 有送就出報告；`{}` 表示全採預設值；不送就沒有報告 |\n| `product_recommendation` | 否 | 有送就出推薦；需要 `catalog_id` |\n\n**解析度。** 所有輸出圖片的長邊都以 **2560 px** 為上限，輸入圖片會自動調整尺寸。若 `enable_mask_overlay` 為 `false`，您拿到的是原始遮罩 `.png`，必須自行合成——請先確認輸入解析度，長邊超過 2560 px 時，就以 2560 px 來設定您的顯示尺寸。\n\n---\n"
    },
    {
      "name": "Analysis + Report + Recommendation",
      "description": "## 端點總覽\n\n**這是什麼。** 一次呼叫同時完成肌膚檢測、進階肌膚報告與產品推薦。您拿到的是一份扎實的報告——依據實測的肌膚指標與專業護膚參考資料庫——**加上**完全取自您自家產品的推薦，只需要一個請求、一套輪詢流程。\n\n一個 API 呼叫跑完整個閉環：科學、可信度高、精準的肌膚分析報告，再附上完全以您的目錄為依據的產品推薦。產品曝光與使用者回留，在同一次處理、同一段不中斷的使用者旅程中一起到位。\n\n* 前置作業——上傳您的產品目錄\n\n產品目錄就是肌膚檢測進行推薦時所用的產品清單。上傳一次，記住它的 `catalog_id`，之後每次肌膚檢測都傳入這個 id。目錄歸屬您的**帳號**，而不是某一個 API key——帳號下的每個 key（包含專案 key）看到的都是同一批目錄，輪換或刪除 key 都不會影響它們。上傳與儲存目錄是免費的。\n\n**目錄檔案需求**\n\n| 項目 | 值 |\n|---|---|\n| 格式 | 含標題列的 CSV |\n| 編碼 | UTF-8，可含或不含 BOM（Excel 的「CSV UTF-8」會加上 BOM） |\n| 最大檔案大小 | 5 MB |\n| 最大 SKU 數量 | 除檔案大小外無限制 |\n| 必要欄位 | `product_id`、`product_name`、`product_description` |\n\n其他欄位會被忽略，但仍計入 5 MB 限制。含逗號或換行的值請加上引號。每個非空的資料列計為一個 SKU。\n\n```csv\nproduct_id,product_name,product_description\nSKU-001,Hydrating Serum,\"A lightweight serum for dry skin.\"\nSKU-002,Brightening Cream,\"Evens out skin tone, for daily use.\"\nSKU-003,Barrier Repair Cream,\"Rich cream for dry, redness-prone skin.\"\n```\n\n```bash\n# Upload a catalog — validated in the same request\ncurl -sS -X POST \"$BASE_URL/s2s/v2.1/product-catalog\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -F \"file=@catalog.csv\" \\\n  -F \"name=Summer skincare\"\n```\n\n通過驗證的檔案會回傳 `status: ready`，並附上它的 `catalog_id` 與 `sku_count`——請保留這個 id：\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"catalog_id\": \"1662043585118399001\",\n    \"name\": \"Summer skincare\",\n    \"status\": \"ready\",\n    \"created_time\": 1760256000000,\n    \"sku_count\": 3\n  }\n}\n```\n\n```bash\n# List every catalog of your account, newest first (ready and failed alike)\ncurl -sS -H \"Authorization: Bearer $API_KEY\" \"$BASE_URL/s2s/v2.1/product-catalog\"\n\n# Delete a catalog — immediate and permanent\ncurl -sS -X DELETE -H \"Authorization: Bearer $API_KEY\" \\\n  \"$BASE_URL/s2s/v2.1/product-catalog/1662043585118399001\"\n```\n\n**目錄狀態與限制**\n\n| 狀態 | 意義 | 可用於肌膚檢測 |\n|---|---|---|\n| `ready` | 已上傳並通過驗證 | 是 |\n| `failed` | 已上傳，但檔案驗證失敗 | 否 |\n\n驗證失敗的上傳會回傳錯誤，而且**仍會被記錄成一個 `failed` 目錄**，在「列出目錄」中看得到它；錯誤內容不會帶出它的 `catalog_id`。每個帳號最多可保留 **10 個目錄**，`ready` 與 `failed` 合併計算——上傳新目錄前請先刪掉一個。要更新目錄，請上傳新檔案：每次上傳都會建立新的 `catalog_id`，舊目錄在您刪除前仍可使用，因此可以先確認新目錄再切換。\n\n---\n\n* 建立 AI 任務\n\n```bash\n# Skin Intel System — Report + Recommendations\ncurl -sS -X POST \"$BASE_URL/s2s/v2.1/task/skin-analysis-report-recommendation\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"src_file_url\": \"https://your-cdn.example.com/customer-001.jpg\",\n    \"dst_actions\": [\n      \"hd_skin_type\", \"hd_wrinkle\", \"hd_pore\", \"hd_texture\",\n      \"hd_acne\", \"hd_redness\", \"hd_oiliness\", \"hd_moisture\",\n      \"hd_age_spot\", \"hd_radiance\", \"hd_dark_circle\", \"hd_firmness\",\n      \"hd_eye_bag\", \"hd_tear_trough\", \"hd_droopy_upper_eyelid\",\n      \"hd_droopy_lower_eyelid\"\n    ],\n    \"format\": \"zip\",\n    \"pf_camera_kit\": true,\n    \"miniserver_args\": {\n      \"enable_mask_overlay\": true\n    },\n    \"advanced_report\": {\n      \"language\": \"enu\",\n      \"tone\": \"warm\",\n      \"country\": \"United States\",\n      \"city\": \"New York\"\n    },\n    \"product_recommendation\": {\n      \"catalog_id\": \"1662043585118399001\",\n      \"top_n\": 3\n    }\n  }'\n```\n\n---\n\n* 輪詢取得報告與推薦\n\n每次呼叫都會立刻回傳一個 `BasicRunTaskResponseV2`；用回傳的 id 輪詢任務就行，報告與推薦結果都放在 **`llm_results.json`** 裡。\n\n```bash\n# 1. Run the task and capture the task id\nTASK_ID=$(curl -sS -X POST \"$BASE_URL/s2s/v2.1/task/skin-analysis-report-recommendation\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ ... }' | jq -r '.data.task_id')\n\n# 2. Poll until task_status is \"success\"\ncurl -sS -H \"Authorization: Bearer $API_KEY\" \\\n  \"$BASE_URL/s2s/v2.1/task/skin-analysis-report-recommendation/$TASK_ID\"\n```\n\n`task_status` 會從 `running` 走到 `success` | `error`。用 `format: zip` 時，`results.url` 是一條有效期限 **2 小時**的下載連結，ZIP 裡有一個 `skinanalysisResult` 資料夾，包含 `score_info.json` 與所有偵測結果圖片。用 `format: json` 時，`results.output` 會把分數直接回傳在回應內容中。\n\n---\n\n* 請求欄位速查\n\n| 欄位 | 必填 | 說明 |\n|---|---|---|\n| `src_file_id` / `src_file_url` | 是（二者其一） | 輸入圖片，規則依 `BasicRunTaskV2` |\n| `dst_actions` | **是** | 要全選 HD 功能，**或**全選 SD 功能——不可混用 |\n| `format` | 否 | `zip`（預設）\\| `json`——兩者的回應 schema 不同 |\n| `pf_camera_kit` | 否 | V2.1 新增；臉部輪廓與五官定位 |\n| `miniserver_args` | 否 | 遮罩疊加，以及 HD 毛孔／皺紋的背景控制項 |\n| `advanced_report` | 否 | 有送就出報告；`{}` 表示全採預設值；不送就沒有報告 |\n| `product_recommendation` | 否 | 有送就出推薦；需要 `catalog_id` |\n\n**解析度。** 所有輸出圖片的長邊都以 **2560 px** 為上限，輸入圖片會自動調整尺寸。若 `enable_mask_overlay` 為 `false`，您拿到的是原始遮罩 `.png`，必須自行合成——請先確認輸入解析度，長邊超過 2560 px 時，就以 2560 px 來設定您的顯示尺寸。\n\n---\n"
    },
    {
      "name": "Product Catalogs",
      "description": "## 端點總覽\n\n產品目錄是 AI 肌膚檢測用於產品推薦的產品清單。上傳您的目錄\n一次，保留其 `catalog_id`，並將該 id 傳給肌膚檢測。目錄會保留到您刪除為止。\n\n目錄屬於您的帳號，而非單一 API key：帳號中的所有 API key（包含專案 key）都能看見\n相同的目錄，輪換或刪除 key 不會影響它們。\n\n上傳與儲存目錄是免費的。\n\n* 目錄檔案\n\n| 項目 | 值 |\n|---|---|\n| 格式 | 含標題列的 CSV |\n| 編碼 | UTF-8，可含或不含位元組順序標記（BOM）。Excel 的「CSV UTF-8」格式會加入 BOM。 |\n| 最大檔案大小 | 5 MB |\n| 最大 SKU 數量 | 除檔案大小外無限制 |\n\n必要欄位：\n\n| 欄位 | 說明 |\n|---|---|\n| `product_id` | 您的產品 id |\n| `product_name` | 產品名稱 |\n| `product_description` | 產品說明 |\n\n其他欄位會被忽略，但仍計入 5 MB 限制。含逗號或換行的值必須\n加引號，如同標準 CSV。每個非空的資料列計為一個 SKU。\n\n範例：\n\n```csv\nproduct_id,product_name,product_description\nSKU-001,Hydrating Serum,\"A lightweight serum for dry skin.\"\nSKU-002,Brightening Cream,\"Evens out skin tone, for daily use.\"\n```\n\n* 目錄狀態\n\n| 狀態 | 意義 | 可用於肌膚檢測 |\n|---|---|---|\n| `ready` | 已上傳並通過驗證 | 是 |\n| `failed` | 已上傳，但檔案驗證失敗 | 否 |\n\n驗證失敗的上傳會回傳錯誤，並仍被記錄為 `failed` 目錄，在「列出目錄」中可見。\n像刪除其他目錄一樣刪除它。\n\n* 限制\n\n每個帳號最多可保留 10 個目錄，`ready` 與 `failed` 一計計算。上傳新的目錄前請先刪除一個。\n\n要更新目錄，請上傳新檔案：每次上傳都會建立新的 `catalog_id`，舊目錄在您刪除前仍可使用，\n因此您可以在切換前先檢查新的目錄。\n\n* 刪除\n\n刪除目錄是立即且永久的。自那一刻起，所有使用其 `catalog_id` 的肌膚檢測呼叫\n都會失敗。已刪除的目錄無法恢復；再次上傳相同的檔案會建立一個新的目錄，\n帶有新的 `catalog_id`。\n"
    }
  ],
  "paths": {
    "/s2s/v2.1/task/skin-analysis": {
      "post": {
        "summary": "執行肌膚檢測 V2.1 任務。",
        "x-display-name": "AI Skin Analysis",
        "x-engine-version": "V2.1",
        "description": "AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 `success` 或 `error` 通知後，使用收到的 `task_id` 查詢任務結果。設定與驗證細節請見 [webhook 整合指南](/develop/webhook.md)。\n\n若您的整合不支援 webhook 或無法使用 webhook，請實作輪詢。送出 AI 任務後，以固定間隔（例如每 10 秒）輪詢狀態端點，直到任務狀態為 `success` 或 `error`。\n",
        "tags": [
          "Standard Analysis"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/RunSkincareTaskV2"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "pf_camera_kit": {
                        "type": "boolean",
                        "example": true
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "肌膚檢測任務執行成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BasicRunTaskResponseV2"
                }
              }
            }
          },
          "400": {
            "description": "任務執行失敗。除了常見狀況外，請求如果送了 `advanced_report` 或 `product_recommendation`，會回傳 `InvalidParameters`，而且不扣點數。需要這兩項功能時，請改用 skin-analysis-report、skin-analysis-recommendation 或 skin-analysis-report-recommendation 端點。\n",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/RunError"
                    }
                  ]
                },
                "examples": {
                  "advanced_report_not_supported": {
                    "summary": "本端點收到了 advanced_report",
                    "value": {
                      "status": 400,
                      "error": "advanced_report is not supported by this endpoint.",
                      "error_code": "InvalidParameters"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/s2s/v2.1/task/skin-analysis/{task_id}": {
      "get": {
        "summary": "查詢肌膚檢測 V2.1 任務的狀態。",
        "x-display-name": "AI Skin Analysis",
        "x-engine-version": "V2.1",
        "tags": [
          "Standard Analysis"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
            },
            "description": "要查詢的任務 ID"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/SkinAnalysisResponse"
          },
          "400": {
            "$ref": "#/components/responses/InvalidTaskId"
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "500": {
            "$ref": "#/components/responses/TaskTimeout"
          }
        }
      }
    },
    "/s2s/v2.1/task/skin-analysis-report": {
      "post": {
        "summary": "執行「肌膚檢測＋進階肌膚報告」任務。",
        "x-display-name": "AI Skin Analysis",
        "x-engine-version": "V2.1",
        "description": "AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 `success` 或 `error` 通知後，使用收到的 `task_id` 查詢任務結果。設定與驗證細節請見 [webhook 整合指南](/develop/webhook.md)。\n\n若您的整合不支援 webhook 或無法使用 webhook，請實作輪詢。送出 AI 任務後，以固定間隔（例如每 10 秒）輪詢狀態端點，直到任務狀態為 `success` 或 `error`。\n",
        "tags": [
          "Analysis + Advanced Report"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/RunSkincareTaskV2"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "pf_camera_kit": {
                        "type": "boolean",
                        "example": true
                      },
                      "advanced_report": {
                        "$ref": "#/components/schemas/SkinAnalysisAdvancedReport"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "「肌膚檢測＋進階肌膚報告」任務執行成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BasicRunTaskResponseV2"
                }
              }
            }
          },
          "400": {
            "description": "任務執行失敗。除了常見狀況外，請求如果送了 `product_recommendation`，會回傳 `InvalidParameters`，而且不扣點數。\n",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/RunError"
                    }
                  ]
                },
                "examples": {
                  "product_recommendation_not_supported": {
                    "summary": "本端點收到了 product_recommendation",
                    "value": {
                      "status": 400,
                      "error": "product_recommendation is not supported by this endpoint.",
                      "error_code": "InvalidParameters"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/s2s/v2.1/task/skin-analysis-report/{task_id}": {
      "get": {
        "summary": "查詢「肌膚檢測＋進階肌膚報告」任務的狀態。",
        "x-display-name": "AI Skin Analysis",
        "x-engine-version": "V2.1",
        "tags": [
          "Analysis + Advanced Report"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
            },
            "description": "要查詢的任務 ID"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/SkinAnalysisResponse"
          },
          "400": {
            "$ref": "#/components/responses/InvalidTaskId"
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "500": {
            "$ref": "#/components/responses/TaskTimeout"
          }
        }
      }
    },
    "/s2s/v2.1/task/skin-analysis-recommendation": {
      "post": {
        "summary": "執行「肌膚檢測＋產品推薦」任務。",
        "x-display-name": "AI Skin Analysis",
        "x-engine-version": "V2.1",
        "description": "AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 `success` 或 `error` 通知後，使用收到的 `task_id` 查詢任務結果。設定與驗證細節請見 [webhook 整合指南](/develop/webhook.md)。\n\n若您的整合不支援 webhook 或無法使用 webhook，請實作輪詢。送出 AI 任務後，以固定間隔（例如每 10 秒）輪詢狀態端點，直到任務狀態為 `success` 或 `error`。\n",
        "tags": [
          "Analysis + Product Recommendation"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/RunSkincareTaskV2"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "pf_camera_kit": {
                        "type": "boolean",
                        "example": true
                      },
                      "product_recommendation": {
                        "$ref": "#/components/schemas/SkinAnalysisProductRecommendation"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "「肌膚檢測＋產品推薦」任務執行成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BasicRunTaskResponseV2"
                }
              }
            }
          },
          "400": {
            "description": "任務執行失敗。除了常見狀況外，出現下列情況時請求會回傳 `InvalidParameters`，而且不扣點數：\n* 未提供 `product_recommendation`\n* 送了 `advanced_report`\n* 提供了 `product_recommendation` 卻沒有 `catalog_id`\n* `product_recommendation.catalog_id` 不存在、已被刪除，或屬於其他帳號\n* `product_recommendation.catalog_id` 指向的目錄在上傳時未通過驗證\n* `product_recommendation.top_n` 不是至少為 1 的整數\n* `product_recommendation.top_n` 大於目錄中的產品數量\n",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/RunError"
                    }
                  ]
                },
                "examples": {
                  "product_recommendation_required": {
                    "summary": "缺少 product_recommendation",
                    "value": {
                      "status": 400,
                      "error": "product_recommendation is required for this endpoint.",
                      "error_code": "InvalidParameters"
                    }
                  },
                  "advanced_report_not_supported": {
                    "summary": "本端點收到了 advanced_report",
                    "value": {
                      "status": 400,
                      "error": "advanced_report is not supported by this endpoint.",
                      "error_code": "InvalidParameters"
                    }
                  },
                  "catalog_id_required": {
                    "summary": "product_recommendation 沒有 catalog_id",
                    "value": {
                      "status": 400,
                      "error": "catalog_id is required when product_recommendation is provided.",
                      "error_code": "InvalidParameters"
                    }
                  },
                  "catalog_not_found": {
                    "summary": "找不到該 catalog_id",
                    "value": {
                      "status": 400,
                      "error": "No catalog was found with this catalog_id.",
                      "error_code": "InvalidParameters"
                    }
                  },
                  "catalog_not_ready": {
                    "summary": "catalog_id 指向一個驗證失敗的目錄",
                    "value": {
                      "status": 400,
                      "error": "This catalog failed validation when it was uploaded and can't be used. Upload the catalog again.",
                      "error_code": "InvalidParameters"
                    }
                  },
                  "top_n_exceeds_sku_count": {
                    "summary": "top_n 超過目錄中的產品數量",
                    "value": {
                      "status": 400,
                      "error": "product_recommendation.top_n can't be more than the 3 products in this catalog.",
                      "error_code": "InvalidParameters"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/s2s/v2.1/task/skin-analysis-recommendation/{task_id}": {
      "get": {
        "summary": "查詢「肌膚檢測＋產品推薦」任務的狀態。",
        "x-display-name": "AI Skin Analysis",
        "x-engine-version": "V2.1",
        "tags": [
          "Analysis + Product Recommendation"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
            },
            "description": "要查詢的任務 ID"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/SkinAnalysisResponse"
          },
          "400": {
            "$ref": "#/components/responses/InvalidTaskId"
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "500": {
            "$ref": "#/components/responses/TaskTimeout"
          }
        }
      }
    },
    "/s2s/v2.1/task/skin-analysis-report-recommendation": {
      "post": {
        "summary": "執行「肌膚檢測＋進階肌膚報告＋產品推薦」任務。",
        "x-display-name": "AI Skin Analysis",
        "x-engine-version": "V2.1",
        "description": "AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 `success` 或 `error` 通知後，使用收到的 `task_id` 查詢任務結果。設定與驗證細節請見 [webhook 整合指南](/develop/webhook.md)。\n\n若您的整合不支援 webhook 或無法使用 webhook，請實作輪詢。送出 AI 任務後，以固定間隔（例如每 10 秒）輪詢狀態端點，直到任務狀態為 `success` 或 `error`。\n",
        "tags": [
          "Analysis + Report + Recommendation"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/RunSkincareTaskV2"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "pf_camera_kit": {
                        "type": "boolean",
                        "example": true
                      },
                      "advanced_report": {
                        "$ref": "#/components/schemas/SkinAnalysisAdvancedReport"
                      },
                      "product_recommendation": {
                        "$ref": "#/components/schemas/SkinAnalysisProductRecommendation"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "「肌膚檢測＋進階肌膚報告＋產品推薦」任務執行成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BasicRunTaskResponseV2"
                }
              }
            }
          },
          "400": {
            "description": "任務執行失敗。除了常見狀況外，出現下列情況時請求會回傳 `InvalidParameters`，而且不扣點數：\n* 未提供 `product_recommendation`\n* 提供了 `product_recommendation` 卻沒有 `catalog_id`\n* `product_recommendation.catalog_id` 不存在、已被刪除，或屬於其他帳號\n* `product_recommendation.catalog_id` 指向的目錄在上傳時未通過驗證\n* `product_recommendation.top_n` 不是至少為 1 的整數\n* `product_recommendation.top_n` 大於目錄中的產品數量\n",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/RunError"
                    }
                  ]
                },
                "examples": {
                  "product_recommendation_required": {
                    "summary": "缺少 product_recommendation",
                    "value": {
                      "status": 400,
                      "error": "product_recommendation is required for this endpoint.",
                      "error_code": "InvalidParameters"
                    }
                  },
                  "catalog_id_required": {
                    "summary": "product_recommendation 沒有 catalog_id",
                    "value": {
                      "status": 400,
                      "error": "catalog_id is required when product_recommendation is provided.",
                      "error_code": "InvalidParameters"
                    }
                  },
                  "catalog_not_found": {
                    "summary": "找不到該 catalog_id",
                    "value": {
                      "status": 400,
                      "error": "No catalog was found with this catalog_id.",
                      "error_code": "InvalidParameters"
                    }
                  },
                  "catalog_not_ready": {
                    "summary": "catalog_id 指向一個驗證失敗的目錄",
                    "value": {
                      "status": 400,
                      "error": "This catalog failed validation when it was uploaded and can't be used. Upload the catalog again.",
                      "error_code": "InvalidParameters"
                    }
                  },
                  "top_n_exceeds_sku_count": {
                    "summary": "top_n 超過目錄中的產品數量",
                    "value": {
                      "status": 400,
                      "error": "product_recommendation.top_n can't be more than the 3 products in this catalog.",
                      "error_code": "InvalidParameters"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/s2s/v2.1/task/skin-analysis-report-recommendation/{task_id}": {
      "get": {
        "summary": "查詢「肌膚檢測＋進階肌膚報告＋產品推薦」任務的狀態。",
        "x-display-name": "AI Skin Analysis",
        "x-engine-version": "V2.1",
        "tags": [
          "Analysis + Report + Recommendation"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
            },
            "description": "要查詢的任務 ID"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/SkinAnalysisResponse"
          },
          "400": {
            "$ref": "#/components/responses/InvalidTaskId"
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "500": {
            "$ref": "#/components/responses/TaskTimeout"
          }
        }
      }
    },
    "/s2s/v2.1/product-catalog": {
      "post": {
        "summary": "上傳產品目錄。",
        "description": "以 CSV 檔案上傳產品目錄。檔案會在同一次請求中完成驗證：驗證通過的檔案回傳 `status` `ready`，並附上它的 `catalog_id` 與 `sku_count`；驗證失敗的檔案會回傳錯誤，同時仍會被記錄成一個 `failed` 目錄，「列出目錄」會把它列出來。",
        "tags": [
          "Product Catalogs"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "example": "@catalog.csv",
                    "description": "目錄檔案。其格式、編碼、大小上限與必要欄位，請見產品目錄章節下的「目錄檔案」。"
                  },
                  "name": {
                    "type": "string",
                    "description": "您為目錄自訂的名稱，會顯示在「列出目錄」中。未提供時 `name` 為 `null`。",
                    "example": "Summer skincare"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "目錄已上傳，可用於肌膚檢測",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "integer",
                      "description": "回應狀態",
                      "example": 200
                    },
                    "data": {
                      "$ref": "#/components/schemas/ProductCatalog"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ProductCatalogUploadError"
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          }
        }
      },
      "get": {
        "summary": "列出產品目錄。",
        "description": "列出您帳號下的所有目錄，最新的排在最前面，`ready` 與 `failed` 都會列出。手邊沒有某個 `catalog_id` 時，可以用它找回。不分頁：每個帳號可保留的目錄數量有上限（見產品目錄章節下的「限制」）。",
        "tags": [
          "Product Catalogs"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "responses": {
          "200": {
            "description": "帳號中的所有目錄",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "integer",
                      "description": "回應狀態",
                      "example": 200
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "catalogs": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ProductCatalog"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          }
        }
      }
    },
    "/s2s/v2.1/product-catalog/{catalog_id}": {
      "delete": {
        "summary": "刪除產品目錄。",
        "description": "刪除目錄立即生效且不可恢復。從那一刻起，所有使用該 `catalog_id` 的肌膚檢測呼叫都會失敗。已刪除的目錄無法復原。",
        "tags": [
          "Product Catalogs"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "parameters": [
          {
            "name": "catalog_id",
            "in": "path",
            "required": true,
            "description": "「上傳產品目錄」回傳的 `catalog_id`。",
            "schema": {
              "type": "string",
              "example": "1662043585118399001"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "目錄已刪除",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "integer",
                      "description": "回應狀態",
                      "example": 200
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "404": {
            "$ref": "#/components/responses/ProductCatalogNotFound"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuthenticationV2": {
        "type": "http",
        "scheme": "bearer",
        "description": "使用標準的 'Bearer authentication'。請在標頭中放入您的 'API Key'：`Authorization:Bearer YOUR_API_KEY`。請注意 'Bearer' 與 'YOUR_API_KEY' 之間有一個空格。"
      }
    },
    "schemas": {
      "RunSkincareTaskV2": {
        "allOf": [
          {
            "$ref": "#/components/schemas/BasicRunTaskV2"
          },
          {
            "title": "RunSkincareTaskV2",
            "description": "這個物件代表一個執行肌膚檢測任務。",
            "type": "object",
            "properties": {
              "dst_actions": {
                "$ref": "#/components/schemas/RunSkincareTaskDstActions"
              },
              "miniserver_args": {
                "$ref": "#/components/schemas/RunSkincareTaskMiniserverArgs"
              },
              "format": {
                "type": "string",
                "enum": [
                  "json",
                  "zip"
                ],
                "description": "分析結果的回應格式。預設為 'zip'。- `zip`：結果會被打包成可下載的 ZIP 檔案，內含 skinanalysisResult 資料夾，包含 score_info.json 與所有偵測結果圖片。回應會包含下載該 ZIP 檔案的網址。- `json`：結果會以 JSON 格式直接回傳在回應內容中。請注意：format=json 與 format=zip 的回應 schema 不同。\n",
                "example": "zip"
              }
            },
            "required": [
              "dst_actions"
            ]
          }
        ]
      },
      "RunSkincareTaskDstActions": {
        "type": "array",
        "description": "肌膚檢測的動作項目。\n共有 2 種功能類型：HD 與 SD。\n您可選擇一項或多項功能，但必須全部為 SD 或全部為 HD。\n注意：HD 與 SD 功能不可混合。\nHD 功能：\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：分析整體肌膚質地。\n  - hd_acne：偵測痤瘡。\n  - hd_pore：偵測並評估不同臉部區域的毛孔（額頭、鼻子、臉頰、全臉）。\n  - hd_wrinkle：測量各臉部區域的皺紋嚴重程度（額頭、眉間、魚尾紋、眼周、法令紋、木偶紋、全臉）。\n  - hd_tear_trough：偵測淚溝。\n  - hd_skin_type：子類別（全臉、T 區、U 區）評估膚質為正常、油性、乾性、混合性、泛紅、乾性且泛紅、油性且泛紅，或混合性且泛紅。\n\nSD 功能：\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：子類別（全臉、T 區、U 區）評估膚質為正常、油性、乾性、混合性、泛紅、乾性且泛紅、油性且泛紅，或混合性且泛紅。\n",
        "items": {
          "type": "string",
          "enum": [
            "hd_wrinkle",
            "hd_pore",
            "hd_texture",
            "hd_acne",
            "hd_oiliness",
            "hd_radiance",
            "hd_eye_bag",
            "hd_age_spot",
            "hd_dark_circle",
            "hd_droopy_upper_eyelid",
            "hd_droopy_lower_eyelid",
            "hd_firmness",
            "hd_moisture",
            "hd_redness",
            "hd_tear_trough",
            "hd_skin_type",
            "wrinkle",
            "pore",
            "texture",
            "acne",
            "oiliness",
            "radiance",
            "eye_bag",
            "age_spot",
            "dark_circle_v2",
            "droopy_upper_eyelid",
            "droopy_lower_eyelid",
            "firmness",
            "moisture",
            "redness",
            "tear_trough",
            "skin_type"
          ]
        },
        "example": [
          "hd_wrinkle",
          "hd_pore",
          "hd_texture",
          "hd_acne"
        ]
      },
      "RunSkincareTaskMiniserverArgs": {
        "type": "object",
        "properties": {
          "enable_mask_overlay": {
            "type": "boolean",
            "description": "控制是否將遮罩混合到圖片上。True 會以 .jpg 回傳疊加後的圖片。False 會以 .png 回傳原始遮罩。預設為 false。 <br> 所有輸出圖片的長邊解析度上限為 2560 像素。若未啟用 enable_mask_overlay，您必須自行確認輸入解析度是否超過 2560，並在您端相應處理遮罩疊加。當輸入圖片的長邊低於 2560 像素時，使用原始圖片解析度。否則，請使用 2560 像素來設定您的顯示。"
          },
          "enable_dark_background_hd_pore": {
            "type": "boolean",
            "description": "為 HD 毛孔視覺化啟用深色背景"
          },
          "color_dark_background_hd_pore": {
            "type": "string",
            "description": "HD 毛孔深色背景視覺化的顏色（hex 格式）",
            "example": "3D3D3D"
          },
          "opacity_dark_background_hd_pore": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "HD 毛孔深色背景視覺化的不透明度",
            "example": 0.4
          },
          "enable_dark_background_hd_wrinkle": {
            "type": "boolean",
            "description": "為 HD 皺紋視覺化啟用深色背景"
          },
          "color_dark_background_hd_wrinkle": {
            "type": "string",
            "description": "HD 皺紋深色背景視覺化的顏色（hex 格式）",
            "example": "3D3D3D"
          },
          "opacity_dark_background_hd_wrinkle": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "HD 皺紋深色背景視覺化的不透明度",
            "example": 0.4
          }
        }
      },
      "SkinAnalysisResponseV2": {
        "type": "object",
        "properties": {
          "status": {
            "type": "integer",
            "description": "回應狀態",
            "example": 200
          },
          "data": {
            "type": "object",
            "properties": {
              "task_status": {
                "type": "string",
                "enum": [
                  "running",
                  "success",
                  "error"
                ],
                "description": "這個任務的狀態"
              },
              "error": {
                "$ref": "#/components/schemas/EngineErrorCode"
              },
              "error_message": {
                "type": "string",
                "description": "錯誤的詳細說明"
              },
              "results": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/SkinAnalysisResultsV2Zip"
                  },
                  {
                    "$ref": "#/components/schemas/SkinAnalysisResultsV2Json"
                  }
                ]
              }
            }
          }
        }
      },
      "SkinAnalysisResultsV2Zip": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "description": "下載這個結果的網址。有效期限 2 小時。回傳的 ZIP 檔案包含一個 skinanalysisResult 資料夾，內有 score_info.json 檔案，記錄所有偵測結果的分數，以及所有偵測結果的圖片。當要求進階肌膚報告或產品推薦時，該資料夾也會包含 llm_results.json。僅在格式為 `zip` 時可用。",
            "example": "https://example.com/sample-result-url"
          }
        }
      },
      "SkinAnalysisResultsV2Json": {
        "type": "object",
        "required": [
          "output"
        ],
        "properties": {
          "output": {
            "type": "array",
            "description": "以 JSON 格式直接回傳在回應內容中的分析結果。當要求進階肌膚報告或產品推薦時，輸出也會有一個 `type` 為 `llm_results` 的項目；其 `mask_urls[0]` 就是 llm_results.json 的網址。僅在格式為 `json` 時可用。",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "description": "肌膚檢測的項目",
                  "example": "hd_skin_type"
                },
                "region": {
                  "type": "string",
                  "description": "分析聚焦的臉部區域",
                  "example": "whole"
                },
                "raw_score": {
                  "type": "number",
                  "description": "範圍 1 到 100 的浮點數。raw_score 指 AI 模型直接預測的分數",
                  "example": 98.5
                },
                "ui_score": {
                  "type": "integer",
                  "description": "範圍 1 到 100 的整數。ui_score 是依據 raw_score 調整後的分數",
                  "example": 97
                },
                "score": {
                  "type": "number",
                  "description": "介於 1 到 100 的浮點數，代表整體膚況。",
                  "example": 97.66
                },
                "mask_urls": {
                  "type": "array",
                  "description": "分析過程中產生的遮罩圖片或調整尺寸後圖片的網址",
                  "items": {
                    "type": "string",
                    "example": "https://example.com/mask_image_1.png"
                  }
                }
              }
            }
          }
        }
      },
      "SkinAnalysisAdvancedReport": {
        "type": "object",
        "description": "進階肌膚報告的選項，結果放在 llm_results.json 回傳。不送這個物件、或送一個空物件，即採用全預設值。\n",
        "properties": {
          "language": {
            "type": "string",
            "enum": [
              "enu",
              "cht",
              "jpn",
              "kor",
              "fra",
              "deu",
              "esn",
              "ita",
              "ptb",
              "ind",
              "ara"
            ],
            "default": "enu",
            "description": "報告使用的語言。",
            "example": "cht"
          },
          "tone": {
            "type": "string",
            "enum": [
              "warm",
              "direct"
            ],
            "default": "warm",
            "description": "報告的語氣。兩種語氣都維持專業。",
            "example": "direct"
          },
          "country": {
            "type": "string",
            "description": "用於替報告加入氣候與季節脈絡的國家。",
            "example": "Taiwan"
          },
          "city": {
            "type": "string",
            "description": "用於替報告加入氣候與季節脈絡的城市。",
            "example": "Taipei"
          }
        }
      },
      "SkinAnalysisProductRecommendation": {
        "type": "object",
        "description": "必填。從您的某個產品目錄中推薦產品，結果放在 llm_results.json 回傳。\n",
        "properties": {
          "catalog_id": {
            "type": "string",
            "description": "必填。您以產品目錄 API 上傳的產品目錄 ID。該目錄必須為 ready 狀態，且屬於您的帳號。\n",
            "example": "123456789012345678"
          },
          "top_n": {
            "type": "integer",
            "minimum": 1,
            "default": 3,
            "description": "每項肌膚困擾要推薦的產品數。不得超過目錄中的產品數量。\n",
            "example": 3
          }
        }
      },
      "ProductCatalog": {
        "type": "object",
        "properties": {
          "catalog_id": {
            "type": "string",
            "description": "隨機生成、無法猜出的目錄 ID。把它傳給肌膚檢測，即可使用這個目錄。",
            "example": "1662043585118399001"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "上傳時給定的名稱；未給則為 `null`。",
            "example": "Summer skincare"
          },
          "status": {
            "type": "string",
            "enum": [
              "ready",
              "failed"
            ],
            "description": "目錄狀態：\n  * ready - 已上傳並通過驗證，可用於肌膚檢測\n  * failed - 檔案未通過驗證，不可使用\n"
          },
          "created_time": {
            "type": "integer",
            "format": "int64",
            "description": "上傳時間，毫秒單位的 Unix 時間戳記",
            "example": 1760256000000
          },
          "sku_count": {
            "type": "integer",
            "nullable": true,
            "description": "從檔案解析出的產品數量；`failed` 目錄為 `null`。",
            "example": 3
          }
        }
      },
      "BasicRunTaskV2SrcFileUrl": {
        "type": "object",
        "required": [
          "src_file_url"
        ],
        "properties": {
          "src_file_url": {
            "type": "string",
            "description": "要執行任務的檔案網址。該網址應可公開存取。",
            "example": "https://example.com/selfie.jpg"
          }
        }
      },
      "BasicRunTaskV2SrcFileId": {
        "type": "object",
        "required": [
          "src_file_id"
        ],
        "properties": {
          "src_file_id": {
            "type": "string",
            "description": "要執行任務的檔案 ID。檔案 ID 來自上傳檔案 API。",
            "example": "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE="
          }
        }
      },
      "BasicRunTaskV2": {
        "title": "BasicRunTaskV2",
        "anyOf": [
          {
            "title": "Run task with src file url",
            "allOf": [
              {
                "$ref": "#/components/schemas/BasicRunTaskV2SrcFileUrl"
              }
            ]
          },
          {
            "title": "Run task with src file ID",
            "allOf": [
              {
                "$ref": "#/components/schemas/BasicRunTaskV2SrcFileId"
              }
            ]
          }
        ]
      },
      "BasicRunTaskResponseV2": {
        "type": "object",
        "properties": {
          "status": {
            "type": "integer",
            "description": "回應狀態",
            "example": 200
          },
          "data": {
            "type": "object",
            "properties": {
              "task_id": {
                "type": "string",
                "description": "這個任務的 ID。任務結果可以此 ID 查詢，有效期限 24 小時。",
                "example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
              }
            }
          }
        }
      },
      "RunError": {
        "type": "object",
        "properties": {
          "status": {
            "type": "integer",
            "description": "回應狀態",
            "example": 400
          },
          "error": {
            "type": "string",
            "description": "錯誤訊息",
            "example": "The operation could not be completed"
          },
          "error_code": {
            "type": "string",
            "enum": [
              "InvalidParameters",
              "CreditInsufficiency",
              "InvalidStyleGroup",
              "InvalidStyle",
              "BadRequest"
            ],
            "description": "錯誤代碼：\n* InvalidParameters - 請求參數無效\n* CreditInsufficiency - 點數不足，無法執行\n* BadRequest - 非預期的請求參數\n* InvalidStyleGroup - 風格群組 id 無效\n* InvalidStyle - 風格 id 無效\n"
          }
        }
      },
      "EngineErrorCode": {
        "type": "string",
        "nullable": true,
        "enum": [
          "error_exceed_max_image_size",
          "exceed_max_filesize",
          "invalid_parameter",
          "error_download_image",
          "error_download_mask",
          "error_decode_image",
          "error_decode_mask",
          "error_nsfw_content_detected",
          "error_no_face",
          "error_pose",
          "error_face_parsing",
          "error_inference",
          "exceed_nsfw_retry_limits",
          "error_upload",
          "unknown_internal_error"
        ],
        "description": "錯誤：\n- \\`error_exceed_max_image_size\\`  - 輸入圖片尺寸超過上限\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_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- \\`unknown_internal_error\\` - 其他"
      }
    },
    "responses": {
      "SkinAnalysisResponse": {
        "description": "成功查詢肌膚檢測任務的狀態",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/SkinAnalysisResponseV2"
                }
              ]
            },
            "examples": {
              "format_zip_success": {
                "summary": "format=zip 時的回應（成功）",
                "description": "任務成功完成。結果被打包成 ZIP 檔案。",
                "value": {
                  "status": 200,
                  "data": {
                    "task_status": "success",
                    "results": "https://example.com/sample-result-url"
                  }
                }
              },
              "format_json_success": {
                "summary": "format=json 時的回應（成功）",
                "description": "任務成功完成。結果以 JSON 直接回傳，包含詳細分數與圖片網址。",
                "value": {
                  "status": 200,
                  "data": {
                    "task_status": "success",
                    "results": {
                      "output": [
                        {
                          "type": "hd_wrinkle",
                          "region": "whole",
                          "raw_score": 25.3,
                          "ui_score": 25,
                          "mask_urls": [
                            "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_wrinkle_whole.jpg"
                          ]
                        },
                        {
                          "type": "hd_wrinkle",
                          "region": "forehead",
                          "raw_score": 20.1,
                          "ui_score": 20,
                          "mask_urls": [
                            "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_wrinkle_forehead.jpg"
                          ]
                        },
                        {
                          "type": "hd_wrinkle",
                          "region": "glabellar",
                          "raw_score": 15.8,
                          "ui_score": 16,
                          "mask_urls": [
                            "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_wrinkle_glabellar.jpg"
                          ]
                        },
                        {
                          "type": "hd_wrinkle",
                          "region": "crowfeet",
                          "raw_score": 30.5,
                          "ui_score": 31,
                          "mask_urls": [
                            "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_wrinkle_crowfeet.jpg"
                          ]
                        },
                        {
                          "type": "hd_pore",
                          "region": "whole",
                          "raw_score": 35.2,
                          "ui_score": 35,
                          "mask_urls": [
                            "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_pore_whole.jpg"
                          ]
                        },
                        {
                          "type": "hd_pore",
                          "region": "forehead",
                          "raw_score": 30,
                          "ui_score": 30,
                          "mask_urls": [
                            "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_pore_forehead.jpg"
                          ]
                        },
                        {
                          "type": "hd_pore",
                          "region": "nose",
                          "raw_score": 45.7,
                          "ui_score": 46,
                          "mask_urls": [
                            "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_pore_nose.jpg"
                          ]
                        },
                        {
                          "type": "hd_pore",
                          "region": "cheek",
                          "raw_score": 32.1,
                          "ui_score": 32,
                          "mask_urls": [
                            "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_pore_cheek.jpg"
                          ]
                        },
                        {
                          "type": "hd_acne",
                          "region": "whole",
                          "raw_score": 12.5,
                          "ui_score": 13,
                          "mask_urls": [
                            "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_acne_whole.jpg"
                          ]
                        },
                        {
                          "type": "skin_age",
                          "score": 29
                        },
                        {
                          "type": "all",
                          "score": 28.5
                        },
                        {
                          "type": "resize_image",
                          "mask_urls": [
                            "https://s3-us-west-2.amazonaws.com/yce-us/results/resized_image.jpg"
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      },
      "ProductCatalogUploadError": {
        "description": "上傳被拒絕。驗證失敗的檔案仍會被記錄成一個 `failed` 目錄；錯誤內容不會帶出它的 `catalog_id`。",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "integer",
                  "example": 400,
                  "description": "回應狀態"
                },
                "error": {
                  "type": "string",
                  "description": "錯誤訊息",
                  "example": "The file must be UTF-8 encoded. Detected encoding: BIG5."
                },
                "error_code": {
                  "type": "string",
                  "enum": [
                    "InvalidParameters",
                    "ExceedMaxNumOfProductCatalog"
                  ],
                  "description": "錯誤代碼：\n  * InvalidParameters - 請求或目錄檔案無效\n  * ExceedMaxNumOfProductCatalog - 帳號已保留的目錄數量已達上限\n"
                }
              }
            }
          }
        }
      },
      "ProductCatalogNotFound": {
        "description": "您的帳號中不存在此 `catalog_id` 的目錄",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "integer",
                  "example": 404,
                  "description": "回應狀態"
                },
                "error": {
                  "type": "string",
                  "description": "錯誤訊息",
                  "example": "No catalog was found with this catalog_id."
                },
                "error_code": {
                  "type": "string",
                  "enum": [
                    "NotFound"
                  ],
                  "description": "錯誤代碼：\n  * NotFound - `catalog_id` 不存在，或屬於其他帳號\n"
                }
              }
            }
          }
        }
      },
      "InvalidApiKey": {
        "description": "API 金鑰無效或缺失",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "integer",
                  "example": 401,
                  "description": "回應狀態"
                },
                "error": {
                  "type": "string",
                  "example": "Invalid API key"
                }
              }
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "請求過多",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "integer",
                  "example": 429,
                  "description": "回應狀態"
                },
                "error": {
                  "type": "string",
                  "example": "Too many requests"
                }
              }
            }
          }
        }
      },
      "InvalidTaskId": {
        "description": "任務 ID 無效",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "integer",
                  "example": 400,
                  "description": "回應狀態"
                },
                "error": {
                  "type": "string",
                  "example": "Invalid task ID"
                }
              }
            }
          }
        }
      },
      "TaskTimeout": {
        "description": "任務執行逾時",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "integer",
                  "example": 500,
                  "description": "回應狀態"
                },
                "error": {
                  "type": "string",
                  "example": "Task execution timed out"
                }
              }
            }
          }
        }
      }
    }
  }
}