AI 手表虚拟试戴
AR 腕表虚拟试戴，轻松上手！只需一张 2D 图片。
用户只要上传一张 2D 图片，就能通过我们创新的 AR 腕表应用即刻虚拟试戴高端腕表。这项独特能力让我们在电商领域独树一帜，让体验您的商品变得前所未有地简单。
本指南将带您走完全流程：
- 接口地址：
/s2s/v2.0/task/2d-vto/watch - 鉴权： 所有请求都需要
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/watch- 轮询接口
GET /s2s/v2.0/task/2d-vto/watch/{task_id}- AI 手表虚拟试戴规格
支持的手表图视角
手表图需为正面清晰视角，表盘无遮挡；表带请裁剪到接近真实佩戴时的长度。
- 手表必须立着、正对镜头——平放（水平放置）会得到错误结果。
- 图中不得出现表带背面（例如表扣），只能看到正面的表带。
支持的手腕图视角
手腕背面需完整可见，五根手指清晰可辨，且无任何遮挡。
watch_wearing_location: float（−0.3 到 1.0） 表示沿手腕的佩戴位置： −0.3 表示靠近手腕主关节 1.0 表示远离手腕主关节 默认值：null（使用引擎默认值）
watch_shadow_intensity: float（0.0 到 1.0） 控制阴影强度： 0.0 表示无阴影 1.0 表示最大阴影 默认值：0.15
watch_ambient_light_intensity: float（0.0 到 1.0） 定义光线在多大程度上参考目标手部图： 0.0 忽略手部图的光线 1.0 完全匹配手部图的光线与阴影渲染 默认值：1.0
手表锚点：像素坐标下由 4 个点组成的数组（可选） 前两个点标出佩戴时表带的起点与终点。 另外两个点标出表壳的上缘与下缘。
- 支持的格式与尺寸
| 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 |