AI 戒指虚拟试戴
本指南将带您走完全流程：
- 接口地址：
/s2s/v2.0/task/2d-vto/ring - 鉴权： 所有请求都需要
Authorization: Bearer YOUR_API_KEY - 流程：
- 准备手部图片： 上传一张手部图片，或提供有效的手部图片 URL
- 准备戒指图片： 上传一张戒指商品图片，或提供有效的商品图片 URL
- 发起 AI 任务并获取 Task ID： 从响应中取到
task_id。 - 轮询状态（
GET）： 用task_id查询任务状态，持续轮询直到task_status为"success"或"error"。
- API Playground
用官方在线调试台交互式地体验与测试接口：
- 鉴权
- 请在请求头中以 Bearer Token 方式带上您的 API 密钥：
Authorization: Bearer YOUR_API_KEY
API Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。
- 上传图片
您可以把文件直接上传到服务器，也可以在 VTO 任务参数中提供有效的图片 URL。
- 上传接口
POST /s2s/v2.0/file如果您已有公开可访问的图片 URL，这一步可以跳过。
您可以把文件上传到 File 接口响应中给出的 URL，之后调用 AI 任务时使用 File 接口返回的 src_file_id；也可以在 VTO 任务参数中以 src_file_url 提供有效的图片 URL。src_file_id 或 src_file_url 就是虚拟试戴的目标图。
您还需用 ref_file_ids 或 ref_file_urls 提供一张戒指商品图作为参考，套用到您的 src_file_id 或 src_file_url 上。
AI 引擎支持自动去除戒指商品图的背景。您也可以为手部（srcmsk_file_id 或 srcmsk_file_url）或戒指商品（refmsk_file_ids 或 refmsk_file_urls）提供遮挡蒙版图，用于微调分割效果。
- 创建 AI 戒指虚拟试戴任务并轮询结果
图片和模板 ID 备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 success 或 error。
- 创建任务接口
POST /s2s/v2.0/task/2d-vto/ring- 轮询接口
GET /s2s/v2.0/task/2d-vto/ring/{task_id}- AI 戒指虚拟试戴规格
支持的戒指图视角 戒指图需采用斜前方视角（约 45 度）。
支持的手部图视角 手背需完整可见，五根手指清晰可辨，且无任何遮挡。
ring_wearing_finger: integer（0–4） 指定戒指戴在哪根手指上： 0 = 拇指 1 = 食指 2 = 中指 3 = 无名指 4 = 小指
ring_wearing_location: float（0.0–1.0） 表示沿手指的佩戴位置： 0.0 = 靠近 MCP 关节（大指节） 1.0 = 靠近 PIP 关节（中指节）
ring_shadow_intensity: float（0.0–1.0） 控制阴影强度： 0.0 = 无阴影 1.0 = 最大阴影 默认值：0.15
ring_ambient_light_intensity: float（0.0–1.0） 定义光线在多大程度上参考目标手部图： 0.0 = 忽略手部图的光线 1.0 = 完全匹配手部图的光线与阴影渲染 默认值：1.0
ring_anchor_point: 像素坐标下由两个点组成的数组（可选） 标出戒指内缘与手指接触处的左右两个点。戒圈较宽或较厚时尤其好用。 不提供该参数时，AI 引擎会自动检测锚点。
- 支持的格式与尺寸
| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |
|---|---|---|---|
| AI 戒指虚拟试戴 | 长边 <= 4096 | < 10MB | jpg/jpeg/png |
- 错误码
| 错误码 | 说明 |
|---|---|
| RUNTIME_ERROR | 运行时发生未知错误 |
| PHOTO_DETECTION_FAIL | 用户照片无法正确处理，例如未检测到手 |
| OBJECT_DETECTION_FAIL | 商品照片无法正确处理，例如未检测到商品 |
| PHOTO_CHECK_INVALID | 用户照片的姿态或尺寸不符合要求 |
| INPUT_ERROR | 输入文件格式有误 |
| INPUT_MAIN_IMAGE_EMPTY | 必须提供用户图片 |
- 运行环境与依赖
| 示例代码语言 / 工具 | 建议运行时版本 |
|---|---|
| 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 |