# AI 肤质分析 V2.1 # 概览 ![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_demostore_skincarelive_topbanner.0cffe3a7.jpg) **AI 肤质分析 V2.1** 只凭一张正脸自拍，就能给出细致的皮肤洞察。它检测 16 项皮肤指标，包括皱纹、毛孔、色斑、泛红与肤质，并标出每一项皮肤问题出现在脸上的哪个位置；同时估算肌肤年龄，并算出一个整体肌肤状况评分。 在 V2.1 中，您可以按需加上两个加购能力，让接入更完整： - **高级测肤报告** ：基于每位用户的检测结果，生成个性化、读起来轻松好懂的皮肤洞察。 - **商品推荐** ：把您商品目录里的商品对应用户的皮肤问题，做出有针对性的购物体验。 可以只用肤质分析，也可以搭配加购能力一起用。想对比这几种用法，请见 [使用场景](#section/overview/use-cases)。 ## 接入指南 * AI 肤质分析怎么拍照 * 正脸自拍一张 - 拍一张清楚的照片即可，正对镜头。头发散下放下来、垂到胸前，视线直视前方，做出正对镜头的角度。 - 也可以用 JS Camera Kit 拍照。同样把头发散下放下来、垂到胸前，不要扎起来。 * 接口流程 **测肤接口使用指引** 本指引说明如何用 File 接口与 AI 任务接口上传图片并创建 AI 肤质分析。 * **第 1 步：调整源图尺寸** 把图片缩放到支持的尺寸范围——SD 为长边不超过 2560 像素、短边至少 480 像素；HD 为长边不超过 2560 像素、短边至少 1080 像素。详见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)** * **第 2 步：通过 File 接口上传文件元数据** - 图片要求 - 详见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)** 发送 POST 请求初始化文件上传： ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/file \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "files": [ { "content_type": "image/png", "file_name": "skin_analysis_01_3dbd1b6683.png", "file_size": 547541 } ] }' ``` - ***重要***：只调用 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 任务用的标识。 **响应示例：** ```json { "status": 200, "data": { "files": [ { "content_type": "image/png", "file_name": "skin_analysis_01_3dbd1b6683.png", "file_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud", "requests": [ { "method": "PUT", "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...", "headers": { "Content-Length": "547541", "Content-Type": "image/png" } } ] } ] } } ``` --- * **第 4 步：把图片上传到预签名 URL** 使用提供的 `requests.url` 与请求头： ```bash curl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \ --header 'Content-Type: image/png' \ --header 'Content-Length: 547541' \ --data-binary @'./skin_analysis_01_3dbd1b6683.png' ``` --- * **第 5 步：创建 AI 任务** 用第 2 步取得的 `file_id` 创建 AI 肤质分析： ```bash 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": ["wrinkle", "pore", "texture", "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 // Additional parameters omitted for brevity }, "format": "json" }' ``` 上传完成后，就可以用文件 ID 或图片文件 URL 选择要分析的皮肤问题，详见 **[输入与输出](#section/overview/Inputs-and-Outputs)**。 随后用文件 ID 或图片文件 URL 调用 POST 'task/skin-analysis' 执行任务， 并取得 ***task_id***。 请注意，SD 与 HD 的皮肤问题参数**不可**同时混用。 - **使用已有的公开图片 URL** 不必上传，发起 AI 任务时直接提供一个可公开访问的图片 URL 也可以。 **响应示例：** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` --- * **第 6 步：轮询任务状态** 用 `task_id` 取回任务结果： ```bash curl --request GET \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis/ \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' ``` 用这个 ***task_id*** 轮询 GET 'task/skin-analysis' 监控任务状态，取得引擎当前的处理进度。引擎完成任务之前，状态会一直是 'running'，这一阶段不消耗点数。 处理完成的结果保留 30 天。 - 不必用很短的间隔轮询。 - 在保留期限内，轮询间隔可以自由安排。 > **重要：** 由于执行时长没有保证，仍然需要轮询来查看任务状态。 引擎成功处理您的输入文件、生成出图后，任务状态会变为 'success'。您会得到处理后图片的 URL 以及一个 dst_id，可直接串联下一个 AI 任务，不必把结果图重新上传。 只有这种情况才会消耗点数。若引擎处理失败，任务状态会变为 'error'，不消耗点数。 扣除点数时，系统优先扣除临近到期的点数；到期日相同时，优先扣除最早取得的点数。 --- * **第 7 步：解读结果** 响应中包含： * `ui_score` – 面向用户的分数。 * `raw_score` – 原始分析分数。 * `mask_urls` – 检测蒙版的 URL。 **响应示例：** ```json { "status": 200, "data": { "results": { "output": [ { "type": "texture", "ui_score": 68, "raw_score": 57.33, "mask_urls": ["https://yce-us.s3-accelerate.amazonaws.com/...texture_output.jpg"] }, { "type": "pore", "ui_score": 92, "raw_score": 95.34, "mask_urls": ["https://yce-us.s3-accelerate.amazonaws.com/...pore_output.jpg"] } // Additional results omitted for brevity ] }, "task_status": "success" } } ``` * 排障指引 > **警告：** 请注意，SD 与 HD 的皮肤问题参数**不可**同时混用。偏离这些规范会得到 ***InvalidParameters*** 错误。 * 若您混用 HD 与 SD 的皮肤问题参数，会得到如下错误： ```json { "status": 400, "error": "cannot mix HD and SD dst_actions", "error_code": "InvalidParameters" } ``` * 若您拼错皮肤问题名称，或传入未知的皮肤问题，会得到如下错误： ```json { "status": 400, "error": "Not available dst_action abc123", "error_code": "InvalidParameters" } ``` --- * 实际案例： ![](https://plugins-media.makeupar.com/webconsultation/images/skincare-widget/img_webcm_skincare_service_survey_demo.jpg) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/skin_analysis_s5_poster_3_dt_85efe14952.png) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Skincare_Pro_Medspa_Situation_Image_6aea6046f9.jpg) ## 输入与输出 * 输入参数说明 控制 AI 肤质分析结果视觉呈现的方式有两种：要么生成多张图片，每项皮肤问题各出一张独立蒙版；要么用 `enable_mask_overlay` 参数合成一张叠加图。系统默认输出多张蒙版，如何把每项皮肤问题的蒙版与图片混合，完全由您掌握。 * 默认：enable_mask_overlay false ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/mask_overlay_false_1920_ea1cde0ead.png) * 把 enable_mask_overlay 设为 true ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/mask_overlay_1920_0fbb4786cc.png) --- * 输出 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 示例 ```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 示例 ```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 } ``` ## 文件规格与错误码 * 支持的格式与尺寸 | AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 | | --- | --- | --- | --- | | SD 护肤 | 短边长度至少 480 像素。 长边不限制；但超过 2560 像素时，系统会自动缩放到 2560 像素。 | < 10MB | jpg/jpeg/png | | HD 护肤 | 短边长度至少 1080 像素。 长边不限制；但超过 2560 像素时，会自动缩放到 2560 像素。 | < 10MB | jpg/jpeg/png | > **警告：** 接口会自动把图片缩放到最大 2560 像素，但请自行确保所有人脸清楚合焦、画质够高、光线均匀、人脸足够大且正对相机。拍摄 HD 或 SD 护肤图片、准备跑 AI 肤质分析之前，务必避开运动模糊与遮挡。为获得最佳效果，强烈建议采用竖幅（肖像）比例，不要横幅。 * 拍摄建议： ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png) * 开始测肤前的准备说明 * 摘下眼镜，确认刘海没有遮住额头 * 确保您处在光线充足的环境中 * 卸妆后再测，结果更准 * 直视镜头，把脸保持在画面中央 * 照片要求 我们会检查图片质量，确认它适合跑 AI 肤质分析。请确保脸部约占图片宽度的 60–80%，没有任何叠加物或遮挡。光线要明亮且分布均匀，避免过曝与高光溢出。姿态须正对镜头、自然放松，嘴巴闭合、眼睛睁开。 请完整露出额头，把刘海往后梳或把头发扎起来，保证质量最佳。建议摘下眼镜，AI 肤质分析表现更好，这一项不是强制要求。 > **警告：** 脸部宽度需大于图片宽度的 60%。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_error_src_face_too_small_cr_725792a7fb.png) * 错误码 | 错误码 | 说明 | | --- | --- | | error_below_min_image_size | 输入图片分辨率过小 | | error_exceed_max_image_size | 输入图片分辨率过大 | | error_src_face_too_small | 上传图片中的脸部区域太小。脸部宽度需大于图片宽度的 60%。 | | error_src_face_out_of_bound | 上传图片中的脸部区域超出画面边界 | | error_lighting_dark | 上传图片的光线太暗 | * 运行环境与依赖 | 示例代码语言 / 工具 | 建议运行时版本 | | --- | --- | | cURL | - bash >= 3.2 - curl >= 7.58 (modern TLS/HTTP support) - jq >= 1.6 (robust JSON parsing) | | Node.js (JavaScript) | Node >= 18 (for global fetch) | | JavaScript | - Chrome / Edge >= 80 - Firefox >= 74 - Safari >= 13.1 | | PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) or allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (for f-strings), requests >= 2.20.0 | | Java | Java 11+ (for HttpClient), Jackson Databind >= 2.12.0 | --- ## 点数消耗 * AI 肤质分析 V2.1 | AI 功能 | SD | HD | 加购高级测肤报告 | 加购商品推荐 | | --- | --- | --- | --- | --- | | 分析 1~4 项皮肤问题 | 9 | 12 | +15 点 | +10 点 | | 分析 5~8 项皮肤问题 | 12 | 16 | +25 点 | +15 点 | | 分析 9~12 项皮肤问题 | 14 | 20 | +35 点 | +20 点 | | 分析 13~16 项皮肤问题 | 16 | 22 | +40 点 | +25 点 | --- ## 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` 与密钥之间只有一个空格。 ```bash export API_KEY="your-api-key" export BASE_URL="https://yce-api-01.makeupar.com" ``` 每种使用场景各自对应一个接口，按您需要哪些加购能力来选择： | 模式 | `advanced_report` | `product_recommendation` | `llm_results.json` 里能拿到什么 | | --- | --- | --- | --- | | **[AI 肤质分析（标准）](/reference/ai_skin_analysis/standard-analysis/endpoint-overview)** | 不传 | 不传 | 各检测维度的皮肤问题评分 | | **[AI 肤质分析 + 高级测肤报告](/reference/ai_skin_analysis/analysis-+-advanced-report/endpoint-overview)** | 传入 | 不传 | 评分，外加一份讲成因与护理建议的个性化报告 | | **[AI 肤质分析 + 商品推荐](/reference/ai_skin_analysis/analysis-+-product-recommendation/endpoint-overview)** | 不传 | 传入 | 评分，外加从您的商品目录里匹配出的商品 | | **[AI 肤质分析 + 高级测肤报告 + 商品推荐](/reference/ai_skin_analysis/analysis-+-report-+-recommendation/endpoint-overview)** | 传入 | 传入 | 一次调用同时拿到评分、报告与商品匹配结果 | > **说明：** 带加购能力的模式会在基础点数之外产生额外的点数消耗。详情请见 [点数消耗](/reference/ai_skin_analysis/section/overview/unit-consumption)。 --- License: Privacy policy ## Servers ``` https://yce-api-01.makeupar.com ``` ## Security ### BearerAuthenticationV2 使用标准的 Bearer 鉴权。把您的 API 密钥放进请求头： `Authorization:Bearer YOUR_API_KEY`。请注意 'Bearer' 与 'YOUR_API_KEY' 之间有一个空格。 Type: http Scheme: bearer ## Download OpenAPI description - [AI 肤质分析 V2.1](https://docs.perfectcorp.com/_bundle/@l10n/zh-CN/reference/ai_skin_analysis.yaml) ## Standard Analysis - [接口总览](https://docs.perfectcorp.com/zh-cn/reference/ai_skin_analysis/standard-analysis/%E6%8E%A5%E5%8F%A3%E6%80%BB%E8%A7%88.md): ## 接口总览 **这是什么。** 标准 AI 肤质分析针对您选定的皮肤问题给出客观、量化的评分，并附上精准的检测蒙版与热力图。 依托先进的 AI 深度学习与面部区域分割技术，Perfect Corp AI 肤质分析无需物理接触，即可从数字图片中评估可见的皮肤状况。方案会输出量化评分、检测蒙版、热力图与 AR 叠加效果，用个性化的护肤洞察帮助用户更了解自己的皮肤，并据此定制属于每个人的护肤流程。 - [POST /s2s/v2.1/task/skin-analysis](https://docs.perfectcorp.com/zh-cn/reference/ai_skin_analysis/standard-analysis/paths/~1s2s~1v2.1~1task~1skin-analysis/post.md): AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 `success` 或 `error` 通知后，用收到的 `task_id` 查询任务结果。配置与校验的细节请见 [Webhook 接入指南](/develop/webhook)。 若功能不支持 Webhook，或您的接入方式用不了 We - [GET /s2s/v2.1/task/skin-analysis/{task_id}](https://docs.perfectcorp.com/zh-cn/reference/ai_skin_analysis/standard-analysis/paths/~1s2s~1v2.1~1task~1skin-analysis~1%7Btask_id%7D/get.md) ## Analysis + Advanced Report - [接口总览](https://docs.perfectcorp.com/zh-cn/reference/ai_skin_analysis/analysis-+-advanced-report/%E6%8E%A5%E5%8F%A3%E6%80%BB%E8%A7%88.md): ## 接口总览 **这是什么。** 一份覆盖全维度的皮肤报告，用自然语言写成，由大语言模型生成——喂给模型的是您的**精准 AI 肤质分析结果**，再加上一座**专业护肤参考数据库**。模型不会凭空猜测您的皮肤：它解读的是实测出来的、量化的皮肤指标与真实的检测蒙版，把它们同专业护肤数据逐一对照，最后在 `llm_results.json` 里返回一份完整的报告。 **报告的各个维度分别由哪些 `d - [POST /s2s/v2.1/task/skin-analysis-report](https://docs.perfectcorp.com/zh-cn/reference/ai_skin_analysis/analysis-+-advanced-report/paths/~1s2s~1v2.1~1task~1skin-analysis-report/post.md): AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 `success` 或 `error` 通知后，用收到的 `task_id` 查询任务结果。配置与校验的细节请见 [Webhook 接入指南](/develop/webhook)。 若功能不支持 Webhook，或您的接入方式用不了 We - [GET /s2s/v2.1/task/skin-analysis-report/{task_id}](https://docs.perfectcorp.com/zh-cn/reference/ai_skin_analysis/analysis-+-advanced-report/paths/~1s2s~1v2.1~1task~1skin-analysis-report~1%7Btask_id%7D/get.md) ## Analysis + Product Recommendation - [接口总览](https://docs.perfectcorp.com/zh-cn/reference/ai_skin_analysis/analysis-+-product-recommendation/%E6%8E%A5%E5%8F%A3%E6%80%BB%E8%A7%88.md): ## 接口总览 **这是什么。** 把您的商品目录交给一次精准的肤质分析来做匹配。上传您在售的护肤商品及其描述，调用时传入目录 id，接口就会在 `llm_results.json` 里为每一项检测出的皮肤问题返回匹配度最高的商品。 它与通用大模型推荐的区别在于输入。通用大模型靠概率和先验来推荐；Perfect AI 肤质分析先产出**科学、量化的皮肤指标与真实的检测蒙版**，模型再把商品同实测出 - [POST /s2s/v2.1/task/skin-analysis-recommendation](https://docs.perfectcorp.com/zh-cn/reference/ai_skin_analysis/analysis-+-product-recommendation/paths/~1s2s~1v2.1~1task~1skin-analysis-recommendation/post.md): AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 `success` 或 `error` 通知后，用收到的 `task_id` 查询任务结果。配置与校验的细节请见 [Webhook 接入指南](/develop/webhook)。 若功能不支持 Webhook，或您的接入方式用不了 We - [GET /s2s/v2.1/task/skin-analysis-recommendation/{task_id}](https://docs.perfectcorp.com/zh-cn/reference/ai_skin_analysis/analysis-+-product-recommendation/paths/~1s2s~1v2.1~1task~1skin-analysis-recommendation~1%7Btask_id%7D/get.md) ## Analysis + Report + Recommendation - [接口总览](https://docs.perfectcorp.com/zh-cn/reference/ai_skin_analysis/analysis-+-report-+-recommendation/%E6%8E%A5%E5%8F%A3%E6%80%BB%E8%A7%88.md): ## 接口总览 **这是什么。** 一次调用同时拿到「AI 肤质分析 + 高级测肤报告 + 商品推荐」。您会得到那份精准报告——它建立在实测皮肤指标与专业护肤参考数据库之上——**再加上**完全从您自家商品里给出的推荐，只需一个请求、一次轮询流程。 一个接口调用就把整个闭环走完：既有科学、高度可靠、精准的肤质分析报告，又有完全基于您的商品目录的商品推荐。商品曝光与用户黏性一次兼顾，用户体验从头到尾 - [POST /s2s/v2.1/task/skin-analysis-report-recommendation](https://docs.perfectcorp.com/zh-cn/reference/ai_skin_analysis/analysis-+-report-+-recommendation/paths/~1s2s~1v2.1~1task~1skin-analysis-report-recommendation/post.md): AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 `success` 或 `error` 通知后，用收到的 `task_id` 查询任务结果。配置与校验的细节请见 [Webhook 接入指南](/develop/webhook)。 若功能不支持 Webhook，或您的接入方式用不了 We - [GET /s2s/v2.1/task/skin-analysis-report-recommendation/{task_id}](https://docs.perfectcorp.com/zh-cn/reference/ai_skin_analysis/analysis-+-report-+-recommendation/paths/~1s2s~1v2.1~1task~1skin-analysis-report-recommendation~1%7Btask_id%7D/get.md) ## Product Catalogs - [接口总览](https://docs.perfectcorp.com/zh-cn/reference/ai_skin_analysis/product-catalogs/%E6%8E%A5%E5%8F%A3%E6%80%BB%E8%A7%88.md): ## 接口总览 商品目录就是 AI 肤质分析在做商品推荐时使用的那份商品清单。您的目录只需上传一次， 记下它的 `catalog_id`，把这个 id 传给测肤即可。目录会一直保留，直到您删除它。 目录归属于您的账号，不属于某一个 API 密钥：账号下的每个 API 密钥——包括项目密钥—— 看到的都是同一批目录；轮换密钥或删除密钥都不会影响它们。 上传与存储目录完全免费。 * 目录文件 | 项 - [POST /s2s/v2.1/product-catalog](https://docs.perfectcorp.com/zh-cn/reference/ai_skin_analysis/product-catalogs/paths/~1s2s~1v2.1~1product-catalog/post.md): 以 CSV 文件上传商品目录。文件会在同一次请求中完成校验：校验通过的文件返回 `status` `ready`，并带上它的 `catalog_id` 与 `sku_count`；未通过校验的文件返回错误，同时仍会记录为一个 `failed` 目录，「列出目录」接口会把它列出来。 - [GET /s2s/v2.1/product-catalog](https://docs.perfectcorp.com/zh-cn/reference/ai_skin_analysis/product-catalogs/paths/~1s2s~1v2.1~1product-catalog/get.md): 列出您账号下的所有目录，最新的排在最前面，`ready` 与 `failed` 都会列出。手上没有了某个 `catalog_id` 时，可以用它找回来。该接口不分页：每个账号可保留的目录数量有上限（见「商品目录」章节下的「限制」）。 - [DELETE /s2s/v2.1/product-catalog/{catalog_id}](https://docs.perfectcorp.com/zh-cn/reference/ai_skin_analysis/product-catalogs/paths/~1s2s~1v2.1~1product-catalog~1%7Bcatalog_id%7D/delete.md): 删除目录立即生效且不可撤销。从那一刻起，所有使用该 `catalog_id` 的测肤调用都会失败。已删除的目录无法恢复。