YouCam Online Editor AI APIs (v1.6)

Last modified: Nov. 24, 2025 f3b9a57

The YouCam Online Editor AI APIs are series of AI effects that let you beautify your photos, as well as generate amazing aesthetic creations beyond human imagination. Let the magic begin.

PLEASE NOTE that by reading this API documentation, or by setting up code pursuant to the instructions in this API documentation, you acknowledge it adheres to Perfect Corp's Privacy policy, and Terms of Service. And If you have any issue, please contact: YouCamOnlineEditor_API@perfectcorp.com

YouCam Online Editor is a powerful and easy-to-use AI platform that provides beautiful and true-to-life visual effects thanks to the latest AI technology. This API document will briefly introduce how to integrate these awesome AI effects into your business. YouCam Online Editor AI APIs are standard RESTful APIs to let you easily integrate to your website, e-commerce platforms, iOS/Android APP, applets, mini-programs, and more.

The YouCam Online Editor AI APIs are built on top of RESTful web APIs. The API server is the host of all APIs. Once you complete the authentication, you can start your AI tasks through the API Server.

• YouCam Online Editor AI API server:

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

To ensure fair usage and prevent abuse, our API implements rate limiting. There are two types of rate limits:

• Per IP Address

  Each IP address is allowed a maximum of 250 requests per 300 seconds with 5 queries per second(QPS). If this limit is exceeded, subsequent requests will receive a 429 Too Many Requests error.

• Per Access Token

  Each access token is allowed a maximum of 250 requests per 300 seconds with 5 queries per second(QPS). If this limit is exceeded, subsequent requests will receive a 429 Too Many Requests error.

Both conditions must be met for a request to be accepted. If either condition is not met, the request will receive a 429 Too Many Requests error. Please note that each query related to unit will be processed real-time. Other APIs can use the access token util expired.

It is recommended that you handle rate limit errors gracefully in your application by implementing the appropriate backoff and retry mechanisms.

V2 API Any files you upload are stored on our server for 24 hours, and then they're automatically deleted. Processed results are retained for 24 hours after completion.

V1 API Any files you upload are stored on our server for one day, and then they're automatically deleted. Files created by the system – the results you get – we keep those for 7 days before they're automatically removed.

Warning: Even though those result files are still good for 7 days, the link to download them might only be active for about two hours after they're created. If that download link expires, you can still access the file using its file ID – you can use that ID with another feature to get it.

AI Photo Editing	Supported Dimensions	Supported File Size	Supported Formats
AI Photo Enhance	Input: long side <= 4096, Output: long side <= 4096	< 10MB	jpg/jpeg/png
AI Photo Colorize	Input: long side <= 4096, Output: long side <= 4096	< 10MB	jpg/jpeg/png
AI Photo Color Correction	Input: long side <= 4096, Output: long side <= 4096	< 10MB	jpg/jpeg/png
AI Photo Lighting	4096x4096 (long side <= 4096, short side >= 256)	< 10MB	jpg/jpeg/png
AI Image Extender	Input: long side <= 4096, Output: short side <= 1024, long side <= 2048	< 10MB	jpg/jpeg/png
AI Replace	Input: long side <= 4096, Output: short side <= 1024, long side <= 2048	< 10MB	jpg/jpeg/png
AI Object Removal	Input: long side <= 4096, Output: long side <= 4096	< 10MB	jpg/jpeg/png
AI Image Generator	Input: long side <= 4096, Output: long side <= 1024	< 10MB	jpg/jpeg/png
Al Photo Background Removal	Input: long side <= 4096, Output: long side <= 4096	< 10MB	jpg/jpeg/png
AI Photo Background Blur	Input: long side <= 4096, Output: long side <= 4096	< 10MB	jpg/jpeg/png
AI Photo Background Change	Input: long side <= 4096, Output: long side <= 4096	< 10MB	jpg/jpeg/png

AI Portrait	Supported Dimensions	Supported File Size	Supported Formats
AI Avatar Generator	Input: long side <= 4096, Output: long side <= 1024	< 10MB	jpg/jpeg/png
AI Face Swap	4096x4096 (long side <= 4096), single face only, need to show full face	< 10MB	jpg/jpeg/png

AI Video Editing	Supported Dimensions	Supported File Size	Supported Formats
AI Video Enhance	input: long side <= 1920; output: max 2x input resolution, up to 60 sec, 30 FPS, 8 bit	<100MB	container: mov, mp4; video codec: MPEG-4, H.264 AVC; audio codec: aac, mp3;
AI Video Face Swap	input: long side <= 4096; output: 1280x720, 30 FPS, up to 30 sec, 8 bit, single face only	<100MB	container: mov, mp4; video codec: MPEG-4, H.264 AVC; audio codec: aac, mp3
AI Video Style Transfer	input: long side <= 4096; output: long side <= 1280, 16 FPS, up to 30 sec, 8 bit	<100MB	container: mov, mp4; video codec: MPEG-4, H.264 AVC; audio codec: aac, mp3

• Successful responses (100 - 399)
• Client error responses (400 - 499)
• Server error response (500 - 599)

General Error Code	Description
exceed_max_filesize	The input file size exceeds the maximum limit
invalid_parameter	The parameter value is invalid
error_download_image	There was an error downloading the source image
error_download_mask	There was an error downloading the mask image
error_decode_image	There was an error decoding the source image
error_decode_mask	There was an error decoding the mask image
error_download_video	There was an error downloading the source video
error_decode_video	There was an error decoding the source video
error_nsfw_content_detected	NSFW content was detected in the source image
error_no_face	No face was detected in the source image
error_pose	Failed to detect pose in the source image
error_face_parsing	Failed to perform face parsing on the source image
error_inference	An error occurred in the inference pipeline
exceed_nsfw_retry_limits	Retry limits exceeded to avoid generating NSFW image
error_upload	There was an error uploading the result image
error_multiple_people	Multiple people were detected in the source image
error_no_shoulder	Shoulders are not visible in the source image
error_large_face_angle	The face angle in the uploaded image is too large
error_hair_too_short	The input hair is too short
error_unexpected_video_duration	The video duration does not match the expected duration
error_bald_image	The input hairstyle is bald
error_unsupport_ratio	The aspect ratio of the input image is unsupported
unknown_internal_error	Other internal errors

---

First, you need to register a YouCam Online Editor account for free at https://yce.perfectcorp.com/. You can then purchase or subscribe to get your units to use the service. You can see your subscription plan, pay as you go units, and your usage record at https://yce.perfectcorp.com/api-console/en/api-keys/. You can go to the API Key tab under your account page to generate and maintain your API keys to start using the YouCam Online Editor AI APIs.

Overview

Starting from API version v1.5, we have introduced a simplified V2 API to streamline integration processes.

Scope:

• Skin V2 API
  • AI Skin Analysis
  • AI Aging Generator
  • AI Skin Tone Analysis
  • AI Face Analyzer
• Beauty V2 API
  • AI Makeup Virtual Try On
  • AI Look Virtual Try On
• Fashion V2 API
  • AI Clothes
  • AI Fabric
• Hair V2 API
  • AI Hair Color
  • AI Hairstyle Generator
  • AI Hair Extension
  • AI Hair Bang Generator
  • AI Hair Volume Generator
  • AI Wavy Hair
  • AI Hair Length Detection
  • AI Hair Type Detection
  • AI Hair Frizziness Detection
  • AI Beard Style Generator

    Note: V2 API is designed for workflow simplification only. It does not introduce advanced functionality. Both V1 APIs and V2 APIs use the same underlying AI models.

---

Key Changes in V2 API

1. Endpoint Reduction

• V1 API Endpoints:

  • POST /v1.0/client/auth – Authentication
  • POST /v1.1/file/ai-task – Upload a file
  • POST /v1.0/task/ai-task – Run an AI task
  • GET /v1.0/task/ai-task – Get the result

• V2 API Endpoints:

  • POST /v2.0/file/ai-task – Upload a file or provide a file URL
  • POST /v2.0/task/ai-task – Run an AI task
  • GET /v2.0/task/ai-task – Get the result

2. Authentication

• V1 API: Requires explicit call to Authentication endpoint.- V2 API: No separate authentication endpoint. - Include your API key in the request header using Bearer Token:

  Authorization: Bearer <API Key>
  

  You can find your API Key at https://yce.perfectcorp.com/api-console/en/api-keys/.

3. Image Input

• Supports both file upload and file URL as input sources.

4. Polling Mechanism

