# AI Earrings Virtual Try On # Overview The Ultimate AI Earring Virtual Try-On Top AI ear piercing simulator for virtual earring try-on and virtual piercing try-on Create realistic and dynamic earrings vitual try-on from a 2D image, no expensive 3D modelling required. Our advanced algorithms create lifelike virtual try-on earring SKUs with sophisticated lighting effects and physically accurate motions. ## Integration Guide This guide walks you through: * **Endpoint:** `/s2s/v2.0/file/2d-vto/earring` * **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY` * **Workflow:** 1. **Prepare a selfie image:** Uploading an image or provide a valid image URL 2. **Prepare an earring image:** Uploading an image or provide a valid image URL of an earring 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-earring-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-earring-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/earring ``` 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 earring 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 earring product image. However, you may provide an occlusion mask image file for either your hand (`srcmsk_file_id` or `srcmsk_file_url`) or the earring product (`refmsk_file_ids` or `refmsk_file_urls`) to fine-tune the segmentation. --- * 2. Create a Earring 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/earring ``` * Polling Endpoint ``` GET /s2s/v2.0/task/2d-vto/earring/{task_id} ``` --- ## File Specs & Errors * AI Earring Virtual Try-On Specification **Supported Earring Reference Image** * A single earring image in a clear front view without obstruction. * All parameters (including anchor points, masks, location, etc.) apply **only** when the reference image shows a **single earring** being worn. * If the try-on reference image shows **both earrings**, all parameters will use **auto-detection and default settings**. * When trying on **both earrings**, the clearer ear will be used as the source, and the other ear will be generated by mirroring it. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/earring_product_01_41c943f9fc_037ffb1241.jpg) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/earring_product_07_5476e0a156_a69e8e6549.jpg) **Supported Selfie View** * The AI Earring Virtual Try-On supports front-facing images, but the best results are achieved with side-facing images. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Earring_restriction_cdf1de3c7b.png) **earring\_wearing\_location: integer array of size 2** Specifies the target location in the selfie where the earring should be placed. Default value: null (engine default) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/wearing_location_b4f6f4453a.jpg) **earring\_scale: number greater than 0** Controls the earring size in centimetres. Default value: null (engine default) **earring\_is\_right\_ear: boolean** Indicates whether the earring is worn on the right ear. By default, it is worn on the right ear. Default value: true **earring\_occluded\_type: number (Enum: 0, 1, 2)** Specifies the occlusion type: 0 means auto-detect 1 means occluded 2 means no occlusion Default value: 0 **earring\_shadow\_intensity: float (0.0 to 1.0)** Controls the shadow strength: 0.0 represents no shadow 1.0 represents maximum shadow Default value: 0.15 **earring\_ambient\_light\_intensity: float (0.0 to 1.0)** Defines how much the lighting references the selfie image: 0.0 ignores the selfie image lighting 1.0 fully matches the selfie image lighting and shadow rendering Default value: 1.0 **earring\_anchor\_point: array of one point in pixel coordinate (optional)** Specifies the wearing position in the earring product image. Default value: null (engine default) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/anchor_point_787282aa19.jpg) --- * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Earring Virtual Try-On|long side <= 4096 |< 10MB|jpg/jpeg/png| * Error Codes |Error Code|Description| | ---- | ---- | | RUNTIME_ERROR | An unexpected error occurred duearring 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 Earrings Virtual Try On](https://docs.perfectcorp.com/_bundle/reference/ai_earrings.yaml) ## V1.0 Generate virtual try-on experiences for earrings from uploaded images using AI processing, supporting alignment and shadow parameters. ### Create a new file. - [POST /s2s/v2.0/file/2d-vto/earring](https://docs.perfectcorp.com/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1file~12d-vto~1earring/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 Earring task. - [POST /s2s/v2.0/task/2d-vto/earring](https://docs.perfectcorp.com/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1earring/post.md): This endpoint initiates the earring 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 Earring task. - [GET /s2s/v2.0/task/2d-vto/earring/{task_id}](https://docs.perfectcorp.com/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1earring~1%7Btask_id%7D/get.md)