# 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_aging.md) - [Release Notes](https://docs.perfectcorp.com/release/changelog.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_abs_filter.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_lift.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_face_swap.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_face_analyzer.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_background_replace.md) - [Overview](https://docs.perfectcorp.com/reference/description/ai_video_enhance.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/ai_watermark_removal.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](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) - [YouCam スキル](https://docs.perfectcorp.com/ja/develop/agent_skills.md) - [API プレイグラウンド](https://docs.perfectcorp.com/ja/develop/api_playground.md) - [API サーバー](https://docs.perfectcorp.com/ja/develop/api_server.md) - [デバッグガイド](https://docs.perfectcorp.com/ja/develop/debugging_guide.md) - [エラーコード](https://docs.perfectcorp.com/ja/develop/error_codes.md) - [FAQ](https://docs.perfectcorp.com/ja/develop/faq.md) - [ファイル保持期間](https://docs.perfectcorp.com/ja/develop/file_retention_period.md) - [MCP](https://docs.perfectcorp.com/ja/develop/mcp.md) - [クイックスタートガイド](https://docs.perfectcorp.com/ja/develop/quick_start_guide.md) - [レート制限](https://docs.perfectcorp.com/ja/develop/rate_limit.md) - [Webhook](https://docs.perfectcorp.com/ja/develop/webhook.md) - [リリースノート](https://docs.perfectcorp.com/ja/release/changelog.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_2d_vto_bracelet.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_2d_vto_earring.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_2d_vto_necklace.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_2d_vto_ring.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_2d_vto_watch.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_abs_filter.md) - [YouCam API ドキュメント | Perfect Corp.](https://docs.perfectcorp.com/ja/develop/introduction.md): Perfect Corp. による YouCam API ドキュメント。肌分析 API、バーチャル試着 API、画像編集 API、動画生成 AI API の使い方を学びましょう。 - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_aging.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_avatar_generator.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_bag.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_beard_style.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_clothes.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_color_correction.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_eye_color_lens.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_fabric.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_face_analyzer.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_face_lift.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_face_swap.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_face_tone_analyzer.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_fitzpatrick_skin_type.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_frizziness_detection.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_hair_density_detection.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_hair_length.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_hair_type.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_hat.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_headshot_generator.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_image_to_video.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_look_vto.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_makeup_transfer.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_nail_transfer.md) - [概要 (Overview)](https://docs.perfectcorp.com/ja/reference/description/ai_makeup_vto.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_object_removal_pro.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_photo_background_blur.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_photo_background_change.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_replace.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_scarf.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_shoes.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_smile.md) - [概要 (Overview)](https://docs.perfectcorp.com/ja/reference/description/ai_skin_analysis.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_studio_generator.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_teeth_whitening.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_video_background_replace.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_video_enhance.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_video_face_swap.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_video_object_removal.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/ai_video_style_transfer.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/body_reshape_task.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/breast_shape_task.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/colorize_task.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/enhance_task.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/hair_bang_task.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/face_reshape_task.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/hair_color_task.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/hair_curl_task.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/hair_ext_task.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/hair_style_task.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/hair_vol_task.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/image_extender.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/lighting_task.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/nail_vto_task.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/obj_removal_task.md) - [polling_guide.md](https://docs.perfectcorp.com/ja/reference/description/polling_guide.md) - [pre_process_guide.md](https://docs.perfectcorp.com/ja/reference/description/pre_process_guide.md) - [pre_process_index.md](https://docs.perfectcorp.com/ja/reference/description/pre_process_index.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/sod_task.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/skin_simulation_task.md) - [概要](https://docs.perfectcorp.com/ja/reference/description/text_to_image.md) - [Webhook](https://docs.perfectcorp.com/ja/reference/description/webhook.md) - [Overview](https://docs.perfectcorp.com/ja/reference/description/ai_watermark_removal.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. | | error_multi_person | The system detected multiple individuals in the source or reference image under a "normal" or "strict" multi-person filter setting. | * 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.overall` | 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/png| * 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 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 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 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 YOUR_API_KEY" }; 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-transfer` * **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 your footwear. * 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-transfer`) 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-transfer \ --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-transfer/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 | Foot visible, full body 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://plugins-media.makeupar.com/strapi/assets/small_Shoes_3_428e8dddb1.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://plugins-media.makeupar.com/strapi/assets/small_Shoes_2_ec3578c5c2.jpg) ![](https://plugins-media.makeupar.com/strapi/assets/small_Shoes_9_52a61e0935.jpg) **Supported Selfie View** * Recommended image resolution: at least 512 × 512 pixels. * Single Subject Requirement: The image must contain exactly one human subject. No additional people or partial figures are allowed. * Foot Visibility: The subject's foot must be fully visible without obstruction. ![](https://plugins-media.makeupar.com/strapi/assets/small_clothes_04_441e848298.png) --- * 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 Shoes Virtual Try-On V3.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 2560 pixels on the long side and at least 480 pixels on the short side for SD, or up to 2560 pixels on the long side and at least 1080 pixels on the short side for HD. See details in **[File Specs & Errors](#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/png | * 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 Style Transfer | 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. * The watch must be upright and front-facing — placing it flat (horizontally) will produce incorrect results. * The back of the strap (e.g., the clasp) must not appear in the image — only the front-facing strap should be visible. ![](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 Watermark Removal](https://docs.perfectcorp.com/reference/ai_watermark_removal.md): # Overview AI-Powered Watermark Removal Reliably detect and erase watermarks, logos, and other marks while preserving the image's original quality and details. > Use the tool responsibly to avoid unethical applications, such as removing watermarks for unauthorized commercial use. Respect the intended purpose of the image and adhere to fair use principles. ![](https://d32qvgpd29lguw.cloudfront.net/Watermark_Remover_BA_Image_24bf9f2ed1.png) --- ## Integration Guide * AI Watermark Removal Usage Guide This guide explains how to upload images, prepare reference outfits, and create virtual try-on tasks using the AI Watermark Removal. *** * Step 1. Upload a File Using the File API Use the **File API** (`/s2s/v2.0/file`) to upload a target image. *** * Step 2. Retrieve File API Response The response includes: * `file_id` for creating an AI task. * `requests.url` for uploading the actual image file. *** * Step 3. Upload Image to Provided URL Use the `requests.url` from the File API response to upload the image: *** * Step 4. Create an AI Task Use the **AI Task API** (`/s2s/v2.0/task/wmk-removal`) to create an AI task. *** * Step 5. 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/wmk-removal/ \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' ``` *** * Step 6. 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://d32qvgpd29lguw.cloudfront.net/Watermark_Remover_BA_2_c8bbf561af.png) ## File Specs & Errors * Supported Formats & Dimensions |Type|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | | AI Watermark Removal | max side 4096 px | < 10MB | jpg/png | > Removing watermarks can be illegal if done without the copyright owner’s consent or for unauthorized purposes. Always ensure you have proper rights to the image. * Error Codes | Error code | Description | | ---------- | ----------- | | invalid_parameter |The parameter(s) is missing or invalid. | | error_download_image | The image could not be downloaded. | | exceed_max_filesize | The image is too large. The file size must not exceed 10 MB. The long side must not exceed 4096 pixels. | | error_below_min_image_size | The image is too small. The long side must be at least 128 pixels. | | 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 | Something went wrong on our end while processing this request. | * 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 Watermark Removal | 1 | --- - [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." - [AI 腹筋](https://docs.perfectcorp.com/ja/reference/ai_abs_filter.md): # 概要 **AI 腹筋 API** で、写真に腹筋の輪郭を追加します。全身または上半身の画像をアップロードし、補正モードと強度レベルを設定します。 ![](https://plugins-media.makeupar.com/smb/blog/post/2024-09-27/daf70f5e-a350-46a3-8b6c-f63bd60c6cf0.jpg) 対応モード: - `Six-pack`: シックスパックを追加します。 - `Vest-line`: 腹部中央の筋肉の輪郭を強調します。 --- ## 統合ガイド **入力要件と処理基準:** - 全身または上半身の画像をアップロードします。 - 補正モードを選択します: `Six-pack` または `Vest-line`。 - 希望する腹筋補正の強度レベルを選択します。 - 画像の長辺の最大解像度は **4096 px** を超えてはなりません。 - ソースファイルサイズは **10 MB** 未満である必要があります。 - 両肩が確認できる、検出可能な人物が少なくとも 1 人必要です。 - 腹部が確認できる必要があります（衣服を着用している場合も、着用していない場合も可）。 - 対応ポーズ範囲: `−45° < yaw < 45°`。 - 単一人物の処理に対応しています。画像内に複数の人物が写っている場合、API は可視肩面積が最も大きい人物を自動的に選択します。 **ワークフロー:** 1. File API を使用してファイルメタデータをアップロードします。 2. レスポンスから署名付きアップロード URL を取得します。 3. 返された URL に実際の画像をアップロードします。 4. 腹筋形状補正用の AI タスクを作成します。 5. Webhook を設定するか、完了するまでタスクステータスをポーリングします。 6. 処理が成功したら、生成された結果画像をダウンロードします。 --- **ステップ 1 — File API を使用してファイルメタデータをアップロードする** `POST /s2s/v2.0/file` を使用してファイルレコードを作成し、ソース画像のアップロード詳細を受け取ります。 ```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 サンプルレスポンス:** ```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" } } ] } ] } } ``` --- **ステップ 2 — File API レスポンスの詳細を取得する** レスポンスには以下が含まれます: | フィールド | 説明 | | --- | --- | | `file_id` | AI タスクの作成に使用される識別子。 | | `requests.url` | 実際の画像ファイルをアップロードするための署名付き URL。 | | `requests.method` | アップロードメソッド、通常は `PUT`。 | | `requests.headers` | アップロードリクエストに必要なヘッダー。 | --- **ステップ 3 — 提供された URL に画像をアップロードする** File API レスポンスの `requests.url` を使用して、ソース画像をアップロードします。 ```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' ``` --- **ステップ 4 — AI タスクを作成する** `POST /s2s/v2.0/task/abs-shape` を使用して、腹筋補正タスクを作成します。 | パラメータ | 説明 | 例 | | --- | --- | --- | | `src_file_id` | File API アップロードフローから返されるファイル ID。アップロードファイルワークフローを使用する場合に必須。 | `"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud"` | | `src_file_url` | ソース画像の直接 URL。`src_file_id` の代替として使用します。 | `"https://example.com/selfie.jpg"` | | `mode` | 補正モード。対応値は `Six-pack` と `Vest-line` です。 | `"Six-pack"` | | `intensity` | 腹筋補正の強度レベル。 | `1` | **リクエスト例:** ```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 タスク API レスポンス:** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` --- **ステップ 5 — Webhook の設定またはタスク結果のポーリング** 設定および検証の詳細については、[Webhook 統合ガイド](../develop/webhook.md) を参照してください。 ポーリングの場合は、返された `task_id` を使用してタスクステータスを確認します。 ```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' ``` --- **ステップ 6 — 結果画像の取得** 処理が成功すると、レスポンスに `data.results.url` にダウンロード URL が含まれます。 ```json { "status": 200, "data": { "error": null, "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..." }, "task_status": "success" } } ``` **無効な API キーのレスポンス:** アクセストークンが無効な場合、API は `401` レスポンスを返します。 ```json { "status": 401, "error": "Unauthorized", "error_code": "InvalidAccessToken" } ``` ユースケース: ![](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) --- ## ファイル仕様とエラー **ファイル仕様:** | 仕様 | 要件 | | --- | --- | | 画像タイプ | 全身または上半身の画像。 | | ソース被写体 | 両肩と腹部が確認できる、検出可能な人物 1 人。 | | ポーズ要件 | 対応ポーズ範囲は `−45° < yaw < 45°` です。 | | 複数人物の処理 | 複数の人物が検出された場合、API は可視肩面積が最も大きい人物を自動的に選択します。 | | 長辺の最大解像度 | 長辺は **4096 px** を超えてはなりません。 | | ファイルサイズ制限 | **10 MB** 未満である必要があります。 | | 対応フォーマット | `jpg`, `png`。 | **エラーコード:** | エラーコード | 説明 | | --- | --- | | `exceed_max_filesize` | ソース画像が最大許容寸法またはファイルサイズを超えています。長辺は 4096 px を超えてはならず、ファイルサイズは 10 MB 未満を維持する必要があります。 | | `error_pose` | 人物検出の欠如、肩の可視性の問題、腹部の可視性の問題、腰部領域の検出失敗、股関節キーポイントの検出失敗、または非対応のポーズ範囲により、ポーズ検出が失敗しました。 | | `error_nsfw_content_detected` | ソース画像または生成された結果画像に潜在的な NSFW コンテンツが検出されました。 | | `invalid_parameter` | ソースキー、宛先キー、アクション、モード値、強度レベル、またはタスク設定に対して無効なパラメータが提供されました。 | | `error_download_image` | ソース画像を正常にダウンロードできませんでした。 | | `error_decode_image` | ソース画像を正常にデコードできませんでした。 | **環境と依存関係:** | ツール / 言語 | 推奨ランタイムバージョン | | --- | --- | | cURL | Bash ≥ 3.2; curl ≥ 7.58 (モダンな TLS/HTTP 対応); jq ≥ 1.6 (堅牢な JSON 解析用)。 | | Node.js | グローバル `fetch` 対応のため Node ≥ 18。 | | JavaScript ブラウザ対応 | Chrome / Edge ≥ 80, Firefox ≥ 74, Safari ≥ 13.1。 | | PHP | モダンな TLS 互換性のため PHP ≥ 7.4; ext-curl を推奨、または OpenSSL と JSON 対応で `allow_url_fopen=On`。 | | Python | f-strings のため Python ≥ 3.10; requests ≥ 2.20.0。 | | Java | HttpClient のため Java 11+; Jackson Databind ≥ 2.12.0。 | --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | AI 腹筋 V1.0 | 1 | --- - [AI 老け顔](https://docs.perfectcorp.com/ja/reference/ai_aging_simulation.md): # 概要 生成 AI モデルによる AI 老け顔では、1 枚のセルフィー画像から若年期から老年期までの一連の写真を生成します。現在の年齢の推定や、未来・過去の自分の姿の確認ができます。 ![AI 老け顔](https://bcw-media.s3.ap-northeast-1.amazonaws.com/f42f1504_79e3_461c_a3f1_a254623d113b_b068736afb.jpg "AI 老け顔") 1 枚の入力セルフィー画像から一連の写真を生成します。生成写真のサンプルを以下に示します。 ![AI 老け顔](https://bcw-media.s3.ap-northeast-1.amazonaws.com/U_2024_04_17_cr_12112b83e2.png "AI 老け顔") ## ファイル仕様とエラー * 対応フォーマットと解像度 | AI 機能 | 対応解像度 | 対応ファイルサイズ | 対応フォーマット | | ---- | ---- | ---- | ---- | | AI 老け顔 | 長辺 <= 4096、1 人のみ。顔の姿勢制約：ヨー角 ±30° 以内、ロール角 ±20° 以内、ピッチ角 ±20° 以内。 | < 10MB | jpg/jpeg | * エラーコード |エラーコード|説明| | ---- | ---- | | error_below_min_image_size | 元画像の解像度は 320 ピクセル以上である必要があります。 | | error_face_position_invalid | 顔が完全に視認可能で、正面を向いており、画像の中央に配置されている必要があります。 | | error_face_position_too_small | 検出された顔が分析するには小さすぎます。 | | error_face_position_out_of_boundary | 顔が画像の境界を超えています。 | | error_face_not_forward_facing | 顔がカメラを直接向いている必要があります。 | | error_face_angle_upward | 顔が上向きに傾きすぎています。頭をわずかに下げてください。 | | error_face_angle_downward | 顔が下向きに傾きすぎています。頭をわずかに上げてください。 | | error_face_angle_leftward | 顔が左向きに回りすぎています。頭をわずかに右へ回してください。 | | error_face_angle_rightward | 顔が右向きに回りすぎています。頭をわずかに左へ回してください。 | | error_face_angle_left_tilt | 顔が左に傾きすぎています。頭を右にわずかに傾けてください。 | | error_face_angle_right_tilt | 顔が右に傾きすぎています。頭を左にわずかに傾けてください。 | --- ## ユニット消費量 | AI 機能 | 消費ユニット数 | |---|---| | AI 老け顔 V1.0 | 2 | --- - [AI アバター](https://docs.perfectcorp.com/ja/reference/ai_avatar_generator.md): # 概要 AI マジックアバターツールでは、画像から画像への生成技術（image-to-image）を使います。つまり、アバターはユーザーの写真に基づいて生成されます。写真を選ぶと、アプリに組み込まれた技術がユーザーの顔の特徴を分析し、学習を開始します。 より多くのアバタースタイルについては、https://yce.makeupar.com/avatar を参照してください。 ユースケース: ![AI アバター](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Christmas_Avatar_b861c35edf.jpg "AI アバター") ![AI アバター](https://plugins-media.makeupar.com/smb/blog/post/2023-04-06/fc2c3b2e-2b7f-48c9-96c1-cdb780f9dc1d.jpg "AI アバター") 撮影時の推奨事項: ![撮影時の推奨事項](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png "撮影時の推奨事項") --- ## ファイル仕様とエラー * 対応フォーマットとサイズ | AI 機能 | 対応サイズ | 対応ファイルサイズ | 対応フォーマット | | ---- | ---- | ---- | ---- | | AI アバター | 入力: 長辺 <= 4096、出力: 長辺 <= 1024 | < 10MB | jpg/jpeg/png | * エラーコード |エラーコード|説明| | ---- | ---- | | exceed_max_filesize | 入力ファイルサイズが最大制限を超えています | | invalid_parameter | パラメータ値が無効です | | error_download_image | ソース画像のダウンロードに失敗しました | | error_decode_image | ソース画像のデコードに失敗しました | | error_nsfw_content_detected | ソース画像に NSFW コンテンツが検出されました | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI アバター V3.0 | 4 枚あたり 1 ユニット * | > *画像数または動画の長さが割り切れない場合、ユニット数は切り上げられます。 --- - [AI 背景透過](https://docs.perfectcorp.com/ja/reference/ai_background_removal.md): # 概要 AI 背景透過では、写真から背景を除去します。 * 自動背景検出: AI を使用して被写体と背景を識別し、分離します。 * 高精度編集: 被写体の周囲にクリーンで精密なエッジを提供します。 * 多様なカテゴリに対応: 人物、製品、動物、車、グラフィックなどに対応します。 * 他の AI タスクとの連携: 出力ファイル ID を他の AI タスクにチェーンできます。 ![](https://plugins-media.makeupar.com/smb/blog/post/2023-11-03/54285311-7c65-4658-9e27-11bf5c8dfe56.jpg) ## 統合ガイド * AI 背景透過の実行方法 1. **ソース画像のリサイズ
** サポートされている寸法に合わせて写真をリサイズします。詳細は **[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)** を参照してください。 2. **ファイル API を使用したファイルのアップロード
** ***/s2s/v2.0/file*** API を使用して、対象ユーザーの画像をアップロードします。 - 画像要件 - 詳細は **[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)** を参照してください。 - ***重要***: ファイル API を呼び出すだけではファイルはアップロードされません。**ファイル API のレスポンスで提供される URL** にファイルを**手動でアップロード**する必要があります。その URL がアップロード先です。次に進む前に、ファイルがそこに正常に転送されたことを確認してください。
AI API を呼び出す前に、ファイルが正常にアップロードされていることを確認してください。ファイル API を使用してアップロード URL を取得し、その場所にファイルをアップロードします。アップロードが完了すると、レスポンスに ***file_id*** が返されます。この ID は、そのファイルに関連する AI 機能にアクセスするために使用します。 > **警告:** ファイル API のレスポンスで提供される URL にファイルをアップロードしない場合、AI API の使用時に 500 Server Error / unknown_internal_error または 404 Not Found エラーが発生する可能性があります。 3. **AI タスクの実行
** アップロードが完了したら、ファイル ID を指定して POST 'task/sod' を呼び出し、AI タスクを実行して監視用の ***task_id*** を取得します。 4. **Webhook またはポーリングを設定し、タスクが成功またはエラーになるまでステータスを確認する
** ***task_id*** は、保持期間全体を通じてタスクのステータスを監視するための Webhook の設定やポーリングの実装に使用されます。AI エンジンがタスクを完了するまで、ステータスは running のままです。タスクが running 状態の間は、ユニットは消費されません。処理が完了すると、タスクのステータスは success または error に変わります。 1. **成功時に AI タスクの結果を取得する
** エンジンが入力ファイルを正常に処理し、結果の画像を生成すると、タスクは 'success' ステータスに変わります。処理済み画像の URL と、結果画像を再アップロードせずに別の AI タスクにチェーンできる dst_id が得られます。 ユニットはこの場合のみ消費されます。エンジンがタスクの処理に失敗した場合、タスクのステータスは 'error' に変わり、ユニットは消費されません。
ユニットを控除する際、システムは期限切れに近いものから優先的に控除します。期限日が同じ場合は、最も早い日に取得したユニットから控除されます。 * デモシナリオ: 一般的な実装ケース: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Transparen_Background_aca3cdbd83.jpg) ## 入力と出力 * 入力 * `Image` - **型:** `image` - **説明:** 前景が明確な画像。 実際のアプリケーション（入力）: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_removal_bg_s4_poster_1_289b8eaf81.png) --- * 出力 * `Foreground image` - **型:** `image` - **説明:** 背景が除去された画像。 実際のアプリケーション（出力）: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_removal_bg_s4_poster_2_a6bc3c5f6a.png) ## ファイル仕様とエラー * 対応フォーマットと寸法 |AI 機能|対応寸法|ファイルサイズ|受け入れ可能な形式| | ---- | ---- | ---- | ---- | |AI 背景透過|入力画像と出力画像の両方に対する推奨事項と制限は以下の通りです:
解像度: 4096 × 4096 ピクセル（最長辺は 4096 ピクセルを超えてはなりません）|<10MB|JPG および PNG| * エラーコード |エラーコード|説明| | ---- | ---- | |exceed_max_filesize|入力ファイルサイズが最大制限を超えています| |invalid_parameter|パラメータ値が無効です| |error_download_image|ソース画像のダウンロードに失敗しました| |error_download_mask|マスク画像のダウンロードに失敗しました| |error_decode_image|ソース画像のデコードに失敗しました| |error_decode_mask|マスク画像のデコードに失敗しました| |error_download_video|ソース動画のダウンロードに失敗しました| |error_decode_video|ソース動画のデコードに失敗しました| |error_nsfw_content_detected|ソース画像に NSFW コンテンツが検出されました| |error_no_face|ソース画像に顔が検出されませんでした| |error_pose|ソース画像でポーズの検出に失敗しました| |error_face_parsing|ソース画像で顔のセグメンテーションに失敗しました| |error_inference|推論パイプラインエラー| |exceed_nsfw_retry_limits|NSFW 画像の生成を避けるための再試行制限を超えました| |error_upload|結果画像のアップロードに失敗しました| |error_multiple_people|ソース画像で複数の人物が検出されました| |error_no_shoulder|ソース画像で肩が見えません| |error_large_face_angle|アップロードされた画像の顔の角度が大きすぎます| |error_hair_too_short|入力された髪が短すぎます| |error_unexpected_video_duration|動画の長さが dstDuration と等しくありません| |error_bald_image|入力されたヘアスタイルがハゲです| |error_unsupport_ratio|入力画像のアスペクト比がサポートされていません| |unknown_internal_error|その他| --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | AI 背景透過 V1.0 | 1 | --- - [AI バッグバーチャル試着](https://docs.perfectcorp.com/ja/reference/ai_bag.md): # 概要 AI バッグで、バッグのバーチャル試着を作成します。 ## 統合ガイド このガイドでは、以下を説明します： * **エンドポイント:** `/s2s/v2.0/task/bag` * **認証:** すべてのリクエストには `Authorization: Bearer YOUR_API_KEY` が必要です * **ワークフロー:** 1. **セルフィー画像の準備:** バーチャル試着対象として、自分の画像をアップロードするか、有効な画像 URL を提供します。 1. **バッグ画像の準備:** バッグ製品、またはバッグを持っている人物（遮るものがない状態）の画像をアップロードするか、有効な画像 URL を提供します。 1. **スタイルと性別の選択:** 希望するスタイルと、視覚化したい性別を選択します。 1. **AI タスクの実行とタスク ID の取得:** レスポンスから `task_id` を取得します。 1. **ステータスのポーリング (`GET`):** `task_id` を使用してタスクのステータスを確認します。`task_status` が `"success"` または `"error"` になるまでポーリングを継続します。 --- * 認証 - **ベアラートークン** を使用して、リクエストヘッダーに API キーを含めます： ``` Authorization: Bearer YOUR_API_KEY ``` API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/. --- * AI バッグ API 使用ガイド このガイドでは、画像のアップロード、参照バッグの準備、および AI バッグ API を使用したバーチャル試着タスクの作成方法について説明します。 *** * ステップ 1. ファイル API を使用したファイルのアップロード **ファイル API** (`/s2s/v2.0/file`) を使用して、対象ユーザーの画像をアップロードします。 **画像要件:** * セルフィー写真をアップロードします。 * 写真に上半身がはっきりと写っていることを確認します。 * 複数の人物や気が散るオブジェクトがある背景は避けてください。 **リクエスト例:** ```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 } ] }' ``` *** * ステップ 2. ファイル API レスポンスの取得 レスポンスには以下が含まれます： * AI タスク作成用の `file_id`。 * 実際の画像ファイルをアップロードするための `requests.url`。 **レスポンス例:** ```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" } } ] } ] } } ``` *** * ステップ 3. 提供された URL への画像アップロード ファイル API レスポンスの `requests.url` を使用して画像をアップロードします： ```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' ``` *** * ステップ 4. 参照バッグ画像の準備 以下が可能： * ファイル API (`/s2s/v2.0/file`) を使用してバッグ画像をアップロードする、または * 有効な画像 URL を提供する。 **サポートされるバッグ画像:** * バッグの製品画像。 * バッグの参照として、遮るものなくバッグを持っている人物。 詳細な仕様については **[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)** を参照してください。 *** * ステップ 5. AI タスクの作成 希望するスタイルと、視覚化したい性別を選択します。 **AI タスク API** (`/s2s/v2.0/task/bag`) を使用してバーチャル試着タスクを作成します。 **パラメータ:** * ユーザー画像用: `src_file_id` または `src_file_url`。 * バッグ画像用: `ref_file_id` または `ref_file_url`。 **リクエスト例:** ```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" }' ``` **レスポンス例:** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` *** * ステップ 6. タスク結果のポーリング タスク ID を使用してステータスを確認します： ```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' ``` *** * ステップ 7. 結果の取得 成功したレスポンスには、結果画像のダウンロード URL が含まれます： ```json { "status": 200, "data": { "error": null, "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..." }, "task_status": "success" } } ``` 無効な API キーエラーレスポンス： ```json { "status": 401, "error": "Unauthorized", "error_code": "InvalidAccessToken" } ``` --- ## ファイル仕様とエラー * AI バッグバーチャル試着仕様 **サポートされるバッグ画像** * 製品画像要件 * 最小解像度: 512 × 512 ピクセル * 画像あたり 1 つの製品のみ * 製品は画像の高さの 25 % 以上を占める必要があります ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/040_thumb_c5f4d2af8e.jpg) * 着用画像要件 * 最小解像度: 800 × 800 ピクセル ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/003_thumb_c73b207cae.jpg) **サポートされるセルフィービュー** * 推奨画像解像度: 少なくとも 512 × 512 ピクセル。 * 推奨顔の被写体範囲: 画像の高さの 15 % 以上。 * 画像には、顔全体がはっきりと見え、頭から胸まで少なくとも頭部ショットが含まれる単一の人物が写っている必要があります。半身ショットが推奨されます。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/lashana_lynch_thumb_7a900b811e.jpg) **試着スタイル** * バーチャル試着出力を生成するための 4 つの事前定義スタイルがあります: "style_parisian_chic", "style_urban_chic", "style_mediterranean_chic", "style_art_deco_style"。AI タスク作成時にこのスタイルパラメータを指定するか、デフォルトでシステムがランダムにスタイルを選択するようにできます。 ![style_parisian_chic](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/fca6a904_b13a_4c90_bc52_d9200a473c70_4d994afa3e.jpg) --- * サポートされる形式と寸法 |AI 機能|サポートされる寸法|サポートされるファイルサイズ|サポートされる形式| | ---- | ---- | ---- | ---- | |AI バッグバーチャル試着|入力: 長辺 <= 4096
出力: 1104 x 1472 |< 10MB|jpg/jpeg/png/heic| * エラーコード |エラーコード|説明| | ---- | ---- | | error_download_image | srcKeys/refKeys のダウンロードエラー | | error_inference | 推論パイプラインエラー | | error_no_face | ソース画像で顔が検出されませんでした | | error_nsfw_content_detected| 結果画像で NSFW コンテンツが検出されました | | exceed_max_filesize | 入力ファイルサイズが最大制限 (10 MB) を超えています | | invalid_parameter | 無効な性別オプション値
無効なスタイルオプション値 | | unknown_internal_error | その他 | * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON パーシング) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性用), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings 用), requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用), Jackson Databind >= 2.12.0 | --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | AI バッグバーチャル試着 V2.0 | 2 | --- - [AI 前髪バーチャル試着](https://docs.perfectcorp.com/ja/reference/ai_bangs.md): # 概要 AI で理想の前髪を試着 リアルな仕上がり：リアルな前髪を試し、あなたの顔に最も似合うスタイルを見つけましょう。 多彩なスタイル：あらゆる個性やシーンに合う幅広い前髪スタイルを探索できます。 簡単操作：新しい前髪を試せます。 さらに多くの前髪スタイルを見たい場合は、https://yce.makeupar.com/bangs-filter. を参照してください。 ユースケース： ![AI 前髪](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_style_v1_video_1200x674px_1_259f619dfd.png "AI Hair Bang Generator") ![AI 前髪](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](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png "Suggestions for How to Shoot") --- ## ファイル仕様とエラー * 対応フォーマットと寸法 |AI 機能|対応寸法|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | |AI 前髪|長辺 <= 1024、顔幅 >= 128、顔の姿勢：-10 < pitch < +10、-45 < yaw < +45、-15 < roll < +15、単一の顔のみ、顔全体が見えている必要あり|< 10MB|jpg/jpeg/png| * エラーコード |エラーコード|説明| | ---- | ---- | |error_no_shoulder |ソース画像に肩が写っていません |error_large_face_angle |アップロードされた画像の顔の角度が大きすぎます |error_insufficient_landmarks |ソース画像で十分な顔または体のランドマークを検出できません |error_hair_too_short |入力された髪が短すぎます |error_face_pose |ソース画像の顔の姿勢がサポートされていません |error_bald_image |入力されたヘアスタイルがハゲています --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI 前髪 | 1 | --- - [ヒゲスタイル](https://docs.perfectcorp.com/ja/reference/ai_beard_style.md): # 概要 AI 男性ヒゲスタイルシミュレーション AI ヒゲスタイルで、トリムヒゲ、無精ヒゲ、フルヒゲ、サークルヒゲ、口ひげ、ゴティヒゲなどのヒゲスタイルをバーチャル試着できます。 ビフォーアフターの結果を確認できます。 ヒゲフィルターには、口ひげ、ショートボックス、ダックテール、サークルなど、数十のスタイルが含まれています。 ## 統合ガイド 1. **自撮り画像のアップロード** ソース画像は以下の 2 通りの方法で提供できます。 - **既存の公開画像 URL を使用** アップロードの代わりに、AI タスクを開始する際に公開アクセス可能な画像 URL を直接指定できます。 - **File API 経由でアップロード** エンドポイント: ``` POST /s2s/v2.0/file ``` これにより、後続のタスク実行用の `file_id` が返されます。 - ***重要***: File API を呼び出すだけではファイルはアップロードされません。File API のレスポンスで提供される **URL に手動でファイルをアップロード** する必要があります。その URL がアップロード先です。次に進む前に、ファイルが正常に転送されたことを確認してください。

AI API を呼び出す前に、ファイルが正常にアップロードされていることを確認してください。File API を使用してアップロード URL を取得し、その場所にファイルをアップロードします。アップロードが完了すると、レスポンスに ***file_id*** が含まれます。この ID は、そのファイルに関連する AI 機能にアクセスするために使用します。 > **警告:** File API のレスポンスで提供される URL にファイルをアップロードしない場合、AI API の使用時に 500 Server Error / unknown_internal_error または 404 Not Found エラーが発生します。 2. **プリセットスタイルのリスト取得** * /s2s/v2.0/task/template/beard-style を使用してプリセットテンプレートリストを取得し、AI タスクを実行するための ``template_id`` を選択します。 3. **AI タスクの実行とタスク ID の取得** /s2s/v2.0/task/beard-style を使用して AI タスクを実行します。ターゲットユーザー画像には、``src_file_url`` または ``src_file_id`` のいずれかを指定します。適用するスタイルの ``template_id`` を指定し、``task_id`` を取得します。 4. **タスクのステータス確認のためのポーリング（成功または失敗まで）** ``task_id`` を使用して、GET /s2s/v2.0/task/beard-style をポーリングし、現在のエンジンステータスを取得してタスクのステータスを監視します。エンジンがタスクを完了するまで、ステータスは running のままとなり、この段階ではユニットは消費されません。 AI タスクが成功または失敗した際に通知を受け取るために、Webhook を実装することもできます。詳細は **[Webhook](../../../develop/webhook)** セクションを参照してください。 > **警告:** 保持期間内にタスクのステータスを確認するためにポーリングを行うことが必須です。保持期間内にポーリングリクエストがない場合、タスクが正常に処理されていてもタイムアウトします。ユニットは消費されます。 > **警告:** タイムアウトしたタスクのステータスを確認すると、InvalidTaskId エラーが発生します。したがって、AI タスクを実行したら、ステータスが success または error になるまで、保持期間内にステータスを確認するためにポーリングを行う必要があります。 5. **AI タスクの成功後の結果取得** エンジンが入力ファイルを処理し、結果画像を生成すると、タスクのステータスは success に変わります。処理済み画像の URL が返されます。 --- ## ファイル仕様とエラー * 対応フォーマットと寸法 |AI 機能|対応寸法|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | |AI ヒゲスタイル生成|解像度: 長辺 < 1024
顔幅 > 256
顔の姿勢: -30 < yaw < 30,
単一の顔のみ,
顔全体が見えている必要あり|< 10MB|jpg/jpeg| * エラーコード |エラーコード|説明| | ---- | ---- | |error_no_face |ソース画像に顔が写っていません |error_src_face_too_small |顔が小さすぎます |error_inference |ヒゲ除去エラーまたはヒゲ生成エラー |error_face_pose |ソース画像の顔の姿勢がサポートされていません * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON パーシング) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性のため), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings 用), requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用), Jackson Databind >= 2.12.0 | --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | AI ヒゲスタイル生成 V1.0 | 2 | --- - [体型補正](https://docs.perfectcorp.com/ja/reference/ai_body_reshape.md): # 概要 体型補正 API による体型補正＆スリミング AI 体型補正 API で、写真のスリミングと体型補正を行います。 ## 統合ガイド このガイドでは、AI 体型補正 API のワークフローについて説明します。 **エンドポイント:** `/s2s/v2.0/task/body-reshape` **認証必須:** `Authorization: Bearer YOUR_API_KEY` **ワークフロー手順:** 1. **画像アップロードの準備:** - アップロード用のセルフィー画像を準備します。 - ファイル API `/s2s/v2.0/file` を呼び出し、アップロード URL と関連する `file_id` を取得します。 - 提供されたアップロード URL を使用してセルフィー画像をアップロードします。 2. **グループ写真の場合のオプション前処理:** - 画像内に複数の人物がいる場合は、セルフィー画像を前処理します。 3. **体型補正効果の設定:** - まず、適切な体型補正パラメータを選択します。 4. **AI タスクの開始とタスク ID の取得:** - `file_id` と選択した効果設定を HTTP POST リクエストで `/s2s/v2.0/task/body-reshape` に送信します。 - この操作を識別するための一意なタスク ID をレスポンスで待ちます。 5. **タスクステータスのポーリング（継続的な確認）:** - 取得した `task_id` を使用し、HTTP GET リクエスト（例: `GET /s2s/v2.0/task/body-reshape/${task_id}`）で定期的にタスクステータスをポーリングします。 - 以下を継続的に監視します。 - `Task_status = "success"`（処理完了）。 - `Task_status = "error"`（該当する場合、解決または再試行）。 - ステータスが success に遷移したら、ワークフローを適切に更新します。 --- * API プレイグラウンド API プレイグラウンドで API を対話的にテストします。 **API プレイグラウンド:** [http://yce.makeupar.com/api-console/en/api-playground/ai-body-reshape/](http://yce.makeupar.com/api-console/en/api-playground/ai-body-reshape/) --- * 認証 - リクエストヘッダーに **Bearer トークン** を使用して API キーを含めます。 ``` Authorization: Bearer YOUR_API_KEY ``` API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/. * 1. 画像のアップロード ファイルをサーバーに直接アップロードするか、AI タスクペイロードに有効な画像 URL を指定します。 * アップロードエンドポイント ``` POST /s2s/v2.0/file ``` すでに公開画像 URL がある場合は、この手順をスキップできます。 --- * 2. 効果テンプレートの準備 * 前処理 ピクセル座標で検出されたバウンディングボックスを出力します。後で体型補正 AI タスクを作成するために、結果のインデックスを使用します。 ``` { "timed": number, "result": [ { "left": number, "top": number, "width": number, "height": number } ] } ``` * 効果テンプレート JSON スキーマ ``` { "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: 前処理で検出された体のインデックス。省略可、初期値 0。 features: 少なくとも 1 つの非ゼロの体型補正パラメータが必須です。すべてゼロにはできません。 * ペイロードの例（送信可能） ``` { "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. 体型補正 AI タスクの作成と結果のポーリング 画像と完全な効果ペイロードが準備できたら、タスクを作成します。API はリクエストを非同期で処理します。ステータスが `success` または `error` になるまで、タスクステータスをポーリングする必要があります。 * タスク作成エンドポイント ``` POST /s2s/v2.0/task/body-reshape ``` * ポーリングエンドポイント ``` GET /s2s/v2.0/task/body-reshape/{task_id} ``` --- ## ファイル仕様とエラー * AI 体型補正仕様 **対応セルフィービュー** 顔の表情と体の姿勢がはっきりと見える全身写真。 ![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_body_reshape_02_7777218379.jpg) **可視性とポーズの要件** | **領域** | **ソース画像で満たすべき条件** | |------------|---------------------------------------------------| | **首** | ソース画像内で首が見えている必要があります。 | | **腕** | 両腕（上腕、前腕、手）が完全に写っている必要があります。 | | **脚** | 脚全体が画像内に写っている必要があります。 | | **ヒップ** | ヒップが視界に入っている必要があります。 | | **ヒップリフト** | ヒップが視界に入っている必要があります。 | | **肩** | • 肩が見えている必要があります。
• 手を上げるポーズは許可されていません。
• 90° の横向きポーズは許可されていません。 | | **腹部** | 腹部が見えている必要があります。 | | **ウエスト** | ウエストが見えている必要があります。 | | **胸** | • 胸の領域が画像内に写っている必要があります。
• ヒップを含むショットである必要があります（「ヒップなしのハーフボディ」は不可）。
• 胸の中央が見えている必要があります。 | | **スリム** | 肩がフレーム内に入っている必要があります。 | | **身長** | • ヒップが写っている必要があります。
• ハーフボディビューの場合、脚が含まれている必要があります（脚が見えていること）。 | **体型補正カスタマイズパラメータガイド** | カテゴリ | パラメータ | 機能 | 最小値 (-100 / 0) | 最大値 (100) | | -------- | --------- | -------- | -------------------- | --------------- | | 腕| 強度 | 腕の太さを調整します | 細い | 太い | | 腹部| 強度 | 腹部の突出を調整します | 平坦 | 突出 | | 胸| 強度（左 / 右） | 各側の胸のボリュームを調整します | 平坦 | 豊か | | ヒップリフト | 強度 | ヒップの曲率とリフトを調整します（ヒップアップ効果を追加） | 引き締まった（リフトアップ＆引き締め） | 丸みのある（リフトアップ＆ボリュームアップ） | | ヒップサイズ | 強度 | ヒップ全体の幅を調整します | 狭い | 広い | | 脚| 強度 | 脚の太さを調整します | 細い | 太い| | 首| 強度（左 / 右） | 各側の首の輪郭とスリミングを調整します| 元通り (0)| 引き締まった | | 肩幅 | 強度（左 / 右） | 各肩の幅を調整します | 狭い | 広い | | 肩の形 | 強度（左 / 右） | 各肩の角度と傾きを調整します | 傾斜 | 四角い | | スリム| 強度 | 全身の曲線を調整します | スリム | 曲線的 | | 身長| 強度 | 人物全体の身長を調整します | 元通り (0) | 高い | | ウエスト| 強度 | ウエストラインの幅を調整します | 狭い | 広い | **注意:** *“左”と“右”は、視聴者の画面の左右ではなく、人物本人の視点に基づいています。* --- * 対応フォーマットと寸法 |AI 機能|対応寸法|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | |AI 体型補正|長辺 <= 2048、短辺 >= 320|< 10MB|jpg/jpeg/png| * エラーコード | エラーコード | 説明 | | ---- | ---- | | RUNTIME_ERROR | 体型補正の実行中に予期しないエラーが発生しました | | PHOTO_DETECTION_FAIL | ユーザー写真を正しく処理できませんでした。例えば、手が検出されませんでした | | PHOTO_CHECK_INVALID | ユーザー写真のポーズまたはサイズが無効です | | INPUT_ERROR | 入力ファイルフォーマットが正しくありません | | INPUT_MAIN_IMAGE_EMPTY | ユーザー画像が必要です | * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON パーシング) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch のため) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性のため), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings のため), requests >= 2.20.0 | | Java | Java 11+ (HttpClient のため), Jackson Databind >= 2.12.0 | --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | AI 体型補正 V1.0 | 1 | --- - [ブレスレットバーチャル試着](https://docs.perfectcorp.com/ja/reference/ai_bracelet.md): # 概要 ブレスレットのバーチャル試着を作成します。 2D 画像 1 枚でブレスレットの試着プレビューを生成します。 ジュエリーブランドで使えます。 ## 統合ガイド 本ガイドでは以下内容を説明します: * **エンドポイント:** `/s2s/v2.0/task/2d-vto/bracelet` * **認証:** すべてのリクエストに `Authorization: Bearer YOUR_API_KEY` が必要です * **ワークフロー:** 1. **手首の画像を準備する:** 画像をアップロードするか、手首の有効な画像 URL を提供します 1. **ブレスレットの画像を準備する:** 画像をアップロードするか、ブレスレット製品の有効な画像 URL を提供します 1. **AI タスクを発行しタスク ID を取得する:** レスポンスから `task_id` を取得します。 1. **ステータスをポーリングする（`GET`）:** `task_id` を使用してタスクのステータスを確認します。`task_status` が `"success"` または `"error"` になるまでポーリングを続行してください。 --- * API プレイグラウンド API プレイグラウンドで API を対話的にテストします: **API プレイグラウンド:** [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/) --- * 認証 - リクエストヘッダーに **Bearer Token** を使用して API キーを含めます: ``` Authorization: Bearer YOUR_API_KEY ``` API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/. * 1. 画像のアップロード ファイルをサーバーに直接アップロードするか、VTO タスクペイロードに有効な画像 URL を提供できます。 * アップロードエンドポイント ``` POST /s2s/v2.0/file ``` すでにパブリックな画像 URL を持っている場合は、このステップをスキップできます。 File API のレスポンスで提供された URL にファイルを直接アップロードし、その後 File API が返した対応する `src_file_id` を使用して AI タスクを呼び出すことができます。または VTO タスクペイロードに有効な画像 URL を `src_file_url` として提供します。`src_file_id` または `src_file_url` がバーチャル試着の対象となります。 また、`src_file_id` または `src_file_url` に適用するブレスレット製品画像を参照として `ref_file_ids` または `ref_file_urls` で提供する必要があります。 AI エンジンでは、ブレスレット製品画像の自動背景透過に対応しています。ただし、手（`srcmsk_file_id` または `srcmsk_file_url`）またはブレスレット製品（`refmsk_file_ids` または `refmsk_file_urls`）のオクルージョンマスク画像ファイルを提供してセグメンテーションを微調整できます。 --- * 2. ブレスレット VTO タスクの作成と結果のポーリング 画像とテンプレート ID が揃ったら、タスクを作成します。API はリクエストを非同期で処理します。ステータスが `success` または `error` に達するまでタスクステータスをポーリングする必要があります。 * タスク作成エンドポイント ``` POST /s2s/v2.0/task/2d-vto/bracelet ``` * ポーリングエンドポイント ``` GET /s2s/v2.0/task/2d-vto/bracelet/{task_id} ``` --- ## ファイル仕様とエラー * ブレスレットバーチャル試着の仕様 **サポートされるブレスレットビュー** ブレスレット画像は四分之三前面ビュー（約 45 度）で提供する必要があります。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/bracelet_product_09_2cb9721d77_2f8d90ab9f.jpg) **サポートされる手首ビュー** 手首の裏側が完全に、5 つの指がすべて明確に見え、オクルージョン（遮蔽）がない状態である必要があります。 ![](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)** 手首に沿った位置を示します: −0.3 は主要な手首関節に近いことを示します 1.0 は主要な手首関節から遠いことを示します デフォルト値: null（エンジンのデフォルトを使用） ![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)** 影の強さを制御します: 0.0 は影なしを示します 1.0 は最大限の影を示します デフォルト値: 0.15 **bracelet\_ambient\_light\_intensity: float (0.0 to 1.0)** ライティングがターゲットの手画像を参照する度合いを定義します: 0.0 は手画像のライティングを無視します 1.0 は手画像のライティングと影のレンダリングに完全に一致させます デフォルト値: 1.0 **ブレスレットアンカーポイント: ピクセル座標の 2 点の配列（任意）** ブレスレットが手首に接する内側のエッジをマークし、左と右の点を指定します。 このパラメータを提供しない場合、AI エンジンがアンカーポイントを自動的に検出します。 ![bracelet_anchor_point](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/bracelet_anchor_point_c353245edc.jpg) --- * サポートされる形式と寸法 |AI 機能|サポートされる寸法|サポートされるファイルサイズ|サポートされる形式| | ---- | ---- | ---- | ---- | |ブレスレットバーチャル試着|長辺 <= 4096 |< 10MB|jpg/jpeg/png| * エラーコード |エラーコード|説明| | ---- | ---- | | RUNTIME_ERROR | ブレスレットランタイムで予期しないエラーが発生しました | | PHOTO_DETECTION_FAIL | ユーザー写真が正しく処理できませんでした（例: 手が検出されなかった） | | OBJECT_DETECTION_FAIL | オブジェクト写真が正しく処理できませんでした（例: 製品が検出されなかった） | | PHOTO_CHECK_INVALID | ユーザー写真のポーズまたはサイズが無効です | | INPUT_ERROR | 入力ファイルの形式が正しくありません | | INPUT_MAIN_IMAGE_EMPTY | ユーザー画像が必要です | * 環境と依存関係 | サンプルコードの言語/ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58（モダンな TLS/HTTP サポート）
- jq >= 1.6（堅牢な JSON パーシング） | | Node.js (JavaScript) | Node >= 18（グローバル fetch のため） | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4（モダンな TLS/互換性のため）、ext-curl（推奨）または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10（f-strings のため）、requests >= 2.20.0 | | Java | Java 11+（HttpClient のため）、Jackson Databind >= 2.12.0 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | ブレスレットバーチャル試着 V1.0 | シングルアイテム着用で 1 ユニット
スタック着用で 2 ユニット | --- - [豊胸シミュレーター](https://docs.perfectcorp.com/ja/reference/ai_breast_augmentation.md): # 概要 AI 豊胸シミュレーターでは、写真のバスト形状を補正します。 シルエットや遠近感を調整して、バスト形状を補正します。 ![](https://plugins-media.makeupar.com/smb/blog/post/2025-06-18/e41b8942-22e1-4846-8f81-f41171b74558.jpg) 補正は、写真内の人物に合わせて適用されます。 AI 豊胸シミュレータータスクを作成して補正を実行します。 ![](https://plugins-media.makeupar.com/smb/blog/post/2025-06-18/733cedfd-2e8e-4cfc-8758-6854d923664b.jpg) --- ## 統合ガイド このガイドでは、以下を説明します。 AI 豊胸シミュレーター API のワークフロー： **エンドポイント:** `/s2s/v2.0/task/breast-shape` **認証必須:** `Authorization: Bearer YOUR_API_KEY` **ワークフロー手順:** 1. **画像アップロード準備:** - プロセスはバストショットのセルフィーを準備することから始まります。 2. **AI 豊胸シミュレーター設定** AI 豊胸シミュレーターでは、1（控えめ）から 3（顕著）までの強度レベルを調整して補正の度合いを制御します。 3. **AI タスクの開始とタスク ID の取得:** - アップロードした画像とパラメータ設定を HTTP POST リクエストで `/s2s/v2.0/file` に送信します。 - このインタラクションを識別する一意のタスク ID をレスポンスで待ちます。 4. **タスクステータスのポーリング（継続的な確認）:** - 取得した `task_id` を使用して、HTTP GET リクエスト（例: `GET /task/${task_id}`）でタスクステータスを定期的にポーリングします。 - 以下を継続的に監視します： - `Task_status = "success"`（処理完了）。 - `Task_status = "error"`（該当する場合、解決または再試行）。 - ステータスが成功に遷移したら、ワークフローを適切に更新します。 --- * 認証 - リクエストヘッダーに **Bearer トークン** を使用して API キーを含めます： ``` Authorization: Bearer YOUR_API_KEY ``` API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/. --- * 画像のアップロード ファイルをサーバーに直接アップロードするか、AI タスクペイロードに有効な画像 URL を指定できます。 * アップロードエンドポイント ``` POST /s2s/v2.0/file ``` すでに公開画像 URL がある場合は、この手順をスキップできます。 --- * AI 豊胸シミュレーター強度の調整 **AI 豊胸シミュレーター設定** AI 豊胸シミュレーターでは、強度レベルを **1 から 3** の間に設定して補正の度合いを制御します。 - **レベル 1**: 控えめな補正。 - **レベル 2**: 中程度の補正。 - **レベル 3**: 顕著な補正。 --- * AI 豊胸シミュレーター AI タスクの作成と結果のポーリング 画像をアップロードし、希望する強度レベルを選択した後、補正タスクを開始できます。API はリクエストを非同期で処理します。タスクステータスが `success` または `error` に達するまでポーリングする必要があります。 * タスク作成エンドポイント ``` POST /s2s/v2.0/task/breast-shape ``` * ポーリングエンドポイント ``` GET /s2s/v2.0/task/breast-shape/{task_id} ``` --- ## ファイル仕様とエラー * AI 豊胸シミュレーター仕様 **最適な結果のための画像要件と推奨事項** - **解像度ガイドライン**: 入力画像の最長辺は 4096 ピクセルを超えてはなりません。最高のパフォーマンスを得るには、頭頂部から胸部を含む上半身領域が、少なくとも 1024 × 768 ピクセルの解像度でレンダリングされていることを確認してください。 - **被写体要件**: - 画像には少なくとも 1 人の完全に検出可能な人物が含まれている必要があります。両肩がフレーム内で明確に視認できる必要があります。 - 胸部領域が視認可能である必要があります。これには、被写体が主に正面を向いている場合（つまり、ヨー角が −90° から +90° の間）、衣服を着用している場合と着用していない場合の両方が含まれます。斜めや横顔のポーズよりも、正面からのビューが強く推奨されます。 - **結果向上のための推奨プラクティス**: - 上半身構図を優先してください：画像は上半身に特化しているか、全身が含まれている場合でも、上半身領域がフレームの大部分を占め、最長辺が 1024 ピクセルを超えている必要があります。 - 正面のポーズのみを使用してください。検出精度と結果の品質が低下するため、横向きや大きく回転した位置は避けてください。 - 胸部輪郭の最も自然な補正を得るには、水着、低カットトップス、V ネックウェアなど、バスト周辺の肌を露出させる服装を選択してください。これらのスタイルにより、AI は下層構造をよりよく推測し、控えめでリアルなデコルテ効果を生み出すことができます。 - システムは単一被写体の画像のみをサポートします。フレーム内に複数の人物がいる場合、処理は自動的に最も大きな可視肩幅を持つ個人（つまり、カメラに最も近い、または最も中央に整列している人物）を対象とします。 - 胸部領域上の遮蔽を避けてください。バッグ、バックパックストラップ、スカーフ、ネックレス、その他のアクセサリーなどのオブジェクトは、誤って除去されたり、編集時にアーティファクトを引き起こしたりする可能性があります。 - 衣服の外観は元の画像と異なる場合があります。補正の度合いは強度設定に依存します：補正レベルが高いほど、胸部周辺の衣服の形状、フィット感、ドレープの顕著な変更など、より顕著な変化が生じます。 ![](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) --- * サポートされる形式と寸法 |AI 機能|サポートされる寸法|サポートされるファイルサイズ|サポートされる形式| | ---- | ---- | ---- | ---- | |AI 豊胸シミュレーター|最小: 512x384
最大: 長辺 < 4096|< 10MB|jpg/jpeg/png/heic | * エラーコード | エラーコード | 説明 | |----------------------------------|-------------| | `invalid_parameter` | 提供されたパラメータが無効です。具体的には、必須フィールド（`src_keys`、`dst_keys`、または `acts`）の 1 つ以上が欠落している、形式が不正である、またはサポートされていない値を含んでいます。 | | `exceed_max_filesize` | 入力画像が許可される最大ファイルサイズ（10 MB）を超えています。送信前に画像を圧縮またはリサイズしてください。 | | `error_download_image` | システムがソース画像のダウンロードに失敗しました。これは、ネットワークの問題、無効な URL、またはリソースへのアクセス権限の問題が原因である可能性があります。 | | `error_decode_image` | ダウンロードした画像をデコードできませんでした。これは、ファイルの破損、サポートされていない形式、または無効なバイナリデータが原因である可能性があります。 | | `error_nsfw_content_detected` | ソース画像または生成された出力画像のいずれかで、潜在的に NSFW（Not Safe For Work）コンテンツが検出されました。コンプライアンスと安全上の理由から、処理は中止されました。 | | `error_pose` | 人体ポーズ推定に失敗しました。全身または上半身のスケルトンを確実に検出できなかったため、その後の解剖学的分析が実行できませんでした。 | | `error_breast_region_detection` | システムはポーズとセグメンテーションの手がかりに基づいてバスト領域を検出しようとしましたが、有効で識別可能な胸部領域（遮蔽、極端な角度、または視認性の不足などによる）を特定できませんでした。 | * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON パーシング) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性用), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings 用), requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用), Jackson Databind >= 2.12.0 | --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | AI 豊胸シミュレーター V1.0 | 1 | --- - [服バーチャル試着](https://docs.perfectcorp.com/ja/reference/ai_clothes.md): # 概要 AI Clothes で、服のバーチャル試着を作成します。 画像に衣装を重ね合わせて試着プレビューを生成します。 --- ## 統合ガイド * API プレイグラウンド API プレイグラウンドで AI Clothes のバーチャル試着機能をテストします。 API プレイグラウンドにアクセスするには: --- * AI Clothes API 使用ガイド このガイドでは、画像のアップロード、参照衣装の準備、および AI Clothes API を使用したバーチャル試着タスクの作成方法について説明します。 *** * ステップ 1. File API を使用してファイルをアップロードする **File API** (`/s2s/v2.0/file`) を使用して、対象ユーザーの画像をアップロードします。 **画像要件:** * 高解像度の全身写真をアップロードしてください。 * 写真に全身がはっきりと映っていることを確認してください。 * 複数の人物や気が散るオブジェクトがある背景は避けてください。 **リクエスト例:** ```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 } ] }' ``` *** * ステップ 2. File API レスポンスを取得する レスポンスには以下が含まれます: * AI タスク作成用の `file_id`。 * 実際の画像ファイルをアップロードするための `requests.url`。 **レスポンス例:** ```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" } } ] } ] } } ``` *** * ステップ 3. 提供された URL に画像をアップロードする File API レスポンスの `requests.url` を使用して画像をアップロードします: ```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' ``` *** * ステップ 4. 参照衣装を準備する * 4.1 参照衣装画像をアップロードする 以下のいずれかの方法が可能です: * File API (`/s2s/v2.0/file`) を使用して衣装画像をアップロードする、または * 有効な画像 URL を提供する。 **サポートされる衣装画像:** * 服の商品画像。 * 衣装参照としての全身写真。 詳細な仕様については、**[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)** を参照してください。 *** * ステップ 5. AI タスクを作成する **AI Task API** (`/s2s/v2.0/task/cloth-v4`) を使用して、バーチャル試着タスクを作成します。 **パラメータ:** * ユーザー画像用: `src_file_id` または `src_file_url`。 * 衣装画像用: `ref_file_id`、`ref_file_url`、または `template_id`。 **リクエスト例:** ```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" }' ``` **レスポンス例:** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` *** * ステップ 6. タスク結果をポーリングする タスク ID を使用してステータスを確認します: ```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' ``` *** * ステップ 7. 結果を取得する 成功したレスポンスには、結果画像のダウンロード URL が含まれます: ```json { "status": 200, "data": { "error": null, "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..." }, "task_status": "success" } } ``` 無効な API キー エラー レスポンス: ```json { "status": 401, "error": "Unauthorized", "error_code": "InvalidAccessToken" } ``` --- ユースケース: ![](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) 撮影方法のヒント: ![撮影方法のヒント](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI-Cloth-Guideline.png "撮影方法のヒント") ## ファイル仕様とエラー * サポートされる形式と寸法 |タイプ|サポートされる寸法|サポートされるファイルサイズ|サポートされる形式| | ---- | ---- | ---- | ---- | |対象ユーザー画像|推奨: 1024×768、最小: 512×384、最大辺: 4096 px。

- 1 人のみ。
- 最適な結果を得るには、人物がフレームの少なくとも 80% を占めている必要があります。
- 画像には上半身のみを含め、胸から上を映してください。腹部は映す必要はありませんが、肩は見える必要があります。
- 顔全体がはっきりと見え、遮るものがない必要があります。
- 体は正面を向いて立っている状態である必要があります（座ったりしゃがんだりしていないこと）。 |< 10MB|jpg/png| |服の参照画像 |推奨: 1024×768、最小: 512×384、最大辺: 4096 px。

- 実写の服写真を参照として使用する場合
   - 1 人のみである必要があります。
   - 見える服の領域が、試着対象領域を完全にカバーしている必要があります。
      - 例: 全身試着の場合、上半身のみの服画像は受け入れられません。
      - 例: 下半身試着の場合、部分的なパンツ画像は受け入れられません。
   - 服が激しく遮られていてはいけません（例: 長い髪や腕で覆われているなど）。
   - 顔全体がはっきりと見え、遮るものがない必要があります。
   - 体は正面を向いて立っている状態である必要があります（座ったりしゃがんだりしていないこと）。

- 商品画像を参照として使用する場合
   - 単一の衣類の正面からの商品ショットである必要があります。
   - 合成画像（例: 1 枚の写真にトップスとボトムスが含まれているなど）は使用しないでください。
   - 下半身の場合、実際に着用された衣装のみがサポートされ、単独の商品画像はサポートされません。|< 10MB|jpg/png| * エラーコード * エラーコード（前処理） | エラーコード | 説明 | | ---------- | ----------- | | exceed_max_filesize | SRC または REF 画像が大きすぎます。長辺は 4096 ピクセルを超えてはいけません。 | | error_below_min_image_size | SRC または REF 画像が小さすぎます。長辺は少なくとも 128 ピクセルである必要があります。 | | error_pose | アップロードされた人間の SRC 画像からポーズを検出できませんでした。 | | error_invalid_ref | REF 画像が無効です。例えば、空であるか、被写体が完全に見えていません。 | | error_apply_region_mismatch | SRC 画像内の適用領域が REF 画像と一致しないため、編集を適用できません。 | | error_invalid_src | ソース画像に下半身のみ、または足のみが映っている場合。 | * エラーコード（エンジン） | エラーコード | 説明 | | ---------- | ----------- | | invalid_parameter | - 無効な衣類カテゴリー。
- Style_id が inference_style_list に含まれていません。
- 無効な src_keys、dst_keys、または acts。
- 無効な ref_keys または template_ref_image。
- 必ずそのうち 1 つのみを提供してください。 | | error_download_image | SRC または REF 画像をダウンロードできませんでした。 | | exceed_max_filesize | SRC または REF 画像が大きすぎます。ファイルサイズは 10 MB を超えてはいけません。 | | error_nsfw_content_detected | 結果画像に潜在的な NSFW コンテンツが検出されました。 | | error_editing_failed | 結果画像がソース画像と類似しすぎているため、編集プロセスが失敗しました。 | | unknown_internal_error | - モデルの読み込みに失敗しました。
- 無効なスケジューラーアルゴリズムタイプ。
- エンジンが読み込まれていません。
- ファイルがアップロード結果に含まれていません。 | | error_multi_person | 「normal」または「strict」のマルチパーソンフィルター設定下で、ソース画像または参照画像に複数の人物が検出されました。 | * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON パーシング) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性のため)、ext-curl (推奨) または allow_url_fopen=On + ext-openssl、ext-json | | Python | Python >= 3.10 (f-strings 用)、requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用)、Jackson Databind >= 2.12.0 | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | 服バーチャル試着 V2.0 | 2 | | 服バーチャル試着 V3.0 | 2 | --- - [AI カラー補正](https://docs.perfectcorp.com/ja/reference/ai_color_correction.md): # 概要 AI カラー補正で、写真の彩度、色温度、色相をワンタップで自動調整します。ホワイトバランスによる色温度の補正、鮮やかな色合いの表現、露出レベルによる明るさのバランス調整、色かぶりの除去、自然な肌色の人物写真への改善、シャドウとハイライトの詳細の強調、ノイズ除去とクリアさの向上、クリエイティブなカラーグレーディング効果の適用まで、すべて可能です。暖色系から寒色系まで異なる色調を持つ 4 種類のカラーグレーディングバージョンを数秒で生成できます。 サンプル 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) --- ## ファイル仕様とエラー * 対応フォーマットとサイズ | AI 機能 | 対応サイズ | 対応ファイルサイズ | 対応フォーマット | | ---- | ---- | ---- | ---- | | AI カラー補正 | 長辺 <= 4096 | < 10MB | jpg/jpeg/png | * エラーコード |エラーコード|説明| | ---- | ---- | | exceed_max_filesize | 入力ファイルサイズが最大制限を超えています | | invalid_parameter | パラメータ値が無効です | | error_download_image | ソース画像のダウンロードに失敗しました | | error_decode_image | ソース画像のデコードに失敗しました | | error_nsfw_content_detected | ソース画像に NSFW コンテンツが検出されました | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI カラー補正 V1.0 | 2 | --- - [イヤリングバーチャル試着](https://docs.perfectcorp.com/ja/reference/ai_earrings.md): # 概要 イヤリングバーチャル試着 イヤリング試着とピアシング試着のプレビューを作成します。 2D 画像からイヤリングバーチャル試着を作成します。3D モデリングは不要です。 ## 統合ガイド 本ガイドでは以下内容を説明します: * **エンドポイント:** `/s2s/v2.0/task/2d-vto/earring` * **認証:** すべてのリクエストに `Authorization: Bearer YOUR_API_KEY` が必要です * **ワークフロー:** 1. **セルフィー画像を準備する:** 画像をアップロードするか、有効な画像 URL を提供します 2. **イヤリング画像を準備する:** 画像をアップロードするか、イヤリング製品の有効な画像 URL を提供します 3. **AI タスクを発行しタスク ID を取得する:** レスポンスから `task_id` を取得します。 4. **ステータスをポーリングする（`GET`）:** `task_id` を使用してタスクのステータスを確認します。`task_status` が `"success"` または `"error"` になるまでポーリングを続行してください。 --- * API プレイグラウンド API プレイグラウンドで API を対話的にテストします: **API プレイグラウンド:** [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/) --- * 認証 - リクエストヘッダーに **Bearer Token** を使用して API キーを含めます: ``` Authorization: Bearer YOUR_API_KEY ``` API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/. * 1. 画像のアップロード ファイルをサーバーに直接アップロードするか、VTO タスクペイロードに有効な画像 URL を提供できます。 * アップロードエンドポイント ``` POST /s2s/v2.0/file ``` すでにパブリックな画像 URL を持っている場合は、このステップをスキップできます。 File API のレスポンスで提供された URL にファイルを直接アップロードし、その後 File API が返した対応する `src_file_id` を使用して AI タスクを呼び出すことができます。または VTO タスクペイロードに有効な画像 URL を `src_file_url` として提供します。`src_file_id` または `src_file_url` がバーチャル試着の対象となります。 また、`src_file_id` または `src_file_url` に適用するイヤリング製品画像を参照として `ref_file_ids` または `ref_file_urls` で提供する必要があります。 AI エンジンでは、イヤリング製品画像の自動背景透過に対応しています。ただし、手（`srcmsk_file_id` または `srcmsk_file_url`）またはイヤリング製品（`refmsk_file_ids` または `refmsk_file_urls`）のオクルージョンマスク画像ファイルを提供してセグメンテーションを微調整できます。 --- * 2. イヤリング VTO タスクの作成と結果のポーリング 画像とテンプレート ID が揃ったら、タスクを作成します。API はリクエストを非同期で処理します。ステータスが `success` または `error` に達するまでタスクステータスをポーリングする必要があります。 * タスク作成エンドポイント ``` POST /s2s/v2.0/task/2d-vto/earring ``` * ポーリングエンドポイント ``` GET /s2s/v2.0/task/2d-vto/earring/{task_id} ``` --- ## ファイル仕様とエラー * イヤリングバーチャル試着の仕様 **サポートされるイヤリング参照画像** * 遮蔽のない明瞭な前面ビューの単一のイヤリング画像。 * すべてのパラメータ（アンカーポイント、マスク、位置などを含む）は、参照画像が**片方のイヤリング**を着用している場合のみ適用されます。 * 試着の参照画像に**両方のイヤリング**が表示されている場合、すべてのパラメータは**自動検出とデフォルト設定**を使用します。 * **両方のイヤリング**を試着する場合、より明瞭な耳がソースとして使用され、もう片方の耳はミラーリングによって生成されます。 ![](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) **サポートされるセルフィービュー** * イヤリングバーチャル試着は前面画像に対応していますが、最も良い結果は横顔の画像で得られます。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Earring_restriction_cdf1de3c7b.png) **earring\_wearing\_location: integer array of size 2** セルフィー内でイヤリングを配置すべきターゲット位置を指定します。 デフォルト値: null（エンジンのデフォルト） ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/wearing_location_b4f6f4453a.jpg) **earring\_scale: number greater than 0** センチメートルでイヤリングのサイズを制御します。 デフォルト値: null（エンジンのデフォルト） **earring\_is\_right\_ear: boolean** イヤリングが右耳に装着されているかどうかを示します。デフォルトでは右耳に装着されます。 デフォルト値: true **earring\_occluded\_type: number (Enum: 0, 1, 2)** オクルージョンの種類を指定します: 0 は自動検出を意味します 1 は遮蔽ありを意味します 2 は遮蔽なしを意味します デフォルト値: 0 **earring\_shadow\_intensity: float (0.0 to 1.0)** 影の強さを制御します: 0.0 は影なしを示します 1.0 は最大限の影を示します デフォルト値: 0.15 **earring\_ambient\_light\_intensity: float (0.0 to 1.0)** ライティングがセルフィー画像を参照する度合いを定義します: 0.0 はセルフィー画像のライティングを無視します 1.0 はセルフィー画像のライティングと影のレンダリングに完全に一致させます デフォルト値: 1.0 **イヤリングアンカーポイント: ピクセル座標の 1 点の配列（任意）** イヤリング製品画像内の装着位置を指定します。 デフォルト値: null（エンジンのデフォルト） ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/anchor_point_787282aa19.jpg) --- * サポートされる形式と寸法 |AI 機能|サポートされる寸法|サポートされるファイルサイズ|サポートされる形式| | ---- | ---- | ---- | ---- | |イヤリングバーチャル試着|長辺 <= 4096 |< 10MB|jpg/jpeg/png| * エラーコード |エラーコード|説明| | ---- | ---- | | RUNTIME_ERROR | イヤリングランタイムで予期しないエラーが発生しました | | PHOTO_DETECTION_FAIL | ユーザー写真が正しく処理できませんでした（例: 手が検出されなかった） | | OBJECT_DETECTION_FAIL | オブジェクト写真が正しく処理できませんでした（例: 製品が検出されなかった） | | PHOTO_CHECK_INVALID | ユーザー写真のポーズまたはサイズが無効です | | INPUT_ERROR | 入力ファイルの形式が正しくありません | | INPUT_MAIN_IMAGE_EMPTY | ユーザー画像が必要です | * 環境と依存関係 | サンプルコードの言語/ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58（モダンな TLS/HTTP サポート）
- jq >= 1.6（堅牢な JSON パーシング） | | Node.js (JavaScript) | Node >= 18（グローバル fetch のため） | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4（モダンな TLS/互換性のため）、ext-curl（推奨）または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10（f-strings のため）、requests >= 2.20.0 | | Java | Java 11+（HttpClient のため）、Jackson Databind >= 2.12.0 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | イヤリングバーチャル試着 V1.0 | シングルアイテム着用で 1 ユニット
スタック着用で 2 ユニット | --- - [カラコンバーチャル試着](https://docs.perfectcorp.com/ja/reference/ai_eye_color_lens.md): # 概要 カラコンバーチャル試着では、虹彩を検出し、レンズの不透明度とブレンドをシミュレートして目の色を変えます。 ![](https://plugins-media.makeupar.com/smb/blog/post/2022-01-25/2a348e5b-6a2b-4f08-bc54-1d16a0777e87.jpg) **コンタクトレンズバーチャルシミュレーション** AI 駆動のバーチャル試着ツールで、目の色を変えます。虹彩を検出し、色調調整を適用します。 **リアルな出力** 自然な目の反射を保持します。 **コンタクトフィルターシミュレーション** 異なる虹彩のベースカラーにわたって不透明度とブレンドを再現します。 --- ## 統合ガイド * セルフィーを撮影する * 適切な照明の下でカメラに直接向きます。 * JS Camera Kit を使用して写真をキャプチャします。 * レンズスタイルの切り抜き画像を準備する * **1 つの明確なレンズスタイル画像**を提供します： * 形式：**PNG**（推奨：背景透過済み） * 寸法：**200 × 200 ≤ W × H ≤ 600 × 600** * ファイルサイズ：**< 10 MB** **サンプル：** ![](https://d3ss46vukfdtpo.cloudfront.net/static/media/01.00ccf3ac.png) ![](https://d3ss46vukfdtpo.cloudfront.net/static/media/02.c8beb3fc.png) * ***/s2s/v2.0/file*** API を介してアップロード URL とファイル ID を取得する ファイル API レスポンスで返されたアップロード URL を使用して、以下のファイルをアップロードします： * セルフィー写真 * レンズスタイル画像 * AI タスク ***/s2s/v2.0/task/eye-color-vto*** を実行する ファイル ID または画像 URL を入力ソースとして使用して AI タスクを実行します。効果パラメータを必要に応じて設定します。 * タスクステータスのポーリング 返された **task\_id** を使用してタスクの進捗を監視します。 **GET /task/eye-color-vto** をポーリングしてエンジンのステータスを確認します。 タスクは完了するまで **“running”** 状態のままです。タスク実行中はユニットは消費されません。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_9535461b-69fc-4432-b56b-2d7c4cd0bf3b_b1ef78e813.jpg) * **サンプルアプリケーションシナリオ** - ステップ 1: 色を選ぶ 試着したい色合いを選択します。 - ステップ 2: バーチャル試着カメラを開く バーチャル試着ツールを起動します。 - ステップ 3: ライブカメラを使用または写真をアップロードする ライブカメラで撮影するか、写真をアップロードしてカラーコンタクトレンズをバーチャルに試着します。 ![](https://plugins-media.makeupar.com/smb/blog/post/2025-03-28/2732a9f0-9cae-4639-b765-15866550b109.jpg) ## ファイル仕様とエラー * 対応形式と寸法 |タイプ|対応寸法|対応ファイルサイズ|対応形式| | ---- | ---- | ---- | ---- | |AI カラコンバーチャルシミュレーション|セルフィー画像:
* 長辺 ≤ 1920 px
* 短辺 ≥ 320 px

レンズスタイル画像:
* ファイル形式: PNG
* 解像度: 200 × 200 ≤ W × H ≤ 600 × 600 px|< 10MB|jpg/png| * エラーコード |エラーコード|説明| | ---- | ---- | |error_below_min_image_size|画像の幅または高さが 320 ピクセル未満の場合、使用するには小さすぎます| |error_face_position_invalid|画像内で顔全体が完全に可視であり、一部が切れていない必要があります| |error_face_position_too_small|写真内の顔が小さすぎて適切に分析できません| |error_face_position_out_of_boundary|顔が大きすぎるか、写真の端の一部が外れています| |error_insufficient_lighting|照明が暗すぎて分析が困難です| |error_face_angle_invalid|顔の角度が適切ではありません。正面を向いた撮影では、頭を正面から 10 度以内に保ってください。横を向いた撮影では、角度が 15 度以上である必要があります| * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON パーシング) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性用), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings 用), requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用), Jackson Databind >= 2.12.0 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | カラコンバーチャル試着 V1.0 | 1 | --- - [AI ファブリックチェンジ](https://docs.perfectcorp.com/ja/reference/ai_fabric.md): # 概要 AI ファブリック API では、画像の衣服領域にファブリックスタイルを適用します。 新しいファブリックスタイルを追加します。 --- ## 統合ガイド * AI ファブリック API 使用ガイド このガイドでは、画像のアップロード、事前定義されたファブリックスタイルの取得、および AI ファブリック API を使用したバーチャル試着タスクの作成方法について説明します。 *** * ステップ 1. ファイル API を使用してファイルをアップロードする **File API** (`/s2s/v2.0/file`) を使用して、対象ユーザーの画像をアップロードします。 **画像要件:** * 高解像度の全身写真をアップロードしてください。 * 写真に全身がはっきりと映っていることを確認してください。 * 複数の人物や気が散るオブジェクトがある背景は避けてください。 **リクエスト例:** ```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 } ] }' ``` *** * ステップ 2. File API のレスポンスを取得する レスポンスには以下が含まれます: * AI タスク作成用の `file_id`。 * 実際の画像ファイルをアップロードするための `requests.url`。 **レスポンス例:** ```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" } } ] } ] } } ``` *** * ステップ 3. 指定された URL に画像をアップロードする File API レスポンスの `requests.url` を使用して画像をアップロードします: ```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' ``` *** * ステップ 4. 事前定義されたファブリックテンプレートを取得する **Template API** (`/s2s/v2.0/task/template/fabric`) を使用して、事前定義されたファブリックテンプレートのリストを取得します: ```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' ``` *** * ステップ 5. AI タスクを作成する **AI Task API** (`/s2s/v2.0/task/fabric`) を使用して、バーチャル試着タスクを作成します。 **パラメータ:** * ユーザー画像用: `src_file_id` または `src_file_url`。 * ファブリックスタイル用: `template_id`。 **リクエスト例:** ```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" }' ``` **レスポンス例:** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` *** * ステップ 6. タスク結果をポーリングする タスク ID を使用してステータスを確認します: ```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' ``` *** * ステップ 7. 結果を取得する 成功したレスポンスには、結果画像のダウンロード URL が含まれます: ```json { "status": 200, "data": { "error": null, "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..." }, "task_status": "success" } } ``` 無効な API キーエラーレスポンス: ```json { "status": 401, "error": "Unauthorized", "error_code": "InvalidAccessToken" } ``` --- ユースケース: ![](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) 撮影方法の提案: ![撮影方法の提案](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI-Cloth-Guideline.png "撮影方法の提案") --- ## ファイル仕様とエラー * サポートされる形式と寸法 |AI 機能|サポートされる寸法|サポートされるファイルサイズ|サポートされる形式| | ---- | ---- | ---- | ---- | |AI ファブリック|長辺 <= 4096、単一の人物のみ、腹部、顔、肩がすべて見えている必要があります。顔が遮られてはいけません。体は直立し、正面を向いており、座るやしゃがむなどのポーズは避けてください。|< 10MB|jpg/jpeg| * エラーコード |エラーコード|説明| | ---- | ---- | |error_apply_region_not_detected|入力画像内の衣服領域が小さすぎるか、検出されませんでした * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON パーシング) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性用)、ext-curl (推奨) または allow_url_fopen=On + ext-openssl、ext-json | | Python | Python >= 3.10 (f-strings 用)、requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用)、Jackson Databind >= 2.12.0 | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | ファブリックチェンジ V1.0 | 2 | --- - [顔の比率分析](https://docs.perfectcorp.com/ja/reference/ai_face_analyzer.md): # 概要 顔の比率分析では、顔の構造を解析し、顔、目、眉、唇、鼻、頬骨などの形状を特定します。 ## 統合ガイド * 顔の比率分析 用に写真を撮る方法 * 正面を向いた自撮り写真を撮る - 鮮明な写真 1 枚で、カメラにまっすぐ向き合ってください。髪は自然な状態にし、顔全体が隠れることなく見える状態がベストです。おでこを出すために髪を流し、まっすぐ正面を見つめることで、適切な正面からのアングルを撮影してください。 - または、JS Camera Kit を使用して写真を撮影してください。自動的な顔アラインメント、ライティングのガイド、顔サイズ検出に従い、写真が処理に必要な基準を満たすことを確認してください。 * AI による肌の悩みの検出方法 1. **ソース画像のサイズを変更する**
写真のサイズをサポートされている寸法に合わせてください。詳細は **[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)** 2. **File API を使用してファイルをアップロードする**
***/s2s/v2.0/file*** API を使用して、対象のユーザー画像をアップロードします。 - 画像の要件 - 詳細は **[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)** をご覧ください。 ***重要***: File API を呼び出すだけでは、ファイルはアップロードされません。File API レスポンスで提供された **URL** へファイルを **手動でアップロード** する必要があります。その URL がアップロード先です。続行する前に、ファイルがそこに正常に転送されたことを確認してください。
AI API を呼び出す前に、ファイルが正常にアップロード済みであることを確認してください。File API を使用してアップロード用 URL を取得し、その場所にファイルをアップロードします。アップロードが完了すると、レスポンスで ***file_id*** を受け取ります。この ID を使用して、そのファイルに関連する AI 機能にアクセスします。 > **警告:** File API レスポンスで提供された URL へファイルをアップロードせずに AI API を使用すると、500 Server Error / unknown_internal_error または 404 Not Found のエラーが発生する点にご注意ください。 3. **顔の比率分析 タスクを実行する**
アップロードが完了すると、ファイル ID を使用して分析する複数の顔属性を選択できます。 **[入力と出力](#section/overview/Inputs-and-Outputs)** を参照してください。
その後、File ID を用いて POST 'task/face-attr-analysis' を呼び出すと、 enhance タスクが実行され、***task_id*** が取得されます。 4. **タスクが成功またはエラーになるまでポーリングでステータスを確認する**
この ***task_id*** を使用して、GET 'task/face-attr-analysis' をポーリングし、現在のエンジンステータスを取得してタスクのステータスを監視します。エンジンがタスクを完了するまで、ステータスは 'running' のままで、この段階ではユニットは消費されません。 **警告:** タスクの保持期間に基づいて **ポーリング** でタスクのステータスを確認することは必須です。保持期間内にポーリングリクエストがなければ、タスクが正常に処理されていても、タスクはタイムアウトします（ユニットは消費されます）。 > **警告:** タイムアウトしたタスクのステータスを確認すると、***InvalidTaskId*** エラーが発生します。そのため、AI タスクを実行したら、保持期間内に **ポーリング** でステータスを確認し、ステータスが *success* または *error* になるまで続行する必要があります。 5. **AI タスクが成功したら結果を取得する**
エンジンが入力ファイルを正常に処理し、結果画像を生成すると、タスクは 'success' ステータスに変更されます。処理された画像の URL と、結果画像を再アップロードせずに別の AI タスクを連続実行できる dst_id を受け取ります。 ユニットは、この場合にのみ消費されます。エンジンがタスクの処理に失敗すると、タスクのステータスは 'error' に変更され、ユニットは消費されません。
ユニットを控除する際、システムは期限の近づいているものを優先します。期限が同じ場合は、最も早く取得したユニットを控除します。 * 実際の使用例: ![](https://plugins-media.makeupar.com/smb/blog/post/2025-01-15/10a4b980-f571-4d08-8f5d-e3ed48db77aa.jpg) ## 入力と出力 * 顔属性: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/img_Face_Ratio_sec_01_01_enu_79380baa14.jpg) | **カテゴリ** | **サブカテゴリ** | **リクエストパラメータ** | **結果パラメータ** | **結果タイプ** | | --- | --- | --- | --- | --- | | **顔** | 顔の形 | `faceShape` | `faceshape` | Triangle, Diamond, Heart, InvTriangle, Oblong, Oval, Round, Square, Unknown | | **年齢と性別** | 年齢 | `age` | `agegender.age` | integer | | | 性別 | `gender` | `agegender.gender` | female, male, unknown | | **目** | 目の形 | `eyeShape` | `eyelid.left_shape`, `eyelid.right_shape` | Narrow, Round, Almond | | | 目の大きさ | `eyeSize` | `eyelid.size` | Big, Small, Average | | | 目の角度 | `eyeAngle` | `eyelid.left_angle`, `eyelid.right_angle` | Downturned, Upturned, Average | | | 目の間隔 | `eyeDistance` | `eyelid.setting` | Close-set, Wide-Set, Average | | | まぶた | `eyelid` | `eyelid.left_eyelid`, `eyelid.right_eyelid` | Hooded-lid, Single-lid, Double-lid, Deep-Set | | **眉** | 眉の形 | `eyebrowShape` | `eyebrow.left_shape`, `eyebrow.right_shape` | Hard Angled, Soft Angled, Straight, Rounded, Obscured | | | 眉の太さ | `eyebrowThickness` | `eyebrow.left_body_thickness`, `eyebrow.right_body_thickness` | Dense, Sparse, Average, Unknown | | | 眉間 | `eyebrowDistance` | `eyebrow.gap` | Far-Apart, Close, Average | | | 眉の短さ | `eyebrowShortness` | `eyebrow.left_shortness`, `eyebrow.right_shortness` | Short, Normal | | **唇** | 唇の形 | `lipShape` | `lipshape[]` | Bow, Downturned, Full, Heavy Lower Lip, Heavy Upper Lip, Narrow, Round, Thin, Wide, Average | | **鼻** | 鼻の幅 | `noseWidth` | `nose.width` | Narrow, Broad, Average | | | 鼻の長さ | `noseLength` | `nose.length` | Long, Short, Average | | **頬骨** | 頬骨 | `cheekbones` | `cheekbone.left`, `cheekbone.right`, `cheekbone.overall` | Flat Cheekbone, High Cheekbone, Low Cheekbone, Round Cheeks | --- * 顔比率: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/img_Face_Ratio_sec_01_03_2fe8f06b92.jpg) | **サブカテゴリ** | **リクエストパラメータ** | **結果パラメータ** | **結果タイプ** | **説明** | | --- | --- | --- | --- | --- | | 水平 3 分割比率 | `horizontalThird` | `horizontal_third` | 3 分割のパーセンテージ; 解釈: Short / Balanced / Long; ゴールデンRatio: 33% : 33% : 33% | 顔の水平比率は、顔を 3 つの等しい区間に分割することに基づいています：生え際から眉の下端まで、眉の下端から鼻の下端まで、そして鼻の下端から顎先まで。3 つの区間のゴールデンRatio、つまり理想の比率は 1:1:1 です。| | 垂直 5 分割比率 | `verticalFifth` | `vertical_fifth` | 5 分割のパーセンテージ; 解釈 (目の間隔と目の幅): Narrow / Balanced / Wide; ゴールデンRatio: 20% : 20% : 20% : 20% : 20% | 顔の垂直比率は、顔を 5 つの区間に分割して決定されます：1 つの目の幅、2 つの目の間隔、そして目の外側から顔の縁までの空間。これらの比率のゴールデンRatioは 1:1:1:1:1 です。 | | 顔のアスペクト比 | `faceAspectRatio` | `face_aspect_ratio` | `[1, r]`; 解釈: Short / Balanced / Long; ゴールデンRatio: 1 : 1.46 | 顔のアスペクト比は、顔の幅と高さの関係であり、ゴールデンRatio 1:1.46 に従うことが理想です。 | | 目のアスペクト比 | `eyeAspectRatio` | `left_eye_aspect_ratio` `right_eye_aspect_ratio` | `[1, r]`; 解釈: Round / Balanced / Flat; ゴールデンRatio: 1 : 3 | 目のアスペクト比は、目の高さとその幅の関係であり、ゴールデンRatio 1:3 に合うことが理想です。 | | 眉山アーチ比率 | `eyebrowArch` | `left_eyebrow_arch_to_eyebrow_width` `right_eyebrow_arch_to_eyebrow_width` | `[1, r]`; 解釈: Short Arch / Balanced / Long Arch; ゴールデンRatio: 1 : 1.618 | 眉山アーチの理想の比率は、眉自体の形によって決まり、最高点（アーチ）がゴールデンRatio に合致することで、美しい外観が得られます。 | | 目の高さから眉までの距離 | `eyeHeightToEyebrowDistance` | `left_eye_height_to_eyebrow_distance` `right_eye_height_to_eyebrow_distance` `overall_eye_height_to_eyebrow_distance` | `[1, r]`; 解釈: Short / Balanced / Long; ゴールデンRatio: 1 : 1.618 | 眉までの距離は、上まぶたの上端から眉の最高点までの垂直距離です。理想としては、目の高さを基準にゴールデンRatio 1.618:1 となることで、目と眉の間に最も調和のとれたバランスが得られます。 | | 鼻のアスペクト比 | `noseAspectRatio` | `nose_aspect_ratio` | `[1, r]`; 解釈: Wide / Balanced / Narrow; ゴールデンRatio: 1 : 1.618 | 鼻のアスペクト比は、鼻の幅と高さの関係であり、ゴールデンRatio 1:1.618 に従うことが理想です。 | | 鼻幅に対する口幅 | `noseWidthToMouthWidth` | `nose_width_to_mouth_width` | `[1, r]`; 解釈: Small / Balanced / Large; ゴールデンRatio: 1 : 1.618 | 鼻幅と口幅の比率は、鼻の幅と口の幅の関係であり、ゴールデンRatio 1:1.618 に従うことが理想です。 | | 鼻から唇、顎まで | `noseToLipToChin` | `nose_to_lip_to_chin` | `[1, r]`; 解釈: Short / Balanced / Long (顔の下半分の長さ); ゴールデンRatio: 1 : 1.618 | 鼻から唇、顎までの比率は、鼻の基部から唇の中心までの距離を 1 としたとき、唇の中心から顎までの理想の距離が 1.618 となる比率です。このゴールデンRatioにより、顔の対称性の原理に従い、調和のとれた下半顔が得られます。 | | 上唇に対する下唇 | `upperLipToLowerLip` | `upper_lip_to_lower_lip` | `[1, r]`; 解釈: Full Upper / Balanced / Full Lower; ゴールデンRatio: 1 : 1.618 | 上唇と下唇のゴールデンRatioでは、下唇の厚さは上唇の 1.618 倍であるべきとされています。この比率により、下唇が上唇よりややふっくらします。 | ---- * 撮影方法の提案: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_Face_Analysis_how_to_shoot_35ca9af08e.png) > **警告:** 顔の幅は、画像の幅の 60% を超える必要があります。 ## ファイル仕様とエラー * 対応形式と解像度 |AI 機能|対応解像度|対応ファイルサイズ|対応形式| | ---- | ---- | ---- | ---- | |顔の比率分析|長辺 <= 4096、1 人のみ。1 辺が 1080px 超の画像は自動的にリサイズされて分析されます。|< 10MB|jpg/jpeg| * エラーコード |エラーコード|説明| | ---- | ---- | | error_below_min_image_size | ソース画像の解像度は 320 ピクセル以上である必要があります。 | | error_face_position_invalid | 顔は完全に露出しており、正面を向いて、画像内で中央に位置している必要があります。 | | error_face_position_too_small | 検出された顔は分析に小さすぎます。 | | error_face_position_out_of_boundary | 顔が画像の境界を超えています。 | | error_face_not_forward_facing | 顔はカメラに正面を向いている必要があります。 | | error_face_angle_upward | 顔が上向きに角度が大きすぎます—頭を少し下へ傾けてください。 | | error_face_angle_downward | 顔が下向きに角度が大きすぎます — 頭を少し上へ傾けてください。 | | error_face_angle_leftward | 顔が左に回りすぎです — 頭を少し右へ回してください。 | | error_face_angle_rightward | 顔が右に回りすぎです — 頭を少し左へ回してください。 | | error_face_angle_left_tilt | 顔が左に傾きすぎです — 頭を軽く右へ傾けてください。 | | error_face_angle_right_tilt | 顔が右に傾きすぎです — 頭を軽く左へ傾けてください。 | * 環境と依存関係 | サンプルコードの言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (最新の TLS/HTTP 対応)
- jq >= 1.6 (堅牢な JSON パース) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (最新の TLS/互換性用), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings 用), requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用), Jackson Databind >= 2.12.0 | --- ## JS カメラキット {% partial file="/_partials/js-camera-kit.md" /%} --- ## ユニット消費 * 顔属性・比率分析 | AI 機能 | 消費ユニット数 | |---|---| | 顔構造機能 1~5 個 | 10 | | 顔構造機能 6~14 個 | 20 | | 顔構造機能 15~28 個 | 30 | --- - [フェイスリフト](https://docs.perfectcorp.com/ja/reference/ai_face_lift.md): # 概要 AI フェイスリフトでは、顔の補正を行います。顔の構造、肌の質感、比率を分析して画像を再構築します。 目の下のクマ、頬、額、顔全体の形状、口などの顔の領域を 0 から 100 の数値で調整できます。 SNS、プロフィール写真、クリエイティブコンテンツ、ビジネス用途で使えます。 ![](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) ## 統合ガイド このガイドでは、以下を説明します。 AI フェイスリフト API のワークフロー: **エンドポイント:** `/s2s/v2.0/task/face-lift` **認証必須:** `Authorization: Bearer YOUR_API_KEY` **ワークフローの手順:** 1. **画像アップロードの準備:** - アップロード用のセルフィー画像を準備します。 - File API `/s2s/v2.0/file` を呼び出して、アップロード URL と関連する `file_id` を取得します。 - 提供されたアップロード URL を使用してセルフィー画像をアップロードします。 2. **複数顔がある場合のオプションの前処理:** - 画像内に複数の顔が含まれている場合は、セルフィー画像を前処理します。 3. **フェイスリフト効果の設定:** - まず、適切なフェイスリフトパラメータを選択します。 4. **AI タスクの開始とタスク ID の取得:** - 選択した効果設定とともに `file_id` を HTTP POST リクエストで `/s2s/v2.0/task/face-lift` に送信します。 - この操作を識別するための一意なタスク ID をレスポンスで待ちます。 5. **タスクステータスのポーリング（継続的な確認）:** - 取得した `task_id` を使用して、HTTP GET リクエスト（例: `GET /s2s/v2.0/task/face-lift${task_id}`）で定期的にタスクステータスをポーリングします。 - 以下を継続的に監視します: - `Task_status = "success"` （処理完了）。 - `Task_status = "error"` （該当する場合、解決または再試行）。 - ステータスが success に遷移したら、ワークフローを適切に更新します。 --- 1. 認証 - リクエストヘッダーに **Bearer トークン** を使用して API キーを含めます: ``` Authorization: Bearer YOUR_API_KEY ``` API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/. 2. 画像のアップロード サーバーにファイルを直接アップロードするか、AI タスクペイロードに有効な画像 URL を指定できます。 * アップロードエンドポイント ``` POST /s2s/v2.0/file ``` すでに公開画像 URL がある場合は、この手順をスキップできます。 --- 3. 前処理により補正対象の顔を選択する * 前処理 API の呼び出し ピクセル座標で検出されたバウンディングボックスを出力します。後で Face Lift AI タスクを作成するために、結果のインデックスを使用します。 ``` POST /s2s/v2.0/task/face-lift/pre-process ``` ``` { "timed": number, "result": [ { "left": number, "top": number, "width": number, "height": number } ] } ``` 4. Face Lift AI タスクの作成と結果のポーリング 画像と完全な効果ペイロードが準備できたら、タスクを作成します。API はリクエストを非同期で処理します。ステータスが `success` または `error` になるまでタスクステータスをポーリングする必要があります。 * タスク作成エンドポイント ``` POST /s2s/v2.0/task/face-lift ``` * ポーリングエンドポイント ``` GET /s2s/v2.0/task/face-lift/{task_id} ``` --- ## ファイル仕様とエラー * AI フェイスリフト仕様 **対応セルフィービュー** 画像は 1920 x 1920 以下で、長辺が 640 のときに 32 x 32 ピクセルを超える十分なサイズの顔がはっきりと写っており、ロール角度がプラスマイナス 75 度以内、ヨー角度がプラスマイナス 90 度以内で撮影されている必要があります。 ![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_face_reshape_01_85c8ffc055.jpg) --- * 対応フォーマットと寸法 | AI 機能 | 対応寸法 | 対応ファイルサイズ | 対応フォーマット | | ---- | ---- | ---- | ---- | | AI フェイスリフト | 長辺 <= 1920 | < 10MB | jpg/jpeg/png | * エラーコード | エラーコード | 説明 | | ---- | ---- | | RUNTIME_ERROR | フェイスリフトの実行中に予期しないエラーが発生しました | | PHOTO_DETECTION_FAIL | ユーザー写真を正しく処理できませんでした。例えば、手が検出されませんでした | | OBJECT_DETECTION_FAIL | オブジェクト写真を正しく処理できませんでした。例えば、製品が検出されませんでした | | PHOTO_CHECK_INVALID | ユーザー写真のポーズまたはサイズが無効です | | INPUT_ERROR | 入力ファイルフォーマットが正しくありません | | INPUT_MAIN_IMAGE_EMPTY | ユーザー画像が必要です | * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON パーシング) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性用), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings 用), requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用), Jackson Databind >= 2.12.0 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI フェイスリフト V1.0 | 1 | --- - [顔パーツ補正](https://docs.perfectcorp.com/ja/reference/ai_face_reshape.md): # 概要 AI 顔パーツ補正 API では、目、鼻、唇、顎、顔全体のパーツを補正します。 美容治療ワークフローのビフォーアフタープレビューに使用します。 * 鼻形成術（隆鼻術） オンライン鼻形成シミュレーターで、鼻梁、リフト、小鼻などをシミュレーションします。 * 顎フィラー 顎フィラーの効果をプレビューします。顎の長さと顎の形を調整します。 * 唇フィラー 唇フィラーの効果をプレビューします。唇のボリュームと形を調整します。 * 眉リフト手術 眉リフトの結果をプレビューします。 ## 統合ガイド このガイドでは、以下を説明します： AI 顔パーツ補正 API のワークフロー： **エンドポイント:** `/s2s/v2.0/file` **認証が必要:** `Authorization: Bearer YOUR_API_KEY` **ワークフローの手順:** 1. **画像アップロードの準備:** - アップロード用のセルフィー画像を準備します。 - File API `/s2s/v2.0/file` を呼び出し、アップロード URL と関連する `file_id` を取得します。 - 提供されたアップロード URL を使用してセルフィー画像をアップロードします。 2. **複数顔の場合のオプションの前処理:** - 画像内に複数の顔がある場合、セルフィー画像を前処理します。 3. **顔パーツ補正効果の設定:** - まず、目、顔、唇、または鼻に適した顔パーツ補正パラメータを選択します。 4. **AI タスクの開始とタスク ID の取得:** - 選択した効果設定とともに `file_id` を HTTP POST リクエストで `/s2s/v2.0/task/face-reshape` に送信します。 - このやり取りを識別する一意のタスク ID をレスポンスで待ちます。 5. **タスクステータスのポーリング（継続的な確認）:** - 取得した `task_id` を使用し、HTTP GET リクエスト（例：`GET /s2s/v2.0/task/face-reshape/${task_id}`）で定期的にタスクステータスをポーリングします。 - 以下を継続的に監視します： - `Task_status = "success"`（処理完了）。 - `Task_status = "error"`（該当する場合、解決または再試行）。 - ステータスが success に遷移したら、ワークフローを適切に更新します。 --- * API プレイグラウンド API プレイグラウンドで API を対話的にテストします： **API プレイグラウンド:** [http://yce.makeupar.com/api-console/en/api-playground/ai-face-reshape/](http://yce.makeupar.com/api-console/en/api-playground/ai-face-reshape/) --- * 認証 - **Bearer トークン** を使用して、リクエストヘッダーに API キーを含めます： ``` Authorization: Bearer YOUR_API_KEY ``` API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/. 1. 画像のアップロード ファイルをサーバーに直接アップロードするか、AI タスクペイロードに有効な画像 URL を指定します。 * アップロードエンドポイント ``` POST /s2s/v2.0/file ``` すでに公開画像 URL がある場合は、この手順をスキップできます。 --- 2. 効果テンプレートの準備 * 前処理 ピクセル座標で検出されたバウンディングボックスを出力します。結果のインデックスを使用して、後で顔パーツ補正 AI タスクを作成します。 ``` { "timed": number, "result": [ { "left": number, "top": number, "width": number, "height": number } ] } ``` * 効果テンプレート JSON スキーマ ``` { "version": "1.0", "index": 0, "features": {}, "global": { "skin_smooth_strength": 50, "skin_smooth_color_intensity": 50, }, } ``` index: 前処理で検出された顔のインデックス。省略可、初期値 0。 features: 少なくとも 1 つの非ゼロの顔パーツ補正パラメータが必要。すべてゼロにはできません。 skin_smooth_strength: 0~100 skin_smooth_color_intensity: 0~100 * 効果フォーマット - 顔 初期範囲: -100~100 頬骨と顎の範囲: 0~100 すべての機能値が同時にゼロであってはなりません。少なくとも 1 つの機能値は非ゼロである必要があります ``` { "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, } ``` - 目 初期範囲: -100~100 すべての機能値が同時にゼロであってはなりません。少なくとも 1 つの機能値は非ゼロである必要があります ``` { "eye_size_left": 0, "eye_size_right": 0, "eye_distance": 0, "eye_angle": 0, "eye_height": 0, "eye_width": 0, } ``` - 鼻 初期範囲: -100~100 すべての機能値が同時にゼロであってはなりません。少なくとも 1 つの機能値は非ゼロである必要があります ``` { "nose_bridge_width": 0, "nose_lift": 0, "nose_size": 0, "nose_tip": 0, "nose_tip_width": 0, "nose_wing": 0 } ``` - 唇 初期範囲: -100~100 すべての機能値が同時にゼロであってはなりません。少なくとも 1 つの機能値は非ゼロである必要があります ``` { "lip_size": 0, "lip_width": 0, "lip_peak": 0, "lip_height_top": 0, "lip_height_bottom": 0, } ``` * ペイロードの例（送信可能） ``` { "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. 顔パーツ補正 AI タスクの作成と結果のポーリング 画像と完全な効果ペイロードが用意できたら、タスクを作成します。API はリクエストを非同期で処理します。タスクステータスが `success` または `error` に達するまでポーリングする必要があります。 * タスク作成エンドポイント ``` POST /s2s/v2.0/task/face-reshape ``` * ポーリングエンドポイント ``` GET /s2s/v2.0/task/face-reshape/{task_id} ``` --- ## ファイル仕様とエラー * AI 顔パーツ補正仕様 **サポートされるセルフィービュー** 画像の幅と高さの 1/20 より大きい顔の幅と高さを持つセルフィー。 ピッチ、ヨー、ロールの顔角度は 30 度未満。 ![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_face_reshape_01_85c8ffc055.jpg) **顔カスタマイズパラメータガイド** | カテゴリ | パラメータ | 機能 | 最小 (-100 / 0) | 最大 (100) | | -------- | ---------------- | ------------------------------------ | -------------- | ------------ | | 目 | サイズ (左/右) | 各目の全体的なサイズをスケーリング | 小さい | 大きい | | 目 | 幅 | 水平方向の範囲を調整 | 狭い | 広い | | 目 | 高さ | 垂直方向の範囲を調整 | 狭い / 平たい | 丸い / 高い | | 目 | 間隔 | 目と目の間の間隔を調整 | 近い | 遠い | | 目 | 角度 | 回転の傾きを調整 | 内側傾き | 外側傾き | | 顔 | サイズ (左/右) | 顔の各側のサイズをスケーリング | 小さい | 大きい | | 顔 | 顎の形 (左/右) | 顎の輪郭の幅を調整 | 狭い | 広い | | 顔 | 顎の長さ | 顎の垂直方向の長さを調整 | 短い | 長い | | 顔 | 幅 | 顔全体の幅を調整 | 狭い | 広い | | 顔 | 頬骨 | 頬骨の突出を調整 | 元 (0) | 引き締める | | 顔 | 顎 | 顎ラインの突出を調整 | 元 (0) | 引き締める | | 唇 | サイズ | 唇全体のボリュームをスケーリング | 小さい | 大きい | | 唇 | 幅 | 水平方向の範囲を調整 | 狭い | 広い | | 唇 | 上唇の高さ | 上唇の厚さを調整 | 薄い | 厚い | | 唇 | 下唇の高さ | 下唇の厚さを調整 | 薄い | 厚い | | 唇 | 山形 | キューピッドボウの鋭さを調整 | なめらか | 明確 | | 鼻 | サイズ | 鼻全体のサイズをスケーリング | 小さい | 大きい | | 鼻 | リフト | 垂直方向の位置を調整 | 低い | 高い | | 鼻 | 鼻梁 | 鼻梁の幅を調整 | 狭い | 広い | | 鼻 | 鼻尖 | 鼻尖の垂直角度を調整 | 上向き | 下向き | | 鼻 | 小鼻 | 鼻孔の幅を調整 | 狭い | 広い | | 鼻 | 幅 | 鼻尖の幅を調整 | 狭い | 広い | **注意:** *“左”と“右”はキャラクターの視点であり、視聴者の画面の側ではありません。* --- * サポートされる形式と寸法 |AI 機能|サポートされる寸法|サポートされるファイルサイズ|サポートされる形式| | ---- | ---- | ---- | ---- | |AI 顔パーツ補正|長辺 <= 4096|< 10MB|jpg/jpeg/png| * エラーコード | エラーコード | 説明 | | ---- | ---- | | RUNTIME_ERROR | 顔パーツ補正の実行中に予期しないエラーが発生しました | | PHOTO_DETECTION_FAIL | ユーザー写真を正しく処理できませんでした。例えば、手が検出されませんでした | | OBJECT_DETECTION_FAIL | オブジェクト写真を正しく処理できませんでした。例えば、製品が検出されませんでした | | PHOTO_CHECK_INVALID | ユーザー写真のポーズまたはサイズが無効です | | INPUT_ERROR | 入力ファイル形式が正しくありません | | INPUT_MAIN_IMAGE_EMPTY | ユーザー画像が必要です | * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON 解析) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性のため), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings 用), requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用), Jackson Databind >= 2.12.0 | --- ## JS カメラキット {% partial file="/_partials/js-camera-kit.md" /%} --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI 顔パーツ補正 V1.0 | 1 | --- - [AI 顔交換](https://docs.perfectcorp.com/ja/reference/ai_face_swap.md): # 概要 AI 顔交換では、写真内の顔を交換します。1 つまたは複数の顔の交換に対応しています。 ## 統合ガイド * AI 顔交換の実装方法 * ステップ 1: ソース画像と参照画像のアップロード 1. API からアップロード URL をリクエストします: ``` POST https://yce-api-01.makeupar.com/s2s/v2.0/file Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` ボディ: ```json { "files": [ { "file_name": "target.jpg", "file_size": 123456, "content_type": "image/jpeg" } ] } ``` 1. レスポンスには、事前署名付きの **アップロード URL** と `file_id` が含まれます。 2. 指定された URL に対して HTTP PUT リクエストでファイルをアップロードします。 3. 後で使用するために `file_id` を保存します。**ターゲット**画像と**参照**画像の両方に対してこの手順を繰り返します。 2. 実際のファイルを **アップロード URL** にアップロードします。 --- * ステップ 2: ソース画像と参照画像の前処理（顔検出） 1. 前処理タスクを作成します: ``` POST https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` ボディ: ```json { "request_id": 1, "payload": { "file_sets": { "src_ids": ["TARGET_FILE_ID"] }, "actions": [ { "id": 0 } ] } } ``` 1. API は `task_id` を返します。 2. タスクのステータスを次の URL でポーリングします: ``` GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process?task_id=TASK_ID ``` 1. 完了すると、バウンディングボックス付きの検出された顔のリストを受け取ります。 --- * ステップ 3: 顔交換タスクの実行 1. どの参照画像が各ソース画像を置き換えるかを定義します `face_mapping` 配列は、**ソース画像**内の顔が**参照画像**内の顔によってどのように置き換えられるかを定義します。これは、ソース内で検出された顔を特定の参照画像に接続するリンクリストとして機能します。 * 構造 配列内の各要素は、2 つのプロパティを含むオブジェクトです: | パラメータ | 型 | 説明 | | :--- | :--- | :--- | | `position` | `integer` | **ソース画像**内で検出された顔のインデックス（例: 0, 1, 2）。 | | `index` | `integer` | 交換対象となる**参照画像リスト**内の顔画像のインデックス。 | * ロジックルール 1. **インデックスマッピング:** `index` は、参照リストに提供された画像の順序に直接対応します。 * `0`: 1 番目の参照画像。 * `1`: 2 番目の参照画像。 2. **交換のスキップ:** ソース内で検出された特定の顔の交換をスキップするには、`index` と `position` の両方を `-1` に設定します。 3. **配列の順序:** 配列内のオブジェクトの順序は、`position` に基づいて一致させる必要があります。 * 使用例 **シナリオ:** * **参照リスト:** 2 枚の画像を提供（画像 A、画像 B）。 * **ソース画像:** 3 つの顔が検出される（顔 0、顔 1、顔 2）。 **目標:** * **顔 0**（ソース）を**画像 1**（参照）と交換する。 * **顔 1**（ソース）の交換をスキップする。 * **顔 2**（ソース）を**画像 0**（参照）と交換する。 **設定:** ```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. メインタスクリクエストを送信します: ``` POST https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` ボディ: ```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. レスポンスには `task_id` が返されます。 --- * ステップ 4: タスクステータスのポーリングと結果の取得 許可されたポーリングウィンドウ内で、一定の間隔でタスクステータスを照会するタイミングループを実装する必要があります。 1. 次の URL でポーリングします: ``` GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap?task_id=TASK_ID ``` 2. `status` が `success` になると、レスポンスには生成された画像の URL が含まれます。 3. その URL から画像をダウンロードまたは表示します。 --- * ステップ 5: プラットフォームへの統合 * **Web フロントエンド**では、fetch または Axios を使用して JavaScript で直接実装できます。 * **バックエンド**（Node.js、Python、Java、PHP など）では、標準的な HTTP ライブラリを使用して同じエンドポイントを使用できます。 * タスクは非同期で実行されるため、リトライとエラーハンドリングを実装してください。 --- * デバッグガイド 1. **Invalid TaskId エラー**
**理由:** タイムアウトしたタスクのステータスを確認しようとすると、InvalidTaskId エラーが発生します。したがって、AI タスクが開始されたら、ステータスが success または error に変わるまで、polling_interval 内でステータスをポーリングする必要があります。
**解決策:** タスクが無効になるのを避けるために、許可されたポーリングウィンドウ内で一定の間隔でタスクステータスを照会するタイミングループを実装する必要があります。 2. **ソース画像で一部の顔が検出されない理由**
**理由:** 顔がはっきりと見えており、覆われたり遮られたりしておらず、画像内で十分に大きい必要があります。
**解決策:** 顔が大きく写っており、覆いや遮りがなくはっきりと見える写真を撮影してみてください。 --- ## 入力と出力 * 実際の例: 複数顔交換サンプル: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_face_swap_S2_img_04_d4b747a41d.jpg) 単一顔交換サンプル: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_face_swap_S2_img_05_8e68faff2c.jpg) * 撮影方法の提案: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png) ## ファイル仕様とエラー * 対応フォーマットと寸法 |AI 機能|対応寸法|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | |AI 顔交換|入力と出力: 長辺が 4096 ピクセル以下|< 10MB|jpg/jpeg/png| * エラーコード | エラーコード | 説明 | | ------------------ | ----------- | | exceed_max_filesize | 入力ファイルサイズが最大制限を超えています | | invalid_parameter | パラメータ値が無効です | | error_download_image | ソース画像のダウンロード中にエラーが発生しました | | error_download_mask | マスク画像のダウンロード中にエラーが発生しました | | error_decode_image | ソース画像のデコード中にエラーが発生しました | | error_decode_mask | マスク画像のデコード中にエラーが発生しました | | error_download_video | ソース動画のダウンロード中にエラーが発生しました | | error_decode_video | ソース動画のデコード中にエラーが発生しました | | error_nsfw_content_detected | ソース画像で NSFW コンテンツが検出されました | | error_no_face | ソース画像で顔が検出されませんでした | | error_pose | ソース画像でポーズの検出に失敗しました | | error_face_parsing | ソース画像での顔解析に失敗しました | | error_inference | 推論パイプラインでエラーが発生しました | | exceed_nsfw_retry_limits | NSFW 画像の生成を避けるためのリトライ制限を超えました | | error_upload | 結果画像のアップロード中にエラーが発生しました | | error_multiple_people | 人物の数が最大制限を超えています | | error_no_shoulder | ソース画像で肩が見えません | | error_large_face_angle | アップロード画像の顔の角度が大きすぎます | | error_unsupport_ratio | 入力画像のアスペクト比はサポートされていません | | unknown_internal_error | その他の内部エラー | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI 顔交換 V1.0 | 1 | --- - [AI フィッツパトリック肌タイプ分析](https://docs.perfectcorp.com/ja/reference/ai_fitzpatrick_skin_type.md): # 概要 ![](https://plugins-media.makeupar.com/smb/blog/post/2026-01-28/webp_a00e88ca-e20a-4082-89c2-9d486b03b8e8.webp) **AI フィッツパトリック肌タイプ分析** AI 駆動のフィッツパトリック肌タイプ検出をアプリケーションに統合し、カメラ入力を使用して肌タイプを分類します。e コマースおよびデジタルヘルスプラットフォームで、スキンケア、日焼け止め、製品推奨ワークフローに使用できます。 **肌タイプ検出** この API は、コンピュータビジョンと機械学習モデルを使用して肌の特徴を分析し、単一のリクエストでフィッツパトリック分類を返します。フロントエンドアプリケーション、推奨エンジン、または臨床システムによって直接消費可能な、構造化された客観的なデータを提供します。 トーマス・B・フィッツパトリック博士によって導入されたフィッツパトリックスケールは、メラニンレベルと UV 曝露への反応に基づいて 6 つの肌タイプを定義し、システムが日焼けや日焼けしやすさを予測できるようにします。 **分類出力** API は、UV 反応モデリングに基づいて、タイプ I からタイプ VI までの 6 つの標準化された肌タイプのいずれかを返します。 この出力で、カスタマイズされた製品推奨を提供し、スキンケアワークフローを自動化できます。 | フィッツパトリックスケール | 肌タイプ | 太陽に対する肌の反応 | | ---- | ---- | ---- | | タイプ I | 白 | ほぼ必ず日焼けし、日焼けしない | | タイプ II | ベージュ | 通常日焼けし、わずかに日焼けする | | タイプ III | 明るい茶色 | 時々日焼けし、徐々に日焼けする | | タイプ V | 中程度の茶色 | ほとんど日焼けせず、日焼けしやすい | | タイプ V | 濃い茶色 | 非常にまれに日焼けする | | タイプ VI | 非常に濃い茶色 | ほとんど日焼けしない | ![](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) --- ## 統合ガイド **1. 画像のキャプチャ** 十分な照明の下で正面を向いた画像をキャプチャします。顔がはっきりと見え、フレームの十分な部分を占めていることを確認してください。 **2. 画像のアップロード** 以下のエンドポイントを通じて、アップロード URL とファイル ID をリクエストします。 ``` POST /s2s/v2.0/file ``` 返された URL を使用して画像をアップロードします。 または、独自のストレージにホストされている公開アクセス可能な画像 URL を提供します。 **3. オプションの前処理** ``` POST /s2s/v2.0/task/fitzpatrick-scale-analyzer/pre-process ``` 画像に複数の顔が含まれている場合、または明示的なターゲット選択が必要な場合にこの手順を使用します。単一の顔の画像の場合、デフォルトのインデックスで十分な場合、この手順はスキップできます。 **4. 前処理結果の取得** ``` GET /s2s/v2.0/task/fitzpatrick-scale-analyzer/pre-process ``` [Webhook](../develop/webhook.md) を設定するか、ポーリングを実装してタスク結果を取得します。Webhook を使用すると、タスクが完了したときにアプリケーションが自動的に通知を受信します。ポーリングを使用すると、ステータスが running から success または error に変更されるまで、システムがタスクエンドポイントを繰り返し呼び出します。 **5. 分析タスクの実行** ``` POST /s2s/v2.0/task/fitzpatrick-scale-analyzer ``` ファイル ID または画像 URL を入力として使用してタスクを送信します。レスポンスには、追跡および結果取得用の task_id が返されます。 **6. タスク結果の取得** ``` GET /s2s/v2.0/task/fitzpatrick-scale-analyzer/{task_id} ``` タスク ID を使用してステータスを追跡し、結果を取得します。 [Webhooks](../develop/webhook.md) を設定して、success または error ステータスでタスク完了時の非同期通知を受信できます。ステータスが running から success または error に更新されるまでタスクエンドポイントを繰り返し呼び出すことにより、ポーリングもサポートされています。 使用料は、タスクが正常に完了した場合にのみ課金されます。 --- ## ファイル仕様とエラー * サポートされる形式と寸法 |AI 機能|サポートされる寸法|サポートされるファイルサイズ|サポートされる形式| | ---- | ---- | ---- | ---- | | AI フィッツパトリック肌タイプ分析 | 長い辺の長さは 4096 ピクセルを超えてはならず、短い辺の長さは 320 ピクセル以上でなければなりません。 | < 10MB | jpg/jpeg | * エラーコード |エラーコード|説明| | ---- | ---- | | error_below_min_image_size | ソース画像の寸法は少なくとも 320 ピクセルでなければなりません。 | |error_face_position_invalid|画像内で顔が完全に可視であり、切り取られた部分がない必要があります| |error_face_position_too_small|写真内の顔が小さすぎて適切に分析できません| |error_face_position_out_of_boundary|顔が大きすぎるか、写真の端の一部が外れています| |error_insufficient_lighting|照明が暗すぎて分析が困難です| |error_face_angle_invalid|顔の角度が正しくありません。正面からの撮影では、頭を正面から 10 度以内に保ってください。横からの撮影では、角度は 15 度以上である必要があります| * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON パーシング) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性用), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings 用), requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用), Jackson Databind >= 2.12.0 | --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | AI フィッツパトリック肌タイプ分析 V1.0 | 10 | --- - [ヘアカラー](https://docs.perfectcorp.com/ja/reference/ai_hair_color.md): # 概要 ヘアカラーチェンジャーで、幅広いヘアカラーを試せます。スライダーで選択したカラーの濃淡を調整できます。 * 画像をアップロード ヘアカラーを変更したい写真をアップロードします。 * プリセットカラーを選択、またはパターンとパレットでカスタマイズ predefined なカラープリセットから選択するか、グラデーション（オンブレ）の適用範囲やブレンドを調整できます。 > **警告:** プリセットとパターン＋パレットの両方が指定されている場合、プリセットが優先されます。 > **警告:** 元の画像には、染めたい髪の領域が含まれている必要があります。適用前に確認してください。これはユーザー側の責任となります。 ![](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) ## ファイル仕様とエラー * 対応フォーマットとサイズ |AI 機能|対応サイズ|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | |AI ヘアカラー|長辺 < 1920、顔幅 >= 100|< 10MB|jpg/jpeg/png| * エラーコード |エラーコード|説明| | ---- | ---- | |error_below_min_image_size|元の画像サイズが最小値より小さい（期待値: 幅 >= 320px、高さ >= 320px） |error_exceed_max_image_size|元の画像サイズが最大値より大きい（期待値: 幅 < 1920px、高さ < 1080px） * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON パーシング) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch のため) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性のため)、ext-curl (推奨) または allow_url_fopen=On + ext-openssl、ext-json | | Python | Python >= 3.10 (f-strings のため)、requests >= 2.20.0 | | Java | Java 11+ (HttpClient のため)、Jackson Databind >= 2.12.0 | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI ヘアカラーバーチャル試着 V1.0 | フルモードで 1 ユニット
オンブレモードで 1 ユニット | --- - [髪密度分析](https://docs.perfectcorp.com/ja/reference/ai_hair_density_detection.md): # 概要 AI 髪密度分析では、アップロードした 1 枚の画像から頭皮の可視性と髪の分布パターンを評価し、髪の密度を 4 つのレベルに分類します。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_hair_density_S3_02_b34f2db2ce.jpg) ## 統合ガイド * AI 髪密度分析用の写真の撮影方法 * セルフィーを撮影する - カメラを正面に向け、適切な照明の下で頭を45度下げてください。髪を結ばず、生え際全体がはっきりと見えるようにしてください。 ![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_popup_step_animated_02.aadf7a34.png) - 代わりに、JS Camera Kit を使用して写真を撮影してください。 * AI による髪密度の検出方法 * ***/s2s/v2.0/file*** API を使用して、以下のアセットをアップロードします： - セルフィー写真。 * AI タスク ***/s2s/v2.0/task/hair-density-detection*** を実行
正面から45度下げたセルフィー画像を1枚送信して検出タスクを実行します。AI のソース入力としてそのファイル ID を使用します。 * タスクのステータスを成功またはエラーになるまでポーリングして確認する
この ***task_id*** は、GET 'task/hair-density-detection' によるポーリングを通じてタスクのステータスを監視するために使用され、現在のエンジンステータスを取得します。エンジンがタスクを完了するまで、ステータスは 'running' のままであり、この段階ではユニットは消費されません。 ## 髪密度の分類 |サムネイル|髪密度の分類|説明| | ---- | ---- | ---- | |![](https://d3ss46vukfdtpo.cloudfront.net/static/media/dt_classification_LV01.5097a6c2.png)|レベル 1
極めて低い密度|髪が著しくまばらで、広い範囲で頭皮が見えます。| |![](https://d3ss46vukfdtpo.cloudfront.net/static/media/dt_classification_LV02.7966983d.png)|レベル 2
低い密度|特に頭頂部や分け目で頭皮がはっきりと見える、目立つ薄毛があります。| |![](https://d3ss46vukfdtpo.cloudfront.net/static/media/dt_classification_LV03.c49dbfb7.png)|レベル 3
中程度の密度|直射日光の下で頭皮が部分的に見えますが、髪は中程度のボリュームとカバー率を維持しています。| |![](https://d3ss46vukfdtpo.cloudfront.net/static/media/dt_classification_LV04.e467f2aa.png)|レベル 4
高い密度|髪はふさふさで厚く見え、頭皮はほとんどまたは全く見えません。| * 撮影方法のヒント ![撮影方法のヒント](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/icon_S2_step1_20d0a161da.png "撮影方法のヒント") ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_hair_density_S1_02_f60369b14d.jpg) ## ファイル仕様とエラー * 対応フォーマットと寸法 |タイプ|対応寸法|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | |AI 髪密度分析|画像は幅と高さが少なくとも100ピクセル、いずれかの次元で4096ピクセル以下である必要があります。画像の片方の辺が1080ピクセルを超える場合、分析のためにその制限内に自動的にリサイズされます。|< 10MB|jpg/png| * エラーコード |エラーコード|説明| | ---- | ---- | |error_below_min_image_size|画像の幅または高さが100ピクセル未満の場合、小さすぎて使用できません| |error_face_position_invalid|画像内で顔全体が完全に可視であり、一部が切れていない必要があります| |error_face_position_too_small|写真内の顔が小さすぎて適切に分析できません| |error_face_position_out_of_boundary|顔が大きすぎるか、写真の端の一部が外れています| |error_insufficient_lighting|照明が暗すぎて、分析が困難です| |error_face_angle_invalid|顔の角度が正しくありません。正面を向いた撮影では、頭を正面から10度以内に保ってください。横を向いた撮影では、角度は15度以上である必要があります| * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON 解析) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch のため) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性のため)、ext-curl (推奨) または allow_url_fopen=On + ext-openssl、ext-json | | Python | Python >= 3.10 (f-strings のため)、requests >= 2.20.0 | | Java | Java 11+ (HttpClient のため)、Jackson Databind >= 2.12.0 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | AI 髪密度分析 V1.0 | 1 | --- - [AI ヘアエクステ](https://docs.perfectcorp.com/ja/reference/ai_hair_extension.md): # 概要 AI で理想のヘアエクステを見つけよう 長さはロングからエクストラロングまで、スタイル、カラー、前髪など、さまざまな組み合わせをデバイス上で試せます。生成 AI により、ヘアエクステのスタイルがどのように見えるかを確認できます。 現在の髪の長さに自然に馴染む AI ヘアエクステで、超ロングスタイルを試す絶好の機会です。 ユースケース: ![AI ヘアエクステ](https://bcw-media.s3.ap-northeast-1.amazonaws.com/YCE_web_Hair_Extension_Filter_S2_img_07_098b6e08c4.jpg "AI Hair Extension") ![AI ヘアエクステ](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](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png "Suggestions for How to Shoot") --- ## ファイル仕様とエラー * 対応フォーマットと寸法 |AI 機能|対応寸法|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | |AI ヘアエクステ|長辺 <= 1024、顔幅 >= 128、顔の姿勢: -10 < pitch < +10, -45 < yaw < +45, -15 < roll < +15、単一の顔のみ、顔全体が写っている必要あり|< 10MB|jpg/jpeg| * エラーコード |エラーコード|説明| | ---- | ---- | |error_no_shoulder |ソース画像に肩が写っていません |error_large_face_angle |アップロードされた画像の顔の角度が大きすぎます |error_insufficient_landmarks |ソース画像で十分な顔または体のランドマークを検出できません |error_hair_too_short |入力された髪が短すぎます |error_face_pose |ソース画像の顔の姿勢はサポートされていません |error_bald_image |入力されたヘアスタイルがハゲています --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI ヘアエクステ V1.0 | 1 | --- - [髪のうねり分析](https://docs.perfectcorp.com/ja/reference/ai_hair_frizziness_detection.md): # 概要 180° フルビュー髪のうねり分析 AI 髪のうねり分析ツールでは、髪の正面、左側、右側の 3 枚の写真をアップロードして髪のうねりレベルを分析します。 企業は、髪のうねりレベルに基づいたヘアソリューションやアンチフラジー製品を提供できます。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_frizzy_S_02_enu_b80c238858.jpg) ## 統合ガイド 1. **セルフィーのアップロード** ソース画像は以下の 2 通りの方法で提供できます。 - **既存の公開画像 URL の使用** アップロードの代わりに、AI タスクを開始する際に公開アクセス可能な画像 URL を直接指定できます。 - **File API によるアップロード** エンドポイントを使用します。 ``` POST /s2s/v2.0/file ``` これにより、後続のタスク実行用の `file_id` が返されます。 - ***重要***: File API を呼び出すだけではファイルはアップロードされません。File API のレスポンスで提供された **URL に手動でファイルをアップロード** する必要があります。その URL がアップロード先です。次に進む前に、ファイルが正常に転送されたことを確認してください。 AI API を呼び出す前に、ファイルが正常にアップロードされていることを確認してください。File API を使用してアップロード URL を取得し、その場所にファイルをアップロードします。アップロードが完了すると、レスポンスに ***file_id*** が含まれます。この ID は、そのファイルに関連する AI 機能にアクセスするために使用します。 > **警告:** File API のレスポンスで提供された URL にファイルをアップロードしない場合、AI API の使用時に 500 Server Error / unknown_internal_error または 404 Not Found エラーが発生します。 2. **AI タスクの実行とタスク ID の取得** /s2s/v2.0/task/hair-frizziness-detection を使用して AI タスクを実行します。対象ユーザー画像には、``src_file_url`` または ``src_file_id`` のいずれかを指定します。また、適用するスタイルの ``template_id`` を指定し、``task_id`` を取得します。 3. **タスクのステータス確認のためのポーリング（成功または失敗まで）** ``task_id`` を使用して、GET /s2s/v2.0/task/hair-frizziness-detection をポーリングし、現在のエンジンステータスを取得してタスクのステータスを監視します。エンジンがタスクを完了するまで、ステータスは running のままとなり、この段階ではユニットは消費されません。 AI タスクが成功または失敗した際に通知を受け取るために Webhook を実装することもできます。詳細は **[Webhook](../../../../develop/webhook)** セクションを参照してください。 > **警告:** 保持期間内にタスクのステータスを確認するためにポーリングを行うことが必須です。保持期間内にポーリングリクエストがない場合、タスクが正常に処理されていてもタイムアウトします。ユニットは消費されます。 > **警告:** タイムアウトしたタスクのステータスを確認すると、InvalidTaskId エラーが発生します。したがって、AI タスクを実行した後は、ステータスが success または error になるまで、保持期間内にステータスを確認するためにポーリングを行う必要があります。 4. **成功後の AI タスク結果の取得** エンジンが入力ファイルを処理し、結果画像を生成すると、タスクのステータスは success に変わります。処理済み画像の URL が返されます。 ## 入力と出力 * 入力形式 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_frizzy_step_01_ac5c651ea4.png) 髪の正面、左側、右側の 3 枚の写真をアップロードします。 JS Camera Kit を使用して、3 枚の適格な写真を撮影するための Javascript カメラモジュールを実装できます。 * 出力形式 AI 髪のうねり分析ツールでは髪質を評価し、滑らかな髪から非常にうねった髪まで、4 つの異なる髪のうねり度を識別します。 | **マッピング (0–3)** | **用語** | **説明** | | ----------------- | ------------------- | --------------------------------------------------------- | | 0 | Not Frizzy | 髪は滑らかで、目立つうねりはほとんどまたは全く見られません。 | | 1 | Slightly Frizzy | 軽いうねりが見られます。表面の質感にわずかな不規則性があります。 | | 2 | Frizzy | 髪全体に目立つうねりがあります。質感の乱れが明確です。 | | 3 | Extreme Frizzy | 強いうねりが広範囲に見られます。髪の質感が非常に不規則です。 | ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_frizzy_S_01_enu_fcd10905ff.jpg) * サンプル出力 ```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"] } ``` ## ファイル仕様とエラー * サポートされる形式と寸法 |タイプ|サポートされる寸法|サポートされるファイルサイズ|サポートされる形式| | ---- | ---- | ---- | ---- | |AI 髪のうねり分析|画像は幅と高さともに少なくとも 320 ピクセル、いずれかの次元で最大 4096 ピクセルである必要があります。画像の片側の長さが 1080 ピクセルを超える場合、分析のためにその制限内に自動的にリサイズされます。|< 10MB|jpg/png| * エラーコード |エラーコード|説明| | ---- | ---- | |error_mismatch_image_size|すべての顔写真（正面、左側、右側）が同じサイズであることを確認してください| |error_below_min_image_size|画像の幅または高さが 320 ピクセル未満の場合、使用するには小さすぎます| |error_face_position_invalid|画像内で顔全体が完全に視認可能であり、一部が切れていない必要があります| |error_face_position_too_small|写真内の顔が小さすぎて適切に分析できません| |error_face_position_out_of_boundary|顔が大きすぎるか、写真の端の一部が外れています| |error_insufficient_lighting|照明が暗すぎて、分析が困難です| |error_face_angle_invalid|顔の角度が正しくありません。正面を向いたショットでは、頭を正面から 10 度以内に保ってください。横を向いたショットでは、角度は 15 度以上である必要があります| * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON パーシング) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性用), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings 用), requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用), Jackson Databind >= 2.12.0 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | AI 髪のうねり分析 V1.0 | 2 | --- - [髪の長さ分析](https://docs.perfectcorp.com/ja/reference/ai_hair_length_detection.md): # 概要 AI 髪の長さ測定では、髪の長さを分析・測定し、パーソナライズされた製品やサービスの決定を支援します。 耳上から背中中央までの 5 つの髪の長さを識別・分類します。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_length_S1_01_enu_b03bd393af.jpg) ## 統合ガイド * 髪の長さ分析のための撮影方法 * 正面を向いて自撮り写真を撮影します - カメラをまっすぐ見ている、1 枚のクリアな写真のみで十分です。髪を下ろして胸にかかっている状態にし、真正面を向いて撮影してください。 - 代わりに、JS Camera Kit を使用して写真を撮影します。髪を下ろして胸にかかっている状態にしてください。結ばないでください。 * AI による髪の長さの検出方法 * ***/s2s/v2.0/file*** API を使用して、以下のアセットをアップロードします: - 自撮り写真。 * AI タスク ***/s2s/v2.0/task/hair-length-detection*** の実行
正面を向いた自撮り画像を 1 枚送信して、髪の長さ検出タスクを実行します。AI のソース入力としてそのファイル ID を使用します。 * タスクのステータスを成功またはエラーになるまでポーリングで確認します
この ***task_id*** は、GET 'task/hair-length-detection' によるポーリングを通じてタスクのステータスを監視するために使用され、現在のエンジンステータスを取得します。エンジンがタスクを完了するまで、ステータスは 'running' のままであり、この段階ではユニットは消費されません。 ## 髪の長さの分類 |サムネイル|髪の長さの分類|説明| | ---- | ---- | ---- | |![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_above_the_ears.b41525da.png)|耳上長さ|耳のすぐ上までかかる髪。| |![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_ear_length.0740b805.png)|耳長さ|耳たぶまで届く髪。| |![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_short_hair.d7f24ddb.png)|ショートヘア|肩より上でカットされた髪。| |![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_above_chest.1b624c17.png)|ミディアム長さ|鎖骨付近までかかる髪。| |![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_longer_hair.7fbcc9d0.png)|ロングヘア|背中中央までかかる髪。| * 結果引数 * term: 結果は、検出された髪の長さタイプを示す文字列です。考えられるすべての結果文字列を配列で以下に示します: ```json ["above the ears", "ear length", "ear length or longer", "short hair", "short hair or longer", "above chest", "above chest or longer", "long hair"] ``` * 撮影方法の提案 ![撮影方法の提案](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Hair%20Length%20Detection_how%20to%20shoot.png "撮影方法の提案") ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Skin%20Analysis_camera.png) ## ファイル仕様とエラー * 対応フォーマットと寸法 |タイプ|対応寸法|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | |髪の長さ分析|画像は幅と高さともに少なくとも 320 ピクセル、いずれかの次元で最大 4096 ピクセルである必要があります。画像の片側の長さが 1080 ピクセルを超える場合、分析のためにその制限内に自動的にリサイズされます。|< 10MB|jpg/png| * エラーコード |エラーコード|説明| | ---- | ---- | |error_below_min_image_size|画像の幅または高さが 320 ピクセル未満の場合、小さすぎて使用できません| |error_face_position_invalid|画像内で顔全体が完全に視認可能であり、一部が切れていない必要があります| |error_face_position_too_small|写真内の顔が小さすぎて、適切に分析できません| |error_face_position_out_of_boundary|顔が大きすぎるか、写真の端の一部または全体が外れています| |error_insufficient_lighting|照明が暗すぎて、分析が困難です| |error_face_angle_invalid|顔の角度が適切ではありません。正面を向いた撮影では、頭を正面から 10 度以内に保ってください。横を向いた撮影では、角度が 15 度以上である必要があります| * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON パーシング) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性のため), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings のため), requests >= 2.20.0 | | Java | Java 11+ (HttpClient のため), Jackson Databind >= 2.12.0 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | 髪の長さ分析 V1.0 | 2 | --- - [髪タイプ分析](https://docs.perfectcorp.com/ja/reference/ai_hair_type_detection.md): # 概要 AI 髪タイプ分析では、髪の質感、厚み、カールのパターンを分析し、ストレートから kinky までの 9 つの明確なタイプに分類します。 ## 統合ガイド * AI 髪タイプ分析のための撮影方法 * 左、正面、右の 3 方向から写真を撮影します。 - 3 枚のセルフポートレートを素早く撮影してください。1 枚は正面を向き、1 枚は左に約 45 度回転し、1 枚は右に 45 度回転します。髪の全体像をあらゆる角度から捉えることが目的です。各写真で顔全体と髪の上部の境界線がはっきりと見えるようにしてください。顔が画像幅の約 50% から 80% を占めるようにします。小さすぎず、近すぎない距離で撮影してください。これにより、分析に十分な鮮明さが確保されます。横顔のショットを撮影する際は、首を左右に振る（ヨー回転）ように頭を回転させてください。頭を上下左右に傾けず、水平に保ってください。背面や上からの角度は分析に使用できないため、避けてください。 - 写真撮影には JS Camera Kit を利用できます。髪を結ばず、胸の前で垂らした状態にしてください。頭を右に向けて静止し、次に左に向けて、分析用の 3 枚の画像を撮影します。 * AI による髪タイプの検出方法 * ***/s2s/v2.0/file*** API を使用して、以下のアセットをアップロードしてください： - 正面、右側面、左側面の写真。 * AI タスク ***/s2s/v2.0/task/hair-type-detection*** の実行
正面、右側面、左側面の 3 枚の画像を送信して、髪タイプ検出タスクを実行します。これらのファイル ID を AI のソース入力として使用します。 * タスクのステータスを成功またはエラーになるまでポーリングで確認する
この ***task_id*** は、GET 'task/hair-type-detection' によるポーリングを通じてタスクのステータスを監視するために使用され、現在のエンジンステータスを取得します。エンジンがタスクを完了するまで、ステータスは 'running' のままとなり、この段階ではユニットは消費されません。 ## 髪タイプの分類 |カテゴリー|サムネイル|髪タイプの分類|説明| | ---- | ---- | ---- | ---- | |1|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t1.b19d4657.jpg)|ストレート|カールがなく、根元から毛先までストレートに落ちる髪| |2A|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t2A.351ef0a6.jpg)|ややウェーブ|控えめで繊細なウェーブ。滑らかな質感、根元にボリュームはありません| |2B|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t2B.daac62f4.jpg)|中程度のウェーブ|髪の中間部から始まる S 字型のウェーブ| |2C|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t2C.10ef2132.jpg)|厚手のウェーブ|根元から始まる S 字型のウェーブ。粗い質感、広がりやすい| |3A|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t3A.073b6767.jpg)|ゆるいカール|大きくゆるやかなカール| |3B|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t3B.06bf109b.jpg)|中程度のカーリー|粗く弾力のあるリングレット。広がりやすい| |3C|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t3C.9091ea1e.jpg)|タイトなカーリー|密でコンパクトなコルクスクリュー形状| |4A|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t4A.cf742771.jpg)| kinky ソフト|密に詰まった弾力のある S 字型のコイル| |4B|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t4B.4a6300fe.jpg)|コイリー|鋭いジグザグ角度に強く巻き込まれた、密に詰まったコイル| |4C|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t4C.4ed5a7f8.jpg)|極度のコイリー|きつくふわふわしたコイル。切れやすい| * 結果引数 * mapping: 結果は、検出された髪タイプのカテゴリーを示す文字列です。考えられるすべての結果文字列を配列で以下に示します： ```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: 髪タイプのカテゴリーとその分類間の 1 対 1 のマッピング文字列です。考えられるすべての結果文字列を配列で以下に示します： ```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"] ``` * 撮影方法のヒント ![撮影方法のヒント](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Hair%20Type%20Detection_how%20to%20shoot.png "撮影方法のヒント") ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Skin%20Analysis_camera.png) ## ファイル仕様とエラー * 対応フォーマットと寸法 |タイプ|対応寸法|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | |AI 髪タイプ分析|画像は幅と高さともに少なくとも 320 ピクセル、いずれかの次元で最大 4096 ピクセルである必要があります。画像の片側の長さが 1080 ピクセルを超える場合、分析用にその制限内に自動的にリサイズされます。|< 10MB|jpg/png| * エラーコード |エラーコード|説明| | ---- | ---- | |error_mismatch_image_size|すべての顔写真（正面、左、右）が同じサイズであることを確認してください| |error_below_min_image_size|画像の幅または高さが 320 ピクセル未満の場合、使用するには小さすぎます| |error_face_position_invalid|画像内で顔全体が完全に可視であり、一部が切れていない必要があります| |error_face_position_too_small|写真内の顔が小さすぎて、適切に分析できません| |error_face_position_out_of_boundary|顔が大きすぎるか、写真の端の一部が外れています| |error_insufficient_lighting|照明が暗すぎて、分析が困難です| |error_face_angle_invalid|顔の角度が適切ではありません。正面を向いたショットでは、頭を正面から 10 度以内に保ってください。横顔を向いたショットでは、角度が 15 度以上である必要があります| * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON 解析) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch のため) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性のため), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings のため), requests >= 2.20.0 | | Java | Java 11+ (HttpClient のため), Jackson Databind >= 2.12.0 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | AI 髪タイプ分析 V1.0 | 2 | --- - [ヘアボリューム](https://docs.perfectcorp.com/ja/reference/ai_hair_volume.md): # 概要 AI でふんわりしたボリュームヘアにできます。 細毛や薄毛に自然なボリュームを付けられます。AI で隙間を埋めたり、髪を追加したりできます。ストレート、カール、細毛などすべての髪質に対応しています。 プライベート、ビジネス、SNS などの写真で、髪のボリュームと密度を調整できます。 ユースケース: ![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](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png "Suggestions for How to Shoot") --- ## ファイル仕様とエラー * 対応フォーマットとサイズ |AI 機能|対応サイズ|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | |ヘアボリューム|長辺 <= 1024、顔幅 >= 128、顔の向き: -10 < pitch < +10, -45 < yaw < +45, -15 < roll < +15、単一の顔のみ、顔全体が写っている必要あり|< 10MB|jpg/jpeg/png| * エラーコード |エラーコード|説明| | ---- | ---- | |error_no_shoulder |ソース画像に肩が写っていません |error_large_face_angle |アップロードされた画像の顔の角度が大きすぎます |error_insufficient_landmarks |ソース画像で十分な顔または体のランドマークを検出できません |error_hair_too_short |入力された髪が短すぎます |error_face_pose |ソース画像の顔の向きがサポートされていません |error_bald_image |入力されたヘアスタイルがハゲています --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | ヘアボリューム V1.0 | 2 | --- - [髪型シミュレーション](https://docs.perfectcorp.com/ja/reference/ai_hairstyle.md): # 概要 AI 髪型シミュレーションで、さまざまな髪型を試します。 カール、ロング、ベリーショートなどのスタイルに対応しています。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_style_v3_poster_bb1c7aad10.jpg) --- ## 統合ガイド * API プレイグラウンド API プレイグラウンドで AI 髪型シミュレーション機能をテストします。 API プレイグラウンドにアクセスするには： --- * API ワークフロー このガイドでは、AI 髪型シミュレーション API のワークフローを説明します。 **エンドポイント:** `/s2s/v2.1/task/hair-transfer` **認証必須:** `Authorization: Bearer YOUR_API_KEY` **ワークフロー手順:** 1. **画像アップロード準備:** - プロセスはセルフィーの準備から始まります。 2. **プリセットテンプレートのリスト取得、または独自のリファレンス写真の使用** **リファレンスソースの選択** スタイル参照には 2 つのオプションがあります。 | オプション | 使用ケース | 実装ヒント | |-------|-----------|---------------------| | **プリセットテンプレート** (`template_id`) | 迅速な開始（例：「カールボブ」、「サイドスウェプトバングス」） | `/s2s/v2.1/task/template/hair-transfer` を呼び出し、`template_id` を選択します。 | | **カスタムリファレンス画像** (`ref_file_url` / `ref_file_id`) | ユーザーが自身のスタイル写真をアップロード、または提供された画像リンクを使用 | 同じファイル API を介してアップロードします。
リファレンス画像がすでにオンラインでホストされている場合は `ref_file_url` を使用します。 | 3. **AI タスクの開始とタスク ID の取得:** - アップロードした画像とスタイル設定を HTTP POST リクエストで `/s2s/v2.0/file` に送信します。 - このインタラクションを識別する一意のタスク ID をレスポンスで待ちます。 4. **タスクステータスのポーリング（継続的な確認）:** - 取得した `task_id` を使用して、HTTP GET リクエスト（例：`GET /task/${task_id}`）でタスクステータスを定期的にポーリングします。 - 以下を継続的に監視します。 - `Task_status = "success"`（処理完了）。 - `Task_status = "error"`（該当する場合は解決または再試行）。 - ステータスが成功に遷移したら、ワークフローを適切に更新します。 --- * 認証 - **Bearer トークン** を使用して、リクエストヘッダーに API キーを含めます。 ``` Authorization: Bearer YOUR_API_KEY ``` API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/. --- * API 使用ガイド このガイドでは、画像のアップロード、リファレンス画像の準備、および AI 髪型シミュレーション API を使用したバーチャル試着タスクの作成方法について説明します。 *** * ステップ 1. ファイル API を使用したファイルのアップロード、または有効な画像 URL の提供 **ファイル API** (`/s2s/v2.0/file`) を使用して、対象ユーザーの画像をアップロードします。 すでに公開されている画像 URL がある場合は、ステップ 1〜3 をスキップできます。 **画像要件:** * 高解像度のセルフィー写真をアップロードします。 * 写真に全身がはっきりと映っていることを確認します。 * 複数の人物や邪魔なオブジェクトがある背景は避けてください。 **リクエスト例:** ```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 } ] }' ``` *** * ステップ 2. ファイル API レスポンスの取得 レスポンスには以下が含まれます。 * AI タスク作成用の `file_id`。 * 実際の画像ファイルをアップロードするための `requests.url`。 **レスポンス例:** ```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" } } ] } ] } } ``` *** * ステップ 3. 提供された URL への画像アップロード ファイル API レスポンスの `requests.url` を使用して画像をアップロードします。 ```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' ``` *** * ステップ 4. リファレンス画像の準備 * 4.1 プリセット画像テンプレートの取得 **テンプレート API** (`/s2s/v2.1/task/template/hair-transfer`) を使用して、プリセットリファレンステンプレートのリストを取得します。 ```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 リファレンス画像のアップロード 以下が可能になります。 * ファイル API (`/s2s/v2.0/file`) を使用してリファレンス画像をアップロードする、または * 有効な画像 URL を提供する。 **サポートされる画像:** * リファレンス画像としての別のセルフィー写真。 詳細な仕様については **[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)** を参照してください。 *** * ステップ 5. AI 髪型シミュレーションタスクの作成 **AI タスク API** (`/s2s/v2.1/task/hair-transfer`) を使用して、バーチャル試着タスクを作成します。 **パラメータ:** * ユーザー画像用： `src_file_id` または `src_file_url`。 * リファレンス画像用： `ref_file_id`、`ref_file_url`、または `template_id`。 **リクエスト例:** ```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" }' ``` **レスポンス例:** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` *** * ステップ 6. タスク結果のポーリング タスク ID を使用してステータスを確認します。 ```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' ``` *** * ステップ 7. 結果の取得 成功したレスポンスには、結果画像のダウンロード URL が含まれます。 ```json { "status": 200, "data": { "error": null, "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..." }, "task_status": "success" } } ``` 無効な API キーエラーレスポンス： ```json { "status": 401, "error": "Unauthorized", "error_code": "InvalidAccessToken" } ``` --- ユースケース： ユースケース： ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_style_v1_video_08513beb46.jpg) 撮影方法の提案： ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png) ## ファイル仕様とエラー * サポートされる形式と寸法 |AI 機能|サポートされる寸法|サポートされるファイルサイズ|サポートされる形式| | ---- | ---- | ---- | ---- | |AI 髪型シミュレーション|長辺 <= 1024、顔幅 >= 128、顔のポーズ: -10 < pitch < +10, -45 < yaw < +45, -15 < roll < +15、単一の顔のみ、顔全体が見える必要がある|< 10MB|jpg/jpeg| * エラーコード |エラーコード|説明| | ---- | ---- | |error_no_shoulder |ソース画像に肩が見えません |error_large_face_angle |アップロードされた画像の顔の角度が大きすぎます |error_insufficient_landmarks |ソース画像で十分な顔または体のランドマークを検出できません |error_hair_too_short |入力された髪が短すぎます |error_face_pose |ソース画像の顔のポーズはサポートされていません * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON 解析) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性用), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings 用), requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用), Jackson Databind >= 2.12.0 | --- ## FAQ **Q: カスタムの髪型を試すことはできますか？** **A:** はい、独自のリファレンス写真を使用してカスタムの髪型を試すことができます。AI 髪型シミュレーションでは、希望する髪型を指定するための 2 つの方法をサポートしています。 1. **独自のリファレンス画像のアップロード** ファイル API (`/s2s/v2.0/file`) を介して、高解像度のセルフィーやスタイル写真（例：ターゲットの髪型をしている人物）をアップロードできます。アップロード後、AI タスク作成時に返された `file_id` または公開 URL をリファレンスソースとして使用します。 2. **有効な画像 URL の提供** リファレンス画像がすでにオンラインでホストされている場合（例：独自サーバーや CDN 上）、リクエストボディの `ref_file_url` フィールドに HTTPS URL を直接指定できます。 `/s2s/v2.1/task/hair-transfer` を介してタスクを送信する際は、以下を含めます。 - `src_file_id`（セルフィー）と `ref_file_id`（カスタムリファレンス画像）、 または - `src_file_url` と `ref_file_url`。 両方の画像が指定された要件を満たしていることを確認してください。 - サポートされる形式：JPG/JPEG のみ - ファイルサイズは 10 MB 未満 - 長辺 ≤ 1024 ピクセル - 顔幅 ≥ 128 ピクセル - 頭のポーズが許容範囲内（pitch: −10°〜+10°, yaw: −45°〜+45°, roll: −15°〜+15°） - 単一の顔が見え、髪がはっきり見える正面からの完全なビュー プリセットテンプレートだけでなく、写真リファレンスからも髪型を指定できます。 --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI Hair Style Virtual Try-On V2.0 | プリセットモードで 1 ユニット
カスタムモードで 2 ユニット | | AI Hair Style Virtual Try-On V2.1 | プリセットモードで 2 ユニット
カスタムモードで 2 ユニット | --- - [帽子バーチャル試着](https://docs.perfectcorp.com/ja/reference/ai_hat.md): # 概要 帽子バーチャル試着を作成します。 帽子を着用した状態のプレビューを確認できます。 ## 統合ガイド このガイドでは、以下を説明します。 * **エンドポイント:** `/s2s/v2.0/task/hat` * **認証:** すべてのリクエストで `Authorization: Bearer YOUR_API_KEY` が必要です * **ワークフロー:** 1. **セルフィー画像の準備:** バーチャル試着のターゲットとして、ご自身の画像をアップロードするか、有効な画像 URL を指定します。 1. **帽子画像の準備:** 帽子の商品画像または帽子を着用した人物の写真をアップロードします。 1. **スタイルと性別の選択:** 希望するスタイルと、ビジュアライズしたい性別を選択します。 1. **AI タスクの実行とタスク ID の取得:** レスポンスから `task_id` を取得します。 1. **ステータスのポーリング (`GET`):** `task_id` を使用してタスクのステータスを確認します。`task_status` が `"success"` または `"error"` になるまでポーリングを続けます。 --- * 認証 - **Bearer トークン** を使用して、リクエストヘッダーに API キーを含めます。 ``` Authorization: Bearer YOUR_API_KEY ``` API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/. --- * AI 帽子 API 使用ガイド このガイドでは、画像のアップロード、参照用帽子の準備、および AI 帽子 API を使用したバーチャル試着タスクの作成方法について説明します。 *** * ステップ 1. セルフィー画像の準備 以下のいずれかの方法が可能です。 * File API (`/s2s/v2.0/file`) を使用してセルフィー画像をアップロードする、または * 有効な画像 URL を指定する。 * ステップ 1.1 File API を使用したファイルのアップロード **File API** (`/s2s/v2.0/file`) を使用して、ターゲットユーザーの画像をアップロードします。 **画像要件:** * セルフィー写真をアップロードします。 * 写真に上半身がはっきりと写っていることを確認してください。 * 複数の人物や気が散るオブジェクトがある背景は避けてください。 **リクエスト例:** ```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 } ] }' ``` *** * ステップ 1.2. File API レスポンスの取得 レスポンスには以下が含まれます。 * AI タスク作成用の `file_id`。 * 実際の画像ファイルをアップロードするための `requests.url`。 **レスポンス例:** ```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" } } ] } ] } } ``` *** * ステップ 1.3. 指定された URL への画像アップロード File API レスポンスの `requests.url` を使用して画像をアップロードします。 ```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' ``` *** * ステップ 2. 参照用帽子画像の準備 以下のいずれかの方法が可能です。 * File API (`/s2s/v2.0/file`) を使用して帽子画像をアップロードする、または * 有効な画像 URL を指定する。 **サポートされる帽子画像:** * 帽子の商品画像。 * 帽子を着用した人物の写真。 詳細な仕様については、**[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)** を参照してください。 *** * ステップ 3. AI タスクの作成 希望するスタイルと、ビジュアライズしたい性別を選択します。 **AI タスク API** (`/s2s/v2.0/task/hat`) を使用して、バーチャル試着タスクを作成します。 **パラメータ:** * ユーザー画像用: `src_file_id` または `src_file_url`。 * 帽子画像用: `ref_file_id` または `ref_file_url`。 **リクエスト例:** ```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" }' ``` **レスポンス例:** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` *** * ステップ 4. タスク結果のポーリング タスク ID を使用してステータスを確認します。 ```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' ``` *** * ステップ 5. 結果の取得 成功したレスポンスには、結果画像のダウンロード URL が含まれます。 ```json { "status": 200, "data": { "error": null, "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..." }, "task_status": "success" } } ``` 無効な API キーエラーレスポンス: ```json { "status": 401, "error": "Unauthorized", "error_code": "InvalidAccessToken" } ``` --- ## ファイル仕様とエラー * 帽子バーチャル試着仕様 * 画像要件 | 種類 | 最小解像度 | 備考 | | ------ | ------------------ | ----- | | セルフィー | 512 × 512 | 顔が見えること、頭から胸までが推奨 | | 帽子 | 512 × 512 (商品)
800 × 800 (着用時) | 帽子がはっきりと、遮られずに写っていること | **サポートされる帽子画像** * 商品画像要件 * 最小解像度: 512 × 512 ピクセル * 画像あたり 1 つの商品のみ * 商品は画像の高さの 25% 以上を占める必要があります ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/026_thumb_dca334af3c.jpg) * 着用画像要件 * 最小解像度: 800 × 800 ピクセル * 単一アイテム要件: モデルは正確に 1 つのアイテムのみを着用している必要があります。複数のアイテムやアクセサリーは許可されません。 * カバレッジ比率: 着用したアイテムは画像全体の height の 20% 以上を占める必要があります。これにより、アイテムがフレーム内で明確かつ目立つことが保証されます。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/010_thumb_51490eebeb.jpg) **サポートされるセルフィービュー** * 推奨画像解像度: 少なくとも 512 × 512 ピクセル。 * 推奨顔のカバレッジ: 画像 height の 15% 以上。 * 単一被写体要件: 画像には正確に 1 人の人間の被写体のみが含まれている必要があります。追加の人物や部分的な人物像は許可されません。 * 顔の可視性: 被写体の顔が遮られることなく完全に可視である必要があります。髪、アクセサリー、またはオブジェクトが主要な顔の特徴を覆ってはいけません。 * フレーミング: 画像には少なくとも頭部ショットが含まれており、頭頂部から胸までの領域をカバーする必要があります。最適な分析のためには、半身ショット（頭から腰まで）が推奨されます。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/lashana_lynch_thumb_7a900b811e.jpg) **試着スタイル** * バーチャル試着出力を生成するための 5 つの事前定義されたスタイルがあります: "style_sporty_casual" "style_urban_fashion" "style_vacation_casual" "style_warm_cozy" および "style_bohemian"。AI タスク作成時にこの style パラメータを指定するか、デフォルトでシステムがランダムにスタイルを選択するようにできます。 ![style_vacation_casual](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/5f42385b_6aef_44cd_b576_2ec10e31305d_824cc2019b.jpg) --- * サポートされる形式と寸法 | AI 機能 | サポートされる寸法 | サポートされるファイルサイズ | サポートされる形式 | | ---- | ---- | ---- | ---- | | 帽子バーチャル試着 | 入力: 長辺 <= 4096
出力: 896 x 1152 | < 10MB | jpg/jpeg/png/heic | * エラーコード | エラーコード | 説明 | | ------------------------------ | -------------------------------------------- | | error\_download\_image | ソースまたは参照画像のダウンロードに失敗しました | | error\_inference | 推論パイプラインエラー | | error\_no\_face | ソース画像で顔が検出されませんでした | | error\_nsfw\_content\_detected | 結果に NSFW コンテンツが検出されました | | exceed\_max\_filesize | ファイルサイズが 10 MB を超えています | | invalid\_parameter | 無効な gender または style 値 | | unknown\_internal\_error | その他の内部エラー | * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON 解析) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch のため) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性のため), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings のため), requests >= 2.20.0 | | Java | Java 11+ (HttpClient のため), Jackson Databind >= 2.12.0 | --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | 帽子バーチャル試着 V2.0 | 2 | --- - [AI ビジネス写真](https://docs.perfectcorp.com/ja/reference/ai_headshot_generator.md): # 概要 AI ビジネス写真ジェネレーターで、写真をプロフェッショナルなビジネス写真に変換します。 * 多彩なスタイル: 洗練された LinkedIn 用ビジネス写真からクリエイティブなモデル風ビジネス写真まで、用途に合わせたルックを選べます。 * プロフェッショナルな結果: ビジネス写真が自然に見えるよう補正し、採用担当者やクライアントに良い印象を与えます。 * 利便性: 写真家がいなくても、いつでもどこでも複数の AI ビジネス写真を生成できます。 その他の AI ビジネス写真スタイルについては、https://yce.makeupar.com/ai-headshot-generator. を参照してください。 ユースケース: ![AI ビジネス写真ジェネレーター](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_headshot_s2_img_03_4b55742358.jpg "AI ビジネス写真ジェネレーター") ![AI ビジネス写真ジェネレーター](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_headshot_s1_img_1_d03183d7e0.jpg "AI ビジネス写真ジェネレーター") 撮影方法のヒント: ![撮影方法のヒント](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png "撮影方法のヒント") --- ## ファイル仕様とエラー * 対応フォーマットと寸法 |AI 機能|対応寸法|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | | AI ビジネス写真ジェネレーター | 入力画像に OpenPose で両肩ポイントと顔全体が確認できる人物が 1 人含まれており、短辺が 1024 ピクセル以下であることを確認してください。それ以外の場合、エンジンは自動的に 1024 にリサイズします。出力: 長辺 <= 1024 | < 10MB | jpg/jpeg/png | * エラーコード |エラーコード|説明| | ---- | ---- | | exceed_max_filesize | 入力ファイルサイズが最大制限を超えています | | invalid_parameter | パラメータ値が無効です | | error_download_image | ソース画像のダウンロードに失敗しました | | error_decode_image | ソース画像のデコードに失敗しました | | error_nsfw_content_detected | ソース画像に NSFW コンテンツが検出されました | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI ビジネス写真ジェネレーター V1.0 | 2 枚あたり 1 ユニット * | > *画像数または動画の長さが割り切れない場合、ユニットは切り上げられます。 --- - [AI 画像拡張](https://docs.perfectcorp.com/ja/reference/ai_image_extender.md): # 概要 AI 画像拡張（アウトペインティング）では、あらゆる比率で画像を拡張できます。スタイルや美観を損なうことなく、元の品質を維持します。背景を自動的に拡大でき、拡張された領域は元の写真と自然に馴染むように処理されます。 ![AI 画像拡張](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_outpainting_S1_img_03_cf19a018d9.jpg "AI 画像拡張") Instagram での投稿や、画像の額装表示など、用途に合わせてさまざまなサイズと比率から選択できます。拡張された領域は元の写真と自然に溶け込むように処理されます。 ![AI 画像拡張](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_outpainting_S1_img_01_1876fb85a5.jpg "AI 画像拡張") ## ファイル仕様とエラー * 対応フォーマットと寸法 | AI 機能 | 対応寸法 | 対応ファイルサイズ | 対応フォーマット | | ---- | ---- | ---- | ---- | | AI 画像拡張 | 長辺 <= 4096 | < 10MB | jpg/jpeg | * エラーコード |エラーコード|説明| | ---- | ---- | | exceed_max_filesize | 入力ファイルサイズが最大制限を超えています | | invalid_parameter | パラメータ値が無効です | | error_download_image | ソース画像のダウンロードに失敗しました | | error_decode_image | ソース画像のデコードに失敗しました | | error_nsfw_content_detected | ソース画像に NSFW コンテンツが検出されました | --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | AI 画像拡張 V2.0 | 2 | --- - [AI 画像生成](https://docs.perfectcorp.com/ja/reference/ai_image_generator.md): # 概要 AI 画像生成では、テキストプロンプトから画像を生成します。カートゥーン、油絵、スケッチなどのスタイルを試せます。画像を参照として追加することもできます。 その他のスタイルについては、https://yce.makeupar.com/ai-art-generator. を参照してください。 ユースケース: ![AI 画像生成](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_v3_video_02f161f909.jpg "AI 画像生成") ![AI 画像生成](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_v4_poster_092d2fbb9f.jpg "AI 画像生成") 出力例: ![AI 画像生成](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_topbanner_dt_2_e325681588.jpg "AI 画像生成") ![AI 画像生成](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_topbanner_dt_5_8b4fa13c6a.jpg "AI 画像生成") ## ファイル仕様とエラー * 対応フォーマットと寸法 |AI 機能|対応寸法|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | | V1.0 Text to Image | 出力: 長辺 1024 ピクセル。 | プロンプトは 500 文字以内 | N/A | | V2.0 Text to Image | 出力: 初期解像度は 1664 × 928 で、対応解像度は 1664 × 928 (16:9)、1472 × 1104 (4:3)、1328 × 1328 (1:1)、1104 × 1472 (3:4)、928 × 1664 (9:16) です。 | プロンプトは 800 文字以内 | N/A | | V2.0 Image to Image | 入力: 幅と高さの両方が 384 から 3072 ピクセルの範囲内である必要があります。
出力: 幅と高さのカスタマイズ可能な範囲は 512 から 2,048 ピクセルで、初期設定では入力画像のアスペクト比に基づき、総ピクセル数が約 1,024 × 1,024 となるように維持されます。 | <10MB
プロンプトは 800 文字以内 | JPG、JPEG、PNG、BMP、TIFF、WEBP、GIF。
アニメーション GIF の場合、最初のフレームのみが処理されます。 | * エラーコード | エラーコード | 説明 | | ---------- | ----------- | | exceed_max_filesize | アップロードされたファイルサイズが最大制限を超えています。 | | invalid_parameter | 1 つ以上のパラメータが不足しているか、無効です | | error_download_image | ソース画像のダウンロードに失敗しました。 | | error_decode_image | ソース画像のデコードまたは解析に失敗しました。 | | error_nsfw_content_detected | ソース画像に NSFW（職場不適切）コンテンツが検出されました。 | | error_unsupport_ratio | 入力画像のアスペクト比はサポートされていません。 | | unknown_internal_error | 不明な内部エラーが発生しました。 | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI 画像生成 V1.0 | 2 | | AI 画像生成 V2.0 | 1 | --- - [フルメイク](https://docs.perfectcorp.com/ja/reference/ai_look_vto.md): # 概要 フルメイク API では、事前定義されたメイクアップルックをユーザー写真に適用します。 ## 統合ガイド このガイドでは、以下の手順を解説します。 * **エンドポイント:** `/s2s/v2.0/task/look-vto` * **認証:** すべてのリクエストには `Authorization: Bearer ` が必要です * **ワークフロー:** 1. **セルフィーの準備:** 画像をアップロードするか、有効な画像 URL を指定します 1. **ルックテンプレートのリスト取得:** 利用可能な AI ルックテンプレートを一覧表示します 1. **タスクの開始 (`POST`):** 画像 ID/URL とルック ``template_id`` を送信します。 1. **タスク ID の取得:** レスポンスから `task_id` を取得します。 1. **ステータスのポーリング (`GET`):** `task_id` を使用してタスクのステータスを確認します。`task_status` が `"success"` または `"error"` になるまでポーリングを継続します。 --- * API プレイグラウンド API プレイグラウンドで API を対話的にテストします。 **API プレイグラウンド:** [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/) --- * 認証 - リクエストヘッダーに **Bearer トークン** を使用して API キーを含めます: ``` Authorization: Bearer ``` API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/. * 1. 画像のアップロード サーバーにファイルを直接アップロードするか、VTO タスクペイロードに有効な画像 URL を指定します。 * アップロードエンドポイント ``` POST /s2s/v2.0/file ``` すでに公開されている画像 URL がある場合は、この手順をスキップできます。 --- * 2. 利用可能なルックスタイルのリスト取得 バーチャル試着に利用可能なすべての AI メイクアップルックテンプレートを取得します。 * エンドポイント ``` GET /s2s/v2.0/task/template/look-vto ``` * クエリパラメータ | パラメータ | 説明 | | ---------------- | ------------------------------- | | `page_size` | ページあたりの項目数 | | `starting_token` | ページネーション用トークン（省略可） | * JavaScript リクエスト例 ```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); ``` * 成功時のレスポンス例 ```json { "status": 200, "data": { "templates": [ { "id": "good_template_001", "thumb": "thumbnail preview image URL", "title": "Berry Smooth", "category_name": "Daily" } ], "next_token": 73a3c9e69b89 } } ``` > **備考:** Look VTO タスクを作成する際は、`id` 値（`template_id`）を使用してください。 --- * 3. Look VTO タスクの作成と結果のポーリング 画像とテンプレート ID が用意できたら、タスクを作成します。API はリクエストを非同期で処理します。ステータスが `success` または `error` になるまで、タスクステータスをポーリングする必要があります。 * タスク作成エンドポイント ``` POST /s2s/v2.0/task/look-vto ``` * ポーリングエンドポイント ``` GET /s2s/v2.0/task/look-vto/{task_id} ``` --- * JavaScript 実装例 ```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); } })(); ``` --- * 成功時のレスポンス例 ```json { "status": 200, "data": { "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/.../result.jpg?..." }, "task_status": "success" } } ``` `results.url` フィールドには、最終的にレンダリングされたバーチャルメイク画像が含まれます。 --- * まとめ | ステップ | 説明 | | -------------------------- | ---------------------------------------- | | **1. 画像のアップロード** | 直接アップロードするか、画像 URL を指定します。 | | **2. ルックテンプレートのリスト取得** | ID 付きで利用可能なルックスタイルを取得します。 | | **3. VTO タスクの作成** | 画像 URL + テンプレート ID を送信します。 | | **4. 完了のポーリング** | 最終的な結果画像 URL を取得します。 | --- ## ファイル仕様とエラー * 対応フォーマットと寸法 |AI 機能|対応寸法|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | |フルメイク|長辺 < 1920、顔幅 >= 100|< 10MB|jpg/jpeg/png| * エラーコード |エラーコード|説明| | ---- | ---- | |error_below_min_image_size|ソース画像のサイズが最小値より小さいです（期待値: 幅 >= 100px、高さ >= 100px） |error_exceed_max_image_size|ソース画像のサイズが最大値より大きいです（期待値: 幅 < 1920px、高さ < 1080px） |error_face_position_invalid |画像内で顔全体が完全に確認できることを確認してください| |error_face_position_too_small|検出された顔が小さすぎます。カメラに近づいてください| |error_face_position_out_of_boundary|顔が大きすぎるか、画像フレームの一部が外れています。位置を調整してください| |error_face_angle_invalid|顔の角度が正しくありません。正面を向いた写真の場合は、頭を 10° 以内に保ってください。横を向いた写真の場合は、15° 以上にしてください。| * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON 解析) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性用), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-string 用), requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用), Jackson Databind >= 2.12.0 | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | フルメイク V1.0 | 2 | --- - [メイクトランスファー](https://docs.perfectcorp.com/ja/reference/ai_makeup_transfer.md): # 概要 AI メイクトランスファーでは、アップロードした写真でさまざまなルックを試せます。 まず、顔とその特徴がはっきりと見えるご自身の写真をターゲット画像としてアップロードします。 次に、試したいメイクアップルックの写真を参照画像としてアップロードします。 AI メイクトランスファー後の写真が生成されます。 サンプル: ![](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) --- ## ファイル仕様とエラー * 対応フォーマットとサイズ |AI 機能|対応サイズ|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | |AI メイクトランスファー|1024x1024 (長辺 <= 1024)、顔は 1 名のみ、顔全体が写っている必要あり|< 10MB|jpg/jpeg/png| * エラーコード |エラーコード|説明| | ---- | ---- | |error_src_no_face |ユーザー画像で顔が検出されませんでした |error_ref_no_face |参照画像で顔が検出されませんでした |error_src_face_too_small |ユーザー画像内の顔が小さすぎます |error_ref_face_too_small |参照画像内の顔が小さすぎます |error_src_large_face_angle |ユーザー画像では正面を向いた顔が必要です |error_ref_large_face_angle |参照画像では正面を向いた顔が必要です |error_src_eye_closed |ユーザー画像で目が閉じています |error_ref_eye_closed |参照画像で目が閉じています |error_src_eye_occluded |ユーザー画像で目が隠れています |error_ref_eye_occluded |参照画像で目が隠れています |error_src_lip_occluded |ユーザー画像で唇が隠れています |error_ref_lip_occluded |参照画像で唇が隠れています |error_inappropriate_ref_case01 |参照画像の両目で、髪が目にかかりすぎているか、目尻横の肌領域が十分に広くありません |error_inappropriate_ref_case02 |参照画像の片目で、髪が目にかかりすぎているか、目尻横の肌領域が十分に広くありません。もう片方の目が十分に正面を向いていません --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI メイクトランスファー V1.0 | 2 | --- - [ネイル再現](https://docs.perfectcorp.com/ja/reference/ai_nail_transfer.md): # 概要 ネイル再現 API では、参照写真のネイルデザインを手の写真に転送します。 ジェルネイル、ネイルアート、ポリッシュ仕上げ、ラメ、シェルアクセント、メタリックテクスチャーなどのネイルスタイルをプレビューとして再現します。 美容ブランド、サロン、ネイルアーティストで使えます。 ![](https://plugins-media.makeupar.com/smb/blog/post/2022-11-24/8821ab6e-9852-4401-89df-dd6005fb81fc.jpg) ## 統合ガイド このガイドでは、以下を説明します。 ネイル再現 API のワークフロー： **エンドポイント:** `/s2s/v2.0/task/ai-nail` **認証必須:** `Authorization: Bearer YOUR_API_KEY` **ワークフロー手順:** 1. **画像アップロード準備:** - プロセスは、File API を使用して `/s2s/v2.0/file` に手の画像を準備することから始まります。 2. **参照写真のアップロード:** - 希望するネイルデザインが写った参照写真を、File API を使用して `/s2s/v2.0/file` にアップロードします。すべての爪が明確に見えるようにしてください。 1. **AI タスクの開始とタスク ID の取得:** - アップロードした画像を HTTP POST リクエストで `/s2s/v2.0/task/ai-nail` に送信します。 - このインタラクションを識別する一意の `task_id` をレスポンスで待ちます。 1. **タスクステータスのポーリング（継続的な確認）:** - 取得した `task_id` を使用して、HTTP GET リクエスト（例：`GET /task/${task_id}`）でタスクステータスを定期的にポーリングします。 - 以下を継続的に監視します： - `Task_status = "success"`（処理完了）。 - `Task_status = "error"`（該当する場合、解決または再試行）。 - ステータスが success に遷移したら、ワークフローを適切に更新します。 このワークフローにより、タスクの監視と結果の取得を行います。 --- * 認証 - リクエストヘッダーに **Bearer Token** を使用して API キーを含めます： ``` Authorization: Bearer YOUR_API_KEY ``` API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/. * 1. 画像のアップロード ファイルをサーバーに直接アップロードするか、AI タスクペイロードに有効な画像 URL を指定します。 * アップロードエンドポイント ``` POST /s2s/v2.0/file ``` または、公開画像 URL が既に存在する場合は、この手順をスキップします。 --- * 2. 参照写真のアップロード ファイルをサーバーに直接アップロードするか、AI タスクペイロードに有効な画像 URL を指定します。すべての爪が見えるようにしてください。 * アップロードエンドポイント ``` POST /s2s/v2.0/file ``` --- * 3. ネイル再現 AI タスクの作成と結果のポーリング 画像と完全なエフェクトペイロードが用意できたら、タスクを作成します。API はリクエストを非同期で処理します。ステータスが `success` または `error` になるまで、タスクステータスをポーリングします。 * タスク作成エンドポイント ``` POST /s2s/v2.0/task/ai-nail ``` * ポーリングエンドポイント ``` GET /s2s/v2.0/task/ai-nail/{task_id} ``` --- ## ファイル仕様とエラー * ネイル再現 仕様 **対応する手のビュー** 画像あたり最大 2 本の手に対応します。追加の手は無視されます。検出のため、各手が画像面積の少なくとも 0.5% を占める必要があります（FHD で約 102×102 px、2K で 139×139 px、4K 画像で 204×204 px）。 ![](https://plugins-media.makeupar.com/strapi/assets/small_webp_bare_nails_014_f6451b0343.png) **対応する参照画像** ![](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) --- * 対応フォーマットと寸法 |AI 機能|対応寸法|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | | ネイル再現 | 長辺 <= 4096 | < 10MB | jpg/jpeg/png | * エラーコード | エラーコード | 説明 | | ---- | ---- | | exceed_max_filesize | 画像ファイルが大きすぎます | | invalid_parameter | 入力パラメータが不足しているか、形式が正しくありません | | error_download_image | ファイルアップロードが完了していないか、画像 URL が無効です | | error_inference | 推論に失敗しました。入力画像と参照画像がサポートされているか確認してください | | no_hand_detected | ソース画像で手が検出されませんでした | * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON 解析) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性用), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings 用), requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用), Jackson Databind >= 2.12.0 | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | ネイル再現 V1.0 | 1 | --- - [ネイルバーチャル試着](https://docs.perfectcorp.com/ja/reference/ai_nail_vto.md): # 概要 ネイルバーチャル試着 (AI Nail Virtual Try-On) API で、ネイルのバーチャル試着を作成します。 天然爪にも人工爪にも、さまざまなネイルスタイルをビジュアライズできます。 ## 統合ガイド このガイドでは、次の内容について説明します: ネイルバーチャル試着 API のワークフロー: **認証が必要:** `Authorization: Bearer YOUR_API_KEY` **ワークフロー手順:** 1. **画像アップロードの準備:** - 手の甲の画像を用意することから始めます。 - ファイル管理 API の `/s2s/v2.0/file` を呼び出し、アップロード URL と関連する `file_id` を取得します。 - 提供されたアップロード URL を使用して、ネイルのある手の甲の画像をアップロードします。 2. **ネイルデザインのセットアップオプション:** - まず、適したネイルカラーを選択します。お好みに合わせたカスタムシェイプも選択できます。 3. **AI タスクの開始とタスク ID の取得:** - アップロードした画像と選択したエフェクト設定を、HTTP POST リクエストで `/s2s/v2.0/task/nail-vto` に送信します。 - この操作を識別する一意のタスク ID をレスポンスで受け取ります。 4. **タスクステータスのポーリング（継続的なチェック）:** - 取得した `task_id` を使用して、HTTP GET リクエスト（例: `GET /s2s/v2.0/task/nail-vto/${task_id}`）で定期的にタスクステータスをポーリングします。 - 以下を継続的に監視します: - `Task_status = "success"`（処理が完了）。 - `Task_status = "error"`（該当する場合、解決するか再試行）。 - ステータスが success に移行したら、ワークフローを適切に更新します。 --- * API プレイグラウンド API プレイグラウンドで API を対話的にテストします: **API プレイグラウンド:** [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/) --- * 認証 - **Bearer Token** を使用して、リクエストヘッダーに API キーを含めます: ``` Authorization: Bearer YOUR_API_KEY ``` API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/. 1. 画像のアップロード ファイルをサーバーに直接アップロードするか、VTO タスクペイロードに有効な画像 URL を指定できます。 * アップロードエンドポイント ``` POST /s2s/v2.0/file ``` すでに公開済みの画像 URL を持っている場合は、このステップをスキップできます。 --- 2. エフェクトテンプレートの準備 * この目的のために、4 つの異なるセットアップモードが用意されています: 1. カラーをカスタマイズし、現在のネイルルックに合わせる 2. プリセットデザインと特定のシェイプを使用して、イメージを実現する 3. プレスオンネイルを追加し、既存の元のネイル画像とリンクする 4. 一致するプレッスオンネイル製品の画像リンクを提供する * エフェクトテンプレートの JSON スキーマ ``` { "version": "1.0", "effect_type": "nail_polish", // valid values: ['nail_polish', 'press_on_nails'] "effects": [], "ref_file_ids": [] } ``` * エフェクト形式 - ネイルポリッシュ - カラー ``` { "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 } ``` - ネイルポリッシュ - デザイン ``` { "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 } ``` - プレスオンネイル - カラー * 最新のシェイプ値は、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 } ``` - プレスオンネイル - デザイン ``` { "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 } ``` * エフェクトテンプレートのデザインロジック 1. **エフェクトタイプの検出**（`press_on_nails` または `nail_polish`）。 2. **`effects` の各エントリを繰り返し:** *`sub_type === "color"` の場合* → フィールドを直接マッピングし、欠落しているテクスチャ関連のキーをデフォルト値で埋めます。 *`sub_type === "design"` の場合* → - ユーザーが `ref_file_url` を指定した場合は、それを保持し、`ref_file_index` を **省略**します。 - ユーザーがインデックス (`ref_file_index`) を指定した場合は、`ref_file_ids` が存在し、インデックスが有効であることを確認してから、`"ref_file_id": ref_file_ids[index]` を設定します（省略可 – 一部のバックエンドでは id ではなく生のインデックスを期待します）。 1. **数値範囲の正規化** – 範囲外の値を 0-100 または長さの制限にクランプします。 2. スキーマバリデーションを通過できるように、**欠落している任意のキー**をデフォルト値で追加します。 3. 最終オブジェクトを JSON として **シリアライズ** します（デバッグ用に compact または pretty）。 * 送信準備ができたペイロード例 ``` { "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. ネイル VTO タスクの作成と結果のポーリング 画像と完全なエフェクトペイロードが揃ったら、タスクを作成します。API はリクエストを非同期で処理します。`success` または `error` になるまで、タスクステータスをポーリングする必要があります。 * タスク作成エンドポイント ``` POST /s2s/v2.0/task/nail-vto ``` * ポーリングエンドポイント ``` GET /s2s/v2.0/task/nail-vto/{task_id} ``` --- ## ファイル仕様とエラー * ネイルバーチャル試着の仕様 **対応ネイルビュー** 遮蔽物のない、明確な正面ビューの 1 枚のネイル画像。 | 項目 | 対応寸法 | 対応ファイルサイズ | 対応フォーマット | | --- | --- | --- | --- | | ネイルデザイン画像 - ネイルポリッシュ | * 271 px ≤ 幅 ≤ 542 px
* 522 px ≤ 高さ ≤ 1044 px
* 72ppi 以上
画像は中央から適用され、バーチャル試着効果はユーザーの爪の長さに応じて変わります。 | ≤ 1MB | png | | ネイルデザイン画像 - プレスオンネイル | * 271 px ≤ 幅 ≤ 542 px
* 522 px ≤ 高さ ≤ 1044 px
* 0.5 ≤ 画像のアスペクト比 (H/W) ≤ 3.5
* 72ppi 以上
画像のコンテンツ、シェイプ、長さの設定はすべて、バーチャル試着効果の生成に使用されます。
適切な画像スケーリングを確保するためにユーザーの爪の幅が検出されるため、正しいアスペクト比で各爪用に別の画像を作成することをお勧めします。
プレッスオンネイルのデザイン画像サンプルをダウンロードし、詳細については画像ガイドラインを参照してください。ダウンロード: [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 | プレッスオンネイルデザイン画像サンプル: ![](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) --- **対応ハンドビュー** | 項目 | 対応寸法 | 対応ファイルサイズ | 対応フォーマット | | --- | --- | --- | --- | | ユーザー写真 | * 長辺 ≤ 2048
* 短辺 ≥ 256 | ≤ 10MB | jpg/jpeg/png | * 入力画像は 1 つの手のみをサポートします * 手のひらの面積は、入力画像の面積の少なくとも半分であることが望ましいです * 入力画像のアスペクト比は 1:1、3:4、4:3 が望ましいです * 指の爪は隠れていないこと * 爪にネイルチップやネイルポリッシュがないことが望ましいです ![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_nail_user_photo_02_fdba1848d6.jpg) --- * エラーコード | エラーコード | 説明 | | ---- | ---- | | error_nail_too_small | ネイル領域が小さすぎます。 | | error_no_nail | ソース画像にネイルが検出されませんでした。 | * 環境と依存関係 | サンプルコードの言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58（最新の TLS/HTTP 対応）
- jq >= 1.6（堅牢な JSON 解析） | | Node.js (JavaScript) | Node >= 18（グローバル fetch 用） | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4（最新の TLS/互換対応用）, ext-curl（推奨）または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10（f-strings 用）, requests >= 2.20.0 | | Java | Java 11+（HttpClient 用）, Jackson Databind >= 2.12.0 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | ネイルバーチャル試着 V1.0 | 1 | --- - [AI ネックレスバーチャル試着](https://docs.perfectcorp.com/ja/reference/ai_necklace.md): # 概要 ネックレスのバーチャル試着を作成します。 AI の首元と鎖骨トラッキングにより、ネックレスの試着プレビューを生成します。 2D 画像からネックレスのバーチャル試着を作成します。3D モデリングは不要です。 ## 統合ガイド 本ガイドでは以下内容を説明します: * **エンドポイント:** `/s2s/v2.0/task/2d-vto/necklace` * **認証:** すべてのリクエストに `Authorization: Bearer YOUR_API_KEY` が必要です * **ワークフロー:** 1. **セルフィー画像を準備する:** 画像をアップロードするか、有効な画像 URL を提供します 2. **ネックレス画像を準備する:** 画像をアップロードするか、ネックレス製品の有効な画像 URL を提供します 3. **AI タスクを発行しタスク ID を取得する:** レスポンスから `task_id` を取得します。 4. **ステータスをポーリングする（`GET`）:** `task_id` を使用してタスクのステータスを確認します。`task_status` が `"success"` または `"error"` になるまでポーリングを続行してください。 --- * API プレイグラウンド API プレイグラウンドで API を対話的にテストします: **API プレイグラウンド:** [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/) --- * 認証 - リクエストヘッダーに **Bearer Token** を使用して API キーを含めます: ``` Authorization: Bearer YOUR_API_KEY ``` API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/. * 1. 画像のアップロード ファイルをサーバーに直接アップロードするか、VTO タスクペイロードに有効な画像 URL を提供できます。 * アップロードエンドポイント ``` POST /s2s/v2.0/file ``` すでにパブリックな画像 URL を持っている場合は、このステップをスキップできます。 File API のレスポンスで提供された URL にファイルを直接アップロードし、その後 File API が返した対応する `src_file_id` を使用して AI タスクを呼び出すことができます。または VTO タスクペイロードに有効な画像 URL を `src_file_url` として提供します。`src_file_id` または `src_file_url` がバーチャル試着の対象となります。 また、`src_file_id` または `src_file_url` に適用するネックレス製品画像を参照として `ref_file_ids` または `ref_file_urls` で提供する必要があります。 AI エンジンでは、セルフィーの自動背景透過に対応しています。ただし、首（`srcmsk_file_id` または `srcmsk_file_url`）のオクルージョンマスク画像ファイルを提供してセグメンテーションを微調整できます。 --- * 2. ネックレス VTO タスクの作成と結果のポーリング 画像とテンプレート ID が揃ったら、タスクを作成します。API はリクエストを非同期で処理します。ステータスが `success` または `error` に達するまでタスクステータスをポーリングする必要があります。 * タスク作成エンドポイント ``` POST /s2s/v2.0/task/2d-vto/necklace ``` * ポーリングエンドポイント ``` GET /s2s/v2.0/task/2d-vto/necklace/{task_id} ``` --- ## ファイル仕様とエラー * ネックレスバーチャル試着の仕様 **サポートされるネックレスビュー** 背景を除去した、ネックレスを着用した前面画像。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/necklace_product_01_124206cfbe_3993a2128d.jpg) **サポートされるセルフィービュー** 首が明確に見えており、遮蔽のない前面のセルフィー。頭の水平回転は 20 度以内でサポートされます。頭のサイズは比例したものであり、首の幅は画像幅の少なくとも 15 パーセントを占める必要があります。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Necklace_restriction_83410fb6c1.png) **necklace\_wearing\_location: array of two points (optional)** ネックレスを配置すべき写真内のターゲット位置を指定します。 デフォルト: null（エンジンのデフォルト） ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/wearing_location_874264bb70.jpg) **necklace\_shadow\_intensity: float (0.0 to 1.0)** 影の強さを制御します: 0.0 は影なしを示します 1.0 は最大限の影を示します デフォルト値: 0.15 **necklace\_ambient\_light\_intensity: float (0.0 to 1.0)** ライティングがセルフィー画像を参照する度合いを定義します: 0.0 はセルフィー画像のライティングを無視します 1.0 はセルフィー画像のライティングと影のレンダリングに完全に一致させます デフォルト値: 1.0 **ネックレスアンカーポイント: ピクセル座標の 2 点の配列（任意）** 製品画像内のネックレスチェーンの左右に見える端部のアンカーポイントを指定し、アラインメントに使用します。 デフォルト: null（エンジンのデフォルト） ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/anchor_point_7f9b254ca4.jpg) --- * サポートされる形式と寸法 |AI 機能|サポートされる寸法|サポートされるファイルサイズ|サポートされる形式| | ---- | ---- | ---- | ---- | |ネックレスバーチャル試着|長辺 <= 4096 |< 10MB|jpg/jpeg/png| * エラーコード |エラーコード|説明| | ---- | ---- | | RUNTIME_ERROR | ネックレスランタイムで予期しないエラーが発生しました | | PHOTO_DETECTION_FAIL | ユーザー写真が正しく処理できませんでした（例: 首が検出されなかった） | | OBJECT_DETECTION_FAIL | オブジェクト写真が正しく処理できませんでした（例: 製品が検出されなかった） | | PHOTO_CHECK_INVALID | ユーザー写真のポーズまたはサイズが無効です | | INPUT_ERROR | 入力ファイルの形式が正しくありません | | INPUT_MAIN_IMAGE_EMPTY | ユーザー画像が必要です | * 環境と依存関係 | サンプルコードの言語/ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58（モダンな TLS/HTTP サポート）
- jq >= 1.6（堅牢な JSON パーシング） | | Node.js (JavaScript) | Node >= 18（グローバル fetch のため） | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4（モダンな TLS/互換性のため）、ext-curl（推奨）または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10（f-strings のため）、requests >= 2.20.0 | | Java | Java 11+（HttpClient のため）、Jackson Databind >= 2.12.0 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | ネックレスバーチャル試着 V1.0 | シングルアイテム着用で 1 ユニット | --- - [AI 除去](https://docs.perfectcorp.com/ja/reference/ai_object_removal_pro.md): # 概要 高度な AI 除去 Pro 技術により、写真編集を一段レベル上げます。 人物や反射、影などの不要な要素を除去しつつ、細部まではっきりと保ちます。 写真とシンプルなグレースケールマスクをアップロードするだけで、すっきりとした自然な仕上がりを実現できます。 使用例: ![](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) --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI 除去 | 標準：1 ユニット
プロフェッショナル：2 ユニット | --- - [背景ぼかし](https://docs.perfectcorp.com/ja/reference/ai_photo_background_blur.md): # 概要 背景ぼかし API では、写真の背景をぼかします。 背景ぼかし API で、被写体を自動的に切り出し、背景をぼかします。 **主な利用シーン:** * ポートレート強化 ボケ効果を適用して被写体を際立たせます。 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) * プロフェッショナルな証明写真 標準的な写真からスタジオ風の背景ぼかし効果を作成します。 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) --- ## 統合ガイド **入力要件と処理基準:** - 明確で目立つ前景の被写体を含む画像をアップロードします。 - 画像の長辺は **4,096 px** を超えてはいけません。 - ソースファイルサイズは **10 MB** 未満である必要があります。 - 少なくとも 1 つの明確に視認できる前景の被写体が必要です。 - 単一被写体の分析のみサポートされています。複数の人物が存在する場合、API は可視面積が最大の被写体を自動的に選択します。 **ワークフロー:** 1. File API を呼び出します。 2. レスポンスから署名付きアップロード URL を取得します。 3. 返された URL に実際の画像をアップロードします。 4. AI タスクを作成します。 5. Webhook を設定するか、完了するまでタスクステータスをポーリングします。 6. 処理が成功したら、生成された結果画像をダウンロードします。 --- **ステップ 1 — File API を使用してファイルメタデータをアップロードする** `POST /s2s/v2.0/file` を使用してファイルレコードを作成し、ソース画像のアップロード詳細を取得します。 ```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 レスポンス例:** ```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" } } ] } ] } } ``` --- **ステップ 2 — File API レスポンスの詳細を取得する** レスポンスには以下が含まれます: | フィールド | 説明 | | --- | --- | | `file_id` | AI タスクの作成に使用される識別子。 | | `requests.url` | 実際の画像ファイルをアップロードするための署名付き URL。 | | `requests.method` | アップロードメソッド。通常は `PUT`。 | | `requests.headers` | アップロードリクエストに必要なヘッダー。 | --- **ステップ 3 — 提供された URL に画像をアップロードする** File API レスポンスの `requests.url` を使用して、ソース画像をアップロードします。 ```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' ``` --- **ステップ 4 — AI タスクを作成する** `POST /s2s/v2.0/task/bg-blur` を使用して AI タスクを作成します。 | パラメータ | 説明 | 例 | | --- | --- | --- | | `src_file_id` | File API アップロードフローから返されるファイル ID。アップロードファイルワークフローを使用する場合に必須。 | `"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud"` | | `src_file_url` | ソース画像の直接 URL。`src_file_id` の代替として使用します。 | `"https://example.com/selfie.jpg"` | | `intensity` | ぼかしの強度。0 はぼかしなし、100 は最大ぼかしを意味します。 | 50 | **リクエスト例:** ```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 タスク API レスポンス:** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` --- **ステップ 5 — Webhook の設定またはタスク結果のポーリング** 設定および検証の詳細については、[Webhook 統合ガイド](../develop/webhook.md) を参照してください。 ポーリングの場合は、返された `task_id` を使用してタスクステータスを確認します。 ```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' ``` --- **ステップ 6 — 結果画像を取得する** 処理が成功すると、レスポンスの `data.results.url` にダウンロード URL が含まれます。 ```json { "status": 200, "data": { "error": null, "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..." }, "task_status": "success" } } ``` **無効な API キーのレスポンス:** アクセストークンが無効な場合、API は `401` レスポンスを返します。 ```json { "status": 401, "error": "Unauthorized", "error_code": "InvalidAccessToken" } ``` --- ## ファイル仕様とエラー **ファイル仕様:** | 仕様 | 要件 | | --- | --- | | 画像タイプ | 画像には、1 つの明確で目立つ前景の被写体または人物が含まれている必要があります。 | | 長辺の最大解像度 | 長辺は **4096 px** を超えてはいけません。 | | ファイルサイズ制限 | **10 MB** 未満である必要があります。 | | サポート形式 | `jpg`, `png`。 | **エラーコード:** | エラーコード | 説明 | | --- | --- | | `exceed_max_filesize` | ソース画像が許容される最大寸法またはファイルサイズを超えています。長辺は 4096 px を超えてはならず、ファイルサイズは 10 MB 未満である必要があります。 | | `error_nsfw_content_detected` | ソース画像または生成された結果画像に潜在的な NSFW コンテンツが検出されました。 | | `invalid_parameter` | ソースキー、宛先キー、アクション、モード値、強度レベル、またはタスク設定に対して無効なパラメータが提供されました。 | | `error_download_image` | ソース画像を正常にダウンロードできませんでした。 | | `error_decode_image` | ソース画像を正常にデコードできませんでした。 | **環境と依存関係:** | ツール / 言語 | 推奨ランタイムバージョン | | --- | --- | | cURL | Bash ≥ 3.2; curl ≥ 7.58 (モダンな TLS/HTTP サポート付き); jq ≥ 1.6 (堅牢な JSON 解析用)。 | | Node.js | グローバル `fetch` サポートのため Node ≥ 18。 | | JavaScript ブラウザサポート | Chrome / Edge ≥ 80, Firefox ≥ 74, Safari ≥ 13.1。 | | PHP | モダンな TLS 互換性のため PHP ≥ 7.4; ext-curl を推奨、または OpenSSL および JSON サポート付きで `allow_url_fopen=On`。 | | Python | f-strings のため Python ≥ 3.10; requests ≥ 2.20.0。 | | Java | HttpClient のため Java 11+; Jackson Databind ≥ 2.12.0。 | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | 背景ぼかし V2.0 | 1 | --- - [AI 背景変更](https://docs.perfectcorp.com/ja/reference/ai_photo_background_change.md): # 概要 AI 背景変更 API で、画像から被写体を切り出して背景を分離します。 カスタムプロンプトまたは事前定義されたテンプレートで背景を置き換えます。 **使用例** 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) --- ## 統合ガイド **1. 画像のアップロード** 以下のエンドポイントを通じて、アップロード URL とファイル ID をリクエストします。 ``` POST /s2s/v2.0/file ``` 返された URL を使用して画像をアップロードします。 または、独自のストレージにホストされた公開アクセス可能な画像 URL を指定することもできます。 **2. 背景説明プロンプトの準備または背景テンプレートの選択** ``` GET /s2s/v2.0/task/template/bg-replace ``` 事前定義された背景テンプレートのリストを取得し、template_id で 1 つを選択します。プロンプトを使用する場合、プロンプトに基づいて背景が生成されます。テンプレートを使用する場合、template_id で指定されたテンプレートから背景が生成され、prompt パラメータは無視されます。 **3. 分析タスクの実行** ``` POST /s2s/v2.0/task/bg-replace ``` ファイル ID または画像 URL と、希望する背景プロンプトを指定してタスクを送信します。 レスポンスには、結果の追跡と取得に使用される task_id が返されます。 **4. タスク結果の取得** ``` GET /s2s/v2.0/task/bg-replace/{task_id} ``` タスク ID を使用してステータスを追跡し、結果を取得します。 [Webhook](../develop/webhook.md) を設定すると、タスク完了時に成功またはエラーのステータスで非同期通知を受信できます。タスクエンドポイントを繰り返し呼び出して、ステータスが running から success または error に更新されるまでポーリングすることもできます。 課金は、タスクが正常に完了した場合にのみ発生します。 --- ## ファイル仕様とエラー * 対応フォーマットと寸法 |AI 機能|対応寸法|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | | AI 背景変更 | 長い辺の長さは 4096 ピクセル以下である必要があります。 | < 10MB | jpg/jpeg/png | * エラーコード |エラーコード|説明| | ---- | ---- | | exceed_max_filesize | 入力ファイルサイズが最大制限を超えています。 | | size_mismatch_on_input_image_and_mask | 入力画像のサイズは、入力マスク画像の寸法と一致する必要があります。 | | invalid_parameter | パラメータ値が無効です。リクエストパラメータが不足しているか、無効な形式であるか、サポートされていない値が含まれています。| * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON 解析) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性用), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings 用), requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用), Jackson Databind >= 2.12.0 | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI 背景変更 V2.0 | 4 | --- - [カラー化](https://docs.perfectcorp.com/ja/reference/ai_photo_colorize.md): # 概要 最新の AI 技術で、白黒写真や古い画像をカラー化・修復します。カラー化（AI Photo Colorize）は、暖色系から寒色系までの 4 種類のカラーバージョンを生成します。ディープラーニングで白黒写真を数秒でカラー画像に変換します。 ![カラー化（AI Photo Colorize）](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_colorize_s4_poster_11c0bdfead.jpg "AI Photo Colorize") --- ## ファイル仕様とエラー * 対応フォーマットと寸法 | AI 機能 | 対応寸法 | 対応ファイルサイズ | 対応フォーマット | | ---- | ---- | ---- | ---- | | カラー化 | 長辺 <= 4096 | < 10MB | jpg/jpeg/png | * エラーコード |エラーコード|説明| | ---- | ---- | | exceed_max_filesize | 入力ファイルサイズが最大制限を超えています | | invalid_parameter | パラメータ値が無効です | | error_download_image | ソース画像のダウンロードに失敗しました | | error_decode_image | ソース画像のデコードに失敗しました | | error_nsfw_content_detected | ソース画像に NSFW コンテンツが検出されました | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | カラー化 V1.0 | 2 | --- - [高画質化](https://docs.perfectcorp.com/ja/reference/ai_photo_enhance.md): # 概要 AI 高画質化は、高度な AI とディープラーニング技術で画像の詳細を分析し、解像度を向上させます。低解像度の画像を鮮明にし、モーションブラーを修正します。 * ピクセル化の解消: ピクセル化を除去し、より滑らかで輪郭がはっきりした画像にします。 * ぼやけた写真の修正: ぼやけを除去し、よりシャープでくっきりとしたディテールを際立たせます。 * 品質の向上: より細かなディテールを引き出し、画像のあらゆる部分を際立たせます。 * 画像のシャープ化: シャープネスを高め、より鮮明で鮮やかな画像にします。 * 明瞭度の改善: 全体的な明瞭度を向上させ、写真を新鮮でプロフェッショナルな仕上がりにします。 * 顔の補正: 動的な画像において、顔の特徴を洗練させ、よりリアルで補正されたポートレートを作成します。 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) --- ## ファイル仕様とエラー * 対応フォーマットと寸法 | AI 機能 | 対応寸法 | 対応ファイルサイズ | 対応フォーマット | | ---- | ---- | ---- | ---- | | AI 高画質化 | 長辺 <= 4096 | < 10MB | jpg/jpeg/png | * エラーコード |エラーコード|説明| | ---- | ---- | | exceed_max_filesize | 入力ファイルサイズが最大制限を超えています | | invalid_parameter | パラメータ値が無効です | | error_download_image | ソース画像のダウンロードに失敗しました | | error_decode_image | ソース画像のデコードに失敗しました | | error_nsfw_content_detected | ソース画像に NSFW コンテンツが検出されました | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI 高画質化 V1.0 | 2 | --- - [AI 照明](https://docs.perfectcorp.com/ja/reference/ai_photo_lighting.md): # 概要 AI 画像明るさ調整ツールで、画像を明るくできます。 AI 照明で暗い写真や画像を明るくできます。 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) AI ツールで低照度の写真を簡単に明るくし、ディテールと鮮やかな色を引き出します。 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) AI 照明で商品写真を明るくし、魅力的なプレゼンテーションを実現します。 --- ## ファイル仕様とエラー * 対応フォーマットと寸法 | AI 機能 | 対応寸法 | 対応ファイルサイズ | 対応フォーマット | | ---- | ---- | ---- | ---- | | AI 照明 | 長辺 <= 4096 | < 10MB | jpg/jpeg/png | * エラーコード |エラーコード|説明| | ---- | ---- | | exceed_max_filesize | 入力ファイルサイズが最大制限を超えています | | invalid_parameter | パラメータ値が無効です | | error_download_image | ソース画像のダウンロードに失敗しました | | error_decode_image | ソース画像のデコードに失敗しました | | error_nsfw_content_detected | ソース画像に NSFW コンテンツが検出されました | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI 照明 V2.0 | 2 | --- - [AI 置き換え](https://docs.perfectcorp.com/ja/reference/ai_replace.md): # 概要 AI 置き換えで、写真の不要な要素を新しいオブジェクトに置き換えます。テキストの指示だけで、不要なオブジェクトを削除して新しいオブジェクトに置き換えられます。バッグや車などのオブジェクトを除去できます。 サンプル: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_replace_S3_feature_img_02_a73a26bcc3.jpg) SNS に投稿する旅行写真やプロモーション画像の仕上げに、AI 置き換えが使えます。要素を削除・置き換えて、コンテンツの内容を強調できます。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_replace_S3_feature_img_03_42c9cd98d0.jpg) AI 置き換えで、空いているスペースに家具やオブジェクトを配置して、ルームモックアップを作成できます。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_replace_S3_feature_img_04_4d2d82f76e.jpg) --- ## ファイル仕様とエラー * 対応フォーマットと寸法 | AI 機能 | 対応寸法 | 対応ファイルサイズ | 対応フォーマット | | ---- | ---- | ---- | ---- | | AI 置き換え | 長辺 <= 2048 | < 10MB | jpg/jpeg/png | * エラーコード |エラーコード|説明| | ---- | ---- | | exceed_max_filesize | 入力ファイルサイズが最大制限を超えています | | invalid_parameter | パラメータ値が無効です | | error_download_image | ソース画像のダウンロードに失敗しました | | error_decode_image | ソース画像のデコードに失敗しました | | error_nsfw_content_detected | ソース画像に NSFW コンテンツが検出されました | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI 置き換え V1.0 | 1 | --- - [スカーフバーチャル試着](https://docs.perfectcorp.com/ja/reference/ai_scarf.md): # 概要 スカーフバーチャル試着を作成します。 スカーフを服装に着用した状態のプレビューを確認できます。 ## 統合ガイド このガイドでは、以下を説明します。 * **エンドポイント:** `/s2s/v2.0/task/scarf` * **認証:** すべてのリクエストには `Authorization: Bearer YOUR_API_KEY` が必要です * **ワークフロー:** 1. **セルフィー画像の準備:** バーチャル試着のターゲットとして、自分の画像をアップロードするか、有効な画像 URL を提供します。 1. **スカーフ画像の準備:** スカーフ製品またはスカーフを着用した人物（遮るものなく明確に見える）の画像をアップロードするか、有効な画像 URL を提供します。 1. **スタイルと性別の選択:** 希望するスタイルと、視覚化したい性別を選択します。 1. **AI タスクの実行とタスク ID の取得:** レスポンスから `task_id` を取得します。 1. **ステータスのポーリング (`GET`):** `task_id` を使用してタスクのステータスを確認します。`task_status` が `"success"` または `"error"` になるまでポーリングを続けます。 --- * 認証 - リクエストヘッダーに **Bearer トークン** を使用して API キーを含めます: ``` Authorization: Bearer YOUR_API_KEY ``` API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/. --- * AI スカーフ API 使用ガイド このガイドでは、画像のアップロード、参照スカーフの準備、および AI スカーフ API を使用したバーチャル試着タスクの作成方法について説明します。 *** * ステップ 1. セルフィー画像の準備 以下のいずれかの方法が利用可能です: * File API (`/s2s/v2.0/file`) を使用してセルフィー画像をアップロードする、または * 有効な画像 URL を提供する。 * ステップ 1.1 File API を使用したファイルのアップロード **File API** (`/s2s/v2.0/file`) を使用して、ターゲットユーザーの画像をアップロードします。 **画像要件:** * セルフィー写真をアップロードします。 * 写真に上半身が明確に写っていることを確認します。 * 複数の人物や気が散るオブジェクトがある背景は避けてください。 **リクエスト例:** ```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 } ] }' ``` *** * ステップ 1.2. File API レスポンスの取得 レスポンスには以下が含まれます: * AI タスク作成用の `file_id`。 * 実際の画像ファイルをアップロードするための `requests.url`。 **レスポンス例:** ```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" } } ] } ] } } ``` *** * ステップ 1.3. 提供された URL への画像アップロード File API レスポンスの `requests.url` を使用して画像をアップロードします: ```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' ``` *** * ステップ 2. 参照スカーフ画像の準備 以下のいずれかの方法が利用可能です: * File API (`/s2s/v2.0/file`) を使用してスカーフ画像をアップロードする、または * 有効な画像 URL を提供する。 **対応スカーフ画像:** * スカーフの製品画像。 * 遮るものなくスカーフを持っている人物（スカーフの参照用）。 詳細な仕様については、**[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)** を参照してください。 *** * ステップ 3. AI タスクの作成 希望するスタイルと、視覚化したい性別を選択します。 **AI タスク API** (`/s2s/v2.0/task/scarf`) を使用してバーチャル試着タスクを作成します。 **パラメータ:** * ユーザー画像用: `src_file_id` または `src_file_url`。 * スカーフ画像用: `ref_file_id` または `ref_file_url`。 **リクエスト例:** ```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" }' ``` **レスポンス例:** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` *** * ステップ 4. タスク結果のポーリング タスク ID を使用してステータスを確認します: ```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' ``` *** * ステップ 5. 結果の取得 成功したレスポンスには、結果画像のダウンロード URL が含まれます: ```json { "status": 200, "data": { "error": null, "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..." }, "task_status": "success" } } ``` 無効な API キーエラーレスポンス: ```json { "status": 401, "error": "Unauthorized", "error_code": "InvalidAccessToken" } ``` --- ## ファイル仕様とエラー * AI スカーフバーチャル試着仕様 * 画像要件 | タイプ | 最小解像度 | 備考 | | ------ | ------------------ | ----- | | セルフィー | 512 × 512 | 顔が見えること、頭から胸までが推奨 | | スカーフ | 512 × 512 (製品)
800 × 800 (着用時) | 明確で遮られていないスカーフのビュー | **対応スカーフ画像** * 製品画像要件 * 最小解像度: 512 × 512 ピクセル * 画像あたり 1 つの製品のみ * 製品は画像の高さの 25 パーセント以上を占める必要があります ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/021_thumb_e356d121b3.jpg) * 着用画像要件 * 最小解像度: 800 × 800 ピクセル ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/008_thumb_5dd8b1be93.jpg) **対応セルフィービュー** * 推奨画像解像度: 少なくとも 512 × 512 ピクセル。 * 推奨顔の被写体範囲: 画像の高さの 15 パーセント以上。 * 画像には単一の人物が明確に写っており、顔全体が見え、頭から胸まで（少なくとも頭部ショット）がフレームに含まれている必要があります。半身ショットが推奨されます。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/lashana_lynch_thumb_7a900b811e.jpg) **試着スタイル** * バーチャル試着出力を生成するための 5 つの事前定義スタイルがあります: "style_french_elegance", "style_light_luxury", "style_cottagecore", "style_modern_chic", "style_bohemian"。AI タスク作成時にこのスタイルパラメータを指定するか、デフォルトでシステムにランダムにスタイルを選択させることができます。 ![style_french_elegance](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/3d88ad75_41ca_4bf8_b81d_f52adf5db263_4a06b3e174.jpg) --- * 対応フォーマットと寸法 |AI 機能|対応寸法|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | |AI スカーフバーチャル試着|入力: 長辺 <= 4096
出力: 896 x 1152 |< 10MB|jpg/jpeg/png/heic| * エラーコード | エラーコード | 説明 | | ------------------------------ | -------------------------------------------- | | error\_download\_image | ソースまたは参照画像のダウンロードに失敗しました | | error\_inference | 推論パイプラインエラー | | error\_no\_face | ソース画像で顔が検出されませんでした | | error\_nsfw\_content\_detected | 結果に NSFW コンテンツが検出されました | | exceed\_max\_filesize | ファイルサイズが 10 MB を超えています | | invalid\_parameter | 無効な性別またはスタイル値 | | unknown\_internal\_error | その他の内部エラー | * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON パーシング) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch のため) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性のため), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings のため), requests >= 2.20.0 | | Java | Java 11+ (HttpClient のため), Jackson Databind >= 2.12.0 | --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | AI スカーフバーチャル試着 V2.0 | 2 | --- - [靴バーチャル試着](https://docs.perfectcorp.com/ja/reference/ai_shoes.md): # 概要 靴バーチャル試着を作成します。 靴を履いた状態のプレビューを確認できます。 ## 統合ガイド このガイドでは、以下を説明します。 * **エンドポイント:** `/s2s/v2.0/task/shoes` * **認証:** すべてのリクエストには `Authorization: Bearer YOUR_API_KEY` が必要です * **ワークフロー:** 1. **セルフィー画像の準備:** バーチャル試着の対象として、自分の画像をアップロードするか、有効な画像 URL を指定します。 1. **靴画像の準備:** 靴の商品画像または靴を履いた人物の写真をアップロードします。 1. **スタイルと性別の選択:** 希望するスタイルと、視覚化したい性別を選択します。 1. **AI タスクの実行とタスク ID の取得:** レスポンスから `task_id` を取得します。 1. **ステータスのポーリング (`GET`):** `task_id` を使用してタスクのステータスを確認します。`task_status` が `"success"` または `"error"` になるまでポーリングを続けます。 --- * 認証 - リクエストヘッダーに **Bearer トークン** を使用して API キーを含めます: ``` Authorization: Bearer YOUR_API_KEY ``` API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/. --- * AI 靴 API 使用ガイド このガイドでは、画像のアップロード、参照用靴の準備、および AI 靴 API を使用したバーチャル試着タスクの作成方法について説明します。 *** * ステップ 1. セルフィー画像の準備 以下のいずれかの方法が可能です: * File API (`/s2s/v2.0/file`) を使用してセルフィー画像をアップロードする、または * 有効な画像 URL を指定する。 * ステップ 1.1 File API を使用したファイルのアップロード **File API** (`/s2s/v2.0/file`) を使用して、対象ユーザーの画像をアップロードします。 **画像要件:** * セルフィー写真をアップロードします。 * 写真に上半身がはっきりと写っていることを確認してください。 * 複数の人物や気が散るオブジェクトがある背景は避けてください。 **リクエスト例:** ```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 } ] }' ``` *** * ステップ 1.2. File API レスポンスの取得 レスポンスには以下が含まれます: * AI タスク作成用の `file_id`。 * 実際の画像ファイルをアップロードするための `requests.url`。 **レスポンス例:** ```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" } } ] } ] } } ``` *** * ステップ 1.3. 指定された URL への画像アップロード File API レスポンスの `requests.url` を使用して画像をアップロードします: ```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' ``` *** * ステップ 2. 参照用靴画像の準備 以下のいずれかの方法が可能です: * File API (`/s2s/v2.0/file`) を使用して靴画像をアップロードする、または * 有効な画像 URL を指定する。 **サポートされる靴画像:** * 靴の商品画像。 * 靴を履いた人物の写真。 詳細な仕様については、**[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)** を参照してください。 *** * ステップ 3. AI タスクの作成 希望するスタイルと、視覚化したい性別を選択します。 **AI タスク API** (`/s2s/v2.0/task/shoes`) を使用して、バーチャル試着タスクを作成します。 **パラメータ:** * ユーザー画像用: `src_file_id` または `src_file_url`。 * 靴画像用: `ref_file_id` または `ref_file_url`。 **リクエスト例:** ```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" }' ``` **レスポンス例:** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` *** * ステップ 4. タスク結果のポーリング タスク ID を使用してステータスを確認します: ```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' ``` *** * ステップ 5. 結果の取得 成功したレスポンスには、結果画像のダウンロード URL が含まれます: ```json { "status": 200, "data": { "error": null, "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..." }, "task_status": "success" } } ``` 無効な API キーのエラーレスポンス: ```json { "status": 401, "error": "Unauthorized", "error_code": "InvalidAccessToken" } ``` --- ## ファイル仕様とエラー * AI 靴バーチャル試着仕様 * 画像要件 | 種類 | 最小解像度 | 備考 | | ------ | ------------------ | ----- | | セルフィー | 512 × 512 | 顔が見えること、頭から胸までが推奨 | | 靴 | 512 × 512 (商品)
800 × 800 (着用) | 靴がはっきりと、遮られずに写っていること | **サポートされる靴画像** * 商品画像の要件 * 最小解像度: 512 × 512 ピクセル * 画像あたり 1 つの製品のみ * 製品は画像の高さの 25% 以上を占める必要があります ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/0019_thumb_06a4a9cc5f.jpg) * 着用画像の要件 * 最小解像度: 800 × 800 ピクセル * 単一アイテム要件: モデルは正確に 1 つのアイテムのみを着用している必要があります。複数のアイテムやアクセサリーは許可されません。 * カバレッジ比率: 着用アイテムは画像全体の height の 20% 以上を占める必要があります。これにより、アイテムがフレーム内で明確に見え、目立つことが保証されます。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/0006_thumb_50a0a0640c.jpg) **サポートされるセルフィービュー** * 推奨画像解像度: 少なくとも 512 × 512 ピクセル。 * 推奨顔のカバレッジ: 画像の高さの 15% 以上。 * 単一被写体要件: 画像には正確に 1 人の人間の被写体のみが含まれている必要があります。追加の人物や部分的な人物像は許可されません。 * 顔の可視性: 被写体の顔が完全に視認可能で、遮られていない必要があります。髪、アクセサリー、またはオブジェクトが主要な顔の特徴を覆ってはいけません。 * フレーミング: 画像には少なくとも頭部ショットを含み、頭頂部から胸までの領域をカバーする必要があります。最適な分析のためには、半身ショット（頭から腰まで）が推奨されます。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/lashana_lynch_thumb_7a900b811e.jpg) **試着スタイル** * バーチャル試着出力の生成には、"style_minimalist" "style_bohemian" "style_cottagecore" "style_french_elegance" および "style_retro_fashion" の 5 つの事前定義されたスタイルがあります。AI タスク作成時にこの style パラメータを指定するか、デフォルトでシステムがランダムにスタイルを選択させることができます。 ![style_bohemian](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/cc55fe0d_aec9_4ead_b2e9_bc70f48c58b9_670a875b29.jpg) --- * サポートされる形式と寸法 | AI 機能 | サポートされる寸法 | サポートされるファイルサイズ | サポートされる形式 | | ---- | ---- | ---- | ---- | | AI 靴バーチャル試着 | 入力: 長辺 <= 4096
出力: 1008 x 1344 | < 10MB | jpg/jpeg/png/heic | * エラーコード | エラーコード | 説明 | | ------------------------------ | -------------------------------------------- | | error\_download\_image | ソースまたは参照画像のダウンロードに失敗しました | | error\_inference | 推論パイプラインエラー | | error\_no\_face | ソース画像で顔が検出されませんでした | | error\_nsfw\_content\_detected | 結果に NSFW コンテンツが検出されました | | exceed\_max\_filesize | ファイルサイズが 10 MB を超えています | | invalid\_parameter | 無効な gender または style 値 | | unknown\_internal\_error | その他の内部エラー | * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON パーシング) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性用), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings 用), requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用), Jackson Databind >= 2.12.0 | --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | AI 靴バーチャル試着 V2.0 | 2 | --- - [AI 肌分析](https://docs.perfectcorp.com/ja/reference/ai_skin_analysis.md): # 概要 (Overview) ![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_demostore_skincarelive_topbanner.0cffe3a7.jpg) AI 肌分析 (AI Skin Analysis) では、真正面を向いた 1 枚のセルフィーから顔の肌悩みを評価します。 キメ、色素沈着、うるおい、毛穴の大きさなど、肌のさまざまな側面を解析します。 肌悩みスコアと検出マスクを提供します。 ## 統合ガイド (Integration Guide) * AI 肌分析のための写真の撮影方法 * 真正面を向いてセルフィーを撮影する - 1 枚の鮮明な写真を、カメラをまっすぐ見つめて撮影します。髪は下ろして胸にかかるようにし、真正面の構図になるよう必ずまっすぐ前方を見てください。 - 代わりに JS Camera Kit を使用して撮影します。髪は下ろして胸にかかるようにするだけで構いません。まとめないでください。 * ワークフロー **肌診断 API 使用ガイド** このガイドでは、File API と AI Task API を使用して画像をアップロードし、肌診断タスクを作成する方法を説明します。 * **ステップ 1: 元画像をリサイズする**
写真を対応寸法に合わせてリサイズします - SD は長辺が最大 4096 ピクセルで短辺が 480 ピクセル以上、または HD は長辺が最大 4096 ピクセルで短辺が 1080 ピクセル以上です。詳細は **[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)** を参照してください * **ステップ 2: File API でファイルメタデータをアップロードする** - 画像の要件 - 詳細は **[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)** を参照してください POST リクエストを送信して、ファイルアップロードを初期化します： ```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 } ] }' ``` - ***重要***: File API を呼び出すだけではファイルはアップロードされません。**File API のレスポンスで提供される URL** に対してファイルを**追加でアップロード**する必要があります。その URL がアップロード先です。次に進む前に、ファイルが正常に転送されたことを確認してください。 > **警告:** File API のレスポンスで提供される URL にファイルをアップロードしないまま AI API を使用すると、500 Server Error / unknown_internal_error または 404 Not Found エラーが発生します。 *** * **ステップ 3: アップロード URL とファイル ID を取得する** レスポンスには以下が含まれます： * `requests.url` – 画像アップロード用のプリサインド URL。 * `file_id` – AI タスク作成用の識別子。 **レスポンス例：** ```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" } } ] } ] } } ``` *** * **ステップ 4: プリサインド URL に画像をアップロードする** 提供された `requests.url` とヘッダーを使用します： ```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' ``` *** * **ステップ 5: AI タスクを作成する** ステップ 2 の `file_id` を使用して肌診断タスクを作成します： ```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" }' ``` アップロードが完了したら、ファイル ID または画像ファイル URL を使用して、解析する肌悩みを選択できます。**[入力と出力](#section/overview/Inputs-and-Outputs)** を参照してください。
その後、ファイル ID または画像ファイル URL を指定して POST 'task/skin-analysis' を呼び出すと画質改善タスクが実行され、***task_id*** が取得されます。 SD と HD の肌悩みパラメータを同時に使用することは**サポートされていません**。 - **既存の公開画像 URL を使用する** アップロードの代わりに、AI タスクの開始時に公開アクセス可能な画像 URL を直接指定できます。 **レスポンス例：** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` *** * **ステップ 6: タスクステータスをポーリングする** `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' ``` この ***task_id*** は、GET 'task/skin-analysis' をポーリングして現在のエンジンステータスを取得し、タスクのステータスを監視するために使用します。エンジンがタスクを完了するまでステータスは 'running' のままとなり、この段階ではユニットは消費されません。 処理された結果は完了後 24 時間保持されます。- 短い間隔でポーリングする必要はありません。- 24 時間以内の範囲であればポーリング間隔は柔軟に設定できます。 > **重要:** 実行時間は保証されないため、タスクステータスを確認するには引き続きポーリングが必要です。 エンジンが入力ファイルの処理に成功し、結果画像を生成すると、タスクは 'success' ステータスに変わります。処理済み画像の URL と dst_id が取得され、結果画像を再アップロードせずに別の AI タスクを連鎖して実行できます。 ユニットが消費されるのはこの場合のみです。エンジンがタスクの処理に失敗すると、タスクのステータスは 'error' に変わり、ユニットは消費されません。 ユニットを減算する際、システムは有効期限が近いものを優先します。有効期限が同じ場合は、最も早く取得したユニットから減算されます。 *** * **ステップ 7: 結果を解釈する** レスポンスには以下が含まれます： * `ui_score` – ユーザー向けのスコア。 * `raw_score` – 解析の生スコア。 * `mask_urls` – 検出マスクの URL。 **レスポンス例：** ```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" } } ``` * デバッグガイド > **警告:** SD と HD の肌悩みパラメータを同時に使用することは**サポートされていません**。これらの仕様に違反する操作を行うと ***InvalidParameters*** エラーが発生します。 * HD と SD の肌悩みを混在して使用すると、次のようなエラーが発生します： ```json { "status": 400, "error": "cannot mix HD and SD dst_actions", "error_code": "InvalidParameters" } ``` * 肌悩みをスペルミスした場合、または不明な肌悩みを送信した場合、次のようなエラーが発生します： ```json { "status": 400, "error": "Not available dst_action abc123", "error_code": "InvalidParameters" } ``` --- * 実際の活用例： ![](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) * 入力パラメータの説明 AI 肌分析 (AI Skin Analysis) の結果の視覚的な出力を制御する方法は 2 つあります。複数の画像を生成して各肌悩みをそれぞれ独立したマスクとして表示する方法と、``enable_mask_overlay`` パラメータを使用してブレンドされた 1 枚の画像を生成する方法のいずれかを選択できます。初期設定ではシステムが複数のマスクを出力するため、各肌悩みのマスクを画像とどのようにブレンドするかを完全に制御できます。 * 初期値: enable_mask_overlay false ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/mask_overlay_false_1920_ea1cde0ead.png) * enable_mask_overlay を true に設定 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/mask_overlay_1920_0fbb4786cc.png) ---- * 出力 ZIP のデータ構造の説明 システムは ZIP ファイルを提供し、その内部に 'skinanalysisResult' フォルダが含まれています。このフォルダには、すべての検出スコアと結果画像への参照を含む 'score_info.json' ファイルが格納されています。 'score_info.json' ファイルには、すべての肌診断の検出結果が、数値のスコアと対応する出力マスクファイル名とともに含まれています。 PNG ファイルは、元の画像にオーバーレイできる検出結果のマスクです。これらの PNG ファイルのアルファ値を使って元の画像とブレンドするだけで、検出結果を元画像上で直接確認できます。 * 肌診断結果 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 データ構造 (score_info.json) * "all": 1 から 100 の範囲の浮動小数点値で、一般的な肌状態を表します。スコアが高いほど、より健康で美しさに優れた肌状態であることを示します。 * "skin_age": すべての年齢層にわたる一般母集団の分布に対する、AI が算出した肌年齢。 * 各カテゴリには以下が含まれます: * "raw_score": 1 から 100 の範囲の浮動小数点値。スコアが高いほど、より健康で美しさに優れた肌状態であることを示します。 * "ui_score": 1 から 100 の範囲の整数。UI Score は主に美容評価において心理的なモチベーションの向上として機能します。消費者は一般的に自身の肌状態について肯定的な評価を好むことを踏まえ、より好ましい結果となるよう raw スコアを調整しています。このキャリブレーションは、根底にある美容心理学の枠組みを維持しつつ、ユーザーにより大きな自信を持っていただくことを目的としています。 * "output_mask_name": 対応する出力マスク画像のファイル名。 * カテゴリと説明 * HD Skincare: * "hd_redness": 肌の赤みの深刻度を測定します。 * "hd_oiliness": 肌の皮脂レベルを判定します。 * "hd_age_spot": 老人斑と色素沈着を検出します。 * "hd_radiance": 肌の輝きを評価します。 * "hd_moisture": 肌の水分量を評価します。 * "hd_dark_circle": 目の下のクマの有無を解析します。 * "hd_eye_bag": 目元のたるみを検出します。 * "hd_droopy_upper_eyelid": 上まぶたの下垂の深刻度を測定します。 * "hd_droopy_lower_eyelid": 下まぶたの下垂の深刻度を測定します。 * "hd_firmness": 肌のハリと弾力を評価します。 * "hd_texture": Subcategories[whole]; 肌全体のキメを解析します。 * "hd_acne": Subcategories[whole]; にきりの有無を検出します。 * "hd_pore": Subcategories[forehead, nose, cheek, whole]; 異なる顔領域の毛穴を検出し、評価します。 * "hd_wrinkle": Subcategories[forehead, glabellar, crowfeet, periocular, nasolabial, marionette, whole]; さまざまな顔領域におけるしわの深刻度を測定します。 * "hd_tear_trough": 涙溝を検出します。 * "hd_skin_type": Subcategories[whole, t_zone, u_zone] Normal、Oily、Dry、Combination、Redness、Dry & Redness、Oily & Redness、Combination & Redness のいずれかの肌タイプを評価します。 * SD Skincare: * "wrinkle": しわに関する一般的な解析。 * "droopy_upper_eyelid": 上まぶたの下垂の深刻度を測定します。 * "droopy_lower_eyelid": 下まぶたの下垂の深刻度を測定します。 * "firmness": 肌のハリと弾力を評価します。 * "acne": にきりの有無を評価します。 * "moisture": 肌の水分量を測定します。 * "eye_bag": 目元のたるみを検出します。 * "dark_circle_v2": 別の方法を用いてクマを解析します。 * "age_spot": 老人斑を検出します。 * "radiance": 肌の明るさを評価します。 * "redness": 肌の赤みを測定します。 * "oiliness": 肌の皮脂レベルを判定します。 * "pore": 毛穴の目立ち度を測定します。 * "texture": 肌全体のキメを解析します。 * "tear_trough": 涙溝を検出します。 * "skin_type": Subcategories[whole, t_zone, u_zone] Normal、Oily、Dry、Combination、Redness、Dry & Redness、Oily & Redness、Combination & Redness のいずれかの肌タイプを評価します。 * HD Skincare の score_info.json の例 ```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 } ``` * SD Skincare の score_info.json の例 ```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 and Errors) * 対応しているファイル形式と解像度 | AI 機能 | 対応解像度 | 対応ファイルサイズ | 対応フォーマット | | ---- | ---- | ---- | ---- | | SD スキンケア | 短辺の長さは最低 480 ピクセル以上である必要があります。
長辺に上限はありませんが、2560 ピクセルを超える場合、システムにより自動的に 2560 ピクセルへリサイズされます。 | < 10MB | jpg/jpeg/png | | HD スキンケア | 短辺の長さは最低 1080 ピクセル以上である必要があります。
長辺に制限はありませんが、2560 ピクセルを超える場合、自動的に 2560 ピクセルへリサイズされます。 |< 10MB | jpg/jpeg/png | > **警告:** API では画像が自動的に最大 2560 ピクセルにリサイズされますが、すべての顔にはっきりとピントが合っていること、画像の品質が高いこと、照明が均一であること、顔のサイズが十分に大きく、カメラの正面を向いていることを、お客様ご自身の責任でご確認ください。AI 肌分析 (AI Skin Analysis) を実行する前に HD または SD のスキンケア画像を撮影する際は、被写体ブレと遮蔽を避けてください。最適な結果を得るには、横位置よりも縦位置のアスペクト比の使用を推奨します。 * 撮影方法の推奨事項: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png) * 肌診断を開始する準備ガイド * 眼鏡を外し、前髪が額にかかっていないことを確認してください * 明るい環境であることを確認してください * より正確な結果を得るためにメイクを落としてください * カメラをまっすぐ見つめ、顔を中央に保ってください * 写真の要件 画像の品質を確認し、AI 肌分析に適しているかどうかを判断します。顔が画像の幅の約 60–80% を占め、オーバーレイや遮蔽物がないようにしてください。照明は明るく均一に分配し、露出オーバーや白飛びを避けてください。姿勢は正面を向き、自然でリラックスした状態とし、口を閉じて目を開けてください。 額が完全に見えるようにし、最良の品質を確保するため、前髪を後ろにとかすか髪を結んでください。AI 肌分析の性能を最適化するには眼鏡を外すことを推奨しますが、必須ではありません。 > **警告:** 顔の幅は画像の幅の 60% より大きい必要があります。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_error_src_face_too_small_cr_725792a7fb.png) * エラーコード |エラーコード|説明| | ---- | ---- | |error_below_min_image_size|入力画像の解像度が小さすぎます| |error_exceed_max_image_size|入力画像の解像度が大きすぎます| |error_src_face_too_small|アップロードされた画像内の顔の領域が小さすぎます。顔の幅は画像の幅の 60% より大きい必要があります。| |error_src_face_out_of_bound|アップロードされた画像内の顔の領域が範囲外です| |error_lighting_dark|アップロードされた画像の照明が暗すぎます| * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON パース) | | Node.js (JavaScript) | Node >= 18 (global fetch を使用するため) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性のため)、ext-curl (推奨) または allow_url_fopen=On + ext-openssl、ext-json | | Python | Python >= 3.10 (f-string を使用するため)、requests >= 2.20.0 | | Java | Java 11+ (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" /%} --- ## ユニット消費量 * AI 肌分析 (AI Skin Analysis) (V2.0, 2.1) | AI 機能 | 消費ユニット数 | |---|---| | 1~4 項目の肌悩み解析 | SD は 9 ユニット、HD は 12 ユニット | | 5~8 項目の肌悩み解析 | SD は 12 ユニット、HD は 16 ユニット | | 9~12 項目の肌悩み解析 | SD は 14 ユニット、HD は 20 ユニット | | 13~16 項目の肌悩み解析 | SD は 16 ユニット、HD は 22 ユニット | --- - [AI 肌改善シミュレーション](https://docs.perfectcorp.com/ja/reference/ai_skin_simulation.md): # 概要 **AI 駆動の肌シミュレーション** AI 肌シミュレーションでは、顔の肌状態のビフォーアフターを可視化します。 最大 10 種類の肌悩み（輝き、ニキビ、皮脂、目の下のたるみ、クマ、シミ、毛穴、肌質、しわ、赤み）を可視化できます。 ![](https://plugins-media.makeupar.com/smb/blog/post/2025-04-17/4edad54f-ef6b-4842-b104-d114889318b1.jpg) 各シミュレーションは数秒で生成されます。 ![](https://plugins-media.makeupar.com/smb/blog/post/2025-11-13/webp_27e3ad50-7769-46de-822c-c9300f87f57d.webp) e コマースウェブサイト、モバイルアプリケーションなどで使えます。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_Skin_Simulation_pores_b1e209ee58.jpg) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_Skin_Simulation_283421234a.jpg) --- ## 統合ガイド このガイドでは、以下を説明します。 AI 肌改善シミュレーション API のワークフロー： **エンドポイント:** `/s2s/v2.0/task/skin-simulation` **認証必須:** `Authorization: Bearer YOUR_API_KEY` **ワークフロー手順:** 1. **画像アップロードの準備:** - プロセスはセルフィー画像の準備から始まります。 2. **AI 肌改善シミュレーション設定** 各肌悩み（例：しわ、毛穴、赤み）について、**シミュレーション強度**を **0.0 から 1.0** の値で調整します： - **0.0**: *元の*肌の外観を表示します—変更なし。 - **1.0**: その悩みに対して AI が生成できる*最も自然で健康的に見える*強化を適用します。 **仕組み:** - 低い設定（例：0.2～0.4）では、細かいしわや軽微な欠陥が微妙に緩和されます。 - 高い設定（例：0.7～1.0）では、中程度または深いしわの大幅な軽減、滑らかな質感、トーンの改善など、より顕著な改善が、自然な肌のディテールを保持しながらも発生します。 望ましい見た目になるまで調整してください。 3. **AI タスクの開始とタスク ID の取得:** - アップロードした画像と肌シミュレーション設定を HTTP POST リクエストで `/s2s/v2.0/task/skin-simulation` に送信します。 - このやり取りを識別する一意のタスク ID をレスポンスで待ちます。 4. **タスクステータスのポーリング（継続的な確認）:** - 取得した `task_id` を使用して、HTTP GET リクエスト（例：`GET /task/${task_id}`）でタスクステータスを定期的にポーリングします。 - 以下を継続的に監視します： - `Task_status = "success"`（処理完了）。 - `Task_status = "error"`（該当する場合、解決または再試行）。 - ステータスが success に遷移したら、ワークフローを適切に更新します。 --- * 認証 - リクエストヘッダーに **Bearer トークン** を使用して API キーを含めます： ``` Authorization: Bearer YOUR_API_KEY ``` API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/. --- * 画像のアップロード ファイルをサーバーに直接アップロードするか、AI タスクペイロードに有効な画像 URL を提供できます。 * アップロードエンドポイント ``` POST /s2s/v2.0/file ``` すでに公開画像 URL がある場合は、この手順をスキップできます。 --- * AI 肌改善シミュレーション強度の調整 **AI 肌改善シミュレーション設定** 各肌悩み（例：しわ、毛穴、赤み）について、**シミュレーション強度**を **0.0 から 1.0** のスケールで調整します： - **0.0** → *元の外観* — AI 強化は適用されません。 - **1.0** → その悩みに対する最大限の改善。 **異なる強度レベルでの期待効果：** | 強度範囲 | 効果 | |-----------------|--------| | **0.1 – 0.3** | 微妙な改善: 細かいしわの軽微な平滑化、毛穴のわずかな軽減、赤みの穏やかな軽減。 | | **0.4 – 0.6** | 中程度の改善: 質感と透明感の改善。 | | **0.7 – 1.0** | 顕著な改善: 中程度から深いしわの大幅な軽減、トーンの均一化、毛穴と赤みの最小化。 | 低め（例：0.2）から開始して調整します。 --- * AI 肌改善シミュレーション AI タスクの作成と結果のポーリング 画像をアップロードし、**少なくとも 1 つ**の肌悩みのシミュレーション強度を 0.0 以上に設定した後、タスクを開始できます。API はリクエストを非同期で処理します。ステータスが `success` または `error` に達するまで、タスクステータスをポーリングする必要があります。 * タスク作成エンドポイント ``` POST /s2s/v2.0/task/skin-simulation ``` * ポーリングエンドポイント ``` GET /s2s/v2.0/task/skin-simulation/{task_id} ``` --- ## ファイル仕様とエラー * AI 肌改善シミュレーション仕様 **カメラと撮影ガイドライン** **ライティング条件** 環境が十分に明るく、均一に照明されていることを確認してください。強い逆光、局所的な露出オーバー、顔への大きな影を避けてください。可能な限り自然光または柔らかい屋内照明を使用してください。ピンク、ブルー、その他の色付き光源など、有色光は肌の色調の表現を歪める可能性があるため使用しないでください。 **顔の位置と遮蔽** 顔がカメラを直接向いている正面からのビューを撮影してください。頭の回転は最小限に抑え、過度な傾きや左右への向きを避けてください。額、頬、あごを含む顔全体が完全に可視であり、遮蔽されていないことを確認してください。髪、マスク、手、メガネのフレーム、携帯電話、または顔の特徴を部分的に覆うその他のオブジェクトは使用しないでください。 **表情とポーズ** 両目を開いた自然でリラックスした表情を保ってください。口は閉じたままでもわずかに開いていても構いませんが、ポーズを無理にしたり誇張したりしないでください。 **フレーム内の顔サイズ** 正確な分析に必要な十分なディテールを確保するために、顔は画像幅の少なくとも 60% を占める必要があります。被写体が小さすぎる、遠すぎる、または不適切にフレーミングされている画像の撮影は避けてください。 ![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_skin_analysis_01_5b5defd339.png) --- * サポートされる形式と寸法 |AI 機能|サポートされる寸法|サポートされるファイルサイズ|サポートされる形式| | ---- | ---- | ---- | ---- | |AI 肌改善シミュレーション|短辺 >= 480, 長辺 <= 2560|< 10MB|jpg/jpeg/png| * エラーコード | **エラーコード** | **説明** | |------------------------------------|----------------| | `error_below_min_image_size` | 入力画像の解像度が最小必要サイズ未満です（例：< 256×256 ピクセル）。より高解像度の画像をアップロードしてください。 | | `error_exceed_max_image_size` | 入力画像の解像度が最大許容サイズを超えています（例：> 2560×2560 ピクセル）。アップロード前に画像をリサイズまたはダウンスケールしてください。 | | `error_invalid_params` | 無効なリクエストパラメータが提供されました。 | | `error_src_face_too_small` | 検出された顔が画像幅の 60% 未満を占めています—正確な肌分析には小さすぎます。フレーム中央に大きく鮮明な顔がある画像を使用してください。 | | `error_src_face_out_of_bound` | 検出された顔が画像境界の外側に部分的または完全に位置しています（例：顔が切り詰められすぎている）。額、頬、あごを含む顔全体が可視であり、適切にフレーミングされていることを確認してください。 | | `error_lighting_dark` | 画像内の環境光が信頼できる肌分析には不十分です（例：露出不足、顔に影が支配的）。顔に均一な照明がある明るく撮影された画像をアップロードしてください。 | * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON パーシング) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性用), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings 用), requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用), Jackson Databind >= 2.12.0 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## ユニット消費 * 肌シミュレーション | AI 機能 | 消費ユニット | |---|---| | 1～4 悩みの分析 | 4 | | 5～10 悩みの分析 | 6 | --- - [顔パーツの色分析](https://docs.perfectcorp.com/ja/reference/ai_skin_tone_analysis.md): # 概要 顔パーツの色分析では、肌の色調、目、眉毛、唇、髪の色を検出します。 ![](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) ## 統合ガイド * 顔パーツの色分析用の写真撮影方法 正面を向いて自撮りしてください - カメラをまっすぐ見ている、1 枚のクリアな写真のみを使用してください。髪を下ろして胸にかかっている状態にし、真正面を向いていることを確認してください。 - 代わりに、JS Camera Kit を使用して写真を撮影してください。髪を下ろして胸にかかっている状態にしてください。結ばないでください。 * AI による肌トラブル検出方法 1. **ソース画像のリサイズ**
サポートされている寸法に合わせて写真をリサイズします。詳細は **[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)** を参照してください。 2. **File API を使用したファイルのアップロード**
***/s2s/v2.0/file*** API を使用して、対象ユーザーの画像をアップロードします。 - 画像要件 - 詳細は **[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)** を参照してください。 - ***重要***: File API を呼び出すだけではファイルはアップロードされません。File API のレスポンスで提供される **URL に手動でファイル** をアップロードする必要があります。その URL がアップロード先です。次に進む前に、ファイルが正常に転送されたことを確認してください。
AI API を呼び出す前に、ファイルが正常にアップロードされていることを確認してください。File API を使用してアップロード URL を取得し、その場所にファイルをアップロードします。アップロードが完了すると、レスポンスに ***file_id*** が返されます。この ID は、そのファイルに関連する AI 機能にアクセスするために使用します。 > **警告:** File API のレスポンスで提供される URL にファイルをアップロードしない場合、AI API の使用時に 500 Server Error / unknown_internal_error または 404 Not Found エラーが発生します。 3. **顔パーツの色分析タスクの実行**
アップロードが完了すると、AI はファイル ID を使用して、唇、目、眉毛、肌、髪の色調を調べます。詳細は **[入力と出力](#section/overview/Inputs-and-Outputs)** を参照してください。
次に、File ID を指定して POST 'task/skin-tone-analysis' を呼び出すと、タスクが実行され、***task_id*** が取得されます。 4. **タスクのステータスをポーリングして成功またはエラーを確認する**
この ***task_id*** は、GET 'task/skin-tone-analysis' によるポーリングを通じてタスクのステータスを監視するために使用され、現在のエンジンステータスを取得します。エンジンがタスクを完了するまで、ステータスは 'running' のままであり、この段階ではユニットは消費されません。 **警告:** タスクのステータスを保持期間に基づいてポーリングで確認することは必須です。保持期間内にポーリングリクエストがない場合、タスクが正常に処理されていてもタイムアウトします（ユニットが消費されます）。 > **警告:** タイムアウトしたタスクのステータスを確認すると、***InvalidTaskId*** エラーが発生します。したがって、AI タスクを実行したら、ステータスが *success* または *error* になるまで、保持期間内にステータスを確認するために **ポーリング** する必要があります。 5. **成功時に AI タスクの結果を取得する**
エンジンが入力ファイルを正常に処理し、結果画像を生成すると、タスクは 'success' ステータスに変更されます。処理済み画像の URL と、結果画像を再アップロードせずに別の AI タスクをチェーン実行できる dst_id が取得されます。 ユニットは、この場合のみ消費されます。エンジンがタスクの処理に失敗した場合、タスクのステータスは 'error' に変更され、ユニットは消費されません。
ユニットを控除する際、システムは期限切れに近いものから優先的に控除します。期限が同じ場合は、最も早い日に取得されたユニットから控除されます。 ![](https://plugins-media.makeupar.com/smb/blog/post/2022-08-19/2a1af800-7c69-44a5-a94c-70a4a9c4d2b0.jpg) --- ## 入力と出力 * 入力 AI は肌の色調を分析します。`face_angle_strictness_level` を調整して、入力された顔の角度のチェックの厳密さを、strict、high、medium、low、flexible の範囲で制御できます。厳密さレベルは、ピッチ、ヨー、ロールを含む顔の角度検出に適用されます。デフォルト設定は high です。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/shade_finder_s4_poster_399f34c6ef.jpg) * 出力 ```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" } } } } ``` | **結果パラメータ** | **結果タイプ** | | --- | --- | | `skin_color` | Hex 値 | | `eye_color`| Hex 値 | | `eye_color_name` | Amber, Brown, Green, Blue, Gray, Other | | `lip_color` | Hex 値 | | `eyebrow_color` | Hex 値 | | `hair_color` | Hex 値 | | `color.hair_color_name` | Auburn, Black, Blonde, Brown, Grey/White, Red | * 撮影方法のヒント: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png) > **警告:** 顔の幅は画像の幅の 60% より大きくなければなりません。 --- ## ファイル仕様とエラー * サポートされている形式と寸法 | AI 機能 | サポートされている寸法 | サポートされているファイルサイズ | サポートされている形式 | | ---- | ---- | ---- | ---- | | 顔パーツの色分析 | 長辺 <= 4096、1 人のみ。1080px より長い辺を持つ画像は、分析のために自動的にリサイズされます。 | < 10MB | jpg/jpeg | * エラーコード |エラーコード|説明| | ---- | ---- | | error_below_min_image_size | ソース画像の寸法は少なくとも 320 ピクセルである必要があります。 | | error_face_position_invalid | 顔は完全に可視であり、正面を向いており、画像の中央にある必要があります。 | | error_face_position_too_small | 検出された顔が分析には小さすぎます。 | | error_face_position_out_of_boundary | 顔が画像の境界を超えています。 | | error_face_not_forward_facing | 顔はカメラを直接向いている必要があります。 | | error_face_angle_upward | 顔が上向きに傾きすぎています—頭をわずかに下げてください。 | | error_face_angle_downward | 顔が下向きに傾きすぎています—頭をわずかに上げてください。 | | error_face_angle_leftward | 顔が左に回りすぎています—頭をわずかに右に回してください。 | | error_face_angle_rightward | 顔が右に回りすぎています—頭をわずかに左に回してください。 | | error_face_angle_left_tilt | 顔が左に傾きすぎています—頭を優しく右に傾けてください。 | | error_face_angle_right_tilt | 顔が右に傾きすぎています—頭を優しく左に傾けてください。 | * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON パーシング) | | Node.js (JavaScript) | Node >= 18 (global fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性用), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings 用), requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用), Jackson Databind >= 2.12.0 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | 顔パーツの色分析 V1.0 | 20 | --- - [笑顔補正](https://docs.perfectcorp.com/ja/reference/ai_smile.md): # 概要 AI 笑顔補正では、表情を笑顔に変換します。 AI 笑顔補正は 2 種類の笑顔スタイルをサポートしています。 1. **smile_with_teeth_visible** 歯が見える笑顔を作成します。 2. **closed_mouth_smile** 唇を閉じた控えめな笑顔を作成します。 写真の内容に合わせて笑顔タイプを選択します。 ![](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) ## 統合ガイド このガイドでは、以下を説明します。 AI 笑顔補正 のワークフロー: **エンドポイント:** `/s2s/v2.0/task/ai-smile` **認証必須:** `Authorization: Bearer YOUR_API_KEY` **ワークフロー手順:** 1. **画像アップロード準備:** - アップロード用の自撮り画像を準備します。 - File API `/s2s/v2.0/file` を呼び出して、アップロード URL と関連する `file_id` を取得します。 - 提供されたアップロード URL を使用して、自撮り画像をアップロードします。 2. **AI タスクの開始とタスク ID の取得:** - `file_id` と選択したエフェクト設定を HTTP POST リクエストで `/s2s/v2.0/task/ai-smile` に送信します。 - このやり取りを識別する一意のタスク ID をレスポンスで待ちます。 3. **タスクステータスのポーリング（継続的な確認）:** - 取得した `task_id` を使用して、HTTP GET リクエスト（例: `GET /s2s/v2.0/task/ai-smile/${task_id}`）でタスクステータスを定期的にポーリングします。 - 以下を継続的に監視します: - `Task_status = "success"`（処理完了）。 - `Task_status = "error"`（該当する場合、解決または再試行）。 - ステータスが success に遷移したら、ワークフローを適切に更新します。 --- 1. 認証 - **Bearer トークン** を使用して、リクエストヘッダーに API キーを含めます: ``` Authorization: Bearer YOUR_API_KEY ``` API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/. 2. 画像のアップロード サーバーへファイルを直接アップロードするか、AI タスクペイロードに有効な画像 URL を指定します。 * アップロードエンドポイント ``` POST /s2s/v2.0/file ``` すでに公開画像 URL がある場合は、この手順をスキップできます。 --- 3. AI 笑顔タスクの作成と結果のポーリング 画像と完全なエフェクト設定が用意できたら、タスクを作成します。API はリクエストを非同期で処理します。ステータスが `success` または `error` になるまで、タスクステータスをポーリングする必要があります。 * タスク作成エンドポイント ``` POST /s2s/v2.0/task/ai-smile ``` * ポーリングエンドポイント ``` GET /s2s/v2.0/task/ai-smile/{task_id} ``` --- ## ファイル仕様とエラー * AI 笑顔仕様 **サポートされる自撮りビュー** 単一人物の画像のみサポートされます。画像には、長辺が 640 ピクセルの場合に 32 x 32 ピクセルを超える十分なサイズの顔が明確に写っている必要があり、顔検出の失敗を避けるため、撮影角度はロールがプラスマイナス 75 度以内、ヨーがプラスマイナス 90 度以内である必要があります。 ![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_face_reshape_01_85c8ffc055.jpg) --- * サポートされる形式と寸法 | AI 機能 | サポートされる寸法 | サポートされるファイルサイズ | サポートされる形式| | ---- | ---- | ---- | ---- | | AI 笑顔 | 長辺 <= 4096 | < 10MB | jpg/jpeg/png/heic | * エラーコード | エラーコード | 説明 | | ---------- | ----------- | | EXCEED_MAX_FILESIZE | 入力ファイルが最大許容サイズを超えています。 | | INVALID_PARAMETER | 1 つ以上の必須パラメータが欠落、空、または不正な形式です。 | | ERROR_DOWNLOAD_IMAGE | ソース画像をダウンロードできませんでした。 | | ERROR_NO_FACE | 提供された画像で顔が検出されませんでした。 | | ERROR_INFERENCE | ワークフローの問題、実行エラー、エンコーディングエラー、または出力画像の欠落により、推論プロセスが失敗しました。 | | UNKNOWN_INTERNAL_ERROR | 予期しない内部エラーが発生しました。 | * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON 解析) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性用), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings 用), requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用), Jackson Databind >= 2.12.0 | --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | AI 笑顔 V1.0 | 1 | --- - [AI スタジオ写真](https://docs.perfectcorp.com/ja/reference/ai_studio_generator.md): # 概要 AI スタジオ写真では、セルフィーをスタジオ品質のポートレートに変換します。 * スタジオ不要の利便性：カメラマンやスタジオへの訪問は不要です。いつでもどこでも、スタジオ品質の芸術的な写真を生成できます * 迅速な写真変換：高速処理により、高品質な芸術的な写真の結果を即座に得られます。素早い更新に最適です * 高品質な芸術的出力：スタジオで撮影したかのような、細部が鮮明で照明が完璧なプロフェッショナル基準の芸術的な写真を提供します ユースケース: ![AI スタジオ写真](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_studio_S1_img_19b627b6af.jpg "AI スタジオ写真") ![AI スタジオ写真](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_studio_S2_img_01_2e318817e9.jpg "AI スタジオ写真") 撮影のヒント： ![撮影のヒント](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png "撮影のヒント") --- ## ファイル仕様とエラー * 対応フォーマットと寸法 |AI 機能|対応寸法|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | |AI スタジオ写真|入力画像に 1 つの顔が含まれていること、短辺が少なくとも 200 ピクセル、長辺が 1920 ピクセル以下であることを確認してください。複数の顔がある場合、エンジンは最も大きい顔を選択します。出力解像度は 960×1280 (W×H) を超えません|< 10MB|jpg/jpeg/png| * エラーコード |エラーコード|説明| | ---- | ---- | |error_below_min_image_size |入力画像の解像度が小さすぎます| |error_exceed_max_image_size |入力画像の解像度が大きすぎます| --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI スタジオ写真 V3.0 | 画像 2 枚につき 1 ユニット * | > *画像数または動画の長さが割り切れない場合、ユニット数は切り上げられます。 --- - [歯ホワイトニング](https://docs.perfectcorp.com/ja/reference/ai_teeth_whitening.md): # 概要 **歯ホワイトニング API** 歯ホワイトニング API で、写真内の歯を明るくします。 ![](https://plugins-media.makeupar.com/smb/blog/post/2023-07-28/f05fda4d-8ca8-4661-b4b5-135067280a10.jpg) **写真内の黄ばんだ歯を除去する方法** **スマートホワイトニング** API は自動的に歯を検出し、ホワイトニング効果を適用します。 **調整可能なレベル** ホワイトニングの度合いを調整できます。 **主な機能** **迅速な強化** 数秒で歯を明るくします。 **正確な AI 検出** 歯のみが修正されます。 **調整可能なホワイトニング強度** ホワイトニングの強度を調整できます。 **自然な結果** 歯ホワイトニング API は、歯を識別してホワイトニング効果を適用します。強度を調整できます。 --- ## 統合ガイド * セルフィーを撮影する * 適切な照明の下でカメラに直接向かいます。 * JS Camera Kit を使用して写真をキャプチャします。 * ***/s2s/v2.0/file*** API を介してアップロード URL とファイル ID を取得する ファイル API レスポンスで返されたアップロード URL を使用して、以下のファイルをアップロードします。 * セルフィー写真 * AI タスク ***/s2s/v2.0/task/teeth-whiten*** を実行する 入力ソースとしてファイル ID または画像 URL を使用して AI タスクを実行します。効果パラメータを必要に応じて設定します。 * タスクステータスのポーリング 返された **task\_id** を使用してタスクの進捗を監視します。 **GET /s2s/v2.0/task/teeth-whiten/{task_id}** をポーリングしてエンジンのステータスを確認します。 タスクは完了するまで **“running”** 状態のままです。タスク実行中はユニットは消費されません。 * **使用例のデモ** ![](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) ## ファイル仕様とエラー * 対応フォーマットと寸法 |タイプ|対応寸法|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | |AI Teeth Whitening|セルフィー画像:
* 長辺 ≤ 1920 px
* 短辺 ≥ 320 px |< 10MB|jpg/png| * エラーコード |エラーコード|説明| | ---- | ---- | | error_exceed_max_image_size | 画像の長辺が 1920 ピクセルを超える場合 | |error_below_min_image_size|画像の幅または高さが 320 ピクセル未満の場合、使用するには小さすぎます| |error_face_position_invalid|画像内で顔全体が完全に可視であり、一部が切り取られていない必要があります| |error_face_position_too_small|写真内の顔が小さすぎて適切に分析できません| |error_face_position_out_of_boundary|顔が大きすぎるか、写真の端の一部が外れています| |error_insufficient_lighting|照明が暗すぎて分析が困難です| |error_face_angle_invalid|顔の角度が適切ではありません。正面を向いた撮影では、頭を正面から 10 度以内に保ってください。横を向いた撮影では、角度は 15 度以上である必要があります| * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON パーシング) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性用), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings 用), requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用), Jackson Databind >= 2.12.0 | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI Teeth Whitening V1.0 | 1 | --- - [AI 動画背景置換](https://docs.perfectcorp.com/ja/reference/ai_video_background_replace.md): # 概要 **AI 動画背景置換** ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Green_Screen_ddb7892393.png) AI 動画背景置換 API で、動画に任意の背景を追加できます。風景やカスタム画像などの背景から選択できます。 スタジオやグリーンスクリーンは不要です。動画の背景を置き換えます。 --- ## 統合ガイド **1. ソース動画と背景画像の準備** 出力は MP4 形式で、入力と同じ解像度、フレームレートは最大 30 フレーム/秒（入力がこの制限を超える場合は自動変換）、最大長は 600 秒（入力動画が長い場合は最初の 600 秒のみ保持）である必要があります。 背景画像は JPG または PNG 形式で、最大解像度は 4096 x 4096 ピクセル（長辺が 4096 ピクセル以下）、ファイルサイズは 10 メガバイト以下である必要があります。 **2. ファイルのアップロード** 以下のエンドポイントを通じて、アップロード URL とファイル ID をリクエストします。 ``` POST /s2s/v2.0/file ``` **3. AI タスクの実行** ``` POST /s2s/v2.0/task/bg-replace-vid ``` ファイル ID または画像 URL を入力として使用してタスクを送信します。レスポンスには、結果の追跡と取得に使用される task_id が返されます。 **4. タスク結果の取得** ``` GET /s2s/v2.0/task/bg-replace-vid/{task_id} ``` タスク ID を使用してステータスを追跡し、結果を取得します。 [Webhook](../develop/webhook.md) を設定すると、タスク完了時に成功またはエラーのステータスを含む非同期通知を受信できます。また、タスクエンドポイントを繰り返し呼び出して、ステータスが running から success または error に更新されるまでポーリングすることもできます。 料金は、タスクが正常に完了した場合にのみ課金されます。 --- ## ファイル仕様とエラー * 対応フォーマットと寸法 |AI 機能|対応寸法|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | | AI 動画背景置換 | 出力は MP4 形式で、入力と同じ解像度、フレームレートは最大 30 フレーム/秒（入力がこの制限を超える場合は自動変換）、最大長は 600 秒（入力動画が長い場合は最初の 600 秒のみ保持）である必要があります。
背景画像は JPG または PNG 形式で、最大解像度は 4096 x 4096 ピクセル（長辺が 4096 ピクセル以下）、ファイルサイズは 10 メガバイト以下である必要があります。 | 動画長制限: 600s
背景画像: <10MB | コンテナ: mp4
動画: MPEG-4, MPEG-4 AVC,
音声: aac, amr, mp3 | * エラーコード |エラーコード|説明| | ---- | ---- | | error_download_video | ソース動画のダウンロードに失敗しました | | error_decode_video | ソース動画のデコードに失敗しました | | error_unsupported_video | 対応していない動画形式です | | exceed_max_filesize | 入力ファイルサイズが最大制限を超えています | | error_nsfw_content_detected | ソースファイルで NSFW コンテンツが検出されました | | error_decode_mask | マスク画像のデコードに失敗しました | | invalid_parameter | パラメータ値が無効です | * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON パーシング) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch のため) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性のため), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings のため), requests >= 2.20.0 | | Java | Java 11+ (HttpClient のため), Jackson Databind >= 2.12.0 | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI 動画背景置換 V1.0 | 2 (1 秒) * | > *画像数または動画長が均等に割り切れない場合、ユニットは切り上げられます。 --- - [AI 動画高画質化](https://docs.perfectcorp.com/ja/reference/ai_video_enhancer.md): # 概要 AI 動画高画質化 API で、動画の品質を自動的に向上させます。ぼやけの修正、シャープネスの調整、明るさの最適化、低解像度映像のアップスケーリングを行います。 動画編集や機械学習の経験は不要です。ユーザー生成コンテンツ（UGC）を扱うアプリケーション、メディアプラットフォーム、マーケティングツール、コンテンツ自動化システムで使えます。 **主要機能** 1. ぼやけ補正 モーションブラーや曖昧なディテールを検出し、AI 強化モデルでよりシャープなフレームを再構築します。 2. シャープネス最適化 エッジやテクスチャを強化し、動画をくっきりとします。 3. 明るさと露出の調整 照明の不一致を自動的に補正し、視認性とカラーバランスを整えます。 4. AI アップスケーリング 480p などの低品質フォーマットを HD 品質にアップスケーリングします。ディテールを保持します。 5. 品質向上 ノイズリダクションとアーティファクト除去を適用します。 使用例: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_video_enhancer_S2_feature_video_03_S_0_10169a6902.jpg) --- ## ファイル仕様とエラー * 対応フォーマットと寸法 |AI 機能|対応寸法|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | | AI 動画高画質化 | 入力動画の長さは 60 秒以下、解像度は 2K 以下、フレームレートは 30fps 以下である必要があります。 | 長さ制限: 60s | コンテナ: mov, mp4
動画: MPEG-4, MPEG-4 AVC,
音声: aac, amr, mp3 | * エラーコード |エラーコード|説明| | ---- | ---- | | error_download_video | ソース動画のダウンロードに失敗しました | | error_decode_video | ソース動画のデコードに失敗しました | | error_unsupported_video | 対応していない動画形式です | | exceed_max_filesize | 入力ファイルサイズが最大制限を超えています| | error_nsfw_content_detected | ソースファイルで NSFW コンテンツが検出されました | | error_decode_mask | マスク画像のデコードに失敗しました | | invalid_parameter | パラメータ値が無効です| --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI 動画高画質化 V1.0 | 1 (2 秒) * | > *画像の枚数または動画の長さが割り切れない場合、ユニットは切り上げられます。 --- - [AI 動画顔入れ替え](https://docs.perfectcorp.com/ja/reference/ai_video_face_swap.md): # 概要 動画顔入れ替えは、YouCam の AI 動画顔入れ替え API で、動画内の人物の顔を別の人物の顔に置き換える AI 駆動のプロセスです。 高度な AI 技術により、AI 動画顔入れ替えは非常にリアルな結果を提供します。顔の表情、ライティング、肌色は細かく調整され、入れ替えた顔が元の映像とシームレスに融合するようにします。 > **備考:** この API は単一の顔を含む動画のみをサポートします。カスタマイズ可能なソリューションについては、[お問い合わせください](mailto:YouCamOnlineEditor_API@perfectcorp.com)。 使用例: ![](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) --- ## ファイル仕様とエラー * 対応フォーマットと寸法 |AI 機能|対応寸法|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | | AI 動画顔入れ替え | 入力動画は 30 秒、4K 解像度、または 30 FPS を超えてはならず、出力は長辺 1280 解像度、30 FPS、最大 30 秒に制限されます。 | 長さ制限: 30s | コンテナ: mov, mp4
動画: MPEG-4, MPEG-4 AVC,
音声: aac, amr, mp3 | * エラーコード |エラーコード|説明| | ---- | ---- | | error_download_video | ソース動画のダウンロードに失敗しました | | error_decode_video | ソース動画のデコードに失敗しました | | error_unsupported_video | 対応していない動画形式です | | exceed_max_filesize | 入力ファイルサイズが最大制限を超えています| | error_nsfw_content_detected | ソースファイルで NSFW コンテンツが検出されました | | error_decode_mask | マスク画像のデコードに失敗しました | | invalid_parameter | パラメータ値が無効です| --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI 動画顔入れ替え V1.0 | 1 (5 秒) * | > *画像数または動画の長さが割り切れない場合、ユニットは切り上げられます。 --- - [静止画を動画に](https://docs.perfectcorp.com/ja/reference/ai_video_generator.md): # 概要 YouCam AI 静止画を動画に は、テキストプロンプトと画像を動画に変換します。 AI 技術で、写真に動きの効果を付与します。 画像から AI 動画を作成するには、背景がクリーンで人物がはっきりと写っている写真を使用します。画像をアップロードすると、テキストプロンプトと写真が動画に変換されます。 ユースケース: ![](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) ## ファイル仕様とエラー * 対応フォーマットと寸法 |AI 機能|対応寸法|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | | V1.0 画像から動画へ (Standard) |入力: >= 300*300px、アスペクト比 1:2.5 ~ 2.5:1。出力: 最大 720p 30fps|入力: <10MB。出力: 5 秒または 10 秒|jpg/jpeg/png| | V1.0 画像から動画へ (Professional) |入力: >= 300*300px、アスペクト比 1:2.5 ~ 2.5:1。出力: 最大 1080p 30fps|入力: <10MB。出力: 5 秒または 10 秒|jpg/jpeg/png| | V2.0 画像から動画へ | 入力画像の長辺は 4096 ピクセル以下、アスペクト比は 1:2.5 から 2.5:1 の範囲である必要があります。
サポートされる出力解像度は 480p、720p、1080p です。入力画像の短辺が選択した解像度を超える場合、または長辺がターゲットサイズより小さい場合、短辺が選択した解像度に一致するように画像が自動的にリサイズされます。 |入力: <10MB。出力: 5 秒または 10 秒|jpg/jpeg/png| * エラーコード | エラーカテゴリー | シナリオ / 説明 | 推奨アクション | | -------------- | ---------------------- | ---------------- | | 無効なリクエストパラメータ | リクエストパラメータが無効または欠落しています | すべてのリクエストパラメータが正しいことを確認します | | | 無効なパラメータ値 (例: 不正なキーまたは不正な値) | レスポンスのエラーメッセージフィールドを確認し、リクエストパラメータを更新します | | | 無効なリクエストメソッド | API ドキュメントを確認し、正しい HTTP メソッドを使用します | | | リクエストされたリソースが存在しません (例: モデルが見つかりません) | レスポンスのエラーメッセージフィールドを参照し、リクエストパラメータを修正します| | トリガー戦略 | プラットフォームポリシーがトリガーされました | プラットフォームポリシーに違反していないか確認します | | | コンテンツセキュリティポリシーがトリガーされました | 入力コンテンツを確認・修正し、リクエストを再送信します | | | リクエストレートが高すぎます (レート制限超過)| リクエスト頻度を下げ、後で再試行するか、カスタマーサービスに連絡して制限を引き上げます | | | 同時実行または QPS がクォータを超えています | リクエスト頻度を下げるか、後で再試行します | | 内部エラー | 内部サーバーエラー | 後で再試行するか、カスタマーサービスに連絡します | | | サーバーが一時的に利用できません | 後で再試行するか、カスタマーサービスに連絡します | | | リクエスト滞留による内部タイムアウト| 後で再試行するか、カスタマーサービスに連絡します | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI 静止画を動画に (Standard) V1.0 | 3 (1 秒) * | | AI 静止画を動画に (Professional) V1.0 | 6 (1 秒) * | | AI 静止画を動画に (画像から動画へ) V2.0 | 1 ユニット (480p / 1 秒) *
2 ユニット (720p / 1 秒) *
3 ユニット (1080p / 1 秒) * | | AI 静止画を動画に (テキストから動画へ) V2.0 | 2 ユニット (720p / 1 秒) *
3 ユニット (1080p / 1 秒) * | > *画像数または動画の長さが割り切れない場合、ユニット数は切り上げられます。 --- - [AI 動画消しゴム](https://docs.perfectcorp.com/ja/reference/ai_video_object_removal.md): # 概要 **AI 動画消しゴム** ![](https://plugins-media.makeupar.com/smb/blog/post/2025-02-04/webp_537ec670-48c0-49fc-b96b-8073de21a64b.webp) AI 動画消しゴム API で、動画から不要な要素を除去できます。観光客で混雑した背景、散らかったデスク、ガラス表面の反射など、マスクした領域を除去します。 --- ## 統合ガイド **1. ソース動画とマスク画像の準備** 入力動画の長さは 60 秒以下である必要があり、出力動画の長辺は 1920 ピクセル以下、フレームレートは 30 フレーム/秒以下である必要があります。 **2. ファイルのアップロード** 以下のエンドポイントを通じて、アップロード URL とファイル ID を取得します。 ``` POST /s2s/v2.0/file ``` 入力動画: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_video_object_removal_input_edd43a2470.png) 参考入力マスク: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_video_object_removal_mask_4a1c9fb658.png) **3. AI タスクの実行** ``` POST /s2s/v2.0/task/obj-rem-vid ``` ファイル ID または画像 URL を入力としてタスクを送信します。レスポンスには、結果の追跡と取得に使用される task_id が返されます。 **4. タスク結果の取得** ``` GET /s2s/v2.0/task/obj-rem-vid/{task_id} ``` タスク ID を使用してステータスを追跡し、結果を取得します。 [Webhook](../develop/webhook.md) を設定すると、タスク完了時に成功またはエラーのステータスを含む非同期通知を受信できます。また、タスクエンドポイントを繰り返し呼び出して、ステータスが running から success または error に更新されるまでポーリングすることもできます。 課金は、タスクが正常に完了した場合にのみ発生します。 出力動画サンプル: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_video_object_removal_output_eb7670cd9e.png) --- ## ファイル仕様とエラー * 対応フォーマットと寸法 |AI 機能|対応寸法|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | | AI 動画消しゴム | 入力動画の長さは 60 秒以下である必要があり、出力動画の長辺は 1920 ピクセル以下、フレームレートは 30 フレーム/秒以下である必要があります。 | 長さ制限: 60s | コンテナ: mov, mp4
動画: MPEG-4, MPEG-4 AVC,
音声: aac, amr, mp3 | * エラーコード |エラーコード|説明| | ---- | ---- | | error_download_video | ソース動画のダウンロードに失敗しました | | error_decode_video | ソース動画のデコードに失敗しました | | error_unsupported_video | 対応していない動画形式です | | exceed_max_filesize | 入力ファイルサイズが最大制限を超えています | | error_nsfw_content_detected | ソースファイルで NSFW コンテンツが検出されました | | error_decode_mask | マスク画像のデコードに失敗しました | | invalid_parameter | パラメータ値が無効です | * 環境と依存関係 | サンプルコード言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON パーシング) | | Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4 (モダンな TLS/互換性用), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (f-strings 用), requests >= 2.20.0 | | Java | Java 11+ (HttpClient 用), Jackson Databind >= 2.12.0 | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI 動画消しゴム V2.1 | 2 (1 秒) * | > *画像数または動画の長さが均等に割り切れない場合、ユニットは切り上げられます。 --- - [動画をアニメ化](https://docs.perfectcorp.com/ja/reference/ai_video_style_transfer.md): # 概要 AI 動画フィルターとエフェクトで、動画にスタイルを適用できます。AI 動画フィルターにより、動画全体にスタイルを変換します。ポップアート、レトロ、アニメなど複数のスタイルから選択でき、すべてのフレームに適用されます。 使用例: ![](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) --- ## ファイル仕様とエラー * 対応フォーマットと解像度 |AI 機能|対応解像度|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | | 動画をアニメ化 | 入力動画は 30 秒、4K 解像度、30 FPS を超えてはならず、出力は長辺 1280 解像度、16 FPS、最大 30 秒に制限されます。 | 長さ制限：30 秒 | コンテナ：mov, mp4
動画：MPEG-4, MPEG-4 AVC,
音声：aac, amr, mp3 | * エラーコード |エラーコード|説明| | ---- | ---- | | error_download_video | ソース動画のダウンロードに失敗しました | | error_decode_video | ソース動画のデコードに失敗しました | | error_unsupported_video | 対応していない動画形式です | | exceed_max_filesize | 入力ファイルサイズが最大制限を超えています | | error_nsfw_content_detected | ソースファイルで NSFW コンテンツが検出されました | | error_decode_mask | マスク画像のデコードに失敗しました | | invalid_parameter | パラメータ値が無効です | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | AI 動画をアニメ化 V1.0 | 4 (1 秒) * | > *画像数または動画の長さが割り切れない場合、ユニットは切り上げられます。 --- - [ウォッチバーチャル試着](https://docs.perfectcorp.com/ja/reference/ai_watch.md): # 概要 AR ウォッチのバーチャル試着を作成します。2D 画像 1 枚でウォッチの試着プレビューを生成します。 ## 統合ガイド 本ガイドでは以下内容を説明します: * **エンドポイント:** `/s2s/v2.0/task/2d-vto/watch` * **認証:** すべてのリクエストに `Authorization: Bearer YOUR_API_KEY` が必要です * **ワークフロー:** 1. **手首の画像を準備する:** 画像をアップロードするか、手首の有効な画像 URL を提供します 1. **ウォッチの画像を準備する:** 画像をアップロードするか、ウォッチ製品の有効な画像 URL を提供します 1. **AI タスクを発行しタスク ID を取得する:** レスポンスから `task_id` を取得します。 1. **ステータスをポーリングする（`GET`）:** `task_id` を使用してタスクのステータスを確認します。`task_status` が `"success"` または `"error"` になるまでポーリングを続行してください。 --- * API プレイグラウンド API プレイグラウンドで API を対話的にテストします: **API プレイグラウンド:** [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/) --- * 認証 - リクエストヘッダーに **Bearer Token** を使用して API キーを含めます: ``` Authorization: Bearer YOUR_API_KEY ``` API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/. * 1. 画像のアップロード ファイルをサーバーに直接アップロードするか、VTO タスクペイロードに有効な画像 URL を提供できます。 * アップロードエンドポイント ``` POST /s2s/v2.0/file ``` すでにパブリックな画像 URL を持っている場合は、このステップをスキップできます。 File API のレスポンスで提供された URL にファイルを直接アップロードし、その後 File API が返した対応する `src_file_id` を使用して AI タスクを呼び出すことができます。または VTO タスクペイロードに有効な画像 URL を `src_file_url` として提供します。`src_file_id` または `src_file_url` がバーチャル試着の対象となります。 また、`src_file_id` または `src_file_url` に適用するウォッチ製品画像を参照として `ref_file_ids` または `ref_file_urls` で提供する必要があります。 AI エンジンでは、ウォッチ製品画像の自動背景透過に対応しています。ただし、手（`srcmsk_file_id` または `srcmsk_file_url`）またはウォッチ製品（`refmsk_file_ids` または `refmsk_file_urls`）のオクルージョンマスク画像ファイルを提供してセグメンテーションを微調整できます。 --- * 2. ウォッチ VTO タスクの作成と結果のポーリング 画像とテンプレート ID が揃ったら、タスクを作成します。API はリクエストを非同期で処理します。ステータスが `success` または `error` に達するまでタスクステータスをポーリングする必要があります。 * タスク作成エンドポイント ``` POST /s2s/v2.0/task/2d-vto/watch ``` * ポーリングエンドポイント ``` GET /s2s/v2.0/task/2d-vto/watch/{task_id} ``` --- ## ファイル仕様とエラー * ウォッチバーチャル試着の仕様 **サポートされるウォッチビュー** 文字盤が遮蔽されていない明瞭な前面ビューのウォッチ画像。ストラップはリアルな装着長さに見えるようにトリミングしてください。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/watch_product_01_aab8053028_50ab7fe9a5.jpg) **サポートされる手首ビュー** 手首の裏側が完全に、5 つの指がすべて明確に見え、オクルージョン（遮蔽）がない状態である必要があります。 ![](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)** 手首に沿った位置を示します: −0.3 は主要な手首関節に近いことを示します 1.0 は主要な手首関節から遠いことを示します デフォルト値: null（エンジンのデフォルトを使用） ![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)** 影の強さを制御します: 0.0 は影なしを示します 1.0 は最大限の影を示します デフォルト値: 0.15 **watch\_ambient\_light\_intensity: float (0.0 to 1.0)** ライティングがターゲットの手画像を参照する度合いを定義します: 0.0 は手画像のライティングを無視します 1.0 は手画像のライティングと影のレンダリングに完全に一致させます デフォルト値: 1.0 **ウォッチアンカーポイント: ピクセル座標の 4 点の配列（任意）** 最初の 2 点は、装着時のストラップの始まりと終わりをマークします。 残りの 2 点は、ウォッチケースの上端と下端をマークします。 ![watch_anchor_point](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Product_anchors_ece6851c88.jpg) --- * サポートされる形式と寸法 |AI 機能|サポートされる寸法|サポートされるファイルサイズ|サポートされる形式| | ---- | ---- | ---- | ---- | |ウォッチバーチャル試着|長辺 <= 4096 |< 10MB|jpg/jpeg/png| * エラーコード |エラーコード|説明| | ---- | ---- | | RUNTIME_ERROR | ウォッチランタイムで予期しないエラーが発生しました | | PHOTO_DETECTION_FAIL | ユーザー写真が正しく処理できませんでした（例: 手が検出されなかった） | | OBJECT_DETECTION_FAIL | オブジェクト写真が正しく処理できませんでした（例: 製品が検出されなかった） | | PHOTO_CHECK_INVALID | ユーザー写真のポーズまたはサイズが無効です | | INPUT_ERROR | 入力ファイルの形式が正しくありません | | INPUT_MAIN_IMAGE_EMPTY | ユーザー画像が必要です | * 環境と依存関係 | サンプルコードの言語/ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58（モダンな TLS/HTTP サポート）
- jq >= 1.6（堅牢な JSON パーシング） | | Node.js (JavaScript) | Node >= 18（グローバル fetch のため） | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4（モダンな TLS/互換性のため）、ext-curl（推奨）または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10（f-strings のため）、requests >= 2.20.0 | | Java | Java 11+（HttpClient のため）、Jackson Databind >= 2.12.0 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | ウォッチバーチャル試着 V1.0 | シングルアイテム着用で 1 ユニット | --- - [AIウォーターマーク除去](https://docs.perfectcorp.com/ja/reference/ai_watermark_removal.md) - [パーマスタイル](https://docs.perfectcorp.com/ja/reference/ai_wavy_hair.md): # 概要 パーマスタイルフィルターで、弾むようなカール、ゆるやかなウェーブ、大胆なカールスタイルなど、自宅にいながら数秒で新しいヘアスタイルを試せます。 ソフトなウェーブから大胆なアフロまで、精度とリアリズムの高さは他社と一線を画します。次のサロン訪問前に、自信を持って新しいヘアスタイルを試すための理想的なツールです。 ![](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) 撮影時の推奨事項: ![撮影時の推奨事項](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png "撮影時の推奨事項") --- ## ファイル仕様とエラー * 対応フォーマットとサイズ |AI 機能|対応サイズ|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | |パーマスタイル|長辺 <= 1024、顔幅 >= 128、顔の姿勢: -10 < pitch < +10, -45 < yaw < +45, -15 < roll < +15、単一の顔のみ、顔全体が写っている必要あり|< 10MB|jpg/jpeg/png| * エラーコード |エラーコード|説明| | ---- | ---- | |error_no_shoulder |ソース画像に肩が写っていません |error_large_face_angle |アップロードされた画像の顔の角度が大きすぎます |error_insufficient_landmarks |ソース画像で十分な顔または体のランドマークを検出できません |error_hair_too_short |入力された髪が短すぎます |error_face_pose |ソース画像の顔の姿勢はサポートされていません --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | パーマスタイル V1.0 | 1 | --- - [ファイル管理](https://docs.perfectcorp.com/ja/reference/file.md) - [バーチャルメイク](https://docs.perfectcorp.com/ja/reference/makeup_vto.md): # 概要 (Overview) AI Makeup API (バーチャルメイク) で、セルフィー画像にバーチャルメイクを適用します。 ファンデーション、チーク、アイシャドウ、リップなどのメイクをサポートしています。 **主な特徴：** * **3D 顔レンダリング：** 3D 顔 AI 技術でメイクをレンダリングします。 * **特許技術：** ディープラーニングアルゴリズムにより実現しています。 * **リアルタイムの精度：** さまざまな照明条件に適応する顔トラッキング。 * **製品色の再現：** 実在の製品の色、質感（マットからメタリックまで）、仕上げを再現します。 * 基本概念 * 色のブレンド ディープラーニングを用いて、実在のメイク製品の色を再現します。 * 質感と仕上げの再現 マットからメタリック、シマーからサテンまで、質感と仕上げをシミュレーションします。 * 光のバランス調整 画像の照明条件を検出します。画像を補正してメイクを適用します。 --- ## 統合ガイド (Integration Guide) Makeup Virtual Try-On サービスは非同期タスクとして動作します。まず、画像 URL と適用したいエフェクトのリストを指定して、メイク処理タスクを開始する必要があります。サーバーは `task_id` を返します。その後、ステータスを確認するエンドポイントを定期的にポーリングして、最終結果またはエラーを取得します。 * **エンドポイント：** `/v2.0/task/makeup-vto` * **認証：** すべてのリクエストには `Authorization: Bearer ` が必要です。 * **ワークフロー：** 1. **自撮り画像の準備：** 画像をアップロードするか、顔画像の既存のファイル URL を使用します。 1. **タスクの開始 (`POST`)：** 画像 ID/URL とメイク設定を送信します。 1. **タスク ID の取得：** レスポンスから `task_id` を取得します。 1. **ステータスのポーリング (`GET`)：** `task_id` を使用してタスクのステータスを確認します。`task_status` が `"success"` または `"error"` になるまでポーリングを継続します。 * API プレイグラウンド API プレイグラウンドで API を対話的にテストします： **API プレイグラウンド：** [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/) --- * 認証 - **Bearer Token** を使用して、リクエストヘッダーに API キーを含めます： ``` Authorization: Bearer ``` API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/. * 1. 自撮り画像のアップロード 元画像は次の 2 つの方法で提供できます： - **既存の公開画像 URL を使用する** アップロードの代わりに、AI タスクの開始時に公開アクセス可能な画像 URL を直接指定できます。 - **File API 経由でアップロードする** 次のエンドポイントを使用します： ``` POST /s2s/v2.0/file ``` これにより、後続のタスク実行に使用する `file_id` が返されます。 - ***重要***：File API を呼び出すだけではファイルはアップロードされません。**File API のレスポンスで提供される URL** に対して、**手動で**ファイルをアップロードする必要があります。その URL がアップロード先であるため、次に進む前にファイルが正常に転送されたことを確認してください。

AI API を呼び出す前に、ファイルが正常にアップロードされていることを確認してください。File API を使用してアップロード URL を取得し、その場所にファイルをアップロードします。アップロードが完了すると、レスポンスに ***file_id*** が返されます。この ID を使用して、そのファイルに関連する AI 機能にアクセスします。 > **警告：** File API のレスポンスで提供された URL にファイルをアップロードせずに AI API を使用すると、500 Server Error / unknown_internal_error または 404 Not Found エラーが発生します。 * 2. メイクタスクの開始 `POST /s2s/v2.0/task/makeup-vto` 指定された画像に対して新しいバーチャルメイクタスクを開始します。このエンドポイントは非同期であり、`task_id` を返します。 * リクエストヘッダー | ヘッダー | 値 | |--------|-------| | Content-Type | `application/json` | | Authorization | `Bearer YOUR_API_KEY` | * リクエストボディの例 ```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" } ``` * リクエストボディのスキーマ | フィールド | 型 | 説明 | |-------|------|---------| | `src_file_url` | string (URL) | 処理対象の自撮り画像への、公開アクセス可能な URL。 | | `effects` | array of Effect | 適用するメイクエフェクトオブジェクトの配列。詳細は [メークエフェクトのスキーマ](#makeup-effect-schemas) をご覧ください。 | | `version` | string | エフェクトペイロード構造の API バージョン。`"1.0"` を使用します。 | * 成功時のレスポンス (`200 OK`) タスク識別子を含む JSON オブジェクトを返します。 **レスポンスボディのスキーマ：** ```json { "status": 200, "data": { "task_id": "" } } ``` **レスポンスの例：** ```json { "status": 200, "data": { "task_id": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe" } } ``` * エラーレスポンス (`400 Bad Request`、`401 InvalidApiKey` など) 失敗を説明するメッセージを含む標準のエラーオブジェクトが返されます。 **エラーレスポンスの例：** ```json { "status": 400, "error": "The operation could not be completed", "error_code": "CreditInsufficiency" } ``` --- * 3. タスクのステータスと結果の取得 `GET /s2s/v2.0/task/makeup-vto/` 進行中または完了したタスクの現在のステータスと結果を取得します。 * リクエストヘッダー | ヘッダー | 値 | |--------|-------| | Authorization | `Bearer YOUR_API_KEY` | * パスパラメータ | パラメータ | 型 | 説明 | |-----------|------|---------| | task_id | string | タスク開始エンドポイントから返される識別子。 | * 成功時のレスポンス (`200 OK`) ステータスと、完了している場合は結果を含む JSON オブジェクト。 **レスポンスボディのスキーマ：** ```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' } } ``` **成功レスポンスの例：** ```json { "status": 200, "data": { "task_status": "success", "results": { "url": "https://s3.storage.prod/processed/image_123.jpg?token=..." } } } ``` **エンジンエラーレスポンスの例：** API クエリは正常に送信されましたが、AI タスクの実行中にエラーが発生しました。 ```json { "status": 200, "data": { "task_status": "error", "error": "exceed_max_filesize", "error_message": "string", } } ``` > 注意：クエリエラーでもエンジンエラーでも、エラーが発生した場合はユニットは消費されません。 **処理中レスポンスの例：** ```json { "status": 200, "data": { "task_status": "running" } } ``` * エラーレスポンス * `404 InvalidTaskId`：`task_id` が存在しないか、無効です。 * `401 InvalidApiKey`：API キーが無効か、指定されていません。 * `500 TaskTimeout`：タスクは正常に完了したか失敗したかのいずれかですが、保持期間を超過しています。 **クエリエラーレスポンスの例：** ```json { "status": 401, "error_code": "InvalidApiKey" } ``` > 注意：クエリエラーでもエンジンエラーでも、エラーが発生した場合はユニットは消費されません。 --- ## 入力と出力 * メイクアップエフェクトスキーマ このセクションでは、AI Makeup タスクのリクエストボディの完全な構造と制約について定義します。各エフェクトは、トップレベルの `effects` 配列内のオブジェクトです。 * エフェクトコンテナ（トップレベル） ```json { "version": "1.0", "effects": [] // array — Contains makeup effect objects } ``` * メイクアップエフェクトカテゴリ * `skin_smooth` ```json { "category": "skin_smooth", // string, const "skin_smooth" "skinSmoothStrength": 50, // integer, range: 0..100 "skinSmoothColorIntensity": 50 // integer, range: 0..100 } ``` > **注意!** ``skin_smooth`` エフェクトがリクエストに含まれていない場合、AI Makeup Engine は自動的に Skin Smooth の初期値 50 を適用します。 肌補正なしでメイクアップを適用したい場合は、``skinSmoothStrength`` と ``skinSmoothColorIntensity`` のすべてのパラメータを 0 に設定してください。ただし、最良の結果と最高品質のブレンドを得るには、初期値の肌補正を有効のままにすることをお勧めします。 * `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 } ] } ``` **パターンカタログ全体:** https://plugins-media.makeupar.com/wcm-saas/patterns/blush.json **固有のメイクアップパターンカテゴリ:** ```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 ] } ``` **パターンカタログ全体:** https://plugins-media.makeupar.com/wcm-saas/patterns/bronzer.json **固有のメイクアップパターンカテゴリ:** ```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 ] } ``` **パターンカタログ全体:** https://plugins-media.makeupar.com/wcm-saas/patterns/contour.json **固有のメイクアップパターンカテゴリ:** ```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" } ] } ``` **パターンカタログ全体:** https://plugins-media.makeupar.com/wcm-saas/patterns/eyebrows.json **固有のメイクアップパターンカテゴリ:** ```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 } ] } ``` **パターンカタログ全体:** https://plugins-media.makeupar.com/wcm-saas/patterns/eyeliner.json **固有のメイクアップパターンカテゴリ:** ```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) } ``` **パターンカタログ全体:** https://plugins-media.makeupar.com/wcm-saas/patterns/eyeshadow.json **固有のメイクアップパターンカテゴリ:** ```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 ] } ``` **パターンカタログ全体:** https://plugins-media.makeupar.com/wcm-saas/patterns/eyelashes.json **固有のメイクアップパターンカテゴリ:** ```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 } ] } ``` **パターンカタログ全体:** https://plugins-media.makeupar.com/wcm-saas/patterns/highlighter.json **固有のメイクアップパターンカテゴリ:** ```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" } } ``` **パターンカタログ全体:** https://plugins-media.makeupar.com/wcm-saas/shapes/lipshape.json **異なるメイクパターンのカテゴリ:** ```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 } ] } ``` **パターンの全カタログ:** https://plugins-media.makeupar.com/wcm-saas/patterns/lipliner.json **異なるメイクパターンのカテゴリ:** ```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": [] } ] ``` --- ## ペイロードの例 ここでは、複数の効果を適用した有効な `effectJson` ペイロードの完全な例を示します。 ```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 } ] } ] } ``` この例では、`blush` は `blush.json` の `2colors1` パターンを使用しており、これには正確に 2 つのパレットが必要です。`lip_color` 効果は `lipshape.json` の `plump` シェイプを使用しています。 ## ファイル仕様とエラー (File Specs & Errors) * 対応フォーマットとサイズ |AI 機能|対応サイズ|対応ファイルサイズ|対応フォーマット| | ---- | ---- | ---- | ---- | |バーチャルメイク (AI Makeup Virtual Try-On)|長辺 < 1920、顔の幅 >= 100|< 10MB|jpg/jpeg/png| * エラーコード |エラーコード|説明| | ---- | ---- | |error_below_min_image_size|ソース画像のサイズが最小値より小さくなっています（期待値: 幅 >= 100px、高さ >= 100px） |error_exceed_max_image_size|ソース画像のサイズが最大値より大きくなっています（期待値: 幅 < 1920px、高さ < 1080px） |error_face_position_invalid |顔全体が画像内に完全に写っていることを確認してください| |error_face_position_too_small|検出された顔が小さすぎます。カメラにもっと近づいてください| |error_face_position_out_of_boundary|顔が大きすぎるか、画像フレームの一部が外に出ています。位置を調整してください| |error_face_angle_invalid|顔の角度が正しくありません。正面を向いた写真では頭を 10° 以内に保ってください。横向きの写真では 15° 以上にしてください。| * 環境と依存関係 | サンプルコードの言語 / ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58（モダンな TLS/HTTP 対応）
- jq >= 1.6（堅牢な JSON パース） | | Node.js (JavaScript) | Node >= 18（グローバル fetch 用） | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4（モダンな TLS/互換性のため）、ext-curl（推奨）または allow_url_fopen=On + ext-openssl、ext-json | | Python | Python >= 3.10（f-string を使用するため）、requests >= 2.20.0 | | Java | Java 11+（HttpClient を使用するため）、Jackson Databind >= 2.12.0 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## ユニット消費 (Unit Consumption) | AI 機能 | 消費ユニット数 | |---|---| | バーチャルメイク V1.0 | 1 | --- - [YouCam API](https://docs.perfectcorp.com/ja/reference/openapi-base.md): YouCam API - [指輪バーチャル試着](https://docs.perfectcorp.com/ja/reference/ring_vto.md): # 概要 AR リングやエンゲージメントリングのバーチャル試着を作成します。2D 画像でリングの試着プレビューを生成します。 ## 統合ガイド 本ガイドでは以下内容を説明します: * **エンドポイント:** `/s2s/v2.0/task/2d-vto/ring` * **認証:** すべてのリクエストに `Authorization: Bearer YOUR_API_KEY` が必要です * **ワークフロー:** 1. **手の画像を準備する:** 画像をアップロードするか、手の有効な画像 URL を提供します 1. **リングの画像を準備する:** 画像をアップロードするか、リング製品の有効な画像 URL を提供します 1. **AI タスクを発行しタスク ID を取得する:** レスポンスから `task_id` を取得します。 1. **ステータスをポーリングする（`GET`）:** `task_id` を使用してタスクのステータスを確認します。`task_status` が `"success"` または `"error"` になるまでポーリングを続行してください。 --- * API プレイグラウンド API プレイグラウンドで API を対話的にテストします: **API プレイグラウンド:** [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/) --- * 認証 - リクエストヘッダーに **Bearer Token** を使用して API キーを含めます: ``` Authorization: Bearer YOUR_API_KEY ``` API キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/. * 1. 画像のアップロード ファイルをサーバーに直接アップロードするか、VTO タスクペイロードに有効な画像 URL を提供できます。 * アップロードエンドポイント ``` POST /s2s/v2.0/file ``` すでにパブリックな画像 URL を持っている場合は、このステップをスキップできます。 File API のレスポンスで提供された URL にファイルを直接アップロードし、その後 File API が返した対応する `src_file_id` を使用して AI タスクを呼び出すことができます。または VTO タスクペイロードに有効な画像 URL を `src_file_url` として提供します。`src_file_id` または `src_file_url` がバーチャル試着の対象となります。 また、`src_file_id` または `src_file_url` に適用するリング製品画像を参照として `ref_file_ids` または `ref_file_urls` で提供する必要があります。 AI エンジンでは、リング製品画像の自動背景透過に対応しています。ただし、手（`srcmsk_file_id` または `srcmsk_file_url`）またはリング製品（`refmsk_file_ids` または `refmsk_file_urls`）のオクルージョンマスク画像ファイルを提供してセグメンテーションを微調整できます。 --- * 2. リング VTO タスクの作成と結果のポーリング 画像とテンプレート ID が揃ったら、タスクを作成します。API はリクエストを非同期で処理します。ステータスが `success` または `error` に達するまでタスクステータスをポーリングする必要があります。 * タスク作成エンドポイント ``` POST /s2s/v2.0/task/2d-vto/ring ``` * ポーリングエンドポイント ``` GET /s2s/v2.0/task/2d-vto/ring/{task_id} ``` --- ## ファイル仕様とエラー * 指輪バーチャル試着の仕様 **サポートされるリングビュー** リング画像は四分之三前面ビュー（約 45 度）で提供する必要があります。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_product_01_9a4d0680f2_b46afe9a53.jpg) **サポートされる手のビュー** 手の甲が完全に、5 つの指がすべて明確に見え、オクルージョン（遮蔽）がない状態である必要があります。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_user_01_6d9893abd0_c7427cdb78.jpg) **ring\_wearing\_finger: integer (0–4)** リングを着用する指を指定します: 0 = 親指 1 = 人差し指 2 = 中指 3 = 薬指 4 = 小指 **ring\_wearing\_location: float (0.0–1.0)** 指に沿った位置を示します: 0.0 = MCP 関節（大きな関節）に近い 1.0 = PIP 関節（中央の関節）に近い ![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)** 影の強さを制御します: 0.0 = 影なし 1.0 = 最大限の影 デフォルト: 0.15 **ring\_ambient\_light\_intensity: float (0.0–1.0)** ライティングがターゲットの手画像を参照する度合いを定義します: 0.0 = 手画像のライティングを無視 1.0 = 手画像のライティングと影のレンダリングに完全に一致 デフォルト: 1.0 **リングアンカーポイント: ピクセル座標の 2 点の配列（任意）** リングが指に接する内側のエッジをマークし、左と右の点を指定します。幅広または厚みのあるリングには特に役立ちます。 このパラメータを提供しない場合、AI エンジンがアンカーポイントを自動的に検出します。 ![ring_anchor_point](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_anchor_point_e6eb241ef8.jpg) --- * サポートされる形式と寸法 |AI 機能|サポートされる寸法|サポートされるファイルサイズ|サポートされる形式| | ---- | ---- | ---- | ---- | |指輪バーチャル試着|長辺 <= 4096 |< 10MB|jpg/jpeg/png| * エラーコード |エラーコード|説明| | ---- | ---- | | RUNTIME_ERROR | ランタイムで予期しないエラーが発生しました | | PHOTO_DETECTION_FAIL | ユーザー写真が正しく処理できませんでした（例: 手が検出されなかった） | | OBJECT_DETECTION_FAIL | オブジェクト写真が正しく処理できませんでした（例: 製品が検出されなかった） | | PHOTO_CHECK_INVALID | ユーザー写真のポーズまたはサイズが無効です | | INPUT_ERROR | 入力ファイルの形式が正しくありません | | INPUT_MAIN_IMAGE_EMPTY | ユーザー画像が必要です | * 環境と依存関係 | サンプルコードの言語/ツール | 推奨ランタイムバージョン | |---|---| | cURL | - bash >= 3.2
- curl >= 7.58（モダンな TLS/HTTP サポート）
- jq >= 1.6（堅牢な JSON パーシング） | | Node.js (JavaScript) | Node >= 18（グローバル fetch のため） | | JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 | | PHP | PHP >= 7.4（モダンな TLS/互換性のため）、ext-curl（推奨）または allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10（f-strings のため）、requests >= 2.20.0 | | Java | Java 11+（HttpClient のため）、Jackson Databind >= 2.12.0 | --- ## JS Camera Kit {% partial file="/_partials/js-camera-kit.md" /%} --- ## ユニット消費 | AI 機能 | 消費ユニット | |---|---| | 指輪バーチャル試着 V1.0 | シングルアイテム着用で 1 ユニット
スタック着用で 2 ユニット | --- - [タスク管理](https://docs.perfectcorp.com/ja/reference/task_management.md) - [ユニットシステム](https://docs.perfectcorp.com/ja/reference/unit_system.md): ユニットの詳細と使用履歴を確認します。ユニットは YouCam API 操作で使用される通貨であり、異なる AI 機能によって消費されるユニットの量は異なります。本ドキュメントでは、ユニットのコード名として "Credit" を使用しています。