AI 肌膚檢測 V2.1

整合指南

• 如何為 AI 肌膚檢測拍攝照片

• 正面自拍

  • 只需一張清晰的照片，直視鏡頭。讓頭髮放下垂於胸前，並確保直視前方，取得正面視角。
  • 或者，使用 JS Camera Kit 拍照。只需讓頭髮放下垂於胸前，不要綁起。

• 工作流程 肌膚檢測 API 使用指南 本指南說明如何使用 File API 與 AI 任務 API 上傳圖片並建立肌膚檢測任務。

  • 步驟 1：調整來源圖片尺寸
    調整您的照片以符合支援的尺寸——SD 長邊最多 2560 像素、短邊至少 480 像素；HD 長邊最多 2560 像素、短邊至少 1080 像素。細節請參考**檔案規格與錯誤**

  • 步驟 2：透過 File API 上傳檔案 metadata

• 圖片需求
  • 細節請參考**檔案規格與錯誤**

發送 POST 請求以初始化檔案上傳：

• 重要：僅呼叫 File API 並不會上傳您的檔案。您必須額外上傳檔案到File API 回應中提供的網址。該網址就是您的上傳目的地，請確保檔案成功傳輸到該處後再繼續。

  警告： 請注意，若您未將檔案上傳到 File API 回應中提供的網址，使用 AI API 時會得到 500 Server Error / unknown_internal_error 或 404 Not Found 錯誤。

• 步驟 3：取得上傳網址與檔案 ID

回應包含：

• requests.url – 用於圖片上傳的預簽名網址。
• file_id – 用於建立 AI 任務的識別碼。

回應範例：

• 步驟 4：上傳圖片到預簽名網址

使用提供的 requests.url 與標頭：

• 步驟 5：建立 AI 任務

使用步驟 2 的 file_id 建立肌膚檢測任務：

上傳完成後，您可以使用檔案 ID 或圖片檔案網址選擇要分析的任何膚況問題。請參考**輸入與輸出**。
接著，使用 檔案 ID 或圖片檔案網址執行增強任務，並取得 task_id。 請注意，不支援同時使用 SD 與 HD 膚況參數。

• 使用現有的公開圖片網址 無需上傳，您可以在啟動 AI 任務時直接提供可公開存取的圖片網址。

回應範例：

• 步驟 6：輪詢任務狀態

使用 task_id 取得任務結果：

這個 task_id 用於透過輪詢 GET 'task/skin-analysis' 監控任務狀態，以取得目前的引擎狀態。在引擎完成任務之前，狀態會維持為 'running'，此階段不會消耗點數。

處理後的結果在完成後保留 30 天。

• 無需短間隔輪詢。

• 在保留期限內可彈性設定輪詢間隔。

  重要： 仍需要輪詢以查詢任務狀態，因為執行時間無法保證。

引擎成功處理您的輸入檔案並生成結果影像後，任務會變為 'success' 狀態。您會取得處理後影像的網址，以及一個 dst_id，讓您在無需重新上傳結果圖片的情況下串接另一個 AI 任務。

點數僅在這種情況下會被消耗。若引擎處理任務失敗，任務狀態會變為 'error'，且不會消耗點數。 扣除點數時，系統會優先使用接近到期的點數。若到期日相同，則扣除最早取得的點數。

• 步驟 7：解讀結果

回應包含：

• ui_score – 使用者友善的分數。
• raw_score – 原始分析分數。
• mask_urls – 偵測遮罩的網址。

回應範例：

• 除錯指南

警告： 請注意，不支援同時使用 SD 與 HD 膚況參數。試圖偏離這些規格會導致 InvalidParameters 錯誤。

• 若您混合使用 HD 與 SD 膚況，會得到如下錯誤：
  {
      "status": 400,
      "error": "cannot mix HD and SD dst_actions",
      "error_code": "InvalidParameters"
  }

• 若您拼寫膚況錯誤，或傳送未知的膚況，會得到如下錯誤：
  {
      "status": 400,
      "error": "Not available dst_action abc123",
      "error_code": "InvalidParameters"
  }

• 實際範例：

輸入與輸出

• 輸入參數說明 控制 AI 肌膚檢測結果視覺輸出有兩種選項：生成多張圖片，每個膚況以獨立的遮罩呈現；或使用 enable_mask_overlay 參數產生單張混合圖片。預設情況下，系統輸出多個遮罩，讓您完全控制如何將每個膚況遮罩與圖片混合。

• 預設：enable_mask_overlay false

• 將 enable_mask_overlay 設為 true

