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/

• 鉴权

• 请在请求头中以 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，这一步可以跳过。

2. 准备特效模板

   • 共有四种设置模式可选：

     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"
         }
     ]
     }

3. 创建美甲 VTO 任务并轮询结果

   图片和完整的特效参数备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 success 或 error。

   • 创建任务接口

     POST /s2s/v2.0/task/nail-vto

   • 轮询接口

     GET /s2s/v2.0/task/nail-vto/{task_id}

文件规格与错误码

• AI 美甲虚拟试用规格

支持的指甲视角 单张指甲图片，正面视角清楚、无遮挡。

穿戴甲设计图示例：

支持的手部视角

• 输入图片中只支持一只手
• 手掌面积最好至少占输入图片的一半
• 输入图片的宽高比最好是 1:1、3:4、4:3
• 手指甲不得被遮挡
• 指甲上最好没有甲片与甲油

• 错误码

• 运行环境与依赖

JS Camera Kit

点数消耗