AI 肤质分析 V2.1

接入指南

• AI 肤质分析怎么拍照

• 正脸自拍一张

  • 拍一张清楚的照片即可，正对镜头。头发散下放下来、垂到胸前，视线直视前方，做出正对镜头的角度。
  • 也可以用 JS Camera Kit 拍照。同样把头发散下放下来、垂到胸前，不要扎起来。

• 接口流程 测肤接口使用指引 本指引说明如何用 File 接口与 AI 任务接口上传图片并创建 AI 肤质分析。

  • 第 1 步：调整源图尺寸
    把图片缩放到支持的尺寸范围——SD 为长边不超过 2560 像素、短边至少 480 像素；HD 为长边不超过 2560 像素、短边至少 1080 像素。详见 文件规格与错误码

  • 第 2 步：通过 File 接口上传文件元数据

• 图片要求
  • 详见 文件规格与错误码

发送 POST 请求初始化文件上传：

• 重要：只调用 File 接口并不等于上传了文件。您必须另外把文件上传到 File 接口响应中给出的那个 URL。那个 URL 就是您的上传目标，务必确认文件已成功传过去，再继续往下做。

  警告： 请注意，若未把文件上传到 File 接口响应中给出的 URL，调用 AI 接口时会得到 500 Server Error / unknown_internal_error 或 404 Not Found 错误。

• 第 3 步：取得上传 URL 与文件 ID

响应中包含：

• requests.url – 用于上传图片的预签名 URL。
• file_id – 创建 AI 任务用的标识。

响应示例：

• 第 4 步：把图片上传到预签名 URL

使用提供的 requests.url 与请求头：

• 第 5 步：创建 AI 任务

用第 2 步取得的 file_id 创建 AI 肤质分析：

上传完成后，就可以用文件 ID 或图片文件 URL 选择要分析的皮肤问题，详见 输入与输出。
随后用文件 ID 或图片文件 URL 调用 POST 'task/skin-analysis' 执行任务， 并取得 task_id。 请注意，SD 与 HD 的皮肤问题参数不可同时混用。

• 使用已有的公开图片 URL 不必上传，发起 AI 任务时直接提供一个可公开访问的图片 URL 也可以。

响应示例：

• 第 6 步：轮询任务状态

用 task_id 取回任务结果：

用这个 task_id 轮询 GET 'task/skin-analysis' 监控任务状态，取得引擎当前的处理进度。引擎完成任务之前，状态会一直是 'running'，这一阶段不消耗点数。

处理完成的结果保留 30 天。

• 不必用很短的间隔轮询。

• 在保留期限内，轮询间隔可以自由安排。

  重要： 由于执行时长没有保证，仍然需要轮询来查看任务状态。

引擎成功处理您的输入文件、生成出图后，任务状态会变为 'success'。您会得到处理后图片的 URL 以及一个 dst_id，可直接串联下一个 AI 任务，不必把结果图重新上传。

只有这种情况才会消耗点数。若引擎处理失败，任务状态会变为 'error'，不消耗点数。 扣除点数时，系统优先扣除临近到期的点数；到期日相同时，优先扣除最早取得的点数。

• 第 7 步：解读结果

响应中包含：

• ui_score – 面向用户的分数。
• raw_score – 原始分析分数。
• mask_urls – 检测蒙版的 URL。

响应示例：

• 排障指引

警告： 请注意，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 值与原图混合，就能在原图上直接看到检测结果。

• AI 肤质分析 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]，评估肤质：Normal、Oily、Dry、Combination、Redness、Dry & Redness、Oily & Redness、Combination & Redness。

    • 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]，评估肤质：Normal、Oily、Dry、Combination、Redness、Dry & Redness、Oily & Redness、Combination & Redness。

  • 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
    }

文件规格与错误码

• 支持的格式与尺寸

警告： 接口会自动把图片缩放到最大 2560 像素，但请自行确保所有人脸清楚合焦、画质够高、光线均匀、人脸足够大且正对相机。拍摄 HD 或 SD 护肤图片、准备跑 AI 肤质分析之前，务必避开运动模糊与遮挡。为获得最佳效果，强烈建议采用竖幅（肖像）比例，不要横幅。

• 拍摄建议：

• 开始测肤前的准备说明

• 摘下眼镜，确认刘海没有遮住额头

• 确保您处在光线充足的环境中

• 卸妆后再测，结果更准

• 直视镜头，把脸保持在画面中央

• 照片要求 我们会检查图片质量，确认它适合跑 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 与密钥之间只有一个空格。

每种使用场景各自对应一个接口，按您需要哪些加购能力来选择：

说明： 带加购能力的模式会在基础点数之外产生额外的点数消耗。详情请见 点数消耗。