# YouCam API Documentation | Perfect Corp. > YouCam API documentation by Perfect Corp. Learn how to use Skin analysis API, Virtual try-on API, Image editing API, and Video generative AI APIs. ## Table of contents - [API Server](https://docs.perfectcorp.com/develop/api_server.md) - [Debugging Guide](https://docs.perfectcorp.com/develop/debugging_guide.md) - [Error Codes](https://docs.perfectcorp.com/develop/error_codes.md) - [File Retention Period](https://docs.perfectcorp.com/develop/file_retention_period.md) - [Rate Limit](https://docs.perfectcorp.com/develop/rate_limit.md) - [YouCam Skills](https://docs.perfectcorp.com/develop/agent_skills.md) - [API Playground](https://docs.perfectcorp.com/develop/api_playground.md) - [FAQ](https://docs.perfectcorp.com/develop/faq.md) - [Quick Start Guide](https://docs.perfectcorp.com/develop/quick_start_guide.md) - [Webhook](https://docs.perfectcorp.com/develop/webhook.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_2d_vto_bracelet.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_2d_vto_earring.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_2d_vto_necklace.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_2d_vto_ring.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_2d_vto_watch.md) - [MCP](https://docs.perfectcorp.com/develop/mcp.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_abs_filter.md) - [Release Notes](https://docs.perfectcorp.com/release/changelog.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_aging.md) - [YouCam API Documentation | Perfect Corp.](https://docs.perfectcorp.com/develop/introduction.md): YouCam API documentation by Perfect Corp. Learn how to use Skin analysis API, Virtual try-on API, Image editing API, and Video generative AI APIs. - [Overview](https://docs.perfectcorp.com/reference/description/ai_avatar_generator.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_bag.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_beard_style.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_clothes.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_color_correction.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_eye_color_lens.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_fabric.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_face_analyzer.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_face_lift.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_face_swap.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_face_tone_analyzer.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_fitzpatrick_skin_type.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_frizziness_detection.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_hair_density_detection.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_hair_length.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_hair_type.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_hat.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_headshot_generator.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_image_to_video.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_look_vto.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_makeup_transfer.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_nail_transfer.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_makeup_vto.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_object_removal_pro.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_photo_background_blur.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_photo_background_change.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_replace.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_scarf.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_shoes.md) - [overview](https://docs.perfectcorp.com/reference/description/ai_smile.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_studio_generator.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_skin_analysis.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_teeth_whitening.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_video_enhance.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_video_background_replace.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_video_face_swap.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_video_object_removal.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_video_style_transfer.md) - [Overview](https://docs.perfectcorp.com/reference/description/body_reshape_task.md) - [Overview](https://docs.perfectcorp.com/reference/description/breast_shape_task.md) - [Overview](https://docs.perfectcorp.com/reference/description/colorize_task.md) - [Overview](https://docs.perfectcorp.com/reference/description/enhance_task.md) - [Overview](https://docs.perfectcorp.com/reference/description/face_reshape_task.md) - [Overview](https://docs.perfectcorp.com/reference/description/hair_bang_task.md) - [Overview](https://docs.perfectcorp.com/reference/description/hair_color_task.md) - [Overview](https://docs.perfectcorp.com/reference/description/hair_curl_task.md) - [Overview](https://docs.perfectcorp.com/reference/description/hair_ext_task.md) - [Overview](https://docs.perfectcorp.com/reference/description/hair_style_task.md) - [Overview](https://docs.perfectcorp.com/reference/description/hair_vol_task.md) - [Overview](https://docs.perfectcorp.com/reference/description/image_extender.md) - [Overview](https://docs.perfectcorp.com/reference/description/lighting_task.md) - [Overview of MCP](https://docs.perfectcorp.com/reference/description/mcp.md) - [Overview](https://docs.perfectcorp.com/reference/description/obj_removal_task.md) - [Overview](https://docs.perfectcorp.com/reference/description/nail_vto_task.md) - [polling_guide.md](https://docs.perfectcorp.com/reference/description/polling_guide.md) - [pre_process_guide.md](https://docs.perfectcorp.com/reference/description/pre_process_guide.md) - [pre_process_index.md](https://docs.perfectcorp.com/reference/description/pre_process_index.md) - [Overview](https://docs.perfectcorp.com/reference/description/skin_simulation_task.md) - [Overview](https://docs.perfectcorp.com/reference/description/sod_task.md) - [Overview](https://docs.perfectcorp.com/reference/description/text_to_image.md) - [Webhook](https://docs.perfectcorp.com/reference/description/webhook.md) - [AI Abs Filter](https://docs.perfectcorp.com/reference/ai_abs_filter.md): # Overview The **AI Abs Filter API** lets you add realistic abdominal definition to a photo and generate an athletic body-shaping result with minimal effort. Upload a full-body or upper-body image, select the desired enhancement mode, set the intensity level, and receive an edited output image. ![](https://plugins-media.makeupar.com/smb/blog/post/2024-09-27/daf70f5e-a350-46a3-8b6c-f63bd60c6cf0.jpg) Supported modes: - `Six-pack`: Adds visible six-pack abs for a more muscular torso appearance. - `Vest-line`: Enhances central abdominal muscle definition for a fit, athletic look. --- ## Integration Guide **Input Requirements & Processing Criteria:** - Upload a full-body or upper-body image. - Select an enhancement mode: `Six-pack` or `Vest-line`. - Choose the desired abdominal enhancement intensity level. - Maximum long-side image resolution must not exceed **4096 px**. - Source file size must be less than **10 MB**. - At least one detectable person is required, with both shoulders visible. - The abdomen must be visible, either clothed or unclothed. - Supported pose range: `−45° < yaw < 45°`. - Single-person processing is supported. If multiple people appear in the image, the API automatically selects the person with the largest visible shoulder area. **Workflow:** 1. Upload file metadata using the File API. 2. Retrieve the signed upload URL from the response. 3. Upload the actual image to the returned URL. 4. Create an AI task for abs-shape enhancement. 5. Setup a Webhook or Poll the task status until completion. 6. Download the generated result image when processing is successful. --- **Step 1 — Upload File Metadata Using the File API** Use `POST /s2s/v2.0/file` to create a file record and receive upload details for the source image. ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/file \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "files": [ { "content_type": "image/jpg", "file_name": "full_body_photo_01_3dbd1b6683.jpg", "file_size": 547541 } ] }' ``` **File API Sample Response:** ```json { "status": 200, "data": { "files": [ { "content_type": "image/jpg", "file_name": "full_body_photo_01_3dbd1b6683.jpg", "file_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud", "requests": [ { "method": "PUT", "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...", "headers": { "Content-Length": "547541", "Content-Type": "image/jpg" } } ] } ] } } ``` --- **Step 2 — Retrieve File API Response Details** The response contains: | Field | Description | | --- | --- | | `file_id` | Identifier used to create the AI task. | | `requests.url` | Signed URL for uploading the actual image file. | | `requests.method` | Upload method, usually `PUT`. | | `requests.headers` | Required headers for the upload request. | --- **Step 3 — Upload Image to Provided URL** Use the `requests.url` from the File API response to upload the source image. ```bash curl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \ --header 'Content-Type: image/jpg' \ --header 'Content-Length: 547541' \ --data-binary @'./full_body_photo_01_3dbd1b6683.jpg' ``` --- **Step 4 — Create an AI Task** Use `POST /s2s/v2.0/task/abs-shape` to create the abs-enhancement task. | Parameter | Description | Example | | --- | --- | --- | | `src_file_id` | File ID returned from the File API upload flow. Required when using uploaded-file workflow. | `"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud"` | | `src_file_url` | Direct URL of the source image. Use this alternative to `src_file_id`. | `"https://example.com/selfie.jpg"` | | `mode` | Enhancement mode. Supported values are `Six-pack` and `Vest-line`. | `"Six-pack"` | | `intensity` | Abdominal enhancement intensity level. | `1` | **Example Request:** ```javascript const resp = await fetch( 'https://yce-api-01.makeupar.com/s2s/v2.0/task/abs-shape', { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' }, body: JSON.stringify({ src_file_url: 'https://example.com/selfie.jpg', mode: 'Six-pack', intensity: 1 }) } ); const data = await resp.json(); console.log(data); ``` **AI Task API Response:** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` --- **Step 5 — Setup a Webhook or Poll for Task Result** See the [webhook integration guide](/develop/webhook.md) for setup and verification details. For polling, use the returned `task_id` to check task status. ```bash curl --request GET \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/abs-shape/ \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' ``` --- **Step 6 — Retrieve Result Image** When processing is successful, the response includes a download URL in `data.results.url`. ```json { "status": 200, "data": { "error": null, "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..." }, "task_status": "success" } } ``` **Invalid API Key Response:** If the access token is invalid, the API returns a `401` response. ```json { "status": 401, "error": "Unauthorized", "error_code": "InvalidAccessToken" } ``` Use cases: ![](https://plugins-media.makeupar.com/smb/blog/post/2025-08-21/307f87b4-d31c-481c-86f1-478c93265a95.jpg) ![](https://plugins-media.makeupar.com/smb/blog/post/2025-08-21/8ab8eca4-b825-4692-aef0-6ffd6176e272.jpg) --- ## File Specs & Errors **File Specifications:** | Specification | Requirement | | --- | --- | | Image type | Full-body or upper-body image. | | Source subject | One detectable person with both shoulders visible and abdomen visible. | | Pose requirement | Supported pose range is `−45° < yaw < 45°`. | | Multi-person handling | If multiple people are detected, the API automatically selects the person with the largest visible shoulder area. | | Maximum long-side resolution | Long side must not exceed **4096 px**. | | File size limit | Must be less than **10 MB**. | | Supported formats | `jpg`, `png`. | **Error Codes:** | Error Code | Description | | --- | --- | | `exceed_max_filesize` | The source image exceeds the maximum allowed dimensions or file size. The long side must not exceed 4096 px, and the file size must remain below 10 MB. | | `error_pose` | Pose detection failed due to missing person detection, shoulder visibility issues, abdomen visibility issues, waist-region detection failure, hip-keypoint detection failure, or unsupported pose range. | | `error_nsfw_content_detected` | Potential NSFW content was detected in the source image or generated result image. | | `invalid_parameter` | Invalid parameters were provided for source keys, destination keys, actions, mode values, intensity levels, or task configuration. | | `error_download_image` | The source image could not be downloaded successfully. | | `error_decode_image` | The source image could not be decoded successfully. | **Environment & Dependencies:** | Tool / Language | Recommended Runtime Versions | | --- | --- | | cURL | Bash ≥ 3.2; curl ≥ 7.58 with modern TLS/HTTP support; jq ≥ 1.6 for robust JSON parsing. | | Node.js | Node ≥ 18 for global `fetch` support. | | JavaScript Browser Support | Chrome / Edge ≥ 80, Firefox ≥ 74, Safari ≥ 13.1. | | PHP | PHP ≥ 7.4 with modern TLS compatibility; ext-curl recommended or `allow_url_fopen=On` with OpenSSL and JSON support. | | Python | Python ≥ 3.10 for f-strings; requests ≥ 2.20.0. | | Java | Java 11+ for HttpClient; Jackson Databind ≥ 2.12.0. | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Abs Filter V1.0 | 1 | --- - [AI Aging Simulation](https://docs.perfectcorp.com/reference/ai_aging_simulation.md): # Overview 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. ![AI Aging Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/f42f1504_79e3_461c_a3f1_a254623d113b_b068736afb.jpg "AI Aging Generator") 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 Aging Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/U_2024_04_17_cr_12112b83e2.png "AI Aging Generator") ## File Specs & Errors * Supported Formats & Dimensions | AI Feature | Supported Dimensions | Supported File Size | Supported Formats | | ---- | ---- | ---- | ---- | | AI Aging | long side <= 4096, single person only. Face pose constraints: yaw within ±30°, roll within ±20°, and pitch within ±20°. | < 10MB | jpg/jpeg | * Error Codes |Error Code|Description| | ---- | ---- | | error_below_min_image_size | Source image dimensions must be at least 320 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. | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Aging Simulation V1.0 | 2 | --- - [AI Avatar Generator](https://docs.perfectcorp.com/reference/ai_avatar_generator.md): # Overview For the AI magic avatar tool, this app uses the technology of image-to-image. which means the avatar is generated based on your photo. Once the photos are selected by the users, the technology embedded in the app starts analyzing and learning the user's facial traits. For more avatar styles, please refer to https://yce.makeupar.com/avatar Use cases: ![AI Avatar Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Christmas_Avatar_b861c35edf.jpg "AI Avatar Generator") ![AI Avatar Generator](https://plugins-media.makeupar.com/smb/blog/post/2023-04-06/fc2c3b2e-2b7f-48c9-96c1-cdb780f9dc1d.jpg "AI Avatar Generator") Suggestions for How to Shoot: ![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png "Suggestions for How to Shoot") --- ## File Specs & Errors * Supported Formats & Dimensions | AI Feature | Supported Dimensions | Supported File Size | Supported Formats | | ---- | ---- | ---- | ---- | | AI Avatar Generator | Input: long side <= 4096, Output: long side <= 1024 | < 10MB | jpg/jpeg/png | * Error Codes |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_decode_image | Decode source image error | | error_nsfw_content_detected | NSFW content detected in source image | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Avatar Generator V3.0 | 1 unit for 4 images * | > *If the number of images or video duration isn’t evenly divisible, units round up. --- - [AI Photo Background Removal](https://docs.perfectcorp.com/reference/ai_background_removal.md): # Overview Remove background from photo with impeccable accuracy, ensuring the high quality of images. * Automatic Background Detection: : Uses AI to identify and separate the subject from the background. * High Precision Editing: : Provides clean and precise edges around the subject. * Supports various categories: People, Products, Animals, Cars, Graphics & more. * Easy to chain with other AI tasks: The output file ID can be chained into other AI tasks in a flash. ![](https://plugins-media.makeupar.com/smb/blog/post/2023-11-03/54285311-7c65-4658-9e27-11bf5c8dfe56.jpg) ## Integration Guide * How to run AI Photo Background Removal 1. **Resize your source image**
Resize your photo to fit the supported dimensions. See details in **[File Specs & Errors](#section/overview/File-Specs-and-Errors)** 2. **Upload file using the File API**
Using the ***/s2s/v2.0/file*** API to upload a target user image. - Image Requirements - See details in **[File Specs & Errors](#section/overview/File-Specs-and-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 task**
Once the upload is complete, calling POST 'task/sod' with the File ID to execute the AI task and obtains a ***task_id*** to monitor. 4. **Configure a webhook or polling to check the status of a task until it succeed or error**
The ***task_id*** is used to configure webhooks or implement polling for monitoring task status throughout the retention period. Until the AI engine completes the task, the status will remain running. No units are consumed while the task is in the running state. Once processing is complete, the task status will change to either success or error. 1. **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. * Demonstrative scenarios: Common implementation cases: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Transparen_Background_aca3cdbd83.jpg) ## Inputs & Outputs * Inputs * `Image` - **Type:** `image` - **Description:** An image with clear foreground. Real-world application (input): ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_removal_bg_s4_poster_1_289b8eaf81.png) --- * Outputs * `Foreground image` - **Type:** `image` - **Description:** A background removed image. Real-world application (output): ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_removal_bg_s4_poster_2_a6bc3c5f6a.png) ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|File Size|Accepted formats| | ---- | ---- | ---- | ---- | |AI Photo Background Removal|Recommendations and limitations for both input and output images are as follows:
Resolution: 4096 × 4096 pixels (longest side must not exceed 4096 pixels)|<10MB|JPG and PNG| * Error Codes |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| --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Photo Background Removal V1.0 | 1 | --- - [AI Bag Virtual Try-On](https://docs.perfectcorp.com/reference/ai_bag.md): # Overview AR makes luxury bag shopping a tangible experience! AR tech empowers brands to showcase handbags with unmatched realism. From strap length to bag pairing, customers can visualize products instantly through camera. ## Integration Guide This guide walks you through: * **Endpoint:** `/s2s/v2.0/task/bag` * **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY` * **Workflow:** 1. **Prepare a selfie image:** Uploading an image or providing a valid image URL of yourself as the virtual try-on target. 1. **Prepare a bag image:** Uploading an image or providing a valid image URL of a bag product or a person carrying a bag without any obstruction. 1. **Select a style and a gender:** Select a preferred style and the gender you wish to visualize. 1. **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response. 1. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `"success"` or `"error"`. --- * Authentication - Include your API key in the request header using **Bearer Token**: ``` Authorization: Bearer YOUR_API_KEY ``` You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/. --- * AI Bag API Usage Guide This guide explains how to upload images, prepare reference bags, and create virtual try-on tasks using the AI Bag API. *** * Step 1. Upload a File Using the File API Use the **File API** (`/s2s/v2.0/file`) to upload a target user image. **Image Requirements:** * Upload a selfie photo. * Ensure the photo clearly shows the upper body. * Avoid backgrounds with multiple people or distracting objects. **Example Request:** ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/file \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "files": [ { "content_type": "image/jpg", "file_name": "selfie_photo_01_3dbd1b6683.jpg", "file_size": 547541 } ] }' ``` *** * Step 2. Retrieve File API Response The response includes: * `file_id` for creating an AI task. * `requests.url` for uploading the actual image file. **Sample Response:** ```json { "status": 200, "data": { "files": [ { "content_type": "image/jpg", "file_name": "selfie_photo_01_3dbd1b6683.jpg", "file_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud", "requests": [ { "method": "PUT", "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...", "headers": { "Content-Length": "547541", "Content-Type": "image/jpg" } } ] } ] } } ``` *** * Step 3. Upload Image to Provided URL Use the `requests.url` from the File API response to upload the image: ```bash curl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \ --header 'Content-Type: image/jpg' \ --header 'Content-Length: 547541' \ --data-binary @'./selfie_photo_01_3dbd1b6683.jpg' ``` *** * Step 4. Prepare a Reference Bag Image You can: * Upload a bag image using the File API (`/s2s/v2.0/file`), or * Provide a valid image URL. **Supported Bag Images:** * Product image of the bag. * A person carrying a bag without any obstruction as a bag reference. Refer to **[File Specs and Errors](#section/overview/File-Specs-and-Errors)** for detailed specifications. *** * Step 5. Create an AI Task Select a preferred style and the gender you wish to visualize. Use the **AI Task API** (`/s2s/v2.0/task/bag`) to create a virtual try-on task. **Parameters:** * For the user image: `src_file_id` or `src_file_url`. * For the bag image: `ref_file_id`, or `ref_file_url`. **Example Request:** ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/bag \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "src_file_url": "https://example.com/selfie.jpg", "ref_file_url": "https://example.com/accessory.jpg", "gender": "female", "style": "random" }' ``` **Sample Response:** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` *** * Step 6. Poll for Task Result Use the task ID to check the status: ```bash curl --request GET \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/bag/SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' ``` *** * Step 7. Retrieve Result A successful response includes a download URL for the result image: ```json { "status": 200, "data": { "error": null, "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..." }, "task_status": "success" } } ``` Invalid API Key error response: ```json { "status": 401, "error": "Unauthorized", "error_code": "InvalidAccessToken" } ``` --- ## File Specs & Errors * AI Bag Virtual Try-On Specification **Supported Bag Image** * Product Image Requirements * Minimum resolution: 512 × 512 pixels * Only one product per image * The product should cover more than 25 per cent of the image height ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/040_thumb_c5f4d2af8e.jpg) * Worn Image Requirements * Minimum resolution: 800 × 800 pixels ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/003_thumb_c73b207cae.jpg) **Supported Selfie View** * Recommended image resolution: at least 512 × 512 pixels. * Recommended face coverage: more than 15 per cent of the image height. * The image must clearly show a single human subject with the face fully visible and at least a head shot included in the frame, from head to chest. A half-body shot is preferred. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/lashana_lynch_thumb_7a900b811e.jpg) **Try-on Styles** * There are four predefined styles for generating the virtual try-on output: "style_parisian_chic", "style_urban_chic", "style_mediterranean_chic" and "style_art_deco_style". You can specify this style parameter when creating an AI task or allow the system to randomly select a style by default. ![style_parisian_chic](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/fca6a904_b13a_4c90_bc52_d9200a473c70_4d994afa3e.jpg) --- * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Bag Virtual Try-On|Input: long side <= 4096
Output: 1104 x 1472 |< 10MB|jpg/jpeg/png/heic| * Error Codes |Error Code|Description| | ---- | ---- | | error_download_image | Download srcKeys/refKeys error | | error_inference | Inference pipeline error | | error_no_face | No face detected in source image | | error_nsfw_content_detected| NSFW content detected in result image | | exceed_max_filesize | Input file size exceeds the maximum limit (10 MB) | | invalid_parameter | Invalid gender option value
Invalid style option value | | unknown_internal_error | Others | * 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 | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Bag Virtual Try-On V2.0 | 2 | --- - [AI Bangs Filter Virtual Try-On](https://docs.perfectcorp.com/reference/ai_bangs.md): # Overview Try on Your Perfect Hair Bangs with AI Realistic Looks: Experiment with realistic bangs and discover the style that best complements your face.​ Versatile Styling Options: Explore a wide range of bangs styles to suit every personality and occasion.​ Effortless Experience: Enjoy a user-friendly interface that makes trying new bangs easy and fun​. Want to see more Hair Bang styles? Please refer to https://yce.makeupar.com/bangs-filter. Use case: ![AI Hair Bang Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_style_v1_video_1200x674px_1_259f619dfd.png "AI Hair Bang Generator") ![AI Hair Bang Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_style_v1_video_1200x674px_2_7146754733.png "AI Hair Bang Generator") Suggestions for How to Shoot: ![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png "Suggestions for How to Shoot") --- ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Hair Bang 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/png| * 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 |error_bald_image |Input hairstyle is bald --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Bangs Filter Virtual Try-On V1.0 | 1 | --- - [AI Beard Style Generator](https://docs.perfectcorp.com/reference/ai_beard_style.md): # Overview AI Simulation for Men's Beard Styles The AI algorithm also empowers men to have the complete freedom to virtually try different beard styles with the highly sophisticated beard simulation technology, including trim beard, stubble beard, full beard, circle beard, mustache, goatee, and others. Shoppers can also see before and after results, without the commitment of putting a razor to the skin. The beard filters include mustache, short box, ducktail, circle and a dozen more. ## Integration Guide 1. **Upload a Selfie** You can provide the source image in one of two ways: - **Use an Existing Public Image URL** Instead of uploading, you may supply a publicly accessible image URL directly when initiating the AI task. - **Upload via File API** Use the endpoint: ``` POST /s2s/v2.0/file ``` 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. 2. **List Predefined Styles** * Use /s2s/v2.0/task/template/beard-style to fetch a predefined template list and select a ``template_id`` to run an AI task. 3. **Run an AI Task to Obtain a Task ID** Execute the AI task using /s2s/v2.0/task/beard-style. For the target user image, provide either ``src_file_url`` or ``src_file_id``. And a stype ``template_id`` to apply and obtain a ``task_id``. 4. **Poll to Check the Status of a Task Until It Succeeds or Fails** Use the ``task_id`` to monitor the task status by polling GET /s2s/v2.0/task/beard-style to retrieve the current engine status. Until the engine completes the task, the status will remain as running, and no units will be consumed during this stage. You can also implement a webhook to receive notifications when an AI task succeeds or fails. Refer to the **[Webhook](../../../develop/webhook)** section for details. > **Warning:** Polling to check the status of a task within its retention period is mandatory. A task will time out if there is no polling request within the retention period, even if the task is processed successfully. Your units will still be consumed. > **Warning:** You will receive an InvalidTaskId error if you check the status of a timed-out task. Therefore, once you run an AI task, you must poll to check the status within the retention period until the status becomes either success or error. 5. **Retrieve the Result of an AI Task Once Successful** The task status will change to success after the engine processes your input file and generates the resulting image. You will receive a URL for the processed image. --- ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Beardstyle Generator|Resolution: Long side < 1024
face width > 256
face pose: -30 < yaw < 30,
single face only,
need to show full face|< 10MB|jpg/jpeg| * Error Codes |Error Code|Description| | ---- | ---- | |error_no_face |Face are not visible in the source image |error_src_face_too_small |The face is too small |error_inference |Beard removal error or beard generation error |error_face_pose |The face pose of source image is unsupported * 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 | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Beard Style Generator V1.0 | 2 | --- - [AI Body Reshape](https://docs.perfectcorp.com/reference/ai_body_reshape.md): # Overview AI Body Reshape API for Body Reshape & Slimming Feel confident in photos with an AI body editor! Slim, reshape, and enhance your body for natural, stunning proportions. Effortlessly reshape any area — waist, arms, thighs, chest, and more. Get natural, stunning results in just a tap! ## Integration Guide This guide walks you through: Workflow for AI Body Reshape API: **Endpoint:** `/s2s/v2.0/task/body-reshape` **Authentication Required:** `Authorization: Bearer YOUR_API_KEY` **Workflow Steps:** 1. **Image Upload Preparation:** - Prepare a selfie image for upload. - Call the File API `/s2s/v2.0/file` to obtain the upload URL and associated `file_id`. - Upload the selfie image using the provided upload URL. 2. **Optional Preprocessing For Group Photos:** - Preprocess the selfie image if there are more than one person in the image. 3. **Body Reshape Effect Setup:** - Begin by selecting suitable body reshape parameters. 4. **Initiate AI Task and Obtain Task ID:** - Send the `file_id` along with the chosen effect configuration via an HTTP POST request to `/s2s/v2.0/task/body-reshape`. - Await a unique task ID in the response, which identifies this interaction. 5. **Poll Task Status (Continuous Check):** - Use the obtained `task_id` to periodically poll the task status using an HTTP GET request (e.g., `GET /s2s/v2.0/task/body-reshape/${task_id}`). - Continuously monitor for: - `Task_status = "success"` (process completed). - `Task_status = "error"` (resolve or retry if applicable). - Update the workflow accordingly once the status transitions to success. This structured workflow ensures efficient integration with user inputs, automated monitoring of tasks, and seamless retrieval of results. --- * API Playground Interactively explore and test the API using our official playground: **API Playground:** [http://yce.makeupar.com/api-console/en/api-playground/ai-body-reshape/](http://yce.makeupar.com/api-console/en/api-playground/ai-body-reshape/) --- * Authentication - Include your API key in the request header using **Bearer Token**: ``` Authorization: Bearer YOUR_API_KEY ``` You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/. * 1. Upload an Image You may upload a file directly to the server or provide a valid image URL in the AI task payload. * Upload Endpoint ``` POST /s2s/v2.0/file ``` Alternatively, skip this step if you already have a public image URL. --- * 2. Prepare an effect template * Preprocessing Output detected bounding boxes in pixel coordinate. Use the index of result to create a Body Reshape AI task later. ``` { "timed": number, "result": [ { "left": number, "top": number, "width": number, "height": number } ] } ``` * Effect Template JSON Schemas ``` { "version": "1.0", "index": 0, "features": { "arm": 0, // -100~100 "breast_left": 0, // -100~100 "breast_right": 0, // -100~100 "hip": 0, // -100~100 "hip_lift": 0, // -100~100 "leg": 0, // -100~100 "neck_left": 0, // 0~100 "neck_right": 0, // 0~100 "shoulder_left": 0, // -100~100 "shoulder_right": 0, // -100~100 "squared_shoulder_left": 0, // -100~100 "squared_shoulder_right": 0, // -100~100 "slim": 0, // -100~100 "taller": 0, // 0~100 "waist": 0, // -100~100 "belly": 0 // -100~100 } } ``` index: index of detected body from preprocessing. optional, default 0. features: required at least 1, non-zero body reshape parameter, cannot be all zero. * Example Payload (ready to send) ``` { "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/body_reshape_02_7777218379.jpg", "version": "1.0", "index": 0, "features": { "arm": 0, "waist": -20, "taller": 80, "squared_shoulder_left": 10, "squared_shoulder_right": 10, "neck_left": 0, "neck_right": 0, "hip": 10, "breast_left": 30, "breast_right": 30, "slim": -70, "shoulder_left": 30, "shoulder_right": 30, "leg": -30, "hip_lift": 0, "belly": -50 } } ``` * 3. Create a Body Reshape AI Task and Poll for Results Once you have an image and a complete effect payload, create a task. The API processes the request asynchronously. You must poll the task status until it reaches `success` or `error`. * Create Task Endpoint ``` POST /s2s/v2.0/task/body-reshape ``` * Polling Endpoint ``` GET /s2s/v2.0/task/body-reshape/{task_id} ``` --- ## File Specs & Errors * AI Body Reshape Specification **Supported Selfie View** Full body shot with clear facial expression and body posture visible. ![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_body_reshape_02_7777218379.jpg) **Visibility & Pose Requirements** | **Region** | **What must be true in the source image** | |------------|---------------------------------------------------| | **Neck** | The neck must be visible in the source image. | | **Arm** | Both arms – upper arm, forearm and hand – have to be fully shown. | | **Leg** | The whole leg must appear in the picture. | | **Hip** | Hips need to be in view. | | **Hip‑Lift** | Hips need to be in view. | | **Shoulder** | • Shoulders are required to be seen.
• Raising a hand is not allowed.
• A 90° side pose is not allowed. | | **Belly** | The belly is required to be visible. | | **Waist** | Waist must be visible. | | **Breast** | • Breast area must appear in the picture.
• The shot should include the hips (i.e., not a “half‑body without hips”).
• The middle of the breast must be shown. | | **Slim** | Shoulders need to be in the frame. | | **Taller** | • Hips must appear.
• A half‑body view should include the legs (i.e., legs are visible). | **Body Reshape Customization Parameters Guide** | Category | Parameter | Function | Min Value (-100 / 0) | Max Value (100) | | -------- | --------- | -------- | -------------------- | --------------- | | Arms| Intensity | Adjusts the thickness of the arms | Thin | Thick | | Belly| Intensity | Adjusts abdominal projection | Flat | Protruding | | Chest| Intensity (Left / Right) | Adjusts chest volume on each side | Flat | Full | | Hip Lift | Intensity | Adjusts the curvature and lift of the hips (adds a butt‑lifting effect) | Sculpted (lifted and tightened) | Rounded (lifted with fuller volume) | | Hip Size | Intensity | Adjusts the overall width of the hips | Narrow | Wide | | Legs| Intensity | Adjusts the thickness of the legs | Thin | Thick| | Neck| Intensity (Left / Right) | Adjusts neck contour and slimming per side| Original (0)| Tucked in | | Shoulder Width | Intensity (Left / Right) | Adjusts the span of each shoulder | Narrow | Broad | | Shoulder Shape | Intensity (Left / Right) | Adjusts the angle and slope of each shoulder | Sloped | Squared | | Slim| Intensity | Adjusts overall body curvature | Slim | Curvy | | Tall| Intensity | Adjusts the overall character height | Original (0) | Taller | | Waist| Intensity | Adjusts the width of the waistline | Narrow | Wide | **Note:** *“Left” and “Right” refer to the character's perspective, not the viewer's side of the screen.* --- * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Body Reshape|long side <= 2048, short side >= 320|< 10MB|jpg/jpeg/png| * Error Codes | Error Code | Description | | ---- | ---- | | RUNTIME_ERROR | An unexpected error occurred dubody reshape runtime | | PHOTO_DETECTION_FAIL | The user photo could not be processed correctly, for example no hand detected | | PHOTO_CHECK_INVALID | The pose or size of the user photo is invalid | | INPUT_ERROR | The input file format is incorrect | | INPUT_MAIN_IMAGE_EMPTY | A user image is required | * 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 | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Body Reshape V1.0 | 1 | --- - [AI Bracelet Virtual Try On](https://docs.perfectcorp.com/reference/ai_bracelet.md): # Overview The Ultimate AI Bracelet Virtual Try-On Employ AI-powered solutions to assist your customers with online purchases, ensuring perfect fit and great shopping satisfaction every time. Only One 2D Image Needed. Create a compelling shopping flow with the hyper-realistic bracelet virtual try-on experiences. Our solution caters to the needs of jewelry brands of all sizes. Opt for 2D images for effortless yet high-quality virtual try-on experiences with minimal effort. This unique feature sets us apart in the world of e-commerce, making it easier than ever for customers to experience your products. ## Integration Guide This guide walks you through: * **Endpoint:** `/s2s/v2.0/task/2d-vto/bracelet` * **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY` * **Workflow:** 1. **Prepare a wrist image:** Uploading an image or provide a valid image URL of your wrist 1. **Prepare a bracelet image:** Uploading an image or provide a valid image URL of a bracelet product 1. **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response. 1. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `"success"` or `"error"`. --- * API Playground Interactively explore and test the API using our official playground: **API Playground:** [http://yce.makeupar.com/api-console/en/api-playground/ai-bracelet-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-bracelet-virtual-try-on/) --- * Authentication - Include your API key in the request header using **Bearer Token**: ``` Authorization: Bearer YOUR_API_KEY ``` You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/. * 1. Upload an Image You may upload a file directly to the server or provide a valid image URL in the VTO task payload. * Upload Endpoint ``` POST /s2s/v2.0/file ``` Alternatively, skip this step if you already have a public image URL. You may upload a file directly to the URL provided in the response from the File API and then use the corresponding `src_file_id` returned by the File API to invoke the AI task later. Or provide a valid image URL in the VTO task payload as `src_file_url`. The `src_file_id` or `src_file_url` will serve as the virtual try-on target. You must also provide another bracelet product image as a reference using `ref_file_ids` or `ref_file_urls` to be applied to your `src_file_id` or `src_file_url`. The AI engine supports automatic background removal for your bracelet product image. However, you may provide an occlusion mask image file for either your hand (`srcmsk_file_id` or `srcmsk_file_url`) or the bracelet product (`refmsk_file_ids` or `refmsk_file_urls`) to fine-tune the segmentation. --- * 2. Create a Bracelet VTO Task and Poll for Results Once you have an image and a template ID, create a task. The API processes the request asynchronously. You must poll the task status until it reaches `success` or `error`. * Create Task Endpoint ``` POST /s2s/v2.0/task/2d-vto/bracelet ``` * Polling Endpoint ``` GET /s2s/v2.0/task/2d-vto/bracelet/{task_id} ``` --- ## File Specs & Errors * AI Bracelet Virtual Try-On Specification **Supported Bracelet View** A bracelet image must be provided in a three-quarter front view (approximately 45 degrees). ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/bracelet_product_09_2cb9721d77_2f8d90ab9f.jpg) **Supported Wrist View** The back of the wrist should be fully visible with all five fingers clearly shown and without any occlusion. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/watch_and_bracelet_user_01_09f16603cb_878dc89179.jpg) **bracelet\_wearing\_location: float (−0.3 to 1.0)** Indicates the position along the wrist: −0.3 represents near the main wrist joint 1.0 represents far from the main wrist joint Default value: null (use engine default) ![bracelet_wearing_location](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/bracelet_wearing_location_01ac0a048e.jpg) **bracelet\_shadow\_intensity: float (0.0 to 1.0)** Controls the strength of the shadow: 0.0 represents no shadow 1.0 represents maximum shadow Default value: 0.15 **bracelet\_ambient\_light\_intensity: float (0.0 to 1.0)** Defines the extent to which lighting references the target hand image: 0.0 ignores the hand image lighting 1.0 fully matches the hand image lighting and shadow rendering Default value: 1.0 **Bracelet Anchor Points: array of 2 points in pixel coordinate (optional)** Marks the inner edge of the bracelet where it contacts the wrist, specifying the left and right points. If this parameter is not provided, the AI engine will automatically detect the anchor points. ![bracelet_anchor_point](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/bracelet_anchor_point_c353245edc.jpg) --- * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Bracelet Virtual Try-On|long side <= 4096 |< 10MB|jpg/jpeg/png| * Error Codes |Error Code|Description| | ---- | ---- | | RUNTIME_ERROR | An unexpected error occurred dubracelet runtime | | PHOTO_DETECTION_FAIL | The user photo could not be processed correctly, for example no hand detected | | OBJECT_DETECTION_FAIL | The object photo could not be processed correctly, for example no product detected | | PHOTO_CHECK_INVALID | The pose or size of the user photo is invalid | | INPUT_ERROR | The input file format is incorrect | | INPUT_MAIN_IMAGE_EMPTY | A user image is required | * 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 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Bracelet Virtual Try-On V1.0 | 1 Unit for Single-item wear
2 Units for Stacked wear | --- - [AI Breast Augmentation Simulator](https://docs.perfectcorp.com/reference/ai_breast_augmentation.md): # Overview AI Breast Augmentation Simulator provides a powerful, non-invasive solution for reshaping your body, no surgery, no recovery time required. With advanced AI technology, you can instantly visualize and explore your ideal appearance, preview before-and-after results, and achieve professional-quality enhancements with ease and simplicity. Enhance your photos naturally by refining your silhouette or correcting perspective issues. For instance, if you’re seeking a more balanced or proportionate upper-body appearance, AI Breast Augmentation Simulator offers AI-powered bust contour enhancement. This feature uses intelligent algorithms to gently add definition and volume where desired, creating subtle, realistic improvements that maintain your natural features and proportions. The result is a confident, polished look without artificial-looking distortion. ![](https://plugins-media.makeupar.com/smb/blog/post/2025-06-18/e41b8942-22e1-4846-8f81-f41171b74558.jpg) Unlike traditional filters that often produce exaggerated or unrealistic effects, this tool delivers clean, authentic edits tailored to your unique anatomy. Whether you’re preparing images for social media, personal use, or creative projects, the enhancements remain true to life while highlighting your best qualities. To begin exploring virtual body refinement, simply create an AI Breast Augmentation Simulator task and adjust the intensity gradually to achieve your desired look. From there, adjust parameters such as augmentation intensity to match your aesthetic preferences, all within a user-friendly API designed for both beginners and experienced users. ![](https://plugins-media.makeupar.com/smb/blog/post/2025-06-18/733cedfd-2e8e-4cfc-8758-6854d923664b.jpg) --- ## Integration Guide This guide walks you through: Workflow for AI Breast Augmentation Simulator API: **Endpoint:** `/s2s/v2.0/task/breast-shape` **Authentication Required:** `Authorization: Bearer YOUR_API_KEY` **Workflow Steps:** 1. **Image Upload Preparation:** - The process begins with preparing a bust shot selfie. 2. **AI Breast Augmentation Simulator Settings** For AI Breast Augmentation Simulator, control the degree of enhancement by adjusting the intensity level, which ranges from 1 (subtle) to 3 (pronounced). Start with a lower setting and incrementally increase it to achieve a natural-looking result that aligns with your aesthetic preference. Gradual adjustment helps ensure realistic and proportionate outcomes. 3. **Initiate AI Task and Obtain Task ID:** - Send the uploaded image along with the parameter configuration via an HTTP POST request to `/s2s/v2.0/file`. - Await a unique task ID in the response, which identifies this interaction. 4. **Poll Task Status (Continuous Check):** - Use the obtained `task_id` to periodically poll the task status using an HTTP GET request (e.g., `GET /task/${task_id}`). - Continuously monitor for: - `Task_status = "success"` (process completed). - `Task_status = "error"` (resolve or retry if applicable). - Update the workflow accordingly once the status transitions to success. This structured workflow ensures efficient integration with user inputs, automated monitoring of tasks, and seamless retrieval of results. --- * Authentication - Include your API key in the request header using **Bearer Token**: ``` Authorization: Bearer YOUR_API_KEY ``` You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/. --- * Upload an Image You may upload a file directly to the server or provide a valid image URL in the AI task payload. * Upload Endpoint ``` POST /s2s/v2.0/file ``` Alternatively, skip this step if you already have a public image URL. --- * Adjust AI Breast Augmentation Simulator Intensity **AI Breast Augmentation Simulator Settings** For AI Breast Augmentation Simulator, control the degree of modification by setting the intensity level between **1 and 3**, where: - **Level 1** provides subtle, natural-looking adjustments ideal for minor refinement. - **Level 2** offers moderate enhancement, balancing realism with noticeable improvement. - **Level 3** delivers the most pronounced effect, suitable for significant reshaping while preserving anatomical plausibility. Select the intensity level that best aligns with your aesthetic goals and desired look. --- * Create a AI Breast Augmentation Simulator AI Task and Poll for Results After uploading an image and selecting your preferred intensity level, you may proceed to start the enhancement task. The API processes the request asynchronously. You must poll the task status until it reaches `success` or `error`. * Create Task Endpoint ``` POST /s2s/v2.0/task/breast-shape ``` * Polling Endpoint ``` GET /s2s/v2.0/task/breast-shape/{task_id} ``` --- ## File Specs & Errors * AI Breast Augmentation Simulator Specification **Image Requirements and Recommendations for Optimal Results** - **Resolution Guidelines**: The longest side of the input image must not exceed 4096 pixels. For best performance, ensure that the upper body region—defined as the area from the top of the head down to and including the chest—is rendered at a resolution of at least 1024 × 768 pixels. - **Subject Requirements**: - The image must contain at least one fully detectable person. Both shoulders should be clearly visible in-frame. - The chest area must be visible. This includes both clothed and unclothed scenarios, provided the subject is facing primarily forward (i.e., yaw angle between −90° and +90°). A frontal view is strongly preferred over angled or profile poses. - **Recommended Practices for Enhanced Outcomes**: - Prioritize upper-body composition: the image should either focus specifically on the upper body, or—if the full figure is included—the upper body region should occupy a substantial portion of the frame and exceed 1024 pixels in its longest dimension. - Use frontal poses exclusively; avoid side-facing or significantly rotated positions, as these reduce detection accuracy and result quality. - For the most natural-looking enhancement of the chest contour, select attire that exposes some skin around the bust area—such as swimwear, low-cut tops, or V-neck garments. These styles allow the AI to better infer underlying structure and produce subtle, realistic cleavage effects. - The system supports only single-subject images. In cases where multiple people appear in the frame, processing will automatically target the individual with the largest visible shoulder span (i.e., the person closest to or most centrally aligned with the camera). - Avoid occlusions over the chest region. Objects such as bags, backpack straps, scarves, necklaces, or other accessories may be incorrectly removed or cause artifacts during editing. - Clothing appearance may differ from the original image. The degree of modification depends on the intensity setting: higher enhancement levels produce more pronounced changes, including visible alterations to garment shape, fit, and drape around the chest area. Following these guidelines ensures optimal input quality and maximizes the fidelity, realism, and consistency of the AI-generated enhancements. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_02-1_2dfe3418c2.jpg) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_02-2_a88356deeb.jpg) --- * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Breast Augmentation Simulator|minimum: 512x384
maximum: long side < 4096|< 10MB|jpg/jpeg/png/heic | * Error Codes | Error Code | Description | |----------------------------------|-------------| | `invalid_parameter` | The provided parameters are invalid—specifically, one or more of the required fields (`src_keys`, `dst_keys`, or `acts`) are missing, malformed, or contain unsupported values. | | `exceed_max_filesize` | The input image exceeds the maximum allowed file size (10 MB). Please compress or resize the image before submission. | | `error_download_image` | The system failed to download the source image, likely due to network issues, an invalid URL, or inaccessible resource permissions. | | `error_decode_image` | The downloaded image could not be decoded—this may result from file corruption, unsupported format, or invalid binary data. | | `error_nsfw_content_detected` | Potential Not Safe For Work (NSFW) content has been detected either in the source image or in the generated output image. Processing was aborted for compliance and safety reasons. | | `error_pose` | Human pose estimation failed; no full-body or upper-body skeleton could be reliably detected, preventing subsequent anatomical analysis. | | `error_breast_region_detection` | The system attempted to detect the breast region based on pose and segmentation cues but was unable to locate a valid, identifiable chest area (e.g., due to occlusion, extreme angle, or insufficient visibility). | * 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 | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Breast Augmentation Simulator V1.0 | 1 | --- - [AI Clothes Virtual Try-On](https://docs.perfectcorp.com/reference/ai_clothes.md): # Overview AI Clothes is a virtual fitting room that lets users try on clothes without physically wearing them. Using AI and photo editing technology, these apps overlay outfits onto your image so you can see how different styles and fits look on your body type. It’s perfect for online shopping, style inspiration, or just playing around with fashion ideas. Try on clothes virtually with AI Clothes . Upload any clothing reference to swap outfits with you photo for an instant virtual wardrobe transformation. --- ## Integration Guide * API Playground You can use the API Playground to test the AI Clothes virtual try-on feature. This allows you to experiment with your ideas and gain a better understanding of the try-on process. Access the API Playground at: --- * AI Clothes API Usage Guide This guide explains how to upload images, prepare reference outfits, and create virtual try-on tasks using the AI Clothes API. *** * Step 1. Upload a File Using the File API Use the **File API** (`/s2s/v2.0/file`) to upload a target user image. **Image Requirements:** * Upload a high-resolution full-body photo. * Ensure the photo clearly shows the entire body. * Avoid backgrounds with multiple people or distracting objects. **Example Request:** ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/file \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "files": [ { "content_type": "image/jpg", "file_name": "full_body_photo_01_3dbd1b6683.jpg", "file_size": 547541 } ] }' ``` *** * Step 2. Retrieve File API Response The response includes: * `file_id` for creating an AI task. * `requests.url` for uploading the actual image file. **Sample Response:** ```json { "status": 200, "data": { "files": [ { "content_type": "image/jpg", "file_name": "full_body_photo_01_3dbd1b6683.jpg", "file_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud", "requests": [ { "method": "PUT", "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...", "headers": { "Content-Length": "547541", "Content-Type": "image/jpg" } } ] } ] } } ``` *** * Step 3. Upload Image to Provided URL Use the `requests.url` from the File API response to upload the image: ```bash curl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \ --header 'Content-Type: image/jpg' \ --header 'Content-Length: 547541' \ --data-binary @'./full_body_photo_01_3dbd1b6683.jpg' ``` *** * Step 4. Prepare a Reference Outfit * 4.1 Upload a Reference Outfit Image You can: * Upload an outfit image using the File API (`/s2s/v2.0/file`), or * Provide a valid image URL. **Supported Outfit Images:** * Product image of the clothing. * Full-body photo as an outfit reference. Refer to **[File Specs and Errors](#section/overview/File-Specs-and-Errors)** for detailed specifications. *** * Step 5. Create an AI Task Use the **AI Task API** (`/s2s/v2.0/task/cloth-v4`) to create a virtual try-on task. **Parameters:** * For the user image: `src_file_id` or `src_file_url`. * For the outfit image: `ref_file_id`, `ref_file_url`, or `template_id`. **Example Request:** ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/cloth-v4 \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/clothes_03_cccd5d4803.jpeg", "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/clothes_reference_full_body_01_5a000d999f.png", "garment_category": "full_body" }' ``` **Sample Response:** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` *** * Step 6. Poll for Task Result Use the task ID to check the status: ```bash curl --request GET \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/cloth-v4/ \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' ``` *** * Step 7. Retrieve Result A successful response includes a download URL for the result image: ```json { "status": 200, "data": { "error": null, "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..." }, "task_status": "success" } } ``` Invalid API Key error response: ```json { "status": 401, "error": "Unauthorized", "error_code": "InvalidAccessToken" } ``` --- Use cases: ![](https://plugins-media.makeupar.com/smb/blog/post/2025-05-08/b80f4ae1-c905-4ec0-b491-e42c15e65575.gif) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/01%20ai%20clothes%20changer.jpg) ![](https://plugins-media.makeupar.com/smb/blog/post/2023-12-01/45f451aa-4b4f-466d-9da7-4538573c92af.jpg) Suggestions for How to Shoot: ![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI-Cloth-Guideline.png "Suggestions for How to Shoot") ## File Specs & Errors * Supported Formats & Dimensions |Type|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |Target user image|1024×768 recommended, 512×384 minimum, max side 4096 px.

- Single person only.
- The person should occupy at least 80% of the frame for optimal results.
- Images should include the upper body only, from the chest upwards. There is no need to show the abdomen, but the shoulders should be visible.
- The face must be fully visible, with no obstructions.
- The body must be facing forward in a standing position (no sitting or crouching). |< 10MB|jpg/png| |Reference image of the clothing |1024×768 recommended, 512×384 minimum, max side 4096 px.

- If Using a Real-Person Clothing Photo as Reference
   - Must feature only one person.
   - The visible clothing area must fully cover the intended try-on area.
      - Example: For full-body try-on, a half-body clothing image is not acceptable.
      - Example: For lower-body try-on, partial pants are not acceptable.
   - The clothing must not be heavily obstructed (e.g. covered by long hair or arms).
   - The face must be fully visible, with no obstructions.
   - The body must be facing forward in a standing position (no sitting or crouching).

- If Using a Product Image as Reference
   - Must be a front-facing product shot of a single garment.
   - Do not use composite images (e.g. top and bottom in one photo).
   - For the lower body, only actual worn outfits are supported, not standalone product images.|< 10MB|jpg/png| * Error Codes * Error code (Preprocess) | Error code | Description | | ---------- | ----------- | | exceed_max_filesize | The SRC or REF image is too large. The long side must not exceed 4096 pixels. | | error_below_min_image_size | The SRC or REF image is too small. The long side must be at least 128 pixels. | | error_pose | The pose could not be detected from the uploaded human SRC image. | | error_invalid_ref | The REF image is invalid, for example, it is empty or the subject is not fully visible. | | error_apply_region_mismatch | The apply region in the SRC image does not match the REF image, so no edits can be applied. | | error_invalid_src | When the source image shows only the lower body or only the feet. | * Error code (Engine) | Error code | Description | | ---------- | ----------- | | invalid_parameter | - Invalid garment category.
- Style_id is not in inference_style_list.
- Invalid src_keys, dst_keys, or acts.
- Invalid ref_keys or template_ref_image.
- Exactly one of them must be provided. | | error_download_image | The SRC or REF image could not be downloaded. | | exceed_max_filesize | The SRC or REF image is too large. The file size must not exceed 10 MB. | | error_nsfw_content_detected | Potential NSFW content was detected in the result image. | | error_editing_failed | The editing process failed because the result image is too similar to the source image. | | unknown_internal_error | - Failed to load the model.
- Invalid scheduler algorithm type.
- No engine loaded.
- The file is not in the upload results. | * 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 | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Clothes Virtual Try-On V2.0 | 2 | | AI Clothes Virtual Try-On V3.0 | 2 | --- - [AI Color Correction](https://docs.perfectcorp.com/reference/ai_color_correction.md): # Overview Perfect AI Color Correction let you automatically adjust saturation, temperature, and hue of photos with ease. Adjust white balance to correct color temperature, enhance saturation and make it vibrant, correct exposure level to balance brightness, remove color casts or tints, improve skin tones for a nature-looking portrait, enhance shadow and highlight details, remove noise and improve clarity, or even apply creative color grading effects all in one touch. With AI Color Correction, you can instantly generate 4 different color graded versions of your photos, each with unique color tones ranging from warm to cool within seconds. Sample Before: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/color_correction_topbanner_before_dt_100_45429e8625.jpg) After: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/color_correction_topbanner_after_dt_100_ef9f9c48ed.jpg) Before: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/color_correction_s1_image_before_dt_fa73b5d41a.jpg) After ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/color_correction_s1_image_after_dt_a3e88a101b.jpg) --- ## File Specs & Errors * Supported Formats & Dimensions | AI Feature | Supported Dimensions | Supported File Size | Supported Formats | | ---- | ---- | ---- | ---- | | AI Color Correction | long side <= 4096 | < 10MB | jpg/jpeg/png | * Error Codes |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_decode_image | Decode source image error | | error_nsfw_content_detected | NSFW content detected in source image | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Color Correction V1.0 | 2 | --- - [AI Earrings Virtual Try On](https://docs.perfectcorp.com/reference/ai_earrings.md): # Overview The Ultimate AI Earring Virtual Try-On Top AI ear piercing simulator for virtual earring try-on and virtual piercing try-on Create realistic and dynamic earrings virtual try-on from a 2D image, no expensive 3D modelling required. Our advanced algorithms create lifelike virtual try-on earring SKUs with sophisticated lighting effects and physically accurate motions. ## Integration Guide This guide walks you through: * **Endpoint:** `/s2s/v2.0/task/2d-vto/earring` * **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY` * **Workflow:** 1. **Prepare a selfie image:** Uploading an image or provide a valid image URL 2. **Prepare an earring image:** Uploading an image or provide a valid image URL of an earring product 3. **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response. 4. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `"success"` or `"error"`. --- * API Playground Interactively explore and test the API using our official playground: **API Playground:** [http://yce.makeupar.com/api-console/en/api-playground/ai-earring-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-earring-virtual-try-on/) --- * Authentication - Include your API key in the request header using **Bearer Token**: ``` Authorization: Bearer YOUR_API_KEY ``` You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/. * 1. Upload an Image You may upload a file directly to the server or provide a valid image URL in the VTO task payload. * Upload Endpoint ``` POST /s2s/v2.0/file ``` Alternatively, skip this step if you already have a public image URL. You may upload a file directly to the URL provided in the response from the File API and then use the corresponding `src_file_id` returned by the File API to invoke the AI task later. Or provide a valid image URL in the VTO task payload as `src_file_url`. The `src_file_id` or `src_file_url` will serve as the virtual try-on target. You must also provide another earring product image as a reference using `ref_file_ids` or `ref_file_urls` to be applied to your `src_file_id` or `src_file_url`. The AI engine supports automatic background removal for your earring product image. However, you may provide an occlusion mask image file for either your hand (`srcmsk_file_id` or `srcmsk_file_url`) or the earring product (`refmsk_file_ids` or `refmsk_file_urls`) to fine-tune the segmentation. --- * 2. Create a Earring VTO Task and Poll for Results Once you have an image and a template ID, create a task. The API processes the request asynchronously. You must poll the task status until it reaches `success` or `error`. * Create Task Endpoint ``` POST /s2s/v2.0/task/2d-vto/earring ``` * Polling Endpoint ``` GET /s2s/v2.0/task/2d-vto/earring/{task_id} ``` --- ## File Specs & Errors * AI Earring Virtual Try-On Specification **Supported Earring Reference Image** * A single earring image in a clear front view without obstruction. * All parameters (including anchor points, masks, location, etc.) apply **only** when the reference image shows a **single earring** being worn. * If the try-on reference image shows **both earrings**, all parameters will use **auto-detection and default settings**. * When trying on **both earrings**, the clearer ear will be used as the source, and the other ear will be generated by mirroring it. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/earring_product_01_41c943f9fc_037ffb1241.jpg) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/earring_product_07_5476e0a156_a69e8e6549.jpg) **Supported Selfie View** * The AI Earring Virtual Try-On supports front-facing images, but the best results are achieved with side-facing images. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Earring_restriction_cdf1de3c7b.png) **earring\_wearing\_location: integer array of size 2** Specifies the target location in the selfie where the earring should be placed. Default value: null (engine default) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/wearing_location_b4f6f4453a.jpg) **earring\_scale: number greater than 0** Controls the earring size in centimetres. Default value: null (engine default) **earring\_is\_right\_ear: boolean** Indicates whether the earring is worn on the right ear. By default, it is worn on the right ear. Default value: true **earring\_occluded\_type: number (Enum: 0, 1, 2)** Specifies the occlusion type: 0 means auto-detect 1 means occluded 2 means no occlusion Default value: 0 **earring\_shadow\_intensity: float (0.0 to 1.0)** Controls the shadow strength: 0.0 represents no shadow 1.0 represents maximum shadow Default value: 0.15 **earring\_ambient\_light\_intensity: float (0.0 to 1.0)** Defines how much the lighting references the selfie image: 0.0 ignores the selfie image lighting 1.0 fully matches the selfie image lighting and shadow rendering Default value: 1.0 **earring\_anchor\_point: array of one point in pixel coordinate (optional)** Specifies the wearing position in the earring product image. Default value: null (engine default) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/anchor_point_787282aa19.jpg) --- * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Earring Virtual Try-On|long side <= 4096 |< 10MB|jpg/jpeg/png| * Error Codes |Error Code|Description| | ---- | ---- | | RUNTIME_ERROR | An unexpected error occurred duearring runtime | | PHOTO_DETECTION_FAIL | The user photo could not be processed correctly, for example no hand detected | | OBJECT_DETECTION_FAIL | The object photo could not be processed correctly, for example no product detected | | PHOTO_CHECK_INVALID | The pose or size of the user photo is invalid | | INPUT_ERROR | The input file format is incorrect | | INPUT_MAIN_IMAGE_EMPTY | A user image is required | * 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 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Earrings Virtual Try-On V1.0 | 1 Unit for Single-item wear
2 Units for Stacked wear | --- - [AI Eye Color Lens Virtual Try-On](https://docs.perfectcorp.com/reference/ai_eye_color_lens.md): # Overview AI Eye Color Lens Virtual Simulation provides instant, hyper‑realistic contact lens try‑on by precisely detecting the iris, preserving natural reflections, accurately simulating lens opacity and blending across all iris colors, and enabling users to explore shades from subtle enhancements to vibrant blue transformations, all within a single, professional‑grade AI API. ![](https://plugins-media.makeupar.com/smb/blog/post/2022-01-25/2a348e5b-6a2b-4f08-bc54-1d16a0777e87.jpg) **Contact Lenses Virtual Simulation** Transform eye color instantly with our AI‑powered virtual try‑on tool. The AI Eye Color Lens Virtual Try‑On delivers hyper‑realistic results by precisely detecting the iris and applying natural, lifelike color adjustments, allowing shoppers to explore new styles without physical samples. **Hyper‑Realistic Output** The system preserves natural eye reflections for authentic results, ensuring each color transformation looks true to life. **Advanced Contact Filter Simulation** The contact lens filter accurately replicates opacity and blending across different iris base colors, enabling customers to virtually try on a full range of lenses with realistic depth and tone. **More Than an Eye Color Changer** This technology goes beyond simple filters, offering a professional‑grade virtual lens experience that enhances customer confidence and boosts conversion. --- ## Integration Guide * Take a Selfie * Face the camera directly with proper lighting. * Use the JS Camera Kit to capture the photo. * Prepare Your Lens Style Cutout * Provide **one clear Lens Style image**: * Format: **PNG** (recommended: background removed) * Dimensions: **200 × 200 ≤ W × H ≤ 600 × 600** * File size: **< 10 MB** **Samples:** ![](https://d3ss46vukfdtpo.cloudfront.net/static/media/01.00ccf3ac.png) ![](https://d3ss46vukfdtpo.cloudfront.net/static/media/02.c8beb3fc.png) * Retrieve upload URLs and File IDs via ***/s2s/v2.0/file*** API Upload the following files using the upload URLs returned in the file API response: * Your selfie photo * Lens Style image * Execute AI Task ***/s2s/v2.0/task/eye-color-vto*** Run the AI task using file IDs or image URLs as the input source. Configure the effect parameters as desired. * Poll Task Status Use the returned **task\_id** to monitor task progress. Poll **GET /task/eye-color-vto** to check the engine's status. The task will remain in a **“running”** state until it is completed. No units are consumed while the task is running. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_9535461b-69fc-4432-b56b-2d7c4cd0bf3b_b1ef78e813.jpg) * **Sample application scenario** AI Eye Color Lens Virtual Simulation transforms how customers shop for colored contact lenses. The process is straightforward, engaging, and requires minimal effort from users. - Step1: Pick Your Favorite color Once customers land on your site and browse your selection, they can select the shades they’d like to try on. Whether they're eyeing a subtle hazel, vibrant green, or icy blue, they can explore a wide variety of colors. - Step 2: Open the Virtual Try-On Camera With just one click, the virtual try-on tool activates. No need for complicated setup instructions or additional downloads. - Step 3: Use Live Camera or Upload a Photo Users can opt for a live camera experience or upload a photo to virtually try on the colored contact lenses. The feature mirrors real-life outcomes with impressive accuracy, ensuring they see how each shade will look in natural settings. ![](https://plugins-media.makeupar.com/smb/blog/post/2025-03-28/2732a9f0-9cae-4639-b765-15866550b109.jpg) ## File Specs & Errors * Supported Formats & Dimensions |Type|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Eye Color Lens Virtual Simulation|Selfie Image:
* Long side ≤ 1920 px
* Short side ≥ 320 px

Lens Style Image:
* File format: PNG
* Resolution: 200 × 200 ≤ W × H ≤ 600 × 600 px|< 10MB|jpg/png| * Error Codes |Error Code|Description| | ---- | ---- | |error_below_min_image_size|If your image is smaller than 320 pixels in width or height, it's too small to use| |error_face_position_invalid|Your face needs to be fully visible in the image, without any parts cut off| |error_face_position_too_small|The face in your photo is too small to analyze properly| |error_face_position_out_of_boundary|Your face is either too large or partially outside the edges of the photo| |error_insufficient_lighting|The lighting is too dim, which makes analysis difficult| |error_face_angle_invalid|Your face angle isn't quite right. For front-facing shots, keep your head within 10 degrees of straight. For side-facing shots, the angle should be more than 15 degrees| * 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 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Eye Color Lens Virtual Try-On V1.0 | 1 | --- - [AI Fabric Virtual Try-On](https://docs.perfectcorp.com/reference/ai_fabric.md): # Overview Transform your look with stunning realism! Explore unique fabric styles with photo mode — whether it's the elegance of silky textures or the vibrance of bold prints, the AI Fabric API brings materials to life! Developers can craft immersive experiences that let users see and feel fabrics like never before. Plus, fresh fabric updates are always on the way! --- ## Integration Guide * AI Fabric API Usage Guide This guide explains how to upload images, fetch predefined fabric styles, and create virtual try-on tasks using the AI Fabric API. *** * Step 1. Upload a File Using the File API Use the **File API** (`/s2s/v2.0/file`) to upload a target user image. **Image Requirements:** * Upload a high-resolution full-body photo. * Ensure the photo clearly shows the entire body. * Avoid backgrounds with multiple people or distracting objects. **Example Request:** ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/file \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "files": [ { "content_type": "image/jpg", "file_name": "full_body_photo_01_3dbd1b6683.jpg", "file_size": 547541 } ] }' ``` *** * Step 2. Retrieve File API Response The response includes: * `file_id` for creating an AI task. * `requests.url` for uploading the actual image file. **Sample Response:** ```json { "status": 200, "data": { "files": [ { "content_type": "image/jpg", "file_name": "full_body_photo_01_3dbd1b6683.jpg", "file_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud", "requests": [ { "method": "PUT", "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...", "headers": { "Content-Length": "547541", "Content-Type": "image/jpg" } } ] } ] } } ``` *** * Step 3. Upload Image to Provided URL Use the `requests.url` from the File API response to upload the image: ```bash curl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \ --header 'Content-Type: image/jpg' \ --header 'Content-Length: 547541' \ --data-binary @'./full_body_photo_01_3dbd1b6683.jpg' ``` *** * Step 4. Fetch Predefined Fabric Templates Use the **Template API** (`/s2s/v2.0/task/template/fabric`) to retrieve a list of predefined fabric templates: ```bash curl --request GET \ --url 'https://yce-api-01.makeupar.com/s2s/v2.0/task/template/fabric?page_size=20&starting_token=73a3c9e69b89' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` *** * Step 5. Create an AI Task Use the **AI Task API** (`/s2s/v2.0/task/fabric`) to create a virtual try-on task. **Parameters:** * For the user image: `src_file_id` or `src_file_url`. * For the fabric style: `template_id`. **Example Request:** ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/fabric \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "template_id":"good_template_001", "src_file_url":"https://example.com/selfie.jpg" }' ``` **Sample Response:** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` *** * Step 6. Poll for Task Result Use the task ID to check the status: ```bash curl --request GET \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/fabric/ \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' ``` *** * Step 7. Retrieve Result A successful response includes a download URL for the result image: ```json { "status": 200, "data": { "error": null, "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..." }, "task_status": "success" } } ``` Invalid API Key error response: ```json { "status": 401, "error": "Unauthorized", "error_code": "InvalidAccessToken" } ``` --- Use cases: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Fabric.png) ![](https://plugins-media.makeupar.com/smb/blog/post/2024-05-07/b103976d-1b0e-4bed-aab4-9307308b84d7.jpg) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/03%20ai%20clothes%20changer.jpg) Suggestions for How to Shoot: ![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI-Cloth-Guideline.png "Suggestions for How to Shoot") --- ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Fabric|long side <= 4096, single person only, The abdomen, face, and shoulders should all be visible. The face must not be obstructed. The body should be upright and facing forward, without any unusual poses like sitting or squatting.|< 10MB|jpg/jpeg| * Error Codes |Error Code|Description| | ---- | ---- | |error_apply_region_not_detected|The clothing area is either too small or wasn’t detected in the input image * 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 | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Fabric Virtual Try-On V1.0 | 2 | --- - [AI Face Attributes & Ratio Analyzer](https://docs.perfectcorp.com/reference/ai_face_analyzer.md): # Overview The AI Face Attributes & Ratio Analyzer examines face structure, identifying features like face, eye, eyebrow, lip, nose, cheekbone shapes, designed to provide personalized recommendations. ## Integration Guide * How to Take Photos for AI Face Attributes & Ratio Analyzer * Take a selfie facing forward - Just one clear photo, looking straight into the camera. It is best to let your hair fall naturally, with your entire face visible and nothing covering it. Brush your hair back to reveal your forehead, and make sure you are looking directly ahead to capture a proper front view. - Instead, use the JS Camera Kit to take the photo. Follow the automatic face alignment, lighting guidance, and face size detection to ensure the photo meets the required standards for processing. * 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](#section/overview/File-Specs-and-Errors)** 2. **Upload file using the File API**
Using the ***/s2s/v2.0/file*** API to upload a target user image. - Image Requirements - See details in **[File Specs & Errors](#section/overview/File-Specs-and-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 Attributes & Ratio Analyzer task**
Once the upload is complete, you can select multiple face attributes to analyze using your file ID. Please refer to the **[Inputs & Outputs](#section/overview/Inputs-and-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 retention period is mandotary. A task will be timed out if there is no polling request within the retention period, 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 retention period 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: ![](https://plugins-media.makeupar.com/smb/blog/post/2025-01-15/10a4b980-f571-4d08-8f5d-e3ed48db77aa.jpg) ## Inputs & Outputs * Face Attributes: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/img_Face_Ratio_sec_01_01_enu_79380baa14.jpg) | **Category** | **Subcategory** | **Request Parameter** | **Result Parameter** | **Result Types** | | --- | --- | --- | --- | --- | | **FACE** | Face Shape | `faceShape` | `faceshape` | Triangle, Diamond, Heart, InvTriangle, Oblong, Oval, Round, Square, Unknown | | **AGE & GENDER** | Age | `age` | `agegender.age` | integer | | | Gender | `gender` | `agegender.gender` | female, male, unknown | | **EYES** | Eye Shape | `eyeShape` | `eyelid.left_shape`, `eyelid.right_shape` | Narrow, Round, Almond | | | Eye Size | `eyeSize` | `eyelid.size` | Big, Small, Average | | | Eye Angle | `eyeAngle` | `eyelid.left_angle`, `eyelid.right_angle` | Downturned, Upturned, Average | | | Eye Distance | `eyeDistance` | `eyelid.setting` | Close-set, Wide-Set, Average | | | Eyelid | `eyelid` | `eyelid.left_eyelid`, `eyelid.right_eyelid` | Hooded-lid, Single-lid, Double-lid, Deep-Set | | **BROWS** | Eyebrow Shape | `eyebrowShape` | `eyebrow.left_shape`, `eyebrow.right_shape` | Hard Angled, Soft Angled, Straight, Rounded, Obscured | | | Eyebrow Thickness | `eyebrowThickness` | `eyebrow.left_body_thickness`, `eyebrow.right_body_thickness` | Dense, Sparse, Average, Unknown | | | Eyebrow Distance | `eyebrowDistance` | `eyebrow.gap` | Far-Apart, Close, Average | | | Eyebrow Shortness | `eyebrowShortness` | `eyebrow.left_shortness`, `eyebrow.right_shortness` | Short, Normal | | **LIPS** | Lip Shape | `lipShape` | `lipshape[]` | Bow, Downturned, Full, Heavy Lower Lip, Heavy Upper Lip, Narrow, Round, Thin, Wide, Average | | **NOSE** | Nose Width | `noseWidth` | `nose.width` | Narrow, Broad, Average | | | Nose Length | `noseLength` | `nose.length` | Long, Short, Average | | **CHEEKBONES** | Cheekbones | `cheekbones` | `cheekbone.left`, `cheekbone.right`, `cheekbone.overrall` | Flat Cheekbone, High Cheekbone, Low Cheekbone, Round Cheeks | --- * Face Ratios: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/img_Face_Ratio_sec_01_03_2fe8f06b92.jpg) | **Subcategory** | **Request Parameter** | **Result Parameter** | **Result Types** | **Description** | | --- | --- | --- | --- | --- | | Horizontal Third Ratio | `horizontalThird` | `horizontal_third` | Three-section percentages; Interpretation: Short / Balanced / Long; Golden Ratio: 33% : 33% : 33% | The Face Horizontal Ratio is based on dividing the face into three equal sections: from the hairline to the bottom of the eyebrows, from the bottom of eyebrows to the bottom of the nose, and from the bottom of the nose to the tip of the chin. The golden ratio, or ideal proportion, between the three is 1:1:1.| | Vertical Fifth Ratio | `verticalFifth` | `vertical_fifth` | Five-section percentages; Interpretation (Eye Distance & Eye Width): Narrow / Balanced / Wide; Golden Ratio: 20% : 20% : 20% : 20% : 20% | The Face Vertical Ratio is determined by dividing the face into five sections: the width of one eye, the distance between the eyes, and the space between the outer corners of the eyes to the edges of the face. The golden ration for these proportions is 1:1:1:1:1. | | Face Aspect Ratio | `faceAspectRatio` | `face_aspect_ratio` | `[1, r]`; Interpretation: Short / Balanced / Long; Golden Ratio: 1 : 1.46 | The Face Aspect Ratio is the relationship between the width of the face and its height, ideally following the golden ratio of 1:1.46, thus creating a balanced and aesthetically pleasing appearance. | | Eye Aspect Ratio | `eyeAspectRatio` | `left_eye_aspect_ratio` `right_eye_aspect_ratio` | `[1, r]`; Interpretation: Round / Balanced / Flat; Golden Ratio: 1 : 3 | The Eye Aspect Ratio is the relationship between the height of the eye compared to its width, ideally aligning with the golden ratio of 1:3, ensuring the most aesthetically balanced look. | | Eyebrow Arch Ratio | `eyebrowArch` | `left_eyebrow_arch_to_eyebrow_width` `right_eyebrow_arch_to_eyebrow_width` | `[1, r]`; Interpretation: Short Arch / Balanced / Long Arch; Golden Ratio: 1 : 1.618 | The ideal proportion of the Eyebrow Arch is determined by the shape of the eyebrow itself, where the highest point (the arch) aligns with the golden ratio for an aesthetically pleasing look. | | Eye Height to Eyebrow Distance | `eyeHeightToEyebrowDistance` | `left_eye_height_to_eyebrow_distance` `right_eye_height_to_eyebrow_distance` `overall_eye_height_to_eyebrow_distance` | `[1, r]`; Interpretation: Short / Balanced / Long; Golden Ratio: 1 : 1.618 | The Eye to Eyebrow Distance is the vertical distance from the top of the upper eyelid to the highest point of the eyebrow. Ideally, it would follow the golden ratio of 1.618:1 when compared to the eye height, for the most harmonious balance between the eyes and the brows. | | Nose Aspect Ratio | `noseAspectRatio` | `nose_aspect_ratio` | `[1, r]`; Interpretation: Wide / Balanced / Narrow; Golden Ratio: 1 : 1.618 | The Nose Aspect Ratio is the relationship between the width of the nose and its height, ideally following the golden ratio of 1:1.618. | | Nose Width to Mouth Width | `noseWidthToMouthWidth` | `nose_width_to_mouth_width` | `[1, r]`; Interpretation: Small / Balanced / Large; Golden Ratio: 1 : 1.618 | The Nose Width to Mouth Width ratio is the relationship between the width of the nose and that of the mouth, ideally following the golden ratio of 1:1.618, creating a balanced and aesthetically pleasing appearance. | | Nose to Lip to Chin | `noseToLipToChin` | `nose_to_lip_to_chin` | `[1, r]`; Interpretation: Short / Balanced / Long (lower face length); Golden Ratio: 1 : 1.618 | The Nose to Lip to Chin ratio is a proportion where the distance from the base of the nose to the center of the lip is 1, and the ideal distance from the center of the lip to the chin is 1.618. This golden ratio creates a balanced and harmonious lower face, following the principles of facial symmetry. | | Upper Lip to Lower Lip | `upperLipToLowerLip` | `upper_lip_to_lower_lip` | `[1, r]`; Interpretation: Full Upper / Balanced / Full Lower; Golden Ratio: 1 : 1.618 | The golden ratio of the Upper Lip to the Lower Lip suggests that the thickness of the lower lip should be 1.618 times that of the upper lip. This proportion creates a balanced and aesthetically pleasing look, with the lower lip being slightly fuller than the upper lip. | ---- * Suggestions for How to Shoot: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_Face_Analysis_how_to_shoot_35ca9af08e.png) > **Warning:** The width of the face needs to be greater than 60% of the width of the image. ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Face Attributes & Ratio 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 320 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 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## Unit Consumption * Face Attribute & Ratio Analysis | AI Feature | Unit Consumed | |---|---| | 1~5 Face Structure Features | 10 | | 6~14 Face Structure Features | 20 | | 15~28 Face Structure Features | 30 | --- - [AI Face Lift](https://docs.perfectcorp.com/reference/ai_face_lift.md): # Overview AI Face Lift is a generative AI facial enhancement feature that allows precise and natural facial refinement through adjustable parameters. Instead of applying filters, the system intelligently analyzes facial structure, skin quality, and proportions, then reconstructs the image to produce realistic improvements that preserve the individual's identity. Users can control specific facial areas such as eye bags, cheeks, forehead, overall face shape, and mouth using numeric values from 0 to 100. Each parameter increases the level of enhancement gradually, allowing subtle touch ups or more polished results depending on user preference. All adjustments are designed to remain natural and balanced, avoiding exaggerated or artificial outcomes. AI Face Lift provides flexible, feature level control for creating a refreshed, confident, and professional appearance suitable for social media, profile photos, creative content, or business use. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/01_1_6c0d97eb51.jpg) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/01_2_8c428a25dc.jpg) ## Integration Guide This guide walks you through: Workflow for AI Face Lift API: **Endpoint:** `/s2s/v2.0/task/face-lift` **Authentication Required:** `Authorization: Bearer YOUR_API_KEY` **Workflow Steps:** 1. **Image Upload Preparation:** - Prepare a selfie image for upload. - Call the File API `/s2s/v2.0/file` to obtain the upload URL and associated `file_id`. - Upload the selfie image using the provided upload URL. 2. **Optional Preprocessing For Multiple Faces:** - Preprocess the selfie image if there are more than one face in the image. 3. **Face Lift Effect Setup:** - Begin by selecting suitable face lift parameters. 4. **Initiate AI Task and Obtain Task ID:** - Send the `file_id` along with the chosen effect configuration via an HTTP POST request to `/s2s/v2.0/task/face-lift`. - Await a unique task ID in the response, which identifies this interaction. 5. **Poll Task Status (Continuous Check):** - Use the obtained `task_id` to periodically poll the task status using an HTTP GET request (e.g., `GET /s2s/v2.0/task/face-lift${task_id}`). - Continuously monitor for: - `Task_status = "success"` (process completed). - `Task_status = "error"` (resolve or retry if applicable). - Update the workflow accordingly once the status transitions to success. This structured workflow ensures efficient integration with user inputs, automated monitoring of tasks, and seamless retrieval of results. --- 1. Authentication - Include your API key in the request header using **Bearer Token**: ``` Authorization: Bearer YOUR_API_KEY ``` You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/. 2. Upload an Image You may upload a file directly to the server or provide a valid image URL in the AI task payload. * Upload Endpoint ``` POST /s2s/v2.0/file ``` Alternatively, skip this step if you already have a public image URL. --- 3. Select the target face to be enhanced by preprocessing * Calling the preprocessing API Output detected bounding boxes in pixel coordinate. Use the index of result to create a Face Lift AI task later. ``` POST /s2s/v2.0/task/face-lift/pre-process ``` ``` { "timed": number, "result": [ { "left": number, "top": number, "width": number, "height": number } ] } ``` 4. Create a Face Lift AI Task and Poll for Results Once you have an image and a complete effect payload, create a task. The API processes the request asynchronously. You must poll the task status until it reaches `success` or `error`. * Create Task Endpoint ``` POST /s2s/v2.0/task/face-lift ``` * Polling Endpoint ``` GET /s2s/v2.0/task/face-lift/{task_id} ``` --- ## File Specs & Errors * AI Face Lift Specification **Supported Selfie View** Images must be no larger than 1920 x 1920, contain a clearly visible face of sufficient size exceeding 32 x 32 pixels when the long edge is 640, and be captured with a roll angle within plus or minus 75 degrees and a yaw angle within plus or minus 90 degrees to ensure reliable face detection. ![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_face_reshape_01_85c8ffc055.jpg) --- * Supported Formats & Dimensions | AI Feature | Supported Dimensions | Supported File Size | Supported Formats| | ---- | ---- | ---- | ---- | | AI Face Lift | long side <= 1920 | < 10MB | jpg/jpeg/png | * Error Codes | Error Code | Description | | ---- | ---- | | RUNTIME_ERROR | An unexpected error occurred duface lift runtime | | PHOTO_DETECTION_FAIL | The user photo could not be processed correctly, for example no hand detected | | OBJECT_DETECTION_FAIL | The object photo could not be processed correctly, for example no product detected | | PHOTO_CHECK_INVALID | The pose or size of the user photo is invalid | | INPUT_ERROR | The input file format is incorrect | | INPUT_MAIN_IMAGE_EMPTY | A user image is required | * 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 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Face Lift V1.0 | 1 | --- - [AI Face Reshape](https://docs.perfectcorp.com/reference/ai_face_reshape.md): # Overview The AI Face Reshape API lets you programmatically reshape facial features — eyes, nose, lips, jawline, or the whole face — with pixel‑perfect control. Use it to generate before/after visualisations for rhinoplasty, chin fillers, lip augmentations, brow lifts and any other aesthetic‑treatment workflow. * Rhinoplasty (Nose Job) Our online rhinoplasty simulator offers medical-grade precision adjustments. Unlike generic photo editing apps, it allows for comprehensive simulation of specific details, including the Bridge, Lift, and Wing. With our hyper-realistic previews, clients can clearly visualize and explore their ideal proportions before consulting. * Chin Filler Through our online simulator, you can preview the ideal proportions achieved with chin fillers. Fine-tune Chin Length and Chin Shape to visualize improvements for a receding or short chin. Discover the optimal solution to balance your facial profile before undergoing any dermal filler treatments. * Lip Filler Users can experiment with different volumes and shapes of lip fillers to simulate the appearance of fuller lips, helping them decide on the desired outcome before undergoing the procedure. * Brow Lift Surgery This functionality enables users to preview the results of a brow lift, which involves lifting and reshaping the eyebrows to create a more youthful and rejuvenated appearance. ## Integration Guide This guide walks you through: Workflow for AI Face Reshape API: **Endpoint:** `/s2s/v2.0/file` **Authentication Required:** `Authorization: Bearer YOUR_API_KEY` **Workflow Steps:** 1. **Image Upload Preparation:** - Prepare a selfie image for upload. - Call the File API `/s2s/v2.0/file` to obtain the upload URL and associated `file_id`. - Upload the selfie image using the provided upload URL. 2. **Optional Preprocessing For Multiple Faces:** - Preprocess the selfie image if there are more than one face in the image. 3. **Face Reshape Effect Setup:** - Begin by selecting suitable face reshape parameters of Eye, Face, Lip or Nose. 4. **Initiate AI Task and Obtain Task ID:** - Send the `file_id` along with the chosen effect configuration via an HTTP POST request to `/s2s/v2.0/task/face-reshape`. - Await a unique task ID in the response, which identifies this interaction. 5. **Poll Task Status (Continuous Check):** - Use the obtained `task_id` to periodically poll the task status using an HTTP GET request (e.g., `GET /s2s/v2.0/task/face-reshape/${task_id}`). - Continuously monitor for: - `Task_status = "success"` (process completed). - `Task_status = "error"` (resolve or retry if applicable). - Update the workflow accordingly once the status transitions to success. This structured workflow ensures efficient integration with user inputs, automated monitoring of tasks, and seamless retrieval of results. --- * API Playground Interactively explore and test the API using our official playground: **API Playground:** [http://yce.makeupar.com/api-console/en/api-playground/ai-face-reshape/](http://yce.makeupar.com/api-console/en/api-playground/ai-face-reshape/) --- * Authentication - Include your API key in the request header using **Bearer Token**: ``` Authorization: Bearer YOUR_API_KEY ``` You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/. 1. Upload an Image You may upload a file directly to the server or provide a valid image URL in the AI task payload. * Upload Endpoint ``` POST /s2s/v2.0/file ``` Alternatively, skip this step if you already have a public image URL. --- 2. Prepare an effect template * Preprocessing Output detected bounding boxes in pixel coordinate. Use the index of result to create a Face Reshape AI task later. ``` { "timed": number, "result": [ { "left": number, "top": number, "width": number, "height": number } ] } ``` * Effect Template JSON Schemas ``` { "version": "1.0", "index": 0, "features": {}, "global": { "skin_smooth_strength": 50, "skin_smooth_color_intensity": 50, }, } ``` index: index of detected face from preprocessing. optional, default 0. features: required at least 1, non-zero face reshape parameter, cannot be all zero. skin_smooth_strength: 0~100 skin_smooth_color_intensity: 0~100 * Effect Format - Face default range: -100~100 range of cheekbones and jaws: 0~100 all feature values must not be zero at the same time, at least one feature value must be non-zero ``` { "cheekbones": 0, "jaw": 0, "face_reshape_left": 0, "face_reshape_right": 0, "face_width": 0, "chin_reshape_left": 0, "chin_reshape_right": 0, "chin_length": 0, } ``` - Eye default range: -100~100 all feature values must not be zero at the same time, at least one feature value must be non-zero ``` { "eye_size_left": 0, "eye_size_right": 0, "eye_distance": 0, "eye_angle": 0, "eye_height": 0, "eye_width": 0, } ``` - Nose default range: -100~100 all feature values must not be zero at the same time, at least one feature value must be non-zero ``` { "nose_bridge_width": 0, "nose_lift": 0, "nose_size": 0, "nose_tip": 0, "nose_tip_width": 0, "nose_wing": 0 } ``` - Lip default range: -100~100 all feature values must not be zero at the same time, at least one feature value must be non-zero ``` { "lip_size": 0, "lip_width": 0, "lip_peak": 0, "lip_height_top": 0, "lip_height_bottom": 0, } ``` * Example Payload (ready to send) ``` { "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/face_reshape_01_85c8ffc055.jpg", "version": "1.0", "source": "yco", "features": { "eye_size_left": 80, "eye_size_right": 80, "eye_width": 0, "eye_height": 0, "eye_distance": 0, "eye_angle": 0, "face_reshape_left": 0, "face_reshape_right": 0, "chin_reshape_left": 20, "chin_reshape_right": 20, "chin_length": 0, "face_width": -30, "cheekbones": 0, "jaw": 0, "lip_size": 10, "lip_width": 40, "lip_height_top": 10, "lip_height_bottom": 10, "lip_peak": -10, "nose_size": 30, "nose_lift": -20, "nose_bridge_width": 10, "nose_tip": -10, "nose_wing": 30, "nose_tip_width": 30 }, "global": { "skin_smooth_strength": 50, "skin_smooth_color_intensity": 50 } } ``` 3. Create a Face Reshape AI Task and Poll for Results Once you have an image and a complete effect payload, create a task. The API processes the request asynchronously. You must poll the task status until it reaches `success` or `error`. * Create Task Endpoint ``` POST /s2s/v2.0/task/face-reshape ``` * Polling Endpoint ``` GET /s2s/v2.0/task/face-reshape/{task_id} ``` --- ## File Specs & Errors * AI Face Reshape Specification **Supported Selfie View** A selfie with width and height of a face larger than 1/20 of image width and heigh. Face angle less than 30 degree for pitch, yaw and rolling. ![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_face_reshape_01_85c8ffc055.jpg) **Facial Customization Parameters Guide** | Category | Parameter | Function | Min (-100 / 0) | Max (100) | | -------- | ---------------- | ------------------------------------ | -------------- | ------------ | | Eyes | Size (L/R) | Scales overall size of each eye | Small | Large | | Eyes | Width | Adjusts horizontal span | Narrow | Wide | | Eyes | Height | Adjusts vertical span | Narrow / Flat | Round / Tall | | Eyes | Distance | Adjusts spacing between eyes | Close-set | Wide-set | | Eyes | Angle | Adjusts rotational tilt | Inward tilt | Outward tilt | | Face | Size (L/R) | Scales size of each side of the face | Small | Large | | Face | Chin Shape (L/R) | Adjusts chin contour width | Narrow | Wide | | Face | Chin Length | Adjusts vertical chin length | Short | Long | | Face | Width | Adjusts overall facial width | Narrow | Wide | | Face | Cheekbone | Adjusts cheekbone prominence | Original (0) | Tucked in | | Face | Jaw | Adjusts jawline prominence | Original (0) | Tucked in | | Lips | Size | Scales overall lip volume | Small | Large | | Lips | Width | Adjusts horizontal span | Narrow | Wide | | Lips | Upper Height | Adjusts top lip thickness | Thin | Full | | Lips | Lower Height | Adjusts bottom lip thickness | Thin | Full | | Lips | Peak | Adjusts Cupid's bow sharpness | Smooth | Defined | | Nose | Size | Scales overall nose size | Small | Large | | Nose | Lift | Adjusts vertical position | Low | High | | Nose | Bridge | Adjusts bridge width | Narrow | Wide | | Nose | Tip | Adjusts vertical angle of the tip | Up | Down | | Nose | Wing | Adjusts nostril width | Narrow | Wide | | Nose | Width | Adjusts width of the nose tip | Narrow | Wide | **Note:** *“Left” and “Right” refer to the character's perspective, not the viewer's side of the screen.* --- * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Face Reshape|long side <= 4096|< 10MB|jpg/jpeg/png| * Error Codes | Error Code | Description | | ---- | ---- | | RUNTIME_ERROR | An unexpected error occurred duface reshape runtime | | PHOTO_DETECTION_FAIL | The user photo could not be processed correctly, for example no hand detected | | OBJECT_DETECTION_FAIL | The object photo could not be processed correctly, for example no product detected | | PHOTO_CHECK_INVALID | The pose or size of the user photo is invalid | | INPUT_ERROR | The input file format is incorrect | | INPUT_MAIN_IMAGE_EMPTY | A user image is required | * 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 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Face Reshape V1.0 | 1 | --- - [AI Face Swap](https://docs.perfectcorp.com/reference/ai_face_swap.md): # Overview Using AI Face Swap for hyper-realistic effect with multiple faces supported.​ Our face swap artificial intelligence supports swapping one or multiple faces. Either for creating funny pictures of faces, or need a professional tool, we've got you covered. ## Integration Guide * How to implement AI Face Swap * Step 1: Upload source and reference images 1. Request upload URLs from the API: ``` POST https://yce-api-01.makeupar.com/s2s/v2.0/file Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` Body: ```json { "files": [ { "file_name": "target.jpg", "file_size": 123456, "content_type": "image/jpeg" } ] } ``` 1. The response provides a pre-signed **upload URL** and a `file_id`. 2. Upload your file with an HTTP PUT request to the given URL. 3. Store the `file_id` for later use. Repeat this for both **target** and **reference** images. 2. Upload the actual file to the **upload URL**. --- * Step 2: Pre-process the source and reference images (face detection) 1. Create a pre-process task: ``` POST https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` Body: ```json { "request_id": 1, "payload": { "file_sets": { "src_ids": ["TARGET_FILE_ID"] }, "actions": [ { "id": 0 } ] } } ``` 1. The API returns a `task_id`. 2. Poll task status at: ``` GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process?task_id=TASK_ID ``` 1. When finished, you receive a list of detected faces with bounding boxes. --- * Step 3: Run the face swap task 1. Define which reference image will substitute each source image The `face_mapping` array defines how faces in the **Source Image** are replaced by faces from the **Reference Images**. It acts as a link list connecting detected faces in the source to specific reference images. * Structure Each element in the array is an object containing two properties: | Parameter | Type | Description | | :--- | :--- | :--- | | `position` | `integer` | The index of the face detected in the **Source Image** (e.g., 0, 1, 2). | | `index` | `integer` | The index of the face image in the **Reference Image List** to swap with. | * Logic Rules 1. **Index Mapping:** The `index` maps directly to the order of images provided in your reference list. * `0`: First Reference Image. * `1`: Second Reference Image. 2. **Skipping Swaps:** To skip swapping a specific face detected in the source, set both `index` and `position` to `-1`. 3. **Array Order:** The order of objects in the array should match based on `position`. * Example Use Case **Scenario:** * **Reference List:** 2 images provided (Image A, Image B). * **Source Image:** Contains 3 faces detected (Face 0, Face 1, Face 2). **Goal:** * Swap **Face 0** (Source) with **Image 1** (Reference). * Skip swapping **Face 1** (Source). * Swap **Face 2** (Source) with **Image 0** (Reference). **Configuration:** ```json "face_mapping": [ { "index": 1, // Use the second reference image "position": 0 // Apply to the first detected face in source }, { "index": -1, // Skip swapping "position": -1 // Skip swapping }, { "index": 0, // Use the first reference image "position": 2 // Apply to the third detected face in source } ] ``` 1. Send the main task request: ``` POST https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` Body: ```json { "request_id": 2, "payload": { "file_sets": { "src_ids": ["TARGET_FILE_ID"], "ref_ids": ["REFERENCE_FILE_ID"] }, "actions": [ { "id": 0, "params": { "face_mapping": [ { "index": 0, "position": 0 }, { "index": -1, "position": -1 } ] } } ] } } ``` 1. The response returns a `task_id`. --- * Step 4: Poll task status and retrieve result It’s necessary to implement a timed loop that queries the task status at regular intervals within the allowed polling window. 1. Poll at: ``` GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap?task_id=TASK_ID ``` 2. When `status` is `success`, the response contains a URL for the generated image. 3. Download or display the image from that URL. --- * Step 5: Integrate into your platform * On a **web frontend**, you can directly implement this with JavaScript using fetch or Axios. * On a **backend** (Node.js, Python, Java, PHP, etc.), you can use the same endpoints with standard HTTP libraries. * Implement retry and error handling since the tasks run asynchronously. --- * Debugging Guide 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. **Why are some faces not detected in my source image**
**Why:** Reason: The face must be clearly visible, not covered or obstructed, and large enough within the image
**Solution:** Try taking a photo where the face appears larger and is clearly visible without any covering or obstruction --- ## Inputs & Outputs * Real-world examples: Multiple faces swap sample: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_face_swap_S2_img_04_d4b747a41d.jpg) Single face swap sample: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_face_swap_S2_img_05_8e68faff2c.jpg) * Suggestions for How to Shoot: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png) ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Face Swap|Input and output: the long side must be less than or equal to 4096 pixels|< 10MB|jpg/jpeg/png| * Error Codes | 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 | People count exceeds the maximum limit | | 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_unsupport_ratio | The aspect ratio of the input image is unsupported | | unknown_internal_error | Other internal errors | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Face Swap V1.0 | 1 | --- - [AI Fitzpatrick Skin Type Analysis](https://docs.perfectcorp.com/reference/ai_fitzpatrick_skin_type.md): # Overview ![](https://plugins-media.makeupar.com/smb/blog/post/2026-01-28/webp_a00e88ca-e20a-4082-89c2-9d486b03b8e8.webp) **AI Fitzpatrick Skin Type Analysis** Integrate AI driven Fitzpatrick skin type detection into your applications to classify skin types accurately using camera input. This API enables developers to build personalized skincare, sunscreen, and product recommendation workflows for eCommerce and digital health platforms. **Skin Type Detection** The API uses computer vision and machine learning models to analyze skin characteristics and return a Fitzpatrick classification in a single request. It provides structured, objective data that can be directly consumed by frontend applications, recommendation engines, or clinical systems. The Fitzpatrick Scale, introduced by Dr. Thomas B. Fitzpatrick, defines six skin types based on melanin levels and response to UV exposure, allowing systems to predict tendencies to burn or tan. **Classification Output** The API returns one of six standardized skin types from Type I to Type VI based on UV response modeling. This output enables developers to deliver tailored product recommendations, automate skincare workflows, and enhance personalization logic across user experiences while maintaining consistency and scalability. | Fitzpatrick Scale | Skin Type | Skin Reaction to Sun | | ---- | ---- | ---- | | Type I | White | Almost always burns, never tans | | Type II | Beige | Usually burns, tans minimally | | Type III | Light Brown | Sometimes burns, gradually tans | | Type V | Medium Brown | Rarely burns, tans easily | | Type V | Dark Brown | Very rarely burns | | Type VI | Very Dark Brown | Almost never burns | ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/fitapatrick_skin_type_S_02_enu_5e4343e801.jpg) ![](https://plugins-media.makeupar.com/smb/blog/post/2026-03-10/webp_b9ca4198-1a9e-44df-9551-ac3ad8b65d17.webp) --- ## Integration Guide **1. Capture Image** Capture a front facing image with adequate lighting. Ensure the face is clearly visible and occupies a sufficient portion of the frame. **2. Upload Image** Request upload URLs and file IDs via: ``` POST /s2s/v2.0/file ``` Upload the image using the returned URL. Alternatively, provide a publicly accessible image URL hosted on your own storage. **3. Optional Preprocessing** ``` POST /s2s/v2.0/task/fitzpatrick-scale-analyzer/pre-process ``` Use this step when the image contains multiple faces or when explicit target selection is required. For single face images, this step can be skipped if default indexing is sufficient. **4. Retrieve Preprocess Result** ``` GET /s2s/v2.0/task/fitzpatrick-scale-analyzer/pre-process ``` Configure a [webhook](/develop/webhook.md) or implement polling to retrieve task results. With webhooks, your application receives automatic notifications when the task is completed. With polling, your system repeatedly calls the task endpoint until the status changes from running to success or error. **5. Execute Analysis Task** ``` POST /s2s/v2.0/task/fitzpatrick-scale-analyzer ``` Submit the task using file IDs or image URLs as input. The response returns a task_id for tracking and retrieving the result. **6. Retrieve Task Result** ``` GET /s2s/v2.0/task/fitzpatrick-scale-analyzer/{task_id} ``` Use the task ID to track status and obtain results. [Webhooks](/develop/webhook.md) can be configured to receive asynchronous notifications on task completion with a success or error status. Polling is also supported by repeatedly calling the task endpoint until the status is updated from running to success or error. Usage is only charged when the task completes successfully. --- ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | | AI Fitzpatrick Skin Type Analysis | The length of the longer side shall not exceed 4096 pixels, and the length of the shorter side shall be no less than 320 pixels. | < 10MB | jpg/jpeg | * Error Codes |Error Code|Description| | ---- | ---- | | error_below_min_image_size | Source image dimensions must be at least 320 pixels. | |error_face_position_invalid|Your face needs to be fully visible in the image, without any parts cut off| |error_face_position_too_small|The face in your photo is too small to analyze properly| |error_face_position_out_of_boundary|Your face is either too large or partially outside the edges of the photo| |error_insufficient_lighting|The lighting is too dim, which makes analysis difficult| |error_face_angle_invalid|Your face angle isn't quite right. For front-facing shots, keep your head within 10 degrees of straight. For side-facing shots, the angle should be more than 15 degrees| * 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 | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Fitzpatrick Skin Type Analysis V1.0 | 10 | --- - [AI Hair Color Virtual Try-On](https://docs.perfectcorp.com/reference/ai_hair_color.md): # Overview 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. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_color_s2_poster_dt_v2_49198cabc0.png) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/01_1_1_8365c3b503.jpg) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/01_2_1_abfcdb7eba.jpg) ## File Specs & Errors * 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 >= 320px, height >= 320px) |error_exceed_max_image_size|the size of the source image is larger than maximum (expect: width < 1920px, height < 1080px) * 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 | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Hair Color Virtual Try-On V1.0 | 1 unit for Full Mode
1 unit for Ombre Mode | --- - [AI Hair Density Detection](https://docs.perfectcorp.com/reference/ai_hair_density_detection.md): # Overview AI Hair Density Detection delivers a fast, professional, photo‑based assessment that accurately classifies hair density into four levels by evaluating scalp visibility and hair distribution patterns, providing trichoscopy‑inspired insights without physical tools and empowering businesses to offer expert‑level personalization at scale from a single uploaded image. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_hair_density_S3_02_b34f2db2ce.jpg) ## Integration Guide * How to Take Photos for AI Hair Density Detection * Take a selfie - Please face the camera directly with proper lighting, then lower your head to a 45‑degree angle. Keep your hair untied and ensure your entire hairline is clearly visible. ![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_popup_step_animated_02.aadf7a34.png) - Instead, use the JS Camera Kit to take a photo. * How to Detect Hair Density by AI * Using the ***/s2s/v2.0/file*** API, please upload the following assets: - Your selfie photo. * Execute AI task ***/s2s/v2.0/task/hair-density-detection***
Run the detection task by sending one front facing 45 degree lower selfie image. Use it's file ID as the source input for the AI. * 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/hair-density-detection' 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. ## Hair Density Classification |Thumbnail|Hair Density Classification|Description| | ---- | ---- | ---- | |![](https://d3ss46vukfdtpo.cloudfront.net/static/media/dt_classification_LV01.5097a6c2.png)|Level 1
Extremely Low Density|Hair appears significantly sparse, with visible scalp across a large area. Hair fibers are thin and coverage is minimal.| |![](https://d3ss46vukfdtpo.cloudfront.net/static/media/dt_classification_LV02.7966983d.png)|Level 2
Low Density|Noticeable thinning with clear scalp visibility, especially at the crown and part lines. Hair may lack volume and body.| |![](https://d3ss46vukfdtpo.cloudfront.net/static/media/dt_classification_LV03.c49dbfb7.png)|Level 3
Medium Density|Scalp is partially visible under direct light, but hair still maintains moderate volume and coverage. Hair may feel finer but remains relatively healthy.| |![](https://d3ss46vukfdtpo.cloudfront.net/static/media/dt_classification_LV04.e467f2aa.png)|Level 4
High Density|Hair looks full and thick, with minimal to no scalp visibility. Hair strands are closely packed, providing rich volume and natural coverage.| * Suggestions for How to Shoot ![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/icon_S2_step1_20d0a161da.png "Suggestions for How to Shoot") ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_hair_density_S1_02_f60369b14d.jpg) ## File Specs & Errors * Supported Formats & Dimensions |Type|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Hair Density Detection|The image must be at least 100 pixels wide and tall, and no more than 4096 pixels in either dimension. If one side of your image is longer than 1080 pixels, it will be resized automatically to fit within that limit for analysis.|< 10MB|jpg/png| * Error Codes |Error Code|Description| | ---- | ---- | |error_below_min_image_size|If your image is smaller than 100 pixels in width or height, it's too small to use| |error_face_position_invalid|Your face needs to be fully visible in the image, without any parts cut off| |error_face_position_too_small|The face in your photo is too small to analyze properly| |error_face_position_out_of_boundary|Your face is either too large or partially outside the edges of the photo| |error_insufficient_lighting|The lighting is too dim, which makes analysis difficult| |error_face_angle_invalid|Your face angle isn't quite right. For front-facing shots, keep your head within 10 degrees of straight. For side-facing shots, the angle should be more than 15 degrees| * 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 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Hair Density Detection V1.0 | 1 | --- - [AI Hair Extension Virtual Try-On](https://docs.perfectcorp.com/reference/ai_hair_extension.md): # Overview Discover Your Perfect Hair Extension Match with AI​ Experiment with a variety of lengths—from long to extra-long—styles, colors, and bangs, all from the comfort of your device. No more guessing games—see exactly how each hair extension style looks on you with the advanced Generative AI. Make informed styling decisions before committing to a new look.​ With the advanced Hair Extension Try-On, which naturally blends with your current hair length, it’s the perfect time to experiment with super-long styles. Use case: ![AI Hair Extension](https://bcw-media.s3.ap-northeast-1.amazonaws.com/YCE_web_Hair_Extension_Filter_S2_img_07_098b6e08c4.jpg "AI Hair Extension") ![AI Hair Extension](https://bcw-media.s3.ap-northeast-1.amazonaws.com/YCE_web_Hair_Extension_Filter_S1_img_01_eab88fe3e2.jpg "AI Hair Extension") Suggestions for How to Shoot: ![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png "Suggestions for How to Shoot") --- ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Hair Extension|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 |error_bald_image |Input hairstyle is bald --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Hair Extension Virtual Try-On V1.0 | 1 | --- - [AI Hair Frizziness Detection](https://docs.perfectcorp.com/reference/ai_hair_frizziness_detection.md): # Overview 180° Full View Hair Frizz Analysis with Just 3 Photos Our AI Frizzy Hair Analyzer delivers precise hair frizz analysis in seconds by simply uploading 3 photos—front, left, and right views of the hair. This efficient process delivers accurate results in seconds, enabling businesses to offer tailored hair solutions and defrizz hair products based on hair frizz levels, without the need for time-consuming in-person consultations, complicated hair quizzes, or specialized hardware installations. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_frizzy_S_02_enu_b80c238858.jpg) ## Integration Guide 1. **Upload a Selfie** You can provide the source image in one of two ways: - **Use an Existing Public Image URL** Instead of uploading, you may supply a publicly accessible image URL directly when initiating the AI task. - **Upload via File API** Use the endpoint: ``` POST /s2s/v2.0/file ``` 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. 2. **Run an AI Task to Obtain a Task ID** Execute the AI task using /s2s/v2.0/task/hair-frizziness-detection. For the target user image, provide either ``src_file_url`` or ``src_file_id``. And a stype ``template_id`` to apply and obtain a ``task_id``. 3. **Poll to Check the Status of a Task Until It Succeeds or Fails** Use the ``task_id`` to monitor the task status by polling GET /s2s/v2.0/task/hair-frizziness-detection to retrieve the current engine status. Until the engine completes the task, the status will remain as running, and no units will be consumed during this stage. You can also implement a webhook to receive notifications when an AI task succeeds or fails. Refer to the **[Webhook](../../../../develop/webhook)** section for details. > **Warning:** Polling to check the status of a task within its retention period is mandatory. A task will time out if there is no polling request within the retention period, even if the task is processed successfully. Your units will still be consumed. > **Warning:** You will receive an InvalidTaskId error if you check the status of a timed-out task. Therefore, once you run an AI task, you must poll to check the status within the retention period until the status becomes either success or error. 4. **Retrieve the Result of an AI Task Once Successful** The task status will change to success after the engine processes your input file and generates the resulting image. You will receive a URL for the processed image. ## Inputs & Outputs * Input format ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_frizzy_step_01_ac5c651ea4.png) Upload 3 photos - front, left, and right views of the hair. You can utilize the JS Camera Kit to implement a Javascript camera module to take 3 qualified photos. * Output format AI Frizzy Hair Analyzer assesses hair types and identifies 4 distinct degrees of hair frizz - from smooth hair to extremely frizzy hair, offering precise insights into hair frizz condition. | **Mapping (0–3)** | **Term** | **Description** | | ----------------- | ------------------- | --------------------------------------------------------- | | 0 | Not Frizzy | Hair appears smooth with minimal or no visible frizz. | | 1 | Slightly Frizzy | Light frizz visible; mild surface texture irregularities. | | 2 | Frizzy | Noticeable frizz across hair; clear texture disruption. | | 3 | Extreme Frizzy | Strong, widespread frizz; highly irregular hair texture. | ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_frizzy_S_01_enu_fcd10905ff.jpg) * Sample Output ```json { "mapping": 1, // number; the key to map of result, alternatives: [0, 1, 2, 3] "term": "Slightly Frizzy" // string; 1-1 map to the "mapping", alternatives: ["Not Frizzy", "Slightly Frizzy", "Frizzy", "Extreme Frizzy"] } ``` ## File Specs & Errors * Supported Formats & Dimensions |Type|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Hair Frizziness Detection|The image must be at least 320 pixels wide and tall, and no more than 4096 pixels in either dimension. If one side of your image is longer than 1080 pixels, it will be resized automatically to fit within that limit for analysis.|< 10MB|jpg/png| * Error Codes |Error Code|Description| | ---- | ---- | |error_mismatch_image_size|Make sure all your face photos (front, left, and right) are the same size| |error_below_min_image_size|If your image is smaller than 320 pixels in width or height, it's too small to use| |error_face_position_invalid|Your face needs to be fully visible in the image, without any parts cut off| |error_face_position_too_small|The face in your photo is too small to analyze properly| |error_face_position_out_of_boundary|Your face is either too large or partially outside the edges of the photo| |error_insufficient_lighting|The lighting is too dim, which makes analysis difficult| |error_face_angle_invalid|Your face angle isn't quite right. For front-facing shots, keep your head within 10 degrees of straight. For side-facing shots, the angle should be more than 15 degrees| * 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 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Hair Frizziness Detection V1.0 | 2 | --- - [AI Hair Length Detection](https://docs.perfectcorp.com/reference/ai_hair_length_detection.md): # Overview AI Hair Length Measurement offers haircare brands and salons a quick solution to analyze and measure hair length, enabling informed decisions for personalized products and services. Our AI is meticulously trained on a vast dataset of diverse images to ensure precise and reliable hair length detection. By analyzing thousands of images of various hair types and styles, it precisely identifies and categorizes five distinct hair lengths, from above-the-ear to mid-back, with exceptional accuracy. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_length_S1_01_enu_b03bd393af.jpg) ## Integration Guide * How to Take Photos for AI Hair Length Detection * 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 Hair Length by AI * Using the ***/s2s/v2.0/file*** API, please upload the following assets: - Your selfie photo. * Execute AI task ***/s2s/v2.0/task/hair-length-detection***
Run the hair-length detection task by sending one front facing selfie image. Use it's file ID as the source input for the AI. * 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/hair-length-detection' 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. ## Hair Length Classification |Thumbnail|Hair Length Classification|Description| | ---- | ---- | ---- | |![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_above_the_ears.b41525da.png)|Above-Ear Length|Hair that falls just above the ear, offering a sleek and stylish look that frames the face nicely.| |![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_ear_length.0740b805.png)|Ear-Length|Hair that reaches the earlobe, providing a chic and versatile style that's easy to maintain.| |![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_short_hair.d7f24ddb.png)|Short Hair|Hair that is cut above the shoulders, ideal for a fresh, modern look that’s both bold and low-maintenance.| |![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_above_chest.1b624c17.png)|Medium-Length|Hair that falls around the collarbone, offering a balanced style that’s perfect for both updos and loose waves.| |![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_longer_hair.7fbcc9d0.png)|Long Hair|Long hair that exudes elegance, providing a classic appearance with numerous styling options.| * Result Arguments * term: result is a string showing the detected hair length type. Here lists all the possible result strings in an array: ```json ["above the ears", "ear length", "ear length or longer", "short hair", "short hair or longer", "above chest", "above chest or longer", "long hair"] ``` * Suggestions for How to Shoot ![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Hair%20Length%20Detection_how%20to%20shoot.png "Suggestions for How to Shoot") ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Skin%20Analysis_camera.png) ## File Specs & Errors * Supported Formats & Dimensions |Type|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Hair Length Detection|The image must be at least 320 pixels wide and tall, and no more than 4096 pixels in either dimension. If one side of your image is longer than 1080 pixels, it will be resized automatically to fit within that limit for analysis.|< 10MB|jpg/png| * Error Codes |Error Code|Description| | ---- | ---- | |error_below_min_image_size|If your image is smaller than 320 pixels in width or height, it's too small to use| |error_face_position_invalid|Your face needs to be fully visible in the image, without any parts cut off| |error_face_position_too_small|The face in your photo is too small to analyze properly| |error_face_position_out_of_boundary|Your face is either too large or partially outside the edges of the photo| |error_insufficient_lighting|The lighting is too dim, which makes analysis difficult| |error_face_angle_invalid|Your face angle isn't quite right. For front-facing shots, keep your head within 10 degrees of straight. For side-facing shots, the angle should be more than 15 degrees| * 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 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Hair Length Detection V1.0 | 2 | --- - [AI Hair Type Detection](https://docs.perfectcorp.com/reference/ai_hair_type_detection.md): # Overview Imagine having an AI hair expert in your pocket. Our tech dives into your hair's texture, thickness, and curl pattern, picking from ten unique curl shapes and sorting them into nine clear types, from Straight to Super Kinky. You get a full hair profile, and brands can use those insights to deliver spot-on product recommendations and tips just for you. ## Integration Guide * How to Take Photos for AI Hair Type Detection * Take 3 Photos from left, front facing to right. - Just snap three quick selfies. One facing straight ahead, one turning about 45 degrees to the left, and one turning 45 degrees to the right. We're trying to catch the full look of your hair from all sides. Make sure your whole face and the upper boundary of your hair are clearly visible in each photo. Your face should take up around 50% to 80% of the image width. Not too small, not too close. That way, it's sharp enough for analysis. When you turn for the side shots, rotate your head left and right like you're saying 'no' (that's called yaw rotation). Keep your head level with no tilting up, down, or sideways. Skip any back or top-down angles because those wont work for us. - You can utilize the JS Camera Kit to snap photos. Make sure your hair is not tied up and let it hang in front of your chest. Turn your head to the right and hold still, and turn to the left to get 3 images to be analyzed. * How to Detect Hair Type by AI * Using the ***/s2s/v2.0/file*** API, please upload the following assets: - Photos from the front, the right side, and the left side. * Execute AI task ***/s2s/v2.0/task/hair-type-detection***
Run the hair-type detection task by sending in three images: one from the front, one from the right side, and one from the left side. Use their file IDs as the source inputs for the AI. * 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/hair-type-detection' 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. ## Hair Type Classification |Category|Thumbnail|Hair Type Classification|Description| | ---- | ---- | ---- | ---- | |1|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t1.b19d4657.jpg)|Straight| This hair type is characterized by strands that lack natural curls and typically fall straight from the root to the tip| |2A|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t2A.351ef0a6.jpg)|Slight Wavy| This hair type features subtle, delicate waves with a smooth and tousled texture, but lacks volume at the roots| |2B|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t2B.daac62f4.jpg)|Medium Wavy| This hair type that showcases natural S-shaped waves that typically begin in the middle of the hair shaft and delicately hug the head, creating a subtle and sophisticated dimension| |2C|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t2C.10ef2132.jpg)|Thick Wavy|The waves in this hair type are characterized by a coarse texture and are shaped like the letter "S", starting at the root and continuing down the length of the hair. This hair type is prone to frizz| |3A|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t3A.073b6767.jpg)|Loose Curls|These curls are big, relaxed, and bouncy, and have a noticeable sheen from roots to ends| |3B|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t3B.06bf109b.jpg)|Medium Curls|This hair type consists of coarse, springy ringlets that are prone to frizz| |3C|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t3C.9091ea1e.jpg)|Tight Curls|These curls boast a dense and compact corkscrew shape, lending them plenty of volume| |4A|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t4A.cf742771.jpg)|Kinky Soft|This hair type is characterized by tightly packed, springy S-shaped coils| |4B|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t4B.4a6300fe.jpg)|Coily|Densely packed coils tightly wound into sharp, zigzag angles| |4C|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t4C.4ed5a7f8.jpg)|Extremely Coily|This hair type is characterized by tight, fluffy coils that are more susceptible to breakage| * Result Arguments * mapping: result is a string showing the detected hair type category. Here lists all the possible result strings in an array: ```json ["1 to 2a", "2a to 2b", "2b to 2c", "2c to 3a", "3a to 3b", "3b to 3c", "3c to 4a", "4a to 4b", "4b to 4c"] ``` * term: a one-to-one mapping string between hair type categories and their classifications. Here lists all the possible result strings in an array: ```json ["Straight to Slight Wavy", "Slight to Medium Wavy", "Medium to Thick Wavy", "Thick Wavy to Loose Curls", "Loose to Medium Curls", "Medium to Tight Curls", "Tight Curls to Kinky Soft", "Kinky Soft to Coily", "Coily to Extremely Coily"] ``` * Suggestions for How to Shoot ![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Hair%20Type%20Detection_how%20to%20shoot.png "Suggestions for How to Shoot") ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Skin%20Analysis_camera.png) ## File Specs & Errors * Supported Formats & Dimensions |Type|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Hair Type Detection|The image must be at least 320 pixels wide and tall, and no more than 4096 pixels in either dimension. If one side of your image is longer than 1080 pixels, it will be resized automatically to fit within that limit for analysis.|< 10MB|jpg/png| * Error Codes |Error Code|Description| | ---- | ---- | |error_mismatch_image_size|Make sure all your face photos (front, left, and right) are the same size| |error_below_min_image_size|If your image is smaller than 320 pixels in width or height, it's too small to use| |error_face_position_invalid|Your face needs to be fully visible in the image, without any parts cut off| |error_face_position_too_small|The face in your photo is too small to analyze properly| |error_face_position_out_of_boundary|Your face is either too large or partially outside the edges of the photo| |error_insufficient_lighting|The lighting is too dim, which makes analysis difficult| |error_face_angle_invalid|Your face angle isn't quite right. For front-facing shots, keep your head within 10 degrees of straight. For side-facing shots, the angle should be more than 15 degrees| * 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 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Hair Type Detection V1.0 | 2 | --- - [AI Hair Volume Virtual Try-On](https://docs.perfectcorp.com/reference/ai_hair_volume.md): # Overview Enhance Your Look with Fuller, More Voluminous Hair Instantly!​ Add natural volume to fine or thinning hair. Seamlessly fill gaps or add hair with AI. Works for all hair types: straight, curly, thin. Perfect for dating profiles, resumes & more. Our AI tool helps you achieve perfect hair volume and density in all your photos, whether for personal, professional, or social use. Say goodbye to bad hair days in pictures and hello to fresh, voluminous hair every time. Use case: ![AI Hair Volume Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/YCE_web_Hair_Volume_Filter_S4_img_01_836436ca00.jpg "AI Hair Volume Generator") ![AI Hair Volume Generator](https://plugins-media.makeupar.com/smb/blog/post/2024-08-26/51eadc51-aaa7-4ebc-ac78-e389be5e16b0.jpg "AI Hair Volume Generator") Suggestions for How to Shoot: ![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png "Suggestions for How to Shoot") --- ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Hair Volume 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/png| * 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 |error_bald_image |Input hairstyle is bald --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Hair Volume Virtual Try-On V1.0 | 2 | --- - [AI Hair Style Virtual Try-On](https://docs.perfectcorp.com/reference/ai_hairstyle.md): # Overview 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! ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_style_v3_poster_bb1c7aad10.jpg) --- ## Integration Guide * API Playground You can use the API Playground to test the AI Hairstyle Generator feature. This allows you to experiment with your ideas and gain a better understanding of the try-on process. Access the API Playground at: --- * API Workflow This guide walks you through: Workflow for AI Hairstyle Generator API: **Endpoint:** `/s2s/v2.1/task/hair-transfer` **Authentication Required:** `Authorization: Bearer YOUR_API_KEY` **Workflow Steps:** 1. **Image Upload Preparation:** - The process begins with preparing a selfie. 2. **List predefined templates or using your own reference photo** **Choose Reference Source** You have two options for styling references: | Option | Use Case | Implementation Tip | |-------|-----------|---------------------| | **Predefined Templates** (`template_id`) | Quick start (e.g., "Curly Bob", "Side-Swept Bangs") | Call `/s2s/v2.1/task/template/hair-transfer` and pick `template_id`. | | **Custom Reference Image** (`ref_file_url` / `ref_file_id`) | User uploads own style photo or uses provided image link | Upload via same file API;
Use `ref_file_url` if your reference image is already hosted online. | 3. **Initiate AI Task and Obtain Task ID:** - Send the uploaded image along with the style configuration via an HTTP POST request to `/s2s/v2.0/file`. - Await a unique task ID in the response, which identifies this interaction. 4. **Poll Task Status (Continuous Check):** - Use the obtained `task_id` to periodically poll the task status using an HTTP GET request (e.g., `GET /task/${task_id}`). - Continuously monitor for: - `Task_status = "success"` (process completed). - `Task_status = "error"` (resolve or retry if applicable). - Update the workflow accordingly once the status transitions to success. This structured workflow ensures efficient integration with user inputs, automated monitoring of tasks, and seamless retrieval of results. --- * Authentication - Include your API key in the request header using **Bearer Token**: ``` Authorization: Bearer YOUR_API_KEY ``` You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/. --- * API Usage Guide This guide explains how to upload images, prepare reference images, and create virtual try-on tasks using the AI Hairstyle Generator API. *** * Step 1. Upload a File Using the File API or provide a valid image URL Use the **File API** (`/s2s/v2.0/file`) to upload a target user image. Alternatively, skip step 1 to 3 if you already have a public image URL. **Image Requirements:** * Upload a high-resolution selfie photo. * Ensure the photo clearly shows the entire body. * Avoid backgrounds with multiple people or distracting objects. **Example Request:** ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/file \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "files": [ { "content_type": "image/jpg", "file_name": "selfie_01_3dbd1b6683.jpg", "file_size": 547541 } ] }' ``` *** * Step 2. Retrieve File API Response The response includes: * `file_id` for creating an AI task. * `requests.url` for uploading the actual image file. **Sample Response:** ```json { "status": 200, "data": { "files": [ { "content_type": "image/jpg", "file_name": "full_body_photo_01_3dbd1b6683.jpg", "file_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud", "requests": [ { "method": "PUT", "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...", "headers": { "Content-Length": "547541", "Content-Type": "image/jpg" } } ] } ] } } ``` *** * Step 3. Upload Image to Provided URL Use the `requests.url` from the File API response to upload the image: ```bash curl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \ --header 'Content-Type: image/jpg' \ --header 'Content-Length: 547541' \ --data-binary @'./full_body_photo_01_3dbd1b6683.jpg' ``` *** * Step 4. Prepare a Reference Image * 4.1 Fetch Predefined Image Templates Use the **Template API** (`/s2s/v2.1/task/template/hair-transfer`) to retrieve a list of predefined reference templates: ```bash curl --request GET \ --url 'https://yce-api-01.makeupar.com/s2s/v2.1/task/template/hair-transfer?page_size=20&starting_token=73a3c9e69b89' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` * 4.2 Upload a Reference Image You can: * Upload an reference image using the File API (`/s2s/v2.0/file`), or * Provide a valid image URL. **Supported Images:** * Another selfie photo as an reference image. Refer to **[File Specs and Errors](#section/overview/File-Specs-and-Errors)** for detailed specifications. *** * Step 5. Create an AI Hairstyle Generator Task Use the **AI Task API** (`/s2s/v2.1/task/hair-transfer`) to create a virtual try-on task. **Parameters:** * For the user image: `src_file_id` or `src_file_url`. * For the reference image: `ref_file_id`, `ref_file_url`, or `template_id`. **Example Request:** ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.1/task/hair-transfer \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/selfie_03_cccd5d4803.jpeg", "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/style_reference_full_body_01_5a000d999f.png" }' ``` **Sample Response:** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` *** * Step 6. Poll for Task Result Use the task ID to check the status: ```bash curl --request GET \ --url https://yce-api-01.makeupar.com/s2s/v2.1/task/hair-transfer/ \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' ``` *** * Step 7. Retrieve Result A successful response includes a download URL for the result image: ```json { "status": 200, "data": { "error": null, "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..." }, "task_status": "success" } } ``` Invalid API Key error response: ```json { "status": 401, "error": "Unauthorized", "error_code": "InvalidAccessToken" } ``` --- Use cases: Use case: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_style_v1_video_08513beb46.jpg) Suggestions for How to Shoot: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png) ## File Specs & Errors * 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 * 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 | --- ## FAQ **Q: Can I try on a custom hairstyle?** **A:** Absolutely, you can try on a custom hairstyle using your own reference photo. The AI Hairstyle Generator supports two methods for specifying the desired hairstyle: 1. **Upload your own reference image** You may upload a high-resolution selfie or style photo (e.g., someone wearing the target hairstyle) via the File API (`/s2s/v2.0/file`). After uploading, use the returned `file_id` or public URL as the reference source when creating the AI task. 2. **Provide a valid image URL** If your reference image is already hosted online (e.g., on your own server or CDN), you can directly supply its HTTPS URL in the request body under the field `ref_file_url`. When submitting the task via `/s2s/v2.1/task/hair-transfer`, include either: - `src_file_id` (your selfie) and `ref_file_id` (your custom reference image), or - `src_file_url` and `ref_file_url`. Ensure both images meet the specified requirements: - Supported format: JPG/JPEG only - File size under 10 MB - Long side ≤ 1024 pixels - Face width ≥ 128 pixels - Head pose within allowed range (pitch: −10° to +10°, yaw: −45° to +45°, roll: −15° to +15°) - Single face visible, full frontal view with clear hair visibility This flexibility allows you to apply virtually any hairstyle from a photo reference, not just predefined templates. --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Hair Style Virtual Try-On V2.0 | 1 unit for Preset Mode
2 units for Custom Mode | | AI Hair Style Virtual Try-On V2.1 | 2 units for Preset Mode
2 units for Custom Mode | --- - [AI Hat Virtual Try-On](https://docs.perfectcorp.com/reference/ai_hat.md): # Overview Step into the future of fashion with our Hyper-Realistic AR Try-On for Headwear, powered by cutting-edge AI technology. This innovative solution transforms online shopping into an immersive experience, allowing customers to virtually try on headwear with unmatched precision and realism. From instant style discovery to true-to-life visualization, our AR technology ensures every hat and headband looks and feels authentic. Helping shoppers find their perfect fit and style before they buy. Elevate engagement, boost confidence, and redefine the way customers interact with your products. ## Integration Guide This guide walks you through: * **Endpoint:** `/s2s/v2.0/task/hat` * **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY` * **Workflow:** 1. **Prepare a selfie image:** Uploading an image or providing a valid image URL of yourself as the virtual try-on target. 1. **Prepare a hat image:** Upload a hat product image or a photo of a person wearing hat. 1. **Select a style and a gender:** Select a preferred style and the gender you wish to visualize. 1. **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response. 1. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `"success"` or `"error"`. --- * Authentication - Include your API key in the request header using **Bearer Token**: ``` Authorization: Bearer YOUR_API_KEY ``` You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/. --- * AI Hat API Usage Guide This guide explains how to upload images, prepare reference hat, and create virtual try-on tasks using the AI Hat API. *** * Step 1. Prepare a Selfie Image You can: * Upload a selfie image using the File API (`/s2s/v2.0/file`), or * Provide a valid image URL. * Step 1.1 Upload a File Using the File API Use the **File API** (`/s2s/v2.0/file`) to upload a target user image. **Image Requirements:** * Upload a selfie photo. * Ensure the photo clearly shows the upper body. * Avoid backgrounds with multiple people or distracting objects. **Example Request:** ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/file \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "files": [ { "content_type": "image/jpg", "file_name": "selfie_photo_01_3dbd1b6683.jpg", "file_size": 547541 } ] }' ``` *** * Step 1.2. Retrieve File API Response The response includes: * `file_id` for creating an AI task. * `requests.url` for uploading the actual image file. **Sample Response:** ```json { "status": 200, "data": { "files": [ { "content_type": "image/jpg", "file_name": "selfie_photo_01_3dbd1b6683.jpg", "file_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud", "requests": [ { "method": "PUT", "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...", "headers": { "Content-Length": "547541", "Content-Type": "image/jpg" } } ] } ] } } ``` *** * Step 1.3. Upload Image to Provided URL Use the `requests.url` from the File API response to upload the image: ```bash curl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \ --header 'Content-Type: image/jpg' \ --header 'Content-Length: 547541' \ --data-binary @'./selfie_photo_01_3dbd1b6683.jpg' ``` *** * Step 2. Prepare a Reference Hat Image You can: * Upload a hat image using the File API (`/s2s/v2.0/file`), or * Provide a valid image URL. **Supported Hat Images:** * A hat product image. * A photo of a person wearing hat. Refer to **[File Specs and Errors](#section/overview/File-Specs-and-Errors)** for detailed specifications. *** * Step 3. Create an AI Task Select a preferred style and the gender you wish to visualize. Use the **AI Task API** (`/s2s/v2.0/task/hat`) to create a virtual try-on task. **Parameters:** * For the user image: `src_file_id` or `src_file_url`. * For the hat image: `ref_file_id`, or `ref_file_url`. **Example Request:** ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/hat \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "src_file_url": "https://example.com/selfie.jpg", "ref_file_url": "https://example.com/accessory.jpg", "gender": "female", "style": "random" }' ``` **Sample Response:** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` *** * Step 4. Poll for Task Result Use the task ID to check the status: ```bash curl --request GET \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/hat/SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' ``` *** * Step 5. Retrieve Result A successful response includes a download URL for the result image: ```json { "status": 200, "data": { "error": null, "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..." }, "task_status": "success" } } ``` Invalid API Key error response: ```json { "status": 401, "error": "Unauthorized", "error_code": "InvalidAccessToken" } ``` --- ## File Specs & Errors * AI Hat Virtual Try-On Specification * Image Requirements | Type | Minimum Resolution | Notes | | ------ | ------------------ | ----- | | Selfie | 512 × 512 | Face visible, head-to-chest preferred | | Hat | 512 × 512 (product)
800 × 800 (worn) | Clear, unobstructed hat view | **Supported Hat Image** * Product Image Requirements * Minimum resolution: 512 × 512 pixels * Only one product per image * The product should cover more than 25% of the image height ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/026_thumb_dca334af3c.jpg) * Worn Image Requirements * Minimum resolution: 800 × 800 pixels * Single Item Requirement: The model must wear exactly one item. Multiple items or accessories are not permitted. * Coverage Ratio: The worn item must occupy more than 20% of the total image height. This ensures the item is clearly visible and prominent within the frame. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/010_thumb_51490eebeb.jpg) **Supported Selfie View** * Recommended image resolution: at least 512 × 512 pixels. * Recommended face coverage: more than 15% of the image height. * Single Subject Requirement: The image must contain exactly one human subject. No additional people or partial figures are allowed. * Face Visibility: The subject's face must be fully visible without obstruction. Hair, accessories, or objects should not cover key facial features. * Framing: The image must include at least a head shot, covering the area from the top of the head to the chest. A half-body shot (head to waist) is preferred for optimal analysis. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/lashana_lynch_thumb_7a900b811e.jpg) **Try-on Styles** * There are five predefined styles for generating the virtual try-on output: "style_sporty_casual" "style_urban_fashion" "style_vacation_casual" "style_warm_cozy" and "style_bohemian". You can specify this style parameter when creating an AI task or allow the system to select a style at random by default. ![style_vacation_casual](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/5f42385b_6aef_44cd_b576_2ec10e31305d_824cc2019b.jpg) --- * Supported Formats & Dimensions | AI Feature | Supported Dimensions | Supported File Size | Supported Formats | | ---- | ---- | ---- | ---- | | AI Hat Virtual Try-On | Input: long side <= 4096
Output: 896 x 1152 | < 10MB | jpg/jpeg/png/heic | * Error Codes | Error Code | Description | | ------------------------------ | -------------------------------------------- | | error\_download\_image | Failed to download source or reference image | | error\_inference | Inference pipeline error | | error\_no\_face | No face detected in source image | | error\_nsfw\_content\_detected | NSFW content detected in result | | exceed\_max\_filesize | File size exceeds 10 MB | | invalid\_parameter | Invalid gender or style value | | unknown\_internal\_error | Other internal errors | * Environment & Dependency | Sample Code Language / Tool | Recommended Runtime Versions | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (modern TLS/HTTP support)
- jquery >= 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 | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Hat Virtual Try-On V2.0 | 2 | --- - [AI Headshot Generator](https://docs.perfectcorp.com/reference/ai_headshot_generator.md): # Overview Transform your photos into stunning professional headshots with our AI Headshot Generator. Elevate your headshots quickly and effectively using our powerful AI tools designed to deliver professional-quality results. * Variety of Styles: From polished LinkedIn headshots and professional business headshots to creative model headshots, our AI headshot generator helps you select the perfect look to suit your needs. * Professional Results: Leveraging AI to ensure your headshots look natural and flattering, making a strong impression on potential employers and clients. * Convenience: Generate multiple AI headshots anytime, anywhere, without the need for a photographer. Perfect for busy professionals. For more AI Headshot styles, please refer to https://yce.makeupar.com/ai-headshot-generator. Use cases: ![AI Headshot Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_headshot_s2_img_03_4b55742358.jpg "AI Headshot Generator") ![AI Headshot Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_headshot_s1_img_1_d03183d7e0.jpg "AI Headshot Generator") Suggestions for How to Shoot: ![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png "Suggestions for How to Shoot") --- ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | | AI Headshot Generator | Ensure the input image contains a single person with both shoulder points and a full face visible from OpenPose, and that its short side is ≤ 1024 pixels — otherwise, the engine will automatically resize it to 1024. Output: long side <= 1024 | < 10MB | jpg/jpeg/png | * Error Codes |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_decode_image | Decode source image error | | error_nsfw_content_detected | NSFW content detected in source image | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Headshot Generator V1.0 | 1 unit for 2 images * | > *If the number of images or video duration isn’t evenly divisible, units round up. --- - [AI Image Extender](https://docs.perfectcorp.com/reference/ai_image_extender.md): # Overview Experience vibrant AI Outpainting with our cutting-edge AI Image Extender. Seamlessly expand images in any ratio, bringing out your creativity with our advanced AI technology. Preserve the highest quality while expanding your photos without compromising on style or aesthetics. Instantly transform your photos with one-click automatic background enlargement thanks to our user-friendly AI tool. Thanks to our advanced context-aware technology, we ensure a seamless and captivating experience for every viewer. ![AI Image Extender](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_outpainting_S1_img_03_cf19a018d9.jpg "AI Image Extender") Whether you're aiming for Instagram glory or framing a digital masterpiece, select from a variety of sizes and ratios for that perfect fit. As you tweak and transform, our AI seamlessly weaves its magic, ensuring the expanded areas blend flawlessly with your original photo. ![AI Image Extender](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_outpainting_S1_img_01_1876fb85a5.jpg "AI Image Extender") ## File Specs & Errors * Supported Formats & Dimensions | AI Feature | Supported Dimensions | Supported File Size | Supported Formats | | ---- | ---- | ---- | ---- | | AI Image Extender | long side <= 4096 | < 10MB | jpg/jpeg | * Error Codes |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_decode_image | Decode source image error | | error_nsfw_content_detected | NSFW content detected in source image | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Image Extender V2.0 | 2 | --- - [AI Image Generator](https://docs.perfectcorp.com/reference/ai_image_generator.md): # Overview Discover the power of AI with our innovative text-to-image generator! Transform your ideas into stunning visuals instantly, experiment with prompts, explore unique styles like cartoons, oil paintings, or sketches, and let your creativity shine through. Whether you're an artist, designer, or creative soul, our tool offers endless possibilities to bring your vision to life. Add images as references to inspire new artistic directions while letting AI refine them into entirely original masterpieces. Want more inspirations? Please refer to https://yce.makeupar.com/ai-art-generator. Use cases: ![AI Image Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_v3_video_02f161f909.jpg "AI Image Generator") ![AI Image Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_v4_poster_092d2fbb9f.jpg "AI Image Generator") Sample output: ![AI Image Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_topbanner_dt_2_e325681588.jpg "AI Image Generator") ![AI Image Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_topbanner_dt_5_8b4fa13c6a.jpg "AI Image Generator") ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | | V1.0 Text to Image | Output: 1024 pixels on the long side. | Prompt cannot exceed 500 characters | N/A | | V2.0 Text to Image | Output: The default resolution is 1664 × 928, with supported resolutions of 1664 × 928 (16:9), 1472 × 1104 (4:3), 1328 × 1328 (1:1), 1104 × 1472 (3:4), and 928 × 1664 (9:16). | Prompt cannot exceed 800 characters | N/A | | V2.0 Image to Image | Input: Both the width and height must fall within the range of 384 to 3072 pixels.
Output: Customizable width and height range from 512 to 2,048 pixels, while the default configuration maintains a total pixel count of approximately 1,024 × 1,024 with an aspect ratio based on the input image. | <10MB
Prompt cannot exceed 800 characters | JPG, JPEG, PNG, BMP, TIFF, WEBP, and GIF.
For animated GIFs, only the first frame is processed. | * Error Codes | Error Code | Description | | ---------- | ----------- | | exceed_max_filesize | The uploaded file size exceeds the maximum allowed limit. | | invalid_parameter | One or more parameters are missing or invalid | | error_download_image | Failed to download the source image. | | error_decode_image | Failed to decode or parse the source image. | | error_nsfw_content_detected | Not Safe For Work content was detected in the source image. | | error_unsupport_ratio | The aspect ratio of the input image is not supported. | | unknown_internal_error | An unspecified internal error occurred. | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Image Generator V1.0 | 2 | | AI Image Generator V2.0 | 1 | --- - [AI Look Virtual Try-On](https://docs.perfectcorp.com/reference/ai_look_vto.md): # Overview The AI Look Virtual Try-On API provides a complete workflow for applying professionally designed facial looks to user photos. Each look is crafted by beauty experts and can be applied instantly via API. ## Integration Guide This guide walks you through: * **Endpoint:** `/s2s/v2.0/task/look-vto` * **Authentication:** All requests require an `Authorization: Bearer ` * **Workflow:** 1. **Prepare a selfie:** Uploading an image or provide a valid image URL 1. **List look templates:** Listing available AI look templates 1. **Start Task (`POST`):** Submit your image id/URL and a look ``template_id``. 1. **Retrieve Task ID:** Capture the `task_id` from the response. 1. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `"success"` or `"error"`. --- * API Playground Interactively explore and test the API using our official playground: **API Playground:** [http://yce.makeupar.com/api-console/en/api-playground/ai-look-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-look-virtual-try-on/) --- * Authentication - Include your API key in the request header using **Bearer Token**: ``` Authorization: Bearer ``` You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/. * 1. Upload an Image You may upload a file directly to the server or provide a valid image URL in the VTO task payload. * Upload Endpoint ``` POST /s2s/v2.0/file ``` Alternatively, skip this step if you already have a public image URL. --- * 2. List Available Look Styles Retrieve all AI makeup look templates available for virtual try-on. * Endpoint ``` GET /s2s/v2.0/task/template/look-vto ``` * Query Parameters | Parameter | Description | | ---------------- | ------------------------------- | | `page_size` | Number of items per page | | `starting_token` | Token for pagination (optional) | * Sample Javascript Request ```javascript const data = null; const xhr = new XMLHttpRequest(); xhr.withCredentials = true; xhr.addEventListener('readystatechange', function () { if (this.readyState === this.DONE) { console.log(this.responseText); } }); xhr.open('GET', 'https://yce-api-01.makeupar.com/s2s/v2.0/task/template/look-vto?page_size=20&starting_token=73a3c9e69b89'); xhr.setRequestHeader('Authorization', 'Bearer '); xhr.send(data); ``` * Sample Successful Response ```json { "status": 200, "data": { "templates": [ { "id": "good_template_001", "thumb": "thumbnail preview image URL", "title": "Berry Smooth", "category_name": "Daily" } ], "next_token": 73a3c9e69b89 } } ``` > **Note:** Use the `id` value (`template_id`) when creating the Look VTO task. --- * 3. Create a Look VTO Task and Poll for Results Once you have an image and a template ID, create a task. The API processes the request asynchronously. You must poll the task status until it reaches `success` or `error`. * Create Task Endpoint ``` POST /s2s/v2.0/task/look-vto ``` * Polling Endpoint ``` GET /s2s/v2.0/task/look-vto/{task_id} ``` --- * Sample JavaScript Implementation ```javascript const BASE_URL = 'https://yce-api-01.makeupar.com/s2s/v2.0/task/look-vto'; const START_METHOD = 'POST'; const HEADERS = { "Content-Type": "application/json", "Authorization": "Bearer FT6Xa7xuU1SBU2ZW6pdAAUh9D093kuX3" }; const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); async function startTask() { const init = { method: START_METHOD, headers: HEADERS, body: JSON.stringify({ "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/sample_Image_7_fa28b2618a.jpg", "template_id": "all_rosy_chic" }) }; const res = await fetch(BASE_URL, init); if (!res.ok) throw new Error(`Start request failed: ${res.status} ${res.statusText}`); const payload = await res.json().catch(() => ({})); const taskId = payload?.data?.task_id; if (!taskId) throw new Error('task_id missing: ' + JSON.stringify(payload)); console.log('[startTask] Task started, id =', taskId); return taskId; } async function pollTask(taskId, { intervalMs = 2000, maxAttempts = 300 } = {}) { for (let attempt = 1; attempt <= maxAttempts; attempt++) { const pollUrl = `${BASE_URL}/${taskId}`; const res = await fetch(pollUrl, { method: 'GET', headers: HEADERS }); if (!res.ok) throw new Error(`Polling failed: ${res.status} ${res.statusText}`); const payload = await res.json().catch(() => ({})); const status = payload?.data?.task_status; console.log(`[pollTask] Attempt ${attempt} status = ${status}`); if (status === 'success') { console.log('[pollTask] Success results:', payload?.data?.results); return payload; } if (status === 'error') { throw new Error('Task failed: ' + JSON.stringify(payload)); } await sleep(intervalMs); } throw new Error('Polling timeout: Max attempts exceeded'); } (async () => { try { const taskId = await startTask(); const final = await pollTask(taskId); console.log('[main] Final response:', final); } catch (e) { console.error('[main] Flow error:', e); } })(); ``` --- * Sample Success Response ```json { "status": 200, "data": { "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/.../result.jpg?..." }, "task_status": "success" } } ``` The `results.url` field contains the final rendered virtual makeup image. --- * Summary | Step | Description | | -------------------------- | ---------------------------------------- | | **1. Upload Image** | Upload directly or provide an image URL. | | **2. List Look Templates** | Retrieve available look styles with IDs. | | **3. Create VTO Task** | Submit image URL + template ID. | | **4. Poll for Completion** | Retrieve the final result image URL. | This workflow ensures a reliable, developer-friendly integration for real-time virtual makeup try-on experiences. --- ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Look Virtual Try-On|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) |error_face_position_invalid |Please ensure your entire face is fully visible within the image| |error_face_position_too_small|The detected face is too small. Move closer to the camera| |error_face_position_out_of_boundary|The face is too large or partially outside the image frame. Adjust your position| |error_face_angle_invalid|The face angle is incorrect. For front-facing photos, keep your head within 10°. For side-facing photos, ensure more than 15°.| * 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 | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Look Virtual Try-On V1.0 | 2 | --- - [AI Makeup Transfer](https://docs.perfectcorp.com/reference/ai_makeup_transfer.md): # Overview Just Upload a Desired Photo with the Look You Like! AI Makeup Transfer makes it easy and fun to experiment with different looks by letting you to upload desired photo to try them one by one. Have any makeup look you want to try now? Let us amaze you with AI Makeup Transfer! First, upload a photo of yourself where your face and its features are clearly visible as the target image. Then, upload a photo of your favorite makeup look as the reference image. There you have it - an AI Makeup Transferred photo. Samples: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/YCE_web_Makeup_Transfer_s1_img_be53c5c345.jpg) ![](https://plugins-media.makeupar.com/smb/blog/post/2024-06-24/fda62e5d-ba58-4ecf-838a-c7d5f804c77b.jpg) --- ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Makeup Transfer|1024x1024 (long side <= 1024), single face only, need to show full face|< 10MB|jpg/jpeg/png| * Error Codes |Error Code|Description| | ---- | ---- | |error_src_no_face |No face detected in the user image |error_ref_no_face |No face detected in the reference image |error_src_face_too_small |Face in the user image is too small |error_ref_face_too_small |Face in the reference image is too small |error_src_large_face_angle |Frontal face required in the user image |error_ref_large_face_angle |Frontal face required in the reference image |error_src_eye_closed |Eye is closed in the user image |error_ref_eye_closed |Eye is closed in the reference image |error_src_eye_occluded |Eye is occluded in the user image |error_ref_eye_occluded |Eye is occluded in the reference image |error_src_lip_occluded |Lip is occluded in the user image |error_ref_lip_occluded |Lip is occluded in the reference image |error_inappropriate_ref_case01 |For both eyes, hair is too close to eye or skin region beside eyetail is not large enough in the reference image |error_inappropriate_ref_case02 |For one eye, hair is too close to eye or skin region beside eyetail is not large enough in the reference image. The other one is not frontal enough in the reference image --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Makeup Transfer V1.0 | 2 | --- - [AI Nail Transfer](https://docs.perfectcorp.com/reference/ai_nail_transfer.md): # Overview AI Nail Transfer API is a powerful generative AI solution for virtual nail try-on experiences. Powered by YouCam API’s advanced AI models and image transformation technology, users can instantly transfer any desired nail design from a reference photo onto their own hand with remarkable realism and precision. From gel nails, nail art, and polish finishes to intricate embellishments such as glitter, shell accents, and metallic textures, the AI accurately recreates a wide range of nail styles in a natural, high-definition virtual preview. This enables consumers to explore and visualize designs with confidence before making a purchase. For beauty brands, salons, and nail artists, AI Nail Transfer API provides a fast and engaging way to showcase nail designs to clients, helping increase customer engagement, improve satisfaction, and drive higher conversion rates through immersive virtual experiences. ![](https://plugins-media.makeupar.com/smb/blog/post/2022-11-24/8821ab6e-9852-4401-89df-dd6005fb81fc.jpg) ## Integration Guide This guide walks you through: Workflow for AI Nail Transfer API: **Endpoint:** `/s2s/v2.0/task/ai-nail` **Authentication Required:** `Authorization: Bearer YOUR_API_KEY` **Workflow Steps:** 1. **Image Upload Preparation:** - The process begins with preparing a hand image via the File API to `/s2s/v2.0/file`. 2. **Reference Photo Upload:** - Upload a reference photo featuring your desired nail design via the File API to `/s2s/v2.0/file`. For best results, ensure all fingernails are clearly visible. 1. **Initiate AI Task and Obtain Task ID:** - Send the uploaded image(s) via an HTTP POST request to `/s2s/v2.0/task/ai-nail`. - Await a unique `task_id` in the response, which identifies this interaction. 1. **Poll Task Status (Continuous Check):** - Use the obtained `task_id` to periodically poll the task status using an HTTP GET request (e.g., `GET /task/${task_id}`). - Continuously monitor for: - `Task_status = "success"` (process completed). - `Task_status = "error"` (resolve or retry if applicable). - Update the workflow accordingly once the status transitions to success. This structured workflow ensures efficient integration with user inputs, automated monitoring of tasks, and seamless retrieval of results. --- * Authentication - Include your API key in the request header using **Bearer Token**: ``` Authorization: Bearer YOUR_API_KEY ``` You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/. * 1. Upload an Image You may upload a file directly to the server or provide a valid image URL in the AI task payload. * Upload Endpoint ``` POST /s2s/v2.0/file ``` Alternatively, skip this step if you already have a public image URL. --- * 2. Upload a reference photo You may upload a file directly to the server or provide a valid image URL in the AI task payload. Ensure all fingernails are visible for the most accurate virtual try-on experience. * Upload Endpoint ``` POST /s2s/v2.0/file ``` --- * 3. Create a AI Nail Transfer AI Task and Poll for Results Once you have an image and a complete effect payload, create a task. The API processes the request asynchronously. You must poll the task status until it reaches `success` or `error`. * Create Task Endpoint ``` POST /s2s/v2.0/task/ai-nail ``` * Polling Endpoint ``` GET /s2s/v2.0/task/ai-nail/{task_id} ``` --- ## File Specs & Errors * AI Nail Transfer Specification **Supported hand view** Supports up to two hands per image. Additional hands will be ignored. For optimal detection, each hand should occupy at least 0.5% of the image area (approximately 102×102 px in FHD, 139×139 px in 2K, and 204×204 px in 4K images). ![](https://plugins-media.makeupar.com/strapi/assets/small_webp_bare_nails_014_f6451b0343.png) **Supported reference image** ![](https://plugins-media.makeupar.com/strapi/assets/small_webp_ref_6_341b11df3d.png) ![](https://plugins-media.makeupar.com/strapi/assets/small_webp_ref_2_86a47c1c26.png) --- * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | | AI Nail Transfer | long side <= 4096 | < 10MB | jpg/jpeg/png | * Error Codes | Error Code | Description | | ---- | ---- | | exceed_max_filesize | Image file is too large | | invalid_parameter | The input parameters are missing or in wrong format | | error_download_image | File upload was not complete or the image URL is invalid | | error_inference | The inference was failed, please check if the input and reference images are supported | | no_hand_detected | No hand is detected in the source image | * 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
- Safarin b\ | PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) orn b\_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 | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Nail Transfer V1.0 | 1 | --- - [AI Nail Virtual Try-On](https://docs.perfectcorp.com/reference/ai_nail_vto.md): # Overview The AI Nail Virtual Try On API offers an innovative way to enhance the online experience for customers interested in nail art. It allows shoppers to visualize a variety of nail styles virtually, from artificial and acrylic nails to press-on options and gel designs. With unlimited color and texture options, users can effortlessly explore different looks on both natural and synthetic nails. The platform enables personalized try-ons, letting individuals switch between styles and see before-and-after comparisons easily. This seamless integration streamlines product discovery and increases customer confidence by providing accurate, interactive previews before purchasing. ## Integration Guide This guide walks you through: Workflow for AI Nail Virtual Try On API: **Authentication Required:** `Authorization: Bearer YOUR_API_KEY` **Workflow Steps:** 1. **Image Upload Preparation:** - The process begins with preparing a back of the hand image. - Call the File API `/s2s/v2.0/file` to obtain the upload URL and associated `file_id`. - Upload the back of the hand with nail image using the provided upload URL. 2. **Nail Design Setup Options:** - Begin by selecting a suitable nail color. You can also choose a custom shape according to your taste. 3. **Initiate AI Task and Obtain Task ID:** - Send the uploaded image(s) along with the chosen effect configuration via an HTTP POST request to `/s2s/v2.0/task/nail-vto`. - Await a unique task ID in the response, which identifies this interaction. 4. **Poll Task Status (Continuous Check):** - Use the obtained `task_id` to periodically poll the task status using an HTTP GET request (e.g., `GET /s2s/v2.0/task/nail-vto/${task_id}`). - Continuously monitor for: - `Task_status = "success"` (process completed). - `Task_status = "error"` (resolve or retry if applicable). - Update the workflow accordingly once the status transitions to success. This structured workflow ensures efficient integration with user inputs, automated monitoring of tasks, and seamless retrieval of results. --- * API Playground Interactively explore and test the API using our official playground: **API Playground:** [http://yce.makeupar.com/api-console/en/api-playground/ai-nail-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-nail-virtual-try-on/) --- * Authentication - Include your API key in the request header using **Bearer Token**: ``` Authorization: Bearer YOUR_API_KEY ``` You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/. 1. Upload an Image You may upload a file directly to the server or provide a valid image URL in the VTO task payload. * Upload Endpoint ``` POST /s2s/v2.0/file ``` Alternatively, skip this step if you already have a public image URL. --- 2. Prepare an effect template * There are four distinct setup modes available for this purpose: 1. Customizing the color and aligning it with your current nail look 2. Utilizing a preset design and a specific shape to create your vision 3. Adding pressed-on nails and linking them with your existing original nail image 4. Providing image links for pressing-on nail products that match * Effect Template JSON Schemas ``` { "version": "1.0", "effect_type": "nail_polish", // valid values: ['nail_polish', 'press_on_nails'] "effects": [], "ref_file_ids": [] } ``` * Effect Format - Nail Polish - Color ``` { "sub_type": "color", "finger": "index", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky'] "color": "#ff0000", "texture": "cream", // valid values: ['matte', 'cream', 'metallic', 'jelly', 'sheer', 'pearl', 'textured', 'shimmer_coarse', 'shimmer_fine'] "transparency": 0, // 0-100, for textures except metallic "reflection": 0, // 0-100 "contrast": 0, // 0-100 "roughness": 0, // 0-100 "shimmer_opacity": 0, // 0-100, for texture pearl "shimmer_size": 0, // 0-100, for texture shimmer_coarse and shimmer_fine "textured_size": 0, // 0-100, for texture textured } ``` - Nail Polish - Design ``` { "sub_type": "design", "finger": "index", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky'] "ref_file_url": "", // Optional; Either ref_file_id or ref_file_url must be filled, but only one can be selected. "ref_file_index": 0, // This field is optional unless uploading is selected. Index corresponding to ref_file_ids under the root node "texture": "cream", // valid values: ['matte', 'cream', 'metallic', 'jelly', 'sheer', 'pearl', 'textured', 'shimmer_coarse', 'shimmer_fine'] "transparency": 0, // 0-100, only for textures except metallic "reflection": 0, // 0-100 "contrast": 0, // 0-100 "roughness": 0, // 0-100 "shimmer_opacity": 0, // 0-100, for texture pearl "shimmer_size": 0, // 0-100, for texture shimmer_coarse and shimmer_fine "textured_size": 0, // 0-100, for texture textured } ``` - Press On Nails - Color * You can find the latest shape values at: https://plugins-media.makeupar.com/wcm-saas/shapes/nails.json ``` { "sub_type": "color", "finger": "index", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky'] "shape": "square_oval", // Please check the nails.json. valid values: ['square_oval','square_square','square_squoval','squoval_oval','squoval_square','squoval_squoval','oval_oval','oval_square','oval_squoval','almond_oval','almond_square','almond_squoval','stiletto_oval','stiletto_square','stiletto_squoval], "length": 1.0, // 0.8-2.15, for shapes except original "color": "#ff0000", "texture": "cream", // valid values for other shapes: ['matte', 'cream', 'metallic'] "reflection": 0, // 0-100 "contrast": 0, // 0-100 "roughness": 0 // 0-100 } ``` - Press on Nails - Design ``` { "sub_type": "design", "finger": "index", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky'] "ref_file_url": "", // Optional; Either ref_file_id or ref_file_url must be filled, but only one can be selected. "ref_file_index": 0, // This field is optional unless uploading is selected. Index corresponding to ref_file_ids under the root node "texture": "cream", // valid values: ['matte', 'cream', 'metallic'] "reflection": 0, // 0-100 "contrast": 0, // 0-100 "roughness": 0, // 0-100 } ``` * Effect Template Design Logic 1. **Detect effect type** (`press_on_nails` vs `nail_polish`). 2. **Iterate over each entry in `effects`:** *If `sub_type === "color"`* → map fields directly, fill missing texture‑related keys with defaults. *If `sub_type === "design"`* → - If the user gave a `ref_file_url`, keep it and **omit** `ref_file_index`. - If the user supplied an index (`ref_file_index`), ensure `ref_file_ids` exists and the index is valid; then set `"ref_file_id": ref_file_ids[index]` (optional – some back‑ends expect the raw index, not id). 1. **Normalize numeric ranges** – clamp any out‑of‑range values to 0‑100 or length limits. 2. **Add missing optional keys** with defaults so the schema validator passes. 3. **Serialize** the final object as JSON (compact or pretty for debugging). * Example Payload (ready to send) ``` { "version": "1.0", "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/nail_user_photo_01_27d4260646.jpg", "effect_type": "press_on_nails", "ref_file_ids": [ "Ks3kh+1nPpVNm8iJb5374CWtBzkT4B44NPJwXbBKqVxfjK3xgCQ+hRt9MJXBFaud", "+Z7PSjuzigvsc3S/Yli1A4WN7c3J6NJHFqK2iUlqD2BfjK3xgCQ+hRt9MJXBFaud" ], "effects": [ { "sub_type": "design", "finger": "thumb", "texture": "cream", "reflection": 100, "contrast": 50, "roughness": 0, "ref_file_index": 0 }, { "sub_type": "design", "finger": "index", "texture": "cream", "reflection": 100, "contrast": 50, "roughness": 0, "ref_file_index": 1 }, { "sub_type": "design", "finger": "middle", "texture": "cream", "reflection": 100, "contrast": 50, "roughness": 0, "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_3_9ce2ddc47a.png" }, { "sub_type": "design", "finger": "pinky", "texture": "cream", "reflection": 100, "contrast": 50, "roughness": 0, "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_5_f6e46dd56f.png" }, { "sub_type": "design", "finger": "ring", "texture": "cream", "reflection": 100, "contrast": 50, "roughness": 0, "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_4_2103ca8cac.png" } ] } ``` 3. Create a Nail VTO Task and Poll for Results Once you have an image and a complete effect payload, create a task. The API processes the request asynchronously. You must poll the task status until it reaches `success` or `error`. * Create Task Endpoint ``` POST /s2s/v2.0/task/nail-vto ``` * Polling Endpoint ``` GET /s2s/v2.0/task/nail-vto/{task_id} ``` --- ## File Specs & Errors * AI Nail Virtual Try-On Specification **Supported Nail View** A single nail image in a clear front view without obstruction. | Item | Supported Dimensions | Supported File Size | Supported Formats | | --- | --- | --- | --- | | Nail Design Image - Nail Polish | * 271 px ≤ Width ≤ 542 px
* 522 px ≤ Height ≤ 1044 px
* At least 72ppi
The image will be applied from the center, and the virtual try-on effect will vary according to the length of user’s fingernails. | ≤ 1MB | png | | Nail Design Image - Press-On Nail | * 271 px ≤ Width ≤ 542 px
* 522 px ≤ Height ≤ 1044 px
* 0.5 ≤ Image aspect ratio (H/W) ≤ 3.5
* At least 72ppi
The image’s content, shape, and length settings are all used to generate the virtual try-on effect.
Since the user’s fingernail width is detected to ensure proper image scaling, it is recommended to create separate images for each fingernail with the correct aspect ratio.
Please download a press-on nail design image sample, and refer to the image guidelines for further details. Download: [Nail_Design_Image_Guidelines.pdf](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/You_Cam_API_AI_Nail_Virtual_Try_On_Press_on_Nail_Design_Image_Guidelines_a229b51750.pdf) | ≤ 1MB​ | png (with transparent background) | Press-on nail design image sample: ![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_press_on_nail_06_5_f6e46dd56f.png) [](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/youcamapi_press_on_nail_design_image_sample_de6bd64f20.png) --- **Supported Hand View** | Item | Supported Dimensions | Supported File Size | Supported Formats | | --- | --- | --- | --- | | User Photo | * Long side ≤ 2048
* Short side ≥ 256 | ≤ 10MB | jpg/jpeg/png | * Support only one hand in the input image * The area of hand palm is better to be at least half of that of input image * The aspect ratio of the input image is better to be 1:1, 3:4, 4:3 * The nails of fingers should not be occluded * It is better that there is no nail tip and nail polish on the nail ![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_nail_user_photo_02_fdba1848d6.jpg) --- * Error Codes | Error Code | Description | | ---- | ---- | | error_nail_too_small | The nail regions are too small. | | error_no_nail | No nails were detected in the source image. | * 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 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Nail Virtual Try-On V1.0 | 1 | --- - [AI Necklace Virtual Try On](https://docs.perfectcorp.com/reference/ai_necklace.md): # Overview Luxurious Look and Feel with State-of-the-Art Virtual Try-On for Necklace Precise AI neck and clavicle tracking gives users an ultra-realistic AR try-on experience, recreating the luxurious look and feel of physical necklace sampling. Create realistic and dynamic necklace vitual try-on from a 2D image, no expensive 3D modelling required. Our advanced algorithms create lifelike virtual try-on necklace SKUs with sophisticated lighting effects and physically accurate motions. ## Integration Guide This guide walks you through: * **Endpoint:** `/s2s/v2.0/task/2d-vto/necklace` * **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY` * **Workflow:** 1. **Prepare a selfie image:** Uploading an image or provide a valid image URL 2. **Prepare a necklace image:** Uploading an image or provide a valid image URL of a necklace product 3. **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response. 4. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `"success"` or `"error"`. --- * API Playground Interactively explore and test the API using our official playground: **API Playground:** [http://yce.makeupar.com/api-console/en/api-playground/ai-necklace-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-necklace-virtual-try-on/) --- * Authentication - Include your API key in the request header using **Bearer Token**: ``` Authorization: Bearer YOUR_API_KEY ``` You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/. * 1. Upload an Image You may upload a file directly to the server or provide a valid image URL in the VTO task payload. * Upload Endpoint ``` POST /s2s/v2.0/file ``` Alternatively, skip this step if you already have a public image URL. You may upload a file directly to the URL provided in the response from the File API and then use the corresponding `src_file_id` returned by the File API to invoke the AI task later. Or provide a valid image URL in the VTO task payload as `src_file_url`. The `src_file_id` or `src_file_url` will serve as the virtual try-on target. You must also provide another necklace product image as a reference using `ref_file_ids` or `ref_file_urls` to be applied to your `src_file_id` or `src_file_url`. The AI engine supports automatic background removal for your selfie. However, you may provide an occlusion mask image file for your neck (`srcmsk_file_id` or `srcmsk_file_url`) to fine-tune the segmentation. --- * 2. Create a Necklace VTO Task and Poll for Results Once you have an image and a template ID, create a task. The API processes the request asynchronously. You must poll the task status until it reaches `success` or `error`. * Create Task Endpoint ``` POST /s2s/v2.0/task/2d-vto/necklace ``` * Polling Endpoint ``` GET /s2s/v2.0/task/2d-vto/necklace/{task_id} ``` --- ## File Specs & Errors * AI Necklace Virtual Try-On Specification **Supported Necklace View** A front-facing image of the necklace worn, with the background removed. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/necklace_product_01_124206cfbe_3993a2128d.jpg) **Supported Selfie View** A front-facing selfie with the neck clearly visible and unobstructed. Horizontal head rotation is supported within 20 degrees. The head size should be proportionate, and the neck width should occupy at least 15 per cent of the image width. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Necklace_restriction_83410fb6c1.png) **necklace\_wearing\_location: array of two points (optional)** Specifies the target locations in the photo where the necklace should be placed. Default: null (engine default) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/wearing_location_874264bb70.jpg) **necklace\_shadow\_intensity: float (0.0 to 1.0)** Controls the shadow strength: 0.0 represents no shadow 1.0 represents maximum shadow Default value: 0.15 **necklace\_ambient\_light\_intensity: float (0.0 to 1.0)** Defines how much the lighting references the selfie image: 0.0 ignores the selfie image lighting 1.0 fully matches the selfie image lighting and shadow rendering Default value: 1.0 **necklace\_anchor\_point: array of two points in pixel coordinate (optional)** Specifies the anchor points for the left and right visible ends of the necklace chain in the product image, used for alignment. Default: null (engine default) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/anchor_point_7f9b254ca4.jpg) --- * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Necklace Virtual Try-On|long side <= 4096 |< 10MB|jpg/jpeg/png| * Error Codes |Error Code|Description| | ---- | ---- | | RUNTIME_ERROR | An unexpected error occurred dunecklace runtime | | PHOTO_DETECTION_FAIL | The user photo could not be processed correctly, for example no neck detected | | OBJECT_DETECTION_FAIL | The object photo could not be processed correctly, for example no product detected | | PHOTO_CHECK_INVALID | The pose or size of the user photo is invalid | | INPUT_ERROR | The input file format is incorrect | | INPUT_MAIN_IMAGE_EMPTY | A user image is required | * 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 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Necklace Virtual Try-On V1.0 | 1 Unit for Single-item wear | --- - [AI Object Removal Pro](https://docs.perfectcorp.com/reference/ai_object_removal_pro.md): # Overview Experience flawless photo editing with our advanced AI Object Removal Pro technology. Remove unwanted elements such as people, reflections and shadows while keeping every fine detail intact. Upload your photo along with a simple grayscale mask and receive clean and natural looking results that elevate your visual content. Sample usage: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/YCE_web_relayout_sign_in_index_Object_Removal_b93ad75683.jpg) ![](https://plugins-media.makeupar.com/smb/blog/post/2026-02-26/webp_6b27a29f-eab0-4205-a69d-d001fffd12ea.jpg) --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Object Removal | 1 Unit for standard
2 Units for professional | --- - [AI Photo Background Blur](https://docs.perfectcorp.com/reference/ai_photo_background_blur.md): # Overview The bokeh effect is a popular photographic technique used to blur the background of a photo and bring the subject into focus. It adds an artistic touch to a photograph, making it look more professional and eye-catching. Create professional-looking photos with the AI Photo Background Blur API, which automatically isolates subjects and applies a natural background blur to draw attention where it matters most. **Sample Usage Scenarios:** * Portrait Enhancement Apply a natural bokeh effect to make subjects stand out and improve the visual quality of profile or portrait photos. Before: ![](https://yce.makeupar.com/assets/images/sod/banner/blur/yce-topbanner-dt-before.jpg) After: ![](https://yce.makeupar.com/assets/images/sod/banner/blur/yce-topbanner-dt-after.jpg) * Professional Headshots Create studio-like background blur effects from standard photos for business profiles and corporate directories. Before: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_blur_bg_s3_poster_1_50a314e3f9.jpg) After: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_blur_bg_s3_poster_2_afb0548cb7.jpg) --- ## Integration Guide **Input Requirements & Processing Criteria:** - Upload an image containing a clear, prominent foreground subject. - The image's longest side must not exceed **4,096 px**. - The source file size must be under **10 MB**. - At least one clearly visible foreground subject is required. - Only single-subject analysis is supported. If multiple people are present, the API automatically selects the subject with the largest visible area. **Workflow:** 1. Call the File API. 2. Retrieve the signed upload URL from the response. 3. Upload the actual image to the returned URL. 4. Create an AI task. 5. Setup a Webhook or Poll the task status until completion. 6. Download the generated result image when processing is successful. --- **Step 1 — Upload File Metadata Using the File API** Use `POST /s2s/v2.0/file` to create a file record and receive upload details for the source image. ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/file \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "files": [ { "content_type": "image/jpg", "file_name": "full_body_photo_01_3dbd1b6683.jpg", "file_size": 547541 } ] }' ``` **File API Sample Response:** ```json { "status": 200, "data": { "files": [ { "content_type": "image/jpg", "file_name": "full_body_photo_01_3dbd1b6683.jpg", "file_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud", "requests": [ { "method": "PUT", "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...", "headers": { "Content-Length": "547541", "Content-Type": "image/jpg" } } ] } ] } } ``` --- **Step 2 — Retrieve File API Response Details** The response contains: | Field | Description | | --- | --- | | `file_id` | Identifier used to create the AI task. | | `requests.url` | Signed URL for uploading the actual image file. | | `requests.method` | Upload method, usually `PUT`. | | `requests.headers` | Required headers for the upload request. | --- **Step 3 — Upload Image to Provided URL** Use the `requests.url` from the File API response to upload the source image. ```bash curl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \ --header 'Content-Type: image/jpg' \ --header 'Content-Length: 547541' \ --data-binary @'./full_body_photo_01_3dbd1b6683.jpg' ``` --- **Step 4 — Create an AI Task** Use `POST /s2s/v2.0/task/bg-blur` to create an AI task. | Parameter | Description | Example | | --- | --- | --- | | `src_file_id` | File ID returned from the File API upload flow. Required when using uploaded-file workflow. | `"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud"` | | `src_file_url` | Direct URL of the source image. Use this alternative to `src_file_id`. | `"https://example.com/selfie.jpg"` | | `intensity` | Blue intensity. 0 means no blur, and 100 means the maximum blur. | 50 | **Example Request:** ```javascript const resp = await fetch( 'https://yce-api-01.makeupar.com/s2s/v2.0/task/bg-blur', { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' }, body: JSON.stringify({ src_file_url: 'https://example.com/selfie.jpg', intensity: 50 }) } ); const data = await resp.json(); console.log(data); ``` **AI Task API Response:** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` --- **Step 5 — Setup a Webhook or Poll for Task Result** See the [webhook integration guide](/develop/webhook.md) for setup and verification details. For polling, use the returned `task_id` to check task status. ```bash curl --request GET \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/bg-blur/ \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' ``` --- **Step 6 — Retrieve Result Image** When processing is successful, the response includes a download URL in `data.results.url`. ```json { "status": 200, "data": { "error": null, "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..." }, "task_status": "success" } } ``` **Invalid API Key Response:** If the access token is invalid, the API returns a `401` response. ```json { "status": 401, "error": "Unauthorized", "error_code": "InvalidAccessToken" } ``` --- ## File Specs & Errors **File Specifications:** | Specification | Requirement | | --- | --- | | Image type | The image must contain one clear and prominent foreground subject or person. | | Maximum long-side resolution | Long side must not exceed **4096 px**. | | File size limit | Must be less than **10 MB**. | | Supported formats | `jpg`, `png`. | **Error Codes:** | Error Code | Description | | --- | --- | | `exceed_max_filesize` | The source image exceeds the maximum allowed dimensions or file size. The long side must not exceed 4096 px, and the file size must remain below 10 MB. | | `error_nsfw_content_detected` | Potential NSFW content was detected in the source image or generated result image. | | `invalid_parameter` | Invalid parameters were provided for source keys, destination keys, actions, mode values, intensity levels, or task configuration. | | `error_download_image` | The source image could not be downloaded successfully. | | `error_decode_image` | The source image could not be decoded successfully. | **Environment & Dependencies:** | Tool / Language | Recommended Runtime Versions | | --- | --- | | cURL | Bash ≥ 3.2; curl ≥ 7.58 with modern TLS/HTTP support; jq ≥ 1.6 for robust JSON parsing. | | Node.js | Node ≥ 18 for global `fetch` support. | | JavaScript Browser Support | Chrome / Edge ≥ 80, Firefox ≥ 74, Safari ≥ 13.1. | | PHP | PHP ≥ 7.4 with modern TLS compatibility; ext-curl recommended or `allow_url_fopen=On` with OpenSSL and JSON support. | | Python | Python ≥ 3.10 for f-strings; requests ≥ 2.20.0. | | Java | Java 11+ for HttpClient; Jackson Databind ≥ 2.12.0. | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Photo Background Blur V2.0 | 1 | --- - [AI Photo Background Change](https://docs.perfectcorp.com/reference/ai_photo_background_change.md): # Overview The AI Photo Background Change API enhances images by isolating the subject from the original background, enabling a wide range of applications including product-focused use cases in business. This API enables developers to replace the background using custom prompts or predefined templates. **Sample Usage** Before: ![](https://yce.makeupar.com/assets/images/sod/banner/change/yce-topbanner-dt-before.jpg) After: ![](https://yce.makeupar.com/assets/images/sod/banner/change/yce-topbanner-dt-after.jpg) Before: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_change_bg_s5_poster_before_0753db3e02.jpg) After: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_change_bg_s5_poster_after_7fb288fde2.jpg) --- ## Integration Guide **1. Upload Image** Request upload URLs and file IDs via: ``` POST /s2s/v2.0/file ``` Upload the image using the returned URL. Alternatively, provide a publicly accessible image URL hosted on your own storage. **2. Prepare a background description prompt or select a background template.** ``` GET /s2s/v2.0/task/template/bg-replace ``` Retrieve the list of predefined background templates and select one using its template_id. When using prompt which is the default, the background will be generated based on the provided prompt. When using template, the background will be generated from the predefined template specified by template_id, and the prompt parameter will be ignored. **3. Execute Analysis Task** ``` POST /s2s/v2.0/task/bg-replace ``` Submit the task using file IDs or image URLs as input, along with the desired background prompt. The response returns a task_id for tracking and retrieving the result. **4. Retrieve Task Result** ``` GET /s2s/v2.0/task/bg-replace/{task_id} ``` Use the task ID to track status and obtain results. [Webhooks](/develop/webhook.md) can be configured to receive asynchronous notifications on task completion with a success or error status. Polling is also supported by repeatedly calling the task endpoint until the status is updated from running to success or error. Usage is only charged when the task completes successfully. --- ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | | AI Photo Background Change | The length of the longer side shall not exceed 4096 pixels. | < 10MB | jpg/jpeg/png | * Error Codes |Error Code|Description| | ---- | ---- | | exceed_max_filesize | The input file size exceeds the maximum allowed limit. | | size_mismatch_on_input_image_and_mask | The input image size must match the input mask image dimensions. | | invalid_parameter | Invalid parameter value. The request parameter is missing, in an invalid format, or contains an unsupported value.| * 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 | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Photo Background Change V2.0 | 4 | --- - [AI Photo Colorize](https://docs.perfectcorp.com/reference/ai_photo_colorize.md): # Overview Using the latest AI technology to colorize black and white photos, old images, or repair them. With AI Photo Colorize, you can instantly generate 4 different colorized versions of your photos, each with unique color tones ranging from warm to cool. Utilizing deep learning technology, this tool transforms your black and white photos into vibrant color images within seconds. ![AI Photo Colorize](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_colorize_s4_poster_11c0bdfead.jpg "AI Photo Colorize") --- ## File Specs & Errors * Supported Formats & Dimensions | AI Feature | Supported Dimensions | Supported File Size | Supported Formats | | ---- | ---- | ---- | ---- | | AI Photo Colorize | long side <= 4096 | < 10MB | jpg/jpeg/png | * Error Codes |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_decode_image | Decode source image error | | error_nsfw_content_detected | NSFW content detected in source image | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Photo Colorize V1.0 | 2 | --- - [AI Photo Enhance](https://docs.perfectcorp.com/reference/ai_photo_enhance.md): # Overview AI Photo Enhance uses advanced AI and deep learning to analyze image details and improve resolution, making low-resolution images clear & fix motion blur. * No More Pixelation: Eliminate pixelation for smoother, more defined images. * Fix Blurry Photos: Remove blurriness to reveal sharper, crisper details. * Enhance Quality: Bring out finer details, making every part of your image stand out. * Sharpen Images: Increase sharpness for clearer and more vivid images. * Improve Clarity: Boost overall clarity to make your photos look fresh and professional. * Face Enhancement: Refine facial features for more lifelike, enhanced portraits in motional images. Before sample: ![AI Photo Enhance](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_s5_poster_1_0779bbdbdb.jpg "AI Photo Enhance") After sample: ![AI Photo Enhance](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_s5_poster_2_a2e15250ef.jpg "AI Photo Enhance") Before sample: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_s2_poster_1_4cd6425807.jpg) After sample: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_s2_poster_2_7674281362.jpg) --- ## File Specs & Errors * Supported Formats & Dimensions | AI Feature | Supported Dimensions | Supported File Size | Supported Formats | | ---- | ---- | ---- | ---- | | AI Photo Enhance | long side <= 4096 | < 10MB | jpg/jpeg/png | * Error Codes |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_decode_image | Decode source image error | | error_nsfw_content_detected | NSFW content detected in source image | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Photo Enhance V1.0 | 2 | --- - [AI Photo Lighting](https://docs.perfectcorp.com/reference/ai_photo_lighting.md): # Overview Brighten your images with Our AI image brightening tool effortlessly. With the legendary AI technology, lighten up any image of your choice. Brighten your dark photos or images with our AI Photo Lighting tool, illuminating your memories in a flash. Before ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_lighting_v3_poster_1_b7d976b686.jpg) After ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_lighting_v3_poster_2_79d3be33bc.jpg) Brighten low-light photos effortlessly using AI tool, bringing out stunning details and vibrant colors. Before ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_lighting_v6_poster_1_2422530612.jpg) After ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_lighting_v6_poster_2_63f1ecc244.jpg) Brighten your product pictures with AI Lighting tool for a captivating and stunning presentation. --- ## File Specs & Errors * Supported Formats & Dimensions | AI Feature | Supported Dimensions | Supported File Size | Supported Formats | | ---- | ---- | ---- | ---- | | AI Photo Lighting | long side <= 4096 | < 10MB | jpg/jpeg/png | * Error Codes |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_decode_image | Decode source image error | | error_nsfw_content_detected | NSFW content detected in source image | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Photo Lighting V2.0 | 2 | --- - [AI Replace](https://docs.perfectcorp.com/reference/ai_replace.md): # Overview Replace unwanted elements with new objects using AI Replace. By using this API, you can instantly remove unwanted object from your photo and replace it with a new one just by using text. Eliminate anything from bags to cars and beyond.​ Sample: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_replace_S3_feature_img_02_a73a26bcc3.jpg) For content creators aiming to perfect their social media presence, AI Replace offers a hassle-free way to polish travel photos or promotional images. Remove and replace elements with ease, ensuring your content stands out. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_replace_S3_feature_img_03_42c9cd98d0.jpg) Create stunning room mockups with AI Replace by filling empty spaces with aesthetically pleasing furniture and objects, transforming the perception of any space. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_replace_S3_feature_img_04_4d2d82f76e.jpg) --- ## File Specs & Errors * Supported Formats & Dimensions | AI Feature | Supported Dimensions | Supported File Size | Supported Formats | | ---- | ---- | ---- | ---- | | AI Replace | long side <= 2048 | < 10MB | jpg/jpeg/png | * Error Codes |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_decode_image | Decode source image error | | error_nsfw_content_detected | NSFW content detected in source image | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Replace V1.0 | 1 | --- - [AI Scarf Virtual Try-On](https://docs.perfectcorp.com/reference/ai_scarf.md): # Overview Enhance your fashion experience with the online AR Scarf Virtual Try-On. Shoppers can instantly drape scarves over their outfits and see how patterns flow in real life. This interactive virtual scarf feature allows customers to explore different styles and colors online, replicating the in-store experience. Powered by high-fidelity AR simulation, users can enjoy detailed scarf visualisation anytime, anywhere. ## Integration Guide This guide walks you through: * **Endpoint:** `/s2s/v2.0/task/scarf` * **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY` * **Workflow:** 1. **Prepare a selfie image:** Uploading an image or providing a valid image URL of yourself as the virtual try-on target. 1. **Prepare a scarf image:** Upload an image or provide a valid image URL of a scarf product or a person wearing a scarf clearly visible without any obstruction. 1. **Select a style and a gender:** Select a preferred style and the gender you wish to visualize. 1. **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response. 1. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `"success"` or `"error"`. --- * Authentication - Include your API key in the request header using **Bearer Token**: ``` Authorization: Bearer YOUR_API_KEY ``` You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/. --- * AI Scarf API Usage Guide This guide explains how to upload images, prepare reference scarfs, and create virtual try-on tasks using the AI Scarf API. *** * Step 1. Prepare a Selfie Image You can: * Upload a selfie image using the File API (`/s2s/v2.0/file`), or * Provide a valid image URL. * Step 1.1 Upload a File Using the File API Use the **File API** (`/s2s/v2.0/file`) to upload a target user image. **Image Requirements:** * Upload a selfie photo. * Ensure the photo clearly shows the upper body. * Avoid backgrounds with multiple people or distracting objects. **Example Request:** ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/file \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "files": [ { "content_type": "image/jpg", "file_name": "selfie_photo_01_3dbd1b6683.jpg", "file_size": 547541 } ] }' ``` *** * Step 1.2. Retrieve File API Response The response includes: * `file_id` for creating an AI task. * `requests.url` for uploading the actual image file. **Sample Response:** ```json { "status": 200, "data": { "files": [ { "content_type": "image/jpg", "file_name": "selfie_photo_01_3dbd1b6683.jpg", "file_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud", "requests": [ { "method": "PUT", "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...", "headers": { "Content-Length": "547541", "Content-Type": "image/jpg" } } ] } ] } } ``` *** * Step 1.3. Upload Image to Provided URL Use the `requests.url` from the File API response to upload the image: ```bash curl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \ --header 'Content-Type: image/jpg' \ --header 'Content-Length: 547541' \ --data-binary @'./selfie_photo_01_3dbd1b6683.jpg' ``` *** * Step 2. Prepare a Reference Scarf Image You can: * Upload a scarf image using the File API (`/s2s/v2.0/file`), or * Provide a valid image URL. **Supported Scarf Images:** * Product image of the scarf. * A person carrying a scarf without any obstruction as a scarf reference. Refer to **[File Specs and Errors](#section/overview/File-Specs-and-Errors)** for detailed specifications. *** * Step 3. Create an AI Task Select a preferred style and the gender you wish to visualize. Use the **AI Task API** (`/s2s/v2.0/task/scarf`) to create a virtual try-on task. **Parameters:** * For the user image: `src_file_id` or `src_file_url`. * For the scarf image: `ref_file_id`, or `ref_file_url`. **Example Request:** ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/scarf \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "src_file_url": "https://example.com/selfie.jpg", "ref_file_url": "https://example.com/accessory.jpg", "gender": "female", "style": "random" }' ``` **Sample Response:** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` *** * Step 4. Poll for Task Result Use the task ID to check the status: ```bash curl --request GET \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/scarf/SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' ``` *** * Step 5. Retrieve Result A successful response includes a download URL for the result image: ```json { "status": 200, "data": { "error": null, "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..." }, "task_status": "success" } } ``` Invalid API Key error response: ```json { "status": 401, "error": "Unauthorized", "error_code": "InvalidAccessToken" } ``` --- ## File Specs & Errors * AI Scarf Virtual Try-On Specification * Image Requirements | Type | Minimum Resolution | Notes | | ------ | ------------------ | ----- | | Selfie | 512 × 512 | Face visible, head-to-chest preferred | | Scarf | 512 × 512 (product)
800 × 800 (worn) | Clear, unobstructed scarf view | **Supported Scarf Image** * Product Image Requirements * Minimum resolution: 512 × 512 pixels * Only one product per image * The product should cover more than 25 per cent of the image height ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/021_thumb_e356d121b3.jpg) * Worn Image Requirements * Minimum resolution: 800 × 800 pixels ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/008_thumb_5dd8b1be93.jpg) **Supported Selfie View** * Recommended image resolution: at least 512 × 512 pixels. * Recommended face coverage: more than 15 per cent of the image height. * The image must clearly show a single human subject with the face fully visible and at least a head shot included in the frame, from head to chest. A half-body shot is preferred. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/lashana_lynch_thumb_7a900b811e.jpg) **Try-on Styles** * There are five predefined styles for generating the virtual try-on output: "style_french_elegance", "style_light_luxury", "style_cottagecore", "style_modern_chic" and "style_bohemian". You can specify this style parameter when creating an AI task or allow the system to select a style at random by default. ![style_french_elegance](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/3d88ad75_41ca_4bf8_b81d_f52adf5db263_4a06b3e174.jpg) --- * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Scarf Virtual Try-On|Input: long side <= 4096
Output: 896 x 1152 |< 10MB|jpg/jpeg/png/heic| * Error Codes | Error Code | Description | | ------------------------------ | -------------------------------------------- | | error\_download\_image | Failed to download source or reference image | | error\_inference | Inference pipeline error | | error\_no\_face | No face detected in source image | | error\_nsfw\_content\_detected | NSFW content detected in result | | exceed\_max\_filesize | File size exceeds 10 MB | | invalid\_parameter | Invalid gender or style value | | unknown\_internal\_error | Other internal errors | * Environment & Dependency | Sample Code Language / Tool | Recommended Runtime Versions | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (modern TLS/HTTP support)
- jquery >= 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 | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Scarf Virtual Try-On V2.0 | 2 | --- - [AI Shoes Virtual Try-On](https://docs.perfectcorp.com/reference/ai_shoes.md): # Overview Step into the future of shopping with our AR Shoes Virtual Try-On. Instantly see how your favourite styles look and fit right from your screen. Powered by cutting-edge AI technology, this experience delivers a perfect visual fit, helping you shop with confidence and reduce returns. Explore endless styles and colours from the comfort of home. Our high-fidelity AR simulation brings every detail to life so you can enjoy the thrill of an in-store experience anytime, anywhere. Try it today and find the perfect pair that matches your style. ## Integration Guide This guide walks you through: * **Endpoint:** `/s2s/v2.0/task/shoes` * **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY` * **Workflow:** 1. **Prepare a selfie image:** Uploading an image or providing a valid image URL of yourself as the virtual try-on target. 1. **Prepare a shoes image:** Upload a shoe product image or a photo of a person wearing shoes. 1. **Select a style and a gender:** Select a preferred style and the gender you wish to visualize. 1. **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response. 1. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `"success"` or `"error"`. --- * Authentication - Include your API key in the request header using **Bearer Token**: ``` Authorization: Bearer YOUR_API_KEY ``` You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/. --- * AI Shoes API Usage Guide This guide explains how to upload images, prepare reference shoes, and create virtual try-on tasks using the AI Shoes API. *** * Step 1. Prepare a Selfie Image You can: * Upload a selfie image using the File API (`/s2s/v2.0/file`), or * Provide a valid image URL. * Step 1.1 Upload a File Using the File API Use the **File API** (`/s2s/v2.0/file`) to upload a target user image. **Image Requirements:** * Upload a selfie photo. * Ensure the photo clearly shows the upper body. * Avoid backgrounds with multiple people or distracting objects. **Example Request:** ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/file \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "files": [ { "content_type": "image/jpg", "file_name": "selfie_photo_01_3dbd1b6683.jpg", "file_size": 547541 } ] }' ``` *** * Step 1.2. Retrieve File API Response The response includes: * `file_id` for creating an AI task. * `requests.url` for uploading the actual image file. **Sample Response:** ```json { "status": 200, "data": { "files": [ { "content_type": "image/jpg", "file_name": "selfie_photo_01_3dbd1b6683.jpg", "file_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud", "requests": [ { "method": "PUT", "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...", "headers": { "Content-Length": "547541", "Content-Type": "image/jpg" } } ] } ] } } ``` *** * Step 1.3. Upload Image to Provided URL Use the `requests.url` from the File API response to upload the image: ```bash curl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \ --header 'Content-Type: image/jpg' \ --header 'Content-Length: 547541' \ --data-binary @'./selfie_photo_01_3dbd1b6683.jpg' ``` *** * Step 2. Prepare a Reference Shoes Image You can: * Upload a shoe image using the File API (`/s2s/v2.0/file`), or * Provide a valid image URL. **Supported Shoes Images:** * A shoe product image. * A photo of a person wearing shoes. Refer to **[File Specs and Errors](#section/overview/File-Specs-and-Errors)** for detailed specifications. *** * Step 3. Create an AI Task Select a preferred style and the gender you wish to visualize. Use the **AI Task API** (`/s2s/v2.0/task/shoes`) to create a virtual try-on task. **Parameters:** * For the user image: `src_file_id` or `src_file_url`. * For the shoes image: `ref_file_id`, or `ref_file_url`. **Example Request:** ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/shoes \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "src_file_url": "https://example.com/selfie.jpg", "ref_file_url": "https://example.com/accessory.jpg", "gender": "female", "style": "random" }' ``` **Sample Response:** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` *** * Step 4. Poll for Task Result Use the task ID to check the status: ```bash curl --request GET \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/shoes/SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' ``` *** * Step 5. Retrieve Result A successful response includes a download URL for the result image: ```json { "status": 200, "data": { "error": null, "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..." }, "task_status": "success" } } ``` Invalid API Key error response: ```json { "status": 401, "error": "Unauthorized", "error_code": "InvalidAccessToken" } ``` --- ## File Specs & Errors * AI Shoes Virtual Try-On Specification * Image Requirements | Type | Minimum Resolution | Notes | | ------ | ------------------ | ----- | | Selfie | 512 × 512 | Face visible, head-to-chest preferred | | Shoes | 512 × 512 (product)
800 × 800 (worn) | Clear, unobstructed shoes view | **Supported Shoes Image** * Product Image Requirements * Minimum resolution: 512 × 512 pixels * Only one product per image * The product should cover more than 25% of the image height ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/0019_thumb_06a4a9cc5f.jpg) * Worn Image Requirements * Minimum resolution: 800 × 800 pixels * Single Item Requirement: The model must wear exactly one item. Multiple items or accessories are not permitted. * Coverage Ratio: The worn item must occupy more than 20% of the total image height. This ensures the item is clearly visible and prominent within the frame. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/0006_thumb_50a0a0640c.jpg) **Supported Selfie View** * Recommended image resolution: at least 512 × 512 pixels. * Recommended face coverage: more than 15% of the image height. * Single Subject Requirement: The image must contain exactly one human subject. No additional people or partial figures are allowed. * Face Visibility: The subject's face must be fully visible without obstruction. Hair, accessories, or objects should not cover key facial features. * Framing: The image must include at least a head shot, covering the area from the top of the head to the chest. A half-body shot (head to waist) is preferred for optimal analysis. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/lashana_lynch_thumb_7a900b811e.jpg) **Try-on Styles** * There are five predefined styles for generating the virtual try-on output: "style_minimalist" "style_bohemian" "style_cottagecore" "style_french_elegance" and "style_retro_fashion". You can specify this style parameter when creating an AI task or allow the system to select a style at random by default. ![style_bohemian](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/cc55fe0d_aec9_4ead_b2e9_bc70f48c58b9_670a875b29.jpg) --- * Supported Formats & Dimensions | AI Feature | Supported Dimensions | Supported File Size | Supported Formats | | ---- | ---- | ---- | ---- | | AI Shoes Virtual Try-On | Input: long side <= 4096
Output: 1008 x 1344 | < 10MB | jpg/jpeg/png/heic | * Error Codes | Error Code | Description | | ------------------------------ | -------------------------------------------- | | error\_download\_image | Failed to download source or reference image | | error\_inference | Inference pipeline error | | error\_no\_face | No face detected in source image | | error\_nsfw\_content\_detected | NSFW content detected in result | | exceed\_max\_filesize | File size exceeds 10 MB | | invalid\_parameter | Invalid gender or style value | | unknown\_internal\_error | Other internal errors | * Environment & Dependency | Sample Code Language / Tool | Recommended Runtime Versions | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (modern TLS/HTTP support)
- jquery >= 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 | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Shoes Virtual Try-On V2.0 | 2 | --- - [AI Skin Analysis](https://docs.perfectcorp.com/reference/ai_skin_analysis.md): # Overview ![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_demostore_skincarelive_topbanner.0cffe3a7.jpg) 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. Using advanced algorithms and machine learning, AI Skin Analysis can evaluate facial skin concerns from a single front facing selfie, providing accurate skin concern scores and detection masks to enable personalized product recommendations and skincare routines tailored to each individual's 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. ## Integration Guide * 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 **Skin Analysis API Usage Guide** This guide explains how to upload an image and create a skin analysis task using the File API and AI Task API. * **Step 1: Resize your source image**
Resize your photo to fit the supported dimensions - up to 4096 pixels on the long side and at least 480 pixels on the short side for SD, or up to 4096 pixels on the long side and at least 1080 pixels on the short side for HD. See details in **[File Specs & Errors](#section/overview/File-Specs-and-Errors)** * **Step 2: Upload File Metadata via File API** - Image Requirements - See details in **[File Specs & Errors](#section/overview/File-Specs-and-Errors)** Send a POST request to initialise the file upload: ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/file \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "files": [ { "content_type": "image/png", "file_name": "skin_analysis_01_3dbd1b6683.png", "file_size": 547541 } ] }' ``` - ***Important***: Simply calling the File API does not upload your file. You must **additionally 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. > **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. *** * **Step 3: Retrieve Upload URL and File ID** The response includes: * `requests.url` – Pre-signed URL for image upload. * `file_id` – Identifier for creating an AI task. **Example Response:** ```json { "status": 200, "data": { "files": [ { "content_type": "image/png", "file_name": "skin_analysis_01_3dbd1b6683.png", "file_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud", "requests": [ { "method": "PUT", "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...", "headers": { "Content-Length": "547541", "Content-Type": "image/png" } } ] } ] } } ``` *** * **Step 4: Upload Image to Pre-signed URL** Use the provided `requests.url` and headers: ```bash curl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \ --header 'Content-Type: image/png' \ --header 'Content-Length: 547541' \ --data-binary @'./skin_analysis_01_3dbd1b6683.png' ``` *** * **Step 5: Create AI Task** Use the `file_id` from Step 2 to create a skin analysis task: ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "src_file_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud", "dst_actions": ["wrinkle", "pore", "texture", "acne"], "miniserver_args": { "enable_mask_overlay": true, "enable_dark_background_hd_pore": true, "color_dark_background_hd_pore": "3D3D3D", "opacity_dark_background_hd_pore": 0.4 // Additional parameters omitted for brevity }, "format": "json" }' ``` Once the upload is complete, you can select any skin concerns to analyze using your file ID or image file url. Please refer to the **[Inputs & Outputs](#section/overview/Inputs-and-Outputs)**.
Subsequently, calling POST 'task/skin-analysis' with the File ID or image file url executes the enhance task and obtains a ***task_id***. Please be advised that simultaneous use of SD and HD skin concern parameters is **NOT** supported. - **Use an Existing Public Image URL** Instead of uploading, you may supply a publicly accessible image URL directly when initiating the AI task. **Example Response:** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` *** * **Step 6: Poll Task Status** Retrieve task results using the `task_id`: ```bash curl --request GET \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis/ \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' ``` 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. *** * **Step 7: Interpret Results** The response includes: * `ui_score` – User-friendly score. * `raw_score` – Raw analysis score. * `mask_urls` – URLs for detection masks. **Example Response:** ```json { "status": 200, "data": { "results": { "output": [ { "type": "texture", "ui_score": 68, "raw_score": 57.33, "mask_urls": ["https://yce-us.s3-accelerate.amazonaws.com/...texture_output.jpg"] }, { "type": "pore", "ui_score": 92, "raw_score": 95.34, "mask_urls": ["https://yce-us.s3-accelerate.amazonaws.com/...pore_output.jpg"] } // Additional results omitted for brevity ] }, "task_status": "success" } } ``` * Debugging Guide > **Warning:** Please be advised that simultaneous use of SD and HD skin concern parameters is **NOT** supported. Attempting to deviate from these specifications will result in an ***InvalidParameters*** error. * If you mix using HD and SD skin concerns, you will get an error as following: ```json { "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: ```json { "status": 400, "error": "Not available dst_action abc123", "error_code": "InvalidParameters" } ``` --- * Real-world examples: ![](https://plugins-media.makeupar.com/webconsultation/images/skincare-widget/img_webcm_skincare_service_survey_demo.jpg) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/skin_analysis_s5_poster_3_dt_85efe14952.png) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Skincare_Pro_Medspa_Situation_Image_6aea6046f9.jpg) ## Inputs & Outputs * 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 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/mask_overlay_false_1920_ea1cde0ead.png) * Set enable_mask_overlay to true ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/mask_overlay_1920_0fbb4786cc.png) ---- * 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 - hd_tear_trough.png - hd_skin_type.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 - tear_trough.png - skin_type.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. * "hd_tear_trough": Detects tear trough. * "hd_skin_type": Subcategories[whole, t_zone, u_zone] Evalutate skin type of Normal, Oily, Dry, Combination, Redness, Dry & Redness, Oily & Redness, Combination & Redness. * 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. * "tear_trough": Detects tear trough. * "skin_type": Subcategories[whole, t_zone, u_zone] Evaluates skin type of Normal, Oily, Dry, Combination, Redness, Dry & Redness, Oily & Redness, Combination & Redness. * Sample score_info.json of HD Skincare ```json { "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 ```json { "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 } ``` ## File Specs & Errors * Supported Formats & Dimensions | AI Feature | Supported Dimensions | Supported File Size | Supported Formats | | ---- | ---- | ---- | ---- | | SD Skincare | Minimum short side length must be at least 480 pixels.
There is no limit on the long side; however, if it exceeds 2560 pixels, the system will automatically resize it to 2560 pixels. | < 10MB | jpg/jpeg/png | | HD Skincare | The minimum short side length must be at least 1080 pixels.
There is no restriction on the long side; however, if it exceeds 2560 pixels, it will be automatically resized to 2560 pixels. |< 10MB | jpg/jpeg/png | > **Warning:** Although the API automatically resizes images to a maximum dimension of 2560 pixels, you are responsible for ensuring that all faces are clearly in focus, the image quality is high, lighting is even, and faces are large enough and oriented directly toward the camera. Motion blur and occlusions must be avoided when capturing HD or SD skincare images prior to running AI Skin Analysis. The use of a portrait aspect ratio is strongly recommended over landscape for optimal results. * Suggestions for How to Shoot: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png) * 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. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_error_src_face_too_small_cr_725792a7fb.png) * 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 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## Mobile Camera Kit {% partial file="/_partials/mobile-camera-kit.md" /%} --- ## Unit Consumption * AI Skin Analysis (V2.0, 2.1) | AI Feature | Unit Consumed | |---|---| | 1~4 concerns analysis | 9 units for SD; 12 units for HD | | 5~8 concerns analysis | 12 units for SD; 16 units for HD | | 9~12 concerns analysis | 14 units for SD; 20 units for HD | | 13~16 concerns analysis | 16 units for SD; 22 units for HD | --- - [AI Skin simulation](https://docs.perfectcorp.com/reference/ai_skin_simulation.md): # Overview **AI-Powered Skin Simulation: Visualizing Treatment Progress with Precision and Professionalism** Our cutting-edge AI-driven skin simulation technology enables highly accurate before-and-after visualizations of facial skin conditions, allowing both professionals and consumers to objectively track the efficacy of skincare treatments over time. Engineered for high-fidelity realism and clinical-grade insights, this solution supports the visualization of up to ten distinct skin concerns, including radiance, acne, oiliness, eye bags, dark circles, spots, pores, texture, wrinkles and redness. ![](https://plugins-media.makeupar.com/smb/blog/post/2025-04-17/4edad54f-ef6b-4842-b104-d114889318b1.jpg) By harnessing sophisticated machine learning models combined with advanced augmented reality capabilities, the system delivers realistic, non-invasive previews of potential outcomes using only a standard smartphone camera or desktop webcam. Each simulation is generated in seconds, offering users an immediate yet scientifically grounded understanding of how targeted skincare interventions may enhance their complexion over time. ![](https://plugins-media.makeupar.com/smb/blog/post/2025-11-13/webp_27e3ad50-7769-46de-822c-c9300f87f57d.webp) Designed specifically for skincare brands, dermatology practices, aesthetic clinics, and retail beauty retailers, this platform integrates effortlessly across digital and physical touchpoints, including e-commerce websites, mobile applications, virtual consultations, and point-of-sale kiosks. Its versatility supports a wide array of use cases such as personalized regimen recommendations, product performance simulation, treatment planning for professional procedures, and interactive educational tools that strengthen client engagement and build trust in brand claims. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_Skin_Simulation_pores_b1e209ee58.jpg) Through objective visualization and data-driven storytelling, our AI skin simulation empowers skincare professionals to set realistic expectations, customize care plans, and demonstrate measurable progress, ultimately elevating the customer experience while reinforcing evidence-based efficacy in an increasingly competitive market landscape. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_Skin_Simulation_283421234a.jpg) --- ## Integration Guide This guide walks you through: Workflow for AI Skin Simulation API: **Endpoint:** `/s2s/v2.0/task/skin-simulation` **Authentication Required:** `Authorization: Bearer YOUR_API_KEY` **Workflow Steps:** 1. **Image Upload Preparation:** - The process begins with preparing a selfie image. 2. **AI Skin Simulation Settings** For each skin concern (e.g., wrinkle, pores, redness), adjust the **simulation intensity** using the value from **0.0 to 1.0**: - **0.0**: Shows your *original* skin appearance—no changes. - **1.0**: Applies the *most natural, healthy-looking* enhancement AI can generate for that concern. **How it works:** - At low settings (e.g., 0.2–0.4), fine lines or minor imperfections are subtly softened. - At higher settings (e.g., 0.7–1.0), more pronounced improvements occur, such as significant reduction in moderate or deep wrinkles, smoother texture, and improved tone, even while preserving natural skin details. Adjust gradually to achieve your desired look! 1. **Initiate AI Task and Obtain Task ID:** - Send the uploaded image along with the skin simulation configuration via an HTTP POST request to `/s2s/v2.0/task/skin-simulation`. - Await a unique task ID in the response, which identifies this interaction. 2. **Poll Task Status (Continuous Check):** - Use the obtained `task_id` to periodically poll the task status using an HTTP GET request (e.g., `GET /task/${task_id}`). - Continuously monitor for: - `Task_status = "success"` (process completed). - `Task_status = "error"` (resolve or retry if applicable). - Update the workflow accordingly once the status transitions to success. This structured workflow ensures efficient integration with user inputs, automated monitoring of tasks, and seamless retrieval of results. --- * Authentication - Include your API key in the request header using **Bearer Token**: ``` Authorization: Bearer YOUR_API_KEY ``` You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/. --- * Upload an Image You may upload a file directly to the server or provide a valid image URL in the AI task payload. * Upload Endpoint ``` POST /s2s/v2.0/file ``` Alternatively, skip this step if you already have a public image URL. --- * Adjust AI Skin Simulation Intensity **AI Skin Simulation Settings** For each skin concern (e.g., wrinkle, pores, redness), adjust the **simulation intensity** on a scale from **0.0 to 1.0**: - **0.0** → *Original appearance* — no AI enhancement applied. - **1.0** → *Maximum natural, healthy-looking improvement* for that concern, as realistically rendered by our AI model. **What to expect at different intensity levels:** | Intensity Range | Effect | |-----------------|--------| | **0.1 – 0.3** | Subtle refinement — minor smoothing of fine lines, slight pore softening, or gentle redness reduction. Ideal for a natural “fresh-faced” look. | | **0.4 – 0.6** | Balanced enhancement — noticeable improvement in texture and clarity while retaining individual skin character. | | **0.7 – 1.0** | Full correction — significantly reduces moderate to deep wrinkles, evens tone, minimizes pores and redness, and enhances overall radiance—*without* looking over-processed or artificial. | **Pro Tip:** Start low (e.g., 0.2) and gradually increase until you reach the desired result in realism. --- * Create a AI Skin Simulation AI Task and Poll for Results After uploading an image and setting **at least one** skin concern's simulation intensity above 0.0, you can initiate a task. The API processes the request asynchronously. You must poll the task status until it reaches `success` or `error`. * Create Task Endpoint ``` POST /s2s/v2.0/task/skin-simulation ``` * Polling Endpoint ``` GET /s2s/v2.0/task/skin-simulation/{task_id} ``` --- ## File Specs & Errors * AI Skin Simulation Specification **Camera and Imaging Guidance** **Lighting Conditions** Ensure the environment is well-lit and evenly illuminated. Avoid strong backlighting, localized overexposure, or large shadows on the face. Use natural daylight or soft indoor lighting whenever possible. Do not use colored lights, including pink, blue, or other tinted sources, as they may distort skin tone representation. **Face Position and Occlusion** Capture a frontal view with the face directly facing the camera. The head rotation should be minimal; avoid excessive tilting or turning to either side. Ensure the entire face, including forehead, cheeks, and chin, is fully visible and unobstructed. Do not use hair, masks, hands, eyeglass frames, mobile phones, or any other objects that partially cover facial features. **Facial Expression and Pose** Maintain a natural, relaxed expression with both eyes open. The mouth may remain closed or slightly open, do not strain or exaggerate the pose. **Face Size in Frame** The face must occupy at least 60% of the image width to ensure sufficient detail for accurate analysis. Avoid capturing subjects that are too small, distant, or improperly framed. ![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_skin_analysis_01_5b5defd339.png) --- * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Skin Simulation|short side >= 480, long side <= 2560|< 10MB|jpg/jpeg/png| * Error Codes | **Error Code** | **Description** | |------------------------------------|----------------| | `error_below_min_image_size` | Input image resolution is below the minimum required size (e.g., < 256×256 pixels). Please upload a higher-resolution image. | | `error_exceed_max_image_size` | Input image resolution exceeds the maximum allowed size (e.g., > 2560×2560 pixels). Resize or downscale your image before uploading. | | `error_invalid_params` | Invalid request parameters were provided. | | `error_src_face_too_small` | The detected face occupies less than 60% of the image width—too small for accurate skin analysis. Use an image with a larger, clearer face centered in frame. | | `error_src_face_out_of_bound` | The detected face is partially or fully outside the image boundaries (e.g., face cropped too tightly). Please ensure the full face—including forehead, cheeks, and chin—is visible and properly framed. | | `error_lighting_dark` | Ambient lighting in the image is insufficient for reliable skin analysis (e.g., underexposed, shadows dominate the face). Upload an image taken in well-lit conditions with even illumination on the face. | * 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 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## Unit Consumption * Skin Simulation | AI Feature | Unit Consumed | |---|---| | 1~4 concerns analysis | 4 | | 5~10 concerns analysis | 6 | --- - [AI Facial Color Tones Analyzer](https://docs.perfectcorp.com/reference/ai_skin_tone_analysis.md): # Overview The AI Facial Color Tones Analyzer detects facial skin tone, eye, eyebrow, lip & hair colors. This inclusive technology ensures to a complete tailored shopping experience for all ethnicities. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/img_Face_Ratio_sec_02_02_enu_21a3d8d423.jpg) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/shade_finder_s5_poster_2_8a8f9307d2.png) ## Integration Guide * How to Take Photos for AI Facial Color Tones Analyzer 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](#section/overview/File-Specs-and-Errors)** 2. **Upload file using the File API**
Using the ***/s2s/v2.0/file*** API to upload a target user image. - Image Requirements - See details in **[File Specs & Errors](#section/overview/File-Specs-and-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 Facial Color Tones Analyzer 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](#section/overview/Inputs-and-Outputs)**.
Subsequently, calling POST 'task/skin-tone-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/skin-tone-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 retention period is mandotary. A task will be timed out if there is no polling request within the retention period, 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 retention period 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. ![](https://plugins-media.makeupar.com/smb/blog/post/2022-08-19/2a1af800-7c69-44a5-a94c-70a4a9c4d2b0.jpg) --- ## Inputs & Outputs * Inputs The AI will analyse the color tones of your skin. You may adjust the `face_angle_strictness_level` to control the checking strictness of the input face angle, ranging from strict, high, medium, low to flexible. The strictness level applies to face angle detection, including pitch, yaw and roll. A stricter level ensures more accurate face attribute results. The default setting is high. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/shade_finder_s4_poster_399f34c6ef.jpg) * Outputs ```json { "status": 200, "data": { "task_status": "success", "results": { "color": { "eye_color": "#293F9B", "eye_color_name": "Blue", "lip_color": "#D23245", "eyebrow_color": "#5B2B31", "skin_color": "#b9947c", "hair_color": "#a0a0a0", "hair_color_name": "Auburn" } } } } ``` | **Result Parameter** | **Result Types** | | --- | --- | | `skin_color` | Hex value | | `eye_color`| Hex value | | `eye_color_name` | Amber, Brown, Green, Blue, Gray, Other | | `lip_color` | Hex value | | `eyebrow_color` | Hex value | | `hair_color` | Hex value | | `color.hair_color_name` | Auburn, Black, Blonde, Brown, Grey/White, Red | * Suggestions for How to Shoot: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png) > **Warning:** The width of the face needs to be greater than 60% of the width of the image. --- ## File Specs & Errors * Supported Formats & Dimensions | AI Feature | Supported Dimensions | Supported File Size | Supported Formats | | ---- | ---- | ---- | ---- | | AI Facial Color Tones 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 320 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 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Facial Color Tones Analyzer V1.0 | 20 | --- - [AI Smile](https://docs.perfectcorp.com/reference/ai_smile.md): # overview Introducing Generative AI Smile API, the easy way to turn that frown upside down. This convenient AI smile generator transforms sad or neutral facial expressions into happy, natural looking smiles in just moments. Powered by advanced generative AI, it helps bring warmth and positivity to any photo with a simple and effortless process. Upload an image, let the AI work its magic, and instantly convert your sad face into a cheerful smiley face that spreads happiness everywhere it's shared. The AI Smile generator supports two distinct smile styles, giving users more control over the final expression. 1. **smile_with_teeth_visible** This option creates a bright, joyful smile with naturally visible teeth. It is ideal for upbeat portraits, social media photos, and situations where a warm and expressive look is desired. 2. **closed_mouth_smile** This option produces a subtle, gentle smile with lips closed. It works well for professional photos, formal profiles, or when a calm and natural expression is preferred. Users can easily choose the smile type that best matches their photo, mood, or intended use, ensuring realistic and appealing results every time. Whether you're editing photos, creating fun content, or simply want to add a touch of positivity, Generative AI Smile makes it easy to spread happiness, one smile at a time. Upload a face. Click once. Smile instantly. ![](https://plugins-media.makeupar.com/smb/blog/post/2024-03-22/5f25b0f7-5d43-421b-ae50-5def0de69f2a.jpg) ![](https://plugins-media.makeupar.com/smb/blog/post/2024-12-16/4f4397e0-9e87-429a-8e39-a9d399b6602b.jpg) ## Integration Guide This guide walks you through: Workflow for AI Smile API: **Endpoint:** `/s2s/v2.0/task/ai-smile` **Authentication Required:** `Authorization: Bearer YOUR_API_KEY` **Workflow Steps:** 1. **Image Upload Preparation:** - Prepare a selfie image for upload. - Call the File API `/s2s/v2.0/file` to obtain the upload URL and associated `file_id`. - Upload the selfie image using the provided upload URL. 2. **Initiate AI Task and Obtain Task ID:** - Send the `file_id` along with the chosen effect configuration via an HTTP POST request to `/s2s/v2.0/task/ai-smile`. - Await a unique task ID in the response, which identifies this interaction. 3. **Poll Task Status (Continuous Check):** - Use the obtained `task_id` to periodically poll the task status using an HTTP GET request (e.g., `GET /s2s/v2.0/task/ai-smile/${task_id}`). - Continuously monitor for: - `Task_status = "success"` (process completed). - `Task_status = "error"` (resolve or retry if applicable). - Update the workflow accordingly once the status transitions to success. This structured workflow ensures efficient integration with user inputs, automated monitoring of tasks, and seamless retrieval of results. --- 1. Authentication - Include your API key in the request header using **Bearer Token**: ``` Authorization: Bearer YOUR_API_KEY ``` You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/. 2. Upload an Image You may upload a file directly to the server or provide a valid image URL in the AI task payload. * Upload Endpoint ``` POST /s2s/v2.0/file ``` Alternatively, skip this step if you already have a public image URL. --- 3. Create an AI Smile Task and Poll for Results Once you have an image and a complete effect setup, create a task. The API processes the request asynchronously. You must poll the task status until it reaches `success` or `error`. * Create Task Endpoint ``` POST /s2s/v2.0/task/ai-smile ``` * Polling Endpoint ``` GET /s2s/v2.0/task/ai-smile/{task_id} ``` --- ## File Specs & Errors * AI Smile Specification **Supported Selfie View** Only single-person images are supported, the image must contain a clearly visible face of sufficient size exceeding 32 x 32 pixels when the long edge is 640, and the capture angles must have a roll within plus or minus 75 degrees and a yaw within plus or minus 90 degrees to avoid face detection failure. ![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_face_reshape_01_85c8ffc055.jpg) --- * Supported Formats & Dimensions | AI Feature | Supported Dimensions | Supported File Size | Supported Formats| | ---- | ---- | ---- | ---- | | AI Smile | long side <= 4096 | < 10MB | jpg/jpeg/png/heic | * Error Codes | Error Code | Description | | ---------- | ----------- | | EXCEED_MAX_FILESIZE | The input file exceeds the maximum allowed size. | | INVALID_PARAMETER | One or more required parameters are missing, empty, or improperly formatted. | | ERROR_DOWNLOAD_IMAGE | The source image could not be downloaded. | | ERROR_NO_FACE | No face was detected in the provided image. | | ERROR_INFERENCE | The inference process failed due to a workflow issue, execution error, encoding error, or missing output image. | | UNKNOWN_INTERNAL_ERROR | An unexpected internal error occurred. | * 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 | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Smile V1.0 | 1 | --- - [AI Studio Generator](https://docs.perfectcorp.com/reference/ai_studio_generator.md): # Overview Embrace the excellence of studio kike AI Portrait Generator. Transform your selfie into a studio-quality portrait in a flash​. * Studio-Free Convenience: No need for a photographer or studio visits—create studio-quality artistic photos anytime, anywhere​ * Quick Photo Transformation: Fast processing for instant high-quality artistic photo results, ideal for quick updates * High-Quality Artistic Output: Delivers professional-standard artistic photos with clear details, perfect lighting, just like you've taken the photos in a studio Use cases: ![AI Studio Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_studio_S1_img_19b627b6af.jpg "AI Studio Generator") ![AI Studio Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_studio_S2_img_01_2e318817e9.jpg "AI Studio Generator") Suggestions for How to Shoot: ![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png "Suggestions for How to Shoot") --- ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Studio|Please ensure the input image has one face, a short side of at least 200 pixels, and a long side no greater than 1920 pixels; the engine will select the largest face if multiple are present, and the output resolution will not exceed 960×1280 (W×H)|< 10MB|jpg/jpeg/png| * 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| --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Studio Generator V3.0 | 1 unit for 2 images * | > *If the number of images or video duration isn’t evenly divisible, units round up. --- - [AI Teeth Whitening](https://docs.perfectcorp.com/reference/ai_teeth_whitening.md): # Overview **AI Teeth Whitening API** The AI Teeth Whitening API provides an advanced, automated solution for enhancing smiles in photos. Using intelligent image processing, it brightens teeth naturally and accurately, creating polished, professional results within seconds. ![](https://plugins-media.makeupar.com/smb/blog/post/2023-07-28/f05fda4d-8ca8-4661-b4b5-135067280a10.jpg) **How It Removes Yellow Teeth in Photos** **Smart Whitening** The API automatically detects teeth and applies a natural-looking whitening effect without making the image appear artificial. **Adjustable Levels** A built-in adjustment feature allows users to control the degree of whitening, from a subtle enhancement to a more pronounced, camera-ready finish. **Key Features** **Quick and Easy Enhancement** Achieve a noticeably brighter smile in just a few seconds. **Accurate AI Detection** Advanced detection ensures that only teeth are modified, maintaining a realistic and balanced appearance. **Adjustable Whitening Intensity** Users can fine-tune the whitening strength to match their preferred style. **Natural Results with Advanced Algorithms** The AI Teeth Whitening API uses sophisticated algorithms designed to identify teeth precisely and apply whitening effects that remain true to life. Users can refine the intensity to achieve a subtle, natural improvement, ensuring that the final result looks authentic and visually appealing. --- ## Integration Guide * Take a Selfie * Face the camera directly with proper lighting. * Use the JS Camera Kit to capture the photo. * Retrieve upload URLs and File IDs via ***/s2s/v2.0/file*** API Upload the following files using the upload URLs returned in the file API response: * Your selfie photo * Execute AI Task ***/s2s/v2.0/task/teeth-whiten*** Run the AI task using file IDs or image URLs as the input source. Configure the effect parameters as desired. * Poll Task Status Use the returned **task\_id** to monitor task progress. Poll **GET /s2s/v2.0/task/teeth-whiten/{task_id}** to check the engine's status. The task will remain in a **“running”** state until it is completed. No units are consumed while the task is running. * **Usage demonstration** ![](https://plugins-media.makeupar.com/smb/blog/post/2022-05-13/26c04462-d183-4392-937b-f6173ff9e814.jpg) ![](https://plugins-media.makeupar.com/smb/blog/post/2025-07-01/webp_a4cd3779-2966-4b8f-888e-032dffc003c0.webp) ![](https://plugins-media.makeupar.com/smb/blog/post/2025-11-13/webp_5824c85f-813e-4c14-b036-38cba206ee0b.webp) ## File Specs & Errors * Supported Formats & Dimensions |Type|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Teeth Whitening|Selfie Image:
* Long side ≤ 1920 px
* Short side ≥ 320 px |< 10MB|jpg/png| * Error Codes |Error Code|Description| | ---- | ---- | | error_exceed_max_image_size | If the longer side of an image exceeds 1920 pixels | |error_below_min_image_size|If your image is smaller than 320 pixels in width or height, it's too small to use| |error_face_position_invalid|Your face needs to be fully visible in the image, without any parts cut off| |error_face_position_too_small|The face in your photo is too small to analyze properly| |error_face_position_out_of_boundary|Your face is either too large or partially outside the edges of the photo| |error_insufficient_lighting|The lighting is too dim, which makes analysis difficult| |error_face_angle_invalid|Your face angle isn't quite right. For front-facing shots, keep your head within 10 degrees of straight. For side-facing shots, the angle should be more than 15 degrees| * 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 | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Teeth Whitening V1.0 | 1 | --- - [AI Video Background Replace](https://docs.perfectcorp.com/reference/ai_video_background_replace.md): # Overview **AI Video Background Replace** ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Green_Screen_ddb7892393.png) The AI Video Background Replace API enables you to seamlessly add any background you choose. You can select from a wide range of options, including scenic landscapes, custom images, or even lighthearted visuals, giving you complete creative control to design the ideal setting for your content. There is no need for a studio or green screen. You can easily replace video backgrounds to achieve a clean and professional look. Whether you want to introduce a new environment or remove unwanted distractions, this solution is ideal for producing engaging videos and tutorials without requiring expensive equipment. --- ## Integration Guide **1. Prepare a Source Video and a Background Image** The output must be in MP4 format with the same resolution as the input, a frame rate capped at 30 frames per second with automatic conversion if the input exceeds this limit, and a maximum duration of 600 seconds with only the first 600 seconds retained if the input video is longer. The background image must be in JPG or PNG format with a maximum resolution of 4096 by 4096 pixels with the long side not exceeding 4096 pixels and a file size limit of 10 megabytes. **2. Upload File** Request upload URLs and file IDs via: ``` POST /s2s/v2.0/file ``` **3. Execute AI Task** ``` POST /s2s/v2.0/task/bg-replace-vid ``` Submit the task using file IDs or image URLs as input. The response returns a task_id for tracking and retrieving the result. **4. Retrieve Task Result** ``` GET /s2s/v2.0/task/bg-replace-vid/{task_id} ``` Use the task ID to track status and obtain results. [Webhooks](/develop/webhook.md) can be configured to receive asynchronous notifications on task completion with a success or error status. Polling is also supported by repeatedly calling the task endpoint until the status is updated from running to success or error. Usage is only charged when the task completes successfully. --- ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | | AI Video Background Replace | The output must be in MP4 format with the same resolution as the input, a frame rate capped at 30 frames per second with automatic conversion if the input exceeds this limit, and a maximum duration of 600 seconds with only the first 600 seconds retained if the input video is longer.
The background image must be in JPG or PNG format with a maximum resolution of 4096 by 4096 pixels with the long side not exceeding 4096 pixels and a file size limit of 10 megabytes. | Video length limit: 600s
Background image: <10MB | container: mp4
video: MPEG-4, MPEG-4 AVC,
audio: aac, amr, mp3 | * Error Codes |Error Code|Description| | ---- | ---- | | error_download_video | Download source video error | | error_decode_video | Decode source video error | | error_unsupported_video | Unsupported video format | | exceed_max_filesize | Input file size exceeds the maximum limit| | error_nsfw_content_detected | NSFW content detected in the source file | | error_decode_mask | Decode mask image error | | invalid_parameter | Invalid parameter value| * 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 | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Video Background Replace V1.0 | 2 (1 seconds) * | > *If the number of images or video duration isn’t evenly divisible, units round up. --- - [AI Video Enhancer](https://docs.perfectcorp.com/reference/ai_video_enhancer.md): # Overview The AI Video Enhance API enables developers to automatically improve video quality with minimal effort. It uses advanced AI processing to fix blur, adjust sharpness, optimize brightness, and upscale low resolution footage. With a simple API call, videos can be transformed from low-res footage and old videos into clean and clear HD quality. This solution is designed for fast integration and does not require prior experience in video editing or machine learning. It is ideal for applications that handle user generated content, media platforms, marketing tools, and content automation systems. **Core Capabilities** 1. Blur correction The API detects motion blur and soft details, then reconstructs sharper frames using AI enhancement models. 2. Sharpness optimization Edges and textures are enhanced to create a more defined and visually crisp video. 3. Brightness and exposure adjustment Lighting inconsistencies are automatically corrected to improve visibility and color balance. 4. AI upscaling Resolution is intelligently increased from lower quality formats such as 480p to HD quality while preserving details. 5. Quality boosting Noise reduction and artifact removal are applied to produce clean and professional results. Sample usage cases: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_video_enhancer_S2_feature_video_03_S_0_10169a6902.jpg) --- ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | | AI Video Enhance | The input video must not exceed 60 seconds in length and 2K resolution or less with a frame rate of 30 frames per second or below. | Length limit: 60s | container: mov, mp4
video: MPEG-4, MPEG-4 AVC,
audio: aac, amr, mp3 | * Error Codes |Error Code|Description| | ---- | ---- | | error_download_video | Download source video error | | error_decode_video | Decode source video error | | error_unsupported_video | Unsupported video format | | exceed_max_filesize | Input file size exceeds the maximum limit| | error_nsfw_content_detected | NSFW content detected in the source file | | error_decode_mask | Decode mask image error | | invalid_parameter | Invalid parameter value| --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Video Enhancer V1.0 | 1 (2 seconds) * | > *If the number of images or video duration isn’t evenly divisible, units round up. --- - [AI Video Face Swap](https://docs.perfectcorp.com/reference/ai_video_face_swap.md): # Overview Video face swapping is an AI-powered process that uses YouCam’s AI Video Face Swap API to replace one person's face with another in a video. With advanced AI technology, the AI video face swap delivers remarkably realistic results. The facial expressions, lighting, and skin tones are finely tuned to ensure that the swapped faces blend seamlessly with the original footage. > **Note:** This API supports video with single face only. For customizable solution, please [contact us](mailto:YouCamOnlineEditor_API@perfectcorp.com). Sample usage cases: ![](https://plugins-media.makeupar.com/smb/blog/post/2024-08-23/b1f96100-37d6-4c28-b467-d397e9c3a25d.jpg) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_video_face_swap_S3_video_03_28785ebe0c.jpg) ![](https://plugins-media.makeupar.com/smb/story/2024-09-12/3582f617-e88e-4219-9e72-43d4c26791cd.png) --- ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | | AI Video Face Swap | The input video must not exceed 30 seconds, 4K resolution, or 30 FPS, and the output is limited to 1280 long-side resolution, 30 FPS, and up to 30 seconds. | Length limit: 30s | container: mov, mp4
video: MPEG-4, MPEG-4 AVC,
audio: aac, amr, mp3 | * Error Codes |Error Code|Description| | ---- | ---- | | error_download_video | Download source video error | | error_decode_video | Decode source video error | | error_unsupported_video | Unsupported video format | | exceed_max_filesize | Input file size exceeds the maximum limit| | error_nsfw_content_detected | NSFW content detected in the source file | | error_decode_mask | Decode mask image error | | invalid_parameter | Invalid parameter value| --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Video Face Swap V1.0 | 1 (5 seconds) * | > *If the number of images or video duration isn’t evenly divisible, units round up. --- - [AI Video Generator](https://docs.perfectcorp.com/reference/ai_video_generator.md): # Overview YouCam AI Video Generator transforms text prompts and images into captivating videos with ease. Powered by advanced AI technology, it creates realistic motion effects that bring your ideas and photos to life. With a wide selection of professionally optimized templates, you can quickly turn still images into engaging, high quality video content. To create an AI video from an image, start with a photo that features a clean background and a clearly visible portrait. Simply upload your image and let YouCam AI Video Generator do the rest, transforming your text prompts and photo into a dynamic video in just moments. Use cases: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_Animate%20Photo_047_d9e1cff579.jpg) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Dance_Video_61cf4c58d1.png) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/241216_AI_Kiss_image05_c3b7f1ac5b.jpg) ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | | V1.0 Image to Video (Standard) |Input: >= 300*300px with aspect ratio between 1:2.5 ~ 2.5:1. Output: Up to 720p 30fps|Input: <10MB. Output: 5 seconds or 10 seconds|jpg/jpeg/png| | V1.0 Image to Video (Professional) |Input: >= 300*300px with aspect ratio between 1:2.5 ~ 2.5:1. Output: Up to 1080p 30fps|Input: <10MB. Output: 5 seconds or 10 seconds|jpg/jpeg/png| | V2.0 Image to Video | Input images must have a long side no greater than 4096 pixels and an aspect ratio between 1:2.5 and 2.5:1.
Supported output resolutions are 480p, 720p, and 1080p. If the input image’s short side exceeds the selected resolution, or if its long side is smaller than the target, the image will be automatically resized so that the short side matches the chosen resolution. |Input: <10MB. Output: 5 seconds or 10 seconds|jpg/jpeg/png| * Error Codes | Error Category | Scenario / Description | Suggested Action | | -------------- | ---------------------- | ---------------- | | Invalid request parameters | Request parameters are invalid or missing | Verify that all request parameters are correct | | | Invalid parameter values (e.g., incorrect key or illegal value) | Check the error message field in the response and update the request parameters | | | Invalid request method | Review the API documentation and use the correct HTTP method | | | Requested resource does not exist (e.g., model not found) | Refer to the response error message field and correct the request parameters| | Trigger strategy | Platform policy has been triggered | Check whether any platform policies were violated | | | Content security policy triggered | Review and modify the input content, then resend the request | | | Request rate too high (rate limit exceeded)| Reduce request frequency, retry later, or contact customer service to increase limits | | | Concurrency or QPS exceeds quota | Reduce request frequency, or retry later | | Internal error | Internal server error | Retry later or contact customer service | | | Server temporarily unavailable | Retry later or contact customer service | | | Internal timeout due to request backlog| Retry later or contact customer service | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Video Generator (Standard) V1.0 | 3 (1 seconds) * | | AI Video Generator (Professional) V1.0 | 6 (1 seconds) * | | AI Video Generator (Image to Video) V2.0 | 1 unit (480p / 1 second(s)) *
2 units (720p / 1 second(s)) *
3 units (1080p / 1 second(s)) * | | AI Video Generator (Text to Video) V2.0 | 2 units (720p / 1 second(s)) *
3 units (1080p / 1 second(s)) * | > *If the number of images or video duration isn’t evenly divisible, units round up. --- - [AI Video Object Removal](https://docs.perfectcorp.com/reference/ai_video_object_removal.md): # Overview **AI Video Object Removal** ![](https://plugins-media.makeupar.com/smb/blog/post/2025-02-04/webp_537ec670-48c0-49fc-b96b-8073de21a64b.webp) The AI Video Object Removal API enables seamless removal of unwanted elements from video content. Whether dealing with crowded backgrounds filled with tourists, cluttered environments such as desks with tissues and bottles, or distracting reflections on glass surfaces, the API can precisely and reliably eliminate masked areas with high accuracy and consistency. --- ## Integration Guide **1. Prepare a Source Video and a Mask Image** The input video must not exceed 60 seconds in length, and the output video must have a long axis of 1920 pixels or less with a frame rate of 30 frames per second or below. **2. Upload File** Request upload URLs and file IDs via: ``` POST /s2s/v2.0/file ``` Input video: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_video_object_removal_input_edd43a2470.png) Reference input mask: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_video_object_removal_mask_4a1c9fb658.png) **3. Execute AI Task** ``` POST /s2s/v2.0/task/obj-rem-vid ``` Submit the task using file IDs or image URLs as input. The response returns a task_id for tracking and retrieving the result. **4. Retrieve Task Result** ``` GET /s2s/v2.0/task/obj-rem-vid/{task_id} ``` Use the task ID to track status and obtain results. [Webhooks](/develop/webhook.md) can be configured to receive asynchronous notifications on task completion with a success or error status. Polling is also supported by repeatedly calling the task endpoint until the status is updated from running to success or error. Usage is only charged when the task completes successfully. Output video sample: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_video_object_removal_output_eb7670cd9e.png) --- ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | | AI Video Object Removal | The input video must not exceed 60 seconds in length, and the output video must have a long axis of 1920 pixels or less with a frame rate of 30 frames per second or below. | Length limit: 60s | container: mov, mp4
video: MPEG-4, MPEG-4 AVC,
audio: aac, amr, mp3 | * Error Codes |Error Code|Description| | ---- | ---- | | error_download_video | Download source video error | | error_decode_video | Decode source video error | | error_unsupported_video | Unsupported video format | | exceed_max_filesize | Input file size exceeds the maximum limit| | error_nsfw_content_detected | NSFW content detected in the source file | | error_decode_mask | Decode mask image error | | invalid_parameter | Invalid parameter value| * 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 | --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Video Object Removal V2.1 | 2 (1 seconds) * | > *If the number of images or video duration isn’t evenly divisible, units round up. --- - [AI Video Style Transfer](https://docs.perfectcorp.com/reference/ai_video_style_transfer.md): # Overview Create unique videos with our AI Video Filters and Effects. Easily enhance each video with stunning AI styles. AI Video Filters with Instant Transformation. Experience a seamless transformation with AI video filters that apply stunning effects instantly. Choose from an array of unique styles, including pop art, retro, anime, and more, to add depth and creativity to every frame. Sample usage cases: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_video_style_transfer_S1_video_1_0_6d571a8bbb.jpg) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_video_style_transfe_S2_feature_03_0_6dd652a6f2.jpg) --- ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | | AI Video Face Swap | The input video must not exceed 30 seconds, 4K resolution, or 30 FPS, and the output is limited to 1280 long-side resolution, 16 FPS, and up to 30 seconds. | Length limit: 30s | container: mov, mp4
video: MPEG-4, MPEG-4 AVC,
audio: aac, amr, mp3 | * Error Codes |Error Code|Description| | ---- | ---- | | error_download_video | Download source video error | | error_decode_video | Decode source video error | | error_unsupported_video | Unsupported video format | | exceed_max_filesize | Input file size exceeds the maximum limit| | error_nsfw_content_detected | NSFW content detected in the source file | | error_decode_mask | Decode mask image error | | invalid_parameter | Invalid parameter value| --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Video Style Transfer V1.0 | 4 (1 seconds) * | > *If the number of images or video duration isn’t evenly divisible, units round up. --- - [AI Watch Virtual Try On](https://docs.perfectcorp.com/reference/ai_watch.md): # Overview Virtually Try-On AR Watches with Ease! Only One 2D Image Needed. With just a single 2D image upload, users can instantly try on top-notch watches virtually using our innovative AR-Watches App. This unique feature sets us apart in the world of e-commerce, making it easier than ever for customers to experience your products. ## Integration Guide This guide walks you through: * **Endpoint:** `/s2s/v2.0/task/2d-vto/watch` * **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY` * **Workflow:** 1. **Prepare a wrist image:** Uploading an image or provide a valid image URL of your wrist 1. **Prepare a watch image:** Uploading an image or provide a valid image URL of a watch product 1. **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response. 1. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `"success"` or `"error"`. --- * API Playground Interactively explore and test the API using our official playground: **API Playground:** [http://yce.makeupar.com/api-console/en/api-playground/ai-watch-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-watch-virtual-try-on/) --- * Authentication - Include your API key in the request header using **Bearer Token**: ``` Authorization: Bearer YOUR_API_KEY ``` You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/. * 1. Upload an Image You may upload a file directly to the server or provide a valid image URL in the VTO task payload. * Upload Endpoint ``` POST /s2s/v2.0/file ``` Alternatively, skip this step if you already have a public image URL. You may upload a file directly to the URL provided in the response from the File API and then use the corresponding `src_file_id` returned by the File API to invoke the AI task later. Or provide a valid image URL in the VTO task payload as `src_file_url`. The `src_file_id` or `src_file_url` will serve as the virtual try-on target. You must also provide another watch product image as a reference using `ref_file_ids` or `ref_file_urls` to be applied to your `src_file_id` or `src_file_url`. The AI engine supports automatic background removal for your watch product image. However, you may provide an occlusion mask image file for either your hand (`srcmsk_file_id` or `srcmsk_file_url`) or the watch product (`refmsk_file_ids` or `refmsk_file_urls`) to fine-tune the segmentation. --- * 2. Create a Watch VTO Task and Poll for Results Once you have an image and a template ID, create a task. The API processes the request asynchronously. You must poll the task status until it reaches `success` or `error`. * Create Task Endpoint ``` POST /s2s/v2.0/task/2d-vto/watch ``` * Polling Endpoint ``` GET /s2s/v2.0/task/2d-vto/watch/{task_id} ``` --- ## File Specs & Errors * AI Watch Virtual Try-On Specification **Supported Watch View** A watch image in a clear front view with the watch face unobstructed. The strap should be cropped to resemble a realistic wearing length. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/watch_product_01_aab8053028_50ab7fe9a5.jpg) **Supported Wrist View** The back of the wrist should be fully visible with all five fingers clearly shown and without any occlusion. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/watch_and_bracelet_user_01_09f16603cb_878dc89179.jpg) **watch\_wearing\_location: float (−0.3 to 1.0)** Indicates the position along the wrist: −0.3 represents near the main wrist joint 1.0 represents far from the main wrist joint Default value: null (use engine default) ![watch_wearing_location](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/bracelet_wearing_location_01ac0a048e.jpg) **watch\_shadow\_intensity: float (0.0 to 1.0)** Controls the strength of the shadow: 0.0 represents no shadow 1.0 represents maximum shadow Default value: 0.15 **watch\_ambient\_light\_intensity: float (0.0 to 1.0)** Defines the extent to which lighting references the target hand image: 0.0 ignores the hand image lighting 1.0 fully matches the hand image lighting and shadow rendering Default value: 1.0 **Watch Anchor Points: array of 4 points in pixel coordinate (optional)** The first two points mark the beginning and end of the strap when worn. The remaining two points mark the upper and lower edges of the watch case. ![watch_anchor_point](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Product_anchors_ece6851c88.jpg) --- * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Watch Virtual Try-On|long side <= 4096 |< 10MB|jpg/jpeg/png| * Error Codes |Error Code|Description| | ---- | ---- | | RUNTIME_ERROR | An unexpected error occurred duwatch runtime | | PHOTO_DETECTION_FAIL | The user photo could not be processed correctly, for example no hand detected | | OBJECT_DETECTION_FAIL | The object photo could not be processed correctly, for example no product detected | | PHOTO_CHECK_INVALID | The pose or size of the user photo is invalid | | INPUT_ERROR | The input file format is incorrect | | INPUT_MAIN_IMAGE_EMPTY | A user image is required | * 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 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Watch Virtual Try-On V1.0 | 1 Unit for Single-item wear | --- - [AI Wavy Hair Virtual Try-On](https://docs.perfectcorp.com/reference/ai_wavy_hair.md): # Overview Whether you're dreaming of bouncy ringlets, loose waves, or a bold curly statement, the YouCam API’s curly hair filter lets you experiment with a fresh, fabulous hairstyle in seconds—all from the comfort of home. Whether you're trying a soft wave or a bold afro, YouCam delivers a level of precision and realism that sets it apart. It's the ideal tool for exploring new hairstyles with confidence before your next salon visit. ![](https://plugins-media.makeupar.com/smb/blog/post/2025-04-01/webp_03963789-fb1e-4ad8-be4d-48932e247376.jpg) ![](https://plugins-media.makeupar.com/smb/blog/post/2025-03-20/b25b228a-259b-4efb-a7c1-31d200b62e8c.jpg) Suggestions for How to Shoot: ![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png "Suggestions for How to Shoot") --- ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Wavy Hair|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/png| * 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 --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Wavy Hair Virtual Try-On V1.0 | 1 | --- - [File Management](https://docs.perfectcorp.com/reference/file.md) - [AI Makeup Virtual Try-On](https://docs.perfectcorp.com/reference/makeup_vto.md): # Overview The AI Makeup API provides a powerful, hyper-realistic virtual makeover experience powered by our patented face-analyzing technology. This service enables your applications to apply true-to-life makeup effects onto user-provided selfie images with unprecedented customization capabilities. **Key Features:** * **Hyper-realistic Rendering:** Leverages revolutionary 3D face AI technology for the most realistic makeovers. * **Patented Technology:** Powered by jitter-free, lag-free deep learning algorithms optimized for all ages and ethnicities. * **Real-time Precision:** Ultra-precise facial tracking that adapts to various lighting conditions. * **True-to-life Matching:** Accurately matches real-world product colors, textures (from matte to metallic), and finishes. * Core Concepts * Color Blending Our AI accurately matches the color of real-life makeup products using deep learning. This ensures consumers are confident that the virtual color they see is the true color of the product they intend to purchase. * Texture & Finish Matching The technology simulates realistic textures and finishes, providing a highly accurate makeover experience. From matte to metallic, shimmer to satin, the AI taps into advanced algorithms to render these effects seamlessly in real-time. * Light Balancing The smart 3D AI engine detects lighting conditions in the user's photo or video feed. It corrects images for true-to-life makeup application, ensuring a consistent and high-quality result regardless of the environment. --- ## Integration Guide The Makeup Virtual Try-On service operates as an asynchronous task. You must first initiate a makeup processing task by providing the image URL and a list of desired effects. The server responds with a `task_id`. You then periodically poll a status endpoint to retrieve the final result or any errors. * **Endpoint:** `/v2.0/task/makeup-vto` * **Authentication:** All requests require an `Authorization: Bearer ` * **Workflow:** 1. **Prepare a selfie:** Upload an image or use existing file url of a face image. 1. **Start Task (`POST`):** Submit your image id/URL and makeup configuration. 1. **Retrieve Task ID:** Capture the `task_id` from the response. 1. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `"success"` or `"error"`. * API Playground Interactively explore and test the API using our official playground: **API Playground:** [http://yce.makeupar.com/api-console/en/api-playground/ai-makeup-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-makeup-virtual-try-on/) --- * Authentication - Include your API key in the request header using **Bearer Token**: ``` Authorization: Bearer ``` You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/. * 1. Upload a Selfie You can provide the source image in one of two ways: - **Use an Existing Public Image URL** Instead of uploading, you may supply a publicly accessible image URL directly when initiating the AI task. - **Upload via File API** Use the endpoint: ``` POST /s2s/v2.0/file ``` 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. * 2. Start Makeup Task `POST /s2s/v2.0/task/makeup-vto` Initiates a new virtual makeup task on the provided image. This endpoint is asynchronous and returns with a `task_id`. * Request Headers | Header | Value | |--------|-------| | Content-Type | `application/json` | | Authorization | `Bearer YOUR_API_KEY` | * Example Request Body ```json { "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/sample_Image_1_202b6bf6e6.jpg", "effects": [ { "category": "blush", "pattern": { "name": "2colors6" }, "palettes": [ { "color": "#FF0000", "texture": "matte", "colorIntensity": 50 }, { "color": "#F2A53E", "texture": "matte", "colorIntensity": 50 } ] }, { "category": "eye_liner", "pattern": { "name": "3colors5" }, "palettes": [ { "color": "#000000", "texture": "matte", "colorIntensity": 50 }, { "color": "#BA0656", "texture": "matte", "colorIntensity": 50 }, { "color": "#089085", "texture": "matte", "colorIntensity": 50 } ] } ], "version": "1.0" } ``` * Request Body Schema | Field | Type | Description | |-------|------|---------| | `src_file_url` | string (URL) | A publicly accessible URL to the selfie image to be processed. | | `effects` | array of Effect | An array of makeup effects objects to apply. See [Makeup Effect Schemas](#makeup-effect-schemas) for details. | | `version` | string | The API version of the effect payload structure. Use `"1.0"`. | * Successful Response (`200 OK`) Returns a JSON object containing the task identifier. **Response Body Schema:** ```json { "status": 200, "data": { "task_id": "" } } ``` **Example Response:** ```json { "status": 200, "data": { "task_id": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe" } } ``` * Error Responses (`400 Bad Request`, `401 InvalidApiKey`, etc.) A standard error object will be returned with a message describing the failure. **Example Error Response:** ```json { "status": 400, "error": "The operation could not be completed", "error_code": "CreditInsufficiency" } ``` --- * 3. Get Task Status & Results `GET /s2s/v2.0/task/makeup-vto/` Retrieves the current status and results of an in-progress or completed task. * Request Headers | Header | Value | |--------|-------| | Authorization | `Bearer YOUR_API_KEY` | * Path Parameters | Parameter | Type | Description | |-----------|------|---------| | task_id | string | The identifier returned from the start-task endpoint. | * Successful Response (`200 OK`) A JSON object containing the status and, if completed, the results. **Response Body Schema:** ```json { "data": { "task_status": "", // 'success', 'error', or a processing state (e.g., 'queued', 'processing') "results": [ // present only when task_status is 'success' { "download_url": "" // URL to download the processed image } ], "failure_reason": "" // present only when task_status is 'error' } } ``` **Example Success Response:** ```json { "status": 200, "data": { "task_status": "success", "results": { "url": "https://s3.storage.prod/processed/image_123.jpg?token=..." } } } ``` **Example Engine Error Response:** The API query was sent successfully; however, an error occurred while executing the AI task. ```json { "status": 200, "data": { "task_status": "error", "error": "exceed_max_filesize", "error_message": "string", } } ``` > Please note that no units will be consumed if an error occurs, whether it is a query error or an engine error. **Example In-Progress Response:** ```json { "status": 200, "data": { "task_status": "running" } } ``` * Error Responses * `404 InvalidTaskId`: The `task_id` does not exist or is invalid. * `401 InvalidApiKey`: The API key is invalid or missing. * `500 TaskTimeout`: The task has either completed successfully or failed and has exceeded the retention period. **Example Query Error Response:** ```json { "status": 401, "error_code": "InvalidApiKey" } ``` > Please note that no units will be consumed if an error occurs, whether it is a query error or an engine error. --- ## Inputs & Outputs * Makeup Effect Schema This section defines the complete structure and constraints for the request body of an AI Makeup task. Each effect is an object in the top-level `effects` array. * Effect Container (Top Level) ```json { "version": "1.0", "effects": [] // array — Contains makeup effect objects } ``` * Makeup Effect Categories * `skin_smooth` ```json { "category": "skin_smooth", // string, const "skin_smooth" "skinSmoothStrength": 50, // integer, range: 0..100 "skinSmoothColorIntensity": 50 // integer, range: 0..100 } ``` > **Note!** If no ``skin_smooth`` effect is included in the request, the AI Makeup Engine will automatically apply a default Skin Smooth value of 50. Set all ``skinSmoothStrength`` and ``skinSmoothColorIntensity`` parameters to 0 if you want makeup applied with no skin smoothing. However, for best results and highest-quality blending, it is recommended to leave the default skin smoothing enabled. * `blush` ```json { "category": "blush", // string, const "blush" "pattern": { // object "name": "" // string — MUST equal a `label` from blush.json }, "palettes": [ // array, minItems: (see colorNum in pattern) { "color": "#ff0000", // string, hex color "#RRGGBB" "texture": "matte", // string, enum ["matte","satin","shimmer"] "glowStrength": 50, // integer, range: 0..100 — REQUIRED if texture="satin" "shimmerColor": "#fc288f", // string, hex color "#RRGGBB" — REQUIRED if texture="shimmer" "shimmerDensity": 50, // integer, range: 0..100 — REQUIRED if texture="shimmer" "colorIntensity": 50 // integer, range: 0..100 } ] } ``` **Full Pattern Catalog:** https://plugins-media.makeupar.com/wcm-saas/patterns/blush.json **Distinct Makeup Pattern Categories:** ```json [ { "category": "1 color", "label": "1color1", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/483/a53cd4f4-43b6-4e19-b85a-ec7a95c6a47f.jpg", "tags": [ { "id": 100, "name": "Blush 3D" }, { "id": 103, "name": "Oblong" } ], "colorNum": 1 }, { "category": "2 colors", "label": "2colors1", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/147/a8d86a4b-8aa0-48d7-a716-63ec78dfb30b.jpg", "tags": [ { "id": 100, "name": "Blush 3D" } ], "colorNum": 2 }, { "category": "3 colors", "label": "3colors1", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/734/af8b625b-ae3a-4211-9413-f22c16a5f174.jpg", "tags": [ { "id": 100, "name": "Blush 3D" }, { "id": 104, "name": "Round" } ], "colorNum": 3 } ] ``` * `bronzer` ```json { "category": "bronzer", // string, const "bronzer" "pattern": { "name": "" }, // object — name MUST equal a `label` from bronzer.json "palettes": [ { "color": "#ff0000", "colorIntensity": 50 } // hex color, int range: 0..100 ] } ``` **Full Pattern Catalog:** https://plugins-media.makeupar.com/wcm-saas/patterns/bronzer.json **Distinct Makeup Pattern Categories:** ```json [ { "category": "Bronzer", "label": "Bronzer1", "thumbnail": "https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/973/22ff2c07-d584-4ae6-8281-c095cd121a52.jpg", "tags": [], "colorNum": 1 } ] ``` * `concealer` ```json { "category": "concealer", // string, const "concealer" "palettes": [ { "color": "#ff0000", // string, hex color "#RRGGBB" "colorIntensity": 50, // integer, range: 0..100 "colorUnderEyeIntensity": 50, // integer, range: 0..100 "coverageLevel": 50 // integer, range: 0..100 } ] } ``` * `contour` ```json { "category": "contour", // string, const "contour" "pattern": { "name": "" }, // object — name MUST equal a `label` from contour.json "palettes": [ { "color": "#ff0000", "colorIntensity": 50 } // hex color, int range: 0..100 ] } ``` **Full Pattern Catalog:** https://plugins-media.makeupar.com/wcm-saas/patterns/contour.json **Distinct Makeup Pattern Categories:** ```json [ { "category": "Heart face", "label": "HeartFace2", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/731/49a1b3b9-b393-4bf4-b486-1493fe468436.jpg", "tags": [] }, { "category": "Invtriangle", "label": "Invtriangle1", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/858/a94c8cca-5f8c-4b8b-a02d-94edb6a4ad7f.jpg", "tags": [] }, { "category": "Oval face", "label": "OvalFace6", "thumbnail": "https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/906/644368a3-7eee-4ad9-829e-e2b3d4320fec.jpg", "tags": [] }, { "category": "Round face", "label": "RoundFace4", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/106/3e455b5f-7e2d-46f7-8627-dc137051c144.jpg", "tags": [] }, { "category": "Triangle face", "label": "TriangleFace2", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/528/18765180-c254-4411-a25c-c1d78f5c3d77.jpg", "tags": [] } ] ``` * `eyebrows` ```json { "category": "eyebrows", // string, const "eyebrows" "pattern": { "type": "shape", // string, enum ["shape","color"], default: "shape" "name": "", // string, required when type="shape" — label from eyebrows.json "curvature": 0, // integer, range: -100..100 (shape only) "thickness": 0, // integer, range: -100..100 (shape only) "definition": 0 // integer, range: 0..100 (shape only) }, "palettes": [ { "color": "#ff0000", // string, hex color "#RRGGBB" "colorIntensity": 50, // integer, range: 0..100 "texture": "matte", // string, enum ["matte","shimmer"] "shimmerColor": "#fc288f", // string, hex color "#RRGGBB" — REQUIRED if texture="shimmer" "shimmerIntensity": 50, // integer, range: 0..100 — REQUIRED if texture="shimmer" "shimmerSize": 50, // integer, range: 0..100 — REQUIRED if texture="shimmer" "shimmerDensity": 50 // integer, range: 0..100 — REQUIRED if texture="shimmer" } ] } ``` **Full Pattern Catalog:** https://plugins-media.makeupar.com/wcm-saas/patterns/eyebrows.json **Distinct Makeup Pattern Categories:** ```json [ { "category": "Arrow", "label": "Arrow1", "thumbnail": "https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/490/1fb96bf9-979e-4327-a8c4-8c503f541f1a.jpg", "tags": [] }, { "category": "Curved", "label": "Curved1", "thumbnail": "https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/389/1ccb300e-c7ed-4995-920e-7d1bf8da1fad.jpg", "tags": [] }, { "category": "Drama", "label": "Drama2", "thumbnail": "https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/196/5fb14bec-553d-4841-bba7-ca7e5e27c12e.jpg", "tags": [] }, { "category": "High Arch", "label": "HighArch1", "thumbnail": "https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/609/7a8676dc-6f6a-4b12-aab0-c50328e448c5.jpg", "tags": [] }, { "category": "Original", "label": "Original2", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/300/123551e9-ca94-4732-89ed-5b3866678555.jpg", "tags": [] }, { "category": "Soft Arch", "label": "SoftArch1", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/121/2552ebf0-2705-43f7-b295-4fac21e18009.jpg", "tags": [] }, { "category": "Straight", "label": "Straight1", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/1/7734e777-8e51-41f1-abaf-205f0ed5e3b4.jpg", "tags": [] }, { "category": "Thin", "label": "Thin1", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/734/6ee10843-a251-4aa0-9183-db7f981d714d.jpg", "tags": [] }, { "category": "Upward", "label": "Upward4", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/751/76578317-f475-49c7-bd96-910ccad617ef.jpg", "tags": [] } ] ``` * `eye_liner` ```json { "category": "eye_liner", // string, const "eye_liner" "pattern": { "name": "" }, // object — name MUST equal a label from eyeliner.json "palettes": [ { "color": "#ff0000", // string, hex color "#RRGGBB" "texture": "matte", // string, enum ["matte","shimmer","metallic"] "shimmerColor": "#fc288f", // string, hex color "#RRGGBB" — REQUIRED if texture in ["shimmer","metallic"] "shimmerIntensity": 50, // integer, range: 0..100 — REQUIRED if texture in ["shimmer","metallic"] "metallicIntensity": 50, // integer, range: 0..100 — REQUIRED if texture="metallic" "colorIntensity": 50 // integer, range: 0..100 } ] } ``` **Full Pattern Catalog:** https://plugins-media.makeupar.com/wcm-saas/patterns/eyeliner.json **Distinct Makeup Pattern Categories:** ```json [ { "category": "2 colors", "label": "2colors1", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/419/71d9429a-dc08-4e80-9c46-6e55631ef766.jpg", "tags": [ { "id": 28, "name": "Drama" } ], "colorNum": 2 }, { "category": "3 colors", "label": "3colors2", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/208/056aa6cd-8678-470c-b111-b7653d7ddf93.jpg", "tags": [ { "id": 28, "name": "Drama" } ], "colorNum": 3 }, { "category": "1 color", "label": "Arabic3", "thumbnail": "https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/726/1919aad4-21a2-493a-a5f8-48bc99a61ba5.jpg", "tags": [ { "id": 26, "name": "Arabic" } ], "colorNum": 1 } ] ``` * `eye_shadow` ```json { "category": "eye_shadow", // string, const "eye_shadow" "pattern": { "name": "" }, // object — name MUST equal a label from eyeshadow.json "palettes": [ { "color": "#ff0000", // string, hex color "#RRGGBB" "texture": "matte", // string, enum ["matte","shimmer","metallic"] "shimmerColor": "#fc288f", // string, hex color "#RRGGBB" — REQUIRED if texture in ["shimmer","metallic"] "shimmerIntensity": 50, // integer, range: 0..100 — REQUIRED if texture in ["shimmer","metallic"] "metallicIntensity": 50, // integer, range: 0..100 — REQUIRED if texture="metallic" "colorIntensity": 50 // integer, range: 0..100 } ] // minItems: (see colorNum in pattern) } ``` **Full Pattern Catalog:** https://plugins-media.makeupar.com/wcm-saas/patterns/eyeshadow.json **Distinct Makeup Pattern Categories:** ```json [ { "category": "1 color", "label": "1color1", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/188/0322c4f9-e54d-4a6b-8072-6bb76560121a.jpg", "tags": [ { "id": 12, "name": "Artistic" }, { "id": 14, "name": "Dream" }, { "id": 15, "name": "Trend" } ], "colorNum": 1 }, { "category": "2 colors", "label": "2colors1", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/938/3348211c-1b83-4ab2-9c6a-ce06e4aa3528.jpg", "tags": [ { "id": 1, "name": "Fan shape" }, { "id": 8, "name": "Only upper lid" } ], "colorNum": 2 }, { "category": "3 colors", "label": "3colors1", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/542/55e1b0fd-b888-47ff-bd3a-3dc1af2a7b69.jpg", "tags": [ { "id": 1, "name": "Fan shape" }, { "id": 8, "name": "Only upper lid" } ], "colorNum": 3 }, { "category": "4 colors", "label": "4colors1", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/429/29cd5839-464b-4a7a-a5c1-c7b40e9464d7.jpg", "tags": [ { "id": 4, "name": "Closed banana" }, { "id": 10, "name": "Whole eye" } ], "colorNum": 4 }, { "category": "5 colors", "label": "5colors1", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/2/824dcf7c-1273-4a30-8f1f-2137926057d6.jpg", "tags": [ { "id": 4, "name": "Closed banana" }, { "id": 10, "name": "Whole eye" } ], "colorNum": 5 } ] ``` * `eyelashes` ```json { "category": "eyelashes", // string, const "eyelashes" "pattern": { "name": "" }, // object — name MUST equal a label from eyelashes.json "palettes": [ { "color": "#ff0000", "colorIntensity": 50 } // hex color, int range: 0..100 ] } ``` **Full Pattern Catalog:** https://plugins-media.makeupar.com/wcm-saas/patterns/eyelashes.json **Distinct Makeup Pattern Categories:** ```json [ { "category": "Artistic", "label": "Artistic1", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/146/7a8ed606-1c27-4d91-9320-c40a904f621f.jpg", "tags": [] }, { "category": "Natural", "label": "Natural1", "thumbnail": "https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/287/cd5cae75-a1b3-48f8-8537-e6e259213901.png", "tags": [] }, { "category": "Upper&Lower", "label": "Upper&Lower1", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/18/2689ea2d-725e-4fa0-8563-df874ae1a83f.jpg", "tags": [] }, { "category": "Upper", "label": "Upper1", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/982/c99bf74e-545f-4da7-a314-f3bd84b82156.jpg", "tags": [] }, { "category": "UpperDense", "label": "UpperDense1", "thumbnail": "https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/888/452ec863-f0a8-40e7-aa33-31c0c39f57e2.jpg", "tags": [] }, { "category": "Winged", "label": "Winged1", "thumbnail": "https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/825/36ab3859-eae5-49e4-9d97-161698bbb8bb.jpg", "tags": [] }, { "category": "Wispies", "label": "Wispies1", "thumbnail": "https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/722/a2a727f6-748c-41e7-8ac0-c9c57c18c05a.png", "tags": [] } ] ``` * `foundation` ```json { "category": "foundation", // string, const "foundation" "palettes": [ { "color": "#ff0000", // string, hex color "#RRGGBB" "colorIntensity": 50, // integer, range: 0..100 "glowIntensity": 50, // integer, range: 0..100 "coverageIntensity": 50 // integer, range: 0..100 } ] } ``` * `highlighter` ```json { "category": "highlighter", // string, const "highlighter" "pattern": { "name": "" }, // object — name MUST equal a label from highlighter.json "palettes": [ { "color": "#ff0000", // string, hex color "#RRGGBB" "glowIntensity": 50, // integer, range: 0..100 "shimmerIntensity": 50, // integer, range: 0..100 "shimmerDensity": 50, // integer, range: 0..100 "shimmerSize": 50, // integer, range: 0..100 "colorIntensity": 50 // integer, range: 0..100 } ] } ``` **Full Pattern Catalog:** https://plugins-media.makeupar.com/wcm-saas/patterns/highlighter.json **Distinct Makeup Pattern Categories:** ```json [ { "category": "Heart face", "label": "HeartFace4", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/246/6ca40279-79cc-4918-b48a-64306009b365.jpg", "tags": [] }, { "category": "Invtriangle", "label": "Invtriangle2", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/7/6b0b9760-612c-4319-bd81-855d262d8e89.jpg", "tags": [] }, { "category": "Oblong", "label": "Oblong11", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/862/b7279f4e-edf2-43f3-8156-561fe5a52ec3.jpg", "tags": [] }, { "category": "Oval face", "label": "OvalFace2", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/369/91097a05-9fd2-43cb-82e9-dd45e72b613b.jpg", "tags": [] }, { "category": "Round face", "label": "RoundFace3", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/520/2d3ccbe2-36c3-43df-9e78-4c2c931fa431.jpg", "tags": [] }, { "category": "Square face", "label": "SquareFace3", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/989/2959777b-19ca-4f4a-a023-3c8927191497.jpg", "tags": [] }, { "category": "Triangle face", "label": "TriangleFace3", "thumbnail": "https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/765/221c1f12-c621-4567-a8ee-1433038ee8a2.jpg", "tags": [] } ] ``` * `lip_color` ```json { "category": "lip_color", // string, const "lip_color" "shape": { // object — driven by lipshape.json "name": "original" // string — MUST equal a `label` from lipshape.json }, "morphology": { // optional object "fullness": 50, // integer, range: 0..100 (default: 0) "wrinkless": 50 // integer, range: 0..100 (default: 0) }, "palettes": [ // minItems depends on style; often ≥1 { "color": "#ff0000", // string, hex color "#RRGGBB" "texture": "matte", // string, enum ["matte","gloss","holographic","metallic","satin","sheer","shimmer"] "colorIntensity": 50, // integer, range: 0..100 "gloss": 50, // int, range: 0..100 — REQUIRED if texture in ["gloss","holographic","metallic","sheer","shimmer"] "shimmerColor": "#ff0000", // string, hex color "#RRGGBB" — REQUIRED if texture in ["holographic","metallic","shimmer"] "shimmerIntensity": 50, // integer, range: 0..100 — REQUIRED if texture in ["holographic","metallic","shimmer"] "shimmerDensity": 50, // integer, range: 0..100 — REQUIRED if texture in ["holographic","metallic","shimmer"] "shimmerSize": 50, // integer, range: 0..100 — REQUIRED if texture in ["holographic","metallic","shimmer"] "transparencyIntensity": 50 // integer, range: 0..100 — REQUIRED if texture in ["gloss","sheer","shimmer"] } ], "style": { "type": "full", // string, enum ["full","ombre","twoTone"] "innerRatio": 50, // int, range: 0..100 — REQUIRED if type="ombre" "featherStrength": 50 // int, range: 0..100 — REQUIRED if type="ombre" } } ``` **Full Pattern Catalog:** https://plugins-media.makeupar.com/wcm-saas/shapes/lipshape.json **Distinct Makeup Pattern Categories:** ```json [{ "category": "general", "label": "original", "thumbnail": "https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/original.png", "tags": [ ] }, { "category": "general", "label": "heart-shaped", "thumbnail": "https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/heart-shaped.jpg", "tags": [ ] }, { "category": "general", "label": "m-shaped", "thumbnail": "https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/m-shaped.jpg", "tags": [ ] }, { "category": "general", "label": "petal", "thumbnail": "https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/petal.jpg", "tags": [ ] }, { "category": "general", "label": "plump", "thumbnail": "https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/plump.jpg", "tags": [ ] }, { "category": "general", "label": "pouty", "thumbnail": "https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/pouty.jpg", "tags": [ ] }, { "category": "general", "label": "smile", "thumbnail": "https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/smile.jpg", "tags": [ ] }, { "category": "general", "label": "vintage", "thumbnail": "https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/vintage.jpg", "tags": [ ] } ] ``` * `lip_liner` ```json { "category": "lip_liner", // string, const "lip_liner" "pattern": { "name": "" }, // object — name MUST equal a label from lipliner.json "palettes": [ { "color": "#ff0000", // string, hex color "#RRGGBB" "texture": "matte", // string, enum ["matte","satin"] "colorIntensity": 50, // integer, range: 0..100 "thickness": 50, // integer, range: 0..100 "smoothness": 50 // integer, range: 0..100 } ] } ``` **Full Pattern Catalog:** https://plugins-media.makeupar.com/wcm-saas/patterns/lipliner.json **Distinct Makeup Pattern Categories:** ```json [ { "category": "Large & Full", "label": "Large&Full1", "thumbnail": "https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/417/7ac66cb2-2c7b-451c-8284-cc77791b7001.jpg", "tags": [] }, { "category": "Larger Lower", "label": "LargerLower1", "thumbnail": "https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/878/84b2ef48-3af4-4851-86d2-b01d10db82b2.jpg", "tags": [] }, { "category": "Larger Upper", "label": "LargerUpper1", "thumbnail": "https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/867/674f9f4c-7961-462e-8cc9-9a8acaad4168.jpg", "tags": [] }, { "category": "Natural", "label": "Natural1", "thumbnail": "https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/258/7533c08a-cc9c-45ab-9294-5d5a8114037d.jpg", "tags": [] }, { "category": "Rosebud", "label": "Rosebud1", "thumbnail": "https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/47/eb95e91f-6ef1-41f7-bc4f-aecd7d780c42.jpg", "tags": [] }, { "category": "Small", "label": "Small1", "thumbnail": "https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/396/6b78e461-24a6-4c6d-afb4-88beb71f1732.jpg", "tags": [] }, { "category": "Wider", "label": "Wider1", "thumbnail": "https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/867/21f92b70-72b5-4a57-b4d7-81c5cce757a6.jpg", "tags": [] } ] ``` --- ## Example Payload Here is a full example of a valid `effectJson` payload applying multiple effects. ```json { "version": "1.0", "effects": [ { "category": "skin_smooth", "skinSmoothStrength": 55, "skinSmoothColorIntensity": 45 }, { "category": "blush", "pattern": { "name": "2colors1" }, "palettes": [ { "color": "#e19f9f", "texture": "matte", "colorIntensity": 60, "shimmerColor": "#d63252", "shimmerDensity": 50 }, { "color": "#c98a8a", "texture": "satin", "glowStrength": 40, "colorIntensity": 70 } ] }, { "category": "lip_color", "shape": { "name": "plump" }, "morphology": { "fullness": 30, "wrinkless": 25 }, "style": { "type": "full" }, "palettes": [ { "color": "#e11c43", "texture": "gloss", "colorIntensity": 80, "gloss": 75 } ] } ] } ``` In this example, `blush` uses the the `2colors1` pattern from the `blush.json`, which requires exactly two palettes. The `lip_color` effect uses the the `plump` shape from `lipshape.json`. ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Makeup Virtual Try-On|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) |error_face_position_invalid |Please ensure your entire face is fully visible within the image| |error_face_position_too_small|The detected face is too small. Move closer to the camera| |error_face_position_out_of_boundary|The face is too large or partially outside the image frame. Adjust your position| |error_face_angle_invalid|The face angle is incorrect. For front-facing photos, keep your head within 10°. For side-facing photos, ensure more than 15°.| * 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 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Makeup Virtual Try-On V1.0 | 1 | --- - [YouCam API](https://docs.perfectcorp.com/reference/openapi-base.md): YouCam API - [AI Ring Virtual Try-On](https://docs.perfectcorp.com/reference/ring_vto.md): # Overview Easily Create Your AR Ring or Engagement Ring Try Ons. You Only Need to Upload Images. Opt for 2D images for effortless yet high-quality virtual try-on experiences with minimal effort. ## Integration Guide This guide walks you through: * **Endpoint:** `/s2s/v2.0/task/2d-vto/ring` * **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY` * **Workflow:** 1. **Prepare a hand image:** Uploading an image or provide a valid image URL of your hand 1. **Prepare a ring image:** Uploading an image or provide a valid image URL of a ring product 1. **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response. 1. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `"success"` or `"error"`. --- * API Playground Interactively explore and test the API using our official playground: **API Playground:** [http://yce.makeupar.com/api-console/en/api-playground/ai-ring-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-ring-virtual-try-on/) --- * Authentication - Include your API key in the request header using **Bearer Token**: ``` Authorization: Bearer YOUR_API_KEY ``` You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/. * 1. Upload an Image You may upload a file directly to the server or provide a valid image URL in the VTO task payload. * Upload Endpoint ``` POST /s2s/v2.0/file ``` Alternatively, skip this step if you already have a public image URL. You may upload a file directly to the URL provided in the response from the File API and then use the corresponding `src_file_id` returned by the File API to invoke the AI task later. Or provide a valid image URL in the VTO task payload as `src_file_url`. The `src_file_id` or `src_file_url` will serve as the virtual try-on target. You must also provide another ring product image as a reference using `ref_file_ids` or `ref_file_urls` to be applied to your `src_file_id` or `src_file_url`. The AI engine supports automatic background removal for your ring product image. However, you may provide an occlusion mask image file for either your hand (`srcmsk_file_id` or `srcmsk_file_url`) or the ring product (`refmsk_file_ids` or `refmsk_file_urls`) to fine-tune the segmentation. --- * 2. Create a Ring VTO Task and Poll for Results Once you have an image and a template ID, create a task. The API processes the request asynchronously. You must poll the task status until it reaches `success` or `error`. * Create Task Endpoint ``` POST /s2s/v2.0/task/2d-vto/ring ``` * Polling Endpoint ``` GET /s2s/v2.0/task/2d-vto/ring/{task_id} ``` --- ## File Specs & Errors * AI Ring Virtual Try-On Specification **Supported Ring View** The ring image must be provided in a three-quarter front view (approximately 45 degrees). ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_product_01_9a4d0680f2_b46afe9a53.jpg) **Supported Hand View** The back of the hand should be fully visible with all five fingers clearly shown and without any occlusion. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_user_01_6d9893abd0_c7427cdb78.jpg) **ring\_wearing\_finger: integer (0–4)** Specifies the finger on which the ring is worn: 0 = Thumb 1 = Index finger 2 = Middle finger 3 = Ring finger 4 = Little finger **ring\_wearing\_location: float (0.0–1.0)** Indicates the position along the finger: 0.0 = Near the MCP joint (large knuckle) 1.0 = Near the PIP joint (middle joint) ![ring_wearing_location](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_wearing_location_59567be4af.jpg) **ring\_shadow\_intensity: float (0.0–1.0)** Controls the shadow strength: 0.0 = No shadow 1.0 = Maximum shadow Default: 0.15 **ring\_ambient\_light\_intensity: float (0.0–1.0)** Defines how much the lighting references the target hand image: 0.0 = Ignore the hand image lighting 1.0 = Fully match the hand image lighting and shadow rendering Default: 1.0 **ring\_anchor\_point: array of two points in pixel coordinate (optional)** Marks the inner edge of the ring where it contacts the finger, specifying the left and right points. This is particularly useful for wide or thick rings. If this parameter is not provided, the AI engine will automatically detect the anchor points. ![ring_anchor_point](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_anchor_point_e6eb241ef8.jpg) --- * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Ring Virtual Try-On|long side <= 4096 |< 10MB|jpg/jpeg/png| * Error Codes |Error Code|Description| | ---- | ---- | | RUNTIME_ERROR | An unexpected error occurred during runtime | | PHOTO_DETECTION_FAIL | The user photo could not be processed correctly, for example no hand detected | | OBJECT_DETECTION_FAIL | The object photo could not be processed correctly, for example no product detected | | PHOTO_CHECK_INVALID | The pose or size of the user photo is invalid | | INPUT_ERROR | The input file format is incorrect | | INPUT_MAIN_IMAGE_EMPTY | A user image is required | * 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 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Ring Virtual Try-On V1.0 | 1 Unit for Single-item wear
2 Units for Stacked wear | --- - [Task Management](https://docs.perfectcorp.com/reference/task_management.md) - [Unit system](https://docs.perfectcorp.com/reference/unit_system.md): Check your unit details and usage history. Please note that Units is the currency used for YouCam API operations; different AI features deduct different amounts of units. In this document, the code name used for a Unit is "Credit."