• Processed results are retained for 24 hours after completion.
• No need for short-interval polling.
• Flexible polling intervals within the 24-hour window.
• Important: Polling is still required to check task status, as execution time is not guaranteed.

5. JSON Structure Simplification

• List Style API now uses a simplified JSON parameter structure.
  • AI Hairstyle Generator: https://yce-api-01.perfectcorp.com/s2s/v2.0/task/template/hair-style
  • AI Clothes: https://yce-api-01.perfectcorp.com/s2s/v2.0/task/template/cloth

---

Summary

• V2 API = Simplified workflow, same AI models.- Reduced endpoints, easier authentication, flexible input options, improved polling, and cleaner JSON.

---

To complete the authentication and start using the AI APIs, you need:

1. Go to https://yce.perfectcorp.com/api-console/en/api-keys/ and create the API Key.

2. Upon creation is completed, it will show the API Key and the Secret key. Where your API Key is the client_id and the Secret key is the client_secret in this document to complete the authentication process.

   

   Warning: Please kindly note that your Secret key can only be copied at step #2. Once the dialog is closed, there is no method to obtain the Secret key again unless create an another API Key.

3. To obtain id_token, you need to follow the method below and convert client_secret into id_token

   Encrypt

   client_id=<client_id>&timestamp=<timestamp in millisecond>

   with RSA X.509 format Base64 encoded client_secret to obtain id_token

   JavaScript sample:

   let encrypt = new JSEncrypt();
   encrypt.setPublicKey(client_secret);
   let encrypted = encrypt.encrypt(
   `client_id=${client_id}&timestamp=${new Date().getTime()}`
   );
   console.log(encrypted);
   

   PHP sample:

   <?php
   class RSAPublicEncryption {
       private $publicKey;
   
       public function __construct($rawPublicKey) {
           $pemKey = "-----BEGIN PUBLIC KEY-----\n" .
                   chunk_split($rawPublicKey, 64, "\n") .
                   "-----END PUBLIC KEY-----";
   
           $this->publicKey = openssl_pkey_get_public($pemKey);
           if ($this->publicKey === false) {
               throw new Exception('Invalid public key');
           }
       }
   
       public function encrypt($data) {
           $encrypted = '';
           $result = openssl_public_encrypt($data, $encrypted, $this->publicKey);
           if ($result === false) {
               throw new Exception('Encryption failed');
           }
           return base64_encode($encrypted);
       }
   }
   
   try {
       $rawPublicKey = "<client_secret>";
   
       $rsa = new RSAPublicEncryption($rawPublicKey);
   
       $data = "client_id=<client_id>&timestamp=<timestamp in millisecond>";
   
       $encrypted = $rsa->encrypt($data);
       echo "Encrypted: " . $encrypted . "\n";
   
   } catch (Exception $e) {
       echo "Error: " . $e->getMessage();
   }
   ?>
   

4. Calling the authentication API to obtain the access_token to start using the YouCam Online Editor AI APIs.

Please note that your units will be consumed when the resulting image was successfully generated. You may refer to the AI API page regarding the price of each task and how to obtain units.

---

V1 API AI Task Execution Workflow and Style Querying APIs

We support three categories of AI tasks:

• Direct Execution Tasks
  These tasks operate directly on user input without additional configuration. Examples include AI Photo Enhance and AI Image Extender.

• Style-Based Tasks
  These require an initial style selection before execution. Examples include AI Hairstyles Try-On, AI Studio Generator, and AI Clothes Try-On.
  There are two ways to retrieve styles for these tasks:

  • Version 1.0
    • v1.0/task/style-group/{feature}: Lists style groups.
    • v1.0/task/style/{feature}: Fetches styles within the selected group.
  • Version 1.1
    • v1.1/task/style/{feature}: Retrieves styles categorized by predefined groups. If no category_id is specified, the response includes either styles or subcategories. Single-layer categories contain only styles, while multi-layer categories include subcategories. To explore a subcategory, provide its ID as category_id and query the endpoint again.

• Preprocessing-Required Tasks
  These tasks require an initial detection step before execution. For example, AI Face Swap needs a face detection task to identify faces in the input. After detection, you can specify which face to swap in the main AI task.

---

V1 API Integration Guide - Direct Execution Tasks

Now, let's consider an example usage flow of an AI Photo Enhance API calling sequence.

1. Upload file using the File API
   After successfully authorizing and getting the access_token, you can call 'file/enhance' to acquire the upload URL and a File ID associated with it. 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.

2. Run an AI task to obtain it's task_id
   Subsequently, calling POST 'task/enhance' with the File ID executes the enhance task and obtains a task_id.

3. Polling to check the status of a task until it succeed or error
   This task_id is used to monitor the task's status through polling GET 'task/enhance' to retrieve the current engine status. Until the engine completes the task, the status will remain 'running', and no units will be consumed during this stage.

   Warning: Please note that, Polling to check the status of a task based on it's polling_interval is mandotary. A task will be timed out if there is no polling request within the polling_interval, even if the task is processed succefully(Your unit(s) will be consumed).

   Warning: You will get a InvalidTaskId error once you check the status of a timed out task. So, once you run an AI task, you need to polling to check the status within the polling_interval until the status become either success or error.

4. Get the result of an AI task once success
   The task will change to the 'success' status after the engine successfully processes your input file and generates the resulting image. You will get an url of the processed image and a dst_id that allow you to chain another AI task without re-upload the result image. Your units will only be consumed in this case. If the engine fails to process the task, the task's status will change to 'error' and no unit will be consumed.
   When deducting units, the system will prioritize those nearing expiration. If the expiration date is the same, it will deduct the units obtained on the earliest date.

V1 API Integration Guide - Style-Based Tasks

Now, let's consider an example usage flow of an AI Clothes API calling sequence to try on predefined outfit styles.

1. Upload file using the File API
   Using the v1.1/file/cloth API to upload a target user image.

   • Image Requirements
     • See details in File Specs & Errors.
   • Upload a full body photo of yourself. The virtual outfit changer works best with high resolution photos that show your clothes clearly. The photo background should not have too many people or distracting objects.

2. List Predefined Outfit Styles
   There are two ways to list outfits for AI Clothes virtual try-on:

   • v1.0/task/style-group/cloth and v1.0/task/style/cloth: Retrieve style groups first, then fetch styles within the chosen group.
   • v1.1/task/style/cloth: Fetch a predefined style list by category. If you don’t specify a category_id, each category will contain either styles or subcategories. Categories with a single layer only include styles, while multi-layered categories will have subcategories. To explore a subcategory, pass its ID as category_id and call the list again.

3. Run an AI task to obtain it's task_id
   Execute AI task v1.0/task/cloth with the clothing image file_id as ref_ids and the target user image file_id as src_ids.

4. Polling to check the status of a task until it succeed or error
   This task_id is used to monitor the task's status through polling GET 'v1.0/task/cloth' to retrieve the current engine status. Until the engine completes the task, the status will remain 'running', and no units will be consumed during this stage.

   Warning: Please note that, Polling to check the status of a task based on it's polling_interval is mandotary. A task will be timed out if there is no polling request within the polling_interval, even if the task is processed succefully(Your unit(s) will be consumed).

   Warning: You will get a InvalidTaskId error once you check the status of a timed out task. So, once you run an AI task, you need to polling to check the status within the polling_interval until the status become either success or error.

5. Get the result of an AI task once success
   The task will change to the 'success' status after the engine successfully processes your input file and generates the resulting image. You will get an url of the processed image and a dst_id that allow you to chain another AI task without re-upload the result image.
   Your units will only be consumed in this case. If the engine fails to process the task, the task's status will change to 'error' and no unit will be consumed.
   When deducting units, the system will prioritize those nearing expiration. If the expiration date is the same, it will deduct the units obtained on the earliest date.

---

1. Q: What does 'Unit' mean, and how is it used?
   A: Please note that credits are exclusively used within the YouCam Online Editor UI, whereas units are designated solely for AI API usage. Throughout this document, all references to 'credit' or 'unit' pertain to the Unit.

   
   Please check the page https://yce.perfectcorp.com/ai-api for details on how many units each AI feature consumes.
   
   

2. Q: Why am I getting InvalidTaskId error?
   A: You will get a InvalidTaskId error once you check the status of a timed out task. So, once you run an AI task, you need to polling to check the status within the polling_interval until the status become either success or error.
   
   

3. Q: What is client_id, client_secret and id_token?
   A: Your API Key is the client_id and the Secret key is the client_secret. And please follow the Quick start guide to get the id_token to complete the authentication process.

   For more information and questions, please refer to our blog page and the FAQ page. Or send an e-mail to YouCamOnlineEditor_API@perfectcorp.com. Our customer success team are very happy to help. ;)
   
   

