AI Nail Virtual Try-On

Integration Guide

This guide walks you through:

Workflow for AI Nail Virtual Try On API:

Authentication Required: Authorization: Bearer YOUR_API_KEY

Workflow Steps:

1. Image Upload Preparation:

   • The process begins with preparing a back of the hand image.
   • Call the File API /s2s/v2.0/file to obtain the upload URL and associated file_id.
   • Upload the back of the hand with nail image using the provided upload URL.

2. Nail Design Setup Options:

   • Begin by selecting a suitable nail color. You can also choose a custom shape according to your taste.

3. Initiate AI Task and Obtain Task ID:

   • Send the uploaded image(s) along with the chosen effect configuration via an HTTP POST request to /s2s/v2.0/task/nail-vto.
   • Await a unique task ID in the response, which identifies this interaction.

4. Poll Task Status (Continuous Check):

   • Use the obtained task_id to periodically poll the task status using an HTTP GET request (e.g., GET /s2s/v2.0/task/nail-vto/${task_id}).
   • Continuously monitor for:
     • Task_status = "success" (process completed).
     • Task_status = "error" (resolve or retry if applicable).
   • Update the workflow accordingly once the status transitions to success.

This structured workflow ensures efficient integration with user inputs, automated monitoring of tasks, and seamless retrieval of results.

• API Playground

Interactively explore and test the API using our official playground:

API Playground: http://yce.makeupar.com/api-console/en/api-playground/ai-nail-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.

2. Prepare an effect template

   • There are four distinct setup modes available for this purpose:

     1. Customizing the color and aligning it with your current nail look
     2. Utilizing a preset design and a specific shape to create your vision
     3. Adding pressed-on nails and linking them with your existing original nail image
     4. Providing image links for pressing-on nail products that match

   • Effect Template JSON Schemas

     {
         "version": "1.0",
         "effect_type": "nail_polish", // valid values: ['nail_polish', 'press_on_nails']
         "effects": [],
         "ref_file_ids": []
     }

     • Effect Format

       • Nail Polish - Color
       {
           "sub_type": "color",
           "finger": "index", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']
           "color": "#ff0000",
           "texture": "cream", // valid values: ['matte', 'cream', 'metallic', 'jelly', 'sheer', 'pearl', 'textured', 'shimmer_coarse', 'shimmer_fine']
           "transparency": 0, // 0-100, for textures except metallic
           "reflection": 0, // 0-100
           "contrast": 0, // 0-100
           "roughness": 0, // 0-100
           "shimmer_opacity": 0, // 0-100, for texture pearl
           "shimmer_size": 0, // 0-100, for texture shimmer_coarse and shimmer_fine
           "textured_size": 0, // 0-100, for texture textured
       }

       • Nail Polish - Design
       {
           "sub_type": "design",
           "finger": "index", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']
           "ref_file_url": "",  // Optional; Either ref_file_id or ref_file_url must be filled, but only one can be selected.
           "ref_file_index": 0, // This field is optional unless uploading is selected. Index corresponding to ref_file_ids under the root node
           "texture": "cream", // valid values: ['matte', 'cream', 'metallic', 'jelly', 'sheer', 'pearl', 'textured', 'shimmer_coarse', 'shimmer_fine']
           "transparency": 0, // 0-100, only for textures except metallic
           "reflection": 0, // 0-100
           "contrast": 0, // 0-100
           "roughness": 0, // 0-100
           "shimmer_opacity": 0, // 0-100, for texture pearl
           "shimmer_size": 0, // 0-100, for texture shimmer_coarse and shimmer_fine
           "textured_size": 0, // 0-100, for texture textured
       }
       

       • Press On Nails - Color
       • You can find the latest shape values at: https://plugins-media.makeupar.com/wcm-saas/shapes/nails.json
       {
           "sub_type": "color",
           "finger": "index", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']
           "shape": "square_oval", // Please check the nails.json. valid values: ['square_oval','square_square','square_squoval','squoval_oval','squoval_square','squoval_squoval','oval_oval','oval_square','oval_squoval','almond_oval','almond_square','almond_squoval','stiletto_oval','stiletto_square','stiletto_squoval],
           "length": 1.0, // 0.8-2.15, for shapes except original
           "color": "#ff0000",
           "texture": "cream", // valid values for other shapes: ['matte', 'cream', 'metallic']
           "reflection": 0, // 0-100
           "contrast": 0, // 0-100
           "roughness": 0 // 0-100
       }

       • Press on Nails - Design
       {
           "sub_type": "design",
           "finger": "index", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']
           "ref_file_url": "",  // Optional; Either ref_file_id or ref_file_url must be filled, but only one can be selected.
           "ref_file_index": 0, // This field is optional unless uploading is selected. Index corresponding to ref_file_ids under the root node
           "texture": "cream", // valid values: ['matte', 'cream', 'metallic']
           "reflection": 0, // 0-100
           "contrast": 0, // 0-100
           "roughness": 0, // 0-100
       }
       

   • Effect Template Design Logic

     1. Detect effect type (press_on_nails vs nail_polish).
     2. Iterate over each entry in effects:

     If sub_type === "color" → map fields directly, fill missing texture‑related keys with defaults. If sub_type === "design" →

     • If the user gave a ref_file_url, keep it and omit ref_file_index.
     • If the user supplied an index (ref_file_index), ensure ref_file_ids exists and the index is valid; then set "ref_file_id": ref_file_ids[index] (optional – some back‑ends expect the raw index, not id).
     1. Normalize numeric ranges – clamp any out‑of‑range values to 0‑100 or length limits.
     2. Add missing optional keys with defaults so the schema validator passes.
     3. Serialize the final object as JSON (compact or pretty for debugging).

   • Example Payload (ready to send)

     {
     "version": "1.0",
     "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/nail_user_photo_01_27d4260646.jpg",
     "effect_type": "press_on_nails",
     "ref_file_ids": [
         "Ks3kh+1nPpVNm8iJb5374CWtBzkT4B44NPJwXbBKqVxfjK3xgCQ+hRt9MJXBFaud",
         "+Z7PSjuzigvsc3S/Yli1A4WN7c3J6NJHFqK2iUlqD2BfjK3xgCQ+hRt9MJXBFaud"
     ],
     "effects": [
         {
         "sub_type": "design",
         "finger": "thumb",
         "texture": "cream",
         "reflection": 100,
         "contrast": 50,
         "roughness": 0,
         "ref_file_index": 0
         },
         {
         "sub_type": "design",
         "finger": "index",
         "texture": "cream",
         "reflection": 100,
         "contrast": 50,
         "roughness": 0,
         "ref_file_index": 1
         },
         {
         "sub_type": "design",
         "finger": "middle",
         "texture": "cream",
         "reflection": 100,
         "contrast": 50,
         "roughness": 0,
         "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_3_9ce2ddc47a.png"
         },
         {
         "sub_type": "design",
         "finger": "pinky",
         "texture": "cream",
         "reflection": 100,
         "contrast": 50,
         "roughness": 0,
         "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_5_f6e46dd56f.png"
         },
         {
         "sub_type": "design",
         "finger": "ring",
         "texture": "cream",
         "reflection": 100,
         "contrast": 50,
         "roughness": 0,
         "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_4_2103ca8cac.png"
         }
     ]
     }