• 輸出 ZIP 資料結構說明 系統提供一個 ZIP 檔案，內含 'skinanalysisResult' 資料夾。此資料夾包含一個 'score_info.json' 檔案，涵蓋所有偵測分數與結果圖片的參考。

'score_info.json' 檔案包含所有肌膚檢測偵測結果，含數值分數與對應輸出遮罩檔案的名稱。

PNG 檔案是可疊加在您原始圖片上的偵測結果遮罩。只需使用這些 PNG 檔案中的 alpha 值，將其與您的原始圖片混合，即可直接在來源圖片上看見偵測結果。

• 肌膚檢測結果 ZIP 中的檔案結構

• HD 護膚 ZIP

  • skinanalysisResult
    • score_info.json
    • hd_acne_output.png
    • hd_age_spot_output.png
    • hd_dark_circle_output.png
    • hd_droopy_lower_eyelid_output.png
    • hd_droopy_upper_eyelid_output.png
    • hd_eye_bag_output.png
    • hd_firmness_output.png
    • hd_moisture_output.png
    • hd_oiliness_output.png
    • hd_radiance_output.png
    • hd_redness_output.png
    • hd_texture_output.png
    • hd_pore_output_all.png
    • hd_pore_output_cheek.png
    • hd_pore_output_forehead.png
    • hd_pore_output_nose.png
    • hd_wrinkle_output_all.png
    • hd_wrinkle_output_crowfeet.png
    • hd_wrinkle_output_forehead.png
    • hd_wrinkle_output_glabellar.png
    • hd_wrinkle_output_marionette.png
    • hd_wrinkle_output_nasolabial.png
    • hd_wrinkle_output_periocular.png
    • hd_tear_trough.png
    • hd_skin_type.png

• SD 護膚 ZIP

  • skinanalysisResult
    • score_info.json
    • acne_output.png
    • age_spot_output.png
    • dark_circle_v2_output.png
    • droopy_lower_eyelid_output.png
    • droopy_upper_eyelid_output.png
    • eye_bag_output.png
    • firmness_output.png
    • moisture_output.png
    • oiliness_output.png
    • pore_output.png
    • radiance_output.png
    • redness_output.png
    • texture_output.png
    • wrinkle_output.png
    • tear_trough.png
    • skin_type.png

