YouCam Online Editor AI APIs (v1.2_55766b1)

Last modified: Aug. 4, 2025 55766b1

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.

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 30 days before they're automatically removed.

Warning: Even though those result files are still good for 30 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	Input file size exceeds the maximum limit
invalid_parameter	Invalid parameter value
error_download_image	Download source image error
error_download_mask	Download mask image error
error_decode_image	Decode source image error
error_decode_mask	Decode mask image error
error_download_video	Download source video error
error_decode_video	Decode source video error
error_nsfw_content_detected	NSFW content detected in source image
error_no_face	No face detected on source image
error_pose	Failed to detect pose on source image
error_face_parsing	Failed to do face segmentation on source image
error_inference	Inference pipeline error
exceed_nsfw_retry_limits	Exceed the retry limits to avoid generated NSFW image
error_upload	Upload result image error
error_multiple_people	Multiple people 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	Input hair is too short
error_unexpected_video_duration	Video durateion is not equal to the dstDuration
error_bald_image	Input hairstyle is bald
error_unsupport_ratio	The aspect ratio of input image is unsupported
unknown_internal_error	Others

---

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/account/apikey. 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.

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

1. Go to https://yce.perfectcorp.com/account/apikey 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.

---

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.

---

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.

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.

Authentication with Perfect API server.

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.

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.

The AI Skin Analysis API is easy to use.

• First, 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.
• Next, call the upload file API to get a URL for uploading the photo and a file ID for reference.
• Once the upload is complete, you can select 4, 7, or 14 skin concerns to analyze using your file ID.
• Finally, poll for the task status until it succeeds, then download the result zip file, which contains the skin analysis data to present to your users.

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"
  }
  

---

Use cases:

Suggestions for How to Shoot:

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

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

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.

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

Want to perform AI skin analysis in a browser? This camera kit lets you open your browser’s camera, snap a photo, and you are ready to run an AI skin analysis API task. But if you’d rather create your own version, you’re free to do so! It’s just a JavaScript demo for reference and isn’t mandatory for using the AI Skin Analysis API.

Download the YMK JS Camera Module

https://plugins-media.makeupar.com/v1.0-skincare-camera-kit/sdk.js

YMK JS Camera Module API Documentation

Introduction

This document outlines the JavaScript camera module designed to capture high-quality images for integration into an AI Skin Analysis workflow. The API supports both UI Mode (with built-in camera controls and face quality indicators) and Headless Mode (API-driven without visual components), enabling flexible use cases in web applications.

---

Quick Start Guide

The YMK JS Camera Module API provides robust tools for capturing and validating images tailored for AI analysis workflows. Use UI Mode for user-facing applications and Headless Mode for server-side integration or custom implementations. Always prioritize face quality checks before triggering captures to ensure accurate results.

Prerequisites

• A webpage with a <script> tag to declare window.ymkAsyncInit.
• Basic understanding of JavaScript event handling.

Declare the Async Initialization Function

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

UI Mode Integration

Use this mode for applications requiring a camera preview and automatic face quality checks via predefined UI elements.

Steps:

1. Initialize the module (defaults to UI Mode):

   YMK.init({
     width: 360,
     height: 480,
     language: "enu"
   });
   

2. Registering Event Handlers See Event Handling
3. Open Camera with face quality monitoring:

   YMK.openSkincareCamera(); // Shows built-in UI with camera and overlays
   

4. Capture Photo automatically when minimum requirements are met, or manually via the UI.
5. Close Module:

   YMK.close();
   

Headless Mode Integration

Ideal for applications needing minimal overhead (e.g., backend integration) or custom UI implementation.

Steps:

1. Set Input Source (optional):

   YMK.setCanvasInput("base64", "data:image/png;base64...", canvasElement);
   

2. Initialize in Headless Mode:

   YMK.init({
     moduleMode: "headless",
     width: 640,
     height: 480,
     snapshotType: "base64"
   });
   

3. Registering Event Handlers See Event Handling
4. Open Specific Module:

   YMK.openSkincareCamera();
   

5. Capture A Photo:(to be used for AI Skin Analysis task)

   YMK.capture();
   

6. Close Module:

   YMK.close();
   

---

API Reference

Method	Description	Availability
YMK.init(args)	Initializes the camera module	UI/Headless
YMK.setCanvasInput(type, source, input) Set input for headless mode. When using base64 or file: - Supported image formats: PNG, JPEG - Supported video format: MP4 Recommended input size: Below 1080p for stability"	* Fields of arguments * - type: string; alternatives: ["image", "video"]. - source (required): string; alternatives: ["base64", "file", "canvas", "mediaStreamTrack"]. - input (required): base64-string / File / HTMLCanvasElement / MediaStreamTrack	Headless Mode only
YMK.capture()	Captures a frame from the live stream	Headless Mode only
YMK.getResultCanvas()	Retrieves an HTMLCanvasElement sized to args.width and args.height from YMK.init	Headless Mode only
YMK.flipCamera()	Flip the camera if your device supports it	Headless Mode only

---

Initialization (YMK.init(args))

Parameters:

{
  width: <integer>, // Defaults to responsive based on screen size
  height: <integer>, // Defaults to window.screen.height * 0.8 for smaller screens
  moduleMode: "ui" or "headless", // Default is UI Mode (no explicit headless option in v1.x)
  snapshotType: "base64" or "blob", // Default is "base64" for skinAnalysisDetectionCaptured event
  language: ["chs", "cht", "deu", "enu", "esp", "fra", "jpn", "kor", "ptb", "ita"] // Defaults to "enu"
}

Core Methods

/**
 * Starts or resumes the live stream.
 * Resumes the live stream if it was previously paused. This function works only in live mode.
 * Options:
 * - restartWebcam (boolean) – Defaults to false. Set to true to force the webcam to restart when resuming the stream.
 */
YMK.resume(false);

/**
 * Pauses the camera preview (useful for background tasks).
 */
YMK.pause();

/**
 * Closes the module entirely (stops camera and releases resources).
 */
YMK.close();


/**
 * See whether the live stream or photo made it onto the canvas.
 */
YMK.isLoaded();


/**
 * Captures a frame by pausing the live stream and triggering the skinAnalysisDetectionCaptured event to retrieve the snapshot image.
 * For best results, call YMK.capture only when face quality is sufficient—meaning "area", "frontal", and "lighting" are all reported as "good" or "ok" via the faceQualityChanged event.
 * Alternatively, you can trigger it right after receiving the skinAnalysisDetectionCompleted event.
 * Note: Capturing with poor image quality may lead to inaccurate analysis.
 */
YMK.capture();

/**
 * Retrieves the current FPS (frames per second).
 * Returns:
 * A JavaScript object containing the latest module info at the time the API is called.
 *     • fps (number) – The current frame rate. Defaults to 0 if the engine hasn’t loaded yet.
 * 
 */
YMK.getInfo();

---

Event Handling

// Add listener example:
const faceQualityListener = YMK.addEventListener("faceQualityChanged", handleFaceQuality);

function handleFaceQuality(quality) {
  console.log("Face Quality:", quality);
}

// Remove listener example:
YMK.removeEventListener(faceQualityListener); // *Note: Headless Mode uses custom event handlers*

Events

Common Events

Event Name	Triggered When	Arguments
opened	Module UI is fully rendered	None
loading(progress: number)	During module initialization	Progress (0-100%)
loaded	Triggered when a live stream or photo is loaded onto the canvas.	None
closed	YMK module closed	None
cameraOpened	Camera hardware successfully starts	None
cameraClosed	Camera closed	None
cameraFailed	Accessing camera fails due to permission denial or device error	None

Face Quality Monitoring (faceQualityChanged)

UI Mode Only:

YMK.addEventListener("faceQualityChanged", function(quality) {
  // Check minimum criteria for analysis:
  if (quality.hasFace && quality.area === "good" && quality.lighting >= "ok") {
    console.log("Proceed with Analysis");
  }
});

Headless Mode Example:

YMK.addEventListener("faceQualityChanged", function(quality) {
  // Handle specific property checks:
  if (!quality.hasFace) alert("No face detected! Keep your face inside the circle.");
  else if (quality.area === "outofboundary") {
    console.log("Warning:", quality.areaMessages[0]); // "Your face is too close..."
  }
});

Module-Specific Events

Event Name	Description	Availability
faceQualityChanged(quality: object)	Real-time face quality updates	UI/Headless
skinAnalysisDetectionStarted	UI Mode only – Enters face quality detection page	UI Mode only
skinAnalysisDetectionCaptured	In UI mode, this is triggered once a face is qualified and captured. In headless mode, it's triggered right after capturing with YMK.capture Args: [image] image: the snapshot image in base64 format or binary format (according to args.snapshotType)	UI/Headless
unsupportedResolution	Triggered when the YMK module receives an unexpected width or height	UI Mode only

faceQualityChanged Arguments: [quality] quality: JS Object

• hasFace: true, false (boolean): Determines if a face is detected. Analysis proceeds only when the value is true.
• area: "good", "notgood", "toosmall", "outofboundary" (string): Assesses whether the user's face is positioned at an appropriate distance. Possible values:
  • "good" – Distance is optimal; analysis can proceed.
  • "notgood", "toosmall", "outofboundary" – Distance requires adjustment.
• frontal: "good", "notgood" (string): Indicates whether the user's face is sufficiently forward-facing.
  • "good" – Alignment is correct; analysis can proceed.
  • "notgood" – Face needs to be repositioned.
• lighting: "good", "ok", "notgood" (string): Evaluates whether lighting conditions are sufficient.
  • "good", "ok" – Lighting is acceptable; analysis can proceed.
  • "notgood" – Additional lighting may be required.
• nakedeye: "good", "notgood" (string): Confirms if the user is not wearing eyewear. Applicable only during eyewear auto PD detection.
  • "good" – No eyewear detected; PD analysis can proceed.
  • "notgood" – Eyewear removal may be necessary.