4. Q: How to uplaod an image through curl?
   A: curl --location --request PUT '{url_api_response}' --header '{headers_in_api_response}' --data-binary @'{local_file_path}'

   curl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/ttl30/320554715144259928/77022501909/v2/aeMNNB0KmUIP8rnQ996tC5Q/49c9f5cb-882c-41d9-a435-73b951cdf018.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250507T110821Z&X-Amz-SignedHeaders=content-length%3Bcontent-type%3Bhost&X-Amz-Expires=7200&X-Amz-Credential=AKIARB77EV5Y5D7DAE3S%2F20250507%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Signature=efaeed8fd3da03be0f0c9ed1274325651ef2adffb51321cc489f6baa4a80e394' --header 'Content-Type: image/jpg' --header 'Content-Length: 50000'  --data-binary @'./test.jpg'
   

   
   
   

5. Q: What platforms does the AI API support? Can it be used on mobile devices?
   A: The AI API works seamlessly across different platforms. Since it's built on a standard RESTful API, you can use it for server-to-server communication, on mobile devices, or in a web browser - whatever best fits your needs.
   
   

6. Q: Is it possible to use the AI API with Flutter on both Android and iOS?
   A: Absolutely. Since AI APIs are standard RESTful APIs, you can access them using Flutter's built-in HTTP APIs to make requests. Here are some official Flutter documents on making network queries.

   • https://docs.flutter.dev/cookbook/networking/fetch-data
   • https://pub.dev/packages/http

   And here’s a simple way to call a http GET with Bearer Authentication using Flutter’s http package:

   import 'dart:convert';
   import 'package:http/http.dart' as http;
   
   Future<void> fetchData() async {
       String token = "your_bearer_token_here"; // Replace with your actual token
   
       final response = await http.get(
           Uri.parse("https://yce-api-01.perfectcorp.com/s2s/v1.0/task/ai-task"),
           headers: {
           "Content-Type": "application/json",
           "Authorization": "Bearer $token",
           },
       );
   
       if (response.statusCode == 200) {
           print("Data fetched successfully: ${response.body}");
       } else {
           print("Failed to fetch data: ${response.statusCode}");
       }
   }
   

   Key Steps to Auth:

   • Retrieve the Token – You can store and retrieve the token using SharedPreferences or another secure storage method.
   • Include the Token in Headers – Use "Authorization": "Bearer $token" in the request headers.
   • Handle Expired Tokens – If the API returns a 401 InvalidAccessToken error, refresh the token if needed.
     
     

7. Q: API key is the API key, Where can I find the secret key?
   A: The secret key is created only when you first generate it. So make sure to save it right away, you won't be able to see it again later.
   
   

8. Q: Is it possible to integrate AI APIs into your website using Wix?
   A: We do not currently have an official integration guide for using AI APIs with Wix. However, the RESTful API itself does not impose any restrictions on the platform, provided it supports standard web queries.

   We strongly recommend to begin by reading the official documentation provided by Wix: https://dev.wix.com/docs/develop-websites/articles/get-started/integrate-with-3rd-parties

   Wix offers several methods for integrating with third-party APIs, primarily through its Velo development platform:

   • Fetch API: This is the most common method and an implementation of the standard JavaScript Fetch API. It allows you to make HTTP requests to external APIs from your Wix site's frontend or backend code. Backend calls: Recommended for security (especially for APIs requiring keys) and to avoid CORS issues. Use the Secrets Manager to securely store API keys. Frontend calls: Possible but less secure and may encounter CORS restrictions.

   • npm Packages: Velo supports the use of approved npm packages, allowing you to leverage a wide array of prebuilt JavaScript modules to extend your site's functionality with third-party features.

   • Service Plugins (formerly SPIs/Custom Extensions): These enable you to inject custom logic or integrate third-party services directly into Wix's business solutions (e.g., Wix Stores, Wix Bookings). Service plugins allow you to customize specific parts of existing app flows or integrate external services for functionalities like custom shipping rates, dynamic pricing, or alternative payment providers.

   • HTTP Functions: You can expose your site's functionality as an API, allowing third-party services to call your Wix site''s backend functions and interact with your site's data or logic.

   Steps for Integration (using Fetch API as an example):

   • Store API Keys: If the third-party API requires authentication, store sensitive credentials like API keys securely in Wix's Secrets Manager. Import wix-fetch: In your Velo backend or frontend code, import the wixFetch module.

     import { fetch } from 'wix-fetch';
     

   • Make API Calls: Use the fetch function to send requests to the third-party API, including necessary headers and body data.

     export async function getWeatherData() {
         const apiKey = await getSecret("yourApiKeyName"); // Retrieve from Secrets Manager
         const response = await fetch(`https://api.weatherapi.com/v1/current.json?key=${apiKey}&q=London`, {
             method: 'GET',
             headers: {
                 'Content-Type': 'application/json'
             }
         });
         const data = await response.json();
         return data;
     }
     

   • Handle Responses: Process the data received from the API and integrate it into your site's design or functionality.
     
     

9. Q: Is it possible to integrate AI APIs into WooCommerce?
   A: We do not currently have an official integration guide for using AI APIs with WooCommerce. However, the RESTful API itself does not impose any restrictions on the platform, provided it supports standard web queries.

   We strongly recommend to begin by reading the official documentation provided by WooCommerce: https://woocommerce.com/document/woocommerce-rest-api/

   Integrating third-party APIs with WooCommerce enhances store functionality and streamlines operations. This can be achieved through various methods:

   • Utilizing WooCommerce REST API:

     WooCommerce provides a robust REST API that allows external applications to interact with your store data. You can create API keys with specific permissions (Read, Write, or Read/Write) in WooCommerce > Settings > Advanced > REST API. This enables you to automate tasks like inventory syncing, order processing, customer data synchronization, and more, by building custom integrations or using third-party services that leverage this API.

   • Employing Plugins:

     Many WordPress and WooCommerce plugins are designed specifically for integrating with popular third-party services like payment gateways, shipping carriers, CRM systems, and accounting software. Plugins often offer pre-built integrations, simplifying the setup process and reducing the need for custom coding. Examples include plugins for specific payment processors (e.g., Stripe, PayPal), shipping solutions (e.g., FedEx, USPS), or general API integration tools like WPGet API.

   • Custom Code and Webhooks:

     For unique integration needs or when a suitable plugin isn't available, you can implement custom code within your WordPress theme or a custom plugin. This involves using WordPress/WooCommerce hooks and filters to trigger API calls at specific events (e.g., woocommerce_payment_complete for post-purchase actions). Webhooks can also be used to send real-time data from WooCommerce to a third-party service when certain events occur (e.g., new order, product update).

   
   
   

1. Invalid TaskId Error
   Why: You’ll receive an InvalidTaskId error if you attempt to check the status of a task that has timed out. Therefore, once an AI task is initiated, you’ll need to poll for its status within the polling_interval until the status changes to either success or error.
   Solution: To avoid the task becoming invalid, it’s necessary to implement a timed loop that queries the task status at regular intervals within the allowed polling window.

2. 500 Server Error / unknown_internal_error
   A: Important: Simply calling the File API does not upload your file. You must manually upload the file to the URL provided in the File API response. That URL is your upload destination, make sure the file is successfully transferred there before proceeding.
   Before calling the AI API, ensure your file has been successfully uploaded. Use the File API to retrieve an upload URL, then upload your file to that location. Once the upload is complete, you'll receive a file_id in the response, this ID is what you'll use to access AI features related to that file.
   
   

3. 404 Not Found error when using AI APIs
   A: Important: Simply calling the File API does not upload your file. You must manually upload the file to the URL provided in the File API response. That URL is your upload destination, make sure the file is successfully transferred there before proceeding.
   Before calling the AI API, ensure your file has been successfully uploaded. Use the File API to retrieve an upload URL, then upload your file to that location. Once the upload is complete, you'll receive a file_id in the response, this ID is what you'll use to access AI features related to that file.
   
   

4. The API response returns the same style ID on the Postman
   A: The is because Postman (Pretty view) and Chrome use JavaScript to parse JSON responses. In JavaScript, numbers larger than 9007199254740991 (2^53-1) cannot be represented precisely. They are rounded to the nearest representable value, which makes different IDs appear identical (e.g., 219691778809271815 → 219691778809271800).
   

   • Precision Loss in JavaScript/JSON Error Handling
     • Cause: JavaScript's Number type cannot safely handle integers beyond 2^53 - 1, leading to silent truncation or rounding.
     • Solution: Use a JSON parser like json-bigint to treat IDs as strings and retain full precision.
       
       

