# AI 美甲虚拟试用 # 概览 AI 美甲虚拟试用接口为关注美甲的顾客带来一种全新的线上体验。购物者可以在网上试看各种美甲风格，从假指甲、亚克力指甲，到穿戴甲与甲油胶设计都涵盖。颜色与纹理不设上限，真甲、假甲都能轻松尝试不同造型。平台支持个性化试戴，风格随您切换，调整前后的对比一目了然。这套顺畅的接入方式让商品更容易被发现，靠精准、互动的预览效果，让顾客买得更有信心。 ## 接入指南 本指南将带您走完全流程： AI 美甲虚拟试用接口的流程： **需要鉴权：** `Authorization: Bearer YOUR_API_KEY` **流程步骤：** 1. **准备图片上传：** - 第一步是准备一张手背照片。 - 调用 File 接口 `/s2s/v2.0/file` 取得上传 URL 与对应的 `file_id` 。 - 用提供的上传 URL 把带指甲的手背照片上传上去。 2. **美甲样式设置方式：** - 先选一个合适的指甲颜色，也可以按您的喜好自定义甲形。 3. **发起 AI 任务并取得 Task ID：** - 把上传好的图片连同选好的特效配置，通过 HTTP POST 请求送到 `/s2s/v2.0/task/nail-vto` 。 - 响应会返回一个唯一的任务 ID，用于标识本次调用。 4. **轮询任务状态（持续检查）：** - 用取得的 `task_id` 通过 HTTP GET 请求定期轮询任务状态（例如 `GET /s2s/v2.0/task/nail-vto/${task_id}` ）。 - 持续留意： - `Task_status = "success"` （处理完成）。 - `Task_status = "error"` （视情况排查或重试）。 - 状态转为 success 后，按流程继续往下走。 这套规整的流程能顺畅对接用户输入、自动监控任务，并顺利取回结果。 --- * API Playground 用官方演练场交互式地体验和测试接口： **API Playground：** [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/) --- * 鉴权 - 请在请求头中以 **Bearer Token** 方式带上您的 API 密钥： ``` Authorization: Bearer YOUR_API_KEY ``` API Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。 1. 上传图片 您可以把文件直接上传到服务器，也可以在 VTO 任务参数中提供有效的图片 URL。 * 上传接口 ``` POST /s2s/v2.0/file ``` 如果您已有公开可访问的图片 URL，这一步可以跳过。 --- 1. 准备特效模板 * 共有四种设置模式可选： 1. 自定义颜色，并与您现有的指甲造型对齐 2. 使用预设设计搭配指定甲形，做出您想要的效果 3. 加上穿戴甲，并与您原本指甲图片贴合 4. 提供相符穿戴甲商品的图片链接 * 特效模板 JSON Schema ``` { "version": "1.0", "effect_type": "nail_polish", // valid values: ['nail_polish', 'press_on_nails'] "effects": [], "ref_file_ids": [] } ``` * 特效格式 - 甲油胶 - 颜色 ``` { "sub_type": "color", "finger": "index", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky'] "color": "#ff0000", "texture": "cream", // valid values: ['matte', 'cream', 'metallic', 'jelly', 'sheer', 'pearl', 'textured', 'shimmer_coarse', 'shimmer_fine'] "transparency": 0, // 0-100, for textures except metallic "reflection": 0, // 0-100 "contrast": 0, // 0-100 "roughness": 0, // 0-100 "shimmer_opacity": 0, // 0-100, for texture pearl "shimmer_size": 0, // 0-100, for texture shimmer_coarse and shimmer_fine "textured_size": 0, // 0-100, for texture textured } ``` - 甲油胶 - 设计 ``` { "sub_type": "design", "finger": "index", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky'] "ref_file_url": "", // Optional; Either ref_file_id or ref_file_url must be filled, but only one can be selected. "ref_file_index": 0, // This field is optional unless uploading is selected. Index corresponding to ref_file_ids under the root node "texture": "cream", // valid values: ['matte', 'cream', 'metallic', 'jelly', 'sheer', 'pearl', 'textured', 'shimmer_coarse', 'shimmer_fine'] "transparency": 0, // 0-100, only for textures except metallic "reflection": 0, // 0-100 "contrast": 0, // 0-100 "roughness": 0, // 0-100 "shimmer_opacity": 0, // 0-100, for texture pearl "shimmer_size": 0, // 0-100, for texture shimmer_coarse and shimmer_fine "textured_size": 0, // 0-100, for texture textured } ``` - 穿戴甲 - 颜色 * 最新可用的甲形取值见：https://plugins-media.makeupar.com/wcm-saas/shapes/nails.json ``` { "sub_type": "color", "finger": "index", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky'] "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], "length": 1.0, // 0.8-2.15, for shapes except original "color": "#ff0000", "texture": "cream", // valid values for other shapes: ['matte', 'cream', 'metallic'] "reflection": 0, // 0-100 "contrast": 0, // 0-100 "roughness": 0 // 0-100 } ``` - 穿戴甲 - 设计 ``` { "sub_type": "design", "finger": "index", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky'] "ref_file_url": "", // Optional; Either ref_file_id or ref_file_url must be filled, but only one can be selected. "ref_file_index": 0, // This field is optional unless uploading is selected. Index corresponding to ref_file_ids under the root node "texture": "cream", // valid values: ['matte', 'cream', 'metallic'] "reflection": 0, // 0-100 "contrast": 0, // 0-100 "roughness": 0, // 0-100 } ``` * 特效模板的设计逻辑 1. **判断特效类型** （ `press_on_nails` 与 `nail_polish` ）。 2. **逐一处理 `effects` 中的每一项：** *若 `sub_type === "color"`* → 直接映射各字段，缺失的纹理相关键用默认值补齐。 *若 `sub_type === "design"`* → - 用户提供 `ref_file_url` 时保留该 URL，并 **省略** `ref_file_index` 。 - 用户提供下标（ `ref_file_index` ）时，确认 `ref_file_ids` 存在且下标有效，然后设为 `"ref_file_id": ref_file_ids[index]` （选填——部分后端期望的是原始下标，而非 id）。 1. **规整数值范围** – 超出范围的值收敛到 0‑100 或长度上限。 2. **补齐缺失的选填键** 并填入默认值，让 Schema 校验通过。 3. **序列化** 最终对象为 JSON（紧凑格式，或便于排错的缩进格式）。 * 请求示例（可直接发送） ``` { "version": "1.0", "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/nail_user_photo_01_27d4260646.jpg", "effect_type": "press_on_nails", "ref_file_ids": [ "Ks3kh+1nPpVNm8iJb5374CWtBzkT4B44NPJwXbBKqVxfjK3xgCQ+hRt9MJXBFaud", "+Z7PSjuzigvsc3S/Yli1A4WN7c3J6NJHFqK2iUlqD2BfjK3xgCQ+hRt9MJXBFaud" ], "effects": [ { "sub_type": "design", "finger": "thumb", "texture": "cream", "reflection": 100, "contrast": 50, "roughness": 0, "ref_file_index": 0 }, { "sub_type": "design", "finger": "index", "texture": "cream", "reflection": 100, "contrast": 50, "roughness": 0, "ref_file_index": 1 }, { "sub_type": "design", "finger": "middle", "texture": "cream", "reflection": 100, "contrast": 50, "roughness": 0, "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_3_9ce2ddc47a.png" }, { "sub_type": "design", "finger": "pinky", "texture": "cream", "reflection": 100, "contrast": 50, "roughness": 0, "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_5_f6e46dd56f.png" }, { "sub_type": "design", "finger": "ring", "texture": "cream", "reflection": 100, "contrast": 50, "roughness": 0, "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_4_2103ca8cac.png" } ] } ``` 2. 创建美甲 VTO 任务并轮询结果 图片和完整的特效参数备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。 * 创建任务接口 ``` POST /s2s/v2.0/task/nail-vto ``` * 轮询接口 ``` GET /s2s/v2.0/task/nail-vto/{task_id} ``` --- ## 文件规格与错误码 * AI 美甲虚拟试用规格 **支持的指甲视角** 单张指甲图片，正面视角清楚、无遮挡。 | 项目 | 支持尺寸 | 支持文件大小 | 支持格式 | | --- | --- | --- | --- | | 美甲设计图 - 甲油胶 | * 271 px ≤ 宽 ≤ 542 px* 522 px ≤ 高 ≤ 1044 px* 至少 72ppi图片会从中央开始套用，虚拟试戴效果会随用户指甲长度而变化。 | ≤ 1MB | png | | 美甲设计图 - 穿戴甲 | * 271 px ≤ 宽 ≤ 542 px* 522 px ≤ 高 ≤ 1044 px* 0.5 ≤ 图片宽高比（高/宽）≤ 3.5* 至少 72ppi图片的内容、甲形与长度设置都会用于生成虚拟试戴效果。系统会检测用户指甲宽度以确保图片缩放恰当，建议为每根指甲分别制作符合正确宽高比的图片。请下载穿戴甲设计图示例，并参照图片规范了解更多细节。下载：[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（透明背景） | 穿戴甲设计图示例： ![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_press_on_nail_06_5_f6e46dd56f.png) [](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/youcamapi_press_on_nail_design_image_sample_de6bd64f20.png) --- **支持的手部视角** | 项目 | 支持尺寸 | 支持文件大小 | 支持格式 | | --- | --- | --- | --- | | 用户照片 | * 长边 ≤ 2048* 短边 ≥ 256 | ≤ 10MB | jpg/jpeg/png | * 输入图片中只支持一只手 * 手掌面积最好至少占输入图片的一半 * 输入图片的宽高比最好是 1:1、3:4、4:3 * 手指甲不得被遮挡 * 指甲上最好没有甲片与甲油 ![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_nail_user_photo_02_fdba1848d6.jpg) --- * 错误码 | 错误码 | 说明 | | --- | --- | | error_nail_too_small | 指甲区域太小。 | | error_no_nail | 源图中未检测到指甲。 | * 运行环境与依赖 | 示例代码语言 / 工具 | 建议运行时版本 | | --- | --- | | cURL | - bash >= 3.2 - curl >= 7.58 (modern TLS/HTTP support) - jq >= 1.6 (robust JSON parsing) | | Node.js (JavaScript) | Node >= 18 (for global fetch) | | JavaScript | - Chrome / Edge >= 80 - Firefox >= 74 - Safari >= 13.1 | | PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) or allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (for f-strings), requests >= 2.20.0 | | Java | Java 11+ (for HttpClient), Jackson Databind >= 2.12.0 | --- ## JS Camera Kit --- ## 点数消耗 | AI 功能 | 消耗点数 | | --- | --- | | AI 美甲虚拟试用 | 1 | --- License: Privacy policy ## Servers ``` https://yce-api-01.makeupar.com ``` ## Security ### BearerAuthenticationV2 使用标准的 Bearer 鉴权。把您的 API 密钥放进请求头： `Authorization:Bearer YOUR_API_KEY`。请注意 'Bearer' 与 'YOUR_API_KEY' 之间有一个空格。 Type: http Scheme: bearer ## Download OpenAPI description - [AI 美甲虚拟试用](https://docs.perfectcorp.com/_bundle/@l10n/zh-CN/reference/ai_nail_vto.yaml) ## V1.0 - [POST /s2s/v2.0/task/nail-vto](https://docs.perfectcorp.com/zh-cn/reference/ai_nail_vto/v1.0/paths/~1s2s~1v2.0~1task~1nail-vto/post.md): 本接口用于发起 AI 美甲虚拟试用流程。您需要提供源文件与参考图（URL 或文件 ID），以及具体的美甲特效配置。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。 - [GET /s2s/v2.0/task/nail-vto/{task_id}](https://docs.perfectcorp.com/zh-cn/reference/ai_nail_vto/v1.0/paths/~1s2s~1v2.0~1task~1nail-vto~1%7Btask_id%7D/get.md)