# AI Eye Color Lens Virtual Try-On

# Overview
AI Eye Color Lens Virtual Simulation provides instant, hyper‑realistic contact lens try‑on by precisely detecting the iris, preserving natural reflections, accurately simulating lens opacity and blending across all iris colors, and enabling users to explore shades from subtle enhancements to vibrant blue transformations, all within a single, professional‑grade AI API.

![](https://plugins-media.makeupar.com/smb/blog/post/2022-01-25/2a348e5b-6a2b-4f08-bc54-1d16a0777e87.jpg)

**Contact Lenses Virtual Simulation**

Transform eye color instantly with our AI‑powered virtual try‑on tool. The AI Eye Color Lens Virtual Try‑On delivers hyper‑realistic results by precisely detecting the iris and applying natural, lifelike color adjustments, allowing shoppers to explore new styles without physical samples.

**Hyper‑Realistic Output**  
The system preserves natural eye reflections for authentic results, ensuring each color transformation looks true to life.

**Advanced Contact Filter Simulation**  
The contact lens filter accurately replicates opacity and blending across different iris base colors, enabling customers to virtually try on a full range of lenses with realistic depth and tone.

**More Than an Eye Color Changer**  
This technology goes beyond simple filters, offering a professional‑grade virtual lens experience that enhances customer confidence and boosts conversion.

---

## Integration Guide

* Take a Selfie

    *   Face the camera directly with proper lighting.
    *   Use the JS Camera Kit to capture the photo.

* Prepare Your Lens Style Cutout

*   Provide **one clear Lens Style image**:

    *   Format: **PNG** (recommended: background removed)
    *   Dimensions: **200 × 200 ≤ W × H ≤ 600 × 600**
    *   File size: **< 10 MB**

    **Samples:**

    ![](https://d3ss46vukfdtpo.cloudfront.net/static/media/01.00ccf3ac.png)
    ![](https://d3ss46vukfdtpo.cloudfront.net/static/media/02.c8beb3fc.png)

* Retrieve upload URLs and File IDs via ***/s2s/v2.0/file/eye-color-vto*** API

    Upload the following files using the upload URLs returned in the file API response:
    *   Your selfie photo
    *   Lens Style image

* Execute AI Task ***/s2s/v2.0/task/eye-color-vto***

    Run the AI task using file IDs or image URLs as the input source. Configure the effect parameters as desired.

* Poll Task Status

    Use the returned **task\_id** to monitor task progress.  
    Poll **GET /task/eye-color-vto** to check the engine's status.  
    The task will remain in a **“running”** state until it is completed. No units are consumed while the task is running.


![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_9535461b-69fc-4432-b56b-2d7c4cd0bf3b_b1ef78e813.jpg)



* **Sample application scenario**

    AI Eye Color Lens Virtual Simulation transforms how customers shop for colored contact lenses. The process is straightforward, engaging, and requires minimal effort from users.

    - Step1: Pick Your Favorite color
    Once customers land on your site and browse your selection, they can select the shades they’d like to try on. Whether they're eyeing a subtle hazel, vibrant green, or icy blue, they can explore a wide variety of colors.

    - Step 2: Open the Virtual Try-On Camera
    With just one click, the virtual try-on tool activates. No need for complicated setup instructions or additional downloads.

    - Step 3: Use Live Camera or Upload a Photo
    Users can opt for a live camera experience or upload a photo to virtually try on the colored contact lenses. The feature mirrors real-life outcomes with impressive accuracy, ensuring they see how each shade will look in natural settings.

    ![](https://plugins-media.makeupar.com/smb/blog/post/2025-03-28/2732a9f0-9cae-4639-b765-15866550b109.jpg)

## File Specs & Errors
* Supported Formats & Dimensions

|Type|Supported Dimensions|Supported File Size|Supported Formats|
|  ----  | ----  | ----  | ----  |
|AI Eye Color Lens Virtual Simulation|Selfie Image:<br>    *   Long side ≤ 1920 px <br>    *   Short side ≥ 320 px <br><br>Lens Style Image:<br>    *   File format: PNG <br>    *   Resolution: 200 × 200 ≤ W × H ≤ 600 × 600 px|< 10MB|jpg/png|


* Error Codes

|Error Code|Description|
|  ----  | ----  |
|error_below_min_image_size|If your image is smaller than 100 pixels in width or height, it's too small to use|
|error_face_position_invalid|Your face needs to be fully visible in the image, without any parts cut off|
|error_face_position_too_small|The face in your photo is too small to analyze properly|
|error_face_position_out_of_boundary|Your face is either too large or partially outside the edges of the photo|
|error_insufficient_lighting|The lighting is too dim, which makes analysis difficult|
|error_face_angle_invalid|Your face angle isn't quite right. For front-facing shots, keep your head within 10 degrees of straight. For side-facing shots, the angle should be more than 15 degrees|

* Environment & Dependency

| Sample Code Language / Tool | Recommended Runtime Versions |
|---|---|
| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |
| Node.js (JavaScript) | Node >= 18 (for global fetch) |
| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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 Eye Color Lens Virtual Try-On](https://docs.perfectcorp.com/_bundle/reference/ai_eye_color_lens.yaml)

## V1.0

AI-powered eye color lens features for virtual try on.

### Create a new file.

 - [POST /s2s/v2.0/file/eye-color-vto](https://docs.perfectcorp.com/reference/ai_eye_color_lens/v1.0/paths/~1s2s~1v2.0~1file~1eye-color-vto/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 Eye Color Lens task.

 - [POST /s2s/v2.0/task/eye-color-vto](https://docs.perfectcorp.com/reference/ai_eye_color_lens/v1.0/paths/~1s2s~1v2.0~1task~1eye-color-vto/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 Eye Color Lens task.

 - [GET /s2s/v2.0/task/eye-color-vto/{task_id}](https://docs.perfectcorp.com/reference/ai_eye_color_lens/v1.0/paths/~1s2s~1v2.0~1task~1eye-color-vto~1%7Btask_id%7D/get.md)