Check your unit details and usage history. Please note that credits are exclusively used within the YouCam Online Editor UI, whereas units are designated solely for AI API usage. Throughout this document, all references to 'credit' or 'unit' pertain to the Unit.

Webhook

Webhooks allow your application to receive asynchronous notifications when an AI task completes with either a success or error status. Notifications are sent to an HTTP endpoint you control and follow the Standard Webhooks Specification.

---

Webhook Secret

Construction of Webhook Secret

We use HMAC-SHA256 signature schme webhook secret, and webhook secret is base64 encoded, prefixed with whsec_ for easy identification.

Example webhook secret:

whsec_NDQzMzYxNzkzMzE0NjYyNDM6OTIxOTcwNDIxODQ

Implement Webhook with Standard Webhooks Library

We strongly recommend using an official implementation of the Standard Webhooks Library, and you do not have to worry about the signature validation details.

Using an official implementation also ensures secure and correct signature validation.

https://github.com/standard-webhooks/standard-webhooks/tree/main?tab=readme-ov-file#reference-implementations

Implement Webhook by Yourself

Please carefully understand the construction of the webhook secret, refer to Symmetric part of Signature scheme.

When you are trying to sign signature input, please remove the whsec_ prefix and base64 decode the remaining string to obtain the actual bytes of secret to do HMAC-SHA256 hash.

---

Webhook Request Example

POST https://yourdomain.com/webhook-endpoint
Content-Type: application/json
webhook-id: msg_1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4:1761112848
webhook-timestamp: 1761112900
webhook-signature: v1,vyVNWrjoZcBK1JXrFGkdDKK2slo5+Q5yfzpkHmqO5R0=

{
  "created_at": 1761112848,
  "data": {
    "task_id": "1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4",
    "task_status": "success"
  }
}

---

HTTP Headers

webhook-id

A unique identifier for the webhook delivery. This value remains consistent across retries and should be used for idempotency handling.

webhook-timestamp

The Unix epoch timestamp (seconds) when the webhook was sent.

webhook-signature

'v1' followed by a comma (,), followed by the base64 encoded HMAC-SHA256 signature.

'v1' indicates the version of the signature scheme, and is currently the only supported version.

The base64 encoded HMAC-SHA256 signature is the result of signing signature input using your webhook secret.

Signature input format:

{webhook-id}.{webhook-timestamp}.{raw-minified-json-body}

Example signed content:

msg_1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4:1761112848.1761112900.{"created_at":1761112848,"data":{"task_id":"1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4","task_status":"success"}}

---

Request Body

created_at

Unix epoch timestamp (seconds) indicating when the task completed.

data

Contains the event payload.

Field	Description
task_id	The task identifier returned when the task was created. Use this ID to query the final task result.
task_status	Task completion status. Possible values: success, error.

---

Webhook Integration Guide

1. Prepare a webhook endpoint on your server. Ensure the endpoint accepts POST requests and is accessible via HTTPS.

2. Create a webhook in the API Console.

3. Run an AI task and record the task_id.

4. Process webhook notifications using the task_id to retrieve task results.

---

Creating a Webhook Endpoint

Visit the API Console's Webhook Management page:

https://yce.perfectcorp.com/api-console/en/webhook/

1. Locate the Webhook Section

2. Create a New Webhook Endpoint

You may configure up to 10 webhook endpoints concurrently.

3. Secure Your Webhook Secret

Your webhook secret is used to validate the webhook-signature. Keep it safe and never expose it publicly.

4. Manage Existing Webhooks

---

Handling Webhook Requests on Your Server

We recommend using an official implementation of the Standard Webhooks Library:

https://github.com/standard-webhooks/standard-webhooks/tree/main?tab=readme-ov-file#reference-implementations

This ensures secure and correct signature validation.

You can also test or debug payloads using the Standard Webhooks Simulator:

https://www.standardwebhooks.com/simulate

Verifying Webhook Signatures

Consider the webhook request example:

POST https://yourdomain.com/webhook-endpoint
Content-Type: application/json
webhook-id: msg_1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4:1761112848
webhook-timestamp: 1761112900
webhook-signature: v1,vyVNWrjoZcBK1JXrFGkdDKK2slo5+Q5yfzpkHmqO5R0=

Request body:

{
  "created_at": 1761112848,
  "data": {
    "task_id": "1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4",
    "task_status": "success"
  }
}

Signature input format will be like:

{webhook-id}.{webhook-timestamp}.{raw-minified-json-body}

Example signed content:

msg_1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4:1761112848.1761112900.{"created_at":1761112848,"data":{"task_id":"1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4","task_status":"success"}}

Veriry HMAC-SHA256 encrypted signed content using your webhook secret key with the received webhook-signature. Example:

v1,vyVNWrjoZcBK1JXrFGkdDKK2slo5+Q5yfzpkHmqO5R0=

AI Skin Analysis

AI skincare analysis technology harnesses the power of artificial intelligence to analyze various aspects of the skin, from texture and pigmentation to hydration and pore size, with remarkable precision. By employing advanced algorithms and machine learning, AI skin analysis can offer personalized recommendations and skincare routines tailored to an individual's unique skin type and concerns.

This not only enhances the effectiveness of skincare products but also empowers users to make informed decisions about their skincare regimen. With the integration of AI skin analysis, individuals can now embark on a journey towards healthier, more radiant skin, guided by data-driven insights and the promise of more effective skincare solutions.

How to Take Photos for AI Skin Analysis

• Take a selfie facing forward
  • Just one clear shot, looking straight into the camera. Leave your hair down so it falls over your chest, and make sure you're staring directly ahead for that front-on view.
  • Instead, use the JS Camera Kit to take a photo. Just leave your hair down so it falls over your chest. Don't tie it up.

Workflow

1. Resize your source image
   Resize your photo to fit the supported dimensions - up to 1920 pixels on the long side and at least 480 pixels on the short side for SD, or up to 2560 pixels on the long side and at least 1080 pixels on the short side for HD. See details in File Specs & Errors

2. Image Upload Options
   

• Image Requirements

  • See details in File Specs & Errors. You can provide the source image in one of two ways:

• Upload via File API Use the endpoint:

  POST /v2.0/file/skin-analysis
  

  This returns a file_id for subsequent task execution.

  • Important: Simply calling the File API does not upload your file. You must manually upload the file to the URL provided in the File API response. That URL is your upload destination, make sure the file is successfully transferred there before proceeding.
    
    Before calling the AI API, ensure your file has been successfully uploaded. Use the File API to retrieve an upload URL, then upload your file to that location. Once the upload is complete, you'll receive a file_id in the response, this ID is what you'll use to access AI features related to that file.

    Warning: Please note that, you will get an 500 Server Error / unknown_internal_error or 404 Not Found error when using AI APIs if you do not upload the file to the URL provided in the File API response.

• Use an Existing Public Image URL Instead of uploading, you may supply a publicly accessible image URL directly when initiating the AI task.

3. Run an AI Skin Analysis task
   Once the upload is complete, you can select 4, 7, or 14 skin concerns to analyze using your file ID or image file url. Please refer to the Inputs & Outputs.
   Subsequently, calling POST 'task/skin-analysis' with the File ID or image file url executes the enhance task and obtains a task_id.

4. Get the result of an AI task once success
   This task_id is used to monitor the task's status through polling GET 'task/skin-analysis' to retrieve the current engine status. Until the engine completes the task, the status will remain 'running', and no units will be consumed during this stage.
   
   Processed results are retained for 24 hours after completion.- No need for short-interval polling.- Flexible polling intervals within the 24-hour window.- Important: Polling is still required to check task status, as execution time is not guaranteed.
   
   The task will change to the 'success' status after the engine successfully processes your input file and generates the resulting image. You will get an url of the processed image and a dst_id that allow you to chain another AI task without re-upload the result image. Your units will only be consumed in this case. If the engine fails to process the task, the task's status will change to 'error' and no unit will be consumed.
   When deducting units, the system will prioritize those nearing expiration. If the expiration date is the same, it will deduct the units obtained on the earliest date.

Debugging Guide

Warning: Please be advised that the system requires processing exactly 4, 7, or 14 distinct skin concerns at one time. Simultaneous use of SD and HD skin concern parameters is NOT supported. Attempting to deviate from these specifications will result in an InvalidParameters error.