• JSON 資料結構（score_info.json）

  • "all"：介於 1 與 100 之間的浮點值，代表整體膚況。較高的分數代表更健康、更具美感的膚況。

  • "skin_age"：相對於全年齡層一般人口分布，由 AI 推得的肌膚年齡。

  • 每個類別包含：

    • "raw_score"：範圍從 1 到 100 的浮點值。較高的分數代表更健康、更具美感的膚況。
    • "ui_score"：範圍從 1 到 100 的整數。UI 分數主要作為美妝評估中的心理激勵因素。我們調整原始分數以產生更理想的結果，因為理解消費者通常偏好關於其皮膚健康的正面評價。此校準旨在維持底層的美妝心理架構，同時為使用者注入更多信心。
    • "output_mask_name"：對應輸出遮罩圖片的檔案名稱。

  • 類別與說明

    • HD 護膚：

      • "hd_redness"：測量皮膚泛紅的嚴重程度。
      • "hd_oiliness"：判定皮膚油脂程度。
      • "hd_age_spot"：偵測老化斑點與色素。
      • "hd_radiance"：評估皮膚光澤。
      • "hd_moisture"：評估皮膚保濕程度。
      • "hd_dark_circle"：分析眼下方黑眼圈的存在。
      • "hd_eye_bag"：偵測眼袋。
      • "hd_droopy_upper_eyelid"：測量上眼皮下垂的嚴重程度。
      • "hd_droopy_lower_eyelid"：測量下眼皮下垂的嚴重程度。
      • "hd_firmness"：評估皮膚緊實度與彈性。
      • "hd_texture"：子類別[whole]；分析整體皮膚質地。
      • "hd_acne"：子類別[whole]；偵測痤瘡的存在。
      • "hd_pore"：子類別[forehead, nose, cheek, whole]；偵測並評估不同臉部區域的毛孔。
      • "hd_wrinkle"：子類別[forehead, glabellar, crowfeet, periocular, nasolabial, marionette, whole]；測量各臉部區域皺紋的嚴重程度。
      • "hd_tear_trough"：偵測淚溝。
      • "hd_skin_type"：子類別[whole, t_zone, u_zone]，評估正常、油性、乾性、混合性、泛紅、乾性與泛紅、油性與泛紅、混合性與泛紅等膚質。

    • SD 護膚：

      • "wrinkle"：一般皺紋分析。
      • "droopy_upper_eyelid"：測量上眼皮下垂的嚴重程度。
      • "droopy_lower_eyelid"：測量下眼皮下垂的嚴重程度。
      • "firmness"：評估皮膚緊實度與彈性。
      • "acne"：評估痤瘡的存在。
      • "moisture"：測量皮膚保濕。
      • "eye_bag"：偵測眼袋。
      • "dark_circle_v2"：以另一種方法分析黑眼圈。
      • "age_spot"：偵測老化斑點。
      • "radiance"：評估皮膚亮度。
      • "redness"：測量皮膚泛紅。
      • "oiliness"：判定皮膚油脂。
      • "pore"：測量毛孔可見度。
      • "texture"：分析整體皮膚質地。
      • "tear_trough"：偵測淚溝。
      • "skin_type"：子類別[whole, t_zone, u_zone]，評估正常、油性、乾性、混合性、泛紅、乾性與泛紅、油性與泛紅、混合性與泛紅等膚質。

  • HD 護膚的 score_info.json 範例

    {
        "hd_redness": {
            "raw_score": 72.011962890625,
            "ui_score": 77,
            "output_mask_name": "hd_redness_output.png"
        },
        "hd_oiliness": {
            "raw_score": 60.74365234375,
            "ui_score": 72,
            "output_mask_name": "hd_oiliness_output.png"
        },
        "hd_age_spot": {
            "raw_score": 83.23274230957031,
            "ui_score": 77,
            "output_mask_name": "hd_age_spot_output.png"
        },
        "hd_radiance": {
            "raw_score": 76.57244205474854,
            "ui_score": 79,
            "output_mask_name": "hd_radiance_output.png"
        },
        "hd_moisture": {
            "raw_score": 48.694559931755066,
            "ui_score": 70,
            "output_mask_name": "hd_moisture_output.png"
        },
        "hd_dark_circle": {
            "raw_score": 80.1993191242218,
            "ui_score": 76,
            "output_mask_name": "hd_dark_circle_output.png"
        },
        "hd_eye_bag": {
            "raw_score": 76.67280435562134,
            "ui_score": 79,
            "output_mask_name": "hd_eye_bag_output.png"
        },
        "hd_droopy_upper_eyelid": {
            "raw_score": 79.05348539352417,
            "ui_score": 80,
            "output_mask_name": "hd_droopy_upper_eyelid_output.png"
        },
        "hd_droopy_lower_eyelid": {
            "raw_score": 79.97175455093384,
            "ui_score": 81,
            "output_mask_name": "hd_droopy_lower_eyelid_output.png"
        },
        "hd_firmness": {
            "raw_score": 89.66898322105408,
            "ui_score": 85,
            "output_mask_name": "hd_firmness_output.png"
        },
        "hd_texture": {
            "whole": {
                "raw_score": 66.3921568627451,
                "ui_score": 75,
                "output_mask_name": "hd_texture_output.png"
            }
        },
        "hd_acne": {
            "whole": {
                "raw_score": 59.92677688598633,
                "ui_score": 76,
                "output_mask_name": "hd_acne_output.png"
            }
        },
        "hd_pore": {
            "forehead": {
                "raw_score": 79.59770965576172,
                "ui_score": 80,
                "output_mask_name": "hd_pore_output_forehead.png"
            },
            "nose": {
                "raw_score": 29.139814376831055,
                "ui_score": 58,
                "output_mask_name": "hd_pore_output_nose.png"
            },
            "cheek": {
                "raw_score": 44.11081314086914,
                "ui_score": 65,
                "output_mask_name": "hd_pore_output_cheek.png"
            },
            "whole": {
                "raw_score": 49.23978805541992,
                "ui_score": 67,
                "output_mask_name": "hd_pore_output_all.png"
            }
        },
        "hd_wrinkle": {
            "forehead": {
                "raw_score": 55.96956729888916,
                "ui_score": 67,
                "output_mask_name": "hd_wrinkle_output_forehead.png"
            },
            "glabellar": {
                "raw_score": 76.7251181602478,
                "ui_score": 75,
                "output_mask_name": "hd_wrinkle_output_glabellar.png"
            },
            "crowfeet": {
                "raw_score": 83.4361481666565,
                "ui_score": 78,
                "output_mask_name": "hd_wrinkle_output_crowfeet.png"
            },
            "periocular": {
                "raw_score": 67.88706302642822,
                "ui_score": 72,
                "output_mask_name": "hd_wrinkle_output_periocular.png"
            },
            "nasolabial": {
                "raw_score": 74.03312683105469,
                "ui_score": 74,
                "output_mask_name": "hd_wrinkle_output_nasolabial.png"
            },
            "marionette": {
                "raw_score": 71.94477319717407,
                "ui_score": 73,
                "output_mask_name": "hd_wrinkle_output_marionette.png"
            },
            "whole": {
                "raw_score": 49.64699745178223,
                "ui_score": 65,
                "output_mask_name": "hd_wrinkle_output_all.png"
            }
        },
        "all": {
            "score": 75.75757575757575
        },
        "skin_age": 37
    }

  • SD 護膚的 score_info.json 範例

    {
        "wrinkle": {
            "raw_score": 36.09360456466675,
            "ui_score": 60,
            "output_mask_name": "wrinkle_output.png"
        },
        "droopy_upper_eyelid": {
            "raw_score": 79.05348539352417,
            "ui_score": 80,
            "output_mask_name": "droopy_upper_eyelid_output.png"
        },
        "droopy_lower_eyelid": {
            "raw_score": 79.97175455093384,
            "ui_score": 81,
            "output_mask_name": "droopy_lower_eyelid_output.png"
        },
        "firmness": {
            "raw_score": 89.66898322105408,
            "ui_score": 85,
            "output_mask_name": "firmness_output.png"
        },
        "acne": {
            "raw_score": 92.29713000000001,
            "ui_score": 88,
            "output_mask_name": "acne_output.png"
        },
        "moisture": {
            "raw_score": 48.694559931755066,
            "ui_score": 70,
            "output_mask_name": "moisture_output.png"
        },
        "eye_bag": {
            "raw_score": 76.67280435562134,
            "ui_score": 79,
            "output_mask_name": "eye_bag_output.png"
        },
        "dark_circle_v2": {
            "raw_score": 80.1993191242218,
            "ui_score": 76,
            "output_mask_name": "dark_circle_v2_output.png"
        },
        "age_spot": {
            "raw_score": 83.23274230957031,
            "ui_score": 77,
            "output_mask_name": "age_spot_output.png"
        },
        "radiance": {
            "raw_score": 76.57244205474854,
            "ui_score": 79,
            "output_mask_name": "radiance_output.png"
        },
        "redness": {
            "raw_score": 72.011962890625,
            "ui_score": 77,
            "output_mask_name": "redness_output.png"
        },
        "oiliness": {
            "raw_score": 60.74365234375,
            "ui_score": 72,
            "output_mask_name": "oiliness_output.png"
        },
        "pore": {
            "raw_score": 88.38014125823975,
            "ui_score": 84,
            "output_mask_name": "pore_output.png"
        },
        "texture": {
            "raw_score": 80.09742498397827,
            "ui_score": 76,
            "output_mask_name": "texture_output.png"
        },
        "all": {
            "score": 75.75757575757575
        },
        "skin_age": 37
    }

