{ "openapi": "3.0.0", "info": { "title": "AI 肤质分析", "description": "# 概览\n![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_demostore_skincarelive_topbanner.0cffe3a7.jpg)\nAI 肤质分析技术借助人工智能分析皮肤的方方面面——纹理、色素、水润度、毛孔大小——精准度相当高。依靠先进算法与机器学习，AI 肤质分析只凭一张正脸自拍照就能评估脸部皮肤问题，给出准确的问题评分与检测蒙版，从而为每个人的肤质与困扰量身推荐产品与护肤流程。\n\n这不但提升了护肤产品的有效性，也让用户能为自己的护肤方案做出明白的抉择。接入 AI 肤质分析之后，用户就能在数据洞察的指引下，走向更健康、更透亮的肌肤，收获更有效的护肤方案。\n\n\n## 接入指南\n* AI 肤质分析怎么拍照\n* 正脸自拍一张\n - 拍一张清楚的照片即可，正对镜头。头发散下放下来、垂到胸前，视线直视前方，做出正对镜头的角度。\n - 也可以用 JS Camera Kit 拍照。同样把头发散下放下来、垂到胸前，不要扎起来。\n\n* 接口流程\n**测肤接口使用指引**\n本指引说明如何用 File 接口与 AI 任务接口上传图片并创建 AI 肤质分析。\n\n * **第 1 步：调整源图尺寸**
\n 把图片缩放到支持的尺寸范围——SD 为长边不超过 2560 像素、短边至少 480 像素；HD 为长边不超过 2560 像素、短边至少 1080 像素。详见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)**\n\n * **第 2 步：通过 File 接口上传文件元数据**\n- 图片要求\n - 详见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)**\n\n发送 POST 请求初始化文件上传：\n\n```bash\ncurl --request POST \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/file \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"files\": [\n {\n \"content_type\": \"image/png\",\n \"file_name\": \"skin_analysis_01_3dbd1b6683.png\",\n \"file_size\": 547541\n }\n ]\n }'\n```\n\n- ***重要***：只调用 File 接口并不等于上传了文件。您必须**另外把文件上传到 File 接口响应中给出的那个 URL**。那个 URL 就是您的上传目标，务必确认文件已成功传过去，再继续往下做。\n\n > **警告：** 请注意，若未把文件上传到 File 接口响应中给出的 URL，调用 AI 接口时会得到 500 Server Error / unknown_internal_error 或 404 Not Found 错误。\n\n***\n\n * **第 3 步：取得上传 URL 与文件 ID**\n\n响应中包含：\n\n* `requests.url` – 用于上传图片的预签名 URL。\n* `file_id` – 创建 AI 任务用的标识。\n\n**响应示例：**\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"files\": [\n {\n \"content_type\": \"image/png\",\n \"file_name\": \"skin_analysis_01_3dbd1b6683.png\",\n \"file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n \"requests\": [\n {\n \"method\": \"PUT\",\n \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\",\n \"headers\": {\n \"Content-Length\": \"547541\",\n \"Content-Type\": \"image/png\"\n }\n }\n ]\n }\n ]\n }\n}\n```\n\n***\n\n * **第 4 步：把图片上传到预签名 URL**\n\n使用提供的 `requests.url` 与请求头：\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n --header 'Content-Type: image/png' \\\n --header 'Content-Length: 547541' \\\n --data-binary @'./skin_analysis_01_3dbd1b6683.png'\n```\n\n***\n\n * **第 5 步：创建 AI 任务**\n\n用第 2 步取得的 `file_id` 创建 AI 肤质分析：\n\n```bash\ncurl --request POST \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"src_file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n \"dst_actions\": [\"wrinkle\", \"pore\", \"texture\", \"acne\"],\n \"miniserver_args\": {\n \"enable_mask_overlay\": true,\n \"enable_dark_background_hd_pore\": true,\n \"color_dark_background_hd_pore\": \"3D3D3D\",\n \"opacity_dark_background_hd_pore\": 0.4\n // Additional parameters omitted for brevity\n },\n \"format\": \"json\"\n }'\n```\n 上传完成后，就可以用文件 ID 或图片文件 URL 选择要分析的皮肤问题，详见 **[输入与输出](#section/overview/Inputs-and-Outputs)**。
\n 随后用文件 ID 或图片文件 URL 调用 POST 'task/skin-analysis' 执行任务，\n 并取得 ***task_id***。\n 请注意，SD 与 HD 的皮肤问题参数**不可**同时混用。\n\n- **使用已有的公开图片 URL**\n不必上传，发起 AI 任务时直接提供一个可公开访问的图片 URL 也可以。\n\n**响应示例：**\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"task_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT\"\n }\n}\n```\n\n***\n\n * **第 6 步：轮询任务状态**\n\n用 `task_id` 取回任务结果：\n\n```bash\ncurl --request GET \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis/ \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'Content-Type: application/json'\n```\n用这个 ***task_id*** 轮询 GET 'task/skin-analysis' 监控任务状态，取得引擎当前的处理进度。引擎完成任务之前，状态会一直是 'running'，这一阶段不消耗点数。\n\n处理完成的结果保留 30 天。\n- 不必用很短的间隔轮询。\n- 在保留期限内，轮询间隔可以自由安排。\n\n > **重要：** 由于执行时长没有保证，仍然需要轮询来查看任务状态。\n\n引擎成功处理您的输入文件、生成出图后，任务状态会变为 'success'。您会得到处理后图片的 URL 以及一个 dst_id，可直接串联下一个 AI 任务，不必把结果图重新上传。\n\n只有这种情况才会消耗点数。若引擎处理失败，任务状态会变为 'error'，不消耗点数。\n扣除点数时，系统优先扣除临近到期的点数；到期日相同时，优先扣除最早取得的点数。\n\n\n***\n\n * **第 7 步：解读结果**\n\n响应中包含：\n\n* `ui_score` – 面向用户的分数。\n* `raw_score` – 原始分析分数。\n* `mask_urls` – 检测蒙版的 URL。\n\n**响应示例：**\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"results\": {\n \"output\": [\n {\n \"type\": \"texture\",\n \"ui_score\": 68,\n \"raw_score\": 57.33,\n \"mask_urls\": [\"https://yce-us.s3-accelerate.amazonaws.com/...texture_output.jpg\"]\n },\n {\n \"type\": \"pore\",\n \"ui_score\": 92,\n \"raw_score\": 95.34,\n \"mask_urls\": [\"https://yce-us.s3-accelerate.amazonaws.com/...pore_output.jpg\"]\n }\n // Additional results omitted for brevity\n ]\n },\n \"task_status\": \"success\"\n }\n}\n```\n\n\n* 排障指引\n> **警告：** 请注意，SD 与 HD 的皮肤问题参数**不可**同时混用。偏离这些规范会得到 ***InvalidParameters*** 错误。\n\n * 若您混用 HD 与 SD 的皮肤问题参数，会得到如下错误：\n ```json\n {\n \"status\": 400,\n \"error\": \"cannot mix HD and SD dst_actions\",\n \"error_code\": \"InvalidParameters\"\n }\n ```\n * 若您拼错皮肤问题名称，或传入未知的皮肤问题，会得到如下错误：\n ```json\n {\n \"status\": 400,\n \"error\": \"Not available dst_action abc123\",\n \"error_code\": \"InvalidParameters\"\n }\n ```\n\n---\n\n* 实际案例：\n![](https://plugins-media.makeupar.com/webconsultation/images/skincare-widget/img_webcm_skincare_service_survey_demo.jpg)\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/skin_analysis_s5_poster_3_dt_85efe14952.png)\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Skincare_Pro_Medspa_Situation_Image_6aea6046f9.jpg)\n\n## 输入与输出\n* 输入参数说明\n控制 AI 肤质分析结果视觉呈现的方式有两种：要么生成多张图片，每项皮肤问题各出一张独立蒙版；要么用 ``enable_mask_overlay`` 参数合成一张叠加图。系统默认输出多张蒙版，如何把每项皮肤问题的蒙版与图片混合，完全由您掌握。\n\n* 默认：enable_mask_overlay false\n ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/mask_overlay_false_1920_ea1cde0ead.png)\n\n* 把 enable_mask_overlay 设为 true\n ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/mask_overlay_1920_0fbb4786cc.png)\n\n----\n\n* 输出 ZIP 数据结构说明\n系统会提供一个 ZIP 文件，里面有一个 'skinanalysisResult' 文件夹。该文件夹中有一份 'score_info.json'，收录全部检测分数以及结果图片的对应关系。\n\n'score_info.json' 收录所有测肤检测结果，包含数值分数与对应输出蒙版文件的名称。\n\nPNG 文件是检测结果蒙版，可以叠加到您的原图上。直接用这些 PNG 的 alpha 值与原图混合，就能在原图上直接看到检测结果。\n\n* AI 肤质分析 ZIP 的文件结构\n* HD 护肤 ZIP\n * skinanalysisResult\n - score_info.json\n - hd_acne_output.png\n - hd_age_spot_output.png\n - hd_dark_circle_output.png\n - hd_droopy_lower_eyelid_output.png\n - hd_droopy_upper_eyelid_output.png\n - hd_eye_bag_output.png\n - hd_firmness_output.png\n - hd_moisture_output.png\n - hd_oiliness_output.png\n - hd_radiance_output.png\n - hd_redness_output.png\n - hd_texture_output.png\n - hd_pore_output_all.png\n - hd_pore_output_cheek.png\n - hd_pore_output_forehead.png\n - hd_pore_output_nose.png\n - hd_wrinkle_output_all.png\n - hd_wrinkle_output_crowfeet.png\n - hd_wrinkle_output_forehead.png\n - hd_wrinkle_output_glabellar.png\n - hd_wrinkle_output_marionette.png\n - hd_wrinkle_output_nasolabial.png\n - hd_wrinkle_output_periocular.png\n - hd_tear_trough.png\n - hd_skin_type.png\n\n* SD 护肤 ZIP\n * skinanalysisResult\n - score_info.json\n - acne_output.png\n - age_spot_output.png\n - dark_circle_v2_output.png\n - droopy_lower_eyelid_output.png\n - droopy_upper_eyelid_output.png\n - eye_bag_output.png\n - firmness_output.png\n - moisture_output.png\n - oiliness_output.png\n - pore_output.png\n - radiance_output.png\n - redness_output.png\n - texture_output.png\n - wrinkle_output.png\n - tear_trough.png\n - skin_type.png\n\n* JSON 数据结构（score_info.json）\n * \"all\"：1 到 100 之间的浮点数，代表整体皮肤状况。分数越高，皮肤越健康、观感越好。\n * \"skin_age\"：由 AI 推算的皮肤年龄，参照全年龄段人群分布得出。\n * 每个类别包含：\n * \"raw_score\"：1 到 100 之间的浮点数。分数越高，皮肤越健康、观感越好。\n * \"ui_score\"：1 到 100 之间的整数。UI 分数在美容评估中主要起心理激励的作用。我们会调整原始分数，让结果更讨喜——考虑到消费者普遍希望关于自己皮肤状况的评价更正面。这样的校准能让用户更有信心，同时守住美容心理学的底层框架。\n * \"output_mask_name\"：对应输出蒙版图片的文件名。\n\n * 类别与说明\n * HD 护肤：\n * \"hd_redness\"：衡量泛红严重程度。\n * \"hd_oiliness\"：判定出油程度。\n * \"hd_age_spot\"：检测老年斑与色素沉淀。\n * \"hd_radiance\"：评估光泽度。\n * \"hd_moisture\"：评估皮肤水润度。\n * \"hd_dark_circle\"：分析眼下黑眼圈情况。\n * \"hd_eye_bag\"：检测眼袋。\n * \"hd_droopy_upper_eyelid\"：衡量上眼皮下垂程度。\n * \"hd_droopy_lower_eyelid\"：衡量下眼皮下垂程度。\n * \"hd_firmness\"：评估皮肤紧实度与弹性。\n * \"hd_texture\"：子类别[whole]；分析整体皮肤纹理。\n * \"hd_acne\"：子类别[whole]；检测痘痘情况。\n * \"hd_pore\"：子类别[forehead, nose, cheek, whole]；检测并评估脸部各区域的毛孔。\n * \"hd_wrinkle\"：子类别[forehead, glabellar, crowfeet, periocular, nasolabial, marionette, whole]；衡量脸部各区域皱纹的严重程度。\n * \"hd_tear_trough\"：检测泪沟。\n * \"hd_skin_type\"：子类别[whole, t_zone, u_zone]，评估肤质：Normal、Oily、Dry、Combination、Redness、Dry & Redness、Oily & Redness、Combination & Redness。\n\n * SD 护肤：\n * \"wrinkle\"：皱纹综合分析。\n * \"droopy_upper_eyelid\"：衡量上眼皮下垂程度。\n * \"droopy_lower_eyelid\"：衡量下眼皮下垂程度。\n * \"firmness\"：评估皮肤紧实度与弹性。\n * \"acne\"：评估痘痘情况。\n * \"moisture\"：衡量皮肤水润度。\n * \"eye_bag\"：检测眼袋。\n * \"dark_circle_v2\"：以另一套方法分析黑眼圈。\n * \"age_spot\"：检测老年斑。\n * \"radiance\"：评估皮肤明亮度。\n * \"redness\"：衡量泛红程度。\n * \"oiliness\"：判定出油程度。\n * \"pore\"：衡量毛孔明显程度。\n * \"texture\"：分析整体皮肤纹理。\n * \"tear_trough\"：检测泪沟。\n * \"skin_type\"：子类别[whole, t_zone, u_zone]，评估肤质：Normal、Oily、Dry、Combination、Redness、Dry & Redness、Oily & Redness、Combination & Redness。\n\n * HD 护肤的 score_info.json 示例\n ```json\n {\n \"hd_redness\": {\n \"raw_score\": 72.011962890625,\n \"ui_score\": 77,\n \"output_mask_name\": \"hd_redness_output.png\"\n },\n \"hd_oiliness\": {\n \"raw_score\": 60.74365234375,\n \"ui_score\": 72,\n \"output_mask_name\": \"hd_oiliness_output.png\"\n },\n \"hd_age_spot\": {\n \"raw_score\": 83.23274230957031,\n \"ui_score\": 77,\n \"output_mask_name\": \"hd_age_spot_output.png\"\n },\n \"hd_radiance\": {\n \"raw_score\": 76.57244205474854,\n \"ui_score\": 79,\n \"output_mask_name\": \"hd_radiance_output.png\"\n },\n \"hd_moisture\": {\n \"raw_score\": 48.694559931755066,\n \"ui_score\": 70,\n \"output_mask_name\": \"hd_moisture_output.png\"\n },\n \"hd_dark_circle\": {\n \"raw_score\": 80.1993191242218,\n \"ui_score\": 76,\n \"output_mask_name\": \"hd_dark_circle_output.png\"\n },\n \"hd_eye_bag\": {\n \"raw_score\": 76.67280435562134,\n \"ui_score\": 79,\n \"output_mask_name\": \"hd_eye_bag_output.png\"\n },\n \"hd_droopy_upper_eyelid\": {\n \"raw_score\": 79.05348539352417,\n \"ui_score\": 80,\n \"output_mask_name\": \"hd_droopy_upper_eyelid_output.png\"\n },\n \"hd_droopy_lower_eyelid\": {\n \"raw_score\": 79.97175455093384,\n \"ui_score\": 81,\n \"output_mask_name\": \"hd_droopy_lower_eyelid_output.png\"\n },\n \"hd_firmness\": {\n \"raw_score\": 89.66898322105408,\n \"ui_score\": 85,\n \"output_mask_name\": \"hd_firmness_output.png\"\n },\n \"hd_texture\": {\n \"whole\": {\n \"raw_score\": 66.3921568627451,\n \"ui_score\": 75,\n \"output_mask_name\": \"hd_texture_output.png\"\n }\n },\n \"hd_acne\": {\n \"whole\": {\n \"raw_score\": 59.92677688598633,\n \"ui_score\": 76,\n \"output_mask_name\": \"hd_acne_output.png\"\n }\n },\n \"hd_pore\": {\n \"forehead\": {\n \"raw_score\": 79.59770965576172,\n \"ui_score\": 80,\n \"output_mask_name\": \"hd_pore_output_forehead.png\"\n },\n \"nose\": {\n \"raw_score\": 29.139814376831055,\n \"ui_score\": 58,\n \"output_mask_name\": \"hd_pore_output_nose.png\"\n },\n \"cheek\": {\n \"raw_score\": 44.11081314086914,\n \"ui_score\": 65,\n \"output_mask_name\": \"hd_pore_output_cheek.png\"\n },\n \"whole\": {\n \"raw_score\": 49.23978805541992,\n \"ui_score\": 67,\n \"output_mask_name\": \"hd_pore_output_all.png\"\n }\n },\n \"hd_wrinkle\": {\n \"forehead\": {\n \"raw_score\": 55.96956729888916,\n \"ui_score\": 67,\n \"output_mask_name\": \"hd_wrinkle_output_forehead.png\"\n },\n \"glabellar\": {\n \"raw_score\": 76.7251181602478,\n \"ui_score\": 75,\n \"output_mask_name\": \"hd_wrinkle_output_glabellar.png\"\n },\n \"crowfeet\": {\n \"raw_score\": 83.4361481666565,\n \"ui_score\": 78,\n \"output_mask_name\": \"hd_wrinkle_output_crowfeet.png\"\n },\n \"periocular\": {\n \"raw_score\": 67.88706302642822,\n \"ui_score\": 72,\n \"output_mask_name\": \"hd_wrinkle_output_periocular.png\"\n },\n \"nasolabial\": {\n \"raw_score\": 74.03312683105469,\n \"ui_score\": 74,\n \"output_mask_name\": \"hd_wrinkle_output_nasolabial.png\"\n },\n \"marionette\": {\n \"raw_score\": 71.94477319717407,\n \"ui_score\": 73,\n \"output_mask_name\": \"hd_wrinkle_output_marionette.png\"\n },\n \"whole\": {\n \"raw_score\": 49.64699745178223,\n \"ui_score\": 65,\n \"output_mask_name\": \"hd_wrinkle_output_all.png\"\n }\n },\n \"all\": {\n \"score\": 75.75757575757575\n },\n \"skin_age\": 37\n }\n ```\n * SD 护肤的 score_info.json 示例\n ```json\n {\n \"wrinkle\": {\n \"raw_score\": 36.09360456466675,\n \"ui_score\": 60,\n \"output_mask_name\": \"wrinkle_output.png\"\n },\n \"droopy_upper_eyelid\": {\n \"raw_score\": 79.05348539352417,\n \"ui_score\": 80,\n \"output_mask_name\": \"droopy_upper_eyelid_output.png\"\n },\n \"droopy_lower_eyelid\": {\n \"raw_score\": 79.97175455093384,\n \"ui_score\": 81,\n \"output_mask_name\": \"droopy_lower_eyelid_output.png\"\n },\n \"firmness\": {\n \"raw_score\": 89.66898322105408,\n \"ui_score\": 85,\n \"output_mask_name\": \"firmness_output.png\"\n },\n \"acne\": {\n \"raw_score\": 92.29713000000001,\n \"ui_score\": 88,\n \"output_mask_name\": \"acne_output.png\"\n },\n \"moisture\": {\n \"raw_score\": 48.694559931755066,\n \"ui_score\": 70,\n \"output_mask_name\": \"moisture_output.png\"\n },\n \"eye_bag\": {\n \"raw_score\": 76.67280435562134,\n \"ui_score\": 79,\n \"output_mask_name\": \"eye_bag_output.png\"\n },\n \"dark_circle_v2\": {\n \"raw_score\": 80.1993191242218,\n \"ui_score\": 76,\n \"output_mask_name\": \"dark_circle_v2_output.png\"\n },\n \"age_spot\": {\n \"raw_score\": 83.23274230957031,\n \"ui_score\": 77,\n \"output_mask_name\": \"age_spot_output.png\"\n },\n \"radiance\": {\n \"raw_score\": 76.57244205474854,\n \"ui_score\": 79,\n \"output_mask_name\": \"radiance_output.png\"\n },\n \"redness\": {\n \"raw_score\": 72.011962890625,\n \"ui_score\": 77,\n \"output_mask_name\": \"redness_output.png\"\n },\n \"oiliness\": {\n \"raw_score\": 60.74365234375,\n \"ui_score\": 72,\n \"output_mask_name\": \"oiliness_output.png\"\n },\n \"pore\": {\n \"raw_score\": 88.38014125823975,\n \"ui_score\": 84,\n \"output_mask_name\": \"pore_output.png\"\n },\n \"texture\": {\n \"raw_score\": 80.09742498397827,\n \"ui_score\": 76,\n \"output_mask_name\": \"texture_output.png\"\n },\n \"all\": {\n \"score\": 75.75757575757575\n },\n \"skin_age\": 37\n }\n ```\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |\n| ---- | ---- | ---- | ---- |\n| SD 护肤 | 短边长度至少 480 像素。
长边不限制；但超过 2560 像素时，系统会自动缩放到 2560 像素。 | < 10MB | jpg/jpeg/png |\n| HD 护肤 | 短边长度至少 1080 像素。
长边不限制；但超过 2560 像素时，会自动缩放到 2560 像素。 |< 10MB | jpg/jpeg/png |\n\n> **警告：** 接口会自动把图片缩放到最大 2560 像素，但请自行确保所有人脸清楚合焦、画质够高、光线均匀、人脸足够大且正对相机。拍摄 HD 或 SD 护肤图片、准备跑 AI 肤质分析之前，务必避开运动模糊与遮挡。为获得最佳效果，强烈建议采用竖幅（肖像）比例，不要横幅。\n\n* 拍摄建议：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png)\n\n* 开始测肤前的准备说明\n* 摘下眼镜，确认刘海没有遮住额头\n* 确保您处在光线充足的环境中\n* 卸妆后再测，结果更准\n* 直视镜头，把脸保持在画面中央\n\n* 照片要求\n我们会检查图片质量，确认它适合跑 AI 肤质分析。请确保脸部约占图片宽度的 60–80%，没有任何叠加物或遮挡。光线要明亮且分布均匀，避免过曝与高光溢出。姿态须正对镜头、自然放松，嘴巴闭合、眼睛睁开。\n\n请完整露出额头，把刘海往后梳或把头发扎起来，保证质量最佳。建议摘下眼镜，AI 肤质分析表现更好，这一项不是强制要求。\n> **警告：** 脸部宽度需大于图片宽度的 60%。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_error_src_face_too_small_cr_725792a7fb.png)\n\n\n* 错误码\n\n|错误码|说明|\n| ---- | ---- |\n|error_below_min_image_size|输入图片分辨率过小|\n|error_exceed_max_image_size|输入图片分辨率过大|\n|error_src_face_too_small|上传图片中的脸部区域太小。脸部宽度需大于图片宽度的 60%。|\n|error_src_face_out_of_bound|上传图片中的脸部区域超出画面边界|\n|error_lighting_dark|上传图片的光线太暗|\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2
- curl >= 7.58 (modern TLS/HTTP support)
- jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 |\n| PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) or allow_url_fopen=On + ext-openssl, ext-json |\n| Python | Python >= 3.10 (for f-strings), requests >= 2.20.0 |\n| Java | Java 11+ (for HttpClient), Jackson Databind >= 2.12.0 |\n\n---\n\n## 点数消耗\n\n* AI 肤质分析 V2.0\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| 分析 1~4 项皮肤问题 | SD 9 点；HD 12 点 | \n| 分析 5~8 项皮肤问题 | SD 12 点；HD 16 点 |\n| 分析 9~12 项皮肤问题 | SD 14 点；HD 20 点 |\n| 分析 13~16 项皮肤问题 | SD 16 点；HD 22 点 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## Mobile Camera Kit\n{% partial file=\"/_partials/mobile-camera-kit.md\" /%}\n\n---\n", "version": "", "termsOfService": "https://www.makeupar.com/perfectbeauty/youcam/terms-of-service-api", "contact": { "email": "YouCamOnlineEditor_API@perfectcorp.com" }, "license": { "name": "Privacy policy", "url": "https://www.makeupar.com/perfectbeauty/youcam/privacy-policy-api" } }, "servers": [ { "url": "https://yce-api-01.makeupar.com" } ], "tags": [ { "name": "V2.0", "description": "AI 肤质分析技术借助人工智能，对肌肤的多个维度做出精细分析，从肤质纹理、色素沉着到水润程度与毛孔大小。" } ], "paths": { "/s2s/v2.0/task/skin-analysis": { "post": { "summary": "执行 AI 肤质分析 任务。", "description": "AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 `success` 或 `error` 通知后，用收到的 `task_id` 查询任务结果。配置与校验的细节请见 [Webhook 接入指南](/develop/webhook.md)。\n\n若功能不支持 Webhook，或您的接入方式用不了 Webhook，就请实现轮询。提交 AI 任务后，按固定间隔（例如每 10 秒）轮询状态接口，直到任务状态变为 `success` 或 `error`。\n", "tags": [ "V2.0" ], "security": [ { "BearerAuthenticationV2": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunSkincareTaskV2" } } } }, "responses": { "200": { "description": "AI 肤质分析任务执行成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicRunTaskResponseV2" } } } }, "400": { "$ref": "#/components/responses/RunError" }, "401": { "$ref": "#/components/responses/InvalidApiKey" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/s2s/v2.0/task/skin-analysis/{task_id}": { "get": { "summary": "查询 AI 肤质分析 任务的状态。", "description": "AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 `success` 或 `error` 通知后，用收到的 `task_id` 查询任务结果。配置与校验的细节请见 [Webhook 接入指南](/develop/webhook.md)。\n\n若功能不支持 Webhook，或您的接入方式用不了 Webhook，就请实现轮询。提交 AI 任务后，按固定间隔（例如每 10 秒）轮询状态接口，直到任务状态变为 `success` 或 `error`。\n", "tags": [ "V2.0" ], "security": [ { "BearerAuthenticationV2": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe" }, "description": "要查询的任务 ID" } ], "responses": { "200": { "$ref": "#/components/responses/SkinAnalysisResponse" }, "400": { "$ref": "#/components/responses/InvalidTaskId" }, "401": { "$ref": "#/components/responses/InvalidApiKey" }, "500": { "$ref": "#/components/responses/TaskTimeout" } } } } }, "components": { "securitySchemes": { "BearerAuthenticationV2": { "type": "http", "scheme": "bearer", "description": "使用标准的 Bearer 鉴权。把您的 API 密钥放进请求头： `Authorization:Bearer YOUR_API_KEY`。请注意 'Bearer' 与 'YOUR_API_KEY' 之间有一个空格。" } }, "schemas": { "RunSkincareTaskV2": { "allOf": [ { "$ref": "#/components/schemas/BasicRunTaskV2" }, { "title": "RunSkincareTaskV2", "description": "该对象表示一次 AI 肤质分析任务的运行。", "type": "object", "properties": { "dst_actions": { "$ref": "#/components/schemas/RunSkincareTaskDstActions" }, "miniserver_args": { "$ref": "#/components/schemas/RunSkincareTaskMiniserverArgs" }, "format": { "type": "string", "enum": [ "json", "zip" ], "description": "分析结果的返回格式，默认为 'zip'。 - `zip`：结果打包成可下载的 ZIP 文件，内含 skinanalysisResult 目录， 包含 score_info.json 与全部检测结果图片。响应中会给出下载该 ZIP 的 URL。 - `json`：结果直接以 JSON 形式在响应体中返回。 注意：format=json 与 format=zip 的响应结构不同。\n", "example": "zip" } }, "required": [ "dst_actions" ] } ] }, "RunSkincareTaskDstActions": { "type": "array", "description": "AI 肤质分析的分析项目。\n分析项目分为 HD 与 SD 两类。\n您可以选择一个或多个项目，但必须全部为 SD 或全部为 HD。\n注意：HD 与 SD 项目不能混用。\nHD 项目：\n - hd_redness：衡量泛红严重程度。\n - hd_oiliness：判断出油程度。\n - hd_age_spot：检测老年斑与色素沉着。\n - hd_radiance：评估肌肤光泽度。\n - hd_moisture：评估肌肤含水量。\n - hd_dark_circle：分析眼下黑眼圈情况。\n - hd_eye_bag：检测眼袋。\n - hd_droopy_upper_eyelid：衡量上睑下垂严重程度。\n - hd_droopy_lower_eyelid：衡量下睑下垂严重程度。\n - hd_firmness：评估肌肤紧致度与弹性。\n - hd_texture：分析整体肤质纹理。\n - hd_acne：检测痘痘情况。\n - hd_pore：检测并评估各面部区域的毛孔（额头、鼻、颊、全脸）。\n - hd_wrinkle：衡量各面部区域皱纹的严重程度（额头、眉间、眼角、眼周、法令纹、木偶纹、全脸）。\n - hd_tear_trough：检测泪沟。\n - hd_skin_type：按子类（全脸、T 区、U 区）判定肤质，取值为中性、油性、干性、混合性、泛红、干性伴泛红、油性伴泛红、混合性伴泛红。\n\nSD 项目：\n - wrinkle：皱纹总体分析。\n - droopy_upper_eyelid：衡量上睑下垂严重程度。\n - droopy_lower_eyelid：衡量下睑下垂严重程度。\n - firmness：评估肌肤紧致度与弹性。\n - acne：评估痘痘情况。\n - moisture：衡量肌肤含水量。\n - eye_bag：检测眼袋。\n - dark_circle_v2：分析黑眼圈。\n - age_spot：检测老年斑。\n - radiance：评估肌肤明亮度。\n - redness：衡量泛红程度。\n - oiliness：判断出油程度。\n - pore：衡量毛孔明显程度。\n - texture：分析整体肤质纹理。\n - tear_trough：检测泪沟。\n - skin_type：按子类（全脸、T 区、U 区）判定肤质，取值为中性、油性、干性、混合性、泛红、干性伴泛红、油性伴泛红、混合性伴泛红。\n", "items": { "type": "string", "enum": [ "hd_wrinkle", "hd_pore", "hd_texture", "hd_acne", "hd_oiliness", "hd_radiance", "hd_eye_bag", "hd_age_spot", "hd_dark_circle", "hd_droopy_upper_eyelid", "hd_droopy_lower_eyelid", "hd_firmness", "hd_moisture", "hd_redness", "hd_tear_trough", "hd_skin_type", "wrinkle", "pore", "texture", "acne", "oiliness", "radiance", "eye_bag", "age_spot", "dark_circle_v2", "droopy_upper_eyelid", "droopy_lower_eyelid", "firmness", "moisture", "redness", "tear_trough", "skin_type" ] }, "example": [ "hd_wrinkle", "hd_pore", "hd_texture", "hd_acne" ] }, "RunSkincareTaskMiniserverArgs": { "type": "object", "properties": { "enable_mask_overlay": { "type": "boolean", "description": "控制是否把蒙版叠加到图片上。为 true 时返回叠加后的 .jpg， 为 false 时返回原始蒙版 .png。默认为 false。
所有输出图片的长边最高为 2560 像素。若未启用 enable_mask_overlay，您需要自行确认输入分辨率是否超过 2560，并在客户端相应处理蒙版叠加。当输入图片长边小于 2560 像素时，按原图分辨率显示；否则请按 2560 像素配置显示。" }, "enable_dark_background_hd_pore": { "type": "boolean", "description": "为高清毛孔可视化启用深色底" }, "color_dark_background_hd_pore": { "type": "string", "description": "高清毛孔深色底可视化所用的颜色（十六进制）", "example": "3D3D3D" }, "opacity_dark_background_hd_pore": { "type": "number", "minimum": 0, "maximum": 1, "description": "高清毛孔深色底可视化的不透明度", "example": 0.4 }, "enable_dark_background_hd_wrinkle": { "type": "boolean", "description": "为高清皱纹可视化启用深色底" }, "color_dark_background_hd_wrinkle": { "type": "string", "description": "高清皱纹深色底可视化所用的颜色（十六进制）", "example": "3D3D3D" }, "opacity_dark_background_hd_wrinkle": { "type": "number", "minimum": 0, "maximum": 1, "description": "高清皱纹深色底可视化的不透明度", "example": 0.4 } } }, "SkinAnalysisResponseV2": { "type": "object", "properties": { "status": { "type": "integer", "description": "响应状态", "example": 200 }, "data": { "type": "object", "properties": { "task_status": { "type": "string", "enum": [ "running", "success", "error" ], "description": "任务状态" }, "error": { "$ref": "#/components/schemas/EngineErrorCode" }, "error_message": { "type": "string", "description": "错误的详细说明" }, "results": { "oneOf": [ { "$ref": "#/components/schemas/SkinAnalysisResultsV2Zip" }, { "$ref": "#/components/schemas/SkinAnalysisResultsV2Json" } ] } } } } }, "SkinAnalysisResultsV2Zip": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "该结果的下载 URL，有效期 2 小时。返回的 ZIP 文件内含 skinanalysisResult 目录，其中的 score_info.json 记录了全部检测项的评分， 目录中还包含所有检测结果图片。若请求了高级测肤报告或商品推荐， 目录中还会有 llm_results.json。 仅在 format 为 `zip` 时提供。", "example": "https://example.com/sample-result-url" } } }, "SkinAnalysisResultsV2Json": { "type": "object", "required": [ "output" ], "properties": { "output": { "type": "array", "description": "分析结果以 JSON 格式直接写在响应体中。 当请求了高级测肤报告或商品推荐时，输出中还会有一个 `type` 为 `llm_results` 的条目，其 `mask_urls[0]` 即 llm_results.json 的 URL。 仅在 format 为 `json` 时可用。", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "AI 肤质分析的分析项目", "example": "hd_skin_type" }, "region": { "type": "string", "description": "分析所聚焦的面部区域", "example": "whole" }, "raw_score": { "type": "number", "description": "1 到 100 之间的浮点数。raw_score 指 AI 模型直接预测出的分数", "example": 98.5 }, "ui_score": { "type": "integer", "description": "1 到 100 之间的整数。ui_score 是在 raw_score 基础上调整后的分数", "example": 97 }, "score": { "type": "number", "description": "1 到 100 之间的浮点数，表示肌肤整体状况。", "example": 97.66 }, "mask_urls": { "type": "array", "description": "分析过程中生成的蒙版图或缩放图的 URL", "items": { "type": "string", "example": "https://example.com/mask_image_1.png" } } } } } } }, "SkinAnalysisAdvancedReport": { "type": "object", "description": "高级测肤报告的选项，结果放在 llm_results.json 里返回。不传这个对象、或传一个空对象，就全部用默认值。\n", "properties": { "language": { "type": "string", "enum": [ "enu", "cht", "jpn", "kor", "fra", "deu", "esn", "ita", "ptb", "ind", "ara" ], "default": "enu", "description": "报告使用的语言。", "example": "cht" }, "tone": { "type": "string", "enum": [ "warm", "direct" ], "default": "warm", "description": "报告的语气。两种语气都保持专业。", "example": "direct" }, "country": { "type": "string", "description": "用来给报告加上气候与季节背景的国家。", "example": "Taiwan" }, "city": { "type": "string", "description": "用来给报告加上气候与季节背景的城市。", "example": "Taipei" } } }, "SkinAnalysisProductRecommendation": { "type": "object", "description": "必填。从您的某个商品目录里推荐商品，结果放在 llm_results.json 里返回。\n", "properties": { "catalog_id": { "type": "string", "description": "必填。您通过商品目录接口上传的商品目录 ID。该目录必须处于 ready 状态，且属于您的账号。\n", "example": "123456789012345678" }, "top_n": { "type": "integer", "minimum": 1, "default": 3, "description": "每类皮肤问题要推荐的商品数。不能超过目录里的商品数量。\n", "example": 3 } } }, "BasicRunTaskV2SrcFileUrl": { "type": "object", "required": [ "src_file_url" ], "properties": { "src_file_url": { "type": "string", "description": "用于运行任务的文件 URL，该 URL 需可公开访问。", "example": "https://example.com/selfie.jpg" } } }, "BasicRunTaskV2SrcFileId": { "type": "object", "required": [ "src_file_id" ], "properties": { "src_file_id": { "type": "string", "description": "用于运行任务的文件 ID，取自上传文件接口返回的 file_id。", "example": "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=" } } }, "BasicRunTaskV2": { "title": "BasicRunTaskV2", "anyOf": [ { "title": "用源文件 URL 运行任务", "allOf": [ { "$ref": "#/components/schemas/BasicRunTaskV2SrcFileUrl" } ] }, { "title": "用源文件 ID 运行任务", "allOf": [ { "$ref": "#/components/schemas/BasicRunTaskV2SrcFileId" } ] } ] }, "BasicRunTaskResponseV2": { "type": "object", "properties": { "status": { "type": "integer", "description": "响应状态", "example": 200 }, "data": { "type": "object", "properties": { "task_id": { "type": "string", "description": "该任务的 ID。凭这个 ID 可在 24 小时内查询任务结果。", "example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe" } } } } }, "EngineErrorCode": { "type": "string", "nullable": true, "enum": [ "error_exceed_max_image_size", "exceed_max_filesize", "invalid_parameter", "error_download_image", "error_download_mask", "error_decode_image", "error_decode_mask", "error_nsfw_content_detected", "error_no_face", "error_pose", "error_face_parsing", "error_inference", "exceed_nsfw_retry_limits", "error_upload", "unknown_internal_error" ], "description": "错误码：\n- \\`error_exceed_max_image_size\\` - 输入图片尺寸超出上限\n- \\`exceed_max_filesize\\` - 输入文件大小超出上限\n- \\`invalid_parameter\\` - 参数取值无效\n- \\`error_download_image\\` - 下载原图出错\n- \\`error_download_mask\\` - 下载蒙版图片出错\n- \\`error_decode_image\\` - 解码原图出错\n- \\`error_decode_mask\\` - 解码蒙版图片出错\n- \\`error_nsfw_content_detected\\` - 在原图中检测到不适宜内容（NSFW）\n- \\`error_no_face\\` - 原图中没有检测到人脸\n- \\`error_pose\\` - 原图的姿态检测失败\n- \\`error_face_parsing\\` - 原图的人脸分割失败\n- \\`error_inference\\` - 推理流程中出现错误\n- \\`exceed_nsfw_retry_limits\\` - 为避免生成不适宜内容， 重试次数已用尽\n- \\`error_upload\\` - 上传结果图片出错\n- \\`unknown_internal_error\\` - 其他错误\n" } }, "responses": { "SkinAnalysisResponse": { "description": "AI 肤质分析任务状态查询成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SkinAnalysisResponseV2" } ] }, "examples": { "format_zip_success": { "summary": "format=zip 时的响应（成功）", "description": "任务已成功完成，结果打包为一个 ZIP 文件。", "value": { "status": 200, "data": { "task_status": "success", "results": "https://example.com/sample-result-url" } } }, "format_json_success": { "summary": "format=json 时的响应（成功）", "description": "任务已成功完成，结果直接以 JSON 返回，包含各项分数与图片 URL。", "value": { "status": 200, "data": { "task_status": "success", "results": { "output": [ { "type": "hd_wrinkle", "region": "whole", "raw_score": 25.3, "ui_score": 25, "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_wrinkle_whole.jpg" ] }, { "type": "hd_wrinkle", "region": "forehead", "raw_score": 20.1, "ui_score": 20, "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_wrinkle_forehead.jpg" ] }, { "type": "hd_wrinkle", "region": "glabellar", "raw_score": 15.8, "ui_score": 16, "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_wrinkle_glabellar.jpg" ] }, { "type": "hd_wrinkle", "region": "crowfeet", "raw_score": 30.5, "ui_score": 31, "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_wrinkle_crowfeet.jpg" ] }, { "type": "hd_pore", "region": "whole", "raw_score": 35.2, "ui_score": 35, "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_pore_whole.jpg" ] }, { "type": "hd_pore", "region": "forehead", "raw_score": 30, "ui_score": 30, "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_pore_forehead.jpg" ] }, { "type": "hd_pore", "region": "nose", "raw_score": 45.7, "ui_score": 46, "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_pore_nose.jpg" ] }, { "type": "hd_pore", "region": "cheek", "raw_score": 32.1, "ui_score": 32, "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_pore_cheek.jpg" ] }, { "type": "hd_acne", "region": "whole", "raw_score": 12.5, "ui_score": 13, "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_acne_whole.jpg" ] }, { "type": "skin_age", "score": 29 }, { "type": "all", "score": 28.5 }, { "type": "resize_image", "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/resized_image.jpg" ] } ] } } } } } } } }, "RunError": { "type": "object", "properties": { "status": { "type": "integer", "description": "响应状态", "example": 400 }, "error": { "type": "string", "description": "错误信息", "example": "The operation could not be completed" }, "error_code": { "type": "string", "enum": [ "InvalidParameters", "CreditInsufficiency", "InvalidStyleGroup", "InvalidStyle", "BadRequest" ], "description": "错误码：\n * InvalidParameters - 请求参数无效\n * CreditInsufficiency - 点数不足，无法运行\n * BadRequest - 请求参数不符合预期\n * InvalidStyleGroup - 风格分组 ID 无效\n * InvalidStyle - 风格 ID 无效\n" } } }, "InvalidApiKey": { "description": "API 密钥无效或缺失", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 401, "description": "响应状态" }, "error": { "type": "string", "example": "Invalid API key" } } } } } }, "TooManyRequests": { "description": "请求过多", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 429, "description": "响应状态" }, "error": { "type": "string", "example": "Too many requests" } } } } } }, "InvalidTaskId": { "description": "任务 ID 无效", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 400, "description": "响应状态" }, "error": { "type": "string", "example": "Invalid task ID" } } } } } }, "TaskTimeout": { "description": "任务执行超时", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 500, "description": "响应状态" }, "error": { "type": "string", "example": "Task execution timed out" } } } } } } } } }