• For example, if you run a task with 5 HD skin concerns, you will get an error as following:

  {
      "status": 400,
      "error": "must select 4, 7 or 14 distinct dst_actions",
      "error_code": "InvalidParameters"
  }
  

• If you mix using HD and SD skin concerns, you will get an error as following:

  {
      "status": 400,
      "error": "cannot mix HD and SD dst_actions",
      "error_code": "InvalidParameters"
  }
  

• If you misspell a skin concern or sending unknown skin concerns, you will get an error as following:

  {
      "status": 400,
      "error": "Not available dst_action abc123",
      "error_code": "InvalidParameters"
  }
  

---

Real-world examples:

Input Paramenter Description

There are two options for controlling the visual output of AI Skin Analysis results: either generate multiple images, with each skin concern displayed as an independent mask, or produce a single blended image using the enable_mask_overlay parameter. By default, the system outputs multiple masks, giving you full control over how to blend each skin concern mask with the image.

• Default: enable_mask_overlay false

• Set enable_mask_overlay to true

---

Output ZIP Data Structure Description

The system provides a ZIP file with a 'skinanalysisResult' folder inside. This folder contains a 'score_info.json' file that includes all the detection scores and references to the result images.

The 'score_info.json' file contains all the skin analysis detection results, with numerical scores and the names of the corresponding output mask files.

The PNG files are detection result masks that can be overlaid on your original image. Simply use the alpha values in these PNG files to blend them with your original image, allowing you to see the detection results directly on the source image.

File Structure in the Skin Analysis Result ZIP

• HD Skincare ZIP

  • skinanalysisResult
    • score_info.json
    • hd_acne_output.png
    • hd_age_spot_output.png
    • hd_dark_circle_output.png
    • hd_droopy_lower_eyelid_output.png
    • hd_droopy_upper_eyelid_output.png
    • hd_eye_bag_output.png
    • hd_firmness_output.png
    • hd_moisture_output.png
    • hd_oiliness_output.png
    • hd_radiance_output.png
    • hd_redness_output.png
    • hd_texture_output.png
    • hd_pore_output_all.png
    • hd_pore_output_cheek.png
    • hd_pore_output_forehead.png
    • hd_pore_output_nose.png
    • hd_wrinkle_output_all.png
    • hd_wrinkle_output_crowfeet.png
    • hd_wrinkle_output_forehead.png
    • hd_wrinkle_output_glabellar.png
    • hd_wrinkle_output_marionette.png
    • hd_wrinkle_output_nasolabial.png
    • hd_wrinkle_output_periocular.png

• SD Skincare ZIP

  • skinanalysisResult
    • score_info.json
    • acne_output.png
    • age_spot_output.png
    • dark_circle_v2_output.png
    • droopy_lower_eyelid_output.png
    • droopy_upper_eyelid_output.png
    • eye_bag_output.png
    • firmness_output.png
    • moisture_output.png
    • oiliness_output.png
    • pore_output.png
    • radiance_output.png
    • redness_output.png
    • texture_output.png
    • wrinkle_output.png

• JSON Data Structure (score_info.json)

  • "all": A floating-point value between 1 and 100 representing the general skin condition. A higher score indicates healthier and more aesthetically pleasing skin condition.

  • "skin_age": AI-derived skin age relative to the general population distribution across all age groups.

  • Each category contains:

    • "raw_score": A floating-point value ranging from 1 to 100. A higher score indicates healthier and more aesthetically pleasing skin condition.
    • "ui_score": An integer ranging from 1 to 100. The UI Score functions primarily as a psychological motivator in beauty assessment. We adjust the raw scores to produce more favorable results, acknowledging that consumers generally prefer positive evaluations regarding their skin health. This calibration serves to instill greater confidence in users while maintaining the underlying beauty psychology framework.
    • "output_mask_name": The filename of the corresponding output mask image.

  • Categories and Descriptions

    • HD Skincare:

      • "hd_redness": Measures skin redness severity.
      • "hd_oiliness": Determines skin oiliness level.
      • "hd_age_spot": Detects age spots and pigmentation.
      • "hd_radiance": Evaluates skin radiance.
      • "hd_moisture": Assesses skin hydration levels.
      • "hd_dark_circle": Analyzes the presence of dark circles under the eyes.
      • "hd_eye_bag": Detects eye bags.
      • "hd_droopy_upper_eyelid": Measures upper eyelid drooping severity.
      • "hd_droopy_lower_eyelid": Measures lower eyelid drooping severity.
      • "hd_firmness": Evaluates skin firmness and elasticity.
      • "hd_texture": Subcategories[whole]; Analyzes overall skin texture.
      • "hd_acne": Subcategories[whole]; Detects acne presence.
      • "hd_pore": Subcategories[forehead, nose, cheek, whole]; Detects and evaluates pores in different facial regions.
      • "hd_wrinkle": Subcategories[forehead, glabellar, crowfeet, periocular, nasolabial, marionette, whole]; Measures the severity of wrinkles in various facial areas.

    • SD Skincare:

      • "wrinkle": General wrinkle analysis.
      • "droopy_upper_eyelid": Measures upper eyelid drooping severity.
      • "droopy_lower_eyelid": Measures lower eyelid drooping severity.
      • "firmness": Evaluates skin firmness and elasticity.
      • "acne": Evaluates acne presence.
      • "moisture": Measures skin hydration.
      • "eye_bag": Detects eye bags.
      • "dark_circle_v2": Analyzes dark circles using an alternative method.
      • "age_spot": Detects age spots.
      • "radiance": Evaluates skin brightness.
      • "redness": Measures skin redness.
      • "oiliness": Determines skin oiliness.
      • "pore": Measures pore visibility.
      • "texture": Analyzes overall skin texture.

  • Sample score_info.json of HD Skincare

    {
        "hd_redness": {
            "raw_score": 72.011962890625,
            "ui_score": 77,
            "output_mask_name": "hd_redness_output.png"
        },
        "hd_oiliness": {
            "raw_score": 60.74365234375,
            "ui_score": 72,
            "output_mask_name": "hd_oiliness_output.png"
        },
        "hd_age_spot": {
            "raw_score": 83.23274230957031,
            "ui_score": 77,
            "output_mask_name": "hd_age_spot_output.png"
        },
        "hd_radiance": {
            "raw_score": 76.57244205474854,
            "ui_score": 79,
            "output_mask_name": "hd_radiance_output.png"
        },
        "hd_moisture": {
            "raw_score": 48.694559931755066,
            "ui_score": 70,
            "output_mask_name": "hd_moisture_output.png"
        },
        "hd_dark_circle": {
            "raw_score": 80.1993191242218,
            "ui_score": 76,
            "output_mask_name": "hd_dark_circle_output.png"
        },
        "hd_eye_bag": {
            "raw_score": 76.67280435562134,
            "ui_score": 79,
            "output_mask_name": "hd_eye_bag_output.png"
        },
        "hd_droopy_upper_eyelid": {
            "raw_score": 79.05348539352417,
            "ui_score": 80,
            "output_mask_name": "hd_droopy_upper_eyelid_output.png"
        },
        "hd_droopy_lower_eyelid": {
            "raw_score": 79.97175455093384,
            "ui_score": 81,
            "output_mask_name": "hd_droopy_lower_eyelid_output.png"
        },
        "hd_firmness": {
            "raw_score": 89.66898322105408,
            "ui_score": 85,
            "output_mask_name": "hd_firmness_output.png"
        },
        "hd_texture": {
            "whole": {
                "raw_score": 66.3921568627451,
                "ui_score": 75,
                "output_mask_name": "hd_texture_output.png"
            }
        },
        "hd_acne": {
            "whole": {
                "raw_score": 59.92677688598633,
                "ui_score": 76,
                "output_mask_name": "hd_acne_output.png"
            }
        },
        "hd_pore": {
            "forehead": {
                "raw_score": 79.59770965576172,
                "ui_score": 80,
                "output_mask_name": "hd_pore_output_forehead.png"
            },
            "nose": {
                "raw_score": 29.139814376831055,
                "ui_score": 58,
                "output_mask_name": "hd_pore_output_nose.png"
            },
            "cheek": {
                "raw_score": 44.11081314086914,
                "ui_score": 65,
                "output_mask_name": "hd_pore_output_cheek.png"
            },
            "whole": {
                "raw_score": 49.23978805541992,
                "ui_score": 67,
                "output_mask_name": "hd_pore_output_all.png"
            }
        },
        "hd_wrinkle": {
            "forehead": {
                "raw_score": 55.96956729888916,
                "ui_score": 67,
                "output_mask_name": "hd_wrinkle_output_forehead.png"
            },
            "glabellar": {
                "raw_score": 76.7251181602478,
                "ui_score": 75,
                "output_mask_name": "hd_wrinkle_output_glabellar.png"
            },
            "crowfeet": {
                "raw_score": 83.4361481666565,
                "ui_score": 78,
                "output_mask_name": "hd_wrinkle_output_crowfeet.png"
            },
            "periocular": {
                "raw_score": 67.88706302642822,
                "ui_score": 72,
                "output_mask_name": "hd_wrinkle_output_periocular.png"
            },
            "nasolabial": {
                "raw_score": 74.03312683105469,
                "ui_score": 74,
                "output_mask_name": "hd_wrinkle_output_nasolabial.png"
            },
            "marionette": {
                "raw_score": 71.94477319717407,
                "ui_score": 73,
                "output_mask_name": "hd_wrinkle_output_marionette.png"
            },
            "whole": {
                "raw_score": 49.64699745178223,
                "ui_score": 65,
                "output_mask_name": "hd_wrinkle_output_all.png"
            }
        },
        "all": {
            "score": 75.75757575757575
        },
        "skin_age": 37
    }
    

  • Sample score_info.json of SD Skincare

    {
        "wrinkle": {
            "raw_score": 36.09360456466675,
            "ui_score": 60,
            "output_mask_name": "wrinkle_output.png"
        },
        "droopy_upper_eyelid": {
            "raw_score": 79.05348539352417,
            "ui_score": 80,
            "output_mask_name": "droopy_upper_eyelid_output.png"
        },
        "droopy_lower_eyelid": {
            "raw_score": 79.97175455093384,
            "ui_score": 81,
            "output_mask_name": "droopy_lower_eyelid_output.png"
        },
        "firmness": {
            "raw_score": 89.66898322105408,
            "ui_score": 85,
            "output_mask_name": "firmness_output.png"
        },
        "acne": {
            "raw_score": 92.29713000000001,
            "ui_score": 88,
            "output_mask_name": "acne_output.png"
        },
        "moisture": {
            "raw_score": 48.694559931755066,
            "ui_score": 70,
            "output_mask_name": "moisture_output.png"
        },
        "eye_bag": {
            "raw_score": 76.67280435562134,
            "ui_score": 79,
            "output_mask_name": "eye_bag_output.png"
        },
        "dark_circle_v2": {
            "raw_score": 80.1993191242218,
            "ui_score": 76,
            "output_mask_name": "dark_circle_v2_output.png"
        },
        "age_spot": {
            "raw_score": 83.23274230957031,
            "ui_score": 77,
            "output_mask_name": "age_spot_output.png"
        },
        "radiance": {
            "raw_score": 76.57244205474854,
            "ui_score": 79,
            "output_mask_name": "radiance_output.png"
        },
        "redness": {
            "raw_score": 72.011962890625,
            "ui_score": 77,
            "output_mask_name": "redness_output.png"
        },
        "oiliness": {
            "raw_score": 60.74365234375,
            "ui_score": 72,
            "output_mask_name": "oiliness_output.png"
        },
        "pore": {
            "raw_score": 88.38014125823975,
            "ui_score": 84,
            "output_mask_name": "pore_output.png"
        },
        "texture": {
            "raw_score": 80.09742498397827,
            "ui_score": 76,
            "output_mask_name": "texture_output.png"
        },
        "all": {
            "score": 75.75757575757575
        },
        "skin_age": 37
    }
    

