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.

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:
Retrieve upload URLs and File IDs via /s2s/v2.0/file 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.

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.

File Specs & Errors

Supported Formats & Dimensions

Type	Supported Dimensions	Supported File Size	Supported Formats
AI Eye Color Lens Virtual Simulation	Selfie Image: * Long side ≤ 1920 px * Short side ≥ 320 px Lens Style Image: * File format: PNG * 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 320 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 - 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

JavaScript Camera Kit SDK Documentation

version: v2.5

Overview

The JavaScript Camera Kit provides a complete in-browser camera solution designed for high-accuracy face-based imaging tasks. It handles camera permissions, real-time face detection, automatic quality validation (lighting, pose, angle, distance), and guided capture UI flows.

This module is optimized for AI-driven image analysis, such as:

AI Skin Analysis (SD/HD)
AI Face Tone Analysis
Hair-related Analysis
Virtual Try-On (Ring, Wrist, Necklace, etc.)

Key Features

Permission Handling: Automatic management of webcam access.
Quality Validation: Real-time monitoring of face position, lighting, and angle.
Multi-Step Flows: Support for complex capture requirements (e.g., multi-angle hair capture).
Flexible Output: Supports both base64 and blob image formats.

Installation

Include the SDK via CDN in your HTML <head> or before the closing <body> tag. Once loaded, the SDK installs a global YMK object.

<script src="https://plugins-media.makeupar.com/v2.5-camera-kit/sdk.js"></script>

Quick Start Example