• faceangle "good", "upward", "downward", "leftward", "rightward", "lefttilt", "righttilt" (string): Measures whether the face angle is within acceptable limits. Applicable only during face analyzer detection.
  • "good" – Face orientation is correct; analysis can proceed.
  • "upward", "downward" – Indicates pitch angle adjustments may be needed.
  • "leftward", "rightward" – Reflects yaw angle deviations.
  • "lefttilt", "righttilt" – Represents roll angle changes (detected only when facial ratio analysis is enabled).

---

Configuration Notes

• Quality Criteria:
  • For skin analysis: { hasFace: true, area: "good", lighting: "ok" }.
• Image Quality Warnings: Always validate face quality before capturing. Use the following minimum thresholds:

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

• Progressive Mode:
  • UI Mode automatically handles quality checks via visual overlays.
  • Headless Mode requires manual validation (e.g., YMK.capture should only be called when faceQuality is acceptable).

---

Troubleshooting

Camera Access Issues

If you encounter an error during camera access, check the following:

1. Ensure HTTPS or localhost for secure contexts (browser security restrictions).
2. Request camera permissions explicitly if required by your environment.
3. Handle cameraFailed event to debug permission denial errors.

Example Error Handling:

YMK.addEventListener("cameraFailed", function() {
  alert("Camera access denied. Please allow permissions or use a different browser/device.");
});

---

AI Face Analyzer

The AI Face Analyzer examines face structure, identifying features like face, eye, eyebrow, lip, nose, cheekbone shapes, designed to provide personalized recommendations.

Use cases:

Face Attributes:

• FACE
  • Face Shape
    • Round
    • Oval
    • Square
    • Oblong
    • Heart
    • Diamond
• EYES
  • Eye Shape
    • Round
    • Almond
    • Narrow
  • Eye Size
    • Big
    • Small
    • Average
  • Eye Angle
    • Upturned
    • Downturned
    • Average
  • Eye Distance
    • Wide-set
    • Close-set
    • Average
  • Eyelid
    • Double-lid
    • Single-lid
    • Hooded-lid
    • Deep-set eyelid
• BROWS
  • Eyebrow Shape
    • Hard Angled
    • Soft Angled
    • Rounded
    • Straight
  • Thickness
    • Sparse
    • Average
    • Dense
  • Eyebrow Distance
    • Far-Apart
    • Close
    • Average
  • Thinness
    • Sparse
    • Average
    • Dense
  • Shortness
    • Short
    • Average
• LIPS
  • Lip Shape
    • Round
    • Bow-shape
    • Downturned
    • Average
• NOSE
  • Nose Width
    • Broad
    • Narrow
    • Average
  • Nose Length
    • Long
    • Short
    • Average
• CHEEKBONES
  • cheekbones
    • Flat
    • High
    • Low
    • Round

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 Analyzer	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.

AI Hair Color

Explore a wide range of hair colors with our hair color changer! Try the hair color you've always dreamed of and experiment with new shades you’ve never tried before. Easily adjust the intensity of your chosen color with sliders for a customized look.

Upload Your Image

Upload the photo you want to change hair color for.

Choose Preset Colors or Customize by Pattern and Palettes

Choose from predefined color presets or fine tune by adjusting the ombre coverage and blend for unlimited possibilities!

Warning: If both a preset and pattern + palettes are specified, the preset will take priority.

Warning: Your source image needs to contain the hair section for dyeing, so double-check before applying. Make sure your source image includes the hair area you want to dye — it's your responsibility to get it right.

Supported Formats & Dimensions

AI Feature	Supported Dimensions	Supported File Size	Supported Formats
AI Hair Color	long side < 1920, face width >= 100	< 10MB	jpg/jpeg/png

Error Codes

Error Code	Description
error_below_min_image_size	the size of the source image is smaller than minimum (expect: width >= 100px, height >= 100px)
error_exceed_max_image_size	the size of the source image is larger than maximum (expect: width < 1920px, height < 1080px)

AI Hairstyle Generator

Using the latest AI technology to try a wide variety of hairstyles, catering to both women and men, meeting different gender and style preference. Discover a world of styles: curly, long, buzz cut, and more. Our AI-powered hair changer lets you experiment effortlessly. Find your ideal hairstyle now!

Want to see more Hair styles? Please refer to https://yce.perfectcorp.com/ai-hairstyle-generator.

Use case:

Suggestions for How to Shoot:

Supported Formats & Dimensions

AI Feature	Supported Dimensions	Supported File Size	Supported Formats
AI Hairstyle Generator	long side <= 1024, face width >= 128, face pose: -10 < pitch < +10, -45 < yaw < +45, -15 < roll < +15, single face only, need to show full face	< 10MB	jpg/jpeg

Error Codes

Error Code	Description
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_insufficient_landmarks	Cannot detect sufficient face or body landmarks in the source image
error_hair_too_short	Input hair is too short
error_face_pose	The face pose of source image is unsupported

Q: Can I try on a custom hairstyle?

A: It's a cool idea, but we're not able to support custom hairstyles right now. Right now, those custom hairdos need heavy optimization to look natural. But if you still want to personalize something, feel free to reach out to our customer success team at YouCamOnlineEditor_API@perfectcorp.com. Let us know what kind of hairstyles you're thinking of, feel free to send sample pics and tell us who you're trying to reach and how big your market is. Let's build something cool together.