AI 肌肤分析（AI Skin Analysis）是一种基于计算机视觉的图像分析技术，能够从面部照片中提取毛孔、皱纹、纹理、痘痘、泛红等肌肤特征，并将检测结果转换为结构化数据。
在实际开发中，AI 测肤不只是调用一次图像识别接口。应用还需要处理图片质量、检测项目配置、异步任务状态以及分析结果的解析和展示。
玩美移动（Perfect Corp.）提供的 AI Skin Analysis API 将上述流程封装为标准 HTTP 接口，并支持 SD、HD 两类分析项目。开发者可以根据需要选择检测维度，获取对应的评分数据及检测区域图像。
1. AI 肌肤分析如何配置 HD 检测项目？
在 AI Skin Analysis API 中，dst_actions 是决定检测内容的关键参数。
API 将 Skin Concern 分为 SD 和 HD 两类。例如，普通分析可以使用 wrinkle、pore、texture、acne，HD 分析则使用 hd_wrinkle、hd_pore、hd_texture、hd_acne 等参数。
这两组参数不能在同一次请求中混用。
HD 模式不仅涉及更高的输入图像分辨率，还支持部分肌肤项目的区域级分析。例如，hd_pore 可以分别分析额头、鼻部、脸颊及全脸，hd_wrinkle 则提供额头、眉间、眼周、法令纹等区域的结果。
curl -i -X POST \ https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Content-Type: application/json' \ -d '{ "src_file_url": "https://example.com/selfie.jpg", "dst_actions": [ "hd_wrinkle", "hd_pore", "hd_texture", "hd_acne" ], "miniserver_args": { "enable_mask_overlay": true, "enable_dark_background_hd_pore": true, "color_dark_background_hd_pore": "3D3D3D", "opacity_dark_background_hd_pore": 0.4, "enable_dark_background_hd_wrinkle": true, "color_dark_background_hd_wrinkle": "3D3D3D", "opacity_dark_background_hd_wrinkle": 0.4 }, "format": "zip" }'
下面是玩美移动 AI Skin Analysis V2.0 官方文档中的请求示例，代码保持原样：
这段请求包含三个值得关注的部分。
src_file_url 指定待分析的图像，要求 URL 可公开访问。接口也支持使用已上传文件的 src_file_id，但对应的请求结构需要按 File ID 模式配置。
dst_actions 指定分析任务需要处理的肌肤项目。
miniserver_args 控制部分检测结果的视觉呈现，例如 Mask Overlay 和毛孔、皱纹相关的背景配置。
示例中的 Token 和图片地址都是占位内容，实际调用时需要替换为有效凭证和真实图像 URL。
2. 异步任务如何管理分析状态？
AI Skin Analysis 采用异步任务机制。
发送 POST 请求后，接口首先返回 task_id，而不是立即返回全部肌肤检测结果。
客户端需要通过对应版本的任务查询接口获取状态：
GET /s2s/v2.0/task/skin-analysis/{task_id}
任务执行期间，task_status 可以处于 running 状态。处理成功后变为 success，失败则返回 error。
因此，业务系统需要区分任务创建成功与图像分析成功，不能仅凭 POST 请求返回 HTTP 200 就直接展示检测报告。
在实际部署中，可以由服务端统一保存 task_id、执行轮询并处理超时或异常。官方文档说明，处理后的结果保留 24 小时，应用需要在有效期内获取所需数据。
3. format=zip 与 format=json 有什么区别？
AI Skin Analysis 支持 zip 和 json 两种结果格式，默认使用 zip。
当选择 format=zip 时，分析结果会打包为 ZIP 文件，其中包含 skinanalysisResult 目录。
该目录中的 score_info.json 保存检测项目的数值结果，以及与检测图像对应的文件名称。其余 PNG 文件则用于保存各项 Skin Concern 的检测 Mask。
如果使用 format=json，则可以通过 JSON 形式读取结构化分析结果。需要注意，两种格式的返回数据结构并不相同，客户端不能直接使用完全一致的解析逻辑。
对于需要保存独立检测图像、进行局部区域展示的系统，ZIP 格式便于同时处理数值与图片资源。对于以结构化结果处理为主的应用，可以根据实际响应结构选择 JSON 格式。
4. raw_score、ui_score 与区域级数据
在官方 score_info.json 示例中，每项肌肤分析结果可以包含以下字段：
raw_score：原始分析分数。
ui_score：经过调整、用于界面展示的整数分数。
output_mask_name：对应检测 Mask 的文件名称。
这两个评分字段不能直接等同。
根据官方说明，raw_score 是原始评分，而 ui_score 会经过面向消费者展示的校准。因此，开发者不应将 ui_score 简单理解为 raw_score 的四舍五入结果。
HD 模式下，还需要处理不同检测项目的数据嵌套结构。
例如，hd_pore 的结果可以包含 forehead、nose、cheek 和 whole；这些子区域分别具有自己的分数及 Mask 文件名。
开发者解析 score_info.json 时，应根据 Skin Concern 判断是否存在区域子级，而不是假设所有项目都直接包含相同的评分字段。
如果应用计划对多次检测结果进行比较，也应记录 API 版本、SD/HD 模式和拍摄条件，避免将不同分析环境产生的数据直接视为可比结果。
5. Detection Mask 如何用于结果可视化？
AI 肌肤分析返回的数值可以表示某项肌肤状况的评分，但无法单独说明对应的检测位置。
Detection Mask 用于补充区域信息。
在 ZIP 输出中，Mask 以 PNG 文件形式保存。官方文档说明，可以利用 PNG 的 Alpha 通道，将检测结果叠加到原始图片上。
例如，前端可以根据 hd_pore 的不同子区域展示对应的毛孔检测 Mask，也可以选择特定皱纹区域进行局部呈现。
API 还提供 enable_mask_overlay 参数。默认情况下，系统可以输出独立的检测 Mask；启用该参数后，可生成叠加后的视觉结果。
对于技术团队来说，这意味着数值解析与检测区域展示可以作为两个独立环节实现，而不必将 API 输出固定成单一的测肤报告界面。
6. 图像输入与参数校验需要注意什么？
在真正执行 Skin Analysis Task 前，输入图像需要满足相应规格。
根据当前官方 File Specs，支持 JPG、JPEG 和 PNG，文件大小需小于 10 MB。SD 分析要求图片短边至少为 480 像素，HD 分析要求短边至少为 1080 像素。对于长边超过 2560 像素的图片，系统会自动调整尺寸。
除了文件格式和尺寸，还应检查面部朝向、清晰度、光照及遮挡情况。毛孔、细纹等细节分析对图像质量尤其敏感。
如果使用 File API 上传图片，还需要特别注意：取得预签名上传 URL 并不代表文件上传完成。
只有将图片真正上传至返回的地址后，才能使用对应的 file_id 创建分析任务。
另外，SD 与 HD 的 dst_actions 不能混合使用。传入无效 Skin Concern 或混用两类参数时，接口会返回 InvalidParameters 错误。因此，建议在服务端建立合法分析项目的参数校验，避免将无效任务直接提交给 AI 服务。
从数据处理角度看，AI Skin Analysis API 的主要工作集中在输入质量控制、检测项目选择、异步任务管理和结果解析。对于希望实现局部肌肤检测、独立 Mask 展示或自定义评分界面的应用，尤其需要理解 HD 数据的嵌套结构，以及 ZIP 和 JSON 两种输出格式的差异。
这些分析结果可以作为护肤咨询或软件应用中的视觉参考，但不应直接等同于临床皮肤诊断结论。
