# AI Ring Virtual Try-On # Overview Easily Create Your AR Ring or Engagement Ring Try Ons. You Only Need to Upload Images. Opt for 2D images for effortless yet high-quality virtual try-on experiences with minimal effort. ## Integration Guide This guide walks you through: * **Endpoint:** `/s2s/v2.0/file/2d-vto/ring` * **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY` * **Workflow:** 1. **Prepare a hand image:** Uploading an image or provide a valid image URL of your hand 1. **Prepare a ring image:** Uploading an image or provide a valid image URL of a ring 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-ring-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-ring-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/ring ``` 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 ring 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 ring product image. However, you may provide an occlusion mask image file for either your hand (`srcmsk_file_id` or `srcmsk_file_url`) or the ring product (`refmsk_file_ids` or `refmsk_file_urls`) to fine-tune the segmentation. --- * 2. Create a Ring 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/ring ``` * Polling Endpoint ``` GET /s2s/v2.0/task/2d-vto/ring/{task_id} ``` --- ## File Specs & Errors * AI Ring Virtual Try-On Specification **Supported Ring View** The ring image must be provided in a three-quarter front view (approximately 45 degrees). ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_product_01_9a4d0680f2_b46afe9a53.jpg) **Supported Hand View** The back of the hand 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/ring_user_01_6d9893abd0_c7427cdb78.jpg) **ring\_wearing\_finger: integer (0–4)** Specifies the finger on which the ring is worn: 0 = Thumb 1 = Index finger 2 = Middle finger 3 = Ring finger 4 = Little finger **ring\_wearing\_location: float (0.0–1.0)** Indicates the position along the finger: 0.0 = Near the MCP joint (large knuckle) 1.0 = Near the PIP joint (middle joint) ![ring_wearing_location](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_wearing_location_59567be4af.jpg) **ring\_shadow\_intensity: float (0.0–1.0)** Controls the shadow strength: 0.0 = No shadow 1.0 = Maximum shadow Default: 0.15 **ring\_ambient\_light\_intensity: float (0.0–1.0)** Defines how much the lighting references the target hand image: 0.0 = Ignore the hand image lighting 1.0 = Fully match the hand image lighting and shadow rendering Default: 1.0 **ring\_anchor\_point: array of two points in pixel coordinate (optional)** Marks the inner edge of the ring where it contacts the finger, specifying the left and right points. This is particularly useful for wide or thick rings. If this parameter is not provided, the AI engine will automatically detect the anchor points. ![ring_anchor_point](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_anchor_point_e6eb241ef8.jpg) --- * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Ring Virtual Try-On|long side <= 4096 |< 10MB|jpg/jpeg/png| * Error Codes |Error Code|Description| | ---- | ---- | | RUNTIME_ERROR | An unexpected error occurred during 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 Ring Virtual Try-On](https://docs.perfectcorp.com/_bundle/reference/ring_vto.yaml) ## V1.0 ### Create a new file. - [POST /s2s/v2.0/file/2d-vto/ring](https://docs.perfectcorp.com/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1file~12d-vto~1ring/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 Ring task. - [POST /s2s/v2.0/task/2d-vto/ring](https://docs.perfectcorp.com/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1ring/post.md): AI tasks are asynchronous. Prefer webhook-based completion handling when the feature supports webhooks. Configure your webhook endpoint, verify webhook signatures, and use the received task_id to query the task result after a success or error notification. See the webhook integration guide for setup and verification details. If webhooks are not supported for the feature, or if your integration cannot use webhooks, implement polling. After starting an AI task, keep polling the task status endpoint at the given polling_interval until the task status is either success or error. Do not stop polling a running task for longer than the allowed polling window. If the task is not polled in time, the task may expire; a later status check can return InvalidTaskId even if processing finished, and the consumed units may still be charged. ### Check the status of a AI 2D Virtual Try On Ring task. - [GET /s2s/v2.0/task/2d-vto/ring/{task_id}](https://docs.perfectcorp.com/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1ring~1%7Btask_id%7D/get.md)