# 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 virtual 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/task/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 ``` 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. --- * 1. 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 --- ## Unit Consumption | AI Feature | Unit Consumed | | --- | --- | | AI Earrings Virtual Try-On V1.0 | 1 Unit for Single-item wear 2 Units for Stacked 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 Earrings Virtual Try On](https://docs.perfectcorp.com/_bundle/reference/ai_earrings.yaml) ## V1.0 - [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 we - [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)