# AI 手表虚拟试戴

# 概览
AR 腕表虚拟试戴，轻松上手！只需一张 2D 图片。
用户只要上传一张 2D 图片，就能通过我们创新的 AR 腕表应用即刻虚拟试戴高端腕表。这项独特能力让我们在电商领域独树一帜，让体验您的商品变得前所未有地简单。
## 接入指南
本指南将带您走完全流程：
* **接口地址：**

`/s2s/v2.0/task/2d-vto/watch`
* **鉴权：**
 所有请求都需要
`Authorization: Bearer YOUR_API_KEY`
* **流程：**
  1. **准备手腕图片：**
 上传一张手腕图片，或提供有效的手腕图片 URL
  2. **准备手表图片：**
 上传一张手表商品图片，或提供有效的商品图片 URL
  3. **发起 AI 任务并获取 Task ID：**
 从响应中取到
`task_id`
。
  4. **轮询状态（`GET`）：**
 用
`task_id`
 查询任务状态，持续轮询直到
`task_status`
 为
`"success"`
 或
`"error"`
。



---

* API Playground

用官方在线调试台交互式地体验与测试接口：
**API Playground：**
[http://yce.makeupar.com/api-console/en/api-playground/ai-watch-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-watch-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，这一步可以跳过。
您可以把文件上传到 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`）提供遮挡蒙版图，用于微调分割效果。


---

*   1. 创建 AI 手表虚拟试戴任务并轮询结果

图片和模板 ID 备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。
* 创建任务接口


```
POST /s2s/v2.0/task/2d-vto/watch
```
* 轮询接口


```
GET /s2s/v2.0/task/2d-vto/watch/{task_id}
```


---

## 文件规格与错误码
* AI 手表虚拟试戴规格

**支持的手表图视角**
手表图需为正面清晰视角，表盘无遮挡；表带请裁剪到接近真实佩戴时的长度。
* 手表必须立着、正对镜头——平放（水平放置）会得到错误结果。
* 图中不得出现表带背面（例如表扣），只能看到正面的表带。

![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/watch_product_01_aab8053028_50ab7fe9a5.jpg)


---

**支持的手腕图视角**
手腕背面需完整可见，五根手指清晰可辨，且无任何遮挡。
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/watch_and_bracelet_user_01_09f16603cb_878dc89179.jpg)
**watch_wearing_location: float（−0.3 到 1.0）**
表示沿手腕的佩戴位置：
−0.3 表示靠近手腕主关节
1.0 表示远离手腕主关节
默认值：null（使用引擎默认值）
![watch_wearing_location](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/bracelet_wearing_location_01ac0a048e.jpg)
**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 个点组成的数组（可选）**
前两个点标出佩戴时表带的起点与终点。
另外两个点标出表壳的上缘与下缘。
![watch_anchor_point](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Product_anchors_ece6851c88.jpg)


---

* 支持的格式与尺寸

| 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 |



---

## JS Camera Kit


---

## 点数消耗
| AI 功能 | 消耗点数 |
|  --- | --- |
| AI 手表虚拟试戴 V1.0 | 单件佩戴 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_watch.yaml)

## V1.0

 - [POST /s2s/v2.0/task/2d-vto/watch](https://docs.perfectcorp.com/zh-cn/reference/ai_watch/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1watch/post.md): 本接口用于发起 AI 手表虚拟试戴流程。您需要提供源文件与参考图（URL 或文件 ID），以及用于对齐、阴影与佩戴位置的具体参数。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。
 - [GET /s2s/v2.0/task/2d-vto/watch/{task_id}](https://docs.perfectcorp.com/zh-cn/reference/ai_watch/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1watch~1%7Btask_id%7D/get.md)