The following example demonstrates how to initialize the kit, open the camera, and handle captured images.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Camera Kit Sample</title>
    <style>
      #YMK-module { margin: 20px 0; }
      img { width: 150px; margin: 5px; border: 1px solid #ccc; }
    </style>
  </head>
  <body>

    <!-- Initialization Script -->
    <script>
      // Define async init entry point
      window.YMKAsyncInit = function() {
        YMK.addEventListener('loaded', function() {
          console.log('Module fully loaded and ready');
        });

        YMK.addEventListener('faceDetectionCaptured', function(capturedResult) {
          const container = document.getElementById('captured-results');
          container.innerHTML = '';

          // Handle multiple images if returned (e.g., multi-angle capture)
          for (const item of capturedResult.images) {
            const img = document.createElement('img');
            // Handle both base64 strings and Blob objects
            img.src = typeof item.image === 'string' 
              ? item.image 
              : URL.createObjectURL(item.image);
            container.appendChild(img);
          }
        });
      };

      function openCameraKit() {
        YMK.init({
          faceDetectionMode: 'makeup',
          imageFormat: 'base64',
          language: 'enu'
        });
        YMK.openCameraKit();
      }
    </script>

    <!-- Load SDK -->
    <script src="https://plugins-media.makeupar.com/v2.5-camera-kit/sdk.js"></script>

    <!-- UI Elements -->
    <button onclick="openCameraKit()">Open Camera Kit</button>

    <!-- Mandatory Mount Point -->
    <div id="YMK-module"></div>

    <h3>Captured Results:</h3>
    <div id="captured-results"></div>
  </body>
</html>

Prerequisites

To ensure successful integration, the following requirements must be met:

Requirement	Description
Browser Support	Must support `getUserMedia` API.
HTTPS	Required on most browsers for webcam access (except localhost).
Mount Point	A `<div id="YMK-module"></div>` is mandatory for rendering the UI.
Async Init	You must define `window.YMKAsyncInit` before the SDK loads.

Integration Guide

Step 1: Initialize the Module

Call YMK.init() before calling YMK.openCameraKit().

YMK.init({
  faceDetectionMode: 'makeup', // Detection flow
  imageFormat: 'base64',       // Output format
  language: 'enu'              // UI Language
});

Step 2: Add Event Handlers

YMK.addEventListener('faceQualityChanged', function(q) {
  console.log('Quality updated:', q);
});

Step 3: Open Camera Kit

This displays the UI, opens the webcam, and begins real-time monitoring.

YMK.openCameraKit();

Step 4: Receive Captured Results

Images arrive via the faceDetectionCaptured event.

YMK.addEventListener('faceDetectionCaptured', function(result) {
  console.log(result.images);
});

Step 5: Close Module

Clean up resources when done.

YMK.close();

API Reference

`YMK.init(args)`

Configures module appearance, detection mode, language, and capture format.

Argument	Type	Description	Default
`faceDetectionMode`	`string`	Detection flow to use (see Detection Modes below).	`"skincare"`
`width`	`number`	Pixel width of module container (`300–1920`).	`360` (≥500px) or `screen width`
`height`	`number`	Pixel height of module container (`300–1920`).	`480` (≥500px) or `min(screen.height, innerHeight)`
`language`	`string`	UI Language code (`chs`, `cht`, `deu`, `enu`, `esp`, `fra`, `jpn`, `kor`, `ptb`, `ita`, `mon` ).	`"enu"`
`imageFormat`	`string`	Format returned via `faceDetectionCaptured`.	`"base64"`
`disableCameraResolutionCheck`	`boolean`	Allow running even if webcam does not meet required resolution.	`false`
`hideFlipCameraButton`	`boolean`	Controls visibility of the flip front/back camera button if the device supports it.	`false`
`countingDuration`	`number`	Controls the countdown milliseconds when camera quality check meets criteria before auto-capture.	`800`
`qualityLevel`	`string`	Controls the camera quality check setting, with options of `relaxed`, `moderate`, or `strict`.	`relaxed`
`qualityOverrides`	`object`	Configure detailed parameters for camera quality verification.	See Camera Kit Quality Configuration
`videoQuality`	`string`	Configure the output quality to `720p`, `1080p`, or `1920p`. 720p corresponds to 1280 × 720, 1080p to 1920 × 1080, and 1920p to 2560 × 1920. This setting is supported only for `skincare` and `hdskincare`	`720p`

Methods

Method	Description
`YMK.openCameraKit()`	Opens the module and begins detection.
`YMK.close()`	Closes module and camera.
`YMK.addEventListener(event, callback)`	Registers event callbacks. Returns an `EventListenerIdentifier`.
`YMK.removeEventListener(id)`	Removes listener by identifier.
`YMK.isLoaded()`	Returns whether livestream or photo is drawn on canvas (`boolean`).
`YMK.pause()`	Pauses the webcam stream.
`YMK.resume(restartWebcam)`	Resumes webcam after pause.
`YMK.getInfo()`	Returns current module info (e.g., `{ fps: 30 }`).

Camera Kit Quality Configuration

Camera Kit provides configurable quality parameters to control face detection and skin analysis behavior. These parameters allow developers to fine-tune detection strictness while maintaining consistency across web and native SDK implementations.

To simplify configuration, Camera Kit includes three predefined presets:

RELAXED: Optimized for usability with minimal restrictions
MODERATE: Balanced between usability and accuracy
STRICT: Optimized for maximum detection accuracy

All custom configurations must meet or exceed the minimum requirements defined by the RELAXED preset.

Camera Kit Quality Configuration supports both skincare and hdskincare.

Preset Behavior

Preset	Description
RELAXED	Less strict validation for smoother user experience
MODERATE	Balanced validation for most use cases
STRICT	Tight validation for high accuracy scenarios

When using qualityOverrides, you may specify only the parameters you want to change. Unspecified parameters fall back to the active preset defaults.

Configuration Object

{
  "face_ratio_lower_threshold": 0.55,
  "face_ratio_upper_threshold": 1,
  "face_left_boundary_lower_threshold": 0,
  "face_left_boundary_upper_threshold": 1,
  "face_right_boundary_lower_threshold": 0,
  "face_right_boundary_upper_threshold": 1,
  "face_top_boundary_lower_threshold": 0,
  "face_top_boundary_upper_threshold": 1,
  "face_bottom_boundary_lower_threshold": 0,
  "face_bottom_boundary_upper_threshold": 1,
  "pitch_lower_threshold": -20,
  "pitch_upper_threshold": 10,
  "yaw_lower_threshold": -15,
  "yaw_upper_threshold": 15,
  "roll_lower_threshold": -15,
  "roll_upper_threshold": 15,
  "lighting_lower_threshold": 0.55,
  "lighting_upper_threshold": 0.8,
  "lighting_uneven_threshold": 0.2
}

Parameters

Face Ratio Control

Controls the acceptable proportion of the detected face.

Measurement basis:
- Landscape mode: vertical ratio
- Portrait mode: horizontal ratio

Parameter	Description	Allowed Range	Preset Defaults
`face_ratio_lower_threshold`	Minimum face ratio	0.55 to 1.0	STRICT 0.75, MODERATE 0.65, RELAXED 0.55
`face_ratio_upper_threshold`	Maximum face ratio	1.0	1.0 (all presets)

Face Boundary Control

Defines how close the face can be to the frame edges.

Parameter	Description	Allowed Range	Default
`face_left_boundary_lower_threshold`	Left boundary minimum	0.0 to 1.0	0.0
`face_left_boundary_upper_threshold`	Left boundary maximum	0.0 to 1.0	1.0
`face_right_boundary_lower_threshold`	Right boundary minimum	0.0 to 1.0	0.0
`face_right_boundary_upper_threshold`	Right boundary maximum	0.0 to 1.0	1.0
`face_top_boundary_lower_threshold`	Top boundary minimum	0.0 to 1.0	0.0
`face_top_boundary_upper_threshold`	Top boundary maximum	0.0 to 1.0	1.0
`face_bottom_boundary_lower_threshold`	Bottom boundary minimum	0.0 to 1.0	0.0
`face_bottom_boundary_upper_threshold`	Bottom boundary maximum	0.0 to 1.0	1.0

Head Pose Angle Control

Controls allowable head orientation.

Parameter	Description	Allowed Range	Preset Defaults
`pitch_lower_threshold`	Minimum pitch angle	-20 to 10	STRICT -10, MODERATE -15, RELAXED -20
`pitch_upper_threshold`	Maximum pitch angle	-20 to 10	STRICT 0, MODERATE 5, RELAXED 10
`yaw_lower_threshold`	Minimum yaw angle	-15 to 15	STRICT -5, MODERATE -10, RELAXED -15
`yaw_upper_threshold`	Maximum yaw angle	-15 to 15	STRICT 5, MODERATE 10, RELAXED 15
`roll_lower_threshold`	Minimum roll angle	-15 to 15	STRICT -5, MODERATE -10, RELAXED -15
`roll_upper_threshold`	Maximum roll angle	-15 to 15	STRICT 5, MODERATE 10, RELAXED 15

Lighting Control

Defines acceptable lighting quality and uniformity.

Parameter	Description	Allowed Range	Preset Defaults
`lighting_lower_threshold`	Minimum lighting level	0.55 to 1.0	STRICT 0.8, MODERATE 0.7, RELAXED 0.55
`lighting_upper_threshold`	Maximum lighting level	0.8 to 1.0	STRICT 0.9, MODERATE 0.85, RELAXED 0.8
`lighting_uneven_threshold`	Maximum luma difference between eyes	0.0 to 0.2	STRICT 0.1, MODERATE 0.15, RELAXED 0.2

Validation Rules

Custom values must not be less restrictive than RELAXED preset values.
Only specified fields in qualityOverrides are applied.
All unspecified parameters default to the selected preset.

Detection Modes

Configure the faceDetectionMode in YMK.init() to suit your specific use case.

Mode	Description
`makeup`	Standard camera mode for virtual cosmetic try-on.
`skincare`	Standard skin analysis mode, close-up face capture. Support AI Skin Analysis and AI Skin Simulation.
`hdskincare`	High-definition capture for AI skin analysis using webcams with a minimum resolution of 2560 pixels on the longer side, subject to device support.
`shadefinder`	Skin Tone Analysis front-face capture.
`facereshape`	AI Face Reshape capture and AI Face Lift.
`hairlength`	Full hair-length capture (from a distance).
`hairfrizziness`	3-phase capture: front, right-turn, left-turn.
`hairtype`	Same 3-phase multi-angle capture flow.
`hairdensity`	A 45‑degree downward head‑angle photograph.
`ring`	Hand capture for ring virtual try‑on.
`wrist`	Wrist capture for watch or bracelet virtual try‑on.
`necklace`	Selfie capture for necklace try-on.
`earring`	Selfie capture for earring virtual try-on.
`teethwhiten`	Front‑facing selfie that detects whether teeth are visible; photo taken only when detected.
`nail`	Hand capture for nails virtual try‑on.
`comprehensive`	Photo to be used simultaneously for AI Makeup, AI Skin Analysis, and AI Facial Attributes & Ratio Analysis.

Events Reference

Lifecycle & Status Events

Event	Description
`opened`	Module opened.
`loading`	Loading progress (0–100).
`loaded`	Camera stream loaded onto canvas.
`closed`	Module closed.
`faceDetectionStarted`	User enters the detection UI.

Camera Events

Event	Description
`cameraOpened`	Webcam opened successfully.
`cameraClosed`	Webcam closed.
`cameraFailed`	Permission denied or no webcam found. Error codes include `"error_resolution_unsupported"`, `"error_permission_denied"`, `"error_access_failed"`.
`unsupportedResolution`	Fired when the device resolution does not meet the minimum requirements for the selected mode.

Detection Events

`faceQualityChanged`

Fires continuously during detection as quality metrics update.

Example Payload:

{
  "hasFace": true,
  "position": "good",
  "frontal": "good",
  "lighting": "ok"
}

Field Definitions:

hasFace: (boolean) Whether a face is detected.
position: (string) Face distance/size quality ("good", "notgood", "toosmall", "outofboundary").
frontal: (string) Whether user is facing forward ("good", "notgood").
lighting: (string) Lighting strength ("good", "ok", "notgood").

`faceDetectionCaptured`

Fired after all required face quality validation checks have passed and the Camera Kit has successfully completed the capture workflow. Depending on the mode, this may contain one or multiple images.

Example Payload:

{
  "mode": "makeup",
  "images": [
    {
      "phase": 0,
      "image": "data:image/jpeg;base64,...",
      "width": 500,
      "height": 500
    }
  ]
}

Image Object Fields:

phase: (integer) Zero-based index representing the capture step.
image: (string | Blob) The captured image data.
width: (integer) Pixel width of the captured image.
height: (integer) Pixel height of the captured image.

Configuration Notes

Quality Requirements

To ensure successful capture:

Distance: Ensure correct face distance (not too zoomed in/out).
Angle: Ensure frontal face angle.
Lighting: Provide sufficient lighting (avoid shadows or dark environments).

Multi-Phase Capture

Modes like hairtype or hairfrizziness require multiple steps:

Front face
Turn right
Turn left

Ensure your event handling logic accounts for multiple images in the faceDetectionCaptured result array.

Advanced Configuration

Flip Button: Use hideFlipCameraButton: true to enforce a specific camera orientation if your UX requires it.
Capture Delay: Adjust countingDuration (default 800) to give users more time to review the capture before auto-submission occurs.

Minimum Recommended Quality

const minQuality = {
  hasFace: true,
  area: "good",
  frontal: "good",
  lighting: "ok"
};

Unit Consumption

AI Feature	Unit Consumed
AI Eye Color Lens Virtual Try-On V1.0	1

Download OpenAPI description

ai_eye_color_lens.json

ai_eye_color_lens.yaml

Overview

E-mail

YouCamOnlineEditor_API@perfectcorp.com

License

Languages

Servers

https://yce-api-01.makeupar.com