Supported Formats & Dimensions

AI Feature	Supported Dimensions	Supported File Size	Supported Formats
SD Skincare	long side <= 1920, short side >= 480	< 10MB	jpg/jpeg/png
HD Skincare	long side <= 2560, short side >= 1080	< 10MB	jpg/jpeg/png

Warning: It is your resposibility to resize input images based on the Supported Dimensions of HD or SD Skincare before runing AI Skin Analysis. It is highly recommended to use portrait rather than landscape aspect ratio as input.

Suggestions for How to Shoot:

Get Ready to Start Skin Analysis Instructions

• Take off your glasses and make sure bangs are not covering your forehead
• Make sure that you’re in a well-lit environment
• Remove makeup to get more accurate results
• Look straight into the camera and keep your face in the center

Photo requirement

We will check the image quality to ensure it is suitable for AI Skin Analysis. Please make sure the face occupies approximately 60–80% of the image width, without any overlays or obstructions. The lighting should be bright and evenly distributed, avoiding overexposure or blown-out highlights. The pose should be front-facing, neutral, and relaxed, with the mouth closed and eyes open.

You should fully reveal your forehead and brush your fringe back or tie your hair to ensure the best quality. It is recommended that you remove your spectacles for optimal AI Skin Analysis performance, although this is not mandatory.

Warning: The width of the face needs to be greater than 60% of the width of the image.

Error Codes

Error Code	Description
error_below_min_image_size	Input image resolution is too small
error_exceed_max_image_size	Input image resolution is too large
error_src_face_too_small	The face area in the uploaded image is too small. The width of the face needs to be greater than 60% of the width of the image.
error_src_face_out_of_bound	The face area in the uploaded image is out of bound
error_lighting_dark	The lighting in the uploaded image is too dark

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

---

Overview

The JavaScript Camera Kit provides a complete in-browser camera solution designed for high-accuracy face-based imaging tasks. It includes:

• Camera permission handling
• Real-time face detection
• Automatic face quality validation (lighting, pose, angle, distance)
• Guided capture UI
• Multi-step capture flows for advanced hair/face tasks
• Support for both base64 and blob output formats

The module is particularly optimized for AI-driven image analysis, such as AI Skin Analysis (SD/HD), AI Face Tone Analysis, and hair-related analysis.

---

Download the JS Camera Kit

Include the JS Camera Kit SDK via CDN:

https://plugins-media.makeupar.com/v2.1-camera-kit/sdk.js

Once loaded, the SDK installs a global YMK object.

---

Quick Start Example

The following sample demonstrates:

• Loading the JS Camera Kit SDK
• Implementing window.ymkAsyncInit
• Initializing the module
• Opening the camera
• Receiving 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>
  </head>

  <body>
    <script>
      window.ymkAsyncInit = function() {
        YMK.addEventListener('loaded', function() {
          /* Module fully loaded and ready */
        });

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

          for (const image of capturedResult.images) {
            const img = document.createElement('img');
            img.src = typeof image.image === 'string'
              ? image.image
              : URL.createObjectURL(image.image);

            container.appendChild(img);
          }
        });
      };

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

    <!-- Load SDK -->
    <script>
      window.addEventListener('load', function() {
        (function(d) {
          const s = d.createElement('script');
          s.type = 'text/javascript';
          s.async = true;
          s.src = 'https://plugins-media.makeupar.com/v2.1-camera-kit/sdk.js';
          d.getElementsByTagName('script')[0].parentNode.insertBefore(s, null);
        })(document);
      });
    </script>

    <button onClick="openCameraKit()">Open Camera Kit</button>

    <div id="YMK-module"></div>

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

---

Prerequisites

You must define the asynchronous initialization entry point:

<script>
  window.ymkAsyncInit = function() {
    YMK.init(); // default settings
  };
</script>

Additional requirements:

Requirement	Description
Browser	Must support getUserMedia
HTTPS	Required on most browsers for webcam access
<div id="YMK-module">	Mandatory mount point for the UI

---

Integration Guide

Step 1 — Initialize the Module

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

YMK.init({
  faceDetectionMode: 'skincare',
  imageFormat: 'base64',
  language: 'enu'
});

Supported Detection Modes

Mode	Description
makeup	Standard camera mode for virtual cosmetic try-on
skincare	Standard skin analysis mode, close-up face capture
hdskincare	HD Skin capture using webcams with ≥ 2560px width
shadefinder	Skin Tone Analysis front-face capture
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

---

Step 2 — Add Event Handlers

Event examples:

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

See the full Events List below.

---

Step 3 — Open Camera Kit

YMK.openCameraKit();

This automatically:

• Shows the UI
• Opens webcam
• Begins real-time face quality monitoring
• Automatically captures when conditions are acceptable

---

Step 4 — Receiving Captured Result

Captured images arrive via:

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

---

Step 5 — Close Module

YMK.close();

---

API Reference

---

YMK.init(args)

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

Arguments

args.faceDetectionMode

Detection flow to use.

