# 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 2. **Prepare a watch image:** Uploading an image or provide a valid image URL of a watch product 3. **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response. 4. **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. --- * 1. 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. * The watch must be upright and front-facing — placing it flat (horizontally) will produce incorrect results. * The back of the strap (e.g., the clasp) must not appear in the image — only the front-facing strap should be visible. ![](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 - 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 --- ## 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 Use the standard 'Bearer authentication'. Put your 'API Key' in header: `Authorization:Bearer YOUR_API_KEY`. Notice that there is ' ' a space between 'Bearer' and the 'YOUR_API_KEY'. 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)