3. Create a Nail VTO Task and Poll for Results

   Once you have an image and a complete effect payload, 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/nail-vto

   • Polling Endpoint

     GET /s2s/v2.0/task/nail-vto/{task_id}

File Specs & Errors

• AI Nail Virtual Try-On Specification

Supported Nail View A single nail image in a clear front view without obstruction.

Press-on nail design image sample:

Supported Hand View

• Support only one hand in the input image
• The area of hand palm is better to be at least half of that of input image
• The aspect ratio of the input image is better to be 1:1, 3:4, 4:3
• The nails of fingers should not be occluded
• It is better that there is no nail tip and nail polish on the nail

• Error Codes

• Environment & Dependency

JS Camera Kit

JavaScript Camera Kit SDK Documentation

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.

Quick Start Example

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

Prerequisites

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

Integration Guide

Step 1: Initialize the Module

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

Step 2: Add Event Handlers

Register listeners for camera events and capture results.

Step 3: Open Camera Kit

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

Step 4: Receive Captured Results

Images arrive via the faceDetectionCaptured event.

Step 5: Close Module

Clean up resources when done.

API Reference

YMK.init(args)

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

Methods

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

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

Configuration Object

Parameters

Face Ratio Control

Controls the acceptable proportion of the detected face.

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

Face Boundary Control

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

Head Pose Angle Control

Controls allowable head orientation.

Lighting Control

Defines acceptable lighting quality and uniformity.

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.

Events Reference

Lifecycle & Status Events

Camera Events

Detection Events

faceQualityChanged

Fires continuously during detection as quality metrics update.

Example Payload:

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:

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:

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

Multi-Phase Capture

Modes like hairtype or hairfrizziness require multiple steps:

1. Front face
2. Turn right
3. 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

Unit Consumption