# 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/file/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/2d-vto/watch ``` 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
- 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 {% partial file="/_partials/js-camera-kit.md" /%} 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) ## V2.0 Generate virtual try-on experiences for watches from uploaded images using AI processing, supporting alignment and shadow parameters. ### Create a new file. - [POST /s2s/v2.0/file/2d-vto/watch](https://docs.perfectcorp.com/reference/ai_watch/v2.0/paths/~1s2s~1v2.0~1file~12d-vto~1watch/post.md): To upload a new file, you'll first need to use the File API. It will give you a URL – use that URL to upload your file. Once the upload is finished, you can use the file_id from the same response to start using our AI features. ### Run an AI 2D Virtual Try On Watch task. - [POST /s2s/v2.0/task/2d-vto/watch](https://docs.perfectcorp.com/reference/ai_watch/v2.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 wearing location. The task will be processed asynchronously, and you can check its status using the task_id returned in this response. ### Check the status of a AI 2D Virtual Try On Watch task. - [GET /s2s/v2.0/task/2d-vto/watch/{task_id}](https://docs.perfectcorp.com/reference/ai_watch/v2.0/paths/~1s2s~1v2.0~1task~12d-vto~1watch~1%7Btask_id%7D/get.md)