{
  "openapi": "3.0.0",
  "info": {
    "title": "AI 美甲虚拟试用",
    "description": "# 概览\nAI 美甲虚拟试用接口为关注美甲的顾客带来一种全新的线上体验。购物者可以在网上试看各种美甲风格，从假指甲、亚克力指甲，到穿戴甲与甲油胶设计都涵盖。颜色与纹理不设上限，真甲、假甲都能轻松尝试不同造型。平台支持个性化试戴，风格随您切换，调整前后的对比一目了然。这套顺畅的接入方式让商品更容易被发现，靠精准、互动的预览效果，让顾客买得更有信心。\n\n## 接入指南\n本指南将带您走完全流程：\n\nAI 美甲虚拟试用接口的流程：\n\n**需要鉴权：** `Authorization: Bearer YOUR_API_KEY`\n\n**流程步骤：**\n\n1. **准备图片上传：**\n    - 第一步是准备一张手背照片。\n    - 调用 File 接口 `/s2s/v2.0/file` 取得上传 URL 与对应的 `file_id`。\n    - 用提供的上传 URL 把带指甲的手背照片上传上去。\n\n2. **美甲样式设置方式：**\n    - 先选一个合适的指甲颜色，也可以按您的喜好自定义甲形。\n\n3. **发起 AI 任务并取得 Task ID：**\n    - 把上传好的图片连同选好的特效配置，通过 HTTP POST 请求送到 `/s2s/v2.0/task/nail-vto`。\n    - 响应会返回一个唯一的任务 ID，用于标识本次调用。\n\n4. **轮询任务状态（持续检查）：**\n    - 用取得的 `task_id` 通过 HTTP GET 请求定期轮询任务状态（例如 `GET /s2s/v2.0/task/nail-vto/${task_id}`）。\n    - 持续留意：\n        - `Task_status = \"success\"`（处理完成）。\n        - `Task_status = \"error\"`（视情况排查或重试）。\n    - 状态转为 success 后，按流程继续往下走。\n\n这套规整的流程能顺畅对接用户输入、自动监控任务，并顺利取回结果。\n\n---\n\n* API Playground\n\n用官方演练场交互式地体验和测试接口：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-nail-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-nail-virtual-try-on/)\n\n---\n\n* 鉴权\n- 请在请求头中以 **Bearer Token** 方式带上您的 API 密钥：\n    ```\n    Authorization: Bearer YOUR_API_KEY\n    ```\nAPI Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。\n\n\n1. 上传图片\n\n    您可以把文件直接上传到服务器，也可以在 VTO 任务参数中提供有效的图片 URL。\n\n    * 上传接口\n\n        ```\n        POST /s2s/v2.0/file\n        ```\n\n    如果您已有公开可访问的图片 URL，这一步可以跳过。\n\n---\n\n2. 准备特效模板\n\n    * 共有四种设置模式可选：\n        1. 自定义颜色，并与您现有的指甲造型对齐\n        2. 使用预设设计搭配指定甲形，做出您想要的效果\n        3. 加上穿戴甲，并与您原本指甲图片贴合\n        4. 提供相符穿戴甲商品的图片链接\n\n    * 特效模板 JSON Schema\n        ```\n        {\n            \"version\": \"1.0\",\n            \"effect_type\": \"nail_polish\", // valid values: ['nail_polish', 'press_on_nails']\n            \"effects\": [],\n            \"ref_file_ids\": []\n        }\n        ```\n\n        * 特效格式\n            - 甲油胶 - 颜色\n            ```\n            {\n                \"sub_type\": \"color\",\n                \"finger\": \"index\", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']\n                \"color\": \"#ff0000\",\n                \"texture\": \"cream\", // valid values: ['matte', 'cream', 'metallic', 'jelly', 'sheer', 'pearl', 'textured', 'shimmer_coarse', 'shimmer_fine']\n                \"transparency\": 0, // 0-100, for textures except metallic\n                \"reflection\": 0, // 0-100\n                \"contrast\": 0, // 0-100\n                \"roughness\": 0, // 0-100\n                \"shimmer_opacity\": 0, // 0-100, for texture pearl\n                \"shimmer_size\": 0, // 0-100, for texture shimmer_coarse and shimmer_fine\n                \"textured_size\": 0, // 0-100, for texture textured\n            }\n            ```\n\n            - 甲油胶 - 设计\n            ```\n            {\n                \"sub_type\": \"design\",\n                \"finger\": \"index\", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']\n                \"ref_file_url\": \"\",  // Optional; Either ref_file_id or ref_file_url must be filled, but only one can be selected.\n                \"ref_file_index\": 0, // This field is optional unless uploading is selected. Index corresponding to ref_file_ids under the root node\n                \"texture\": \"cream\", // valid values: ['matte', 'cream', 'metallic', 'jelly', 'sheer', 'pearl', 'textured', 'shimmer_coarse', 'shimmer_fine']\n                \"transparency\": 0, // 0-100, only for textures except metallic\n                \"reflection\": 0, // 0-100\n                \"contrast\": 0, // 0-100\n                \"roughness\": 0, // 0-100\n                \"shimmer_opacity\": 0, // 0-100, for texture pearl\n                \"shimmer_size\": 0, // 0-100, for texture shimmer_coarse and shimmer_fine\n                \"textured_size\": 0, // 0-100, for texture textured\n            }\n\n            ```\n\n            - 穿戴甲 - 颜色\n            * 最新可用的甲形取值见：https://plugins-media.makeupar.com/wcm-saas/shapes/nails.json\n            ```\n            {\n                \"sub_type\": \"color\",\n                \"finger\": \"index\", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']\n                \"shape\": \"square_oval\", // Please check the nails.json. valid values: ['square_oval','square_square','square_squoval','squoval_oval','squoval_square','squoval_squoval','oval_oval','oval_square','oval_squoval','almond_oval','almond_square','almond_squoval','stiletto_oval','stiletto_square','stiletto_squoval],\n                \"length\": 1.0, // 0.8-2.15, for shapes except original\n                \"color\": \"#ff0000\",\n                \"texture\": \"cream\", // valid values for other shapes: ['matte', 'cream', 'metallic']\n                \"reflection\": 0, // 0-100\n                \"contrast\": 0, // 0-100\n                \"roughness\": 0 // 0-100\n            }\n            ```\n\n            - 穿戴甲 - 设计\n            ```\n            {\n                \"sub_type\": \"design\",\n                \"finger\": \"index\", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']\n                \"ref_file_url\": \"\",  // Optional; Either ref_file_id or ref_file_url must be filled, but only one can be selected.\n                \"ref_file_index\": 0, // This field is optional unless uploading is selected. Index corresponding to ref_file_ids under the root node\n                \"texture\": \"cream\", // valid values: ['matte', 'cream', 'metallic']\n                \"reflection\": 0, // 0-100\n                \"contrast\": 0, // 0-100\n                \"roughness\": 0, // 0-100\n            }\n\n            ```\n\n   * 特效模板的设计逻辑\n\n        1. **判断特效类型**（`press_on_nails` 与 `nail_polish`）。\n        2. **逐一处理 `effects` 中的每一项：**\n\n        *若 `sub_type === \"color\"`* → 直接映射各字段，缺失的纹理相关键用默认值补齐。\n        *若 `sub_type === \"design\"`* →\n        - 用户提供 `ref_file_url` 时保留该 URL，并**省略** `ref_file_index`。\n        - 用户提供下标（`ref_file_index`）时，确认 `ref_file_ids` 存在且下标有效，然后设为 `\"ref_file_id\": ref_file_ids[index]`（选填——部分后端期望的是原始下标，而非 id）。\n\n        1. **规整数值范围** – 超出范围的值收敛到 0‑100 或长度上限。\n        2. **补齐缺失的选填键** 并填入默认值，让 Schema 校验通过。\n        3. **序列化** 最终对象为 JSON（紧凑格式，或便于排错的缩进格式）。\n\n   * 请求示例（可直接发送）\n        ```\n        {\n        \"version\": \"1.0\",\n        \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/nail_user_photo_01_27d4260646.jpg\",\n        \"effect_type\": \"press_on_nails\",\n        \"ref_file_ids\": [\n            \"Ks3kh+1nPpVNm8iJb5374CWtBzkT4B44NPJwXbBKqVxfjK3xgCQ+hRt9MJXBFaud\",\n            \"+Z7PSjuzigvsc3S/Yli1A4WN7c3J6NJHFqK2iUlqD2BfjK3xgCQ+hRt9MJXBFaud\"\n        ],\n        \"effects\": [\n            {\n            \"sub_type\": \"design\",\n            \"finger\": \"thumb\",\n            \"texture\": \"cream\",\n            \"reflection\": 100,\n            \"contrast\": 50,\n            \"roughness\": 0,\n            \"ref_file_index\": 0\n            },\n            {\n            \"sub_type\": \"design\",\n            \"finger\": \"index\",\n            \"texture\": \"cream\",\n            \"reflection\": 100,\n            \"contrast\": 50,\n            \"roughness\": 0,\n            \"ref_file_index\": 1\n            },\n            {\n            \"sub_type\": \"design\",\n            \"finger\": \"middle\",\n            \"texture\": \"cream\",\n            \"reflection\": 100,\n            \"contrast\": 50,\n            \"roughness\": 0,\n            \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_3_9ce2ddc47a.png\"\n            },\n            {\n            \"sub_type\": \"design\",\n            \"finger\": \"pinky\",\n            \"texture\": \"cream\",\n            \"reflection\": 100,\n            \"contrast\": 50,\n            \"roughness\": 0,\n            \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_5_f6e46dd56f.png\"\n            },\n            {\n            \"sub_type\": \"design\",\n            \"finger\": \"ring\",\n            \"texture\": \"cream\",\n            \"reflection\": 100,\n            \"contrast\": 50,\n            \"roughness\": 0,\n            \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_4_2103ca8cac.png\"\n            }\n        ]\n        }\n        ```\n\n\n3. 创建美甲 VTO 任务并轮询结果\n\n    图片和完整的特效参数备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。\n\n    * 创建任务接口\n\n        ```\n        POST /s2s/v2.0/task/nail-vto\n        ```\n\n    * 轮询接口\n\n        ```\n        GET /s2s/v2.0/task/nail-vto/{task_id}\n        ```\n\n---\n\n## 文件规格与错误码\n\n* AI 美甲虚拟试用规格\n\n**支持的指甲视角**\n单张指甲图片，正面视角清楚、无遮挡。\n\n| 项目 | 支持尺寸 | 支持文件大小 | 支持格式 |\n| --- | --- | --- | --- |\n| 美甲设计图 - 甲油胶 | *   271 px ≤ 宽 ≤ 542 px<br>*   522 px ≤ 高 ≤ 1044 px<br>*   至少 72ppi<br>图片会从中央开始套用，虚拟试戴效果会随用户指甲长度而变化。 | ≤ 1MB | png |\n| 美甲设计图 - 穿戴甲 | *   271 px ≤ 宽 ≤ 542 px<br>*   522 px ≤ 高 ≤ 1044 px<br>*   0.5 ≤ 图片宽高比（高/宽）≤ 3.5<br>*   至少 72ppi<br>图片的内容、甲形与长度设置都会用于生成虚拟试戴效果。<br>系统会检测用户指甲宽度以确保图片缩放恰当，建议为每根指甲分别制作符合正确宽高比的图片。<br>请下载穿戴甲设计图示例，并参照图片规范了解更多细节。下载：[Nail_Design_Image_Guidelines.pdf](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/You_Cam_API_AI_Nail_Virtual_Try_On_Press_on_Nail_Design_Image_Guidelines_a229b51750.pdf) | ≤ 1MB​ | png（透明背景） |\n\n穿戴甲设计图示例：\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_press_on_nail_06_5_f6e46dd56f.png)\n\n[<img src=\"https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/youcamapi_press_on_nail_design_image_sample_de6bd64f20.png\" width=\"60\"/>](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/youcamapi_press_on_nail_design_image_sample_de6bd64f20.png)\n\n---\n\n**支持的手部视角**\n\n| 项目 | 支持尺寸 | 支持文件大小 | 支持格式 |\n| --- | --- | --- | --- |\n| 用户照片 | *   长边 ≤ 2048<br>*   短边 ≥ 256 | ≤ 10MB | jpg/jpeg/png |\n* 输入图片中只支持一只手\n* 手掌面积最好至少占输入图片的一半\n* 输入图片的宽高比最好是 1:1、3:4、4:3\n* 手指甲不得被遮挡\n* 指甲上最好没有甲片与甲油\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_nail_user_photo_02_fdba1848d6.jpg)\n\n---\n\n* 错误码\n\n| 错误码 | 说明 |\n|  ----  | ----  |\n| error_nail_too_small | 指甲区域太小。 |\n| error_no_nail\t| 源图中未检测到指甲。 |\n\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 美甲虚拟试用 | 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"
    }
  ],
  "tags": [
    {
      "name": "V1.0",
      "description": "用 AI 处理上传的图片，生成指甲油与穿戴甲虚拟试戴体验。"
    }
  ],
  "paths": {
    "/s2s/v2.0/task/nail-vto": {
      "post": {
        "summary": "执行 AI 美甲虚拟试用 任务。",
        "description": "本接口用于发起 AI 美甲虚拟试用流程。您需要提供源文件与参考图（URL 或文件 ID），以及具体的美甲特效配置。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。\n",
        "tags": [
          "V1.0"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NailVtoTaskRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "任务执行成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BasicRunTaskResponseV2"
                }
              }
            }
          },
          "400": {
            "description": "任务执行失败",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/RunError"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/s2s/v2.0/task/nail-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": {
      "NailVtoTaskRequest": {
        "title": "Nail VTO Task Request",
        "type": "object",
        "allOf": [
          {
            "$ref": "#/components/schemas/BasicRunTaskV2WithMultiRef"
          },
          {
            "type": "object",
            "required": [
              "version",
              "effect_type",
              "effects"
            ],
            "properties": {
              "version": {
                "type": "string",
                "description": "美甲特效规格的版本号。\n未特别指定时默认为 `\"1.0\"`。\n",
                "default": "1.0",
                "example": "1.0"
              },
              "effect_type": {
                "type": "string",
                "enum": [
                  "nail_polish",
                  "press_on_nails"
                ],
                "example": "nail_polish"
              },
              "effects": {
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/NailVtoNailPolishColorEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoNailPolishColorMetallicEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoNailPolishColorPearlEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoNailPolishColorShimmerEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoNailPolishColorTexturedEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoNailPolishDesignEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoNailPolishDesignMetallicEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoNailPolishDesignPearlEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoNailPolishDesignShimmerEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoNailPolishDesignTexturedEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoPressOnNailsColorEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoPressOnNailsDesignEffect"
                    }
                  ]
                }
              }
            }
          }
        ]
      },
      "NailVtoNailPolishColorBaseEffect": {
        "type": "object",
        "required": [
          "sub_type",
          "finger",
          "color",
          "texture",
          "reflection",
          "contrast",
          "roughness"
        ],
        "properties": {
          "sub_type": {
            "type": "string",
            "enum": [
              "color"
            ]
          },
          "finger": {
            "type": "string",
            "enum": [
              "thumb",
              "index",
              "middle",
              "ring",
              "pinky"
            ]
          },
          "color": {
            "type": "string",
            "pattern": "^#([A-Fa-f0-9]{6})$"
          },
          "texture": {
            "type": "string"
          },
          "reflection": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "contrast": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "roughness": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          }
        }
      },
      "NailVtoNailPolishColorEffect": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NailVtoNailPolishColorBaseEffect"
          },
          {
            "title": "指甲油 - 纯色 - 常规",
            "type": "object",
            "required": [
              "transparency"
            ],
            "properties": {
              "texture": {
                "type": "string",
                "enum": [
                  "matte",
                  "cream",
                  "jelly",
                  "sheer"
                ]
              },
              "transparency": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        ]
      },
      "NailVtoNailPolishColorMetallicEffect": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NailVtoNailPolishColorBaseEffect"
          },
          {
            "title": "指甲油 - 纯色 - 金属",
            "type": "object",
            "properties": {
              "texture": {
                "type": "string",
                "enum": [
                  "metallic"
                ]
              }
            }
          }
        ]
      },
      "NailVtoNailPolishColorPearlEffect": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NailVtoNailPolishColorBaseEffect"
          },
          {
            "title": "指甲油 - 纯色 - 珠光",
            "type": "object",
            "required": [
              "shimmer_opacity",
              "transparency"
            ],
            "properties": {
              "texture": {
                "type": "string",
                "enum": [
                  "pearl"
                ]
              },
              "transparency": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "shimmer_opacity": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        ]
      },
      "NailVtoNailPolishColorShimmerEffect": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NailVtoNailPolishColorBaseEffect"
          },
          {
            "title": "指甲油 - 纯色 - 闪片",
            "type": "object",
            "required": [
              "shimmer_size",
              "transparency"
            ],
            "properties": {
              "texture": {
                "type": "string",
                "enum": [
                  "shimmer_coarse",
                  "shimmer_fine"
                ]
              },
              "transparency": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "shimmer_size": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        ]
      },
      "NailVtoNailPolishColorTexturedEffect": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NailVtoNailPolishColorBaseEffect"
          },
          {
            "title": "指甲油 - 纯色 - 纹理",
            "type": "object",
            "required": [
              "textured_size",
              "transparency"
            ],
            "properties": {
              "texture": {
                "type": "string",
                "enum": [
                  "textured"
                ]
              },
              "transparency": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "textured_size": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        ]
      },
      "NailVtoNailPolishDesignBaseEffect": {
        "type": "object",
        "required": [
          "sub_type",
          "finger",
          "texture",
          "reflection",
          "contrast",
          "roughness"
        ],
        "properties": {
          "sub_type": {
            "type": "string",
            "enum": [
              "design"
            ]
          },
          "finger": {
            "type": "string",
            "enum": [
              "thumb",
              "index",
              "middle",
              "ring",
              "pinky"
            ]
          },
          "ref_file_url": {
            "type": "string",
            "description": "要做「指甲油 - 图案」或「穿戴甲 - 图案」效果，需要指定一张图案图。您可以直接给出图片 URL（ref_file_url），或给出与系统根节点下 'ref_file_ids' 对应的下标（ref_file_index）。两者必填其一，且一次只能选一个。\n"
          },
          "ref_file_index": {
            "type": "integer",
            "description": "如果想用 File API 上传图案图来做「指甲油 - 图案」或「穿戴甲 - 图案」效果，请先用 File API 把图片上传，取得文件 ID 后加入 `ref_file_ids` 数组，并用 `ref_file_index` 指明下标。其值对应根节点下 'ref_file_ids' 的下标。\n"
          },
          "texture": {
            "type": "string"
          },
          "reflection": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "contrast": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "roughness": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          }
        }
      },
      "NailVtoNailPolishDesignEffect": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NailVtoNailPolishDesignBaseEffect"
          },
          {
            "title": "指甲油 - 图案 - 常规",
            "type": "object",
            "required": [
              "transparency"
            ],
            "properties": {
              "texture": {
                "type": "string",
                "enum": [
                  "matte",
                  "cream",
                  "jelly",
                  "sheer"
                ]
              },
              "transparency": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        ]
      },
      "NailVtoNailPolishDesignMetallicEffect": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NailVtoNailPolishDesignBaseEffect"
          },
          {
            "title": "指甲油 - 图案 - 金属",
            "type": "object",
            "properties": {
              "texture": {
                "type": "string",
                "enum": [
                  "metallic"
                ]
              }
            }
          }
        ]
      },
      "NailVtoNailPolishDesignPearlEffect": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NailVtoNailPolishDesignBaseEffect"
          },
          {
            "title": "指甲油 - 图案 - 珠光",
            "type": "object",
            "required": [
              "shimmer_opacity",
              "transparency"
            ],
            "properties": {
              "texture": {
                "type": "string",
                "enum": [
                  "pearl"
                ]
              },
              "shimmer_opacity": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "transparency": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        ]
      },
      "NailVtoNailPolishDesignShimmerEffect": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NailVtoNailPolishDesignBaseEffect"
          },
          {
            "title": "指甲油 - 图案 - 闪片",
            "type": "object",
            "required": [
              "shimmer_size",
              "transparency"
            ],
            "properties": {
              "texture": {
                "type": "string",
                "enum": [
                  "shimmer_coarse",
                  "shimmer_fine"
                ]
              },
              "shimmer_size": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "transparency": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        ]
      },
      "NailVtoNailPolishDesignTexturedEffect": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NailVtoNailPolishDesignBaseEffect"
          },
          {
            "title": "指甲油 - 图案 - 纹理",
            "type": "object",
            "required": [
              "textured_size",
              "transparency"
            ],
            "properties": {
              "texture": {
                "type": "string",
                "enum": [
                  "textured"
                ]
              },
              "textured_size": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "transparency": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        ]
      },
      "NailVtoPressOnNailsColorEffect": {
        "title": "穿戴甲 - 纯色",
        "type": "object",
        "required": [
          "sub_type",
          "finger",
          "shape",
          "length",
          "color",
          "texture",
          "reflection",
          "contrast",
          "roughness"
        ],
        "properties": {
          "sub_type": {
            "type": "string",
            "enum": [
              "color"
            ]
          },
          "finger": {
            "type": "string",
            "enum": [
              "thumb",
              "index",
              "middle",
              "ring",
              "pinky"
            ]
          },
          "shape": {
            "type": "string",
            "enum": [
              "square_oval",
              "square_square",
              "square_squoval",
              "squoval_oval",
              "squoval_square",
              "squoval_squoval",
              "oval_oval",
              "oval_square",
              "oval_squoval",
              "almond_oval",
              "almond_square",
              "almond_squoval",
              "stiletto_oval",
              "stiletto_square",
              "stiletto_squoval"
            ]
          },
          "length": {
            "type": "number",
            "minimum": 0.8,
            "maximum": 2.15
          },
          "color": {
            "type": "string",
            "pattern": "^#([A-Fa-f0-9]{6})$"
          },
          "texture": {
            "type": "string",
            "enum": [
              "matte",
              "cream",
              "metallic"
            ]
          },
          "reflection": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "contrast": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "roughness": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          }
        }
      },
      "NailVtoPressOnNailsDesignEffect": {
        "title": "穿戴甲 - 图案",
        "type": "object",
        "required": [
          "sub_type",
          "finger",
          "texture",
          "reflection",
          "contrast",
          "roughness"
        ],
        "properties": {
          "sub_type": {
            "type": "string",
            "enum": [
              "design"
            ]
          },
          "finger": {
            "type": "string",
            "enum": [
              "thumb",
              "index",
              "middle",
              "ring",
              "pinky"
            ]
          },
          "ref_file_url": {
            "type": "string",
            "description": "'ref_file_id' 与 'ref_file_url' 二者必填其一，且只能选一个。"
          },
          "ref_file_index": {
            "type": "integer",
            "description": "除非选择上传方式，此字段可省略。其值对应根节点下 'ref_file_ids' 的下标。"
          },
          "texture": {
            "type": "string",
            "enum": [
              "matte",
              "cream",
              "metallic"
            ]
          },
          "reflection": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "contrast": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "roughness": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          }
        }
      },
      "BasicRunTaskV2SrcFileUrl": {
        "type": "object",
        "required": [
          "src_file_url"
        ],
        "properties": {
          "src_file_url": {
            "type": "string",
            "description": "用于运行任务的文件 URL，该 URL 需可公开访问。",
            "example": "https://example.com/selfie.jpg"
          }
        }
      },
      "BasicRunTaskV2RefFileUrls": {
        "type": "object",
        "properties": {
          "ref_file_urls": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "description": "用于运行任务的参考文件 URL，该 URL 需可公开访问。",
              "example": "https://example.com/accessory.jpg"
            }
          }
        }
      },
      "BasicRunTaskV2RefFileIds": {
        "type": "object",
        "properties": {
          "ref_file_ids": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "description": "用于运行任务的参考文件 ID 列表，取自上传文件接口返回的 file_id。",
              "example": "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE="
            }
          }
        }
      },
      "BasicRunTaskV2SrcFileId": {
        "type": "object",
        "required": [
          "src_file_id"
        ],
        "properties": {
          "src_file_id": {
            "type": "string",
            "description": "用于运行任务的文件 ID，取自上传文件接口返回的 file_id。",
            "example": "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE="
          }
        }
      },
      "BasicRunTaskV2WithMultiRef": {
        "title": "BasicRunTaskV2WithRef",
        "anyOf": [
          {
            "allOf": [
              {
                "title": "以源文件 URL 与多张参考文件 URL 运行任务"
              },
              {
                "$ref": "#/components/schemas/BasicRunTaskV2SrcFileUrl"
              },
              {
                "$ref": "#/components/schemas/BasicRunTaskV2RefFileUrls"
              }
            ]
          },
          {
            "allOf": [
              {
                "title": "以源文件 URL 与多张参考文件 ID 运行任务"
              },
              {
                "$ref": "#/components/schemas/BasicRunTaskV2SrcFileUrl"
              },
              {
                "$ref": "#/components/schemas/BasicRunTaskV2RefFileIds"
              }
            ]
          },
          {
            "allOf": [
              {
                "title": "以源文件 ID 与多张参考文件 URL 运行任务"
              },
              {
                "$ref": "#/components/schemas/BasicRunTaskV2SrcFileId"
              },
              {
                "$ref": "#/components/schemas/BasicRunTaskV2RefFileUrls"
              }
            ]
          },
          {
            "allOf": [
              {
                "title": "以源文件 ID 与多张参考文件 ID 运行任务"
              },
              {
                "$ref": "#/components/schemas/BasicRunTaskV2SrcFileId"
              },
              {
                "$ref": "#/components/schemas/BasicRunTaskV2RefFileIds"
              }
            ]
          }
        ]
      },
      "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"
      },
      "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": null
            }
          }
        },
        "$ref": "#/components/schemas/TaskStatusResponseBodySingleUrlResultsV2"
      }
    },
    "responses": {
      "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"
                }
              }
            }
          }
        }
      }
    }
  }
}