Values: "skincare" | "hdskincare" | "shadefinder" | "hairlength" | "hairfrizziness" | "hairtype" Default: "skincare"

---

args.width

Pixel width of module container. Default:

• 360 (screens ≥ 500px)
• screen width (screens < 500px)

Allowed: 300–1920

---

args.height

Pixel height of module container. Default:

• 480 (screens ≥ 500px)
• min(screen.height, innerHeight) for smaller screens

Allowed: 300–1920

---

args.language

UI language.

Available: "chs", "cht", "deu", "enu", "esp", "fra", "jpn", "kor", "ptb", "ita" Default: "enu"

---

args.imageFormat

Format returned via faceDetectionCaptured.

"base64" or "blob" Default: "base64"

---

args.disableCameraResolutionCheck

Allow running even if webcam does not meet required resolution.

Default: false

---

Other API Methods

YMK.openCameraKit()

Opens the module and begins detection.

---

YMK.addEventListener(eventName, callback)

Registers event callbacks.

Returns: EventListenerIdentifier

---

YMK.removeEventListener(id)

Removes listener by identifier.

---

YMK.isLoaded()

Returns whether livestream or photo is drawn on canvas.

Returns: boolean

---

YMK.pause()

Pauses the webcam stream.

---

YMK.resume(restartWebcam = false)

Resumes webcam after pause.

---

YMK.getInfo()

Returns current module info:

{
  "fps": 30
}

---

YMK.close()

Closes module and camera.

---

Events Reference

Lifecycle Events

Event	Description
opened	Module opened
loading	Loading progress (0–100)
loaded	Camera stream loaded onto canvas
closed	Module closed

---

Camera Events

Event	Description
cameraOpened	Webcam opened
cameraClosed	Webcam closed
cameraFailed	Permission denied or no webcam Error code: * "error_resolution_unsupported" * "error_permission_denied" * "error_access_failed"

---

faceQualityChanged

Fires continuously during detection.

{
  "hasFace": true,
  "area": "good",
  "frontal": "good",
  "lighting": "ok",
  "nakedeye": "good",
  "faceangle": "good"
}

• Field Descriptions

Field	Values	Meaning
hasFace	true/false	Whether face is detected
area	"good", "notgood", "toosmall", "outofboundary"	Face distance/size quality
frontal	"good", "notgood"	Whether user is facing forward
lighting	"good", "ok", "notgood"	Lighting strength
nakedeye	"good", "notgood"	Eyewear detection
faceangle	"good", "upward", "downward", "leftward", "rightward", "lefttilt", "righttilt"	Face orientation

---

Minimum Recommended Quality

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

---

faceDetectionStarted User enters detection UI.

---

faceDetectionCaptured This event is fired after all required face quality validation checks have passed and the Camera Kit has successfully completed the capture workflow. Depending on the selected faceDetectionMode, the event may contain one or multiple captured images (e.g., multi-angle capture for hair modes).

Callback Arguments capturedResult — Object The result object containing all successfully captured images and metadata.

Field Definitions mode — string Indicates the active faceDetectionMode used for capturing. Possible values include: "skincare" | "hdskincare" | "shadefinder" | "hairlength" | "hairfrizziness" | "hairtype" This value corresponds directly to the configuration set in YMK.init({ faceDetectionMode }).

images — Array A list of one or more captured images. Each entry represents a single capture phase, especially relevant for multi-phase modes (e.g., hair analysis).

ImageObject Structure

Field	Type	Description
phase	integer	The zero-based index representing the capture step. Examples: • Skincare = 0 • Hair frizziness sequence = 0 (front), 1 (right turn), 2 (left turn)
image	string or Blob	The captured image. • Base64 string if args.imageFormat = "base64" • Binary Blob if args.imageFormat = "blob"
width	integer	Pixel width of the captured image.
height	integer	Pixel height of the captured image.

---

Notes

• The number of images varies depending on faceDetectionMode.
  • Example: "hairfrizziness" and "hairtype" typically produce three images.
• Image resolution may differ from device to device. The actual pixel size depends on:
  • The user's webcam maximum resolution
  • The constraints and recommended settings for the selected mode
• All images are guaranteed to meet the minimum face quality requirements before this event is dispatched.

---

Configuration Notes

Quality Requirements

• Ensure correct distance
• Ensure frontal face angle
• Provide sufficient lighting (avoid shadows)

Multi-Phase Capture Modes like hairtype or hairfrizziness require:

1. Front face
2. Turn right
3. Turn left

Ensure event handling is in place.

AI Aging Generator

AI aging generator utilizing generative AI model to generate a series of photos from youth to age from a single selfie image. With the help of AI technology, not only can it measure your current age, but it also lets you see yourself in the future or the past.

The AI aging generator can generate a series of photos based on one single input selfie image. A sample generated photos are shown below as a quick reference of this feature.

AI Face Skin Tone Analysis

The AI Face Skin Tone Analysis detects facial skin tone, eye, eyebrow, lip & hair colors. This inclusive technology ensures to a complete tailored shopping experience for all ethnicities.

How to Take Photos for AI Face Skin Tone Analysis

• Take a selfie facing forward
  • Just one clear shot, looking straight into the camera. Leave your hair down so it falls over your chest, and make sure you're staring directly ahead for that front-on view.
  • Instead, use the JS Camera Kit to take a photo. Just leave your hair down so it falls over your chest. Don't tie it up.

How to Detect Skin Concerns by AI

1. Resize your source image
   Resize your photo to fit the supported dimensions. See details in File Specs & Errors

2. Upload file using the File API
   Using the v1.1/file/face-attr-analysis API to upload a target user image.

   • Image Requirements

     • See details in File Specs & Errors.

   • Important: Simply calling the File API does not upload your file. You must manually upload the file to the URL provided in the File API response. That URL is your upload destination, make sure the file is successfully transferred there before proceeding.
     Before calling the AI API, ensure your file has been successfully uploaded. Use the File API to retrieve an upload URL, then upload your file to that location. Once the upload is complete, you'll receive a file_id in the response, this ID is what you'll use to access AI features related to that file.

     Warning: Please note that, you will get an 500 Server Error / unknown_internal_error or 404 Not Found error when using AI APIs if you do not upload the file to the URL provided in the File API response.

3. Run an AI Face Skin Tone Analysis task
   Once your upload is complete, the AI will use your file ID to examine the color tones of your lips, eyes, eyebrows, skin, and hair. Please refer to the Inputs & Outputs.
   Subsequently, calling POST 'task/face-attr-analysis' with the File ID executes the enhance task and obtains a task_id.

4. Polling to check the status of a task until it succeed or error
   This task_id is used to monitor the task's status through polling GET 'task/face-attr-analysis' to retrieve the current engine status. Until the engine completes the task, the status will remain 'running', and no units will be consumed during this stage.

   Warning: Please note that, Polling to check the status of a task based on it's polling_interval is mandotary. A task will be timed out if there is no polling request within the polling_interval, even if the task is processed succefully(Your unit(s) will be consumed).

   Warning: You will get a InvalidTaskId error once you check the status of a timed out task. So, once you run an AI task, you need to polling to check the status within the polling_interval until the status become either success or error.

5. Get the result of an AI task once success
   The task will change to the 'success' status after the engine successfully processes your input file and generates the resulting image. You will get an url of the processed image and a dst_id that allow you to chain another AI task without re-upload the result image. Your units will only be consumed in this case. If the engine fails to process the task, the task's status will change to 'error' and no unit will be consumed.
   When deducting units, the system will prioritize those nearing expiration. If the expiration date is the same, it will deduct the units obtained on the earliest date.

Real-world examples:

Inputs

The AI will analyze the color tones of your lips, eyes, eyebrows, skin, and hair.

Outputs

{
    "eye_color": "#48515c",
    "eye_color_name": "Gray",   // string; alternatives: ["Amber", "Brown", "Green", "Blue", "Gray", "Other"]
    "lip_color": "#d37982",
    "eyebrow_color": "#a17a63",
    "skin_color": "#b28e73",
    "hair_color": "#000000",
    "hair_color_name": "Black"  // string; alternatives: ["Auburn", "Black", "Blonde", "Brown", "Grey/White", "Red"]
}

Suggestions for How to Shoot:

Warning: The width of the face needs to be greater than 60% of the width of the image.

Supported Formats & Dimensions

AI Feature	Supported Dimensions	Supported File Size	Supported Formats
AI Face Skin Tone Analysis	long side <= 4096, single person only. Images with a side longer than 1080px are automatically resized for analysis.	< 10MB	jpg/jpeg

