AI Face Reshape

Integration Guide

This guide walks you through:

Workflow for AI Face Reshape API:

Endpoint: /s2s/v2.0/file

Authentication Required: Authorization: Bearer YOUR_API_KEY

Workflow Steps:

1. Image Upload Preparation:

   • Prepare a selfie image for upload.
   • Call the File API /s2s/v2.0/file to obtain the upload URL and associated file_id.
   • Upload the selfie image using the provided upload URL.

2. Optional Preprocessing For Multiple Faces:

   • Preprocess the selfie image if there are more than one face in the image.

3. Face Reshape Effect Setup:

   • Begin by selecting suitable face reshape parameters of Eye, Face, Lip or Nose.

4. Initiate AI Task and Obtain Task ID:

   • Send the file_id along with the chosen effect configuration via an HTTP POST request to /s2s/v2.0/task/face-reshape.
   • Await a unique task ID in the response, which identifies this interaction.

5. 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/face-reshape/${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-face-reshape/

• 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 AI 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

   • Preprocessing Output detected bounding boxes in pixel coordinate. Use the index of result to create a Face Reshape AI task later.

     {
         "timed": number,
         "result": [
             {
                 "left": number,
                 "top": number,
                 "width": number,
                 "height": number
             }
         ]
     }

     • Effect Template JSON Schemas
     {
         "version": "1.0",
         "index": 0,
         "features": {},
         "global": {
         "skin_smooth_strength": 50,
         "skin_smooth_color_intensity": 50,
         },
     }

     index: index of detected face from preprocessing. optional, default 0. features: required at least 1, non-zero face reshape parameter, cannot be all zero. skin_smooth_strength: 0~100 skin_smooth_color_intensity: 0~100

     • Effect Format
     • Face default range: -100~100 range of cheekbones and jaws: 0~100 all feature values must not be zero at the same time, at least one feature value must be non-zero
     {
         "cheekbones": 0,
         "jaw": 0,
         "face_reshape_left": 0,
         "face_reshape_right": 0,
         "face_width": 0,
         "chin_reshape_left": 0,
         "chin_reshape_right": 0,
         "chin_length": 0,
     }

     • Eye default range: -100~100 all feature values must not be zero at the same time, at least one feature value must be non-zero
     {
         "eye_size_left": 0,
         "eye_size_right": 0,
         "eye_distance": 0,
         "eye_angle": 0,
         "eye_height": 0,
         "eye_width": 0,
     }

     • Nose default range: -100~100 all feature values must not be zero at the same time, at least one feature value must be non-zero
     {
         "nose_bridge_width": 0,
         "nose_lift": 0,
         "nose_size": 0,
         "nose_tip": 0,
         "nose_tip_width": 0,
         "nose_wing": 0
     }

     • Lip default range: -100~100 all feature values must not be zero at the same time, at least one feature value must be non-zero
     {
         "lip_size": 0,
         "lip_width": 0,
         "lip_peak": 0,
         "lip_height_top": 0,
         "lip_height_bottom": 0,
     }

     • Example Payload (ready to send)
     {
     "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/face_reshape_01_85c8ffc055.jpg",
     "version": "1.0",
     "source": "yco",
     "features": {
         "eye_size_left": 80,
         "eye_size_right": 80,
         "eye_width": 0,
         "eye_height": 0,
         "eye_distance": 0,
         "eye_angle": 0,
         "face_reshape_left": 0,
         "face_reshape_right": 0,
         "chin_reshape_left": 20,
         "chin_reshape_right": 20,
         "chin_length": 0,
         "face_width": -30,
         "cheekbones": 0,
         "jaw": 0,
         "lip_size": 10,
         "lip_width": 40,
         "lip_height_top": 10,
         "lip_height_bottom": 10,
         "lip_peak": -10,
         "nose_size": 30,
         "nose_lift": -20,
         "nose_bridge_width": 10,
         "nose_tip": -10,
         "nose_wing": 30,
         "nose_tip_width": 30
     },
     "global": {
         "skin_smooth_strength": 50,
         "skin_smooth_color_intensity": 50
     }
     }

3. Create a Face Reshape AI 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/face-reshape

   • Polling Endpoint

     GET /s2s/v2.0/task/face-reshape/{task_id}

File Specs & Errors

• AI Face Reshape Specification

Supported Selfie View A selfie with width and height of a face larger than 1/20 of image width and heigh. Face angle less than 30 degree for pitch, yaw and rolling.

Facial Customization Parameters Guide

Note: “Left” and “Right” refer to the character's perspective, not the viewer's side of the screen.

• Supported Formats & Dimensions

• 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