{
"openapi": "3.0.0",
"info": {
"title": "AI Eye Color Lens Virtual Try-On",
"description": "# Overview\nAI 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.\n\n\n\n**Contact Lenses Virtual Simulation**\n\nTransform 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.\n\n**Hyper‑Realistic Output** \nThe system preserves natural eye reflections for authentic results, ensuring each color transformation looks true to life.\n\n**Advanced Contact Filter Simulation** \nThe 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.\n\n**More Than an Eye Color Changer** \nThis technology goes beyond simple filters, offering a professional‑grade virtual lens experience that enhances customer confidence and boosts conversion.\n\n---\n\n## Integration Guide\n\n* Take a Selfie\n\n * Face the camera directly with proper lighting.\n * Use the JS Camera Kit to capture the photo.\n\n* Prepare Your Lens Style Cutout\n\n* Provide **one clear Lens Style image**:\n\n * Format: **PNG** (recommended: background removed)\n * Dimensions: **200 × 200 ≤ W × H ≤ 600 × 600**\n * File size: **< 10 MB**\n\n **Samples:**\n\n \n \n\n* Retrieve upload URLs and File IDs via ***/s2s/v2.0/file*** API\n\n Upload the following files using the upload URLs returned in the file API response:\n * Your selfie photo\n * Lens Style image\n\n* Execute AI Task ***/s2s/v2.0/task/eye-color-vto***\n\n Run the AI task using file IDs or image URLs as the input source. Configure the effect parameters as desired.\n\n* Poll Task Status\n\n Use the returned **task\\_id** to monitor task progress. \n Poll **GET /task/eye-color-vto** to check the engine's status. \n The task will remain in a **“running”** state until it is completed. No units are consumed while the task is running.\n\n\n\n\n\n\n* **Sample application scenario**\n\n 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.\n\n - Step1: Pick Your Favorite color\n 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.\n\n - Step 2: Open the Virtual Try-On Camera\n With just one click, the virtual try-on tool activates. No need for complicated setup instructions or additional downloads.\n\n - Step 3: Use Live Camera or Upload a Photo\n 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.\n\n \n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n|Type|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|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|\n\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n|error_below_min_image_size|If your image is smaller than 320 pixels in width or height, it's too small to use|\n|error_face_position_invalid|Your face needs to be fully visible in the image, without any parts cut off|\n|error_face_position_too_small|The face in your photo is too small to analyze properly|\n|error_face_position_out_of_boundary|Your face is either too large or partially outside the edges of the photo|\n|error_insufficient_lighting|The lighting is too dim, which makes analysis difficult|\n|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|\n\n* Environment & Dependency\n\n| Sample Code Language / Tool | Recommended Runtime Versions |\n|---|---|\n| cURL | - bash >= 3.2 - curl >= 7.58 (modern TLS/HTTP support) - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80 - Firefox >= 74 - Safari >= 13.1 |\n| PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) or allow_url_fopen=On + ext-openssl, ext-json |\n| Python | Python >= 3.10 (for f-strings), requests >= 2.20.0 |\n| Java | Java 11+ (for HttpClient), Jackson Databind >= 2.12.0 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## Unit Consumption\n\n| AI Feature | Unit Consumed |\n|---|---|\n| AI Eye Color Lens Virtual Try-On V1.0 | 1 |\n\n---\n",
"version": "",
"termsOfService": "https://www.makeupar.com/perfectbeauty/youcam/terms-of-service-api",
"contact": {
"email": "YouCamOnlineEditor_API@perfectcorp.com"
},
"license": {
"name": "Privacy policy",
"url": "https://www.makeupar.com/perfectbeauty/youcam/privacy-policy-api"
}
},
"servers": [
{
"url": "https://yce-api-01.makeupar.com"
}
],
"tags": [
{
"name": "V1.0",
"description": "AI-powered eye color lens features for virtual try on."
}
],
"paths": {
"/s2s/v2.0/task/eye-color-vto": {
"post": {
"summary": "Run an AI Eye Color Lens task.",
"description": "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](/develop/webhook.md) for setup and verification details.\n\nIf webhooks are not supported or cannot be used in your integration, implement polling. After submitting an AI task, poll the status endpoint at regular intervals (e.g., every 10 seconds) until the task status is `success` or `error`.\n",
"tags": [
"V1.0"
],
"security": [
{
"BearerAuthenticationV2": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/BasicRunTaskV2WithRequiredRef"
},
{
"type": "object",
"required": [
"version",
"effect"
],
"properties": {
"version": {
"type": "string",
"enum": [
"1.0"
]
},
"effect": {
"type": "object",
"required": [
"intensity"
],
"properties": {
"intensity": {
"type": "integer",
"maximum": 100,
"minimum": 1
},
"enlargement": {
"type": "integer",
"maximum": 100,
"minimum": 0,
"default": 0
},
"skin_smooth_strength": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"default": 50
},
"skin_smooth_color_intensity": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"default": 50
}
}
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful execution of the task",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BasicRunTaskResponseV2"
}
}
}
},
"400": {
"description": "Failed execution of task",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/RunError"
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/InvalidApiKey"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
}
}
},
"/s2s/v2.0/task/eye-color-vto/{task_id}": {
"get": {
"summary": "Check the status of a AI Eye Color Lens task.",
"tags": [
"V1.0"
],
"security": [
{
"BearerAuthenticationV2": []
}
],
"parameters": [
{
"name": "task_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
},
"description": "ID of task to check"
}
],
"responses": {
"200": {
"description": "Successful check of the task status",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/TaskStatusResponseV2"
},
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"results": {
"type": "object",
"properties": {
"timed": {
"type": "number"
},
"timed_apply": {
"type": "number"
}
}
}
}
}
}
}
]
}
}
}
},
"400": {
"$ref": "#/components/responses/InvalidTaskId"
},
"401": {
"$ref": "#/components/responses/InvalidApiKey"
},
"500": {
"$ref": "#/components/responses/TaskTimeout"
}
}
}
}
},
"components": {
"securitySchemes": {
"BearerAuthenticationV2": {
"type": "http",
"scheme": "bearer",
"description": "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'."
}
},
"schemas": {
"BasicRunTaskV2SrcFileUrl": {
"type": "object",
"required": [
"src_file_url"
],
"properties": {
"src_file_url": {
"type": "string",
"description": "Url of the file to run task. The url should be publicly accessible.",
"example": "https://example.com/selfie.jpg"
}
}
},
"BasicRunTaskV2RefFileUrl": {
"type": "object",
"properties": {
"ref_file_url": {
"type": "string",
"description": "Url of the reference file to run task. The url should be publicly accessible.",
"example": "https://example.com/accessory.jpg"
}
}
},
"BasicRunTaskV2RefFileId": {
"type": "object",
"properties": {
"ref_file_id": {
"type": "string",
"description": "ID of the reference file to run task. File ID from upload file API.",
"example": "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE="
}
}
},
"BasicRunTaskV2SrcFileId": {
"type": "object",
"required": [
"src_file_id"
],
"properties": {
"src_file_id": {
"type": "string",
"description": "ID of file to run task. File ID from upload file API.",
"example": "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE="
}
}
},
"BasicRunTaskV2WithRequiredRef": {
"title": "BasicRunTaskV2WithRef",
"anyOf": [
{
"allOf": [
{
"title": "Run task with src file url & ref file url",
"required": [
"ref_file_url"
]
},
{
"$ref": "#/components/schemas/BasicRunTaskV2SrcFileUrl"
},
{
"$ref": "#/components/schemas/BasicRunTaskV2RefFileUrl"
}
]
},
{
"allOf": [
{
"title": "Run task with src file url & ref file ID",
"required": [
"ref_file_id"
]
},
{
"$ref": "#/components/schemas/BasicRunTaskV2SrcFileUrl"
},
{
"$ref": "#/components/schemas/BasicRunTaskV2RefFileId"
}
]
},
{
"allOf": [
{
"title": "Run task with src file ID & ref file url",
"required": [
"ref_file_url"
]
},
{
"$ref": "#/components/schemas/BasicRunTaskV2SrcFileId"
},
{
"$ref": "#/components/schemas/BasicRunTaskV2RefFileUrl"
}
]
},
{
"allOf": [
{
"title": "Run task with src file ID & ref file ID",
"required": [
"ref_file_id"
]
},
{
"$ref": "#/components/schemas/BasicRunTaskV2SrcFileId"
},
{
"$ref": "#/components/schemas/BasicRunTaskV2RefFileId"
}
]
}
]
},
"BasicRunTaskResponseV2": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Response status",
"example": 200
},
"data": {
"type": "object",
"properties": {
"task_id": {
"type": "string",
"description": "ID of this task. Task result is valid to query by this ID for 24 hours.",
"example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
}
}
}
}
},
"RunError": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Response status",
"example": 400
},
"error": {
"type": "string",
"description": "Error message",
"example": "The operation could not be completed"
},
"error_code": {
"type": "string",
"enum": [
"InvalidParameters",
"CreditInsufficiency",
"InvalidStyleGroup",
"InvalidStyle",
"BadRequest"
],
"description": "Error code:\n * InvalidParameters - Invalid request parameters\n * CreditInsufficiency - Insufficient unit to run\n * BadRequest - Unexpected request parameter\n * InvalidStyleGroup - Invalid style group id\n * InvalidStyle - Invalid style id\n"
}
}
},
"EngineErrorCode": {
"type": "string",
"nullable": true,
"enum": [
"error_exceed_max_image_size",
"exceed_max_filesize",
"invalid_parameter",
"error_download_image",
"error_download_mask",
"error_decode_image",
"error_decode_mask",
"error_nsfw_content_detected",
"error_no_face",
"error_pose",
"error_face_parsing",
"error_inference",
"exceed_nsfw_retry_limits",
"error_upload",
"unknown_internal_error"
],
"description": "Errors:\n- \\`error_exceed_max_image_size\\` - Input image size exceeds the maximum limit\n- \\`exceed_max_filesize\\` - Input file size exceeds the maximum limit\n- \\`invalid_parameter\\` - Invalid parameter value\n- \\`error_download_image\\` - Download source image error\n- \\`error_download_mask\\` - Download mask image error\n- \\`error_decode_image\\` - Decode source image error\n- \\`error_decode_mask\\` - Decode mask image error\n- \\`error_nsfw_content_detected\\` - NSFW content detected in source image\n- \\`error_no_face\\` - No face detected on source image\n- \\`error_pose\\` - Failed to detect pose on source image\n- \\`error_face_parsing\\` - Failed to do face segmentation on source image\n- \\`error_inference\\` - Inference pipeline error\n- \\`exceed_nsfw_retry_limits\\` - Exceed the retry limits to avoid generated NSFW image\n- \\`error_upload\\` - Upload result image error\n- \\`unknown_internal_error\\` - Others\n"
},
"TaskStatusResponseBodySingleUrlResultsV2": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "URL to download this result. Valid for 2 hours",
"example": "https://example.com/sample-result-url"
}
}
},
"TaskStatusResponseV2": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Response status",
"example": 200
},
"data": {
"type": "object",
"properties": {
"task_status": {
"type": "string",
"enum": [
"running",
"success",
"error"
],
"description": "Status of this task"
},
"error": {
"$ref": "#/components/schemas/EngineErrorCode"
},
"error_message": {
"type": "string",
"description": "Detailed description of error"
},
"results": null
}
}
},
"$ref": "#/components/schemas/TaskStatusResponseBodySingleUrlResultsV2"
}
},
"responses": {
"InvalidApiKey": {
"description": "Invalid or missing API key",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 401,
"description": "Response status"
},
"error": {
"type": "string",
"example": "Invalid API key"
}
}
}
}
}
},
"TooManyRequests": {
"description": "Too many requests",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 429,
"description": "Response status"
},
"error": {
"type": "string",
"example": "Too many requests"
}
}
}
}
}
},
"InvalidTaskId": {
"description": "Invalid task ID",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 400,
"description": "Response status"
},
"error": {
"type": "string",
"example": "Invalid task ID"
}
}
}
}
}
},
"TaskTimeout": {
"description": "Task execution timeout",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 500,
"description": "Response status"
},
"error": {
"type": "string",
"example": "Task execution timed out"
}
}
}
}
}
}
}
}
}