檔案規格與錯誤

• 支援的格式與尺寸

警告： 雖然 API 會自動將圖片調整至最大 2560 像素，您仍需確保所有臉部清晰對焦、影像品質高、光線均勻，且臉部足夠大並正對鏡頭。在執行 AI 肌膚檢測前拍攝 HD 或 SD 護膚影像時，必須避免動態模糊與遮擋。為達到最佳結果，強烈建議使用直式長寬比，而非橫式。

• 拍攝建議：

• 準備開始肌膚檢測的說明

• 摘下眼鏡，並確保瀏海未遮蓋額頭

• 確保您處於光線充足的環境

• 卸妝以獲得更準確的結果

• 直視鏡頭，並將臉部保持在中央

• 照片需求 我們會檢查影像品質，確保適合 AI 肌膚檢測。請確保臉部佔圖片寬度約 60–80%，無任何疊加或遮擋。光線應明亮且均勻分布，避免過度曝光或高光溢出。姿勢應正面、中性且放鬆，嘴巴閉合、雙眼睜開。

您應完全露出額頭，並將瀏海往後梳或綁起頭髮，以確保最佳品質。建議您摘下眼鏡以達到最佳的 AI 肌膚檢測效能，但這並非強制要求。

警告： 臉部寬度需大於圖片寬度的 60%。

• 錯誤代碼

• 環境與相依性

點數消耗

• AI 肌膚檢測 V2.1

JS Camera Kit

Mobile Camera Kit

使用案例

Base URL： https://yce-api-01.makeupar.com 分析端點： POST /s2s/v2.1/task/skin-analysis 認證： Authorization: Bearer YOUR_API_KEY — 請注意 Bearer 與 API key 之間有一個空格。

每個使用案例各有自己的端點，請依您需要的加值功能選擇：

說明： 有加值功能的模式，會在基礎點數之外產生額外的點數消耗。詳情請見點數消耗。