# AI Watch Virtual Try On

# Overview
Virtually Try-On AR Watches with Ease! Only One 2D Image Needed.

With just a single 2D image upload, users can instantly try on top-notch watches virtually using our innovative AR-Watches App. This unique feature sets us apart in the world of e-commerce, making it easier than ever for customers to experience your products.

## Integration Guide
This guide walks you through:

*   **Endpoint:** `/s2s/v2.0/task/2d-vto/watch`
*   **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY`
*   **Workflow:**
    1.  **Prepare a wrist image:** Uploading an image or provide a valid image URL of your wrist
    1.  **Prepare a watch image:** Uploading an image or provide a valid image URL of a watch product
    1.  **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response.
    1.  **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `"success"` or `"error"`.

---

* API Playground

Interactively explore and test the API using our official 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/)

---

* Authentication
- Include your API key in the request header using **Bearer Token**:
    ```
    Authorization: Bearer YOUR_API_KEY
    ```
You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.


* 1. Upload an Image

You may upload a file directly to the server or provide a valid image URL in the VTO task payload.

   * Upload Endpoint

```
POST /s2s/v2.0/file
```

Alternatively, skip this step if you already have a public image URL.

You may upload a file directly to the URL provided in the response from the File API and then use the corresponding `src_file_id` returned by the File API to invoke the AI task later. Or provide a valid image URL in the VTO task payload as `src_file_url`. The `src_file_id` or `src_file_url` will serve as the virtual try-on target.

You must also provide another watch product image as a reference using `ref_file_ids` or `ref_file_urls` to be applied to your `src_file_id` or `src_file_url`.

The AI engine supports automatic background removal for your watch product image. However, you may provide an occlusion mask image file for either your hand (`srcmsk_file_id` or `srcmsk_file_url`) or the watch product (`refmsk_file_ids` or `refmsk_file_urls`) to fine-tune the segmentation.

---

* 2. Create a Watch VTO Task and Poll for Results

Once you have an image and a template ID, create a task. The API processes the request asynchronously. You must poll the task status until it reaches `success` or `error`.

   * Create Task Endpoint

```
POST /s2s/v2.0/task/2d-vto/watch
```

   * Polling Endpoint

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

---

## File Specs & Errors

* AI Watch Virtual Try-On Specification

**Supported Watch View**
A watch image in a clear front view with the watch face unobstructed. The strap should be cropped to resemble a realistic wearing length.

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

**Supported Wrist View**
The back of the wrist should be fully visible with all five fingers clearly shown and without any occlusion.

![](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 to 1.0)**
Indicates the position along the wrist:
−0.3 represents near the main wrist joint
1.0 represents far from the main wrist joint
Default value: null (use engine default)

![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 to 1.0)**
Controls the strength of the shadow:
0.0 represents no shadow
1.0 represents maximum shadow
Default value: 0.15

**watch\_ambient\_light\_intensity: float (0.0 to 1.0)**
Defines the extent to which lighting references the target hand image:
0.0 ignores the hand image lighting
1.0 fully matches the hand image lighting and shadow rendering
Default value: 1.0

**Watch Anchor Points: array of 4 points in pixel coordinate (optional)**
The first two points mark the beginning and end of the strap when worn.
The remaining two points mark the upper and lower edges of the watch case.

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

---

* Supported Formats & Dimensions

|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|
|  ----  | ----  | ----  | ----  |
|AI Watch Virtual Try-On|long side <= 4096 |< 10MB|jpg/jpeg/png|

* Error Codes

|Error Code|Description|
|  ----  | ----  |
| RUNTIME_ERROR | An unexpected error occurred duwatch runtime |
| PHOTO_DETECTION_FAIL | The user photo could not be processed correctly, for example no hand detected |
| OBJECT_DETECTION_FAIL | The object photo could not be processed correctly, for example no product detected |
| PHOTO_CHECK_INVALID | The pose or size of the user photo is invalid |
| INPUT_ERROR | The input file format is incorrect |
| INPUT_MAIN_IMAGE_EMPTY | A user image is required |


* Environment & Dependency

| Sample Code Language / Tool | Recommended Runtime Versions |
|---|---|
| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |
| Node.js (JavaScript) | Node >= 18 (for global fetch) |
| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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
{% partial file="/_partials/js-camera-kit.md" /%}

---

## Unit Consumption

| AI Feature | Unit Consumed |
|---|---|
| AI Watch Virtual Try-On V1.0 | 1 Unit for Single-item wear |

---


License: Privacy policy

## Servers

```
https://yce-api-01.makeupar.com
```

## Security

### BearerAuthenticationV2

[object Object]

Type: http
Scheme: bearer

## Download OpenAPI description

 - [AI Watch Virtual Try On](https://docs.perfectcorp.com/_bundle/reference/ai_watch.yaml)

## V1.0

 - [POST /s2s/v2.0/task/2d-vto/watch](https://docs.perfectcorp.com/reference/ai_watch/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1watch/post.md): This endpoint initiates the watch virtual try-on process. You must provide source file(s) and reference image(s) (via URL or File ID), along with specific parameters for alignment, shadowing, and wear
 - [GET /s2s/v2.0/task/2d-vto/watch/{task_id}](https://docs.perfectcorp.com/reference/ai_watch/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1watch~1%7Btask_id%7D/get.md)