{ "openapi": "3.0.0", "info": { "title": "AI Skin Analysis", "description": "# Overview\n![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_demostore_skincarelive_topbanner.0cffe3a7.jpg)\nAI 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.\n\nThis 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.\n\n\n## Integration Guide\n* How to Take Photos for AI Skin Analysis\n* Take a selfie facing forward\n - 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.\n - 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.\n\n* Workflow\n**Skin Analysis API Usage Guide**\nThis guide explains how to upload an image and create a skin analysis task using the File API and AI Task API.\n\n * **Step 1: Resize your source image**
\n Resize your photo to fit the supported dimensions - up to 4096 pixels on the long side and at least 480 pixels on the short side for SD, or up to 4096 pixels on the long side and at least 1080 pixels on the short side for HD. See details in **[File Specs & Errors](#section/overview/File-Specs-and-Errors)**\n\n * **Step 2: Upload File Metadata via File API**\n- Image Requirements\n - See details in **[File Specs & Errors](#section/overview/File-Specs-and-Errors)**\n\nSend a POST request to initialise the file upload:\n\n```bash\ncurl --request POST \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/file \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"files\": [\n {\n \"content_type\": \"image/png\",\n \"file_name\": \"skin_analysis_01_3dbd1b6683.png\",\n \"file_size\": 547541\n }\n ]\n }'\n```\n\n- ***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.\n\n > **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.\n\n***\n\n * **Step 3: Retrieve Upload URL and File ID**\n\nThe response includes:\n\n* `requests.url` – Pre-signed URL for image upload.\n* `file_id` – Identifier for creating an AI task.\n\n**Example Response:**\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"files\": [\n {\n \"content_type\": \"image/png\",\n \"file_name\": \"skin_analysis_01_3dbd1b6683.png\",\n \"file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n \"requests\": [\n {\n \"method\": \"PUT\",\n \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\",\n \"headers\": {\n \"Content-Length\": \"547541\",\n \"Content-Type\": \"image/png\"\n }\n }\n ]\n }\n ]\n }\n}\n```\n\n***\n\n * **Step 4: Upload Image to Pre-signed URL**\n\nUse the provided `requests.url` and headers:\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n --header 'Content-Type: image/png' \\\n --header 'Content-Length: 547541' \\\n --data-binary @'./skin_analysis_01_3dbd1b6683.png'\n```\n\n***\n\n * **Step 5: Create AI Task**\n\nUse the `file_id` from Step 2 to create a skin analysis task:\n\n```bash\ncurl --request POST \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"src_file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n \"dst_actions\": [\"wrinkle\", \"pore\", \"texture\", \"acne\"],\n \"miniserver_args\": {\n \"enable_mask_overlay\": true,\n \"enable_dark_background_hd_pore\": true,\n \"color_dark_background_hd_pore\": \"3D3D3D\",\n \"opacity_dark_background_hd_pore\": 0.4\n // Additional parameters omitted for brevity\n },\n \"format\": \"json\"\n }'\n```\n 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)**.
\n Subsequently, calling POST 'task/skin-analysis' with the\n File ID or image file url executes the enhance task and obtains a ***task_id***.\n Please be advised that simultaneous use of SD and HD skin concern parameters is **NOT** supported.\n\n- **Use an Existing Public Image URL**\nInstead of uploading, you may supply a publicly accessible image URL directly when initiating the AI task.\n\n**Example Response:**\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"task_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT\"\n }\n}\n```\n\n***\n\n * **Step 6: Poll Task Status**\n\nRetrieve task results using the `task_id`:\n\n```bash\ncurl --request GET \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis/ \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'Content-Type: application/json'\n```\nThis ***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.\n\nProcessed results are retained for 24 hours after completion.- No need for short-interval polling.- Flexible polling intervals within the 24-hour window.\n\n > **Important:** Polling is still required to check task status, as execution time is not guaranteed.\n\nThe 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.\n\nYour 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.\nWhen 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.\n\n\n***\n\n * **Step 7: Interpret Results**\n\nThe response includes:\n\n* `ui_score` – User-friendly score.\n* `raw_score` – Raw analysis score.\n* `mask_urls` – URLs for detection masks.\n\n**Example Response:**\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"results\": {\n \"output\": [\n {\n \"type\": \"texture\",\n \"ui_score\": 68,\n \"raw_score\": 57.33,\n \"mask_urls\": [\"https://yce-us.s3-accelerate.amazonaws.com/...texture_output.jpg\"]\n },\n {\n \"type\": \"pore\",\n \"ui_score\": 92,\n \"raw_score\": 95.34,\n \"mask_urls\": [\"https://yce-us.s3-accelerate.amazonaws.com/...pore_output.jpg\"]\n }\n // Additional results omitted for brevity\n ]\n },\n \"task_status\": \"success\"\n }\n}\n```\n\n\n* Debugging Guide\n> **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.\n\n * If you mix using HD and SD skin concerns, you will get an error as following:\n ```json\n {\n \"status\": 400,\n \"error\": \"cannot mix HD and SD dst_actions\",\n \"error_code\": \"InvalidParameters\"\n }\n ```\n * If you misspell a skin concern or sending unknown skin concerns, you will get an error as following:\n ```json\n {\n \"status\": 400,\n \"error\": \"Not available dst_action abc123\",\n \"error_code\": \"InvalidParameters\"\n }\n ```\n\n---\n\n* Real-world examples:\n![](https://plugins-media.makeupar.com/webconsultation/images/skincare-widget/img_webcm_skincare_service_survey_demo.jpg)\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/skin_analysis_s5_poster_3_dt_85efe14952.png)\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Skincare_Pro_Medspa_Situation_Image_6aea6046f9.jpg)\n\n## Inputs & Outputs\n* Input Paramenter Description\nThere 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.\n\n* Default: enable_mask_overlay false\n ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/mask_overlay_false_1920_ea1cde0ead.png)\n\n* Set enable_mask_overlay to true\n ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/mask_overlay_1920_0fbb4786cc.png)\n\n----\n\n* Output ZIP Data Structure Description\nThe 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.\n\nThe 'score_info.json' file contains all the skin analysis detection results, with numerical scores and the names of the corresponding output mask files.\n\nThe 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.\n\n* File Structure in the Skin Analysis Result ZIP\n* HD Skincare ZIP\n * skinanalysisResult\n - score_info.json\n - hd_acne_output.png\n - hd_age_spot_output.png\n - hd_dark_circle_output.png\n - hd_droopy_lower_eyelid_output.png\n - hd_droopy_upper_eyelid_output.png\n - hd_eye_bag_output.png\n - hd_firmness_output.png\n - hd_moisture_output.png\n - hd_oiliness_output.png\n - hd_radiance_output.png\n - hd_redness_output.png\n - hd_texture_output.png\n - hd_pore_output_all.png\n - hd_pore_output_cheek.png\n - hd_pore_output_forehead.png\n - hd_pore_output_nose.png\n - hd_wrinkle_output_all.png\n - hd_wrinkle_output_crowfeet.png\n - hd_wrinkle_output_forehead.png\n - hd_wrinkle_output_glabellar.png\n - hd_wrinkle_output_marionette.png\n - hd_wrinkle_output_nasolabial.png\n - hd_wrinkle_output_periocular.png\n - hd_tear_trough.png\n - hd_skin_type.png\n\n* SD Skincare ZIP\n * skinanalysisResult\n - score_info.json\n - acne_output.png\n - age_spot_output.png\n - dark_circle_v2_output.png\n - droopy_lower_eyelid_output.png\n - droopy_upper_eyelid_output.png\n - eye_bag_output.png\n - firmness_output.png\n - moisture_output.png\n - oiliness_output.png\n - pore_output.png\n - radiance_output.png\n - redness_output.png\n - texture_output.png\n - wrinkle_output.png\n - tear_trough.png\n - skin_type.png\n\n* JSON Data Structure (score_info.json)\n * \"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.\n * \"skin_age\": AI-derived skin age relative to the general population distribution across all age groups.\n * Each category contains:\n * \"raw_score\": A floating-point value ranging from 1 to 100. A higher score indicates healthier and more aesthetically pleasing skin condition.\n * \"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.\n * \"output_mask_name\": The filename of the corresponding output mask image.\n\n * Categories and Descriptions\n * HD Skincare:\n * \"hd_redness\": Measures skin redness severity.\n * \"hd_oiliness\": Determines skin oiliness level.\n * \"hd_age_spot\": Detects age spots and pigmentation.\n * \"hd_radiance\": Evaluates skin radiance.\n * \"hd_moisture\": Assesses skin hydration levels.\n * \"hd_dark_circle\": Analyzes the presence of dark circles under the eyes.\n * \"hd_eye_bag\": Detects eye bags.\n * \"hd_droopy_upper_eyelid\": Measures upper eyelid drooping severity.\n * \"hd_droopy_lower_eyelid\": Measures lower eyelid drooping severity.\n * \"hd_firmness\": Evaluates skin firmness and elasticity.\n * \"hd_texture\": Subcategories[whole]; Analyzes overall skin texture.\n * \"hd_acne\": Subcategories[whole]; Detects acne presence.\n * \"hd_pore\": Subcategories[forehead, nose, cheek, whole]; Detects and evaluates pores in different facial regions.\n * \"hd_wrinkle\": Subcategories[forehead, glabellar, crowfeet, periocular, nasolabial, marionette, whole]; Measures the severity of wrinkles in various facial areas.\n * \"hd_tear_trough\": Detects tear trough.\n * \"hd_skin_type\": Subcategories[whole, t_zone, u_zone] Evalutate skin type of Normal, Oily, Dry, Combination, Redness, Dry & Redness, Oily & Redness, Combination & Redness.\n\n * SD Skincare:\n * \"wrinkle\": General wrinkle analysis.\n * \"droopy_upper_eyelid\": Measures upper eyelid drooping severity.\n * \"droopy_lower_eyelid\": Measures lower eyelid drooping severity.\n * \"firmness\": Evaluates skin firmness and elasticity.\n * \"acne\": Evaluates acne presence.\n * \"moisture\": Measures skin hydration.\n * \"eye_bag\": Detects eye bags.\n * \"dark_circle_v2\": Analyzes dark circles using an alternative method.\n * \"age_spot\": Detects age spots.\n * \"radiance\": Evaluates skin brightness.\n * \"redness\": Measures skin redness.\n * \"oiliness\": Determines skin oiliness.\n * \"pore\": Measures pore visibility.\n * \"texture\": Analyzes overall skin texture.\n * \"tear_trough\": Detects tear trough.\n * \"skin_type\": Subcategories[whole, t_zone, u_zone] Evaluates skin type of Normal, Oily, Dry, Combination, Redness, Dry & Redness, Oily & Redness, Combination & Redness.\n\n * Sample score_info.json of HD Skincare\n ```json\n {\n \"hd_redness\": {\n \"raw_score\": 72.011962890625,\n \"ui_score\": 77,\n \"output_mask_name\": \"hd_redness_output.png\"\n },\n \"hd_oiliness\": {\n \"raw_score\": 60.74365234375,\n \"ui_score\": 72,\n \"output_mask_name\": \"hd_oiliness_output.png\"\n },\n \"hd_age_spot\": {\n \"raw_score\": 83.23274230957031,\n \"ui_score\": 77,\n \"output_mask_name\": \"hd_age_spot_output.png\"\n },\n \"hd_radiance\": {\n \"raw_score\": 76.57244205474854,\n \"ui_score\": 79,\n \"output_mask_name\": \"hd_radiance_output.png\"\n },\n \"hd_moisture\": {\n \"raw_score\": 48.694559931755066,\n \"ui_score\": 70,\n \"output_mask_name\": \"hd_moisture_output.png\"\n },\n \"hd_dark_circle\": {\n \"raw_score\": 80.1993191242218,\n \"ui_score\": 76,\n \"output_mask_name\": \"hd_dark_circle_output.png\"\n },\n \"hd_eye_bag\": {\n \"raw_score\": 76.67280435562134,\n \"ui_score\": 79,\n \"output_mask_name\": \"hd_eye_bag_output.png\"\n },\n \"hd_droopy_upper_eyelid\": {\n \"raw_score\": 79.05348539352417,\n \"ui_score\": 80,\n \"output_mask_name\": \"hd_droopy_upper_eyelid_output.png\"\n },\n \"hd_droopy_lower_eyelid\": {\n \"raw_score\": 79.97175455093384,\n \"ui_score\": 81,\n \"output_mask_name\": \"hd_droopy_lower_eyelid_output.png\"\n },\n \"hd_firmness\": {\n \"raw_score\": 89.66898322105408,\n \"ui_score\": 85,\n \"output_mask_name\": \"hd_firmness_output.png\"\n },\n \"hd_texture\": {\n \"whole\": {\n \"raw_score\": 66.3921568627451,\n \"ui_score\": 75,\n \"output_mask_name\": \"hd_texture_output.png\"\n }\n },\n \"hd_acne\": {\n \"whole\": {\n \"raw_score\": 59.92677688598633,\n \"ui_score\": 76,\n \"output_mask_name\": \"hd_acne_output.png\"\n }\n },\n \"hd_pore\": {\n \"forehead\": {\n \"raw_score\": 79.59770965576172,\n \"ui_score\": 80,\n \"output_mask_name\": \"hd_pore_output_forehead.png\"\n },\n \"nose\": {\n \"raw_score\": 29.139814376831055,\n \"ui_score\": 58,\n \"output_mask_name\": \"hd_pore_output_nose.png\"\n },\n \"cheek\": {\n \"raw_score\": 44.11081314086914,\n \"ui_score\": 65,\n \"output_mask_name\": \"hd_pore_output_cheek.png\"\n },\n \"whole\": {\n \"raw_score\": 49.23978805541992,\n \"ui_score\": 67,\n \"output_mask_name\": \"hd_pore_output_all.png\"\n }\n },\n \"hd_wrinkle\": {\n \"forehead\": {\n \"raw_score\": 55.96956729888916,\n \"ui_score\": 67,\n \"output_mask_name\": \"hd_wrinkle_output_forehead.png\"\n },\n \"glabellar\": {\n \"raw_score\": 76.7251181602478,\n \"ui_score\": 75,\n \"output_mask_name\": \"hd_wrinkle_output_glabellar.png\"\n },\n \"crowfeet\": {\n \"raw_score\": 83.4361481666565,\n \"ui_score\": 78,\n \"output_mask_name\": \"hd_wrinkle_output_crowfeet.png\"\n },\n \"periocular\": {\n \"raw_score\": 67.88706302642822,\n \"ui_score\": 72,\n \"output_mask_name\": \"hd_wrinkle_output_periocular.png\"\n },\n \"nasolabial\": {\n \"raw_score\": 74.03312683105469,\n \"ui_score\": 74,\n \"output_mask_name\": \"hd_wrinkle_output_nasolabial.png\"\n },\n \"marionette\": {\n \"raw_score\": 71.94477319717407,\n \"ui_score\": 73,\n \"output_mask_name\": \"hd_wrinkle_output_marionette.png\"\n },\n \"whole\": {\n \"raw_score\": 49.64699745178223,\n \"ui_score\": 65,\n \"output_mask_name\": \"hd_wrinkle_output_all.png\"\n }\n },\n \"all\": {\n \"score\": 75.75757575757575\n },\n \"skin_age\": 37\n }\n ```\n * Sample score_info.json of SD Skincare\n ```json\n {\n \"wrinkle\": {\n \"raw_score\": 36.09360456466675,\n \"ui_score\": 60,\n \"output_mask_name\": \"wrinkle_output.png\"\n },\n \"droopy_upper_eyelid\": {\n \"raw_score\": 79.05348539352417,\n \"ui_score\": 80,\n \"output_mask_name\": \"droopy_upper_eyelid_output.png\"\n },\n \"droopy_lower_eyelid\": {\n \"raw_score\": 79.97175455093384,\n \"ui_score\": 81,\n \"output_mask_name\": \"droopy_lower_eyelid_output.png\"\n },\n \"firmness\": {\n \"raw_score\": 89.66898322105408,\n \"ui_score\": 85,\n \"output_mask_name\": \"firmness_output.png\"\n },\n \"acne\": {\n \"raw_score\": 92.29713000000001,\n \"ui_score\": 88,\n \"output_mask_name\": \"acne_output.png\"\n },\n \"moisture\": {\n \"raw_score\": 48.694559931755066,\n \"ui_score\": 70,\n \"output_mask_name\": \"moisture_output.png\"\n },\n \"eye_bag\": {\n \"raw_score\": 76.67280435562134,\n \"ui_score\": 79,\n \"output_mask_name\": \"eye_bag_output.png\"\n },\n \"dark_circle_v2\": {\n \"raw_score\": 80.1993191242218,\n \"ui_score\": 76,\n \"output_mask_name\": \"dark_circle_v2_output.png\"\n },\n \"age_spot\": {\n \"raw_score\": 83.23274230957031,\n \"ui_score\": 77,\n \"output_mask_name\": \"age_spot_output.png\"\n },\n \"radiance\": {\n \"raw_score\": 76.57244205474854,\n \"ui_score\": 79,\n \"output_mask_name\": \"radiance_output.png\"\n },\n \"redness\": {\n \"raw_score\": 72.011962890625,\n \"ui_score\": 77,\n \"output_mask_name\": \"redness_output.png\"\n },\n \"oiliness\": {\n \"raw_score\": 60.74365234375,\n \"ui_score\": 72,\n \"output_mask_name\": \"oiliness_output.png\"\n },\n \"pore\": {\n \"raw_score\": 88.38014125823975,\n \"ui_score\": 84,\n \"output_mask_name\": \"pore_output.png\"\n },\n \"texture\": {\n \"raw_score\": 80.09742498397827,\n \"ui_score\": 76,\n \"output_mask_name\": \"texture_output.png\"\n },\n \"all\": {\n \"score\": 75.75757575757575\n },\n \"skin_age\": 37\n }\n ```\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n| AI Feature | Supported Dimensions | Supported File Size | Supported Formats |\n| ---- | ---- | ---- | ---- |\n| 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 |\n| 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 |\n\n> **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.\n\n* Suggestions for How to Shoot:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png)\n\n* Get Ready to Start Skin Analysis Instructions\n* Take off your glasses and make sure bangs are not covering your forehead\n* Make sure that you’re in a well-lit environment\n* Remove makeup to get more accurate results\n* Look straight into the camera and keep your face in the center\n\n* Photo requirement\nWe 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.\n\nYou 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.\n> **Warning:** The width of the face needs to be greater than 60% of the width of the image.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_error_src_face_too_small_cr_725792a7fb.png)\n\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n|error_below_min_image_size|Input image resolution is too small|\n|error_exceed_max_image_size|Input image resolution is too large|\n|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.|\n|error_src_face_out_of_bound|The face area in the uploaded image is out of bound|\n|error_lighting_dark|The lighting in the uploaded image is too dark|\n\n* Environment & Dependency\n\n| Sample Code Language / Tool | Recommended Runtime Versions |\n|---|---|\n| cURL | - bash >= 3.2
- curl >= 7.58 (modern TLS/HTTP support)
- jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 |\n| PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) or allow_url_fopen=On + ext-openssl, ext-json |\n| Python | Python >= 3.10 (for f-strings), requests >= 2.20.0 |\n| Java | Java 11+ (for HttpClient), Jackson Databind >= 2.12.0 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## Mobile Camera Kit\n{% partial file=\"/_partials/mobile-camera-kit.md\" /%}\n\n---\n\n## Unit Consumption\n\n* AI Skin Analysis (V2.0, 2.1)\n\n| AI Feature | Unit Consumed |\n|---|---|\n| 1~4 concerns analysis | 9 units for SD; 12 units for HD | \n| 5~8 concerns analysis | 12 units for SD; 16 units for HD |\n| 9~12 concerns analysis | 14 units for SD; 20 units for HD |\n| 13~16 concerns analysis | 16 units for SD; 22 units for HD |\n\n---\n", "version": "", "termsOfService": "https://www.makeupar.com/perfectbeauty/youcam/terms-of-service-api", "contact": { "email": "YouCamOnlineEditor_API@perfectcorp.com" }, "license": { "name": "Privacy policy", "url": "https://www.makeupar.com/perfectbeauty/youcam/privacy-policy-api" } }, "servers": [ { "url": "https://yce-api-01.makeupar.com" } ], "tags": [ { "name": "V2.1", "description": "Skin Analysis API v2.1 introduces updated AI engines and increases the maximum skincare output resolution up to 2560 pixels, with automatic input resizing." }, { "name": "V2.0", "description": "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." } ], "paths": { "/s2s/v2.0/task/skin-analysis": { "post": { "summary": "Run a Skin Analysis task.", "description": "AI tasks are asynchronous. Prefer webhook-based completion handling when the feature supports webhooks. Configure your webhook endpoint, verify webhook signatures, and use the received `task_id` to query the task result after a `success` or `error` notification. See the [webhook integration guide](/develop/webhook.md) for setup and verification details.\n\nIf webhooks are not supported or cannot be used in your integration, implement polling. After submitting an AI task, poll the status endpoint at regular intervals (e.g., every 10 seconds) until the task status is `success` or `error`.\n", "tags": [ "V2.0" ], "security": [ { "BearerAuthenticationV2": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunSkincareTaskV2" } } } }, "responses": { "200": { "description": "Successful execution of Skin Analysis task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicRunTaskResponseV2" } } } }, "400": { "$ref": "#/components/responses/RunError" }, "401": { "$ref": "#/components/responses/InvalidApiKey" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/s2s/v2.0/task/skin-analysis/{task_id}": { "get": { "summary": "Check a Skin Analysis task status.", "description": "AI tasks are asynchronous. Prefer webhook-based completion handling when the feature supports webhooks. Configure your webhook endpoint, verify webhook signatures, and use the received `task_id` to query the task result after a `success` or `error` notification. See the [webhook integration guide](/develop/webhook.md) for setup and verification details.\n\nIf webhooks are not supported or cannot be used in your integration, implement polling. After submitting an AI task, poll the status endpoint at regular intervals (e.g., every 10 seconds) until the task status is `success` or `error`.\n", "tags": [ "V2.0" ], "security": [ { "BearerAuthenticationV2": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe" }, "description": "ID of task to check" } ], "responses": { "200": { "$ref": "#/components/responses/SkinAnalysisResponse" }, "400": { "$ref": "#/components/responses/InvalidTaskId" }, "401": { "$ref": "#/components/responses/InvalidApiKey" }, "500": { "$ref": "#/components/responses/TaskTimeout" } } } }, "/s2s/v2.1/task/skin-analysis": { "post": { "summary": "Run a Skin Analysis V2.1 task.", "description": "AI tasks are asynchronous. Prefer webhook-based completion handling when the feature supports webhooks. Configure your webhook endpoint, verify webhook signatures, and use the received `task_id` to query the task result after a `success` or `error` notification. See the [webhook integration guide](/develop/webhook.md) for setup and verification details.\n\nIf webhooks are not supported or cannot be used in your integration, implement polling. After submitting an AI task, poll the status endpoint at regular intervals (e.g., every 10 seconds) until the task status is `success` or `error`.\n", "tags": [ "V2.1" ], "security": [ { "BearerAuthenticationV2": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/RunSkincareTaskV2" }, { "type": "object", "properties": { "pf_camera_kit": { "type": "boolean", "example": true } } } ] } } } }, "responses": { "200": { "description": "Successful execution of Skin Analysis task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicRunTaskResponseV2" } } } }, "400": { "$ref": "#/components/responses/RunError" }, "401": { "$ref": "#/components/responses/InvalidApiKey" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/s2s/v2.1/task/skin-analysis/{task_id}": { "get": { "summary": "Check a Skin Analysis V2.1 task status.", "description": "AI tasks are asynchronous. Prefer webhook-based completion handling when the feature supports webhooks. Configure your webhook endpoint, verify webhook signatures, and use the received `task_id` to query the task result after a `success` or `error` notification. See the [webhook integration guide](/develop/webhook.md) for setup and verification details.\n\nIf webhooks are not supported or cannot be used in your integration, implement polling. After submitting an AI task, poll the status endpoint at regular intervals (e.g., every 10 seconds) until the task status is `success` or `error`.\n", "tags": [ "V2.1" ], "security": [ { "BearerAuthenticationV2": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe" }, "description": "ID of task to check" } ], "responses": { "200": { "$ref": "#/components/responses/SkinAnalysisResponse" }, "400": { "$ref": "#/components/responses/InvalidTaskId" }, "401": { "$ref": "#/components/responses/InvalidApiKey" }, "500": { "$ref": "#/components/responses/TaskTimeout" } } } } }, "components": { "securitySchemes": { "BearerAuthenticationV2": { "type": "http", "scheme": "bearer", "description": "Use the standard 'Bearer authentication'. Put your 'API Key' in header: `Authorization:Bearer YOUR_API_KEY`. Notice that there is ' ' a space between 'Bearer' and the 'YOUR_API_KEY'." } }, "schemas": { "RunSkincareTaskV2": { "allOf": [ { "$ref": "#/components/schemas/BasicRunTaskV2" }, { "title": "RunSkincareTaskV2", "description": "This object represents a run Skin Analysis task.", "type": "object", "properties": { "dst_actions": { "$ref": "#/components/schemas/RunSkincareTaskDstActions" }, "miniserver_args": { "$ref": "#/components/schemas/RunSkincareTaskMiniserverArgs" }, "format": { "type": "string", "enum": [ "json", "zip" ], "description": "Response format of the analysis results. Default is 'zip'. - `zip`: Results will be packaged as a downloadable ZIP file containing a skinanalysisResult folder with score_info.json and all detection result images. The response will include a URL to download the ZIP file. - `json`: Results will be returned directly in the response body as JSON format. Note: The response schema differs between format=json and format=zip.\n", "example": "zip" } }, "required": [ "dst_actions" ] } ] }, "RunSkincareTaskDstActions": { "type": "array", "description": "The actions for Skin Analysis.\nThere are 2 types of features: HD and SD.\nYou can choose one or more features, either all in SD or all in HD.\nNote: HD and SD features cannot be mixed.\nHD features:\n - hd_redness: Measures skin redness severity.\n - hd_oiliness: Determines skin oiliness level.\n - hd_age_spot: Detects age spots and pigmentation.\n - hd_radiance: Evaluates skin radiance.\n - hd_moisture: Assesses skin hydration levels.\n - hd_dark_circle: Analyzes the presence of dark circles under the eyes.\n - hd_eye_bag: Detects eye bags.\n - hd_droopy_upper_eyelid: Measures upper eyelid drooping severity.\n - hd_droopy_lower_eyelid: Measures lower eyelid drooping severity.\n - hd_firmness: Evaluates skin firmness and elasticity.\n - hd_texture: Analyzes overall skin texture.\n - hd_acne: Detects acne presence.\n - hd_pore: Detects and evaluates pores in different facial regions (forehead, nose, cheek, whole).\n - hd_wrinkle: Measures the severity of wrinkles in various facial areas (forehead, glabellar, crowfeet, periocular, nasolabial, marionette, whole).\n - hd_tear_trough: Detects tear trough.\n - hd_skin_type: Subcategories (whole, T-zone, U-zone) evaluate skin type as Normal, Oily, Dry, Combination, Redness, Dry and Redness, Oily and Redness, or Combination and Redness.\n\nSD features:\n - wrinkle: General wrinkle analysis.\n - droopy_upper_eyelid: Measures upper eyelid drooping severity.\n - droopy_lower_eyelid: Measures lower eyelid drooping severity.\n - firmness: Evaluates skin firmness and elasticity.\n - acne: Evaluates acne presence.\n - moisture: Measures skin hydration.\n - eye_bag: Detects eye bags.\n - dark_circle_v2: Analyzes dark circles.\n - age_spot: Detects age spots.\n - radiance: Evaluates skin brightness.\n - redness: Measures skin redness.\n - oiliness: Determines skin oiliness.\n - pore: Measures pore visibility.\n - texture: Analyzes overall skin texture.\n - tear_trough: Detects tear trough.\n - skin_type: Subcategories (whole, T-zone, U-zone) evaluate skin type as Normal, Oily, Dry, Combination, Redness, Dry and Redness, Oily and Redness, or Combination and Redness.\n", "items": { "type": "string", "enum": [ "hd_wrinkle", "hd_pore", "hd_texture", "hd_acne", "hd_oiliness", "hd_radiance", "hd_eye_bag", "hd_age_spot", "hd_dark_circle", "hd_droopy_upper_eyelid", "hd_droopy_lower_eyelid", "hd_firmness", "hd_moisture", "hd_redness", "hd_tear_trough", "hd_skin_type", "wrinkle", "pore", "texture", "acne", "oiliness", "radiance", "eye_bag", "age_spot", "dark_circle_v2", "droopy_upper_eyelid", "droopy_lower_eyelid", "firmness", "moisture", "redness", "tear_trough", "skin_type" ] }, "example": [ "hd_wrinkle", "hd_pore", "hd_texture", "hd_acne" ] }, "RunSkincareTaskMiniserverArgs": { "type": "object", "properties": { "enable_mask_overlay": { "type": "boolean", "description": "Controls whether the mask is blended onto the image. True returns the overlaid image as a .jpg. False returns the raw mask as a .png. Default is false.
All output images are limited to a maximum long-side resolution of 2560 pixels. If enable_mask_overlay is not enabled, you must verify whether the input resolution exceeds 2560 and handle the mask overlay accordingly on your side. When the input image has a long side below 2560 pixels, use the original image resolution. Otherwise, use 2560 pixels to configure your display." }, "enable_dark_background_hd_pore": { "type": "boolean", "description": "Enable dark background for HD pore visualization" }, "color_dark_background_hd_pore": { "type": "string", "description": "Color for HD pore dark background visualization (hex format)", "example": "3D3D3D" }, "opacity_dark_background_hd_pore": { "type": "number", "minimum": 0, "maximum": 1, "description": "Opacity for HD pore dark background visualization", "example": 0.4 }, "enable_dark_background_hd_wrinkle": { "type": "boolean", "description": "Enable dark background for HD wrinkle visualization" }, "color_dark_background_hd_wrinkle": { "type": "string", "description": "Color for HD wrinkle dark background visualization (hex format)", "example": "3D3D3D" }, "opacity_dark_background_hd_wrinkle": { "type": "number", "minimum": 0, "maximum": 1, "description": "Opacity for HD wrinkle dark background visualization", "example": 0.4 } } }, "SkinAnalysisResponseV2": { "description": "RE", "type": "object", "properties": { "status": { "type": "integer", "description": "Response status", "example": 200 }, "data": { "type": "object", "properties": { "task_status": { "type": "string", "enum": [ "running", "success", "error" ], "description": "Status of this task" }, "error": { "$ref": "#/components/schemas/EngineErrorCode" }, "error_message": { "type": "string", "description": "Detailed description of error" }, "results": { "oneOf": [ { "$ref": "#/components/schemas/SkinAnalysisResultsV2Zip" }, { "$ref": "#/components/schemas/SkinAnalysisResultsV2Json" } ] } } } } }, "SkinAnalysisResultsV2Zip": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "URL to download this result. Valid for 2 hours. The returned ZIP file contains a skinanalysisResult folder of a score_info.json file with all detection result scores and images of all detection results. Only available when format is `zip`.", "example": "https://example.com/sample-result-url" } } }, "SkinAnalysisResultsV2Json": { "type": "object", "required": [ "output" ], "properties": { "output": { "type": "array", "description": "The analysis result returned directly in the response body as JSON format. Only available when format is `json`.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The action of Skin Analysis", "example": "hd_skin_type" }, "region": { "type": "string", "description": "The region of the face where the analysis is focused", "example": "whole" }, "raw_score": { "type": "number", "description": "A floating-point value ranging from 1 to 100. The raw_score refers to the score directly predicted by the AI model", "example": 98.5 }, "ui_score": { "type": "integer", "description": "An integer ranging from 1 to 100. The ui_score is the adjusted score based on the raw score", "example": 97 }, "score": { "type": "number", "description": "A floating-point value between 1 and 100 representing the general skin condition.", "example": 97.66 }, "mask_urls": { "type": "array", "description": "The URLs of the mask images or resized images generated during analysis", "items": { "type": "string", "example": "https://example.com/mask_image_1.png" } } } } } } }, "BasicRunTaskV2SrcFileUrl": { "type": "object", "required": [ "src_file_url" ], "properties": { "src_file_url": { "type": "string", "description": "Url of the file to run task. The url should be publicly accessible.", "example": "https://example.com/selfie.jpg" } } }, "BasicRunTaskV2SrcFileId": { "type": "object", "required": [ "src_file_id" ], "properties": { "src_file_id": { "type": "string", "description": "ID of file to run task. File ID from upload file API.", "example": "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=" } } }, "BasicRunTaskV2": { "title": "BasicRunTaskV2", "anyOf": [ { "title": "Run task with src file url", "allOf": [ { "$ref": "#/components/schemas/BasicRunTaskV2SrcFileUrl" } ] }, { "title": "Run task with src file ID", "allOf": [ { "$ref": "#/components/schemas/BasicRunTaskV2SrcFileId" } ] } ] }, "BasicRunTaskResponseV2": { "type": "object", "properties": { "status": { "type": "integer", "description": "Response status", "example": 200 }, "data": { "type": "object", "properties": { "task_id": { "type": "string", "description": "ID of this task. Task result is valid to query by this ID for 24 hours.", "example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe" } } } } }, "EngineErrorCode": { "type": "string", "nullable": true, "enum": [ "error_exceed_max_image_size", "exceed_max_filesize", "invalid_parameter", "error_download_image", "error_download_mask", "error_decode_image", "error_decode_mask", "error_nsfw_content_detected", "error_no_face", "error_pose", "error_face_parsing", "error_inference", "exceed_nsfw_retry_limits", "error_upload", "unknown_internal_error" ], "description": "Errors:\n- \\`error_exceed_max_image_size\\` - Input image size exceeds the maximum limit\n- \\`exceed_max_filesize\\` - Input file size exceeds the maximum limit\n- \\`invalid_parameter\\` - Invalid parameter value\n- \\`error_download_image\\` - Download source image error\n- \\`error_download_mask\\` - Download mask image error\n- \\`error_decode_image\\` - Decode source image error\n- \\`error_decode_mask\\` - Decode mask image error\n- \\`error_nsfw_content_detected\\` - NSFW content detected in source image\n- \\`error_no_face\\` - No face detected on source image\n- \\`error_pose\\` - Failed to detect pose on source image\n- \\`error_face_parsing\\` - Failed to do face segmentation on source image\n- \\`error_inference\\` - Inference pipeline error\n- \\`exceed_nsfw_retry_limits\\` - Exceed the retry limits to avoid generated NSFW image\n- \\`error_upload\\` - Upload result image error\n- \\`unknown_internal_error\\` - Others\n" } }, "responses": { "SkinAnalysisResponse": { "description": "Successful check of Skin Analysis task status", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SkinAnalysisResponseV2" } ] }, "examples": { "format_zip_success": { "summary": "Response when format=zip (success)", "description": "Task completed successfully. Results are packaged as a ZIP file.", "value": { "status": 200, "data": { "task_status": "success", "results": "https://example.com/sample-result-url" } } }, "format_json_success": { "summary": "Response when format=json (success)", "description": "Task completed successfully. Results are returned directly as JSON with detailed scores and image URLs.", "value": { "status": 200, "data": { "task_status": "success", "results": { "output": [ { "type": "hd_wrinkle", "region": "whole", "raw_score": 25.3, "ui_score": 25, "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_wrinkle_whole.jpg" ] }, { "type": "hd_wrinkle", "region": "forehead", "raw_score": 20.1, "ui_score": 20, "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_wrinkle_forehead.jpg" ] }, { "type": "hd_wrinkle", "region": "glabellar", "raw_score": 15.8, "ui_score": 16, "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_wrinkle_glabellar.jpg" ] }, { "type": "hd_wrinkle", "region": "crowfeet", "raw_score": 30.5, "ui_score": 31, "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_wrinkle_crowfeet.jpg" ] }, { "type": "hd_pore", "region": "whole", "raw_score": 35.2, "ui_score": 35, "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_pore_whole.jpg" ] }, { "type": "hd_pore", "region": "forehead", "raw_score": 30, "ui_score": 30, "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_pore_forehead.jpg" ] }, { "type": "hd_pore", "region": "nose", "raw_score": 45.7, "ui_score": 46, "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_pore_nose.jpg" ] }, { "type": "hd_pore", "region": "cheek", "raw_score": 32.1, "ui_score": 32, "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_pore_cheek.jpg" ] }, { "type": "hd_acne", "region": "whole", "raw_score": 12.5, "ui_score": 13, "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_acne_whole.jpg" ] }, { "type": "hd_skin_type", "region": "whole", "skin_type": "Combination", "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_skin_type_whole.jpg" ] }, { "type": "hd_skin_type", "region": "t_zone", "skin_type": "Oily", "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_skin_type_t_zone.jpg" ] }, { "type": "hd_skin_type", "region": "u_zone", "skin_type": "Dry & Redness", "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/hd_skin_type_u_zone.jpg" ] }, { "type": "skin_age", "score": 29 }, { "type": "all", "score": 28.5 }, { "type": "resize_image", "mask_urls": [ "https://s3-us-west-2.amazonaws.com/yce-us/results/resized_image.jpg" ] } ] } } } } } } } }, "RunError": { "type": "object", "properties": { "status": { "type": "integer", "description": "Response status", "example": 400 }, "error": { "type": "string", "description": "Error message", "example": "The operation could not be completed" }, "error_code": { "type": "string", "enum": [ "InvalidParameters", "CreditInsufficiency", "InvalidStyleGroup", "InvalidStyle", "BadRequest" ], "description": "Error code:\n * InvalidParameters - Invalid request parameters\n * CreditInsufficiency - Insufficient unit to run\n * BadRequest - Unexpected request parameter\n * InvalidStyleGroup - Invalid style group id\n * InvalidStyle - Invalid style id\n" } } }, "InvalidApiKey": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 401, "description": "Response status" }, "error": { "type": "string", "example": "Invalid API key" } } } } } }, "TooManyRequests": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 429, "description": "Response status" }, "error": { "type": "string", "example": "Too many requests" } } } } } }, "InvalidTaskId": { "description": "Invalid task ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 400, "description": "Response status" }, "error": { "type": "string", "example": "Invalid task ID" } } } } } }, "TaskTimeout": { "description": "Task execution timeout", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 500, "description": "Response status" }, "error": { "type": "string", "example": "Task execution timed out" } } } } } } } } }