{
  "openapi": "3.0.0",
  "info": {
    "title": "AI 美妆虚拟试妆",
    "description": "# 概览\nAI 妆效接口提供一套强大、逼真到位的虚拟化妆体验，背后是我们取得专利的脸部分析技术。这项服务能让您的应用把真实感十足的妆效套到用户提供的自拍照上，自定义程度前所未有。\n\n**主要特性：**\n*   **逼真到位的渲染：** 采用突破性的 3D 脸部 AI 技术，做出最真实的妆容变化。\n*   **专利技术：** 由不抖动、不卡顿的深度学习算法驱动，各种年龄、各种肤色都调优到位。\n*   **即时精准：** 超精准的脸部追踪，各种光线条件下都跟得上。\n*   **还原真实：** 准确还原现实商品的色彩、质地（从哑光到金属感）与妆效呈现。\n\n* 核心概念\n\n   * 色彩混合\n我们的 AI 用深度学习准确匹配现实彩妆商品的颜色。消费者看到的虚拟颜色就是他们打算购买的商品的真实颜色，这一点可以放心。\n\n   * 质地与妆效还原\n这项技术能模拟真实的质地与妆效，带来准确度极高的上妆体验。从哑光到金属感、从珠光到缎光，AI 依靠先进算法即时把这些效果流畅渲染出来。\n\n   * 光线平衡\n智能 3D AI 引擎会检测用户照片或视频画面中的光线条件，并对图像做校正，让上妆效果贴近真实；不论什么环境，结果都稳定、高质量。\n\n---\n\n## 接入指南\n\nAI 美妆虚拟试妆服务以异步任务的方式运行。您要先提供图片 URL 与要套用的特效清单，发起妆效处理任务；服务器会响应一个 `task_id`。之后定期轮询状态接口，取回最终结果或错误信息。\n\n*   **接口地址：** `/v2.0/task/makeup-vto`\n*   **鉴权：** 所有请求都需要 `Authorization: Bearer <TOKEN>`\n*   **流程：**\n    1.  **准备自拍照：** 上传一张脸部图片，或使用已有的文件 URL。\n    1.  **发起任务（`POST`）：** 提交您的图片 id/URL 与妆效配置。\n    1.  **取得 Task ID：** 从响应中取回 `task_id`。\n    1.  **轮询状态（`GET`）：** 用 `task_id` 查看任务状态，持续轮询直到 `task_status` 为 `\"success\"` 或 `\"error\"`。\n\n\n* API Playground\n\n用官方演练场交互式地体验和测试接口：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-makeup-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-makeup-virtual-try-on/)\n\n---\n\n* 鉴权\n- 请在请求头中以 **Bearer Token** 方式带上您的 API 密钥：\n    ```\n    Authorization: Bearer <API Key>\n    ```\nAPI Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。\n\n* 1. 上传自拍照\n  源图有两种提供方式：\n\n  - **使用已有的公开图片 URL**\n    不必上传，发起 AI 任务时直接提供一个可公开访问的图片 URL 也可以。\n\n  - **通过 File 接口上传**\n    接口地址：\n    ```\n    POST /s2s/v2.0/file\n    ```\n    这会返回一个 `file_id`，供后续执行任务时使用。\n\n    - ***重要***：只调用 File 接口并不等于上传了文件。您必须**手动把文件上传到 File 接口响应中给出的那个 URL**，那个 URL 就是您的上传目标，务必确认文件已成功传过去，再继续往下做。<br></br>\n    调用 AI 接口之前，请确认文件已上传成功。先用 File 接口取到一个上传 URL，把文件上传到该位置。上传完成后，您会在响应中收到一个 ***file_id***，调用与该文件相关的 AI 功能时就用它。\n\n      > **警告：** 请注意，若未把文件上传到 File 接口响应中给出的 URL，调用 AI 接口时会得到 500 Server Error / unknown_internal_error 或 404 Not Found 错误。\n\n\n* 2. 发起妆效任务\n\n`POST /s2s/v2.0/task/makeup-vto`\n\n在指定图片上发起一次新的虚拟上妆任务。该接口为异步接口，响应会返回一个 `task_id`。\n\n   * 请求头\n\n| 请求头 | 取值 |\n|--------|-------|\n| Content-Type | `application/json` |\n| Authorization | `Bearer YOUR_API_KEY` |\n\n   * 请求体示例\n```json\n{\n  \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/sample_Image_1_202b6bf6e6.jpg\",\n  \"effects\": [\n    {\n      \"category\": \"blush\",\n      \"pattern\": { \"name\": \"2colors6\" },\n      \"palettes\": [\n        { \"color\": \"#FF0000\", \"texture\": \"matte\", \"colorIntensity\": 50 },\n        { \"color\": \"#F2A53E\", \"texture\": \"matte\", \"colorIntensity\": 50 }\n      ]\n    },\n    {\n      \"category\": \"eye_liner\",\n      \"pattern\": { \"name\": \"3colors5\" },\n      \"palettes\": [\n        { \"color\": \"#000000\", \"texture\": \"matte\", \"colorIntensity\": 50 },\n        { \"color\": \"#BA0656\", \"texture\": \"matte\", \"colorIntensity\": 50 },\n        { \"color\": \"#089085\", \"texture\": \"matte\", \"colorIntensity\": 50 }\n      ]\n    }\n  ],\n  \"version\": \"1.0\"\n}\n```\n\n   * 请求体 Schema\n\n| 字段 | 类型 | 说明 |\n|-------|------|---------|\n| `src_file_url` | 字符串（URL） | 待处理自拍图片的可公开访问 URL。 |\n| `effects` | Effect 数组 | 要套用的妆效对象数组。详见 [妆效 Schema](#makeup-effect-schemas)。 |\n| `version` | 字符串 | 特效参数的接口版本，使用 `\"1.0\"`。 |\n\n   * 成功响应（`200 OK`）\n返回一个包含任务标识的 JSON 对象。\n\n**响应体 Schema：**\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_id\": \"<string>\"\n  }\n}\n```\n\n**响应示例：**\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_id\": \"grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe\"\n  }\n}\n```\n\n   * 错误响应（`400 Bad Request`、`401 InvalidApiKey` 等）\n返回标准错误对象，并以 message 说明失败原因。\n\n**错误响应示例：**\n```json\n{\n  \"status\": 400,\n  \"error\": \"The operation could not be completed\",\n  \"error_code\": \"CreditInsufficiency\"\n}\n```\n\n---\n\n* 3. 取得任务状态与结果\n\n`GET /s2s/v2.0/task/makeup-vto/<task_id>`\n\n取得进行中或已完成任务的当前状态与结果。\n\n   * 请求头\n\n| 请求头 | 取值 |\n|--------|-------|\n| Authorization | `Bearer YOUR_API_KEY` |\n\n   * 路径参数\n\n| 参数 | 类型 | 说明 |\n|-----------|------|---------|\n| task_id | 字符串 | 发起任务接口返回的标识。 |\n\n   * 成功响应（`200 OK`）\n返回一个 JSON 对象，包含任务状态；若已完成，还包含结果。\n\n**响应体 Schema：**\n```json\n{\n  \"data\": {\n    \"task_status\": \"<string>\", // 'success', 'error', or a processing state (e.g., 'queued', 'processing')\n    \"results\": [ // present only when task_status is 'success'\n      {\n        \"download_url\": \"<string>\" // URL to download the processed image\n      }\n    ],\n    \"failure_reason\": \"<string>\" // present only when task_status is 'error'\n  }\n}\n```\n\n**成功响应示例：**\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_status\": \"success\",\n    \"results\": {\n      \"url\": \"https://s3.storage.prod/processed/image_123.jpg?token=...\"\n    }\n  }\n}\n```\n\n**引擎错误响应示例：**\n接口查询已成功送达，但在执行 AI 任务的过程中发生错误。\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_status\": \"error\",\n    \"error\": \"exceed_max_filesize\",\n    \"error_message\": \"string\",\n  }\n}\n```\n  > 请注意，无论查询错误还是引擎错误，只要发生错误就不消耗点数。\n\n**进行中响应示例：**\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_status\": \"running\"\n  }\n}\n```\n\n   * 错误响应\n*   `404 InvalidTaskId`：`task_id` 不存在或无效。\n*   `401 InvalidApiKey`：API 密钥无效或缺失。\n*   `500 TaskTimeout`：任务已成功完成或已失败，且超过保留期。\n\n**查询错误响应示例：**\n```json\n{\n  \"status\": 401,\n  \"error_code\": \"InvalidApiKey\"\n}\n```\n  > 请注意，无论查询错误还是引擎错误，只要发生错误就不消耗点数。\n\n---\n\n## 输入与输出\n* 妆效 Schema\n\n本节定义 AI 妆效任务请求体的完整结构与限制。每个特效都是顶层 `effects` 数组中的一个对象。\n\n* 特效容器（顶层）\n\n```json\n{\n  \"version\": \"1.0\",\n  \"effects\": []                    // array<Effect> — Contains makeup effect objects\n}\n```\n\n* 妆效类别\n\n   * `skin_smooth`\n```json\n{\n  \"category\": \"skin_smooth\",           // string, const \"skin_smooth\"\n  \"skinSmoothStrength\": 50,            // integer, range: 0..100\n  \"skinSmoothColorIntensity\": 50       // integer, range: 0..100\n}\n```\n  > **注意！** 请求中若未包含 ``skin_smooth`` 特效，AI 妆效引擎会自动套用默认的美肤强度 50。\n  希望只上妆、不做磨皮时，把所有 ``skinSmoothStrength`` 与 ``skinSmoothColorIntensity`` 参数设为 0。不过为了最佳效果与最高质量的混合，建议保留默认的美肤设置。\n\n   * `blush`\n```json\n{\n  \"category\": \"blush\",                 // string, const \"blush\"\n  \"pattern\": {                         // object\n    \"name\": \"\"                         // string — MUST equal a `label` from blush.json\n  },\n  \"palettes\": [                        // array<BlushPalette>, minItems: (see colorNum in pattern)\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"texture\": \"matte\",              // string, enum [\"matte\",\"satin\",\"shimmer\"]\n      \"glowStrength\": 50,              // integer, range: 0..100 — REQUIRED if texture=\"satin\"\n      \"shimmerColor\": \"#fc288f\",       // string, hex color \"#RRGGBB\" — REQUIRED if texture=\"shimmer\"\n      \"shimmerDensity\": 50,            // integer, range: 0..100 — REQUIRED if texture=\"shimmer\"\n      \"colorIntensity\": 50             // integer, range: 0..100\n    }\n  ]\n}\n```\n\n**完整图案清单：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/blush.json\n\n**彩妆图案类别一览：**\n```json\n[\n  {\n    \"category\": \"1 color\",\n    \"label\": \"1color1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/483/a53cd4f4-43b6-4e19-b85a-ec7a95c6a47f.jpg\",\n    \"tags\": [\n      { \"id\": 100, \"name\": \"Blush 3D\" },\n      { \"id\": 103, \"name\": \"Oblong\" }\n    ],\n    \"colorNum\": 1\n  },\n  {\n    \"category\": \"2 colors\",\n    \"label\": \"2colors1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/147/a8d86a4b-8aa0-48d7-a716-63ec78dfb30b.jpg\",\n    \"tags\": [\n      { \"id\": 100, \"name\": \"Blush 3D\" }\n    ],\n    \"colorNum\": 2\n  },\n  {\n    \"category\": \"3 colors\",\n    \"label\": \"3colors1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/734/af8b625b-ae3a-4211-9413-f22c16a5f174.jpg\",\n    \"tags\": [\n      { \"id\": 100, \"name\": \"Blush 3D\" },\n      { \"id\": 104, \"name\": \"Round\" }\n    ],\n    \"colorNum\": 3\n  }\n]\n```\n\n\n   * `bronzer`\n```json\n{\n  \"category\": \"bronzer\",               // string, const \"bronzer\"\n  \"pattern\": { \"name\": \"\" },           // object — name MUST equal a `label` from bronzer.json\n  \"palettes\": [\n    { \"color\": \"#ff0000\", \"colorIntensity\": 50 }  // hex color, int range: 0..100\n  ]\n}\n```\n\n**完整图案清单：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/bronzer.json\n\n**彩妆图案类别一览：**\n```json\n[\n  {\n    \"category\": \"Bronzer\",\n    \"label\": \"Bronzer1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/973/22ff2c07-d584-4ae6-8281-c095cd121a52.jpg\",\n    \"tags\": [],\n    \"colorNum\": 1\n  }\n]\n```\n\n   * `concealer`\n```json\n{\n  \"category\": \"concealer\",             // string, const \"concealer\"\n  \"palettes\": [\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"colorIntensity\": 50,            // integer, range: 0..100\n      \"colorUnderEyeIntensity\": 50,    // integer, range: 0..100\n      \"coverageLevel\": 50              // integer, range: 0..100\n    }\n  ]\n}\n```\n\n   * `contour`\n```json\n{\n  \"category\": \"contour\",               // string, const \"contour\"\n  \"pattern\": { \"name\": \"\" },           // object — name MUST equal a `label` from contour.json\n  \"palettes\": [\n    { \"color\": \"#ff0000\", \"colorIntensity\": 50 }  // hex color, int range: 0..100\n  ]\n}\n```\n\n**完整图案清单：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/contour.json\n\n**彩妆图案类别一览：**\n```json\n[\n  {\n    \"category\": \"Heart face\",\n    \"label\": \"HeartFace2\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/731/49a1b3b9-b393-4bf4-b486-1493fe468436.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Invtriangle\",\n    \"label\": \"Invtriangle1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/858/a94c8cca-5f8c-4b8b-a02d-94edb6a4ad7f.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Oval face\",\n    \"label\": \"OvalFace6\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/906/644368a3-7eee-4ad9-829e-e2b3d4320fec.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Round face\",\n    \"label\": \"RoundFace4\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/106/3e455b5f-7e2d-46f7-8627-dc137051c144.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Triangle face\",\n    \"label\": \"TriangleFace2\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/528/18765180-c254-4411-a25c-c1d78f5c3d77.jpg\",\n    \"tags\": []\n  }\n]\n```\n\n   * `eyebrows`\n```json\n{\n  \"category\": \"eyebrows\",              // string, const \"eyebrows\"\n  \"pattern\": {\n    \"type\": \"shape\",                   // string, enum [\"shape\",\"color\"], default: \"shape\"\n    \"name\": \"\",                        // string, required when type=\"shape\" — label from eyebrows.json\n    \"curvature\": 0,                    // integer, range: -100..100 (shape only)\n    \"thickness\": 0,                    // integer, range: -100..100 (shape only)\n    \"definition\": 0                    // integer, range: 0..100 (shape only)\n  },\n  \"palettes\": [\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"colorIntensity\": 50,            // integer, range: 0..100\n      \"texture\": \"matte\",              // string, enum [\"matte\",\"shimmer\"]\n      \"shimmerColor\": \"#fc288f\",       // string, hex color \"#RRGGBB\" — REQUIRED if texture=\"shimmer\"\n      \"shimmerIntensity\": 50,          // integer, range: 0..100 — REQUIRED if texture=\"shimmer\"\n      \"shimmerSize\": 50,               // integer, range: 0..100 — REQUIRED if texture=\"shimmer\"\n      \"shimmerDensity\": 50             // integer, range: 0..100 — REQUIRED if texture=\"shimmer\"\n    }\n  ]\n}\n```\n\n**完整图案清单：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/eyebrows.json\n\n**彩妆图案类别一览：**\n```json\n[\n  {\n    \"category\": \"Arrow\",\n    \"label\": \"Arrow1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/490/1fb96bf9-979e-4327-a8c4-8c503f541f1a.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Curved\",\n    \"label\": \"Curved1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/389/1ccb300e-c7ed-4995-920e-7d1bf8da1fad.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Drama\",\n    \"label\": \"Drama2\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/196/5fb14bec-553d-4841-bba7-ca7e5e27c12e.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"High Arch\",\n    \"label\": \"HighArch1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/609/7a8676dc-6f6a-4b12-aab0-c50328e448c5.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Original\",\n    \"label\": \"Original2\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/300/123551e9-ca94-4732-89ed-5b3866678555.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Soft Arch\",\n    \"label\": \"SoftArch1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/121/2552ebf0-2705-43f7-b295-4fac21e18009.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Straight\",\n    \"label\": \"Straight1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/1/7734e777-8e51-41f1-abaf-205f0ed5e3b4.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Thin\",\n    \"label\": \"Thin1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/734/6ee10843-a251-4aa0-9183-db7f981d714d.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Upward\",\n    \"label\": \"Upward4\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/751/76578317-f475-49c7-bd96-910ccad617ef.jpg\",\n    \"tags\": []\n  }\n]\n```\n\n   * `eye_liner`\n```json\n{\n  \"category\": \"eye_liner\",             // string, const \"eye_liner\"\n  \"pattern\": { \"name\": \"\" },           // object — name MUST equal a label from eyeliner.json\n  \"palettes\": [\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"texture\": \"matte\",              // string, enum [\"matte\",\"shimmer\",\"metallic\"]\n      \"shimmerColor\": \"#fc288f\",       // string, hex color \"#RRGGBB\" — REQUIRED if texture in [\"shimmer\",\"metallic\"]\n      \"shimmerIntensity\": 50,          // integer, range: 0..100 — REQUIRED if texture in [\"shimmer\",\"metallic\"]\n      \"metallicIntensity\": 50,         // integer, range: 0..100 — REQUIRED if texture=\"metallic\"\n      \"colorIntensity\": 50             // integer, range: 0..100\n    }\n  ]\n}\n```\n\n**完整图案清单：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/eyeliner.json\n\n**彩妆图案类别一览：**\n```json\n[\n  {\n    \"category\": \"2 colors\",\n    \"label\": \"2colors1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/419/71d9429a-dc08-4e80-9c46-6e55631ef766.jpg\",\n    \"tags\": [\n      {\n        \"id\": 28,\n        \"name\": \"Drama\"\n      }\n    ],\n    \"colorNum\": 2\n  },\n  {\n    \"category\": \"3 colors\",\n    \"label\": \"3colors2\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/208/056aa6cd-8678-470c-b111-b7653d7ddf93.jpg\",\n    \"tags\": [\n      {\n        \"id\": 28,\n        \"name\": \"Drama\"\n      }\n    ],\n    \"colorNum\": 3\n  },\n  {\n    \"category\": \"1 color\",\n    \"label\": \"Arabic3\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/726/1919aad4-21a2-493a-a5f8-48bc99a61ba5.jpg\",\n    \"tags\": [\n      {\n        \"id\": 26,\n        \"name\": \"Arabic\"\n      }\n    ],\n    \"colorNum\": 1\n  }\n]\n```\n\n   * `eye_shadow`\n```json\n{\n  \"category\": \"eye_shadow\",            // string, const \"eye_shadow\"\n  \"pattern\": { \"name\": \"\" },           // object — name MUST equal a label from eyeshadow.json\n  \"palettes\": [\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"texture\": \"matte\",              // string, enum [\"matte\",\"shimmer\",\"metallic\"]\n      \"shimmerColor\": \"#fc288f\",       // string, hex color \"#RRGGBB\" — REQUIRED if texture in [\"shimmer\",\"metallic\"]\n      \"shimmerIntensity\": 50,          // integer, range: 0..100 — REQUIRED if texture in [\"shimmer\",\"metallic\"]\n      \"metallicIntensity\": 50,         // integer, range: 0..100 — REQUIRED if texture=\"metallic\"\n      \"colorIntensity\": 50             // integer, range: 0..100\n    }\n  ]                                    // minItems: (see colorNum in pattern)\n}\n```\n\n**完整图案清单：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/eyeshadow.json\n\n**彩妆图案类别一览：**\n```json\n[\n  {\n    \"category\": \"1 color\",\n    \"label\": \"1color1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/188/0322c4f9-e54d-4a6b-8072-6bb76560121a.jpg\",\n    \"tags\": [\n      {\n        \"id\": 12,\n        \"name\": \"Artistic\"\n      },\n      {\n        \"id\": 14,\n        \"name\": \"Dream\"\n      },\n      {\n        \"id\": 15,\n        \"name\": \"Trend\"\n      }\n    ],\n    \"colorNum\": 1\n  },\n  {\n    \"category\": \"2 colors\",\n    \"label\": \"2colors1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/938/3348211c-1b83-4ab2-9c6a-ce06e4aa3528.jpg\",\n    \"tags\": [\n      {\n        \"id\": 1,\n        \"name\": \"Fan shape\"\n      },\n      {\n        \"id\": 8,\n        \"name\": \"Only upper lid\"\n      }\n    ],\n    \"colorNum\": 2\n  },\n  {\n    \"category\": \"3 colors\",\n    \"label\": \"3colors1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/542/55e1b0fd-b888-47ff-bd3a-3dc1af2a7b69.jpg\",\n    \"tags\": [\n      {\n        \"id\": 1,\n        \"name\": \"Fan shape\"\n      },\n      {\n        \"id\": 8,\n        \"name\": \"Only upper lid\"\n      }\n    ],\n    \"colorNum\": 3\n  },\n  {\n    \"category\": \"4 colors\",\n    \"label\": \"4colors1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/429/29cd5839-464b-4a7a-a5c1-c7b40e9464d7.jpg\",\n    \"tags\": [\n      {\n        \"id\": 4,\n        \"name\": \"Closed banana\"\n      },\n      {\n        \"id\": 10,\n        \"name\": \"Whole eye\"\n      }\n    ],\n    \"colorNum\": 4\n  },\n  {\n    \"category\": \"5 colors\",\n    \"label\": \"5colors1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/2/824dcf7c-1273-4a30-8f1f-2137926057d6.jpg\",\n    \"tags\": [\n      {\n        \"id\": 4,\n        \"name\": \"Closed banana\"\n      },\n      {\n        \"id\": 10,\n        \"name\": \"Whole eye\"\n      }\n    ],\n    \"colorNum\": 5\n  }\n]\n```\n\n   * `eyelashes`\n```json\n{\n  \"category\": \"eyelashes\",             // string, const \"eyelashes\"\n  \"pattern\": { \"name\": \"\" },           // object — name MUST equal a label from eyelashes.json\n  \"palettes\": [\n    { \"color\": \"#ff0000\", \"colorIntensity\": 50 }  // hex color, int range: 0..100\n  ]\n}\n```\n\n**完整图案清单：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/eyelashes.json\n\n**彩妆图案类别一览：**\n```json\n[\n  {\n    \"category\": \"Artistic\",\n    \"label\": \"Artistic1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/146/7a8ed606-1c27-4d91-9320-c40a904f621f.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Natural\",\n    \"label\": \"Natural1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/287/cd5cae75-a1b3-48f8-8537-e6e259213901.png\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Upper&Lower\",\n    \"label\": \"Upper&Lower1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/18/2689ea2d-725e-4fa0-8563-df874ae1a83f.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Upper\",\n    \"label\": \"Upper1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/982/c99bf74e-545f-4da7-a314-f3bd84b82156.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"UpperDense\",\n    \"label\": \"UpperDense1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/888/452ec863-f0a8-40e7-aa33-31c0c39f57e2.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Winged\",\n    \"label\": \"Winged1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/825/36ab3859-eae5-49e4-9d97-161698bbb8bb.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Wispies\",\n    \"label\": \"Wispies1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/722/a2a727f6-748c-41e7-8ac0-c9c57c18c05a.png\",\n    \"tags\": []\n  }\n]\n```\n\n   * `foundation`\n```json\n{\n  \"category\": \"foundation\",            // string, const \"foundation\"\n  \"palettes\": [\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"colorIntensity\": 50,            // integer, range: 0..100\n      \"glowIntensity\": 50,             // integer, range: 0..100\n      \"coverageIntensity\": 50          // integer, range: 0..100\n    }\n  ]\n}\n```\n\n   * `highlighter`\n```json\n{\n  \"category\": \"highlighter\",           // string, const \"highlighter\"\n  \"pattern\": { \"name\": \"\" },           // object — name MUST equal a label from highlighter.json\n  \"palettes\": [\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"glowIntensity\": 50,             // integer, range: 0..100\n      \"shimmerIntensity\": 50,          // integer, range: 0..100\n      \"shimmerDensity\": 50,            // integer, range: 0..100\n      \"shimmerSize\": 50,               // integer, range: 0..100\n      \"colorIntensity\": 50             // integer, range: 0..100\n    }\n  ]\n}\n```\n\n**完整图案清单：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/highlighter.json\n\n**彩妆图案类别一览：**\n```json\n[\n  {\n    \"category\": \"Heart face\",\n    \"label\": \"HeartFace4\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/246/6ca40279-79cc-4918-b48a-64306009b365.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Invtriangle\",\n    \"label\": \"Invtriangle2\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/7/6b0b9760-612c-4319-bd81-855d262d8e89.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Oblong\",\n    \"label\": \"Oblong11\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/862/b7279f4e-edf2-43f3-8156-561fe5a52ec3.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Oval face\",\n    \"label\": \"OvalFace2\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/369/91097a05-9fd2-43cb-82e9-dd45e72b613b.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Round face\",\n    \"label\": \"RoundFace3\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/520/2d3ccbe2-36c3-43df-9e78-4c2c931fa431.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Square face\",\n    \"label\": \"SquareFace3\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/989/2959777b-19ca-4f4a-a023-3c8927191497.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Triangle face\",\n    \"label\": \"TriangleFace3\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/765/221c1f12-c621-4567-a8ee-1433038ee8a2.jpg\",\n    \"tags\": []\n  }\n]\n```\n\n   * `lip_color`\n```json\n{\n  \"category\": \"lip_color\",             // string, const \"lip_color\"\n  \"shape\": {                           // object — driven by lipshape.json\n    \"name\": \"original\"                 // string — MUST equal a `label` from lipshape.json\n  },\n  \"morphology\": {                      // optional object\n    \"fullness\": 50,                    // integer, range: 0..100 (default: 0)\n    \"wrinkless\": 50                    // integer, range: 0..100 (default: 0)\n  },\n  \"palettes\": [                        // minItems depends on style; often ≥1\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"texture\": \"matte\",              // string, enum [\"matte\",\"gloss\",\"holographic\",\"metallic\",\"satin\",\"sheer\",\"shimmer\"]\n      \"colorIntensity\": 50,            // integer, range: 0..100\n      \"gloss\": 50,                     // int, range: 0..100 — REQUIRED if texture in [\"gloss\",\"holographic\",\"metallic\",\"sheer\",\"shimmer\"]\n      \"shimmerColor\": \"#ff0000\",       // string, hex color \"#RRGGBB\" — REQUIRED if texture in [\"holographic\",\"metallic\",\"shimmer\"]\n      \"shimmerIntensity\": 50,          // integer, range: 0..100 — REQUIRED if texture in [\"holographic\",\"metallic\",\"shimmer\"]\n      \"shimmerDensity\": 50,            // integer, range: 0..100 — REQUIRED if texture in [\"holographic\",\"metallic\",\"shimmer\"]\n      \"shimmerSize\": 50,               // integer, range: 0..100 — REQUIRED if texture in [\"holographic\",\"metallic\",\"shimmer\"]\n      \"transparencyIntensity\": 50      // integer, range: 0..100 — REQUIRED if texture in [\"gloss\",\"sheer\",\"shimmer\"]\n    }\n  ],\n  \"style\": {\n    \"type\": \"full\",                    // string, enum [\"full\",\"ombre\",\"twoTone\"]\n    \"innerRatio\": 50,                  // int, range: 0..100 — REQUIRED if type=\"ombre\"\n    \"featherStrength\": 50              // int, range: 0..100 — REQUIRED if type=\"ombre\"\n  }\n}\n```\n\n**完整形状清单：**\nhttps://plugins-media.makeupar.com/wcm-saas/shapes/lipshape.json\n\n**彩妆图案类别一览：**\n```json\n[{\n        \"category\": \"general\",\n        \"label\": \"original\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/original.png\",\n        \"tags\": [\n        ]\n    }, {\n        \"category\": \"general\",\n        \"label\": \"heart-shaped\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/heart-shaped.jpg\",\n        \"tags\": [\n        ]\n    }, {\n        \"category\": \"general\",\n        \"label\": \"m-shaped\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/m-shaped.jpg\",\n        \"tags\": [\n        ]\n    }, {\n        \"category\": \"general\",\n        \"label\": \"petal\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/petal.jpg\",\n        \"tags\": [\n        ]\n    }, {\n        \"category\": \"general\",\n        \"label\": \"plump\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/plump.jpg\",\n        \"tags\": [\n        ]\n    }, {\n        \"category\": \"general\",\n        \"label\": \"pouty\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/pouty.jpg\",\n        \"tags\": [\n        ]\n    }, {\n        \"category\": \"general\",\n        \"label\": \"smile\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/smile.jpg\",\n        \"tags\": [\n        ]\n    }, {\n        \"category\": \"general\",\n        \"label\": \"vintage\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/vintage.jpg\",\n        \"tags\": [\n        ]\n    }\n]\n```\n\n   * `lip_liner`\n```json\n{\n  \"category\": \"lip_liner\",             // string, const \"lip_liner\"\n  \"pattern\": { \"name\": \"\" },           // object — name MUST equal a label from lipliner.json\n  \"palettes\": [\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"texture\": \"matte\",              // string, enum [\"matte\",\"satin\"]\n      \"colorIntensity\": 50,            // integer, range: 0..100\n      \"thickness\": 50,                 // integer, range: 0..100\n      \"smoothness\": 50                 // integer, range: 0..100\n    }\n  ]\n}\n```\n\n**完整图案清单：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/lipliner.json\n\n**彩妆图案类别一览：**\n```json\n[\n  {\n    \"category\": \"Large & Full\",\n    \"label\": \"Large&Full1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/417/7ac66cb2-2c7b-451c-8284-cc77791b7001.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Larger Lower\",\n    \"label\": \"LargerLower1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/878/84b2ef48-3af4-4851-86d2-b01d10db82b2.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Larger Upper\",\n    \"label\": \"LargerUpper1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/867/674f9f4c-7961-462e-8cc9-9a8acaad4168.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Natural\",\n    \"label\": \"Natural1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/258/7533c08a-cc9c-45ab-9294-5d5a8114037d.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Rosebud\",\n    \"label\": \"Rosebud1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/47/eb95e91f-6ef1-41f7-bc4f-aecd7d780c42.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Small\",\n    \"label\": \"Small1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/396/6b78e461-24a6-4c6d-afb4-88beb71f1732.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Wider\",\n    \"label\": \"Wider1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/867/21f92b70-72b5-4a57-b4d7-81c5cce757a6.jpg\",\n    \"tags\": []\n  }\n]\n```\n\n---\n\n## 请求示例\n\n以下是一份完整、可用的 `effectJson` 参数，一次套用多项妆效。\n\n```json\n{\n  \"version\": \"1.0\",\n  \"effects\": [\n    {\n      \"category\": \"skin_smooth\",\n      \"skinSmoothStrength\": 55,\n      \"skinSmoothColorIntensity\": 45\n    },\n    {\n      \"category\": \"blush\",\n      \"pattern\": { \"name\": \"2colors1\" },\n      \"palettes\": [\n        {\n          \"color\": \"#e19f9f\",\n          \"texture\": \"matte\",\n          \"colorIntensity\": 60,\n          \"shimmerColor\": \"#d63252\",\n          \"shimmerDensity\": 50\n        },\n        {\n          \"color\": \"#c98a8a\",\n          \"texture\": \"satin\",\n          \"glowStrength\": 40,\n          \"colorIntensity\": 70\n        }\n      ]\n    },\n    {\n        \"category\": \"lip_color\",\n        \"shape\": { \"name\": \"plump\" },\n        \"morphology\": { \"fullness\": 30, \"wrinkless\": 25 },\n        \"style\": { \"type\": \"full\" },\n        \"palettes\": [\n            {\n                \"color\": \"#e11c43\",\n                \"texture\": \"gloss\",\n                \"colorIntensity\": 80,\n                \"gloss\": 75\n            }\n        ]\n    }\n  ]\n}\n```\n在这个示例中，`blush` 使用 `blush.json` 里的 `2colors1` 图案，该图案需要恰好两个色盘。`lip_color` 特效使用 `lipshape.json` 里的 `plump` 形状。\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 美妆虚拟试妆|长边 < 1920，脸部宽度 >= 100|< 10MB|jpg/jpeg/png|\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n|error_below_min_image_size|源图尺寸小于下限（要求：宽 >= 100px，高 >= 100px）\n|error_exceed_max_image_size|源图尺寸超过上限（要求：宽 < 1920px，高 < 1080px）\n|error_face_position_invalid |请确保整张脸在画面中完整可见|\n|error_face_position_too_small|检测到的人脸太小，请靠近相机|\n|error_face_position_out_of_boundary|人脸过大，或部分超出画面边界，请调整位置|\n|error_face_angle_invalid|脸部角度不太对。正脸拍摄时，头部偏离正向请在 10 度以内；侧脸拍摄时，角度应大于 15 度|\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## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 美妆虚拟试妆 V1.0 | 1 |\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"
    }
  ],
  "paths": {
    "/s2s/v2.0/task/makeup-vto": {
      "post": {
        "summary": "执行 AI 美妆虚拟试妆 任务。",
        "description": "本接口用于发起 AI 美妆虚拟试妆流程。您需要提供源文件（URL 或文件 ID），并按既定特效结构指定要应用的特效。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。\n",
        "tags": [
          "V1.0"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/BasicRunTaskV2"
                  },
                  {
                    "type": "object",
                    "required": [
                      "effects"
                    ],
                    "properties": {
                      "version": {
                        "type": "string",
                        "description": "美妆特效规格的版本号。 未特别指定时默认为 `\"1.0\"`。\n",
                        "default": "1.0",
                        "example": "1.0"
                      },
                      "effects": {
                        "type": "array",
                        "description": "要应用的美妆特效列表。 每个特效对象都必须给出 `category`，并符合该美妆类型对应的结构定义。\n",
                        "items": {
                          "anyOf": [
                            {
                              "$ref": "#/components/schemas/SkinSmoothEffect"
                            },
                            {
                              "$ref": "#/components/schemas/BlushEffect"
                            },
                            {
                              "$ref": "#/components/schemas/BronzerEffect"
                            },
                            {
                              "$ref": "#/components/schemas/ConcealerEffect"
                            },
                            {
                              "$ref": "#/components/schemas/ContourEffect"
                            },
                            {
                              "$ref": "#/components/schemas/EyebrowsEffect"
                            },
                            {
                              "$ref": "#/components/schemas/EyelinerEffect"
                            },
                            {
                              "$ref": "#/components/schemas/EyeshadowEffect"
                            },
                            {
                              "$ref": "#/components/schemas/EyelashesEffect"
                            },
                            {
                              "$ref": "#/components/schemas/FoundationEffect"
                            },
                            {
                              "$ref": "#/components/schemas/HighlighterEffect"
                            },
                            {
                              "$ref": "#/components/schemas/LipColorEffect"
                            },
                            {
                              "$ref": "#/components/schemas/LipLinerEffect"
                            }
                          ]
                        }
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "任务执行成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BasicRunTaskResponseV2"
                }
              }
            }
          },
          "400": {
            "description": "任务执行失败",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/responses/RunError"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/s2s/v2.0/task/makeup-vto/{task_id}": {
      "get": {
        "summary": "查询 AI 美妆虚拟试妆 任务的状态。",
        "tags": [
          "V1.0"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
            },
            "description": "要查询的任务 ID"
          }
        ],
        "responses": {
          "200": {
            "description": "任务状态查询成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskStatusResponseV2"
                }
              }
            }
          },
          "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": {
      "EngineErrorCode": {
        "type": "string",
        "nullable": true,
        "enum": [
          "exceed_max_filesize",
          "invalid_parameter",
          "error_download_image",
          "error_decode_image",
          "error_nsfw_content_detected",
          "error_inference",
          "unknown_internal_error"
        ],
        "description": "错误码：\n\n- `exceed_max_filesize` - 输入文件大小超出上限\n\n- `invalid_parameter` - 参数取值无效\n\n- `error_download_image` - 下载原图出错\n\n- `error_decode_image` - 解码原图出错\n\n- `unknown_internal_error` - 其他错误\n"
      },
      "FileV1.1": {
        "title": "File V1.1",
        "description": "该对象表示一个文件。",
        "type": "object",
        "required": [
          "files"
        ],
        "properties": {
          "files": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "content_type",
                "file_name",
                "file_size"
              ],
              "properties": {
                "content_type": {
                  "type": "string",
                  "example": "image/jpg",
                  "description": "该文件的 MIME 类型。当前支持的取值见上方的枚举。"
                },
                "file_name": {
                  "type": "string",
                  "example": "my-selfie.jpg",
                  "description": "文件名"
                },
                "file_size": {
                  "type": "integer",
                  "example": 50000,
                  "description": "该文件的大小（字节）。不应超过 10MB。"
                }
              }
            }
          }
        }
      },
      "BasicFileResponse": {
        "type": "object",
        "properties": {
          "files": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "content_type": {
                  "type": "string",
                  "example": "image/jpg",
                  "description": "该文件的 MIME 类型。"
                },
                "file_name": {
                  "type": "string",
                  "example": "my-selfie.jpg",
                  "description": "文件名"
                },
                "file_id": {
                  "type": "string",
                  "example": "U8aqJbsXGT537jtGnEDFHqxdDXqh8+oTF/cSkLimzuvVwMP+Jb1XbjPsf7ZgUgLY",
                  "description": "该文件的 ID。其他运行任务的接口需要用到这个 `file_id`。"
                },
                "requests": {
                  "type": "array",
                  "description": "请用下面的 `url`、`headers`、`method` 上传文件。上传完成后，用 `file_id` 继续调用运行任务接口。",
                  "items": {
                    "type": "object",
                    "properties": {
                      "headers": {
                        "type": "object",
                        "example": {
                          "Content-Type": "image/jpg",
                          "Content-Length": 50000
                        },
                        "description": "上传文件时需携带的请求头"
                      },
                      "url": {
                        "type": "string",
                        "example": "https://example.com/presigned-upload-url",
                        "description": "上传该文件的 URL"
                      },
                      "method": {
                        "type": "string",
                        "example": "PUT",
                        "description": "上传该文件所用的 HTTP 方法"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "FileResponseV2": {
        "type": "object",
        "properties": {
          "status": {
            "type": "integer",
            "example": 200,
            "description": "响应状态"
          },
          "data": {
            "$ref": "#/components/schemas/BasicFileResponse"
          }
        }
      },
      "BasicRunTaskV2SrcFileUrl": {
        "title": "用源文件 URL 运行任务",
        "type": "object",
        "required": [
          "src_file_url"
        ],
        "properties": {
          "src_file_url": {
            "type": "string",
            "description": "用于运行任务的文件 URL，该 URL 需可公开访问。",
            "example": "https://example.com/selfie.jpg"
          }
        }
      },
      "BasicRunTaskV2SrcFileId": {
        "title": "用源文件 ID 运行任务",
        "type": "object",
        "required": [
          "src_file_id"
        ],
        "properties": {
          "src_file_id": {
            "type": "string",
            "description": "用于运行任务的文件 ID，取自上传文件接口返回的 file_id。",
            "example": "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE="
          }
        }
      },
      "BasicRunTaskV2": {
        "title": "BasicRunTaskV2",
        "anyOf": [
          {
            "$ref": "#/components/schemas/BasicRunTaskV2SrcFileUrl"
          },
          {
            "$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 可在 30 天内查询任务结果。",
                "example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
              }
            }
          }
        }
      },
      "TaskStatusResponseBodySingleUrlResultsV2": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "下载该结果的 URL，有效期 2 小时",
            "example": "https://example.com/sample-result-url"
          }
        }
      },
      "TaskStatusResponseV2": {
        "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": {
                "$ref": "#/components/schemas/TaskStatusResponseBodySingleUrlResultsV2"
              }
            }
          }
        }
      },
      "SkinSmoothEffect": {
        "type": "object",
        "description": "控制施加到皮肤上的 AI 磨皮强度。 未提供 skin_smooth 特效时，系统会自动以 50 的磨皮强度处理，让融合更真实。\n",
        "required": [
          "category"
        ],
        "properties": {
          "category": {
            "type": "string",
            "enum": [
              "skin_smooth"
            ],
            "description": "标识该特效为磨皮特效，取值固定为 \"skin_smooth\"。\n"
          },
          "skinSmoothStrength": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "default": 50,
            "description": "对整体肤质施加的磨皮强度。取值越高，皮肤越柔滑、越像磨过一样。\n"
          },
          "skinSmoothColorIntensity": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "default": 50,
            "description": "磨皮时的色彩融合强度，用于统一肤色、减少肤色不一致。\n"
          }
        },
        "example": {
          "category": "skin_smooth",
          "skinSmoothStrength": 50,
          "skinSmoothColorIntensity": 50
        }
      },
      "BlushEffect": {
        "type": "object",
        "description": "用预置图案与自定义色板为双颊上腮红。 图案名称须取自官方 blush.json 图案目录中的 label。\n",
        "required": [
          "category",
          "pattern",
          "palettes"
        ],
        "properties": {
          "category": {
            "type": "string",
            "enum": [
              "blush"
            ],
            "description": "标识该特效为腮红特效，取值固定为 \"blush\"。\n"
          },
          "pattern": {
            "type": "object",
            "description": "定义腮红在脸上的落点。每个图案对应 blush.json 中的一种脸型与布局。\n",
            "required": [
              "name"
            ],
            "properties": {
              "name": {
                "type": "string",
                "description": "腮红图案名称，须与 blush.json 图案目录中的 `label` 一致。\n",
                "example": "1color1"
              }
            }
          },
          "palettes": {
            "type": "array",
            "minItems": 1,
            "description": "色板条目列表。需要的色板数量取决于所选腮红图案中定义的 `colorNum` 字段。\n",
            "items": {
              "type": "object",
              "required": [
                "color",
                "texture",
                "colorIntensity"
              ],
              "properties": {
                "color": {
                  "type": "string",
                  "description": "腮红主色，十六进制格式（#RRGGBB），作为腮红的主色料。\n",
                  "pattern": "^#?[0-9A-Fa-f]{6}$"
                },
                "texture": {
                  "type": "string",
                  "enum": [
                    "matte",
                    "satin",
                    "shimmer"
                  ],
                  "description": "腮红质地：\n  - matte：纯色料，不带光泽\n  - satin：柔光，需配 glowStrength\n  - shimmer：闪片或珠光，需配 shimmer 相关参数\n"
                },
                "glowStrength": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "缎光腮红的光泽强度。当 texture 为 \"satin\" 或 \"shimmer\" 时必填。\n"
                },
                "shimmerColor": {
                  "type": "string",
                  "description": "闪片颗粒的颜色。当 texture 为 \"shimmer\" 时必填。\n"
                },
                "shimmerDensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "腮红中闪片颗粒的密度。当 texture 为 \"shimmer\" 时必填。\n"
                },
                "colorIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "腮红颜色相对于基础色料的强度。\n"
                }
              }
            }
          }
        },
        "example": {
          "category": "blush",
          "pattern": {
            "name": "1color1"
          },
          "palettes": [
            {
              "color": "#ff7777",
              "texture": "matte",
              "colorIntensity": 60
            }
          ]
        }
      },
      "BronzerEffect": {
        "type": "object",
        "description": "用古铜修容为肤色增暖，营造日晒感的轮廓。图案名称须与 bronzer.json 中的条目一致。\n",
        "required": [
          "category",
          "pattern",
          "palettes"
        ],
        "properties": {
          "category": {
            "type": "string",
            "enum": [
              "bronzer"
            ],
            "description": "标识该特效为古铜修容特效，取值固定为 \"bronzer\"。\n"
          },
          "pattern": {
            "type": "object",
            "required": [
              "name"
            ],
            "description": "定义古铜修容的铺设布局，图案名称须与 bronzer.json 中的 `label` 一致。\n",
            "properties": {
              "name": {
                "type": "string",
                "example": "Bronzer1",
                "description": "古铜修容图案名称，取自 bronzer.json 目录。\n"
              }
            }
          },
          "palettes": {
            "type": "array",
            "description": "古铜修容色板包含色料颜色与强度控制。\n",
            "items": {
              "type": "object",
              "required": [
                "color",
                "colorIntensity"
              ],
              "properties": {
                "color": {
                  "type": "string",
                  "description": "古铜修容颜色，十六进制格式（#RRGGBB）。\n"
                },
                "colorIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "古铜修容的上色强度。\n"
                }
              }
            }
          }
        },
        "example": {
          "category": "bronzer",
          "pattern": {
            "name": "Bronzer1"
          },
          "palettes": [
            {
              "color": "#c08050",
              "colorIntensity": 50
            }
          ]
        }
      },
      "ConcealerEffect": {
        "type": "object",
        "description": "遮瑕用于中和瑕疵、匀整肤色，并提亮眼周。 遮瑕不使用图案，只有色料与强度控制。 色板中的字段全部必填，以保证各面部区域的表现一致。\n",
        "required": [
          "category",
          "palettes"
        ],
        "properties": {
          "category": {
            "type": "string",
            "enum": [
              "concealer"
            ],
            "description": "标识该特效为遮瑕特效，取值固定为 \"concealer\"。\n"
          },
          "palettes": {
            "type": "array",
            "minItems": 1,
            "description": "一组遮瑕色板，定义颜色与强度。同一色板会用在相关面部区域， 例如眼周、额头、下巴等需要修饰的部位。\n",
            "items": {
              "type": "object",
              "required": [
                "color",
                "colorIntensity",
                "colorUnderEyeIntensity",
                "coverageLevel"
              ],
              "properties": {
                "color": {
                  "type": "string",
                  "description": "遮瑕色号，十六进制 RGB 格式（#RRGGBB），通常与肤色一致或略亮于肤色。\n"
                },
                "colorIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "全脸遮瑕的通用上色强度。\n"
                },
                "colorUnderEyeIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "眼周区域的专项上色控制，可在不过度覆盖其他区域的前提下提亮黑眼圈。\n"
                },
                "coverageLevel": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "决定遮瑕的遮盖力。取值越高，越能遮住色差与瑕疵。\n"
                }
              }
            }
          }
        },
        "example": {
          "category": "concealer",
          "palettes": [
            {
              "color": "#e6c7a8",
              "colorIntensity": 50,
              "colorUnderEyeIntensity": 50,
              "coverageLevel": 60
            }
          ]
        }
      },
      "ContourEffect": {
        "type": "object",
        "description": "按脸型定制的修容图案，用于塑造面部轮廓。 修容图案决定高光与阴影的位置，色板则控制修容深浅。\n",
        "required": [
          "category",
          "pattern",
          "palettes"
        ],
        "properties": {
          "category": {
            "type": "string",
            "enum": [
              "contour"
            ],
            "description": "标识该特效为修容特效，取值固定为 \"contour\"。\n"
          },
          "pattern": {
            "type": "object",
            "required": [
              "name"
            ],
            "description": "定义修容阴影落在脸上哪些位置，须使用 contour.json 中定义的图案名（例如 HeartFace2、OvalFace6）。\n",
            "properties": {
              "name": {
                "type": "string",
                "description": "修容图案名称，须与 contour.json 中的 `label` 一致。\n",
                "example": "OvalFace6"
              }
            }
          },
          "palettes": {
            "type": "array",
            "minItems": 1,
            "description": "定义修容所用色料，通常是比粉底更深、偏冷调或中性的色号。\n",
            "items": {
              "type": "object",
              "required": [
                "color",
                "colorIntensity"
              ],
              "properties": {
                "color": {
                  "type": "string",
                  "description": "修容色料颜色，#RRGGBB 十六进制格式。\n"
                },
                "colorIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "修容上色强度。取值越高，阴影越深。\n"
                }
              }
            }
          }
        },
        "example": {
          "category": "contour",
          "pattern": {
            "name": "OvalFace6"
          },
          "palettes": [
            {
              "color": "#8a5b3e",
              "colorIntensity": 55
            }
          ]
        }
      },
      "EyebrowsEffect": {
        "type": "object",
        "description": "用可自定义的几何形状与色板为眉毛塑形上色。 `pattern.type = shape` 时，图案定义眉形几何（眉峰、弯曲度、粗细）。 `pattern.type = color` 时，只改变色料。\n",
        "required": [
          "category",
          "pattern",
          "palettes"
        ],
        "properties": {
          "category": {
            "type": "string",
            "enum": [
              "eyebrows"
            ],
            "description": "标识该特效为眉部造型特效，取值固定为 \"eyebrows\"。\n"
          },
          "pattern": {
            "type": "object",
            "description": "此项定义眉部图案模式，可以改变眉形，也可以只上色。 需要指定图案时，名称须与 eyebrows.json 中的 label 一致。\n",
            "required": [
              "type"
            ],
            "oneOf": [
              {
                "title": "ShapePattern",
                "description": "按形状做眉形（可改眉形，颜色可选）。",
                "required": [
                  "name"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "shape"
                    ],
                    "description": "使用自定义眉形图案"
                  },
                  "name": {
                    "type": "string",
                    "description": "眉形图案名称，须与 eyebrows.json 中的 `label` 一致。\n",
                    "example": "SoftArch1"
                  },
                  "curvature": {
                    "type": "integer",
                    "minimum": -100,
                    "maximum": 100,
                    "description": "调整眉毛的弯曲程度。负值更平更直，正值更弯。\n"
                  },
                  "thickness": {
                    "type": "integer",
                    "minimum": -100,
                    "maximum": 100,
                    "description": "相对检测到的眉毛，控制眉毛粗细的调整幅度。正值加粗，负值变细。\n"
                  },
                  "definition": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "眉毛的清晰与利落程度。取值越高，眉缘越清楚，看起来越干净。\n"
                  }
                }
              },
              {
                "title": "ColorPattern",
                "description": "只调眉色（不改变眉形）。",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "color"
                    ],
                    "description": "使用用户原本的眉形"
                  }
                }
              }
            ]
          },
          "palettes": {
            "type": "array",
            "minItems": 1,
            "description": "眉部色板。每块色板控制色料，以及可选的闪片效果（仅用于 shimmer 质地）。\n",
            "items": {
              "type": "object",
              "required": [
                "color",
                "colorIntensity",
                "texture"
              ],
              "properties": {
                "color": {
                  "type": "string",
                  "description": "眉部色料颜色，#RRGGBB 格式。\n"
                },
                "colorIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "眉部上色时的上色强度。\n"
                },
                "texture": {
                  "type": "string",
                  "enum": [
                    "matte",
                    "shimmer"
                  ],
                  "description": "眉部色料的质地风格。shimmer 会给眉毛加入反光高光。\n"
                },
                "shimmerColor": {
                  "type": "string",
                  "description": "当质地为 shimmer 时所用的闪片颜色。\n"
                },
                "shimmerIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "闪片光泽强度，仅当质地为 shimmer 时必填。\n"
                },
                "shimmerSize": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "闪片颗粒大小，shimmer 质地时必填。\n"
                },
                "shimmerDensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "眉毛中闪片颗粒的密度，shimmer 质地时必填。\n"
                }
              }
            }
          }
        },
        "example": {
          "category": "eyebrows",
          "pattern": {
            "type": "shape",
            "name": "SoftArch1",
            "curvature": 10,
            "thickness": 5,
            "definition": 50
          },
          "palettes": [
            {
              "color": "#3b2f2f",
              "colorIntensity": 70,
              "texture": "matte"
            }
          ]
        }
      },
      "EyelinerEffect": {
        "type": "object",
        "description": "用自定义图案与色料设置画眼线。图案决定眼线的走向（例如阿拉伯式、上扬翅式）， 色板则指定颜色、质地、闪片/金属效果与强度。\n",
        "required": [
          "category",
          "pattern",
          "palettes"
        ],
        "properties": {
          "category": {
            "type": "string",
            "enum": [
              "eye_liner"
            ],
            "description": "标识该特效为眼线特效，取值固定为 \"eye_liner\"。\n"
          },
          "pattern": {
            "type": "object",
            "required": [
              "name"
            ],
            "description": "定义眼线的形状与位置，图案名称须与 eyeliner.json 中的 label 一致。\n",
            "properties": {
              "name": {
                "type": "string",
                "description": "眼线图案名称，须与 eyeliner.json 中的 label 一致。\n",
                "example": "Arabic3"
              }
            }
          },
          "palettes": {
            "type": "array",
            "minItems": 1,
            "description": "眼线色板条目。每块色板控制色料颜色、闪片/金属效果与整体强度。 所选眼线图案需要多种颜色时，会用到多块色板。\n",
            "items": {
              "type": "object",
              "required": [
                "color",
                "texture",
                "colorIntensity"
              ],
              "properties": {
                "color": {
                  "type": "string",
                  "description": "眼线色料颜色，#RRGGBB 格式。\n"
                },
                "texture": {
                  "type": "string",
                  "enum": [
                    "matte",
                    "shimmer",
                    "metallic"
                  ],
                  "description": "眼线质地决定观感：matte 是平实不透明的效果；shimmer 是闪亮反光的妆效（需配闪片字段）；metallic 是带金属光泽的亮泽妆效（需配闪片字段与金属强度）。\n"
                },
                "shimmerColor": {
                  "type": "string",
                  "description": "闪片或金属反光颗粒所用的颜色。质地为 shimmer 或 metallic 时必填。\n"
                },
                "shimmerIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "反光闪亮度。质地为 shimmer 或 metallic 时必填。\n"
                },
                "metallicIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "金属反光强度。质地为 metallic 时必填。\n"
                },
                "colorIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "眼线颜色的上色强度。\n"
                }
              }
            }
          }
        },
        "example": {
          "category": "eye_liner",
          "pattern": {
            "name": "Arabic3"
          },
          "palettes": [
            {
              "color": "#000000",
              "texture": "matte",
              "colorIntensity": 80
            }
          ]
        }
      },
      "EyeshadowEffect": {
        "type": "object",
        "description": "用可自定义的多色色板与质地画眼影。眼影图案决定布局（例如 1 到 5 色）， 色板决定上色强度与闪片/金属属性。\n",
        "required": [
          "category",
          "pattern",
          "palettes"
        ],
        "properties": {
          "category": {
            "type": "string",
            "enum": [
              "eye_shadow"
            ],
            "description": "标识该特效为眼影特效，取值固定为 \"eye_shadow\"。\n"
          },
          "pattern": {
            "type": "object",
            "required": [
              "name"
            ],
            "description": "定义眼影落位图案，须与 eyeshadow.json 中的 `label` 一致（例如 1color1、2colors1 等）。\n",
            "properties": {
              "name": {
                "type": "string",
                "description": "取自 eyeshadow.json 的图案名称，决定颜色数量与眼影的铺设区域。\n",
                "example": "2colors1"
              }
            }
          },
          "palettes": {
            "type": "array",
            "minItems": 1,
            "description": "一至多块色料色板。需要的色板数量取决于图案的 `colorNum`， 每块色板对应眼影图案中的一个层次/颜色。\n",
            "items": {
              "type": "object",
              "required": [
                "color",
                "texture",
                "colorIntensity"
              ],
              "properties": {
                "color": {
                  "type": "string",
                  "description": "眼影色料颜色，十六进制格式（#RRGGBB）。\n"
                },
                "texture": {
                  "type": "string",
                  "enum": [
                    "matte",
                    "shimmer",
                    "metallic"
                  ],
                  "description": "眼影的表面质感决定妆效：matte 平滑哑光；shimmer 闪亮（需配闪片参数）；metallic 强烈的金属光泽（需配闪片参数与金属强度）。\n"
                },
                "shimmerColor": {
                  "type": "string",
                  "description": "闪片颗粒的颜色。质地为 shimmer 或 metallic 时必填。\n"
                },
                "shimmerIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "shimmer 或 metallic 质地的反光闪亮度。\n"
                },
                "metallicIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "金属反光强度，metallic 质地时必填。\n"
                },
                "colorIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "每层眼影颜色的整体上色强度。\n"
                }
              }
            }
          }
        },
        "example": {
          "category": "eye_shadow",
          "pattern": {
            "name": "2colors1"
          },
          "palettes": [
            {
              "color": "#b07baf",
              "texture": "shimmer",
              "shimmerColor": "#f2d3f5",
              "shimmerIntensity": 60,
              "colorIntensity": 70
            },
            {
              "color": "#8e5c9c",
              "texture": "matte",
              "colorIntensity": 65
            }
          ]
        }
      },
      "EyelashesEffect": {
        "type": "object",
        "description": "把色料涂到检测到睫毛上，让睫毛更出彩。 睫毛加长与加密的效果取决于所选图案，色板则控制睫毛颜色与强度。\n",
        "required": [
          "category",
          "pattern",
          "palettes"
        ],
        "properties": {
          "category": {
            "type": "string",
            "enum": [
              "eyelashes"
            ],
            "description": "标识该特效为睫毛特效，取值固定为 \"eyelashes\"。\n"
          },
          "pattern": {
            "type": "object",
            "required": [
              "name"
            ],
            "description": "定义套用哪种睫毛样式（自然、艺术、上扬、上/下睫毛等），须与 eyelashes.json 中的 `label` 一致。\n",
            "properties": {
              "name": {
                "type": "string",
                "description": "睫毛图案名称，取自 eyelashes.json。\n",
                "example": "Upper1"
              }
            }
          },
          "palettes": {
            "type": "array",
            "minItems": 1,
            "description": "睫毛色板。 睫毛不支持闪片/金属效果，只有颜色与强度。\n",
            "items": {
              "type": "object",
              "required": [
                "color",
                "colorIntensity"
              ],
              "properties": {
                "color": {
                  "type": "string",
                  "description": "睫毛颜色，十六进制格式（#RRGGBB）。\n"
                },
                "colorIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "睫毛的上色深浅与强度。\n"
                }
              }
            }
          }
        },
        "example": {
          "category": "eyelashes",
          "pattern": {
            "name": "Upper1"
          },
          "palettes": [
            {
              "color": "#000000",
              "colorIntensity": 80
            }
          ]
        }
      },
      "FoundationEffect": {
        "type": "object",
        "description": "通过色料、遮盖力与光泽控制上粉底，均匀肤色。 与腮红/修容不同，粉底没有图案概念——它基于皮肤分割结果全脸施加。\n",
        "required": [
          "category",
          "palettes"
        ],
        "properties": {
          "category": {
            "type": "string",
            "enum": [
              "foundation"
            ],
            "description": "标识该特效为粉底特效，取值固定为 \"foundation\"。\n"
          },
          "palettes": {
            "type": "array",
            "minItems": 1,
            "description": "粉底色板条目，控制色调、遮盖力、光泽与上色强度。\n",
            "items": {
              "type": "object",
              "required": [
                "color",
                "colorIntensity",
                "glowIntensity",
                "coverageIntensity"
              ],
              "properties": {
                "color": {
                  "type": "string",
                  "description": "粉底色号，#RRGGBB 格式，通常接近自然肤色。\n"
                },
                "colorIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "粉底的上色强度。\n"
                },
                "glowIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "提升肌肤的光亮度。取值越高，越偏光泽感与水光感。\n"
                },
                "coverageIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "控制粉底的遮盖度。取值越高，遮住的瑕疵越多。\n"
                }
              }
            }
          }
        },
        "example": {
          "category": "foundation",
          "palettes": [
            {
              "color": "#eac595",
              "colorIntensity": 50,
              "glowIntensity": 10,
              "coverageIntensity": 50
            }
          ]
        }
      },
      "HighlighterEffect": {
        "type": "object",
        "description": "在面部高点（颧骨、唇峰、鼻梁等）加上反光高光。 图案按脸型决定高光落点；色板控制闪片、光泽、密度、颗粒大小与颜色。\n",
        "required": [
          "category",
          "pattern",
          "palettes"
        ],
        "properties": {
          "category": {
            "type": "string",
            "enum": [
              "highlighter"
            ],
            "description": "标识该特效为高光特效，取值固定为 \"highlighter\"。\n"
          },
          "pattern": {
            "type": "object",
            "required": [
              "name"
            ],
            "description": "高光落位图案，须与 highlighter.json 中的 `label` 一致（例如 HeartFace4、Oblong11、OvalFace2）。\n",
            "properties": {
              "name": {
                "type": "string",
                "description": "高光图案名称，取自 highlighter.json 目录。\n",
                "example": "SquareFace3"
              }
            }
          },
          "palettes": {
            "type": "array",
            "minItems": 1,
            "description": "高光色板条目，定义闪片、光泽、密度与颜色。\n",
            "items": {
              "type": "object",
              "required": [
                "color",
                "glowIntensity",
                "shimmerIntensity",
                "shimmerDensity",
                "shimmerSize",
                "colorIntensity"
              ],
              "properties": {
                "color": {
                  "type": "string",
                  "description": "高光色料颜色，#RRGGBB 十六进制格式，通常为白色、香槟色、金色或粉调。\n"
                },
                "glowIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "加到肌肤上的非闪片光泽量。取值越高，妆面越通透亮泽。\n"
                },
                "shimmerIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "闪片反光强度。取值越高越闪。\n"
                },
                "shimmerDensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "单位面积内的闪片数量。密度越高，越有亮片感。\n"
                },
                "shimmerSize": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "闪片颗粒大小。颗粒越大越像亮片，越小则是细闪。\n"
                },
                "colorIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "高光色料的颜色强度。\n"
                }
              }
            }
          }
        },
        "example": {
          "category": "highlighter",
          "pattern": {
            "name": "SquareFace3"
          },
          "palettes": [
            {
              "color": "#FFF7F8",
              "glowIntensity": 60,
              "shimmerIntensity": 50,
              "shimmerDensity": 40,
              "shimmerSize": 50,
              "colorIntensity": 50
            }
          ]
        }
      },
      "LipColorEffect": {
        "type": "object",
        "description": "涂口红，支持多种唇形、质地与风格。 可控制唇部形态（饱满度、唇纹）、质地（matte 哑光、gloss 唇蜜、metallic 金属、 shimmer 闪片、sheer 清透等）、闪片/光泽参数、多色图案，以及渐层与双色妆效。\n",
        "required": [
          "category",
          "shape",
          "palettes",
          "style"
        ],
        "properties": {
          "category": {
            "type": "string",
            "enum": [
              "lip_color"
            ],
            "description": "标识该特效为口红/唇色特效，取值固定为 \"lip_color\"。\n"
          },
          "shape": {
            "type": "object",
            "description": "定义唇部边界与形状调整。图案名称须与 lipshape.json 一致（例如 plump、original、pouty）。\n",
            "required": [
              "name"
            ],
            "properties": {
              "name": {
                "type": "string",
                "description": "用于调整唇缘与唇部轮廓的唇形样式，须与 lipshape.json 中的 `label` 一致。\n",
                "example": "plump"
              }
            }
          },
          "morphology": {
            "type": "object",
            "description": "可选的唇部形态调整，让嘴唇更饱满、唇纹更淡。\n",
            "properties": {
              "fullness": {
                "type": "integer",
                "default": 0,
                "minimum": 0,
                "maximum": 100,
                "description": "控制嘴唇的饱满程度。取值越高，唇形越饱满立体。\n"
              },
              "wrinkless": {
                "type": "integer",
                "default": 0,
                "minimum": 0,
                "maximum": 100,
                "description": "抚平唇纹与唇面纹理。取值越高，唇面越平滑。\n"
              }
            }
          },
          "palettes": {
            "type": "array",
            "minItems": 1,
            "description": "唇色色板条目，控制色料、质地、闪片与光泽。做渐层或双色妆效时可多用几块色板。\n",
            "items": {
              "type": "object",
              "required": [
                "color",
                "texture",
                "colorIntensity"
              ],
              "properties": {
                "color": {
                  "type": "string",
                  "description": "口红颜色，十六进制格式（#RRGGBB）。\n"
                },
                "texture": {
                  "type": "string",
                  "enum": [
                    "matte",
                    "gloss",
                    "holographic",
                    "metallic",
                    "satin",
                    "sheer",
                    "shimmer"
                  ],
                  "description": "此项指定唇部妆效的质地。选 gloss 就要带上光泽属性；选 shimmer、metallic 或 holographic 要加上闪片相关字段；选 sheer、shimmer 或 gloss 时，别忘了带上透明度强度。\n"
                },
                "colorIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "口红的上色强度。\n"
                },
                "gloss": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "gloss/holographic/metallic/sheer/shimmer 质地下的光泽度。\n"
                },
                "shimmerColor": {
                  "type": "string",
                  "description": "shimmer、metallic 或 holographic 质地中闪片颗粒的颜色。\n"
                },
                "shimmerIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "闪片的反光强度。\n"
                },
                "shimmerDensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "闪片颗粒的密度。\n"
                },
                "shimmerSize": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "闪片颗粒的大小。\n"
                },
                "transparencyIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "通透效果强度，用于 sheer、shimmer 或 gloss 质地。\n"
                }
              }
            }
          },
          "style": {
            "type": "object",
            "description": "风格描述唇色的整体观感：整片均匀色、渐层晕染，或在唇部不同区域用上对比色的双色效果。\n",
            "required": [
              "type"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "full",
                  "ombre",
                  "twoTone"
                ],
                "description": "唇色的上色风格。\n"
              },
              "innerColorRatio": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100,
                "description": "决定副色向内侧延伸的程度（仅渐层适用）。type 为 ombre 时必填。\n"
              },
              "blendStrength": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100,
                "description": "颜色之间的过渡柔和度。type 为 ombre 时必填。\n"
              }
            }
          }
        },
        "example": {
          "category": "lip_color",
          "shape": {
            "name": "plump"
          },
          "morphology": {
            "fullness": 20,
            "wrinkless": 10
          },
          "style": {
            "type": "full"
          },
          "palettes": [
            {
              "color": "#C2185B",
              "texture": "gloss",
              "colorIntensity": 80,
              "gloss": 70,
              "transparencyIntensity": 30
            }
          ]
        }
      },
      "LipLinerEffect": {
        "type": "object",
        "description": "沿唇缘画唇线，让唇形更清晰。 适合修饰唇缘、调整对称度，以及搭配渐层/双色妆效。\n",
        "required": [
          "category",
          "pattern",
          "palettes"
        ],
        "properties": {
          "category": {
            "type": "string",
            "enum": [
              "lip_liner"
            ],
            "description": "标识该特效为唇线特效，取值固定为 \"lip_liner\"。\n"
          },
          "pattern": {
            "type": "object",
            "required": [
              "name"
            ],
            "description": "按 lipliner.json 中的图案定义唇线的落位。\n",
            "properties": {
              "name": {
                "type": "string",
                "description": "唇线图案名称（例如 Natural1、LargerUpper1）。\n",
                "example": "Natural1"
              }
            }
          },
          "palettes": {
            "type": "array",
            "minItems": 1,
            "description": "唇线色板条目，定义颜色、粗细与平滑度。\n",
            "items": {
              "type": "object",
              "required": [
                "color",
                "texture",
                "colorIntensity",
                "thickness",
                "smoothness"
              ],
              "properties": {
                "color": {
                  "type": "string",
                  "description": "唇线色料颜色，十六进制格式。\n"
                },
                "texture": {
                  "type": "string",
                  "enum": [
                    "matte",
                    "satin"
                  ],
                  "description": "唇线的妆效类型。\n"
                },
                "colorIntensity": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "唇线的上色强度。\n"
                },
                "thickness": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "唇线笔画的粗细，取值越高轮廓越粗。\n"
                },
                "smoothness": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "笔画边缘的平滑度，取值越高线条越柔和、越融合。\n"
                }
              }
            }
          }
        },
        "example": {
          "category": "lip_liner",
          "pattern": {
            "name": "Natural1"
          },
          "palettes": [
            {
              "color": "#A63A50",
              "texture": "matte",
              "colorIntensity": 70,
              "thickness": 40,
              "smoothness": 50
            }
          ]
        }
      }
    },
    "responses": {
      "InvalidParameters": {
        "description": "请求参数无效",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "integer",
                  "example": 400,
                  "description": "响应状态"
                },
                "error": {
                  "type": "string",
                  "description": "错误信息",
                  "example": "The operation could not be completed"
                },
                "error_code": {
                  "type": "string",
                  "enum": [
                    "InvalidParameters"
                  ]
                }
              }
            }
          }
        }
      },
      "InvalidApiKey": {
        "description": "API 密钥无效、已停用或已过期",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "integer",
                  "example": 401,
                  "description": "响应状态"
                },
                "error_code": {
                  "type": "string",
                  "enum": [
                    "InvalidApiKey",
                    "InactiveApiKey",
                    "ExpiredApiKey"
                  ]
                }
              }
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "单位时间内请求过多"
      },
      "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": [
              "CreditInsufficiency",
              "InvalidStyleGroup",
              "InvalidStyle",
              "BadRequest",
              "InvalidParameters"
            ]
          }
        }
      },
      "TaskTimeout": {
        "description": "任务在预期时间内没有响应",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "integer",
                  "description": "响应状态",
                  "example": 500
                },
                "error_code": {
                  "type": "string",
                  "enum": [
                    "TaskTimeout"
                  ]
                }
              }
            }
          }
        }
      },
      "InvalidTaskId": {
        "description": "任务 ID 无效",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "integer",
                  "description": "响应状态",
                  "example": 400
                },
                "error_code": {
                  "type": "string",
                  "enum": [
                    "InvalidTaskId"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}