{
  "openapi": "3.0.0",
  "info": {
    "title": "AI 肤质分析 V2.1",
    "description": "# 概览\n![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_demostore_skincarelive_topbanner.0cffe3a7.jpg)\n\n**AI 肤质分析 V2.1** 只凭一张正脸自拍，就能给出细致的皮肤洞察。它检测 16 项皮肤指标，包括皱纹、毛孔、色斑、泛红与肤质，并标出每一项皮肤问题出现在脸上的哪个位置；同时估算肌肤年龄，并算出一个整体肌肤状况评分。\n\n在 V2.1 中，您可以按需加上两个加购能力，让接入更完整：\n\n- **高级测肤报告**：基于每位用户的检测结果，生成个性化、读起来轻松好懂的皮肤洞察。\n- **商品推荐**：把您商品目录里的商品对应用户的皮肤问题，做出有针对性的购物体验。\n\n可以只用肤质分析，也可以搭配加购能力一起用。想对比这几种用法，请见 [使用场景](#section/overview/use-cases)。\n\n## 接入指南\n* AI 肤质分析怎么拍照\n* 正脸自拍一张\n  - 拍一张清楚的照片即可，正对镜头。头发散下放下来、垂到胸前，视线直视前方，做出正对镜头的角度。\n  - 也可以用 JS Camera Kit 拍照。同样把头发散下放下来、垂到胸前，不要扎起来。\n\n* 接口流程\n**测肤接口使用指引**\n本指引说明如何用 File 接口与 AI 任务接口上传图片并创建 AI 肤质分析。\n\n   * **第 1 步：调整源图尺寸**</br>\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)**。</br>\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/<YOUR_TASK_ID> \\\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 像素。 <br> 长边不限制；但超过 2560 像素时，系统会自动缩放到 2560 像素。 | < 10MB | jpg/jpeg/png |\n| HD 护肤 | 短边长度至少 1080 像素。 <br> 长边不限制；但超过 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</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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\n* AI 肤质分析 V2.1\n\n| AI 功能 | SD | HD | 加购高级测肤报告 | 加购商品推荐 |\n|---|---|---|---|---|\n| 分析 1~4 项皮肤问题 | 9 | 12 | +15 点 | +10 点 |\n| 分析 5~8 项皮肤问题 | 12 | 16 | +25 点 | +15 点 |\n| 分析 9~12 项皮肤问题 | 14 | 20 | +35 点 | +20 点 |\n| 分析 13~16 项皮肤问题 | 16 | 22 | +40 点 | +25 点 |\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\n## 使用场景\n\n**Base URL：** `https://yce-api-01.makeupar.com`\n**分析接口：** `POST /s2s/v2.1/task/skin-analysis`\n**鉴权：** `Authorization: Bearer YOUR_API_KEY` —— 请注意 `Bearer` 与密钥之间只有一个空格。\n\n```bash\nexport API_KEY=\"your-api-key\"\nexport BASE_URL=\"https://yce-api-01.makeupar.com\"\n```\n\n每种使用场景各自对应一个接口，按您需要哪些加购能力来选择：\n\n| 模式 | `advanced_report` | `product_recommendation` | `llm_results.json` 里能拿到什么 |\n|---|---|---|---|\n| **[AI 肤质分析（标准）](/reference/ai_skin_analysis/standard-analysis/endpoint-overview)** | 不传 | 不传 | 各检测维度的皮肤问题评分 |\n| **[AI 肤质分析 + 高级测肤报告](/reference/ai_skin_analysis/analysis-+-advanced-report/endpoint-overview)** | 传入 | 不传 | 评分，外加一份讲成因与护理建议的个性化报告 |\n| **[AI 肤质分析 + 商品推荐](/reference/ai_skin_analysis/analysis-+-product-recommendation/endpoint-overview)** | 不传 | 传入 | 评分，外加从您的商品目录里匹配出的商品 |\n| **[AI 肤质分析 + 高级测肤报告 + 商品推荐](/reference/ai_skin_analysis/analysis-+-report-+-recommendation/endpoint-overview)** | 传入 | 传入 | 一次调用同时拿到评分、报告与商品匹配结果 |\n\n> **说明：** 带加购能力的模式会在基础点数之外产生额外的点数消耗。详情请见 [点数消耗](/reference/ai_skin_analysis/section/overview/unit-consumption)。\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": "Standard Analysis",
      "description": "## 接口总览\n\n**这是什么。** 标准 AI 肤质分析针对您选定的皮肤问题给出客观、量化的评分，并附上精准的检测蒙版与热力图。 \n\n依托先进的 AI 深度学习与面部区域分割技术，Perfect Corp AI 肤质分析无需物理接触，即可从数字图片中评估可见的皮肤状况。方案会输出量化评分、检测蒙版、热力图与 AR 叠加效果，用个性化的护肤洞察帮助用户更了解自己的皮肤，并据此定制属于每个人的护肤流程。\n\n* 支持的皮肤问题包括：\n\n  * 皱纹\n  * 水润度\n  * 紧致度\n  * 上睑下垂\n  * 下睑下垂\n  * 毛孔\n  * 纹理\n  * 痘痘\n  * 出油\n  * 色斑\n  * 黑眼圈\n  * 光泽度\n  * 泛红\n  * 眼袋\n  * 泪沟\n\n此外还会输出肤质、预估肌肤年龄与整体肌肤状况评分。所有结果都是基于图片的指标，仅供护肤参考，不构成临床测量、诊断或医学评估。\n\n\n* 创建 AI 任务\n\n```bash\n# Standard Skin Analysis V2.1\ncurl -sS -X POST \"$BASE_URL/s2s/v2.1/task/skin-analysis\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"src_file_url\": \"https://your-cdn.example.com/customer-001.jpg\",\n    \"dst_actions\": [\"hd_wrinkle\", \"hd_pore\", \"hd_texture\", \"hd_acne\"],\n    \"format\": \"zip\",\n    \"pf_camera_kit\": true\n  }'\n```\n\n---\n\n* 轮询获取报告与推荐\n\n每次调用都会立刻返回一个 `BasicRunTaskResponseV2`。用返回的 id 轮询任务即可；报告与推荐结果都在 **`llm_results.json`** 里。\n\n```bash\n# 1. Run the task and capture the task id\nTASK_ID=$(curl -sS -X POST \"$BASE_URL/s2s/v2.1/task/skin-analysis\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ ... }' | jq -r '.data.task_id')\n\n# 2. Poll until task_status is \"success\"\ncurl -sS -H \"Authorization: Bearer $API_KEY\" \\\n  \"$BASE_URL/s2s/v2.1/task/skin-analysis/$TASK_ID\"\n```\n\n`task_status` 会从 `running` 走到 `success` | `error`。用 `format: zip` 时，`results.url` 是一条有效期为 **2 小时**的下载链接，ZIP 里有 `skinanalysisResult` 目录，内含 `score_info.json` 和所有检测结果图片。用 `format: json` 时，`results.output` 会把评分直接写在响应体里。\n\n---\n\n* 请求字段速查\n\n| 字段 | 必填 | 说明 |\n|---|---|---|\n| `src_file_id` / `src_file_url` | 是（二选一） | 输入图片，规则同 `BasicRunTaskV2` |\n| `dst_actions` | **是** | 要么全是 HD 项目，**要么**全是 SD 项目——不能混用 |\n| `format` | 否 | `zip`（默认）\\| `json`——两者的响应结构不同 |\n| `pf_camera_kit` | 否 | V2.1 新增；脸部轮廓与五官定位 |\n| `miniserver_args` | 否 | 蒙版叠加，以及 HD 毛孔／皱纹的底图控制项 |\n| `advanced_report` | 否 | 传了就出报告；`{}` 表示全部用默认值；不传就没有报告 |\n| `product_recommendation` | 否 | 传了就出推荐；需要 `catalog_id` |\n\n**分辨率。** 所有输出图片的长边都限制在 **2560 px** 以内，输入图片会自动缩放。若 `enable_mask_overlay` 为 `false`，您拿到的是原始蒙版 `.png`，需要自行合成——请先确认输入图片的分辨率，长边超过 2560 px 时，按 2560 px 来规划您的显示尺寸。\n\n---\n"
    },
    {
      "name": "Analysis + Advanced Report",
      "description": "## 接口总览\n\n**这是什么。** 一份覆盖全维度的皮肤报告，用自然语言写成，由大语言模型生成——喂给模型的是您的**精准 AI 肤质分析结果**，再加上一座**专业护肤参考数据库**。模型不会凭空猜测您的皮肤：它解读的是实测出来的、量化的皮肤指标与真实的检测蒙版，把它们同专业护肤数据逐一对照，最后在 `llm_results.json` 里返回一份完整的报告。\n\n**报告的各个维度分别由哪些 `dst_actions` 支撑。** 您请求的分析项目决定了报告能有多丰富。`dst_actions` 是必填项，而且**同一个请求里 HD 与 SD 项目不能混用**——只能选其中一类。\n\n| 报告维度 | V2.1 项目 | 返回的区域 |\n|---|---|---|\n| 脸部轮廓与五官定位 | `pf_camera_kit: true` | — |\n| 肤质 | `hd_skin_type` | `whole`, `t_zone`, `u_zone` |\n| T 区与 U 区对比 | `hd_skin_type` | `t_zone`, `u_zone` |\n| 额头纹与眉间纹 | `hd_wrinkle` | `forehead`, `glabellar` |\n| 眼角纹与法令纹 | `hd_wrinkle` | `crowfeet`, `nasolabial` |\n| 毛孔分布 | `hd_pore` | `forehead`, `nose`, `cheek`, `whole` |\n| 肌肤平滑度 | `hd_texture` | `whole` |\n\n**参数**\n\n| 字段 | 类型 | 默认值 | 说明 |\n|---|---|---|---|\n| `language` | string enum | `enu` | `enu` `cht` `jpn` `kor` `fra` `deu` `esn` `ita` `ptb` `ind` `ara` |\n| `tone` | string enum | `warm` | `warm` \\| `direct`——两种语气都保持专业 |\n| `country` | string | — | 为报告加入气候与季节背景 |\n| `city` | string | — | 为报告加入气候与季节背景 |\n\n传 `\"advanced_report\": {}` 就全部采用默认值；整个对象都不传，就没有报告。\n\n\n* 创建 AI 任务\n\n```bash\n# Skin Analysis with Advanced Skin Report\ncurl -sS -X POST \"$BASE_URL/s2s/v2.1/task/skin-analysis-report\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"src_file_url\": \"https://your-cdn.example.com/customer-001.jpg\",\n    \"dst_actions\": [\"hd_skin_type\", \"hd_wrinkle\", \"hd_pore\", \"hd_texture\"],\n    \"format\": \"zip\",\n    \"pf_camera_kit\": true,\n    \"advanced_report\": {\n      \"language\": \"cht\",\n      \"tone\": \"direct\",\n      \"country\": \"Taiwan\",\n      \"city\": \"Taipei\"\n    }\n  }'\n```\n\n```bash\n# Same call, every report default (enu / warm, no climate context)\ncurl -sS -X POST \"$BASE_URL/s2s/v2.1/task/skin-analysis-report\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"src_file_id\": \"your-uploaded-file-id\",\n    \"dst_actions\": [\"hd_skin_type\", \"hd_wrinkle\", \"hd_pore\", \"hd_texture\"],\n    \"pf_camera_kit\": true,\n    \"advanced_report\": {}\n  }'\n```\n\n---\n\n* 轮询获取报告与推荐\n\n每次调用都会立刻返回一个 `BasicRunTaskResponseV2`。用返回的 id 轮询任务即可；报告与推荐结果都在 **`llm_results.json`** 里。\n\n```bash\n# 1. Run the task and capture the task id\nTASK_ID=$(curl -sS -X POST \"$BASE_URL/s2s/v2.1/task/skin-analysis-report\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ ... }' | jq -r '.data.task_id')\n\n# 2. Poll until task_status is \"success\"\ncurl -sS -H \"Authorization: Bearer $API_KEY\" \\\n  \"$BASE_URL/s2s/v2.1/task/skin-analysis-report/$TASK_ID\"\n```\n\n`task_status` 会从 `running` 走到 `success` | `error`。用 `format: zip` 时，`results.url` 是一条有效期为 **2 小时**的下载链接，ZIP 里有 `skinanalysisResult` 目录，内含 `score_info.json` 和所有检测结果图片。用 `format: json` 时，`results.output` 会把评分直接写在响应体里。\n\n---\n\n* 请求字段速查\n\n| 字段 | 必填 | 说明 |\n|---|---|---|\n| `src_file_id` / `src_file_url` | 是（二选一） | 输入图片，规则见 `BasicRunTaskV2` |\n| `dst_actions` | **是** | 要么全是 HD 项目，**要么**全是 SD 项目——不能混用 |\n| `format` | 否 | `zip`（默认）\\| `json`——两者的响应结构不同 |\n| `pf_camera_kit` | 否 | V2.1 新增；脸部轮廓与五官定位 |\n| `miniserver_args` | 否 | 蒙版叠加，以及 HD 毛孔／皱纹的底图控制项 |\n| `advanced_report` | 否 | 传了就出报告；`{}` 表示全部用默认值；不传就没有报告 |\n| `product_recommendation` | 否 | 传了就出推荐；需要 `catalog_id` |\n\n**分辨率。** 所有输出图片的长边都限制在 **2560 px** 以内，输入图片会自动缩放。若 `enable_mask_overlay` 为 `false`，您拿到的是原始蒙版 `.png`，需要自行合成——请先确认输入图片的分辨率，长边超过 2560 px 时，按 2560 px 来规划您的显示尺寸。\n\n---\n"
    },
    {
      "name": "Analysis + Product Recommendation",
      "description": "## 接口总览\n\n**这是什么。** 把您的商品目录交给一次精准的肤质分析来做匹配。上传您在售的护肤商品及其描述，调用时传入目录 id，接口就会在 `llm_results.json` 里为每一项检测出的皮肤问题返回匹配度最高的商品。\n\n它与通用大模型推荐的区别在于输入。通用大模型靠概率和先验来推荐；Perfect AI 肤质分析先产出**科学、量化的皮肤指标与真实的检测蒙版**，模型再把商品同实测出的皮肤状况一一对照——可靠、快速、说得清理由，而不是统计意义上的猜测。\n\n**参数**\n\n| 字段 | 类型 | 必填 | 默认值 | 说明 |\n|---|---|---|---|---|\n| `catalog_id` | string | **是** | — | 来自「上传商品目录」。目录必须处于 `ready` 状态，且属于您的账号。 |\n| `top_n` | integer | 否 | `3` | 每一**类**皮肤问题要推荐的商品数。最小 `1`；不能超过目录的 `sku_count`。 |\n\n\n* 前置准备——上传您的商品目录\n\n商品目录就是肤质分析做推荐时使用的那份商品清单。上传一次，记下它的 `catalog_id`，之后每次测肤都传入这个 id。目录归属于您的**账号**，不属于某一个 API 密钥——账号下的每个密钥（包括项目密钥）看到的都是同一批目录，轮换密钥或删除密钥都不会影响它们。上传与存储目录完全免费。\n\n**目录文件要求**\n\n| 项目 | 取值 |\n|---|---|\n| 格式 | 带表头行的 CSV |\n| 编码 | UTF-8，带或不带 BOM 皆可（Excel 的\"CSV UTF-8\"会带上 BOM） |\n| 文件大小上限 | 5 MB |\n| SKU 数量上限 | 除文件大小外没有限制 |\n| 必填栏位 | `product_id`、`product_name`、`product_description` |\n\n其他栏位会被忽略，但仍计入 5 MB 的大小限制。取值中包含逗号或换行时，必须按标准 CSV 的规则加引号。每一行非空的数据行算作一个 SKU。\n\n```csv\nproduct_id,product_name,product_description\nSKU-001,Hydrating Serum,\"A lightweight serum for dry skin.\"\nSKU-002,Brightening Cream,\"Evens out skin tone, for daily use.\"\nSKU-003,Barrier Repair Cream,\"Rich cream for dry, redness-prone skin.\"\n```\n\n```bash\n# Upload a catalog — validated in the same request\ncurl -sS -X POST \"$BASE_URL/s2s/v2.1/product-catalog\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -F \"file=@catalog.csv\" \\\n  -F \"name=Summer skincare\"\n```\n\n文件校验通过时，响应会给出 `status: ready`，并带上它的 `catalog_id` 与 `sku_count`——请务必记下这个 id：\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"catalog_id\": \"1662043585118399001\",\n    \"name\": \"Summer skincare\",\n    \"status\": \"ready\",\n    \"created_time\": 1760256000000,\n    \"sku_count\": 3\n  }\n}\n```\n\n```bash\n# List every catalog of your account, newest first (ready and failed alike)\ncurl -sS -H \"Authorization: Bearer $API_KEY\" \"$BASE_URL/s2s/v2.1/product-catalog\"\n\n# Delete a catalog — immediate and permanent\ncurl -sS -X DELETE -H \"Authorization: Bearer $API_KEY\" \\\n  \"$BASE_URL/s2s/v2.1/product-catalog/1662043585118399001\"\n```\n\n**目录状态与限制**\n\n| 状态 | 含义 | 可用于测肤 |\n|---|---|---|\n| `ready` | 已上传并通过校验 | 可以 |\n| `failed` | 已上传，但文件未通过校验 | 不可以 |\n\n未通过校验的上传会返回错误，同时**仍会被记录成一个 `failed` 目录**，在「列出目录」里能看到它；错误响应体中不会带上它的 `catalog_id`。每个账号最多保留 **10 个目录**，`ready` 与 `failed` 合并计算——要先删掉一个，才能上传新的。更新目录的做法是上传一份新文件：每次上传都会产生一个新的 `catalog_id`，旧目录在您删除之前一直可用，因此可以先确认新目录没问题再切换。\n\n---\n\n* 创建 AI 任务\n\n```bash\n# Skin Analysis with Product Recommendation\ncurl -sS -X POST \"$BASE_URL/s2s/v2.1/task/skin-analysis-recommendation\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"src_file_url\": \"https://your-cdn.example.com/customer-001.jpg\",\n    \"dst_actions\": [\n      \"hd_skin_type\", \"hd_wrinkle\", \"hd_pore\", \"hd_texture\",\n      \"hd_acne\", \"hd_redness\", \"hd_oiliness\", \"hd_moisture\",\n      \"hd_age_spot\", \"hd_radiance\", \"hd_dark_circle\"\n    ],\n    \"format\": \"zip\",\n    \"pf_camera_kit\": true,\n    \"product_recommendation\": {\n      \"catalog_id\": \"1662043585118399001\",\n      \"top_n\": 3\n    }\n  }'\n```\n\n**校验。** 下面这些情况都会返回 `400` 和 `error_code: InvalidParameters`，并且**不会扣点数**：\n\n| 触发原因 | `error` 错误信息 |\n|---|---|\n| 传了 `product_recommendation` 却没有 `catalog_id` | `catalog_id is required when product_recommendation is provided.` |\n| 目录不存在、已被删除，或属于其他账号 | `No catalog was found with this catalog_id.` |\n| 目录上传时未通过校验（`status: failed`） | `This catalog failed validation when it was uploaded and can't be used. Upload the catalog again.` |\n| `top_n` 不是大于等于 1 的整数 | *（常见的 `InvalidParameters` 情形）* |\n| `top_n` 超过目录里的商品数 | `product_recommendation.top_n can't be more than the 3 products in this catalog.` |\n\n最后一条信息是动态生成的——它会报出目录真实的 `sku_count`。请从「列出目录」读取 `sku_count`，在客户端把 `top_n` 收敛到它的范围内。\n\n---\n\n* 轮询获取报告与推荐\n\n每次调用都会立刻返回一个 `BasicRunTaskResponseV2`。用返回的 id 轮询任务即可；报告与推荐结果都在 **`llm_results.json`** 里。\n\n```bash\n# 1. Run the task and capture the task id\nTASK_ID=$(curl -sS -X POST \"$BASE_URL/s2s/v2.1/task/skin-analysis-recommendation\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ ... }' | jq -r '.data.task_id')\n\n# 2. Poll until task_status is \"success\"\ncurl -sS -H \"Authorization: Bearer $API_KEY\" \\\n  \"$BASE_URL/s2s/v2.1/task/skin-analysis-recommendation/$TASK_ID\"\n```\n\n`task_status` 会从 `running` 走到 `success` | `error`。用 `format: zip` 时，`results.url` 是一条有效期为 **2 小时**的下载链接，ZIP 里有 `skinanalysisResult` 目录，内含 `score_info.json` 和所有检测结果图片。用 `format: json` 时，`results.output` 会把评分直接写在响应体里。\n\n---\n\n* 请求字段速查\n\n| 字段 | 必填 | 说明 |\n|---|---|---|\n| `src_file_id` / `src_file_url` | 是（二选一） | 输入图片，规则见 `BasicRunTaskV2` |\n| `dst_actions` | **是** | 要么全是 HD 项目，**要么**全是 SD 项目——不能混用 |\n| `format` | 否 | `zip`（默认）\\| `json`——两者的响应结构不同 |\n| `pf_camera_kit` | 否 | V2.1 新增；脸部轮廓与五官定位 |\n| `miniserver_args` | 否 | 蒙版叠加，以及 HD 毛孔／皱纹的底图控制项 |\n| `advanced_report` | 否 | 传了就出报告；`{}` 表示全部用默认值；不传就没有报告 |\n| `product_recommendation` | 否 | 传了就出推荐；需要 `catalog_id` |\n\n**分辨率。** 所有输出图片的长边都限制在 **2560 px** 以内，输入图片会自动缩放。若 `enable_mask_overlay` 为 `false`，您拿到的是原始蒙版 `.png`，需要自行合成——请先确认输入图片的分辨率，长边超过 2560 px 时，按 2560 px 来规划您的显示尺寸。\n\n---\n"
    },
    {
      "name": "Analysis + Report + Recommendation",
      "description": "## 接口总览\n\n**这是什么。** 一次调用同时拿到「AI 肤质分析 + 高级测肤报告 + 商品推荐」。您会得到那份精准报告——它建立在实测皮肤指标与专业护肤参考数据库之上——**再加上**完全从您自家商品里给出的推荐，只需一个请求、一次轮询流程。\n\n一个接口调用就把整个闭环走完：既有科学、高度可靠、精准的肤质分析报告，又有完全基于您的商品目录的商品推荐。商品曝光与用户黏性一次兼顾，用户体验从头到尾不断档。\n\n* 前置准备——上传您的商品目录\n\n商品目录就是肤质分析做推荐时使用的那份商品清单。上传一次，记下它的 `catalog_id`，之后每次测肤都传入这个 id。目录归属于您的**账号**，不属于某一个 API 密钥——账号下的每个密钥（包括项目密钥）看到的都是同一批目录，轮换密钥或删除密钥都不会影响它们。上传与存储目录完全免费。\n\n**目录文件要求**\n\n| 项目 | 取值 |\n|---|---|\n| 格式 | 带表头行的 CSV |\n| 编码 | UTF-8，带或不带 BOM 皆可（Excel 的\"CSV UTF-8\"会带上 BOM） |\n| 文件大小上限 | 5 MB |\n| SKU 数量上限 | 除文件大小外没有限制 |\n| 必填栏位 | `product_id`、`product_name`、`product_description` |\n\n其他栏位会被忽略，但仍计入 5 MB 的大小限制。取值中包含逗号或换行时，必须按标准 CSV 的规则加引号。每一行非空的数据行算作一个 SKU。\n\n```csv\nproduct_id,product_name,product_description\nSKU-001,Hydrating Serum,\"A lightweight serum for dry skin.\"\nSKU-002,Brightening Cream,\"Evens out skin tone, for daily use.\"\nSKU-003,Barrier Repair Cream,\"Rich cream for dry, redness-prone skin.\"\n```\n\n```bash\n# Upload a catalog — validated in the same request\ncurl -sS -X POST \"$BASE_URL/s2s/v2.1/product-catalog\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -F \"file=@catalog.csv\" \\\n  -F \"name=Summer skincare\"\n```\n\n文件校验通过时，响应会给出 `status: ready`，并带上它的 `catalog_id` 与 `sku_count`——请务必记下这个 id：\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"catalog_id\": \"1662043585118399001\",\n    \"name\": \"Summer skincare\",\n    \"status\": \"ready\",\n    \"created_time\": 1760256000000,\n    \"sku_count\": 3\n  }\n}\n```\n\n```bash\n# List every catalog of your account, newest first (ready and failed alike)\ncurl -sS -H \"Authorization: Bearer $API_KEY\" \"$BASE_URL/s2s/v2.1/product-catalog\"\n\n# Delete a catalog — immediate and permanent\ncurl -sS -X DELETE -H \"Authorization: Bearer $API_KEY\" \\\n  \"$BASE_URL/s2s/v2.1/product-catalog/1662043585118399001\"\n```\n\n**目录状态与限制**\n\n| 状态 | 含义 | 可用于测肤 |\n|---|---|---|\n| `ready` | 已上传并通过校验 | 可以 |\n| `failed` | 已上传，但文件未通过校验 | 不可以 |\n\n未通过校验的上传会返回错误，同时**仍会被记录成一个 `failed` 目录**，在「列出目录」里能看到它；错误响应体中不会带上它的 `catalog_id`。每个账号最多保留 **10 个目录**，`ready` 与 `failed` 合并计算——要先删掉一个，才能上传新的。更新目录的做法是上传一份新文件：每次上传都会产生一个新的 `catalog_id`，旧目录在您删除之前一直可用，因此可以先确认新目录没问题再切换。\n\n---\n\n* 创建 AI 任务\n\n```bash\n# Skin Intel System — Report + Recommendations\ncurl -sS -X POST \"$BASE_URL/s2s/v2.1/task/skin-analysis-report-recommendation\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"src_file_url\": \"https://your-cdn.example.com/customer-001.jpg\",\n    \"dst_actions\": [\n      \"hd_skin_type\", \"hd_wrinkle\", \"hd_pore\", \"hd_texture\",\n      \"hd_acne\", \"hd_redness\", \"hd_oiliness\", \"hd_moisture\",\n      \"hd_age_spot\", \"hd_radiance\", \"hd_dark_circle\", \"hd_firmness\",\n      \"hd_eye_bag\", \"hd_tear_trough\", \"hd_droopy_upper_eyelid\",\n      \"hd_droopy_lower_eyelid\"\n    ],\n    \"format\": \"zip\",\n    \"pf_camera_kit\": true,\n    \"miniserver_args\": {\n      \"enable_mask_overlay\": true\n    },\n    \"advanced_report\": {\n      \"language\": \"enu\",\n      \"tone\": \"warm\",\n      \"country\": \"United States\",\n      \"city\": \"New York\"\n    },\n    \"product_recommendation\": {\n      \"catalog_id\": \"1662043585118399001\",\n      \"top_n\": 3\n    }\n  }'\n```\n\n---\n\n* 轮询获取报告与推荐\n\n每次调用都会立刻返回一个 `BasicRunTaskResponseV2`。用返回的 id 轮询任务即可；报告与推荐结果都在 **`llm_results.json`** 里。\n\n```bash\n# 1. Run the task and capture the task id\nTASK_ID=$(curl -sS -X POST \"$BASE_URL/s2s/v2.1/task/skin-analysis-report-recommendation\" \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ ... }' | jq -r '.data.task_id')\n\n# 2. Poll until task_status is \"success\"\ncurl -sS -H \"Authorization: Bearer $API_KEY\" \\\n  \"$BASE_URL/s2s/v2.1/task/skin-analysis-report-recommendation/$TASK_ID\"\n```\n\n`task_status` 会从 `running` 走到 `success` | `error`。用 `format: zip` 时，`results.url` 是一条有效期为 **2 小时**的下载链接，ZIP 里有 `skinanalysisResult` 目录，内含 `score_info.json` 和所有检测结果图片。用 `format: json` 时，`results.output` 会把评分直接写在响应体里。\n\n---\n\n* 请求字段速查\n\n| 字段 | 必填 | 说明 |\n|---|---|---|\n| `src_file_id` / `src_file_url` | 是（二选一） | 输入图片，规则同 `BasicRunTaskV2` |\n| `dst_actions` | **是** | 要么全是 HD 项目，**要么**全是 SD 项目——不能混用 |\n| `format` | 否 | `zip`（默认）\\| `json`——两者的响应结构不同 |\n| `pf_camera_kit` | 否 | V2.1 新增；脸部轮廓与五官定位 |\n| `miniserver_args` | 否 | 蒙版叠加，以及 HD 毛孔／皱纹的底图控制项 |\n| `advanced_report` | 否 | 传了就出报告；`{}` 表示全部用默认值；不传就没有报告 |\n| `product_recommendation` | 否 | 传了就出推荐；需要 `catalog_id` |\n\n**分辨率。** 所有输出图片的长边都限制在 **2560 px** 以内，输入图片会自动缩放。若 `enable_mask_overlay` 为 `false`，您拿到的是原始蒙版 `.png`，需要自行合成——请先确认输入图片的分辨率，长边超过 2560 px 时，按 2560 px 来规划您的显示尺寸。\n\n---\n"
    },
    {
      "name": "Product Catalogs",
      "description": "## 接口总览\n\n商品目录就是 AI 肤质分析在做商品推荐时使用的那份商品清单。您的目录只需上传一次，\n记下它的 `catalog_id`，把这个 id 传给测肤即可。目录会一直保留，直到您删除它。\n\n目录归属于您的账号，不属于某一个 API 密钥：账号下的每个 API 密钥——包括项目密钥——\n看到的都是同一批目录；轮换密钥或删除密钥都不会影响它们。\n\n上传与存储目录完全免费。\n\n* 目录文件\n\n| 项目 | 取值 |\n|---|---|\n| 格式 | 带表头行的 CSV |\n| 编码 | UTF-8，带或不带字节顺序标记（BOM）皆可。Excel 的\"CSV UTF-8\"格式会带上 BOM。 |\n| 文件大小上限 | 5 MB |\n| SKU 数量上限 | 除文件大小外没有限制 |\n\n必填栏位：\n\n| 栏位 | 说明 |\n|---|---|\n| `product_id` | 您的商品编号 |\n| `product_name` | 商品名称 |\n| `product_description` | 商品描述 |\n\n其他栏位会被忽略，但仍计入 5 MB 的大小限制。取值中包含逗号或换行时，必须按标准 CSV 的规则\n加引号。每一行非空的数据行算作一个 SKU。\n\n示例：\n\n```csv\nproduct_id,product_name,product_description\nSKU-001,Hydrating Serum,\"A lightweight serum for dry skin.\"\nSKU-002,Brightening Cream,\"Evens out skin tone, for daily use.\"\n```\n\n* 目录状态\n\n| 状态 | 含义 | 可用于测肤 |\n|---|---|---|\n| `ready` | 已上传并通过校验 | 可以 |\n| `failed` | 已上传，但文件未通过校验 | 不可以 |\n\n未通过校验的上传会返回错误，同时仍会记录为一个 `failed` 目录，\"列出目录\"接口\n会把它列出来。删除它和删除其他目录一样操作。\n\n* 限制\n\n每个账号最多可保留 10 个目录，`ready` 与 `failed` 合并计算。要先删除一个目录，才能上传新的。\n\n更新目录的做法是上传一份新文件：每次上传都会产生一个新的 `catalog_id`，旧目录会一直可用，\n直到您删除它，因此您可以先确认新目录没问题再切换。\n\n* 删除\n\n删除目录立即生效且不可撤销。从那一刻起，所有使用该 `catalog_id` 的测肤调用都会失败。\n已删除的目录无法恢复；重新上传同一个文件，\n会创建一个全新的目录、对应一个新的 `catalog_id`。\n"
    }
  ],
  "paths": {
    "/s2s/v2.1/task/skin-analysis": {
      "post": {
        "summary": "执行 AI 肤质分析（V2.1） 任务。",
        "x-display-name": "AI Skin Analysis",
        "x-engine-version": "V2.1",
        "description": "AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 `success` 或 `error` 通知后，用收到的 `task_id` 查询任务结果。配置与校验的细节请见 [Webhook 接入指南](/develop/webhook.md)。\n\n若功能不支持 Webhook，或您的接入方式用不了 Webhook，就请实现轮询。提交 AI 任务后，按固定间隔（例如每 10 秒）轮询状态接口，直到任务状态变为 `success` 或 `error`。\n",
        "tags": [
          "Standard Analysis"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/RunSkincareTaskV2"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "pf_camera_kit": {
                        "type": "boolean",
                        "example": true
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "AI 肤质分析任务执行成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BasicRunTaskResponseV2"
                }
              }
            }
          },
          "400": {
            "description": "任务执行失败。除常见情况外，请求若带了 `advanced_report` 或 `product_recommendation`，会返回 `InvalidParameters`，且不扣点数。需要这两项时，请改用 skin-analysis-report、skin-analysis-recommendation 或 skin-analysis-report-recommendation 接口。\n",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/RunError"
                    }
                  ]
                },
                "examples": {
                  "advanced_report_not_supported": {
                    "summary": "本接口收到了 advanced_report",
                    "value": {
                      "status": 400,
                      "error": "advanced_report is not supported by this endpoint.",
                      "error_code": "InvalidParameters"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/s2s/v2.1/task/skin-analysis/{task_id}": {
      "get": {
        "summary": "查询 AI 肤质分析（V2.1） 任务的状态。",
        "x-display-name": "AI Skin Analysis",
        "x-engine-version": "V2.1",
        "tags": [
          "Standard Analysis"
        ],
        "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"
          }
        }
      }
    },
    "/s2s/v2.1/task/skin-analysis-report": {
      "post": {
        "summary": "执行「肤质分析 + 高级测肤报告」任务。",
        "x-display-name": "AI Skin Analysis",
        "x-engine-version": "V2.1",
        "description": "AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 `success` 或 `error` 通知后，用收到的 `task_id` 查询任务结果。配置与校验的细节请见 [Webhook 接入指南](/develop/webhook.md)。\n\n若功能不支持 Webhook，或您的接入方式用不了 Webhook，就请实现轮询。提交 AI 任务后，按固定间隔（例如每 10 秒）轮询状态接口，直到任务状态变为 `success` 或 `error`。\n",
        "tags": [
          "Analysis + Advanced Report"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/RunSkincareTaskV2"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "pf_camera_kit": {
                        "type": "boolean",
                        "example": true
                      },
                      "advanced_report": {
                        "$ref": "#/components/schemas/SkinAnalysisAdvancedReport"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "「肤质分析 + 高级测肤报告」任务执行成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BasicRunTaskResponseV2"
                }
              }
            }
          },
          "400": {
            "description": "任务执行失败。除常见情况外，请求若带了 `product_recommendation`，会返回 `InvalidParameters`，且不扣点数。\n",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/RunError"
                    }
                  ]
                },
                "examples": {
                  "product_recommendation_not_supported": {
                    "summary": "本接口收到了 product_recommendation",
                    "value": {
                      "status": 400,
                      "error": "product_recommendation is not supported by this endpoint.",
                      "error_code": "InvalidParameters"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/s2s/v2.1/task/skin-analysis-report/{task_id}": {
      "get": {
        "summary": "查询「肤质分析 + 高级测肤报告」任务的状态。",
        "x-display-name": "AI Skin Analysis",
        "x-engine-version": "V2.1",
        "tags": [
          "Analysis + Advanced Report"
        ],
        "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"
          }
        }
      }
    },
    "/s2s/v2.1/task/skin-analysis-recommendation": {
      "post": {
        "summary": "执行「肤质分析 + 商品推荐」任务。",
        "x-display-name": "AI Skin Analysis",
        "x-engine-version": "V2.1",
        "description": "AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 `success` 或 `error` 通知后，用收到的 `task_id` 查询任务结果。配置与校验的细节请见 [Webhook 接入指南](/develop/webhook.md)。\n\n若功能不支持 Webhook，或您的接入方式用不了 Webhook，就请实现轮询。提交 AI 任务后，按固定间隔（例如每 10 秒）轮询状态接口，直到任务状态变为 `success` 或 `error`。\n",
        "tags": [
          "Analysis + Product Recommendation"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/RunSkincareTaskV2"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "pf_camera_kit": {
                        "type": "boolean",
                        "example": true
                      },
                      "product_recommendation": {
                        "$ref": "#/components/schemas/SkinAnalysisProductRecommendation"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "「肤质分析 + 商品推荐」任务执行成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BasicRunTaskResponseV2"
                }
              }
            }
          },
          "400": {
            "description": "任务执行失败。除常见情况外，出现下列情况时请求会返回 `InvalidParameters`，且不扣点数：\n* 未提供 `product_recommendation`\n* 带了 `advanced_report`\n* 提供了 `product_recommendation` 却没有 `catalog_id`\n* `product_recommendation.catalog_id` 不存在、已被删除，或属于其他账号\n* `product_recommendation.catalog_id` 指向的目录在上传时未通过校验\n* `product_recommendation.top_n` 不是不小于 1 的整数\n* `product_recommendation.top_n` 大于目录中的商品数量\n",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/RunError"
                    }
                  ]
                },
                "examples": {
                  "product_recommendation_required": {
                    "summary": "缺少 product_recommendation",
                    "value": {
                      "status": 400,
                      "error": "product_recommendation is required for this endpoint.",
                      "error_code": "InvalidParameters"
                    }
                  },
                  "advanced_report_not_supported": {
                    "summary": "本接口收到了 advanced_report",
                    "value": {
                      "status": 400,
                      "error": "advanced_report is not supported by this endpoint.",
                      "error_code": "InvalidParameters"
                    }
                  },
                  "catalog_id_required": {
                    "summary": "product_recommendation 没有 catalog_id",
                    "value": {
                      "status": 400,
                      "error": "catalog_id is required when product_recommendation is provided.",
                      "error_code": "InvalidParameters"
                    }
                  },
                  "catalog_not_found": {
                    "summary": "找不到该 catalog_id",
                    "value": {
                      "status": 400,
                      "error": "No catalog was found with this catalog_id.",
                      "error_code": "InvalidParameters"
                    }
                  },
                  "catalog_not_ready": {
                    "summary": "catalog_id 指向一个校验失败的目录",
                    "value": {
                      "status": 400,
                      "error": "This catalog failed validation when it was uploaded and can't be used. Upload the catalog again.",
                      "error_code": "InvalidParameters"
                    }
                  },
                  "top_n_exceeds_sku_count": {
                    "summary": "top_n 超过目录中的商品数量",
                    "value": {
                      "status": 400,
                      "error": "product_recommendation.top_n can't be more than the 3 products in this catalog.",
                      "error_code": "InvalidParameters"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/s2s/v2.1/task/skin-analysis-recommendation/{task_id}": {
      "get": {
        "summary": "查询「肤质分析 + 商品推荐」任务的状态。",
        "x-display-name": "AI Skin Analysis",
        "x-engine-version": "V2.1",
        "tags": [
          "Analysis + Product Recommendation"
        ],
        "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"
          }
        }
      }
    },
    "/s2s/v2.1/task/skin-analysis-report-recommendation": {
      "post": {
        "summary": "执行「肤质分析 + 高级测肤报告 + 商品推荐」任务。",
        "x-display-name": "AI Skin Analysis",
        "x-engine-version": "V2.1",
        "description": "AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 `success` 或 `error` 通知后，用收到的 `task_id` 查询任务结果。配置与校验的细节请见 [Webhook 接入指南](/develop/webhook.md)。\n\n若功能不支持 Webhook，或您的接入方式用不了 Webhook，就请实现轮询。提交 AI 任务后，按固定间隔（例如每 10 秒）轮询状态接口，直到任务状态变为 `success` 或 `error`。\n",
        "tags": [
          "Analysis + Report + Recommendation"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/RunSkincareTaskV2"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "pf_camera_kit": {
                        "type": "boolean",
                        "example": true
                      },
                      "advanced_report": {
                        "$ref": "#/components/schemas/SkinAnalysisAdvancedReport"
                      },
                      "product_recommendation": {
                        "$ref": "#/components/schemas/SkinAnalysisProductRecommendation"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "「肤质分析 + 高级测肤报告 + 商品推荐」任务执行成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BasicRunTaskResponseV2"
                }
              }
            }
          },
          "400": {
            "description": "任务执行失败。除常见情况外，出现下列情况时请求会返回 `InvalidParameters`，且不扣点数：\n* 未提供 `product_recommendation`\n* 提供了 `product_recommendation` 却没有 `catalog_id`\n* `product_recommendation.catalog_id` 不存在、已被删除，或属于其他账号\n* `product_recommendation.catalog_id` 指向的目录在上传时未通过校验\n* `product_recommendation.top_n` 不是不小于 1 的整数\n* `product_recommendation.top_n` 大于目录中的商品数量\n",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/RunError"
                    }
                  ]
                },
                "examples": {
                  "product_recommendation_required": {
                    "summary": "缺少 product_recommendation",
                    "value": {
                      "status": 400,
                      "error": "product_recommendation is required for this endpoint.",
                      "error_code": "InvalidParameters"
                    }
                  },
                  "catalog_id_required": {
                    "summary": "product_recommendation 没有 catalog_id",
                    "value": {
                      "status": 400,
                      "error": "catalog_id is required when product_recommendation is provided.",
                      "error_code": "InvalidParameters"
                    }
                  },
                  "catalog_not_found": {
                    "summary": "找不到该 catalog_id",
                    "value": {
                      "status": 400,
                      "error": "No catalog was found with this catalog_id.",
                      "error_code": "InvalidParameters"
                    }
                  },
                  "catalog_not_ready": {
                    "summary": "catalog_id 指向一个校验失败的目录",
                    "value": {
                      "status": 400,
                      "error": "This catalog failed validation when it was uploaded and can't be used. Upload the catalog again.",
                      "error_code": "InvalidParameters"
                    }
                  },
                  "top_n_exceeds_sku_count": {
                    "summary": "top_n 超过目录中的商品数量",
                    "value": {
                      "status": 400,
                      "error": "product_recommendation.top_n can't be more than the 3 products in this catalog.",
                      "error_code": "InvalidParameters"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/s2s/v2.1/task/skin-analysis-report-recommendation/{task_id}": {
      "get": {
        "summary": "查询「肤质分析 + 高级测肤报告 + 商品推荐」任务的状态。",
        "x-display-name": "AI Skin Analysis",
        "x-engine-version": "V2.1",
        "tags": [
          "Analysis + Report + Recommendation"
        ],
        "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"
          }
        }
      }
    },
    "/s2s/v2.1/product-catalog": {
      "post": {
        "summary": "上传商品目录。",
        "description": "以 CSV 文件上传商品目录。文件会在同一次请求中完成校验：校验通过的文件返回 `status` `ready`，并带上它的 `catalog_id` 与 `sku_count`；未通过校验的文件返回错误，同时仍会记录为一个 `failed` 目录，「列出目录」接口会把它列出来。",
        "tags": [
          "Product Catalogs"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "example": "@catalog.csv",
                    "description": "目录文件。它的格式、编码、大小限制与必填栏位，见「商品目录」章节下的「目录文件」。"
                  },
                  "name": {
                    "type": "string",
                    "description": "您自己给目录起的名称，会显示在「列出目录」中。不传时 `name` 为 `null`。",
                    "example": "Summer skincare"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "目录已上传，可用于测肤",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "integer",
                      "description": "响应状态",
                      "example": 200
                    },
                    "data": {
                      "$ref": "#/components/schemas/ProductCatalog"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ProductCatalogUploadError"
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          }
        }
      },
      "get": {
        "summary": "列出商品目录。",
        "description": "列出您账号下的所有目录，最新的排在最前面，`ready` 与 `failed` 都会列出。手上没有了某个 `catalog_id` 时，可以用它找回来。该接口不分页：每个账号可保留的目录数量有上限（见「商品目录」章节下的「限制」）。",
        "tags": [
          "Product Catalogs"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "responses": {
          "200": {
            "description": "账号下的所有目录",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "integer",
                      "description": "响应状态",
                      "example": 200
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "catalogs": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ProductCatalog"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          }
        }
      }
    },
    "/s2s/v2.1/product-catalog/{catalog_id}": {
      "delete": {
        "summary": "删除商品目录。",
        "description": "删除目录立即生效且不可撤销。从那一刻起，所有使用该 `catalog_id` 的测肤调用都会失败。已删除的目录无法恢复。",
        "tags": [
          "Product Catalogs"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "parameters": [
          {
            "name": "catalog_id",
            "in": "path",
            "required": true,
            "description": "「上传商品目录」返回的 `catalog_id`。",
            "schema": {
              "type": "string",
              "example": "1662043585118399001"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "目录已删除",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "integer",
                      "description": "响应状态",
                      "example": 200
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "404": {
            "$ref": "#/components/responses/ProductCatalogNotFound"
          }
        }
      }
    }
  },
  "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。 <br> 所有输出图片的长边最高为 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
          }
        }
      },
      "ProductCatalog": {
        "type": "object",
        "properties": {
          "catalog_id": {
            "type": "string",
            "description": "随机生成、无法猜出的目录 ID。在测肤时传入它，即可使用这个目录。",
            "example": "1662043585118399001"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "上传时给目录起的名称；未填时为 `null`。",
            "example": "Summer skincare"
          },
          "status": {
            "type": "string",
            "enum": [
              "ready",
              "failed"
            ],
            "description": "目录状态：\n  * ready - 已上传并通过校验，可用于测肤\n  * failed - 文件未通过校验，不可使用\n"
          },
          "created_time": {
            "type": "integer",
            "format": "int64",
            "description": "上传时间，Unix 时间戳（毫秒）",
            "example": 1760256000000
          },
          "sku_count": {
            "type": "integer",
            "nullable": true,
            "description": "从文件中解析出的商品数量；`failed` 目录为 `null`。",
            "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"
              }
            }
          }
        }
      },
      "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"
          }
        }
      },
      "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"
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      },
      "ProductCatalogUploadError": {
        "description": "上传被拒绝。未通过校验的文件仍会记录为一个 `failed` 目录；错误响应体中不会带上它的 `catalog_id`。",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "integer",
                  "example": 400,
                  "description": "响应状态"
                },
                "error": {
                  "type": "string",
                  "description": "错误信息",
                  "example": "The file must be UTF-8 encoded. Detected encoding: BIG5."
                },
                "error_code": {
                  "type": "string",
                  "enum": [
                    "InvalidParameters",
                    "ExceedMaxNumOfProductCatalog"
                  ],
                  "description": "错误码：\n  * InvalidParameters - 请求或目录文件无效\n  * ExceedMaxNumOfProductCatalog - 账号已保留的目录数量已达上限\n"
                }
              }
            }
          }
        }
      },
      "ProductCatalogNotFound": {
        "description": "您的账号中不存在该 `catalog_id` 对应的目录",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "integer",
                  "example": 404,
                  "description": "响应状态"
                },
                "error": {
                  "type": "string",
                  "description": "错误信息",
                  "example": "No catalog was found with this catalog_id."
                },
                "error_code": {
                  "type": "string",
                  "enum": [
                    "NotFound"
                  ],
                  "description": "错误码：\n  * NotFound - 该 `catalog_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"
                }
              }
            }
          }
        }
      }
    }
  }
}