从接口设计来看，AI Skin Analysis 并不是一个“上传图片，然后返回一个肤质分数”的简单服务。
一次完整的肌肤分析通常包含几个步骤：准备输入图片、上传文件、创建分析任务、指定需要检测的肌肤问题、查询任务状态，最后读取分数和对应的图像结果。
玩美移动的 AI Skin Analysis API 采用异步任务机制。图片上传完成后，客户端创建 skin-analysis 任务，服务端返回 task_id。应用再通过这个 ID 查询任务状态，直到任务完成。
这种设计很常见于图像 AI 服务，因为推理时间不适合直接绑定在一次同步 HTTP 请求中。
输入图片有明确的尺寸要求
AI 测肤对输入图片的要求比普通人脸检测更高。
原因很直接：毛孔、细纹、纹理等特征本身就属于细节信息。如果输入图像分辨率不足，后续分析的有效信息也会减少。
根据 AI Skin Analysis 文档：
- SD Skin Analysis 的图片短边至少为 480 px
- HD Skin Analysis 的图片短边至少为 1080 px
- 图片最长边不超过 4096 px
因此，在真正调用分析接口之前，应用通常需要先完成图片尺寸检查和预处理。
图片可以先通过 File API 上传，再使用返回的 file_id 创建分析任务。
dst_actions 决定这次任务分析什么
创建 Skin Analysis Task 时，一个比较关键的字段是 dst_actions。
它不是一个展示参数，而是直接决定这次 AI 任务需要运行哪些肌肤分析项目。
文档示例中使用的是：
"dst_actions": ["wrinkle", "pore", "texture", "acne"]
这表示本次任务会分析皱纹、毛孔、纹理和痘痘。
完整的任务请求示例中，可以看到这些参数是如何组合在一起的：
curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "src_file_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud", "dst_actions": ["hd_wrinklewrinkle", "hd_porepore", "hd_texturetexture", "hd_acneacne"], "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 // Additional parameters omitted for brevity }, "format": "json" }'
这里真正需要关注的字段不多。
src_file_id 指向已经上传的源图片。
dst_actions 指定检测项目。
miniserver_args 用于控制部分输出行为，例如是否生成 Mask Overlay。
format 用于指定返回结果格式。
从接口设计上看，Skin Analysis 并不是一个固定的“全量检测”。开发者可以根据业务需要选择具体的 Skin Concern。
返回结果里为什么有两个 Score
AI Skin Analysis 的返回结果中会同时出现 ui_score 和 raw_score。
{ "type": "texture", "ui_score": 68, "raw_score": 57.33, "mask_urls": [ "https://yce-us.s3-accelerate.amazonaws.com/...texture_output.jpg" ]}
例如：
这里有几个字段值得区分。
type 表示当前结果对应的分析项目，例如 texture。
raw_score 是分析产生的原始数值。
ui_score 是用于用户界面展示的分数。
mask_urls 则指向对应的检测结果图像。
在实际开发中，不建议把 raw_score 和 ui_score 当成同一个概念使用。
如果只是做前端测肤报告，通常会更关注 ui_score。如果需要保存更接近原始分析结果的数据，则可以单独处理 raw_score。
Detection Mask 解决的是“检测区域在哪里”
AI 测肤如果只返回一个数字，其实很难说明模型到底分析了图像中的哪个位置。
这也是 Detection Mask 存在的原因。
对于纹理、毛孔、痘痘等分析项目，API 可以返回对应的 Mask 图像。前端可以把 Mask 和原始图片叠加，用来显示检测区域。
在任务参数中可以看到：
"enable_mask_overlay": true
这个参数与 Mask Overlay 的生成有关。
因此，一项 Skin Concern 的结果通常可以包含两类信息：
数值结果，用来描述分析程度；
Mask 结果，用来描述对应区域。
这两部分结合起来，才比较接近一个完整的 AI 肌肤分析结果。
SD 和 HD 不能混用
AI Skin Analysis 文档对 SD 和 HD Skin Concern 做了明确区分。
如果一个请求同时包含 SD 和 HD 的 dst_actions，接口会直接返回参数错误：
{ "status": 400, "error": "cannot mix HD and SD dst_actions", "error_code": "InvalidParameters"}
因此，在应用侧生成请求参数时，需要提前确定本次任务属于 SD 还是 HD，而不是在一个任务中把两套分析项目混在一起。
这类校验最好放在服务端完成。
如果直接允许前端拼接 dst_actions，很容易产生无效组合。更稳妥的方式是由后端维护可用的分析项目列表，再根据业务场景生成请求。
HD 分析不仅仅是分辨率更高
HD Skin Analysis 和普通 SD 分析的区别，并不只是输入图片尺寸更大。
部分 HD Skin Concern 还包含更细的区域结果。
例如 HD 毛孔分析可以进一步区分：
- forehead
- nose
- cheek
- whole
HD wrinkle 也可以按不同面部位置返回分析结果，例如 forehead、glabellar、crowfeet、periocular、nasolabial 等区域。
对于前端来说，这意味着结果展示不一定只能是“全脸毛孔 82 分”这种单值结构。
如果接口返回了区域级结果，就可以进一步做局部展示，例如分别显示鼻部和脸颊的毛孔情况。
文件上传是一个容易被忽略的环节
从实际接入来看，File API 是比较容易出问题的一步。
调用 File API 获取上传 URL，并不代表图片已经上传成功。
应用还需要真正把文件 PUT 到返回的 URL，然后再使用对应的 file_id 创建 Skin Analysis Task。
如果文件没有上传完成就开始创建 AI 任务，后续请求可能失败。
因此，一个相对可靠的服务端流程通常是：
- 初始化文件上传
- 获取上传 URL 和 file_id
- 完成实际文件上传
- 确认上传成功
- 创建 Skin Analysis Task
- 保存 task_id
- 查询任务状态
- 解析分析结果
这部分虽然和 AI 模型本身无关，但在生产环境里往往比模型调用更容易产生集成问题。
从接口角度理解 AI 测肤
如果只看 API，AI Skin Analysis 最终做的事情其实很明确。
输入是一张符合要求的人脸图片。
请求参数决定需要分析哪些 Skin Concern。
AI Task 完成之后，返回每个分析项目对应的结构化结果，例如：
type ui_score raw_score mask_urls HD 模式下，部分结果还可以进一步拆分到具体面部区域。
所以从工程角度看，AI 测肤更接近一个“面部图像分析服务”，而不是一个固定格式的测肤报告生成器。
报告长什么样、显示哪些分数、是否展示 Mask、如何组织 HD 区域结果，这些都属于应用层的实现。API 本身提供的是底层分析结果和对应的数据结构。