Error Codes

Error Code	Description
error_below_min_image_size	Source image dimensions must be at least 100×100 pixels.
error_face_position_invalid	Face must be fully visible, forward-facing, and centered in the image.
error_face_position_too_small	Detected face is too small for analysis.
error_face_position_out_of_boundary	Face extends beyond image boundaries.
error_face_not_forward_facing	Face must be directly facing the camera.
error_face_angle_upward	Face is angled too far upward—slightly tilt head down.
error_face_angle_downward	Face is angled too far downward — slightly tilt head up.
error_face_angle_leftward	Face is turned too far left — slightly rotate head right.
error_face_angle_rightward	Face is turned too far right — slightly rotate head left.
error_face_angle_left_tilt	Face is tilted too far left — gently tilt head right.
error_face_angle_right_tilt	Face is tilted too far right — gently tilt head left.

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

---

Overview

The JavaScript Camera Kit provides a complete in-browser camera solution designed for high-accuracy face-based imaging tasks. It includes:

• Camera permission handling
• Real-time face detection
• Automatic face quality validation (lighting, pose, angle, distance)
• Guided capture UI
• Multi-step capture flows for advanced hair/face tasks
• Support for both base64 and blob output formats

The module is particularly optimized for AI-driven image analysis, such as AI Skin Analysis (SD/HD), AI Face Tone Analysis, and hair-related analysis.

---

Download the JS Camera Kit

Include the JS Camera Kit SDK via CDN:

https://plugins-media.makeupar.com/v2.1-camera-kit/sdk.js

Once loaded, the SDK installs a global YMK object.

---

Quick Start Example

The following sample demonstrates:

• Loading the JS Camera Kit SDK
• Implementing window.ymkAsyncInit
• Initializing the module
• Opening the camera
• Receiving 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>
  </head>

  <body>
    <script>
      window.ymkAsyncInit = function() {
        YMK.addEventListener('loaded', function() {
          /* Module fully loaded and ready */
        });

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

          for (const image of capturedResult.images) {
            const img = document.createElement('img');
            img.src = typeof image.image === 'string'
              ? image.image
              : URL.createObjectURL(image.image);

            container.appendChild(img);
          }
        });
      };

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

    <!-- Load SDK -->
    <script>
      window.addEventListener('load', function() {
        (function(d) {
          const s = d.createElement('script');
          s.type = 'text/javascript';
          s.async = true;
          s.src = 'https://plugins-media.makeupar.com/v2.1-camera-kit/sdk.js';
          d.getElementsByTagName('script')[0].parentNode.insertBefore(s, null);
        })(document);
      });
    </script>

    <button onClick="openCameraKit()">Open Camera Kit</button>

    <div id="YMK-module"></div>

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

---

Prerequisites

You must define the asynchronous initialization entry point:

<script>
  window.ymkAsyncInit = function() {
    YMK.init(); // default settings
  };
</script>

Additional requirements:

Requirement	Description
Browser	Must support getUserMedia
HTTPS	Required on most browsers for webcam access
<div id="YMK-module">	Mandatory mount point for the UI

---

Integration Guide

Step 1 — Initialize the Module

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

YMK.init({
  faceDetectionMode: 'skincare',
  imageFormat: 'base64',
  language: 'enu'
});

Supported Detection Modes

Mode	Description
makeup	Standard camera mode for virtual cosmetic try-on
skincare	Standard skin analysis mode, close-up face capture
hdskincare	HD Skin capture using webcams with ≥ 2560px width
shadefinder	Skin Tone Analysis front-face capture
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

---

Step 2 — Add Event Handlers

Event examples:

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

See the full Events List below.

---

Step 3 — Open Camera Kit

YMK.openCameraKit();

This automatically:

• Shows the UI
• Opens webcam
• Begins real-time face quality monitoring
• Automatically captures when conditions are acceptable

---

Step 4 — Receiving Captured Result

Captured images arrive via:

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

---

Step 5 — Close Module

YMK.close();

---

API Reference

---

YMK.init(args)

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

Arguments

args.faceDetectionMode

Detection flow to use.

Values: "skincare" | "hdskincare" | "shadefinder" | "hairlength" | "hairfrizziness" | "hairtype" Default: "skincare"

---

args.width

Pixel width of module container. Default:

• 360 (screens ≥ 500px)
• screen width (screens < 500px)

Allowed: 300–1920

---

args.height

Pixel height of module container. Default:

• 480 (screens ≥ 500px)
• min(screen.height, innerHeight) for smaller screens

Allowed: 300–1920

---

args.language

UI language.

Available: "chs", "cht", "deu", "enu", "esp", "fra", "jpn", "kor", "ptb", "ita" Default: "enu"

---

args.imageFormat

Format returned via faceDetectionCaptured.

"base64" or "blob" Default: "base64"

---

args.disableCameraResolutionCheck

Allow running even if webcam does not meet required resolution.

Default: false

---

Other API Methods

YMK.openCameraKit()

Opens the module and begins detection.

---

YMK.addEventListener(eventName, callback)

Registers event callbacks.

Returns: EventListenerIdentifier

---

YMK.removeEventListener(id)

Removes listener by identifier.

---

YMK.isLoaded()

Returns whether livestream or photo is drawn on canvas.

Returns: boolean

---

YMK.pause()

Pauses the webcam stream.

---

YMK.resume(restartWebcam = false)

Resumes webcam after pause.

---

YMK.getInfo()

Returns current module info:

{
  "fps": 30
}

---

YMK.close()

Closes module and camera.

---

Events Reference

Lifecycle Events

Event	Description
opened	Module opened
loading	Loading progress (0–100)
loaded	Camera stream loaded onto canvas
closed	Module closed

---

Camera Events

Event	Description
cameraOpened	Webcam opened
cameraClosed	Webcam closed
cameraFailed	Permission denied or no webcam Error code: * "error_resolution_unsupported" * "error_permission_denied" * "error_access_failed"

---

faceQualityChanged

Fires continuously during detection.

{
  "hasFace": true,
  "area": "good",
  "frontal": "good",
  "lighting": "ok",
  "nakedeye": "good",
  "faceangle": "good"
}

• Field Descriptions

Field	Values	Meaning
hasFace	true/false	Whether face is detected
area	"good", "notgood", "toosmall", "outofboundary"	Face distance/size quality
frontal	"good", "notgood"	Whether user is facing forward
lighting	"good", "ok", "notgood"	Lighting strength
nakedeye	"good", "notgood"	Eyewear detection
faceangle	"good", "upward", "downward", "leftward", "rightward", "lefttilt", "righttilt"	Face orientation

---

Minimum Recommended Quality

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

---

faceDetectionStarted User enters detection UI.

---

faceDetectionCaptured This event is fired after all required face quality validation checks have passed and the Camera Kit has successfully completed the capture workflow. Depending on the selected faceDetectionMode, the event may contain one or multiple captured images (e.g., multi-angle capture for hair modes).

Callback Arguments capturedResult — Object The result object containing all successfully captured images and metadata.

Field Definitions mode — string Indicates the active faceDetectionMode used for capturing. Possible values include: "skincare" | "hdskincare" | "shadefinder" | "hairlength" | "hairfrizziness" | "hairtype" This value corresponds directly to the configuration set in YMK.init({ faceDetectionMode }).

images — Array A list of one or more captured images. Each entry represents a single capture phase, especially relevant for multi-phase modes (e.g., hair analysis).

ImageObject Structure

Field	Type	Description
phase	integer	The zero-based index representing the capture step. Examples: • Skincare = 0 • Hair frizziness sequence = 0 (front), 1 (right turn), 2 (left turn)
image	string or Blob	The captured image. • Base64 string if args.imageFormat = "base64" • Binary Blob if args.imageFormat = "blob"
width	integer	Pixel width of the captured image.
height	integer	Pixel height of the captured image.

---

Notes

• The number of images varies depending on faceDetectionMode.
  • Example: "hairfrizziness" and "hairtype" typically produce three images.
• Image resolution may differ from device to device. The actual pixel size depends on:
  • The user's webcam maximum resolution
  • The constraints and recommended settings for the selected mode
• All images are guaranteed to meet the minimum face quality requirements before this event is dispatched.

---

Configuration Notes

Quality Requirements

• Ensure correct distance
• Ensure frontal face angle
• Provide sufficient lighting (avoid shadows)

Multi-Phase Capture Modes like hairtype or hairfrizziness require:

1. Front face
2. Turn right
3. Turn left

Ensure event handling is in place.