{ "openapi": "3.0.0", "info": { "title": "AI 肌膚檢測", "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：調整來源圖片尺寸**
\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)**。
\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/ \\\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 像素。
長邊沒有限制；但若超過 2560 像素，系統會自動調整為 2560 像素。 | < 10MB | jpg/jpeg/png |\n| HD 護膚 | 短邊長度至少需 1080 像素。
長邊沒有限制；但若超過 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
- curl >= 7.58（現代 TLS/HTTP 支援）
- jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | 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 + 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", "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": "V2.0", "description": "AI 護膚分析技術運用人工智慧的力量，以極高的精準度分析肌膚的各個層面，從質地、色素到保濕與毛孔大小。" } ], "paths": { "/s2s/v2.0/task/skin-analysis": { "post": { "summary": "執行肌膚檢測任務。", "description": "AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 `success` 或 `error` 通知後，使用收到的 `task_id` 查詢任務結果。設定與驗證細節請見 [webhook 整合指南](/develop/webhook.md)。\n\n若您的整合不支援 webhook 或無法使用 webhook，請實作輪詢。送出 AI 任務後，以固定間隔（例如每 10 秒）輪詢狀態端點，直到任務狀態為 `success` 或 `error`。\n", "tags": [ "V2.0" ], "security": [ { "BearerAuthenticationV2": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunSkincareTaskV2" } } } }, "responses": { "200": { "description": "肌膚檢測任務執行成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicRunTaskResponseV2" } } } }, "400": { "$ref": "#/components/responses/RunError" }, "401": { "$ref": "#/components/responses/InvalidApiKey" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/s2s/v2.0/task/skin-analysis/{task_id}": { "get": { "summary": "查詢肌膚檢測任務的狀態。", "description": "AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 `success` 或 `error` 通知後，使用收到的 `task_id` 查詢任務結果。設定與驗證細節請見 [webhook 整合指南](/develop/webhook.md)。\n\n若您的整合不支援 webhook 或無法使用 webhook，請實作輪詢。送出 AI 任務後，以固定間隔（例如每 10 秒）輪詢狀態端點，直到任務狀態為 `success` 或 `error`。\n", "tags": [ "V2.0" ], "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" } } } } }, "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。
所有輸出圖片的長邊解析度上限為 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 } } }, "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" } } } } }, "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" ] } ] } } } } } } } }, "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" } } }, "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" } } } } } } } } }