{"items":[{"type":"separator","label":"Utility"},{"type":"group","fsPath":"reference/unit_system.yaml","link":"/reference/unit_system","routeSlug":"/reference/unit_system","label":"Unit System","items":[{"label":"Get unit info","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/unit_system/paths/~1s2s~1v1.0~1client~1credit/get","routeSlug":"/reference/unit_system/paths/~1s2s~1v1.0~1client~1credit/get","metadata":{"seo":{"title":"Get unit info","description":"Display the available API units to two decimal places"}},"httpPath":"/s2s/v1.0/client/credit"},{"label":"View unit history","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/unit_system/paths/~1s2s~1v1.0~1client~1credit~1history/get","routeSlug":"/reference/unit_system/paths/~1s2s~1v1.0~1client~1credit~1history/get","metadata":{"seo":{"title":"View unit history","description":"View unit history"}},"httpPath":"/s2s/v1.0/client/credit/history"},{"label":"Get feature cost","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/unit_system/paths/~1s2s~1v2.0~1credit~1feature-cost/get","routeSlug":"/reference/unit_system/paths/~1s2s~1v2.0~1credit~1feature-cost/get","metadata":{"seo":{"title":"Get feature cost","description":"Check the unit consumption for each API. The values are consistent with those listed at https://yce.perfectcorp.com/ai-api/api-pricing."}},"httpPath":"/s2s/v2.0/credit/feature-cost"}],"metadata":{"type":"openapi","title":"Unit system","version":"","description":"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.\"\n"}},{"type":"group","fsPath":"reference/task_management.yaml","link":"/reference/task_management","routeSlug":"/reference/task_management","label":"Task Management","items":[{"label":"Delete a task and its files.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/task_management/paths/~1s2s~1v2.0~1task~1delete/post","routeSlug":"/reference/task_management/paths/~1s2s~1v2.0~1task~1delete/post","metadata":{"seo":{"title":"Delete a task and its files.","description":"Delete a finished task identified by task_id, including all associated input files and generated outputs. Provide the task_id returned by the task's run endpoint."}},"httpPath":"/s2s/v2.0/task/delete"}],"metadata":{"type":"openapi","title":"Task Management","version":""}},{"type":"group","fsPath":"reference/file.yaml","link":"/reference/file","routeSlug":"/reference/file","label":"File Management","items":[{"label":"Create a new file.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/file/paths/~1s2s~1v2.0~1file/post","routeSlug":"/reference/file/paths/~1s2s~1v2.0~1file/post","metadata":{"seo":{"title":"Create a new file.","description":"To upload a new file, you'll first need to use the File API. It will give you a URL – use that URL to upload your file. Once the upload is finished, you can use the file_id from the same response to start using our AI features."}},"httpPath":"/s2s/v2.0/file"}],"metadata":{"type":"openapi","title":"File Management","version":""}},{"type":"separator","label":"Skin, Face & Body"},{"type":"group","fsPath":"reference/ai_skin_analysis.yaml","link":"/reference/ai_skin_analysis","routeSlug":"/reference/ai_skin_analysis","label":"AI Skin Analysis","items":[{"type":"group","label":"Overview","link":"/reference/ai_skin_analysis/section/overview","routeSlug":"/reference/ai_skin_analysis/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_skin_analysis/section/overview/integration-guide","routeSlug":"/reference/ai_skin_analysis/section/overview/integration-guide"},{"type":"link","label":"Inputs & Outputs","link":"/reference/ai_skin_analysis/section/overview/inputs-and-outputs","routeSlug":"/reference/ai_skin_analysis/section/overview/inputs-and-outputs"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_skin_analysis/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_skin_analysis/section/overview/file-specs-and-errors"},{"type":"link","label":"JS Camera Kit","link":"/reference/ai_skin_analysis/section/overview/js-camera-kit","routeSlug":"/reference/ai_skin_analysis/section/overview/js-camera-kit"},{"type":"link","label":"Mobile Camera Kit","link":"/reference/ai_skin_analysis/section/overview/mobile-camera-kit","routeSlug":"/reference/ai_skin_analysis/section/overview/mobile-camera-kit"}]},{"type":"group","label":"V2.1","link":"/reference/ai_skin_analysis/v2.1","routeSlug":"/reference/ai_skin_analysis/v2.1","items":[{"label":"Run a Skin Analysis V2.1 task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_skin_analysis/v2.1/paths/~1s2s~1v2.1~1task~1skin-analysis/post","routeSlug":"/reference/ai_skin_analysis/v2.1/paths/~1s2s~1v2.1~1task~1skin-analysis/post","metadata":{"seo":{"title":"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 for setup and verification details."}},"httpPath":"/s2s/v2.1/task/skin-analysis"},{"label":"Check a Skin Analysis V2.1 task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_skin_analysis/v2.1/paths/~1s2s~1v2.1~1task~1skin-analysis~1{task_id}/get","routeSlug":"/reference/ai_skin_analysis/v2.1/paths/~1s2s~1v2.1~1task~1skin-analysis~1{task_id}/get","metadata":{"seo":{"title":"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 for setup and verification details."}},"httpPath":"/s2s/v2.1/task/skin-analysis/{task_id}"}]},{"type":"group","label":"V2.0","link":"/reference/ai_skin_analysis/v2.0","routeSlug":"/reference/ai_skin_analysis/v2.0","items":[{"label":"Run a Skin Analysis task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_skin_analysis/v2.0/paths/~1s2s~1v2.0~1task~1skin-analysis/post","routeSlug":"/reference/ai_skin_analysis/v2.0/paths/~1s2s~1v2.0~1task~1skin-analysis/post","metadata":{"seo":{"title":"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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/skin-analysis"},{"label":"Check a Skin Analysis task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_skin_analysis/v2.0/paths/~1s2s~1v2.0~1task~1skin-analysis~1{task_id}/get","routeSlug":"/reference/ai_skin_analysis/v2.0/paths/~1s2s~1v2.0~1task~1skin-analysis~1{task_id}/get","metadata":{"seo":{"title":"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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/skin-analysis/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Skin Analysis","version":"","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"}},{"type":"group","fsPath":"reference/ai_skin_simulation.yaml","link":"/reference/ai_skin_simulation","routeSlug":"/reference/ai_skin_simulation","label":"AI Skin Simulation","items":[{"type":"group","label":"Overview","link":"/reference/ai_skin_simulation/section/overview","routeSlug":"/reference/ai_skin_simulation/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_skin_simulation/section/overview/integration-guide","routeSlug":"/reference/ai_skin_simulation/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_skin_simulation/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_skin_simulation/section/overview/file-specs-and-errors"},{"type":"link","label":"JS Camera Kit","link":"/reference/ai_skin_simulation/section/overview/js-camera-kit","routeSlug":"/reference/ai_skin_simulation/section/overview/js-camera-kit"}]},{"type":"group","label":"V1.0","link":"/reference/ai_skin_simulation/v1.0","routeSlug":"/reference/ai_skin_simulation/v1.0","items":[{"label":"Run an AI Skin Simulation task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_skin_simulation/v1.0/paths/~1s2s~1v2.0~1task~1skin-simulation/post","routeSlug":"/reference/ai_skin_simulation/v1.0/paths/~1s2s~1v2.0~1task~1skin-simulation/post","metadata":{"seo":{"title":"Run an AI Skin Simulation task.","description":"This endpoint initiates the skin simulation process. You must provide a source file (via URL or File ID) and specify the simulation parameters (wrinkle, radiance, etc.). At least one parameter cannot be zero. The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/skin-simulation"},{"label":"Check the status of a AI Skin Simulation task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_skin_simulation/v1.0/paths/~1s2s~1v2.0~1task~1skin-simulation~1{task_id}/get","routeSlug":"/reference/ai_skin_simulation/v1.0/paths/~1s2s~1v2.0~1task~1skin-simulation~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Skin Simulation task.","description":"Check the status of a AI Skin Simulation task."}},"httpPath":"/s2s/v2.0/task/skin-simulation/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Skin simulation","version":"","description":"# Overview\n**AI-Powered Skin Simulation: Visualizing Treatment Progress with Precision and Professionalism**\n\nOur 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.\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-04-17/4edad54f-ef6b-4842-b104-d114889318b1.jpg)\n\nBy 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.\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-11-13/webp_27e3ad50-7769-46de-822c-c9300f87f57d.webp)\n\nDesigned 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.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_Skin_Simulation_pores_b1e209ee58.jpg)\n\nThrough 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.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_Skin_Simulation_283421234a.jpg)\n\n---\n\n## Integration Guide\nThis guide walks you through:\n\nWorkflow for AI Skin Simulation API:\n\n**Endpoint:** `/s2s/v2.0/task/skin-simulation`\n\n**Authentication Required:** `Authorization: Bearer YOUR_API_KEY`\n\n**Workflow Steps:**\n\n1. **Image Upload Preparation:**\n - The process begins with preparing a selfie image.\n\n2. **AI Skin Simulation Settings**\n For each skin concern (e.g., wrinkle, pores, redness), adjust the **simulation intensity** using the value from **0.0 to 1.0**:\n\n - **0.0**: Shows your *original* skin appearance—no changes.\n - **1.0**: Applies the *most natural, healthy-looking* enhancement AI can generate for that concern.\n\n **How it works:**\n - At low settings (e.g., 0.2–0.4), fine lines or minor imperfections are subtly softened.\n - 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.\n\n Adjust gradually to achieve your desired look!\n\n1. **Initiate AI Task and Obtain Task ID:**\n - Send the uploaded image along with the skin simulation configuration via an HTTP POST request to `/s2s/v2.0/task/skin-simulation`.\n - Await a unique task ID in the response, which identifies this interaction.\n\n2. **Poll Task Status (Continuous Check):**\n - Use the obtained `task_id` to periodically poll the task status using an HTTP GET request (e.g., `GET /task/${task_id}`).\n - Continuously monitor for:\n - `Task_status = \"success\"` (process completed).\n - `Task_status = \"error\"` (resolve or retry if applicable).\n - Update the workflow accordingly once the status transitions to success.\n\nThis structured workflow ensures efficient integration with user inputs, automated monitoring of tasks, and seamless retrieval of results.\n\n---\n\n* Authentication\n- Include your API key in the request header using **Bearer Token**:\n ```\n Authorization: Bearer YOUR_API_KEY\n ```\nYou can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.\n\n---\n\n* Upload an Image\n\nYou may upload a file directly to the server or provide a valid image URL in the AI task payload.\n\n * Upload Endpoint\n\n```\nPOST /s2s/v2.0/file\n```\n\nAlternatively, skip this step if you already have a public image URL.\n\n---\n\n* Adjust AI Skin Simulation Intensity\n**AI Skin Simulation Settings**\n\nFor each skin concern (e.g., wrinkle, pores, redness), adjust the **simulation intensity** on a scale from **0.0 to 1.0**:\n\n- **0.0** → *Original appearance* — no AI enhancement applied.\n- **1.0** → *Maximum natural, healthy-looking improvement* for that concern, as realistically rendered by our AI model.\n\n**What to expect at different intensity levels:**\n\n| Intensity Range | Effect |\n|-----------------|--------|\n| **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. |\n| **0.4 – 0.6** | Balanced enhancement — noticeable improvement in texture and clarity while retaining individual skin character. |\n| **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. |\n\n**Pro Tip:** Start low (e.g., 0.2) and gradually increase until you reach the desired result in realism.\n\n---\n\n* Create a AI Skin Simulation AI Task and Poll for Results\n\nAfter 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`.\n\n * Create Task Endpoint\n\n```\nPOST /s2s/v2.0/task/skin-simulation\n```\n\n * Polling Endpoint\n\n```\nGET /s2s/v2.0/task/skin-simulation/{task_id}\n```\n\n---\n\n## File Specs & Errors\n\n* AI Skin Simulation Specification\n\n**Camera and Imaging Guidance**\n\n**Lighting Conditions**\nEnsure 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.\n\n**Face Position and Occlusion**\nCapture 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.\n\n**Facial Expression and Pose**\nMaintain a natural, relaxed expression with both eyes open. The mouth may remain closed or slightly open, do not strain or exaggerate the pose.\n\n**Face Size in Frame**\nThe 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.\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_skin_analysis_01_5b5defd339.png)\n\n\n---\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|AI Skin Simulation|short side >= 480, long side <= 2560|< 10MB|jpg/jpeg/png|\n\n* Error Codes\n\n| **Error Code** | **Description** |\n|------------------------------------|----------------|\n| `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. |\n| `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. |\n| `error_invalid_params` | Invalid request parameters were provided. |\n| `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. |\n| `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. |\n| `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. |\n\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"}},{"type":"group","fsPath":"reference/ai_skin_tone_analysis.yaml","link":"/reference/ai_skin_tone_analysis","routeSlug":"/reference/ai_skin_tone_analysis","label":"AI Facial Color Tones Analyzer","items":[{"type":"group","label":"Overview","link":"/reference/ai_skin_tone_analysis/section/overview","routeSlug":"/reference/ai_skin_tone_analysis/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_skin_tone_analysis/section/overview/integration-guide","routeSlug":"/reference/ai_skin_tone_analysis/section/overview/integration-guide"},{"type":"link","label":"Inputs & Outputs","link":"/reference/ai_skin_tone_analysis/section/overview/inputs-and-outputs","routeSlug":"/reference/ai_skin_tone_analysis/section/overview/inputs-and-outputs"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_skin_tone_analysis/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_skin_tone_analysis/section/overview/file-specs-and-errors"},{"type":"link","label":"JS Camera Kit","link":"/reference/ai_skin_tone_analysis/section/overview/js-camera-kit","routeSlug":"/reference/ai_skin_tone_analysis/section/overview/js-camera-kit"}]},{"type":"group","label":"V1.0","link":"/reference/ai_skin_tone_analysis/v1.0","routeSlug":"/reference/ai_skin_tone_analysis/v1.0","items":[{"label":"Run an Skin Tone Analysis task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_skin_tone_analysis/v1.0/paths/~1s2s~1v2.0~1task~1skin-tone-analysis/post","routeSlug":"/reference/ai_skin_tone_analysis/v1.0/paths/~1s2s~1v2.0~1task~1skin-tone-analysis/post","metadata":{"seo":{"title":"Run an Skin Tone Analysis task.","description":"This endpoint initiates the skin tone analysis process. You must provide a source file (via URL or File ID) and optionally specify face angle strictness level. The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/skin-tone-analysis"},{"label":"Check an Skin Tone Analysis task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_skin_tone_analysis/v1.0/paths/~1s2s~1v2.0~1task~1skin-tone-analysis~1{task_id}/get","routeSlug":"/reference/ai_skin_tone_analysis/v1.0/paths/~1s2s~1v2.0~1task~1skin-tone-analysis~1{task_id}/get","metadata":{"seo":{"title":"Check an Skin Tone Analysis task status.","description":"Check an Skin Tone Analysis task status."}},"httpPath":"/s2s/v2.0/task/skin-tone-analysis/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Facial Color Tones Analyzer","version":"","description":"# Overview\nThe 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.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/img_Face_Ratio_sec_02_02_enu_21a3d8d423.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/shade_finder_s5_poster_2_8a8f9307d2.png)\n\n\n## Integration Guide\n* How to Take Photos for AI Facial Color Tones Analyzer\n\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* How to Detect Skin Concerns by AI\n1. **Resize your source image**
\n Resize your photo to fit the supported dimensions. See details in **[File Specs & Errors](#section/overview/File-Specs-and-Errors)**\n\n2. **Upload file using the File API**
\n Using the ***/s2s/v2.0/file*** API to upload a target user image.\n - Image Requirements\n - See details in **[File Specs & Errors](#section/overview/File-Specs-and-Errors)**.\n - ***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.
\n 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.\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\n3. **Run an AI Facial Color Tones Analyzer task**
\n 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)**.
\n Subsequently, calling POST 'task/skin-tone-analysis' with the\n File ID executes the enhance task and obtains a ***task_id***.\n\n4. **Polling to check the status of a task until it succeed or error**
\nThis ***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.\n\n **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).\n\n > **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*.\n\n5. **Get the result of an AI task once success**
\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.\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![](https://plugins-media.makeupar.com/smb/blog/post/2022-08-19/2a1af800-7c69-44a5-a94c-70a4a9c4d2b0.jpg)\n\n---\n\n## Inputs & Outputs\n* Inputs\nThe 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.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/shade_finder_s4_poster_399f34c6ef.jpg)\n\n* Outputs\n```json\n{\n \"status\": 200,\n \"data\": {\n \"task_status\": \"success\",\n \"results\": {\n \"color\": {\n \"eye_color\": \"#293F9B\",\n \"eye_color_name\": \"Blue\",\n \"lip_color\": \"#D23245\",\n \"eyebrow_color\": \"#5B2B31\",\n \"skin_color\": \"#b9947c\",\n \"hair_color\": \"#a0a0a0\",\n \"hair_color_name\": \"Auburn\"\n }\n }\n }\n}\n```\n\n| **Result Parameter** | **Result Types** |\n| --- | --- |\n| `skin_color` | Hex value |\n| `eye_color`| Hex value |\n| `eye_color_name` | Amber, Brown, Green, Blue, Gray, Other |\n| `lip_color` | Hex value |\n| `eyebrow_color` | Hex value |\n| `hair_color` | Hex value |\n| `color.hair_color_name` | Auburn, Black, Blonde, Brown, Grey/White, Red |\n\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> **Warning:** The width of the face needs to be greater than 60% of the width of the image.\n\n---\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n| AI Feature | Supported Dimensions | Supported File Size | Supported Formats |\n| ---- | ---- | ---- | ---- |\n| 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 |\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| error_below_min_image_size | Source image dimensions must be at least 320 pixels. |\n| error_face_position_invalid | Face must be fully visible, forward-facing, and centered in the image. |\n| error_face_position_too_small | Detected face is too small for analysis. |\n| error_face_position_out_of_boundary | Face extends beyond image boundaries. |\n| error_face_not_forward_facing | Face must be directly facing the camera. |\n| error_face_angle_upward | Face is angled too far upward—slightly tilt head down. |\n| error_face_angle_downward | Face is angled too far downward — slightly tilt head up. |\n| error_face_angle_leftward | Face is turned too far left — slightly rotate head right. |\n| error_face_angle_rightward | Face is turned too far right — slightly rotate head left. |\n| error_face_angle_left_tilt | Face is tilted too far left — gently tilt head right. |\n| error_face_angle_right_tilt | Face is tilted too far right — gently tilt head left. |\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"}},{"type":"group","fsPath":"reference/ai_face_analyzer.yaml","link":"/reference/ai_face_analyzer","routeSlug":"/reference/ai_face_analyzer","label":"AI Face Attributes & Ratio Analyzer","items":[{"type":"group","label":"Overview","link":"/reference/ai_face_analyzer/section/overview","routeSlug":"/reference/ai_face_analyzer/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_face_analyzer/section/overview/integration-guide","routeSlug":"/reference/ai_face_analyzer/section/overview/integration-guide"},{"type":"link","label":"Inputs & Outputs","link":"/reference/ai_face_analyzer/section/overview/inputs-and-outputs","routeSlug":"/reference/ai_face_analyzer/section/overview/inputs-and-outputs"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_face_analyzer/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_face_analyzer/section/overview/file-specs-and-errors"},{"type":"link","label":"JS Camera Kit","link":"/reference/ai_face_analyzer/section/overview/js-camera-kit","routeSlug":"/reference/ai_face_analyzer/section/overview/js-camera-kit"}]},{"type":"group","label":"V1.0","link":"/reference/ai_face_analyzer/v1.0","routeSlug":"/reference/ai_face_analyzer/v1.0","items":[{"label":"Run an Face Attribute Analysis task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_face_analyzer/v1.0/paths/~1s2s~1v2.0~1task~1face-attr-analysis/post","routeSlug":"/reference/ai_face_analyzer/v1.0/paths/~1s2s~1v2.0~1task~1face-attr-analysis/post","metadata":{"seo":{"title":"Run an Face Attribute Analysis task.","description":"This endpoint initiates the face attribute analysis process. You must provide a source file (via URL or File ID) and specify which features to analyze. The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/face-attr-analysis"},{"label":"Check an Face Attribute Analysis task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_face_analyzer/v1.0/paths/~1s2s~1v2.0~1task~1face-attr-analysis~1{task_id}/get","routeSlug":"/reference/ai_face_analyzer/v1.0/paths/~1s2s~1v2.0~1task~1face-attr-analysis~1{task_id}/get","metadata":{"seo":{"title":"Check an Face Attribute Analysis task status.","description":"Check an Face Attribute Analysis task status."}},"httpPath":"/s2s/v2.0/task/face-attr-analysis/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Face Attributes & Ratio Analyzer","version":"","description":"# Overview\nThe AI Face Attributes & Ratio Analyzer examines face structure, identifying features like face, eye, eyebrow, lip, nose, cheekbone shapes, designed to provide personalized recommendations.\n\n## Integration Guide\n* How to Take Photos for AI Face Attributes & Ratio Analyzer\n\n* Take a selfie facing forward\n - 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.\n - 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.\n\n* How to Detect Skin Concerns by AI\n\n1. **Resize your source image**
\n Resize your photo to fit the supported dimensions. See details in **[File Specs & Errors](#section/overview/File-Specs-and-Errors)**\n\n2. **Upload file using the File API**
\n Using the ***/s2s/v2.0/file*** API to upload a target user image.\n - Image Requirements\n - See details in **[File Specs & Errors](#section/overview/File-Specs-and-Errors)**.\n - ***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.
\n 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.\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\n3. **Run an AI Face Attributes & Ratio Analyzer task**
\n 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)**.
\n Subsequently, calling POST 'task/face-attr-analysis' with the\n File ID executes the enhance task and obtains a ***task_id***.\n\n4. **Polling to check the status of a task until it succeed or error**
\nThis ***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.\n\n **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).\n\n > **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*.\n\n5. **Get the result of an AI task once success**
\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.\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* Real-world examples:\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-01-15/10a4b980-f571-4d08-8f5d-e3ed48db77aa.jpg)\n\n## Inputs & Outputs\n* Face Attributes:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/img_Face_Ratio_sec_01_01_enu_79380baa14.jpg)\n\n| **Category** | **Subcategory** | **Request Parameter** | **Result Parameter** | **Result Types** |\n| --- | --- | --- | --- | --- |\n| **FACE** | Face Shape | `faceShape` | `faceshape` | Triangle, Diamond, Heart, InvTriangle, Oblong, Oval, Round, Square, Unknown |\n| **AGE & GENDER** | Age | `age` | `agegender.age` | integer |\n| | Gender | `gender` | `agegender.gender` | female, male, unknown |\n| **EYES** | Eye Shape | `eyeShape` | `eyelid.left_shape`, `eyelid.right_shape` | Narrow, Round, Almond |\n| | Eye Size | `eyeSize` | `eyelid.size` | Big, Small, Average |\n| | Eye Angle | `eyeAngle` | `eyelid.left_angle`, `eyelid.right_angle` | Downturned, Upturned, Average |\n| | Eye Distance | `eyeDistance` | `eyelid.setting` | Close-set, Wide-Set, Average |\n| | Eyelid | `eyelid` | `eyelid.left_eyelid`, `eyelid.right_eyelid` | Hooded-lid, Single-lid, Double-lid, Deep-Set |\n| **BROWS** | Eyebrow Shape | `eyebrowShape` | `eyebrow.left_shape`, `eyebrow.right_shape` | Hard Angled, Soft Angled, Straight, Rounded, Obscured |\n| | Eyebrow Thickness | `eyebrowThickness` | `eyebrow.left_body_thickness`, `eyebrow.right_body_thickness` | Dense, Sparse, Average, Unknown |\n| | Eyebrow Distance | `eyebrowDistance` | `eyebrow.gap` | Far-Apart, Close, Average |\n| | Eyebrow Shortness | `eyebrowShortness` | `eyebrow.left_shortness`, `eyebrow.right_shortness` | Short, Normal |\n| **LIPS** | Lip Shape | `lipShape` | `lipshape[]` | Bow, Downturned, Full, Heavy Lower Lip, Heavy Upper Lip, Narrow, Round, Thin, Wide, Average |\n| **NOSE** | Nose Width | `noseWidth` | `nose.width` | Narrow, Broad, Average |\n| | Nose Length | `noseLength` | `nose.length` | Long, Short, Average |\n| **CHEEKBONES** | Cheekbones | `cheekbones` | `cheekbone.left`, `cheekbone.right`, `cheekbone.overrall` | Flat Cheekbone, High Cheekbone, Low Cheekbone, Round Cheeks |\n\n\n---\n\n* Face Ratios:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/img_Face_Ratio_sec_01_03_2fe8f06b92.jpg)\n\n| **Subcategory** | **Request Parameter** | **Result Parameter** | **Result Types** | **Description** |\n| --- | --- | --- | --- | --- |\n| 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.|\n| 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. |\n| 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. |\n| 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.\n |\n| 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. |\n| 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. |\n| 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. |\n| 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. |\n| 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. |\n| 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. |\n\n----\n\n* Suggestions for How to Shoot:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_Face_Analysis_how_to_shoot_35ca9af08e.png)\n\n> **Warning:** The width of the face needs to be greater than 60% of the width of the image.\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|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|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| error_below_min_image_size | Source image dimensions must be at least 320 pixels. |\n| error_face_position_invalid | Face must be fully visible, forward-facing, and centered in the image. |\n| error_face_position_too_small | Detected face is too small for analysis. |\n| error_face_position_out_of_boundary | Face extends beyond image boundaries. |\n| error_face_not_forward_facing | Face must be directly facing the camera. |\n| error_face_angle_upward | Face is angled too far upward—slightly tilt head down. |\n| error_face_angle_downward | Face is angled too far downward — slightly tilt head up. |\n| error_face_angle_leftward | Face is turned too far left — slightly rotate head right. |\n| error_face_angle_rightward | Face is turned too far right — slightly rotate head left. |\n| error_face_angle_left_tilt | Face is tilted too far left — gently tilt head right. |\n| error_face_angle_right_tilt | Face is tilted too far right — gently tilt head left. |\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"}},{"type":"group","fsPath":"reference/ai_aging_simulation.yaml","link":"/reference/ai_aging_simulation","routeSlug":"/reference/ai_aging_simulation","label":"AI Aging Simulation","items":[{"type":"group","label":"Overview","link":"/reference/ai_aging_simulation/section/overview","routeSlug":"/reference/ai_aging_simulation/section/overview","items":[{"type":"link","label":"File Specs & Errors","link":"/reference/ai_aging_simulation/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_aging_simulation/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_aging_simulation/v1.0","routeSlug":"/reference/ai_aging_simulation/v1.0","items":[{"label":"Run a AI Aging Generator task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_aging_simulation/v1.0/paths/~1s2s~1v2.0~1task~1aging/post","routeSlug":"/reference/ai_aging_simulation/v1.0/paths/~1s2s~1v2.0~1task~1aging/post","metadata":{"seo":{"title":"Run a AI Aging Generator task.","description":"This endpoint initiates the aging generation process. You must provide a source file (via URL or File ID). The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/aging"},{"label":"Check the status of a AI Aging Generator task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_aging_simulation/v1.0/paths/~1s2s~1v2.0~1task~1aging~1{task_id}/get","routeSlug":"/reference/ai_aging_simulation/v1.0/paths/~1s2s~1v2.0~1task~1aging~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Aging Generator task.","description":"Check the status of a AI Aging Generator task."}},"httpPath":"/s2s/v2.0/task/aging/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Aging Simulation","version":"","description":"# Overview\nAI 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.\n\n![AI Aging Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/f42f1504_79e3_461c_a3f1_a254623d113b_b068736afb.jpg \"AI Aging Generator\")\n\nThe 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.\n![AI Aging Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/U_2024_04_17_cr_12112b83e2.png \"AI Aging Generator\")\n\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n| AI Feature | Supported Dimensions | Supported File Size | Supported Formats |\n| ---- | ---- | ---- | ---- |\n| AI Aging | long side <= 4096, single person only. Face pose constraints: yaw within ±30°, roll within ±20°, and pitch within ±20°. | < 10MB | jpg/jpeg |\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| error_below_min_image_size | Source image dimensions must be at least 320 pixels. |\n| error_face_position_invalid | Face must be fully visible, forward-facing, and centered in the image. |\n| error_face_position_too_small | Detected face is too small for analysis. |\n| error_face_position_out_of_boundary | Face extends beyond image boundaries. |\n| error_face_not_forward_facing | Face must be directly facing the camera. |\n| error_face_angle_upward | Face is angled too far upward—slightly tilt head down. |\n| error_face_angle_downward | Face is angled too far downward — slightly tilt head up. |\n| error_face_angle_leftward | Face is turned too far left — slightly rotate head right. |\n| error_face_angle_rightward | Face is turned too far right — slightly rotate head left. |\n| error_face_angle_left_tilt | Face is tilted too far left — gently tilt head right. |\n| error_face_angle_right_tilt | Face is tilted too far right — gently tilt head left. |\n"}},{"type":"group","fsPath":"reference/ai_face_reshape.yaml","link":"/reference/ai_face_reshape","routeSlug":"/reference/ai_face_reshape","label":"AI Face Reshape","items":[{"type":"group","label":"Overview","link":"/reference/ai_face_reshape/section/overview","routeSlug":"/reference/ai_face_reshape/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_face_reshape/section/overview/integration-guide","routeSlug":"/reference/ai_face_reshape/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_face_reshape/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_face_reshape/section/overview/file-specs-and-errors"},{"type":"link","label":"JS Camera Kit","link":"/reference/ai_face_reshape/section/overview/js-camera-kit","routeSlug":"/reference/ai_face_reshape/section/overview/js-camera-kit"}]},{"type":"group","label":"V1.0","link":"/reference/ai_face_reshape/v1.0","routeSlug":"/reference/ai_face_reshape/v1.0","items":[{"label":"Run an AI Face Reshape detection task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1pre-process/post","routeSlug":"/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1pre-process/post","metadata":{"seo":{"title":"Run an AI Face Reshape detection task.","description":"Use the pre-process task when the source image may contain more than one valid target, or when your integration needs to explicitly choose which detected target receives the effect. For single-target images, pre-process can be skipped when the feature supports a default index value and your application does not need manual target selection."}},"httpPath":"/s2s/v2.0/task/face-reshape/pre-process"},{"label":"Check the status of an AI Face Reshape detection task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1pre-process~1{task_id}/get","routeSlug":"/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1pre-process~1{task_id}/get","metadata":{"seo":{"title":"Check the status of an AI Face Reshape detection task.","description":"Use the pre-process task when the source image may contain more than one valid target, or when your integration needs to explicitly choose which detected target receives the effect. For single-target images, pre-process can be skipped when the feature supports a default index value and your application does not need manual target selection."}},"httpPath":"/s2s/v2.0/task/face-reshape/pre-process/{task_id}"},{"label":"Run an AI Face Reshape task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape/post","routeSlug":"/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape/post","metadata":{"seo":{"title":"Run an AI Face Reshape 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/face-reshape"},{"label":"Check the status of a AI Face Reshape task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1{task_id}/get","routeSlug":"/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Face Reshape task.","description":"Check the status of a AI Face Reshape task."}},"httpPath":"/s2s/v2.0/task/face-reshape/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Face Reshape","version":"","description":"# Overview\nThe 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.\n\n* Rhinoplasty (Nose Job)\nOur 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.\n\n* Chin Filler\nThrough 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.\n\n* Lip Filler\nUsers 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.\n\n* Brow Lift Surgery\nThis 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.\n\n\n\n## Integration Guide\nThis guide walks you through:\n\nWorkflow for AI Face Reshape API:\n\n**Endpoint:** `/s2s/v2.0/file`\n\n**Authentication Required:** `Authorization: Bearer YOUR_API_KEY`\n\n**Workflow Steps:**\n\n1. **Image Upload Preparation:**\n - The process begins with preparing a selfie image.\n\n1. **Optional Preprocessing For Multiple Faces:**\n - Preprocess the selfie image if there are more than one face in the image.\n\n2. **Face Reshape Effect Setup:**\n - Begin by selecting suitable face reshape parameters of Eye, Face, Lip or Nose.\n\n3. **Initiate AI Task and Obtain Task ID:**\n - Send the uploaded image(s) along with the chosen effect configuration via an HTTP POST request to `/s2s/v2.0/file`.\n - Await a unique task ID in the response, which identifies this interaction.\n\n4. **Poll Task Status (Continuous Check):**\n - Use the obtained `task_id` to periodically poll the task status using an HTTP GET request (e.g., `GET /task/${task_id}`).\n - Continuously monitor for:\n - `Task_status = \"success\"` (process completed).\n - `Task_status = \"error\"` (resolve or retry if applicable).\n - Update the workflow accordingly once the status transitions to success.\n\nThis structured workflow ensures efficient integration with user inputs, automated monitoring of tasks, and seamless retrieval of results.\n\n---\n\n* API Playground\n\nInteractively explore and test the API using our official playground:\n\n**API Playground:**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-face-reshape/](http://yce.makeupar.com/api-console/en/api-playground/ai-face-reshape/)\n\n---\n\n* Authentication\n- Include your API key in the request header using **Bearer Token**:\n ```\n Authorization: Bearer YOUR_API_KEY\n ```\nYou can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.\n\n\n* 1. Upload an Image\n\nYou may upload a file directly to the server or provide a valid image URL in the AI task payload.\n\n * Upload Endpoint\n\n```\nPOST /s2s/v2.0/file\n```\n\nAlternatively, skip this step if you already have a public image URL.\n\n---\n\n* 2. Prepare an effect template\n\n * Preprocessing\nOutput detected bounding boxes in pixel coordinate. Use the index of result to create a Face Reshape AI task later.\n```\n{\n \"timed\": number,\n \"result\": [\n {\n \"left\": number,\n \"top\": number,\n \"width\": number,\n \"height\": number\n }\n ]\n}\n```\n\n * Effect Template JSON Schemas\n```\n{\n \"version\": \"1.0\",\n \"index\": 0,\n \"features\": {},\n \"global\": {\n \"skin_smooth_strength\": 50,\n \"skin_smooth_color_intensity\": 50,\n },\n}\n```\nindex: index of detected face from preprocessing. optional, default 0.\nfeatures: required at least 1, non-zero face reshape parameter, cannot be all zero.\nskin_smooth_strength: 0~100\nskin_smooth_color_intensity: 0~100\n\n * Effect Format\n- Face\ndefault range: -100~100\nrange of cheekbones and jaws: 0~100\nall feature values must not be zero at the same time, at least one feature value must be non-zero\n```\n{\n \"cheekbones\": 0,\n \"jaw\": 0,\n \"face_reshape_left\": 0,\n \"face_reshape_right\": 0,\n \"face_width\": 0,\n \"chin_reshape_left\": 0,\n \"chin_reshape_right\": 0,\n \"chin_length\": 0,\n}\n```\n\n- Eye\ndefault range: -100~100\nall feature values must not be zero at the same time, at least one feature value must be non-zero\n```\n{\n \"eye_size_left\": 0,\n \"eye_size_right\": 0,\n \"eye_distance\": 0,\n \"eye_angle\": 0,\n \"eye_height\": 0,\n \"eye_width\": 0,\n}\n```\n\n- Nose\ndefault range: -100~100\nall feature values must not be zero at the same time, at least one feature value must be non-zero\n```\n{\n \"nose_bridge_width\": 0,\n \"nose_lift\": 0,\n \"nose_size\": 0,\n \"nose_tip\": 0,\n \"nose_tip_width\": 0,\n \"nose_wing\": 0\n}\n```\n\n- Lip\ndefault range: -100~100\nall feature values must not be zero at the same time, at least one feature value must be non-zero\n```\n{\n \"lip_size\": 0,\n \"lip_width\": 0,\n \"lip_peak\": 0,\n \"lip_height_top\": 0,\n \"lip_height_bottom\": 0,\n}\n```\n\n * Example Payload (ready to send)\n```\n{\n \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/face_reshape_01_85c8ffc055.jpg\",\n \"version\": \"1.0\",\n \"source\": \"yco\",\n \"features\": {\n \"eye_size_left\": 80,\n \"eye_size_right\": 80,\n \"eye_width\": 0,\n \"eye_height\": 0,\n \"eye_distance\": 0,\n \"eye_angle\": 0,\n \"face_reshape_left\": 0,\n \"face_reshape_right\": 0,\n \"chin_reshape_left\": 20,\n \"chin_reshape_right\": 20,\n \"chin_length\": 0,\n \"face_width\": -30,\n \"cheekbones\": 0,\n \"jaw\": 0,\n \"lip_size\": 10,\n \"lip_width\": 40,\n \"lip_height_top\": 10,\n \"lip_height_bottom\": 10,\n \"lip_peak\": -10,\n \"nose_size\": 30,\n \"nose_lift\": -20,\n \"nose_bridge_width\": 10,\n \"nose_tip\": -10,\n \"nose_wing\": 30,\n \"nose_tip_width\": 30\n },\n \"global\": {\n \"skin_smooth_strength\": 50,\n \"skin_smooth_color_intensity\": 50\n }\n}\n```\n\n\n* 3. Create a Face Reshape AI Task and Poll for Results\n\nOnce 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`.\n\n * Create Task Endpoint\n\n```\nPOST /s2s/v2.0/task/face-reshape\n```\n\n * Polling Endpoint\n\n```\nGET /s2s/v2.0/task/face-reshape/{task_id}\n```\n\n---\n\n## File Specs & Errors\n\n* AI Face Reshape Specification\n\n**Supported Selfie View**\nA selfie with width and height of a face larger than 1/20 of image width and heigh.\nFace angle less than 30 degree for pitch, yaw and rolling.\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_face_reshape_01_85c8ffc055.jpg)\n\n\n\n**Facial Customization Parameters Guide**\n\n| Category | Parameter | Function | Min (-100 / 0) | Max (100) |\n| -------- | ---------------- | ------------------------------------ | -------------- | ------------ |\n| Eyes | Size (L/R) | Scales overall size of each eye | Small | Large |\n| Eyes | Width | Adjusts horizontal span | Narrow | Wide |\n| Eyes | Height | Adjusts vertical span | Narrow / Flat | Round / Tall |\n| Eyes | Distance | Adjusts spacing between eyes | Close-set | Wide-set |\n| Eyes | Angle | Adjusts rotational tilt | Inward tilt | Outward tilt |\n| Face | Size (L/R) | Scales size of each side of the face | Small | Large |\n| Face | Chin Shape (L/R) | Adjusts chin contour width | Narrow | Wide |\n| Face | Chin Length | Adjusts vertical chin length | Short | Long |\n| Face | Width | Adjusts overall facial width | Narrow | Wide |\n| Face | Cheekbone | Adjusts cheekbone prominence | Original (0) | Tucked in |\n| Face | Jaw | Adjusts jawline prominence | Original (0) | Tucked in |\n| Lips | Size | Scales overall lip volume | Small | Large |\n| Lips | Width | Adjusts horizontal span | Narrow | Wide |\n| Lips | Upper Height | Adjusts top lip thickness | Thin | Full |\n| Lips | Lower Height | Adjusts bottom lip thickness | Thin | Full |\n| Lips | Peak | Adjusts Cupid's bow sharpness | Smooth | Defined |\n| Nose | Size | Scales overall nose size | Small | Large |\n| Nose | Lift | Adjusts vertical position | Low | High |\n| Nose | Bridge | Adjusts bridge width | Narrow | Wide |\n| Nose | Tip | Adjusts vertical angle of the tip | Up | Down |\n| Nose | Wing | Adjusts nostril width | Narrow | Wide |\n| Nose | Width | Adjusts width of the nose tip | Narrow | Wide |\n\n**Note:** *“Left” and “Right” refer to the character's perspective, not the viewer's side of the screen.*\n\n\n---\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|AI Face Reshape|long side <= 4096|< 10MB|jpg/jpeg/png|\n\n* Error Codes\n\n| Error Code | Description |\n| ---- | ---- |\n| RUNTIME_ERROR | An unexpected error occurred duface reshape runtime |\n| PHOTO_DETECTION_FAIL | The user photo could not be processed correctly, for example no hand detected |\n| OBJECT_DETECTION_FAIL | The object photo could not be processed correctly, for example no product detected |\n| PHOTO_CHECK_INVALID | The pose or size of the user photo is invalid |\n| INPUT_ERROR | The input file format is incorrect |\n| INPUT_MAIN_IMAGE_EMPTY | A user image is required |\n\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"}},{"type":"group","fsPath":"reference/ai_body_reshape.yaml","link":"/reference/ai_body_reshape","routeSlug":"/reference/ai_body_reshape","label":"AI Body Reshape","items":[{"type":"group","label":"Overview","link":"/reference/ai_body_reshape/section/overview","routeSlug":"/reference/ai_body_reshape/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_body_reshape/section/overview/integration-guide","routeSlug":"/reference/ai_body_reshape/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_body_reshape/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_body_reshape/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_body_reshape/v1.0","routeSlug":"/reference/ai_body_reshape/v1.0","items":[{"label":"Run an AI Body Reshape detection task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape~1pre-process/post","routeSlug":"/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape~1pre-process/post","metadata":{"seo":{"title":"Run an AI Body Reshape detection task.","description":"Use the pre-process task when the source image may contain more than one valid target, or when your integration needs to explicitly choose which detected target receives the effect. For single-target images, pre-process can be skipped when the feature supports a default index value and your application does not need manual target selection."}},"httpPath":"/s2s/v2.0/task/body-reshape/pre-process"},{"label":"Check the status of a AI Body Reshape detection task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape~1pre-process~1{task_id}/get","routeSlug":"/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape~1pre-process~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Body Reshape detection task.","description":"Check the status of a AI Body Reshape detection task."}},"httpPath":"/s2s/v2.0/task/body-reshape/pre-process/{task_id}"},{"label":"Run an AI Body Reshape task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape/post","routeSlug":"/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape/post","metadata":{"seo":{"title":"Run an AI Body Reshape 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/body-reshape"},{"label":"Check the status of a AI Body Reshape task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape~1{task_id}/get","routeSlug":"/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Body Reshape task.","description":"Check the status of a AI Body Reshape task."}},"httpPath":"/s2s/v2.0/task/body-reshape/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Body Reshape","version":"","description":"# Overview\nAI Body Reshape API for Body Reshape & Slimming\nFeel 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!\n\n\n## Integration Guide\nThis guide walks you through:\n\nWorkflow for AI Body Reshape API:\n\n**Endpoint:** `/s2s/v2.0/task/body-reshape`\n\n**Authentication Required:** `Authorization: Bearer YOUR_API_KEY`\n\n**Workflow Steps:**\n\n1. **Image Upload Preparation:**\n- The process begins with preparing a selfie image.\n\n2. **Optional Preprocessing For Group Photos:**\n- Preprocess the selfie image if there are more than one person in the image.\n\n3. **Body Reshape Effect Setup:**\n- Begin by selecting suitable body reshape parameters.\n\n4. **Initiate AI Task and Obtain Task ID:**\n- Send the uploaded image(s) along with the chosen effect configuration via an HTTP POST request to `/s2s/v2.0/file`.\n- Await a unique task ID in the response, which identifies this interaction.\n\n5. **Poll Task Status (Continuous Check):**\n- Use the obtained `task_id` to periodically poll the task status using an HTTP GET request (e.g., `GET /task/${task_id}`).\n- Continuously monitor for:\n- `Task_status = \"success\"` (process completed).\n- `Task_status = \"error\"` (resolve or retry if applicable).\n- Update the workflow accordingly once the status transitions to success.\n\nThis structured workflow ensures efficient integration with user inputs, automated monitoring of tasks, and seamless retrieval of results.\n\n---\n\n* API Playground\n\nInteractively explore and test the API using our official playground:\n\n**API Playground:**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-body-reshape/](http://yce.makeupar.com/api-console/en/api-playground/ai-body-reshape/)\n\n---\n\n* Authentication\n- Include your API key in the request header using **Bearer Token**:\n```\nAuthorization: Bearer YOUR_API_KEY\n```\nYou can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.\n\n\n* 1. Upload an Image\n\nYou may upload a file directly to the server or provide a valid image URL in the AI task payload.\n\n* Upload Endpoint\n\n```\nPOST /s2s/v2.0/file\n```\n\nAlternatively, skip this step if you already have a public image URL.\n\n---\n\n* 2. Prepare an effect template\n\n* Preprocessing\nOutput detected bounding boxes in pixel coordinate. Use the index of result to create a Body Reshape AI task later.\n```\n{\n\"timed\": number,\n\"result\": [\n{\n \"left\": number,\n \"top\": number,\n \"width\": number,\n \"height\": number\n}\n]\n}\n```\n\n* Effect Template JSON Schemas\n```\n{\n\"version\": \"1.0\",\n\"index\": 0,\n\"features\": {\n\"arm\": 0, // -100~100\n\"breast_left\": 0, // -100~100\n\"breast_right\": 0, // -100~100\n\"hip\": 0, // -100~100\n\"hip_lift\": 0, // -100~100\n\"leg\": 0, // -100~100\n\"neck_left\": 0, // 0~100\n\"neck_right\": 0, // 0~100\n\"shoulder_left\": 0, // -100~100\n\"shoulder_right\": 0, // -100~100\n\"squared_shoulder_left\": 0, // -100~100\n\"squared_shoulder_right\": 0, // -100~100\n\"slim\": 0, // -100~100\n\"taller\": 0, // 0~100\n\"waist\": 0, // -100~100\n\"belly\": 0 // -100~100\n}\n}\n```\nindex: index of detected body from preprocessing. optional, default 0.\nfeatures: required at least 1, non-zero body reshape parameter, cannot be all zero.\n\n\n* Example Payload (ready to send)\n```\n{\n \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/body_reshape_02_7777218379.jpg\",\n \"version\": \"1.0\",\n \"index\": 0,\n \"features\": {\n\"arm\": 0,\n\"waist\": -20,\n\"taller\": 80,\n\"squared_shoulder_left\": 10,\n\"squared_shoulder_right\": 10,\n\"neck_left\": 0,\n\"neck_right\": 0,\n\"hip\": 10,\n\"breast_left\": 30,\n\"breast_right\": 30,\n\"slim\": -70,\n\"shoulder_left\": 30,\n\"shoulder_right\": 30,\n\"leg\": -30,\n\"hip_lift\": 0,\n\"belly\": -50\n }\n}\n```\n\n\n* 3. Create a Body Reshape AI Task and Poll for Results\n\nOnce 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`.\n\n* Create Task Endpoint\n\n```\nPOST /s2s/v2.0/task/body-reshape\n```\n\n* Polling Endpoint\n\n```\nGET /s2s/v2.0/task/body-reshape/{task_id}\n```\n\n---\n\n## File Specs & Errors\n\n* AI Body Reshape Specification\n\n**Supported Selfie View**\nFull body shot with clear facial expression and body posture visible.\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_body_reshape_02_7777218379.jpg)\n\n**Visibility & Pose Requirements**\n\n| **Region** | **What must be true in the source image** |\n|------------|---------------------------------------------------|\n| **Neck** | The neck must be visible in the source image. |\n| **Arm** | Both arms – upper arm, forearm and hand – have to be fully shown. |\n| **Leg** | The whole leg must appear in the picture. |\n| **Hip** | Hips need to be in view. |\n| **Hip‑Lift** | Hips need to be in view. |\n| **Shoulder** | • Shoulders are required to be seen.
• Raising a hand is not allowed.
• A 90° side pose is not allowed. |\n| **Belly** | The belly is required to be visible. |\n| **Waist** | Waist must be visible. |\n| **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. |\n| **Slim** | Shoulders need to be in the frame. |\n| **Taller** | • Hips must appear.
• A half‑body view should include the legs (i.e., legs are visible). |\n\n\n\n**Body Reshape Customization Parameters Guide**\n\n| Category | Parameter | Function | Min Value (-100 / 0) | Max Value (100) |\n| -------- | --------- | -------- | -------------------- | --------------- |\n| Arms| Intensity | Adjusts the thickness of the arms | Thin | Thick |\n| Belly| Intensity | Adjusts abdominal projection | Flat | Protruding |\n| Chest| Intensity (Left / Right) | Adjusts chest volume on each side | Flat | Full |\n| 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) |\n| Hip Size | Intensity | Adjusts the overall width of the hips | Narrow | Wide |\n| Legs| Intensity | Adjusts the thickness of the legs | Thin | Thick|\n| Neck| Intensity (Left / Right) | Adjusts neck contour and slimming per side| Original (0)| Tucked in |\n| Shoulder Width | Intensity (Left / Right) | Adjusts the span of each shoulder | Narrow | Broad |\n| Shoulder Shape | Intensity (Left / Right) | Adjusts the angle and slope of each shoulder | Sloped | Squared |\n| Slim| Intensity | Adjusts overall body curvature | Slim | Curvy |\n| Tall| Intensity | Adjusts the overall character height | Original (0) | Taller |\n| Waist| Intensity | Adjusts the width of the waistline | Narrow | Wide |\n\n**Note:** *“Left” and “Right” refer to the character's perspective, not the viewer's side of the screen.*\n\n\n---\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|AI Body Reshape|long side <= 2048, short side >= 320|< 10MB|jpg/jpeg/png|\n\n* Error Codes\n\n| Error Code | Description |\n| ---- | ---- |\n| RUNTIME_ERROR | An unexpected error occurred dubody reshape runtime |\n| PHOTO_DETECTION_FAIL | The user photo could not be processed correctly, for example no hand detected |\n| PHOTO_CHECK_INVALID | The pose or size of the user photo is invalid |\n| INPUT_ERROR | The input file format is incorrect |\n| INPUT_MAIN_IMAGE_EMPTY | A user image is required |\n\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"}},{"type":"group","fsPath":"reference/ai_breast_augmentation.yaml","link":"/reference/ai_breast_augmentation","routeSlug":"/reference/ai_breast_augmentation","label":"AI Breast Augmentation Simulator","items":[{"type":"group","label":"Overview","link":"/reference/ai_breast_augmentation/section/overview","routeSlug":"/reference/ai_breast_augmentation/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_breast_augmentation/section/overview/integration-guide","routeSlug":"/reference/ai_breast_augmentation/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_breast_augmentation/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_breast_augmentation/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_breast_augmentation/v1.0","routeSlug":"/reference/ai_breast_augmentation/v1.0","items":[{"label":"Run an AI Breast Augmentation Simulator task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_breast_augmentation/v1.0/paths/~1s2s~1v2.0~1task~1breast-shape/post","routeSlug":"/reference/ai_breast_augmentation/v1.0/paths/~1s2s~1v2.0~1task~1breast-shape/post","metadata":{"seo":{"title":"Run an AI Breast Augmentation Simulator task.","description":"This endpoint initiates the breast augmentation simulation process. You must provide a source file (via URL or File ID) and specify the intensity level. The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/breast-shape"},{"label":"Check the status of a AI Breast Augmentation Simulator task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_breast_augmentation/v1.0/paths/~1s2s~1v2.0~1task~1breast-shape~1{task_id}/get","routeSlug":"/reference/ai_breast_augmentation/v1.0/paths/~1s2s~1v2.0~1task~1breast-shape~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Breast Augmentation Simulator task.","description":"Check the status of a AI Breast Augmentation Simulator task."}},"httpPath":"/s2s/v2.0/task/breast-shape/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Breast Augmentation Simulator","version":"","description":"# Overview\nAI 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.\n\nEnhance 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.\n\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-06-18/e41b8942-22e1-4846-8f81-f41171b74558.jpg)\n\nUnlike 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.\n\nTo 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.\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-06-18/733cedfd-2e8e-4cfc-8758-6854d923664b.jpg)\n\n---\n\n## Integration Guide\nThis guide walks you through:\n\nWorkflow for AI Breast Augmentation Simulator API:\n\n**Endpoint:** `/s2s/v2.0/task/breast-shape`\n\n**Authentication Required:** `Authorization: Bearer YOUR_API_KEY`\n\n**Workflow Steps:**\n\n1. **Image Upload Preparation:**\n - The process begins with preparing a bust shot selfie.\n\n2. **AI Breast Augmentation Simulator Settings**\n 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.\n\n3. **Initiate AI Task and Obtain Task ID:**\n - Send the uploaded image along with the parameter configuration via an HTTP POST request to `/s2s/v2.0/file`.\n - Await a unique task ID in the response, which identifies this interaction.\n\n4. **Poll Task Status (Continuous Check):**\n - Use the obtained `task_id` to periodically poll the task status using an HTTP GET request (e.g., `GET /task/${task_id}`).\n - Continuously monitor for:\n - `Task_status = \"success\"` (process completed).\n - `Task_status = \"error\"` (resolve or retry if applicable).\n - Update the workflow accordingly once the status transitions to success.\n\nThis structured workflow ensures efficient integration with user inputs, automated monitoring of tasks, and seamless retrieval of results.\n\n---\n\n* Authentication\n- Include your API key in the request header using **Bearer Token**:\n ```\n Authorization: Bearer YOUR_API_KEY\n ```\nYou can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.\n\n---\n\n* Upload an Image\n\nYou may upload a file directly to the server or provide a valid image URL in the AI task payload.\n\n * Upload Endpoint\n\n```\nPOST /s2s/v2.0/file\n```\n\nAlternatively, skip this step if you already have a public image URL.\n\n---\n\n* Adjust AI Breast Augmentation Simulator Intensity\n**AI Breast Augmentation Simulator Settings**\n\nFor AI Breast Augmentation Simulator, control the degree of modification by setting the intensity level between **1 and 3**, where:\n- **Level 1** provides subtle, natural-looking adjustments ideal for minor refinement.\n- **Level 2** offers moderate enhancement, balancing realism with noticeable improvement.\n- **Level 3** delivers the most pronounced effect, suitable for significant reshaping while preserving anatomical plausibility.\n\nSelect the intensity level that best aligns with your aesthetic goals and desired look.\n\n---\n\n* Create a AI Breast Augmentation Simulator AI Task and Poll for Results\n\nAfter 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`.\n\n * Create Task Endpoint\n\n```\nPOST /s2s/v2.0/task/breast-shape\n```\n\n * Polling Endpoint\n\n```\nGET /s2s/v2.0/task/breast-shape/{task_id}\n```\n\n---\n\n## File Specs & Errors\n\n* AI Breast Augmentation Simulator Specification\n**Image Requirements and Recommendations for Optimal Results**\n\n- **Resolution Guidelines**:\n 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.\n\n- **Subject Requirements**:\n - The image must contain at least one fully detectable person. Both shoulders should be clearly visible in-frame.\n - 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.\n\n- **Recommended Practices for Enhanced Outcomes**:\n - 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.\n - Use frontal poses exclusively; avoid side-facing or significantly rotated positions, as these reduce detection accuracy and result quality.\n - 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.\n - 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).\n - 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.\n - 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.\n\nFollowing these guidelines ensures optimal input quality and maximizes the fidelity, realism, and consistency of the AI-generated enhancements.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_02-1_2dfe3418c2.jpg)\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_02-2_a88356deeb.jpg)\n\n---\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|AI Breast Augmentation Simulator|minimum: 512x384
maximum: long side < 4096|< 10MB|jpg/jpeg/png/heic |\n\n* Error Codes\n\n| Error Code | Description |\n|----------------------------------|-------------|\n| `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. |\n| `exceed_max_filesize` | The input image exceeds the maximum allowed file size (10 MB). Please compress or resize the image before submission. |\n| `error_download_image` | The system failed to download the source image, likely due to network issues, an invalid URL, or inaccessible resource permissions. |\n| `error_decode_image` | The downloaded image could not be decoded—this may result from file corruption, unsupported format, or invalid binary data. |\n| `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. |\n| `error_pose` | Human pose estimation failed; no full-body or upper-body skeleton could be reliably detected, preventing subsequent anatomical analysis. |\n| `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). |\n\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"}},{"type":"group","fsPath":"reference/ai_face_lift.yaml","link":"/reference/ai_face_lift","routeSlug":"/reference/ai_face_lift","label":"AI Face Lift","items":[{"type":"group","label":"Overview","link":"/reference/ai_face_lift/section/overview","routeSlug":"/reference/ai_face_lift/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_face_lift/section/overview/integration-guide","routeSlug":"/reference/ai_face_lift/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_face_lift/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_face_lift/section/overview/file-specs-and-errors"},{"type":"link","label":"JS Camera Kit","link":"/reference/ai_face_lift/section/overview/js-camera-kit","routeSlug":"/reference/ai_face_lift/section/overview/js-camera-kit"}]},{"type":"group","label":"V1.0","link":"/reference/ai_face_lift/v1.0","routeSlug":"/reference/ai_face_lift/v1.0","items":[{"label":"Run an AI Face Lift detection task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift~1pre-process/post","routeSlug":"/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift~1pre-process/post","metadata":{"seo":{"title":"Run an AI Face Lift detection task.","description":"Use the pre-process task when the source image may contain more than one valid target, or when your integration needs to explicitly choose which detected target receives the effect. For single-target images, pre-process can be skipped when the feature supports a default index value and your application does not need manual target selection."}},"httpPath":"/s2s/v2.0/task/face-lift/pre-process"},{"label":"Check the status of an AI Face Lift detection task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift~1pre-process~1{task_id}/get","routeSlug":"/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift~1pre-process~1{task_id}/get","metadata":{"seo":{"title":"Check the status of an AI Face Lift detection task.","description":"Check the status of an AI Face Lift detection task."}},"httpPath":"/s2s/v2.0/task/face-lift/pre-process/{task_id}"},{"label":"Run an AI Face Lift task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift/post","routeSlug":"/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift/post","metadata":{"seo":{"title":"Run an AI Face Lift 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/face-lift"},{"label":"Check the status of a AI Face Lift task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift~1{task_id}/get","routeSlug":"/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Face Lift task.","description":"Check the status of a AI Face Lift task."}},"httpPath":"/s2s/v2.0/task/face-lift/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Face Lift","version":"","description":"# Overview\nAI 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.\n\nUsers 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.\n\nAI 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.\n\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/01_1_6c0d97eb51.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/01_2_8c428a25dc.jpg)\n\n\n## Integration Guide\nThis guide walks you through:\n\nWorkflow for AI Face Lift API:\n\n**Endpoint:** `/s2s/v2.0/task/face-lift`\n\n**Authentication Required:** `Authorization: Bearer YOUR_API_KEY`\n\n**Workflow Steps:**\n\n1. **Image Upload Preparation:**\n - The process begins with preparing a selfie image.\n\n2. **Optional Preprocessing For Multiple Faces:**\n - Preprocess the selfie image if there are more than one face in the image.\n\n3. **Face Lift Effect Setup:**\n - Begin by selecting suitable face lift parameters.\n\n4. **Initiate AI Task and Obtain Task ID:**\n - Send the uploaded image(s) along with the chosen effect configuration via an HTTP POST request to `/s2s/v2.0/file`.\n - Await a unique task ID in the response, which identifies this interaction.\n\n5. **Poll Task Status (Continuous Check):**\n - Use the obtained `task_id` to periodically poll the task status using an HTTP GET request (e.g., `GET /task/${task_id}`).\n - Continuously monitor for:\n - `Task_status = \"success\"` (process completed).\n - `Task_status = \"error\"` (resolve or retry if applicable).\n - Update the workflow accordingly once the status transitions to success.\n\nThis structured workflow ensures efficient integration with user inputs, automated monitoring of tasks, and seamless retrieval of results.\n\n\n---\n\n* Authentication\n- Include your API key in the request header using **Bearer Token**:\n ```\n Authorization: Bearer YOUR_API_KEY\n ```\nYou can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.\n\n\n* 1. Upload an Image\n\nYou may upload a file directly to the server or provide a valid image URL in the AI task payload.\n\n * Upload Endpoint\n\n```\nPOST /s2s/v2.0/file\n```\n\nAlternatively, skip this step if you already have a public image URL.\n\n---\n\n* 2. Select the target face to be enhanced by preprocessing\n\n * Calling the preprocessing API\nOutput detected bounding boxes in pixel coordinate. Use the index of result to create a Face Lift AI task later.\n```\nPOST /s2s/v2.0/task/face-lift/pre-process\n```\n\n```\n{\n \"timed\": number,\n \"result\": [\n {\n \"left\": number,\n \"top\": number,\n \"width\": number,\n \"height\": number\n }\n ]\n}\n```\n\n* 3. Create a Face Lift AI Task and Poll for Results\n\nOnce 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`.\n\n * Create Task Endpoint\n\n```\nPOST /s2s/v2.0/task/face-lift\n```\n\n * Polling Endpoint\n\n```\nGET /s2s/v2.0/task/face-lift/{task_id}\n```\n\n---\n\n## File Specs & Errors\n\n* AI Face Lift Specification\n\n**Supported Selfie View**\nImages 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.\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_face_reshape_01_85c8ffc055.jpg)\n\n\n---\n\n* Supported Formats & Dimensions\n\n| AI Feature | Supported Dimensions | Supported File Size | Supported Formats|\n| ---- | ---- | ---- | ---- |\n| AI Face Lift | long side <= 1920 | < 10MB | jpg/jpeg/png |\n\n* Error Codes\n\n| Error Code | Description |\n| ---- | ---- |\n| RUNTIME_ERROR | An unexpected error occurred duface lift runtime |\n| PHOTO_DETECTION_FAIL | The user photo could not be processed correctly, for example no hand detected |\n| OBJECT_DETECTION_FAIL | The object photo could not be processed correctly, for example no product detected |\n| PHOTO_CHECK_INVALID | The pose or size of the user photo is invalid |\n| INPUT_ERROR | The input file format is incorrect |\n| INPUT_MAIN_IMAGE_EMPTY | A user image is required |\n\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"}},{"type":"group","fsPath":"reference/ai_smile.yaml","link":"/reference/ai_smile","routeSlug":"/reference/ai_smile","label":"AI Smile","items":[{"type":"group","label":"overview","link":"/reference/ai_smile/section/overview","routeSlug":"/reference/ai_smile/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_smile/section/overview/integration-guide","routeSlug":"/reference/ai_smile/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_smile/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_smile/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_smile/v1.0","routeSlug":"/reference/ai_smile/v1.0","items":[{"label":"Run an AI Smile task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_smile/v1.0/paths/~1s2s~1v2.0~1task~1ai-smile/post","routeSlug":"/reference/ai_smile/v1.0/paths/~1s2s~1v2.0~1task~1ai-smile/post","metadata":{"seo":{"title":"Run an AI Smile 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/ai-smile"},{"label":"Check the status of a AI Smile task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_smile/v1.0/paths/~1s2s~1v2.0~1task~1ai-smile~1{task_id}/get","routeSlug":"/reference/ai_smile/v1.0/paths/~1s2s~1v2.0~1task~1ai-smile~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Smile task.","description":"Check the status of a AI Smile task."}},"httpPath":"/s2s/v2.0/task/ai-smile/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Smile","version":"","description":"# overview\nIntroducing 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.\n\nThe AI Smile generator supports two distinct smile styles, giving users more control over the final expression.\n\n1. **smile_with_teeth_visible** \n 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.\n\n2. **closed_mouth_smile** \n 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.\n\nUsers can easily choose the smile type that best matches their photo, mood, or intended use, ensuring realistic and appealing results every time.\n\nWhether 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.\n\nUpload a face. Click once. Smile instantly.\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2024-03-22/5f25b0f7-5d43-421b-ae50-5def0de69f2a.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2024-12-16/4f4397e0-9e87-429a-8e39-a9d399b6602b.jpg)\n\n## Integration Guide\nThis guide walks you through:\n\nWorkflow for AI Smile API:\n\n**Endpoint:** `/s2s/v2.0/task/ai-smile`\n\n**Authentication Required:** `Authorization: Bearer YOUR_API_KEY`\n\n**Workflow Steps:**\n\n1. **Image Upload Preparation:**\n - The process begins with preparing a selfie image.\n\n2. **Initiate AI Task and Obtain Task ID:**\n - Send the uploaded image(s) along with the chosen effect configuration via an HTTP POST request to `/s2s/v2.0/file`.\n - Await a unique task ID in the response, which identifies this interaction.\n\n3. **Poll Task Status (Continuous Check):**\n - Use the obtained `task_id` to periodically poll the task status using an HTTP GET request (e.g., `GET /task/${task_id}`).\n - Continuously monitor for:\n - `Task_status = \"success\"` (process completed).\n - `Task_status = \"error\"` (resolve or retry if applicable).\n - Update the workflow accordingly once the status transitions to success.\n\nThis structured workflow ensures efficient integration with user inputs, automated monitoring of tasks, and seamless retrieval of results.\n\n\n---\n\n* Authentication\n- Include your API key in the request header using **Bearer Token**:\n ```\n Authorization: Bearer YOUR_API_KEY\n ```\nYou can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.\n\n\n* 1. Upload an Image\n\nYou may upload a file directly to the server or provide a valid image URL in the AI task payload.\n\n * Upload Endpoint\n\n```\nPOST /s2s/v2.0/file\n```\n\nAlternatively, skip this step if you already have a public image URL.\n\n---\n\n* 2. Create a Face Lift AI Task and Poll for Results\n\nOnce 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`.\n\n * Create Task Endpoint\n\n```\nPOST /s2s/v2.0/task/ai-smile\n```\n\n * Polling Endpoint\n\n```\nGET /s2s/v2.0/task/ai-smile/{task_id}\n```\n\n---\n\n## File Specs & Errors\n\n* AI Smile Specification\n\n**Supported Selfie View**\nOnly 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.\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_face_reshape_01_85c8ffc055.jpg)\n\n\n---\n\n* Supported Formats & Dimensions\n\n| AI Feature | Supported Dimensions | Supported File Size | Supported Formats|\n| ---- | ---- | ---- | ---- |\n| AI Smile | long side <= 4096 | < 10MB | jpg/jpeg/png/heic |\n\n\n* Error Codes\n\n| Error Code | Description |\n| ---------- | ----------- |\n| EXCEED_MAX_FILESIZE | The input file exceeds the maximum allowed size. |\n| INVALID_PARAMETER | One or more required parameters are missing, empty, or improperly formatted. |\n| ERROR_DOWNLOAD_IMAGE | The source image could not be downloaded. |\n| ERROR_NO_FACE | No face was detected in the provided image. |\n| ERROR_INFERENCE | The inference process failed due to a workflow issue, execution error, encoding error, or missing output image. |\n| UNKNOWN_INTERNAL_ERROR | An unexpected internal error occurred. |\n\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"}},{"type":"group","fsPath":"reference/ai_fitzpatrick_skin_type.yaml","link":"/reference/ai_fitzpatrick_skin_type","routeSlug":"/reference/ai_fitzpatrick_skin_type","label":"AI Fitzpatrick Skin Type Analysis","items":[{"type":"group","label":"Overview","link":"/reference/ai_fitzpatrick_skin_type/section/overview","routeSlug":"/reference/ai_fitzpatrick_skin_type/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_fitzpatrick_skin_type/section/overview/integration-guide","routeSlug":"/reference/ai_fitzpatrick_skin_type/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_fitzpatrick_skin_type/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_fitzpatrick_skin_type/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V2.0","link":"/reference/ai_fitzpatrick_skin_type/v2.0","routeSlug":"/reference/ai_fitzpatrick_skin_type/v2.0","items":[{"label":"Run an AI Fitzpatrick Scale Analyzer detection task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_fitzpatrick_skin_type/v2.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer~1pre-process/post","routeSlug":"/reference/ai_fitzpatrick_skin_type/v2.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer~1pre-process/post","metadata":{"seo":{"title":"Run an AI Fitzpatrick Scale Analyzer detection task.","description":"Use the pre-process task when the source image may contain more than one valid target, or when your integration needs to explicitly choose which detected target receives the effect. For single-target images, pre-process can be skipped when the feature supports a default index value and your application does not need manual target selection."}},"httpPath":"/s2s/v2.0/task/fitzpatrick-scale-analyzer/pre-process"},{"label":"Check the status of a AI Fitzpatrick Scale Analyzer detection task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_fitzpatrick_skin_type/v2.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer~1pre-process~1{task_id}/get","routeSlug":"/reference/ai_fitzpatrick_skin_type/v2.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer~1pre-process~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Fitzpatrick Scale Analyzer detection task.","description":"Check the status of a AI Fitzpatrick Scale Analyzer detection task."}},"httpPath":"/s2s/v2.0/task/fitzpatrick-scale-analyzer/pre-process/{task_id}"},{"label":"Run an AI Fitzpatrick Scale Analyzer task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_fitzpatrick_skin_type/v2.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer/post","routeSlug":"/reference/ai_fitzpatrick_skin_type/v2.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer/post","metadata":{"seo":{"title":"Run an AI Fitzpatrick Scale Analyzer 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/fitzpatrick-scale-analyzer"},{"label":"Check the status of a AI Fitzpatrick Scale Analyzer task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_fitzpatrick_skin_type/v2.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer~1{task_id}/get","routeSlug":"/reference/ai_fitzpatrick_skin_type/v2.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Fitzpatrick Scale Analyzer task.","description":"Check the status of a AI Fitzpatrick Scale Analyzer task."}},"httpPath":"/s2s/v2.0/task/fitzpatrick-scale-analyzer/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Fitzpatrick Skin Type Analysis","version":"","description":"# Overview\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2026-01-28/webp_a00e88ca-e20a-4082-89c2-9d486b03b8e8.webp)\n\n**AI Fitzpatrick Skin Type Analysis**\n\nIntegrate 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.\n\n**Skin Type Detection**\n\nThe 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.\n\nThe 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.\n\n**Classification Output**\n\nThe API returns one of six standardized skin types from Type I to Type VI based on UV response modeling.\n\nThis output enables developers to deliver tailored product recommendations, automate skincare workflows, and enhance personalization logic across user experiences while maintaining consistency and scalability.\n\n| Fitzpatrick Scale | Skin Type | Skin Reaction to Sun |\n| ---- | ---- | ---- |\n| Type I | White | Almost always burns, never tans |\n| Type II | Beige | Usually burns, tans minimally |\n| Type III | Light Brown | Sometimes burns, gradually tans |\n| Type V | Medium Brown | Rarely burns, tans easily |\n| Type V | Dark Brown | Very rarely burns |\n| Type VI | Very Dark Brown | Almost never burns |\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/fitapatrick_skin_type_S_02_enu_5e4343e801.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2026-03-10/webp_b9ca4198-1a9e-44df-9551-ac3ad8b65d17.webp)\n\n---\n\n## Integration Guide\n\n**1. Capture Image**\nCapture a front facing image with adequate lighting. Ensure the face is clearly visible and occupies a sufficient portion of the frame.\n\n\n**2. Upload Image**\nRequest upload URLs and file IDs via:\n\n```\nPOST /s2s/v2.0/file\n```\n\nUpload the image using the returned URL.\nAlternatively, provide a publicly accessible image URL hosted on your own storage.\n\n\n**3. Optional Preprocessing**\n\n```\nPOST /s2s/v2.0/task/fitzpatrick-scale-analyzer/pre-process\n```\n\nUse 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.\n\n\n**4. Retrieve Preprocess Result**\n\n```\nGET /s2s/v2.0/task/fitzpatrick-scale-analyzer/pre-process\n```\n\nConfigure 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.\n\n**5. Execute Analysis Task**\n\n```\nPOST /s2s/v2.0/task/fitzpatrick-scale-analyzer\n```\n\nSubmit the task using file IDs or image URLs as input. The response returns a task_id for tracking and retrieving the result.\n\n\n**6. Retrieve Task Result**\n\n```\nGET /s2s/v2.0/task/fitzpatrick-scale-analyzer/{task_id}\n```\n\nUse the task ID to track status and obtain results.\n\n[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.\n\nUsage is only charged when the task completes successfully.\n\n---\n\n## File Specs & Errors\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n| 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 |\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| error_below_min_image_size | Source image dimensions must be at least 320 pixels. |\n|error_face_position_invalid|Your face needs to be fully visible in the image, without any parts cut off|\n|error_face_position_too_small|The face in your photo is too small to analyze properly|\n|error_face_position_out_of_boundary|Your face is either too large or partially outside the edges of the photo|\n|error_insufficient_lighting|The lighting is too dim, which makes analysis difficult|\n|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|\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"}},{"type":"group","fsPath":"reference/ai_abs_filter.yaml","link":"/reference/ai_abs_filter","routeSlug":"/reference/ai_abs_filter","label":"AI Abs Filter","items":[{"type":"group","label":"Overview","link":"/reference/ai_abs_filter/section/overview","routeSlug":"/reference/ai_abs_filter/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_abs_filter/section/overview/integration-guide","routeSlug":"/reference/ai_abs_filter/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_abs_filter/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_abs_filter/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_abs_filter/v1.0","routeSlug":"/reference/ai_abs_filter/v1.0","items":[{"label":"Run an AI Abs Filter task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_abs_filter/v1.0/paths/~1s2s~1v2.0~1task~1abs-shape/post","routeSlug":"/reference/ai_abs_filter/v1.0/paths/~1s2s~1v2.0~1task~1abs-shape/post","metadata":{"seo":{"title":"Run an AI Abs Filter 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/abs-shape"},{"label":"Check the status of a AI Abs Filter task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_abs_filter/v1.0/paths/~1s2s~1v2.0~1task~1abs-shape~1{task_id}/get","routeSlug":"/reference/ai_abs_filter/v1.0/paths/~1s2s~1v2.0~1task~1abs-shape~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Abs Filter task.","description":"Check the status of a AI Abs Filter task."}},"httpPath":"/s2s/v2.0/task/abs-shape/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Abs Filter","version":"","description":"# Overview\n\nThe **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.\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2024-09-27/daf70f5e-a350-46a3-8b6c-f63bd60c6cf0.jpg)\n\nSupported modes:\n\n- `Six-pack`: Adds visible six-pack abs for a more muscular torso appearance.\n- `Vest-line`: Enhances central abdominal muscle definition for a fit, athletic look.\n\n---\n\n## Integration Guide\n\n**Input Requirements & Processing Criteria:**\n\n- Upload a full-body or upper-body image.\n- Select an enhancement mode: `Six-pack` or `Vest-line`.\n- Choose the desired abdominal enhancement intensity level.\n- Maximum long-side image resolution must not exceed **4096 px**.\n- Source file size must be less than **10 MB**.\n- At least one detectable person is required, with both shoulders visible.\n- The abdomen must be visible, either clothed or unclothed.\n- Supported pose range: `−45° < yaw < 45°`.\n- Single-person processing is supported. If multiple people appear in the image, the API automatically selects the person with the largest visible shoulder area.\n\n**Workflow:**\n\n1. Upload file metadata using the File API.\n2. Retrieve the signed upload URL from the response.\n3. Upload the actual image to the returned URL.\n4. Create an AI task for abs-shape enhancement.\n5. Setup a Webhook or Poll the task status until completion.\n6. Download the generated result image when processing is successful.\n\n---\n\n**Step 1 — Upload File Metadata Using the File API**\n\nUse `POST /s2s/v2.0/file` to create a file record and receive upload details for the source image.\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/jpg\",\n \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\n \"file_size\": 547541\n }\n ]\n }'\n```\n\n**File API Sample Response:**\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"files\": [\n {\n \"content_type\": \"image/jpg\",\n \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\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/jpg\"\n }\n }\n ]\n }\n ]\n }\n}\n```\n\n---\n\n**Step 2 — Retrieve File API Response Details**\n\nThe response contains:\n\n| Field | Description |\n| --- | --- |\n| `file_id` | Identifier used to create the AI task. |\n| `requests.url` | Signed URL for uploading the actual image file. |\n| `requests.method` | Upload method, usually `PUT`. |\n| `requests.headers` | Required headers for the upload request. |\n\n---\n\n**Step 3 — Upload Image to Provided URL**\n\nUse the `requests.url` from the File API response to upload the source image.\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n --header 'Content-Type: image/jpg' \\\n --header 'Content-Length: 547541' \\\n --data-binary @'./full_body_photo_01_3dbd1b6683.jpg'\n```\n\n---\n\n**Step 4 — Create an AI Task**\n\nUse `POST /s2s/v2.0/task/abs-shape` to create the abs-enhancement task.\n\n| Parameter | Description | Example |\n| --- | --- | --- |\n| `src_file_id` | File ID returned from the File API upload flow. Required when using uploaded-file workflow. | `\"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\"` |\n| `src_file_url` | Direct URL of the source image. Use this alternative to `src_file_id`. | `\"https://example.com/selfie.jpg\"` |\n| `mode` | Enhancement mode. Supported values are `Six-pack` and `Vest-line`. | `\"Six-pack\"` |\n| `intensity` | Abdominal enhancement intensity level. | `1` |\n\n**Example Request:**\n\n```javascript\nconst resp = await fetch(\n 'https://yce-api-01.makeupar.com/s2s/v2.0/task/abs-shape',\n {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n Authorization: 'Bearer '\n },\n body: JSON.stringify({\n src_file_url: 'https://example.com/selfie.jpg',\n mode: 'Six-pack',\n intensity: 1\n })\n }\n);\n\nconst data = await resp.json();\nconsole.log(data);\n```\n\n**AI Task API 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 5 — Setup a Webhook or Poll for Task Result**\n\nSee the [webhook integration guide](/develop/webhook.md) for setup and verification details.\n\nFor polling, use the returned `task_id` to check task status.\n\n```bash\ncurl --request GET \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/abs-shape/ \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json'\n```\n\n---\n\n**Step 6 — Retrieve Result Image**\n\nWhen processing is successful, the response includes a download URL in `data.results.url`.\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"error\": null,\n \"results\": {\n \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n },\n \"task_status\": \"success\"\n }\n}\n```\n\n**Invalid API Key Response:**\n\nIf the access token is invalid, the API returns a `401` response.\n\n```json\n{\n \"status\": 401,\n \"error\": \"Unauthorized\",\n \"error_code\": \"InvalidAccessToken\"\n}\n```\n\nUse cases:\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-08-21/307f87b4-d31c-481c-86f1-478c93265a95.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-08-21/8ab8eca4-b825-4692-aef0-6ffd6176e272.jpg)\n\n---\n\n## File Specs & Errors\n\n**File Specifications:**\n\n| Specification | Requirement |\n| --- | --- |\n| Image type | Full-body or upper-body image. |\n| Source subject | One detectable person with both shoulders visible and abdomen visible. |\n| Pose requirement | Supported pose range is `−45° < yaw < 45°`. |\n| Multi-person handling | If multiple people are detected, the API automatically selects the person with the largest visible shoulder area. |\n| Maximum long-side resolution | Long side must not exceed **4096 px**. |\n| File size limit | Must be less than **10 MB**. |\n| Supported formats | `jpg`, `png`. |\n\n**Error Codes:**\n\n| Error Code | Description |\n| --- | --- |\n| `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. |\n| `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. |\n| `error_nsfw_content_detected` | Potential NSFW content was detected in the source image or generated result image. |\n| `invalid_parameter` | Invalid parameters were provided for source keys, destination keys, actions, mode values, intensity levels, or task configuration. |\n| `error_download_image` | The source image could not be downloaded successfully. |\n| `error_decode_image` | The source image could not be decoded successfully. |\n\n**Environment & Dependencies:**\n\n| Tool / Language | Recommended Runtime Versions |\n| --- | --- |\n| cURL | Bash ≥ 3.2; curl ≥ 7.58 with modern TLS/HTTP support; jq ≥ 1.6 for robust JSON parsing. |\n| Node.js | Node ≥ 18 for global `fetch` support. |\n| JavaScript Browser Support | Chrome / Edge ≥ 80, Firefox ≥ 74, Safari ≥ 13.1. |\n| PHP | PHP ≥ 7.4 with modern TLS compatibility; ext-curl recommended or `allow_url_fopen=On` with OpenSSL and JSON support. |\n| Python | Python ≥ 3.10 for f-strings; requests ≥ 2.20.0. |\n| Java | Java 11+ for HttpClient; Jackson Databind ≥ 2.12.0. |\n"}},{"type":"separator","label":"Beauty"},{"type":"group","fsPath":"reference/ai_makeup_transfer.yaml","link":"/reference/ai_makeup_transfer","routeSlug":"/reference/ai_makeup_transfer","label":"AI Makeup Transfer","items":[{"type":"group","label":"Overview","link":"/reference/ai_makeup_transfer/section/overview","routeSlug":"/reference/ai_makeup_transfer/section/overview","items":[{"type":"link","label":"File Specs & Errors","link":"/reference/ai_makeup_transfer/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_makeup_transfer/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_makeup_transfer/v1.0","routeSlug":"/reference/ai_makeup_transfer/v1.0","items":[{"label":"Run an AI Makeup Transfer task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_makeup_transfer/v1.0/paths/~1s2s~1v2.0~1task~1mu-transfer/post","routeSlug":"/reference/ai_makeup_transfer/v1.0/paths/~1s2s~1v2.0~1task~1mu-transfer/post","metadata":{"seo":{"title":"Run an AI Makeup Transfer 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/mu-transfer"},{"label":"Check a AI Makeup Transfer task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_makeup_transfer/v1.0/paths/~1s2s~1v2.0~1task~1mu-transfer~1{task_id}/get","routeSlug":"/reference/ai_makeup_transfer/v1.0/paths/~1s2s~1v2.0~1task~1mu-transfer~1{task_id}/get","metadata":{"seo":{"title":"Check a AI Makeup Transfer task status.","description":"Check a AI Makeup Transfer task status."}},"httpPath":"/s2s/v2.0/task/mu-transfer/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Makeup Transfer","version":"","description":"# Overview\nJust 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!\n\nFirst, upload a photo of yourself where your face and its features are clearly visible as the target image.\n\nThen, upload a photo of your favorite makeup look as the reference image. \n\nThere you have it - an AI Makeup Transferred photo. \n\nSamples:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/YCE_web_Makeup_Transfer_s1_img_be53c5c345.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2024-06-24/fda62e5d-ba58-4ecf-838a-c7d5f804c77b.jpg)\n\n---\n\n## File Specs & Errors\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|AI Makeup Transfer|1024x1024 (long side <= 1024), single face only, need to show full face|< 10MB|jpg/jpeg/png|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n|error_src_no_face\t|No face detected in the user image\n|error_ref_no_face\t|No face detected in the reference image\n|error_src_face_too_small\t|Face in the user image is too small\n|error_ref_face_too_small\t|Face in the reference image is too small\n|error_src_large_face_angle\t|Frontal face required in the user image\n|error_ref_large_face_angle\t|Frontal face required in the reference image\n|error_src_eye_closed\t|Eye is closed in the user image\n|error_ref_eye_closed\t|Eye is closed in the reference image\n|error_src_eye_occluded\t|Eye is occluded in the user image\n|error_ref_eye_occluded\t|Eye is occluded in the reference image\n|error_src_lip_occluded\t|Lip is occluded in the user image\n|error_ref_lip_occluded\t|Lip is occluded in the reference image\n|error_inappropriate_ref_case01\t|For both eyes, hair is too close to eye or skin region beside eyetail is not large enough in the reference image\n|error_inappropriate_ref_case02\t|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\n"}},{"type":"group","fsPath":"reference/makeup_vto.yaml","link":"/reference/makeup_vto","routeSlug":"/reference/makeup_vto","label":"AI Makeup Virtual Try-On","items":[{"type":"group","label":"Overview","link":"/reference/makeup_vto/section/overview","routeSlug":"/reference/makeup_vto/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/makeup_vto/section/overview/integration-guide","routeSlug":"/reference/makeup_vto/section/overview/integration-guide"},{"type":"link","label":"Inputs & Outputs","link":"/reference/makeup_vto/section/overview/inputs-and-outputs","routeSlug":"/reference/makeup_vto/section/overview/inputs-and-outputs"},{"type":"link","label":"Example Payload","link":"/reference/makeup_vto/section/overview/example-payload","routeSlug":"/reference/makeup_vto/section/overview/example-payload"},{"type":"link","label":"File Specs & Errors","link":"/reference/makeup_vto/section/overview/file-specs-and-errors","routeSlug":"/reference/makeup_vto/section/overview/file-specs-and-errors"},{"type":"link","label":"JS Camera Kit","link":"/reference/makeup_vto/section/overview/js-camera-kit","routeSlug":"/reference/makeup_vto/section/overview/js-camera-kit"}]},{"type":"group","label":"V1.0","link":"/reference/makeup_vto/v1.0","routeSlug":"/reference/makeup_vto/v1.0","items":[{"label":"Run an AI Makeup Virtual Try On task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/makeup_vto/v1.0/paths/~1s2s~1v2.0~1task~1makeup-vto/post","routeSlug":"/reference/makeup_vto/v1.0/paths/~1s2s~1v2.0~1task~1makeup-vto/post","metadata":{"seo":{"title":"Run an AI Makeup Virtual Try On task.","description":"This endpoint initiates the makeup virtual try-on process. You must provide a source file (via URL or File ID) and specify the effects to apply using the defined effect schemas. The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/makeup-vto"},{"label":"Check the status of a AI Makeup Virtual Try On task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/makeup_vto/v1.0/paths/~1s2s~1v2.0~1task~1makeup-vto~1{task_id}/get","routeSlug":"/reference/makeup_vto/v1.0/paths/~1s2s~1v2.0~1task~1makeup-vto~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Makeup Virtual Try On task.","description":"Check the status of a AI Makeup Virtual Try On task."}},"httpPath":"/s2s/v2.0/task/makeup-vto/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Makeup Virtual Try-On","version":"","description":"# Overview\nThe 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.\n\n**Key Features:**\n* **Hyper-realistic Rendering:** Leverages revolutionary 3D face AI technology for the most realistic makeovers.\n* **Patented Technology:** Powered by jitter-free, lag-free deep learning algorithms optimized for all ages and ethnicities.\n* **Real-time Precision:** Ultra-precise facial tracking that adapts to various lighting conditions.\n* **True-to-life Matching:** Accurately matches real-world product colors, textures (from matte to metallic), and finishes.\n\n* Core Concepts\n\n * Color Blending\nOur 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.\n\n * Texture & Finish Matching\nThe 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.\n\n * Light Balancing\nThe 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.\n\n---\n\n## Integration Guide\n\nThe 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.\n\n* **Endpoint:** `/v2.0/task/makeup-vto`\n* **Authentication:** All requests require an `Authorization: Bearer `\n* **Workflow:**\n 1. **Prepare a selfie:** Upload an image or use existing file url of a face image.\n 1. **Start Task (`POST`):** Submit your image id/URL and makeup configuration.\n 1. **Retrieve Task ID:** Capture the `task_id` from the response.\n 1. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `\"success\"` or `\"error\"`.\n\n\n* API Playground\n\nInteractively explore and test the API using our official playground:\n\n**API Playground:**\n[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/)\n\n---\n\n* Authentication\n- Include your API key in the request header using **Bearer Token**:\n ```\n Authorization: Bearer \n ```\nYou can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.\n\n* 1. Upload a Selfie\n You can provide the source image in one of two ways:\n\n - **Use an Existing Public Image URL**\n Instead of uploading, you may supply a publicly accessible image URL directly when initiating the AI task.\n\n - **Upload via File API**\n Use the endpoint:\n ```\n POST /s2s/v2.0/file\n ```\n This returns a `file_id` for subsequent task execution.\n\n - ***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.

\n 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.\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* 2. Start Makeup Task\n\n`POST /s2s/v2.0/task/makeup-vto`\n\nInitiates a new virtual makeup task on the provided image. This endpoint is asynchronous and returns with a `task_id`.\n\n * Request Headers\n\n| Header | Value |\n|--------|-------|\n| Content-Type | `application/json` |\n| Authorization | `Bearer YOUR_API_KEY` |\n\n * Example Request Body\n```json\n{\n \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/sample_Image_1_202b6bf6e6.jpg\",\n \"effects\": [\n {\n \"category\": \"blush\",\n \"pattern\": { \"name\": \"2colors6\" },\n \"palettes\": [\n { \"color\": \"#FF0000\", \"texture\": \"matte\", \"colorIntensity\": 50 },\n { \"color\": \"#F2A53E\", \"texture\": \"matte\", \"colorIntensity\": 50 }\n ]\n },\n {\n \"category\": \"eye_liner\",\n \"pattern\": { \"name\": \"3colors5\" },\n \"palettes\": [\n { \"color\": \"#000000\", \"texture\": \"matte\", \"colorIntensity\": 50 },\n { \"color\": \"#BA0656\", \"texture\": \"matte\", \"colorIntensity\": 50 },\n { \"color\": \"#089085\", \"texture\": \"matte\", \"colorIntensity\": 50 }\n ]\n }\n ],\n \"version\": \"1.0\"\n}\n```\n\n * Request Body Schema\n\n| Field | Type | Description |\n|-------|------|---------|\n| `src_file_url` | string (URL) | A publicly accessible URL to the selfie image to be processed. |\n| `effects` | array of Effect | An array of makeup effects objects to apply. See [Makeup Effect Schemas](#makeup-effect-schemas) for details. |\n| `version` | string | The API version of the effect payload structure. Use `\"1.0\"`. |\n\n * Successful Response (`200 OK`)\nReturns a JSON object containing the task identifier.\n\n**Response Body Schema:**\n```json\n{\n \"status\": 200,\n \"data\": {\n \"task_id\": \"\"\n }\n}\n```\n\n**Example Response:**\n```json\n{\n \"status\": 200,\n \"data\": {\n \"task_id\": \"grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe\"\n }\n}\n```\n\n * Error Responses (`400 Bad Request`, `401 InvalidApiKey`, etc.)\nA standard error object will be returned with a message describing the failure.\n\n**Example Error Response:**\n```json\n{\n \"status\": 400,\n \"error\": \"The operation could not be completed\",\n \"error_code\": \"CreditInsufficiency\"\n}\n```\n\n---\n\n* 3. Get Task Status & Results\n\n`GET /s2s/v2.0/task/makeup-vto/`\n\nRetrieves the current status and results of an in-progress or completed task.\n\n * Request Headers\n\n| Header | Value |\n|--------|-------|\n| Authorization | `Bearer YOUR_API_KEY` |\n\n * Path Parameters\n\n| Parameter | Type | Description |\n|-----------|------|---------|\n| task_id | string | The identifier returned from the start-task endpoint. |\n\n * Successful Response (`200 OK`)\nA JSON object containing the status and, if completed, the results.\n\n**Response Body Schema:**\n```json\n{\n \"data\": {\n \"task_status\": \"\", // 'success', 'error', or a processing state (e.g., 'queued', 'processing')\n \"results\": [ // present only when task_status is 'success'\n {\n \"download_url\": \"\" // URL to download the processed image\n }\n ],\n \"failure_reason\": \"\" // present only when task_status is 'error'\n }\n}\n```\n\n**Example Success Response:**\n```json\n{\n \"status\": 200,\n \"data\": {\n \"task_status\": \"success\",\n \"results\": {\n \"url\": \"https://s3.storage.prod/processed/image_123.jpg?token=...\"\n }\n }\n}\n```\n\n**Example Engine Error Response:**\nThe API query was sent successfully; however, an error occurred while executing the AI task.\n```json\n{\n \"status\": 200,\n \"data\": {\n \"task_status\": \"error\",\n \"error\": \"exceed_max_filesize\",\n \"error_message\": \"string\",\n }\n}\n```\n > Please note that no units will be consumed if an error occurs, whether it is a query error or an engine error.\n\n**Example In-Progress Response:**\n```json\n{\n \"status\": 200,\n \"data\": {\n \"task_status\": \"running\"\n }\n}\n```\n\n * Error Responses\n* `404 InvalidTaskId`: The `task_id` does not exist or is invalid.\n* `401 InvalidApiKey`: The API key is invalid or missing.\n* `500 TaskTimeout`: The task has either completed successfully or failed and has exceeded the retention period.\n\n**Example Query Error Response:**\n```json\n{\n \"status\": 401,\n \"error_code\": \"InvalidApiKey\"\n}\n```\n > Please note that no units will be consumed if an error occurs, whether it is a query error or an engine error.\n\n---\n\n## Inputs & Outputs\n* Makeup Effect Schema\n\nThis 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.\n\n* Effect Container (Top Level)\n\n```json\n{\n \"version\": \"1.0\",\n \"effects\": [] // array — Contains makeup effect objects\n}\n```\n\n* Makeup Effect Categories\n\n * `skin_smooth`\n```json\n{\n \"category\": \"skin_smooth\", // string, const \"skin_smooth\"\n \"skinSmoothStrength\": 50, // integer, range: 0..100\n \"skinSmoothColorIntensity\": 50 // integer, range: 0..100\n}\n```\n > **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.\n 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.\n\n * `blush`\n```json\n{\n \"category\": \"blush\", // string, const \"blush\"\n \"pattern\": { // object\n \"name\": \"\" // string — MUST equal a `label` from blush.json\n },\n \"palettes\": [ // array, minItems: (see colorNum in pattern)\n {\n \"color\": \"#ff0000\", // string, hex color \"#RRGGBB\"\n \"texture\": \"matte\", // string, enum [\"matte\",\"satin\",\"shimmer\"]\n \"glowStrength\": 50, // integer, range: 0..100 — REQUIRED if texture=\"satin\"\n \"shimmerColor\": \"#fc288f\", // string, hex color \"#RRGGBB\" — REQUIRED if texture=\"shimmer\"\n \"shimmerDensity\": 50, // integer, range: 0..100 — REQUIRED if texture=\"shimmer\"\n \"colorIntensity\": 50 // integer, range: 0..100\n }\n ]\n}\n```\n\n**Full Pattern Catalog:**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/blush.json\n\n**Distinct Makeup Pattern Categories:**\n```json\n[\n {\n \"category\": \"1 color\",\n \"label\": \"1color1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/483/a53cd4f4-43b6-4e19-b85a-ec7a95c6a47f.jpg\",\n \"tags\": [\n { \"id\": 100, \"name\": \"Blush 3D\" },\n { \"id\": 103, \"name\": \"Oblong\" }\n ],\n \"colorNum\": 1\n },\n {\n \"category\": \"2 colors\",\n \"label\": \"2colors1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/147/a8d86a4b-8aa0-48d7-a716-63ec78dfb30b.jpg\",\n \"tags\": [\n { \"id\": 100, \"name\": \"Blush 3D\" }\n ],\n \"colorNum\": 2\n },\n {\n \"category\": \"3 colors\",\n \"label\": \"3colors1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/734/af8b625b-ae3a-4211-9413-f22c16a5f174.jpg\",\n \"tags\": [\n { \"id\": 100, \"name\": \"Blush 3D\" },\n { \"id\": 104, \"name\": \"Round\" }\n ],\n \"colorNum\": 3\n }\n]\n```\n\n\n * `bronzer`\n```json\n{\n \"category\": \"bronzer\", // string, const \"bronzer\"\n \"pattern\": { \"name\": \"\" }, // object — name MUST equal a `label` from bronzer.json\n \"palettes\": [\n { \"color\": \"#ff0000\", \"colorIntensity\": 50 } // hex color, int range: 0..100\n ]\n}\n```\n\n**Full Pattern Catalog:**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/bronzer.json\n\n**Distinct Makeup Pattern Categories:**\n```json\n[\n {\n \"category\": \"Bronzer\",\n \"label\": \"Bronzer1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/973/22ff2c07-d584-4ae6-8281-c095cd121a52.jpg\",\n \"tags\": [],\n \"colorNum\": 1\n }\n]\n```\n\n * `concealer`\n```json\n{\n \"category\": \"concealer\", // string, const \"concealer\"\n \"palettes\": [\n {\n \"color\": \"#ff0000\", // string, hex color \"#RRGGBB\"\n \"colorIntensity\": 50, // integer, range: 0..100\n \"colorUnderEyeIntensity\": 50, // integer, range: 0..100\n \"coverageLevel\": 50 // integer, range: 0..100\n }\n ]\n}\n```\n\n * `contour`\n```json\n{\n \"category\": \"contour\", // string, const \"contour\"\n \"pattern\": { \"name\": \"\" }, // object — name MUST equal a `label` from contour.json\n \"palettes\": [\n { \"color\": \"#ff0000\", \"colorIntensity\": 50 } // hex color, int range: 0..100\n ]\n}\n```\n\n**Full Pattern Catalog:**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/contour.json\n\n**Distinct Makeup Pattern Categories:**\n```json\n[\n {\n \"category\": \"Heart face\",\n \"label\": \"HeartFace2\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/731/49a1b3b9-b393-4bf4-b486-1493fe468436.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Invtriangle\",\n \"label\": \"Invtriangle1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/858/a94c8cca-5f8c-4b8b-a02d-94edb6a4ad7f.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Oval face\",\n \"label\": \"OvalFace6\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/906/644368a3-7eee-4ad9-829e-e2b3d4320fec.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Round face\",\n \"label\": \"RoundFace4\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/106/3e455b5f-7e2d-46f7-8627-dc137051c144.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Triangle face\",\n \"label\": \"TriangleFace2\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/528/18765180-c254-4411-a25c-c1d78f5c3d77.jpg\",\n \"tags\": []\n }\n]\n```\n\n * `eyebrows`\n```json\n{\n \"category\": \"eyebrows\", // string, const \"eyebrows\"\n \"pattern\": {\n \"type\": \"shape\", // string, enum [\"shape\",\"color\"], default: \"shape\"\n \"name\": \"\", // string, required when type=\"shape\" — label from eyebrows.json\n \"curvature\": 0, // integer, range: -100..100 (shape only)\n \"thickness\": 0, // integer, range: -100..100 (shape only)\n \"definition\": 0 // integer, range: 0..100 (shape only)\n },\n \"palettes\": [\n {\n \"color\": \"#ff0000\", // string, hex color \"#RRGGBB\"\n \"colorIntensity\": 50, // integer, range: 0..100\n \"texture\": \"matte\", // string, enum [\"matte\",\"shimmer\"]\n \"shimmerColor\": \"#fc288f\", // string, hex color \"#RRGGBB\" — REQUIRED if texture=\"shimmer\"\n \"shimmerIntensity\": 50, // integer, range: 0..100 — REQUIRED if texture=\"shimmer\"\n \"shimmerSize\": 50, // integer, range: 0..100 — REQUIRED if texture=\"shimmer\"\n \"shimmerDensity\": 50 // integer, range: 0..100 — REQUIRED if texture=\"shimmer\"\n }\n ]\n}\n```\n\n**Full Pattern Catalog:**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/eyebrows.json\n\n**Distinct Makeup Pattern Categories:**\n```json\n[\n {\n \"category\": \"Arrow\",\n \"label\": \"Arrow1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/490/1fb96bf9-979e-4327-a8c4-8c503f541f1a.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Curved\",\n \"label\": \"Curved1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/389/1ccb300e-c7ed-4995-920e-7d1bf8da1fad.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Drama\",\n \"label\": \"Drama2\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/196/5fb14bec-553d-4841-bba7-ca7e5e27c12e.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"High Arch\",\n \"label\": \"HighArch1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/609/7a8676dc-6f6a-4b12-aab0-c50328e448c5.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Original\",\n \"label\": \"Original2\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/300/123551e9-ca94-4732-89ed-5b3866678555.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Soft Arch\",\n \"label\": \"SoftArch1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/121/2552ebf0-2705-43f7-b295-4fac21e18009.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Straight\",\n \"label\": \"Straight1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/1/7734e777-8e51-41f1-abaf-205f0ed5e3b4.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Thin\",\n \"label\": \"Thin1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/734/6ee10843-a251-4aa0-9183-db7f981d714d.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Upward\",\n \"label\": \"Upward4\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/751/76578317-f475-49c7-bd96-910ccad617ef.jpg\",\n \"tags\": []\n }\n]\n```\n\n * `eye_liner`\n```json\n{\n \"category\": \"eye_liner\", // string, const \"eye_liner\"\n \"pattern\": { \"name\": \"\" }, // object — name MUST equal a label from eyeliner.json\n \"palettes\": [\n {\n \"color\": \"#ff0000\", // string, hex color \"#RRGGBB\"\n \"texture\": \"matte\", // string, enum [\"matte\",\"shimmer\",\"metallic\"]\n \"shimmerColor\": \"#fc288f\", // string, hex color \"#RRGGBB\" — REQUIRED if texture in [\"shimmer\",\"metallic\"]\n \"shimmerIntensity\": 50, // integer, range: 0..100 — REQUIRED if texture in [\"shimmer\",\"metallic\"]\n \"metallicIntensity\": 50, // integer, range: 0..100 — REQUIRED if texture=\"metallic\"\n \"colorIntensity\": 50 // integer, range: 0..100\n }\n ]\n}\n```\n\n**Full Pattern Catalog:**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/eyeliner.json\n\n**Distinct Makeup Pattern Categories:**\n```json\n[\n {\n \"category\": \"2 colors\",\n \"label\": \"2colors1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/419/71d9429a-dc08-4e80-9c46-6e55631ef766.jpg\",\n \"tags\": [\n {\n \"id\": 28,\n \"name\": \"Drama\"\n }\n ],\n \"colorNum\": 2\n },\n {\n \"category\": \"3 colors\",\n \"label\": \"3colors2\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/208/056aa6cd-8678-470c-b111-b7653d7ddf93.jpg\",\n \"tags\": [\n {\n \"id\": 28,\n \"name\": \"Drama\"\n }\n ],\n \"colorNum\": 3\n },\n {\n \"category\": \"1 color\",\n \"label\": \"Arabic3\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/726/1919aad4-21a2-493a-a5f8-48bc99a61ba5.jpg\",\n \"tags\": [\n {\n \"id\": 26,\n \"name\": \"Arabic\"\n }\n ],\n \"colorNum\": 1\n }\n]\n```\n\n * `eye_shadow`\n```json\n{\n \"category\": \"eye_shadow\", // string, const \"eye_shadow\"\n \"pattern\": { \"name\": \"\" }, // object — name MUST equal a label from eyeshadow.json\n \"palettes\": [\n {\n \"color\": \"#ff0000\", // string, hex color \"#RRGGBB\"\n \"texture\": \"matte\", // string, enum [\"matte\",\"shimmer\",\"metallic\"]\n \"shimmerColor\": \"#fc288f\", // string, hex color \"#RRGGBB\" — REQUIRED if texture in [\"shimmer\",\"metallic\"]\n \"shimmerIntensity\": 50, // integer, range: 0..100 — REQUIRED if texture in [\"shimmer\",\"metallic\"]\n \"metallicIntensity\": 50, // integer, range: 0..100 — REQUIRED if texture=\"metallic\"\n \"colorIntensity\": 50 // integer, range: 0..100\n }\n ] // minItems: (see colorNum in pattern)\n}\n```\n\n**Full Pattern Catalog:**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/eyeshadow.json\n\n**Distinct Makeup Pattern Categories:**\n```json\n[\n {\n \"category\": \"1 color\",\n \"label\": \"1color1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/188/0322c4f9-e54d-4a6b-8072-6bb76560121a.jpg\",\n \"tags\": [\n {\n \"id\": 12,\n \"name\": \"Artistic\"\n },\n {\n \"id\": 14,\n \"name\": \"Dream\"\n },\n {\n \"id\": 15,\n \"name\": \"Trend\"\n }\n ],\n \"colorNum\": 1\n },\n {\n \"category\": \"2 colors\",\n \"label\": \"2colors1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/938/3348211c-1b83-4ab2-9c6a-ce06e4aa3528.jpg\",\n \"tags\": [\n {\n \"id\": 1,\n \"name\": \"Fan shape\"\n },\n {\n \"id\": 8,\n \"name\": \"Only upper lid\"\n }\n ],\n \"colorNum\": 2\n },\n {\n \"category\": \"3 colors\",\n \"label\": \"3colors1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/542/55e1b0fd-b888-47ff-bd3a-3dc1af2a7b69.jpg\",\n \"tags\": [\n {\n \"id\": 1,\n \"name\": \"Fan shape\"\n },\n {\n \"id\": 8,\n \"name\": \"Only upper lid\"\n }\n ],\n \"colorNum\": 3\n },\n {\n \"category\": \"4 colors\",\n \"label\": \"4colors1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/429/29cd5839-464b-4a7a-a5c1-c7b40e9464d7.jpg\",\n \"tags\": [\n {\n \"id\": 4,\n \"name\": \"Closed banana\"\n },\n {\n \"id\": 10,\n \"name\": \"Whole eye\"\n }\n ],\n \"colorNum\": 4\n },\n {\n \"category\": \"5 colors\",\n \"label\": \"5colors1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/2/824dcf7c-1273-4a30-8f1f-2137926057d6.jpg\",\n \"tags\": [\n {\n \"id\": 4,\n \"name\": \"Closed banana\"\n },\n {\n \"id\": 10,\n \"name\": \"Whole eye\"\n }\n ],\n \"colorNum\": 5\n }\n]\n```\n\n * `eyelashes`\n```json\n{\n \"category\": \"eyelashes\", // string, const \"eyelashes\"\n \"pattern\": { \"name\": \"\" }, // object — name MUST equal a label from eyelashes.json\n \"palettes\": [\n { \"color\": \"#ff0000\", \"colorIntensity\": 50 } // hex color, int range: 0..100\n ]\n}\n```\n\n**Full Pattern Catalog:**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/eyelashes.json\n\n**Distinct Makeup Pattern Categories:**\n```json\n[\n {\n \"category\": \"Artistic\",\n \"label\": \"Artistic1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/146/7a8ed606-1c27-4d91-9320-c40a904f621f.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Natural\",\n \"label\": \"Natural1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/287/cd5cae75-a1b3-48f8-8537-e6e259213901.png\",\n \"tags\": []\n },\n {\n \"category\": \"Upper&Lower\",\n \"label\": \"Upper&Lower1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/18/2689ea2d-725e-4fa0-8563-df874ae1a83f.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Upper\",\n \"label\": \"Upper1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/982/c99bf74e-545f-4da7-a314-f3bd84b82156.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"UpperDense\",\n \"label\": \"UpperDense1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/888/452ec863-f0a8-40e7-aa33-31c0c39f57e2.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Winged\",\n \"label\": \"Winged1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/825/36ab3859-eae5-49e4-9d97-161698bbb8bb.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Wispies\",\n \"label\": \"Wispies1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/722/a2a727f6-748c-41e7-8ac0-c9c57c18c05a.png\",\n \"tags\": []\n }\n]\n```\n\n * `foundation`\n```json\n{\n \"category\": \"foundation\", // string, const \"foundation\"\n \"palettes\": [\n {\n \"color\": \"#ff0000\", // string, hex color \"#RRGGBB\"\n \"colorIntensity\": 50, // integer, range: 0..100\n \"glowIntensity\": 50, // integer, range: 0..100\n \"coverageIntensity\": 50 // integer, range: 0..100\n }\n ]\n}\n```\n\n * `highlighter`\n```json\n{\n \"category\": \"highlighter\", // string, const \"highlighter\"\n \"pattern\": { \"name\": \"\" }, // object — name MUST equal a label from highlighter.json\n \"palettes\": [\n {\n \"color\": \"#ff0000\", // string, hex color \"#RRGGBB\"\n \"glowIntensity\": 50, // integer, range: 0..100\n \"shimmerIntensity\": 50, // integer, range: 0..100\n \"shimmerDensity\": 50, // integer, range: 0..100\n \"shimmerSize\": 50, // integer, range: 0..100\n \"colorIntensity\": 50 // integer, range: 0..100\n }\n ]\n}\n```\n\n**Full Pattern Catalog:**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/highlighter.json\n\n**Distinct Makeup Pattern Categories:**\n```json\n[\n {\n \"category\": \"Heart face\",\n \"label\": \"HeartFace4\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/246/6ca40279-79cc-4918-b48a-64306009b365.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Invtriangle\",\n \"label\": \"Invtriangle2\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/7/6b0b9760-612c-4319-bd81-855d262d8e89.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Oblong\",\n \"label\": \"Oblong11\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/862/b7279f4e-edf2-43f3-8156-561fe5a52ec3.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Oval face\",\n \"label\": \"OvalFace2\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/369/91097a05-9fd2-43cb-82e9-dd45e72b613b.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Round face\",\n \"label\": \"RoundFace3\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/520/2d3ccbe2-36c3-43df-9e78-4c2c931fa431.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Square face\",\n \"label\": \"SquareFace3\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/989/2959777b-19ca-4f4a-a023-3c8927191497.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Triangle face\",\n \"label\": \"TriangleFace3\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/765/221c1f12-c621-4567-a8ee-1433038ee8a2.jpg\",\n \"tags\": []\n }\n]\n```\n\n * `lip_color`\n```json\n{\n \"category\": \"lip_color\", // string, const \"lip_color\"\n \"shape\": { // object — driven by lipshape.json\n \"name\": \"original\" // string — MUST equal a `label` from lipshape.json\n },\n \"morphology\": { // optional object\n \"fullness\": 50, // integer, range: 0..100 (default: 0)\n \"wrinkless\": 50 // integer, range: 0..100 (default: 0)\n },\n \"palettes\": [ // minItems depends on style; often ≥1\n {\n \"color\": \"#ff0000\", // string, hex color \"#RRGGBB\"\n \"texture\": \"matte\", // string, enum [\"matte\",\"gloss\",\"holographic\",\"metallic\",\"satin\",\"sheer\",\"shimmer\"]\n \"colorIntensity\": 50, // integer, range: 0..100\n \"gloss\": 50, // int, range: 0..100 — REQUIRED if texture in [\"gloss\",\"holographic\",\"metallic\",\"sheer\",\"shimmer\"]\n \"shimmerColor\": \"#ff0000\", // string, hex color \"#RRGGBB\" — REQUIRED if texture in [\"holographic\",\"metallic\",\"shimmer\"]\n \"shimmerIntensity\": 50, // integer, range: 0..100 — REQUIRED if texture in [\"holographic\",\"metallic\",\"shimmer\"]\n \"shimmerDensity\": 50, // integer, range: 0..100 — REQUIRED if texture in [\"holographic\",\"metallic\",\"shimmer\"]\n \"shimmerSize\": 50, // integer, range: 0..100 — REQUIRED if texture in [\"holographic\",\"metallic\",\"shimmer\"]\n \"transparencyIntensity\": 50 // integer, range: 0..100 — REQUIRED if texture in [\"gloss\",\"sheer\",\"shimmer\"]\n }\n ],\n \"style\": {\n \"type\": \"full\", // string, enum [\"full\",\"ombre\",\"twoTone\"]\n \"innerRatio\": 50, // int, range: 0..100 — REQUIRED if type=\"ombre\"\n \"featherStrength\": 50 // int, range: 0..100 — REQUIRED if type=\"ombre\"\n }\n}\n```\n\n**Full Pattern Catalog:**\nhttps://plugins-media.makeupar.com/wcm-saas/shapes/lipshape.json\n\n**Distinct Makeup Pattern Categories:**\n```json\n[{\n \"category\": \"general\",\n \"label\": \"original\",\n \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/original.png\",\n \"tags\": [\n ]\n }, {\n \"category\": \"general\",\n \"label\": \"heart-shaped\",\n \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/heart-shaped.jpg\",\n \"tags\": [\n ]\n }, {\n \"category\": \"general\",\n \"label\": \"m-shaped\",\n \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/m-shaped.jpg\",\n \"tags\": [\n ]\n }, {\n \"category\": \"general\",\n \"label\": \"petal\",\n \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/petal.jpg\",\n \"tags\": [\n ]\n }, {\n \"category\": \"general\",\n \"label\": \"plump\",\n \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/plump.jpg\",\n \"tags\": [\n ]\n }, {\n \"category\": \"general\",\n \"label\": \"pouty\",\n \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/pouty.jpg\",\n \"tags\": [\n ]\n }, {\n \"category\": \"general\",\n \"label\": \"smile\",\n \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/smile.jpg\",\n \"tags\": [\n ]\n }, {\n \"category\": \"general\",\n \"label\": \"vintage\",\n \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/vintage.jpg\",\n \"tags\": [\n ]\n }\n]\n```\n\n * `lip_liner`\n```json\n{\n \"category\": \"lip_liner\", // string, const \"lip_liner\"\n \"pattern\": { \"name\": \"\" }, // object — name MUST equal a label from lipliner.json\n \"palettes\": [\n {\n \"color\": \"#ff0000\", // string, hex color \"#RRGGBB\"\n \"texture\": \"matte\", // string, enum [\"matte\",\"satin\"]\n \"colorIntensity\": 50, // integer, range: 0..100\n \"thickness\": 50, // integer, range: 0..100\n \"smoothness\": 50 // integer, range: 0..100\n }\n ]\n}\n```\n\n**Full Pattern Catalog:**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/lipliner.json\n\n**Distinct Makeup Pattern Categories:**\n```json\n[\n {\n \"category\": \"Large & Full\",\n \"label\": \"Large&Full1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/417/7ac66cb2-2c7b-451c-8284-cc77791b7001.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Larger Lower\",\n \"label\": \"LargerLower1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/878/84b2ef48-3af4-4851-86d2-b01d10db82b2.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Larger Upper\",\n \"label\": \"LargerUpper1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/867/674f9f4c-7961-462e-8cc9-9a8acaad4168.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Natural\",\n \"label\": \"Natural1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/258/7533c08a-cc9c-45ab-9294-5d5a8114037d.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Rosebud\",\n \"label\": \"Rosebud1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/47/eb95e91f-6ef1-41f7-bc4f-aecd7d780c42.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Small\",\n \"label\": \"Small1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/396/6b78e461-24a6-4c6d-afb4-88beb71f1732.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Wider\",\n \"label\": \"Wider1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/867/21f92b70-72b5-4a57-b4d7-81c5cce757a6.jpg\",\n \"tags\": []\n }\n]\n```\n\n---\n\n## Example Payload\n\nHere is a full example of a valid `effectJson` payload applying multiple effects.\n\n```json\n{\n \"version\": \"1.0\",\n \"effects\": [\n {\n \"category\": \"skin_smooth\",\n \"skinSmoothStrength\": 55,\n \"skinSmoothColorIntensity\": 45\n },\n {\n \"category\": \"blush\",\n \"pattern\": { \"name\": \"2colors1\" },\n \"palettes\": [\n {\n \"color\": \"#e19f9f\",\n \"texture\": \"matte\",\n \"colorIntensity\": 60,\n \"shimmerColor\": \"#d63252\",\n \"shimmerDensity\": 50\n },\n {\n \"color\": \"#c98a8a\",\n \"texture\": \"satin\",\n \"glowStrength\": 40,\n \"colorIntensity\": 70\n }\n ]\n },\n {\n \"category\": \"lip_color\",\n \"shape\": { \"name\": \"plump\" },\n \"morphology\": { \"fullness\": 30, \"wrinkless\": 25 },\n \"style\": { \"type\": \"full\" },\n \"palettes\": [\n {\n \"color\": \"#e11c43\",\n \"texture\": \"gloss\",\n \"colorIntensity\": 80,\n \"gloss\": 75\n }\n ]\n }\n ]\n}\n```\nIn 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`.\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|AI Makeup Virtual Try-On|long side < 1920, face width >= 100|< 10MB|jpg/jpeg/png|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n|error_below_min_image_size|the size of the source image is smaller than minimum (expect: width >= 100px, height >= 100px)\n|error_exceed_max_image_size|the size of the source image is larger than maximum (expect: width < 1920px, height < 1080px)\n|error_face_position_invalid |Please ensure your entire face is fully visible within the image|\n|error_face_position_too_small|The detected face is too small. Move closer to the camera|\n|error_face_position_out_of_boundary|The face is too large or partially outside the image frame. Adjust your position|\n|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°.|\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"}},{"type":"group","fsPath":"reference/ai_look_vto.yaml","link":"/reference/ai_look_vto","routeSlug":"/reference/ai_look_vto","label":"AI Look Virtual Try-On","items":[{"type":"group","label":"Overview","link":"/reference/ai_look_vto/section/overview","routeSlug":"/reference/ai_look_vto/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_look_vto/section/overview/integration-guide","routeSlug":"/reference/ai_look_vto/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_look_vto/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_look_vto/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_look_vto/v1.0","routeSlug":"/reference/ai_look_vto/v1.0","items":[{"label":"List predefined templates.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1template~1look-vto/get","routeSlug":"/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1template~1look-vto/get","metadata":{"seo":{"title":"List predefined templates.","description":"List predefined templates."}},"httpPath":"/s2s/v2.0/task/template/look-vto"},{"label":"Run an AI Look Virtual Try On task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1look-vto/post","routeSlug":"/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1look-vto/post","metadata":{"seo":{"title":"Run an AI Look Virtual Try On task.","description":"This endpoint initiates the look virtual try-on process using a template and source image. The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/look-vto"},{"label":"Check the status of a AI Look Virtual Try On task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1look-vto~1{task_id}/get","routeSlug":"/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1look-vto~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Look Virtual Try On task.","description":"Check the status of a AI Look Virtual Try On task."}},"httpPath":"/s2s/v2.0/task/look-vto/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Look Virtual Try-On","version":"","description":"# Overview\nThe 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.\n\n## Integration Guide\nThis guide walks you through:\n\n* **Endpoint:** `/s2s/v2.0/task/look-vto`\n* **Authentication:** All requests require an `Authorization: Bearer `\n* **Workflow:**\n 1. **Prepare a selfie:** Uploading an image or provide a valid image URL\n 1. **List look templates:** Listing available AI look templates\n 1. **Start Task (`POST`):** Submit your image id/URL and a look ``template_id``.\n 1. **Retrieve Task ID:** Capture the `task_id` from the response.\n 1. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `\"success\"` or `\"error\"`.\n\n---\n\n* API Playground\n\nInteractively explore and test the API using our official playground:\n\n**API Playground:**\n[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/)\n\n---\n\n* Authentication\n- Include your API key in the request header using **Bearer Token**:\n ```\n Authorization: Bearer \n ```\nYou can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.\n\n\n* 1. Upload an Image\n\nYou may upload a file directly to the server or provide a valid image URL in the VTO task payload.\n\n * Upload Endpoint\n\n```\nPOST /s2s/v2.0/file\n```\n\nAlternatively, skip this step if you already have a public image URL.\n\n---\n\n* 2. List Available Look Styles\n\nRetrieve all AI makeup look templates available for virtual try-on.\n\n * Endpoint\n\n```\nGET /s2s/v2.0/task/template/look-vto\n```\n\n * Query Parameters\n\n| Parameter | Description |\n| ---------------- | ------------------------------- |\n| `page_size` | Number of items per page |\n| `starting_token` | Token for pagination (optional) |\n\n * Sample Javascript Request\n\n```javascript\nconst data = null;\n\nconst xhr = new XMLHttpRequest();\nxhr.withCredentials = true;\n\nxhr.addEventListener('readystatechange', function () {\n if (this.readyState === this.DONE) {\n console.log(this.responseText);\n }\n});\n\nxhr.open('GET', 'https://yce-api-01.makeupar.com/s2s/v2.0/task/template/look-vto?page_size=20&starting_token=73a3c9e69b89');\nxhr.setRequestHeader('Authorization', 'Bearer ');\n\nxhr.send(data);\n```\n\n * Sample Successful Response\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"templates\": [\n {\n \"id\": \"good_template_001\",\n \"thumb\": \"thumbnail preview image URL\",\n \"title\": \"Berry Smooth\",\n \"category_name\": \"Daily\"\n }\n ],\n \"next_token\": 73a3c9e69b89\n }\n}\n```\n\n> **Note:** Use the `id` value (`template_id`) when creating the Look VTO task.\n\n---\n\n* 3. Create a Look VTO Task and Poll for Results\n\nOnce 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`.\n\n * Create Task Endpoint\n\n```\nPOST /s2s/v2.0/task/look-vto\n```\n\n * Polling Endpoint\n\n```\nGET /s2s/v2.0/task/look-vto/{task_id}\n```\n\n---\n\n * Sample JavaScript Implementation\n\n```javascript\nconst BASE_URL = 'https://yce-api-01.makeupar.com/s2s/v2.0/task/look-vto';\nconst START_METHOD = 'POST';\nconst HEADERS = {\n \"Content-Type\": \"application/json\",\n \"Authorization\": \"Bearer FT6Xa7xuU1SBU2ZW6pdAAUh9D093kuX3\"\n};\n\nconst sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));\n\nasync function startTask() {\n const init = {\n method: START_METHOD,\n headers: HEADERS,\n body: JSON.stringify({\n \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/sample_Image_7_fa28b2618a.jpg\",\n \"template_id\": \"all_rosy_chic\"\n })\n };\n\n const res = await fetch(BASE_URL, init);\n if (!res.ok) throw new Error(`Start request failed: ${res.status} ${res.statusText}`);\n\n const payload = await res.json().catch(() => ({}));\n const taskId = payload?.data?.task_id;\n if (!taskId) throw new Error('task_id missing: ' + JSON.stringify(payload));\n\n console.log('[startTask] Task started, id =', taskId);\n return taskId;\n}\n\nasync function pollTask(taskId, { intervalMs = 2000, maxAttempts = 300 } = {}) {\n for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n const pollUrl = `${BASE_URL}/${taskId}`;\n const res = await fetch(pollUrl, { method: 'GET', headers: HEADERS });\n\n if (!res.ok) throw new Error(`Polling failed: ${res.status} ${res.statusText}`);\n\n const payload = await res.json().catch(() => ({}));\n const status = payload?.data?.task_status;\n console.log(`[pollTask] Attempt ${attempt} status = ${status}`);\n\n if (status === 'success') {\n console.log('[pollTask] Success results:', payload?.data?.results);\n return payload;\n }\n\n if (status === 'error') {\n throw new Error('Task failed: ' + JSON.stringify(payload));\n }\n\n await sleep(intervalMs);\n }\n\n throw new Error('Polling timeout: Max attempts exceeded');\n}\n\n(async () => {\n try {\n const taskId = await startTask();\n const final = await pollTask(taskId);\n console.log('[main] Final response:', final);\n } catch (e) {\n console.error('[main] Flow error:', e);\n }\n})();\n```\n\n---\n\n * Sample Success Response\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"results\": {\n \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/.../result.jpg?...\"\n },\n \"task_status\": \"success\"\n }\n}\n```\n\nThe `results.url` field contains the final rendered virtual makeup image.\n\n---\n\n* Summary\n\n| Step | Description |\n| -------------------------- | ---------------------------------------- |\n| **1. Upload Image** | Upload directly or provide an image URL. |\n| **2. List Look Templates** | Retrieve available look styles with IDs. |\n| **3. Create VTO Task** | Submit image URL + template ID. |\n| **4. Poll for Completion** | Retrieve the final result image URL. |\n\nThis workflow ensures a reliable, developer-friendly integration for real-time virtual makeup try-on experiences.\n\n---\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|AI Look Virtual Try-On|long side < 1920, face width >= 100|< 10MB|jpg/jpeg/png|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n|error_below_min_image_size|the size of the source image is smaller than minimum (expect: width >= 100px, height >= 100px)\n|error_exceed_max_image_size|the size of the source image is larger than maximum (expect: width < 1920px, height < 1080px)\n|error_face_position_invalid |Please ensure your entire face is fully visible within the image|\n|error_face_position_too_small|The detected face is too small. Move closer to the camera|\n|error_face_position_out_of_boundary|The face is too large or partially outside the image frame. Adjust your position|\n|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°.|\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"}},{"type":"group","fsPath":"reference/ai_nail_vto.yaml","link":"/reference/ai_nail_vto","routeSlug":"/reference/ai_nail_vto","label":"AI Nail Virtual Try-On","items":[{"type":"group","label":"Overview","link":"/reference/ai_nail_vto/section/overview","routeSlug":"/reference/ai_nail_vto/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_nail_vto/section/overview/integration-guide","routeSlug":"/reference/ai_nail_vto/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_nail_vto/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_nail_vto/section/overview/file-specs-and-errors"},{"type":"link","label":"JS Camera Kit","link":"/reference/ai_nail_vto/section/overview/js-camera-kit","routeSlug":"/reference/ai_nail_vto/section/overview/js-camera-kit"}]},{"type":"group","label":"V1.0","link":"/reference/ai_nail_vto/v1.0","routeSlug":"/reference/ai_nail_vto/v1.0","items":[{"label":"Run an AI Nail Vto task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_nail_vto/v1.0/paths/~1s2s~1v2.0~1task~1nail-vto/post","routeSlug":"/reference/ai_nail_vto/v1.0/paths/~1s2s~1v2.0~1task~1nail-vto/post","metadata":{"seo":{"title":"Run an AI Nail Vto task.","description":"This endpoint initiates the nail virtual try-on process. You must provide source file(s) and reference image(s) (via URL or File ID), along with specific nail effect configurations. The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/nail-vto"},{"label":"Check the status of a AI Nail Vto task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_nail_vto/v1.0/paths/~1s2s~1v2.0~1task~1nail-vto~1{task_id}/get","routeSlug":"/reference/ai_nail_vto/v1.0/paths/~1s2s~1v2.0~1task~1nail-vto~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Nail Vto task.","description":"Check the status of a AI Nail Vto task."}},"httpPath":"/s2s/v2.0/task/nail-vto/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Nail Virtual Try-On","version":"","description":"# Overview\nThe 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.\n\n## Integration Guide\nThis guide walks you through:\n\nWorkflow for AI Nail Virtual Try On API:\n\n**Authentication Required:** `Authorization: Bearer YOUR_API_KEY`\n\n**Workflow Steps:**\n\n1. **Image Upload Preparation:**\n - The process begins with preparing a back of the hand image.\n\n2. **Nail Design Setup Options:**\n - Begin by selecting a suitable nail color. You can also choose a custom shape according to your taste.\n\n3. **Initiate AI Task and Obtain Task ID:**\n - Send the uploaded image(s) along with the chosen effect configuration via an HTTP POST request to `/s2s/v2.0/file`.\n - Await a unique task ID in the response, which identifies this interaction.\n\n4. **Poll Task Status (Continuous Check):**\n - Use the obtained `task_id` to periodically poll the task status using an HTTP GET request (e.g., `GET /task/${task_id}`).\n - Continuously monitor for:\n - `Task_status = \"success\"` (process completed).\n - `Task_status = \"error\"` (resolve or retry if applicable).\n - Update the workflow accordingly once the status transitions to success.\n\nThis structured workflow ensures efficient integration with user inputs, automated monitoring of tasks, and seamless retrieval of results.\n\n---\n\n* API Playground\n\nInteractively explore and test the API using our official playground:\n\n**API Playground:**\n[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/)\n\n---\n\n* Authentication\n- Include your API key in the request header using **Bearer Token**:\n ```\n Authorization: Bearer YOUR_API_KEY\n ```\nYou can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.\n\n\n* 1. Upload an Image\n\nYou may upload a file directly to the server or provide a valid image URL in the VTO task payload.\n\n * Upload Endpoint\n\n```\nPOST /s2s/v2.0/file\n```\n\nAlternatively, skip this step if you already have a public image URL.\n\n---\n\n* 2. Prepare an effect template\nThere are four distinct setup modes available for this purpose:\n * Customizing the color and aligning it with your current nail look\n * Utilizing a preset design and a specific shape to create your vision\n * Adding pressed-on nails and linking them with your existing original nail image\n * Providing image links for pressing-on nail products that match your preferences.\n\n * Effect Template JSON Schemas\n```\n{\n \"version\": \"1.0\",\n \"effect_type\": \"nail_polish\", // valid values: ['nail_polish', 'press_on_nails']\n \"effects\": [],\n \"ref_file_ids\": []\n}\n```\n\n * Effect Format\n- Nail Polish - Color\n```\n{\n \"sub_type\": \"color\",\n \"finger\": \"index\", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']\n \"color\": \"#ff0000\",\n \"texture\": \"cream\", // valid values: ['matte', 'cream', 'metallic', 'jelly', 'sheer', 'pearl', 'textured', 'shimmer_coarse', 'shimmer_fine']\n \"transparency\": 0, // 0-100, for textures except metallic\n \"reflection\": 0, // 0-100\n \"contrast\": 0, // 0-100\n \"roughness\": 0, // 0-100\n \"shimmer_opacity\": 0, // 0-100, for texture pearl\n \"shimmer_size\": 0, // 0-100, for texture shimmer_coarse and shimmer_fine\n \"textured_size\": 0, // 0-100, for texture textured\n}\n```\n\n- Nail Polish - Design\n```\n{\n \"sub_type\": \"design\",\n \"finger\": \"index\", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']\n \"ref_file_url\": \"\", // Optional; Either ref_file_id or ref_file_url must be filled, but only one can be selected.\n \"ref_file_index\": 0, // This field is optional unless uploading is selected. Index corresponding to ref_file_ids under the root node\n \"texture\": \"cream\", // valid values: ['matte', 'cream', 'metallic', 'jelly', 'sheer', 'pearl', 'textured', 'shimmer_coarse', 'shimmer_fine']\n \"transparency\": 0, // 0-100, only for textures except metallic\n \"reflection\": 0, // 0-100\n \"contrast\": 0, // 0-100\n \"roughness\": 0, // 0-100\n \"shimmer_opacity\": 0, // 0-100, for texture pearl\n \"shimmer_size\": 0, // 0-100, for texture shimmer_coarse and shimmer_fine\n \"textured_size\": 0, // 0-100, for texture textured\n}\n\n```\n\n- Press On Nails - Color\n * You can find the latest shape values at: https://plugins-media.makeupar.com/wcm-saas/shapes/nails.json\n```\n{\n \"sub_type\": \"color\",\n \"finger\": \"index\", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']\n \"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],\n \"length\": 1.0, // 0.8-2.15, for shapes except original\n \"color\": \"#ff0000\",\n \"texture\": \"cream\", // valid values for other shapes: ['matte', 'cream', 'metallic']\n \"reflection\": 0, // 0-100\n \"contrast\": 0, // 0-100\n \"roughness\": 0 // 0-100\n}\n```\n\n- Press on Nails - Design\n```\n{\n \"sub_type\": \"design\",\n \"finger\": \"index\", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']\n \"ref_file_url\": \"\", // Optional; Either ref_file_id or ref_file_url must be filled, but only one can be selected.\n \"ref_file_index\": 0, // This field is optional unless uploading is selected. Index corresponding to ref_file_ids under the root node\n \"texture\": \"cream\", // valid values: ['matte', 'cream', 'metallic']\n \"reflection\": 0, // 0-100\n \"contrast\": 0, // 0-100\n \"roughness\": 0, // 0-100\n}\n\n```\n\n * Effect Template Design Logic\n1. **Detect effect type** (`press_on_nails` vs `nail_polish`).\n2. **Iterate over each entry in `effects`:**\n\n *If `sub_type === \"color\"`* → map fields directly, fill missing texture‑related keys with defaults.\n *If `sub_type === \"design\"`* →\n - If the user gave a `ref_file_url`, keep it and **omit** `ref_file_index`.\n - 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).\n\n3. **Normalize numeric ranges** – clamp any out‑of‑range values to 0‑100 or length limits.\n4. **Add missing optional keys** with defaults so the schema validator passes.\n5. **Serialize** the final object as JSON (compact or pretty for debugging).\n\n * Example Payload (ready to send)\n```\n{\n \"version\": \"1.0\",\n \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/nail_user_photo_01_27d4260646.jpg\",\n \"effect_type\": \"press_on_nails\",\n \"ref_file_ids\": [\n \"Ks3kh+1nPpVNm8iJb5374CWtBzkT4B44NPJwXbBKqVxfjK3xgCQ+hRt9MJXBFaud\",\n \"+Z7PSjuzigvsc3S/Yli1A4WN7c3J6NJHFqK2iUlqD2BfjK3xgCQ+hRt9MJXBFaud\"\n ],\n \"effects\": [\n {\n \"sub_type\": \"design\",\n \"finger\": \"thumb\",\n \"texture\": \"cream\",\n \"reflection\": 100,\n \"contrast\": 50,\n \"roughness\": 0,\n \"ref_file_index\": 0\n },\n {\n \"sub_type\": \"design\",\n \"finger\": \"index\",\n \"texture\": \"cream\",\n \"reflection\": 100,\n \"contrast\": 50,\n \"roughness\": 0,\n \"ref_file_index\": 1\n },\n {\n \"sub_type\": \"design\",\n \"finger\": \"middle\",\n \"texture\": \"cream\",\n \"reflection\": 100,\n \"contrast\": 50,\n \"roughness\": 0,\n \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_3_9ce2ddc47a.png\"\n },\n {\n \"sub_type\": \"design\",\n \"finger\": \"pinky\",\n \"texture\": \"cream\",\n \"reflection\": 100,\n \"contrast\": 50,\n \"roughness\": 0,\n \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_5_f6e46dd56f.png\"\n },\n {\n \"sub_type\": \"design\",\n \"finger\": \"ring\",\n \"texture\": \"cream\",\n \"reflection\": 100,\n \"contrast\": 50,\n \"roughness\": 0,\n \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_4_2103ca8cac.png\"\n }\n ]\n}\n```\n\n\n* 3. Create a Nail VTO Task and Poll for Results\n\nOnce 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`.\n\n * Create Task Endpoint\n\n```\nPOST /s2s/v2.0/task/nail-vto\n```\n\n * Polling Endpoint\n\n```\nGET /s2s/v2.0/task/nail-vto/{task_id}\n```\n\n---\n\n## File Specs & Errors\n\n* AI Nail Virtual Try-On Specification\n\n**Supported Nail View**\nA single nail image in a clear front view without obstruction.\n\n| Item | Supported Dimensions | Supported File Size | Supported Formats |\n| --- | --- | --- | --- |\n| 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 |\n| 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) |\n\nPress-on nail design image sample:\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_press_on_nail_06_5_f6e46dd56f.png)\n\n[](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/youcamapi_press_on_nail_design_image_sample_de6bd64f20.png)\n\n---\n\n**Supported Hand View**\n\n| Item | Supported Dimensions | Supported File Size | Supported Formats |\n| --- | --- | --- | --- |\n| User Photo | * Long side ≤ 2048
* Short side ≥ 256 | ≤ 10MB | jpg/jpeg/png |\n* Support only one hand in the input image\n* The area of hand palm is better to be at least half of that of input image\n* The aspect ratio of the input image is better to be 1:1, 3:4, 4:3\n* The nails of fingers should not be occluded\n* It is better that there is no nail tip and nail polish on the nail\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_nail_user_photo_02_fdba1848d6.jpg)\n\n---\n\n* Error Codes\n\n| Error Code | Description |\n| ---- | ---- |\n| error_nail_too_small | The nail regions are too small. |\n| error_no_nail\t| No nails were detected in the source image. |\n\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"}},{"type":"group","fsPath":"reference/ai_eye_color_lens.yaml","link":"/reference/ai_eye_color_lens","routeSlug":"/reference/ai_eye_color_lens","label":"AI Eye Color Lens Virtual Try-On","items":[{"type":"group","label":"Overview","link":"/reference/ai_eye_color_lens/section/overview","routeSlug":"/reference/ai_eye_color_lens/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_eye_color_lens/section/overview/integration-guide","routeSlug":"/reference/ai_eye_color_lens/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_eye_color_lens/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_eye_color_lens/section/overview/file-specs-and-errors"},{"type":"link","label":"JS Camera Kit","link":"/reference/ai_eye_color_lens/section/overview/js-camera-kit","routeSlug":"/reference/ai_eye_color_lens/section/overview/js-camera-kit"}]},{"type":"group","label":"V1.0","link":"/reference/ai_eye_color_lens/v1.0","routeSlug":"/reference/ai_eye_color_lens/v1.0","items":[{"label":"Run an AI Eye Color Lens task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_eye_color_lens/v1.0/paths/~1s2s~1v2.0~1task~1eye-color-vto/post","routeSlug":"/reference/ai_eye_color_lens/v1.0/paths/~1s2s~1v2.0~1task~1eye-color-vto/post","metadata":{"seo":{"title":"Run an AI Eye Color Lens 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/eye-color-vto"},{"label":"Check the status of a AI Eye Color Lens task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_eye_color_lens/v1.0/paths/~1s2s~1v2.0~1task~1eye-color-vto~1{task_id}/get","routeSlug":"/reference/ai_eye_color_lens/v1.0/paths/~1s2s~1v2.0~1task~1eye-color-vto~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Eye Color Lens task.","description":"Check the status of a AI Eye Color Lens task."}},"httpPath":"/s2s/v2.0/task/eye-color-vto/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Eye Color Lens Virtual Try-On","version":"","description":"# Overview\nAI 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.\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2022-01-25/2a348e5b-6a2b-4f08-bc54-1d16a0777e87.jpg)\n\n**Contact Lenses Virtual Simulation**\n\nTransform 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.\n\n**Hyper‑Realistic Output** \nThe system preserves natural eye reflections for authentic results, ensuring each color transformation looks true to life.\n\n**Advanced Contact Filter Simulation** \nThe 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.\n\n**More Than an Eye Color Changer** \nThis technology goes beyond simple filters, offering a professional‑grade virtual lens experience that enhances customer confidence and boosts conversion.\n\n---\n\n## Integration Guide\n\n* Take a Selfie\n\n * Face the camera directly with proper lighting.\n * Use the JS Camera Kit to capture the photo.\n\n* Prepare Your Lens Style Cutout\n\n* Provide **one clear Lens Style image**:\n\n * Format: **PNG** (recommended: background removed)\n * Dimensions: **200 × 200 ≤ W × H ≤ 600 × 600**\n * File size: **< 10 MB**\n\n **Samples:**\n\n ![](https://d3ss46vukfdtpo.cloudfront.net/static/media/01.00ccf3ac.png)\n ![](https://d3ss46vukfdtpo.cloudfront.net/static/media/02.c8beb3fc.png)\n\n* Retrieve upload URLs and File IDs via ***/s2s/v2.0/file*** API\n\n Upload the following files using the upload URLs returned in the file API response:\n * Your selfie photo\n * Lens Style image\n\n* Execute AI Task ***/s2s/v2.0/task/eye-color-vto***\n\n Run the AI task using file IDs or image URLs as the input source. Configure the effect parameters as desired.\n\n* Poll Task Status\n\n Use the returned **task\\_id** to monitor task progress. \n Poll **GET /task/eye-color-vto** to check the engine's status. \n The task will remain in a **“running”** state until it is completed. No units are consumed while the task is running.\n\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_9535461b-69fc-4432-b56b-2d7c4cd0bf3b_b1ef78e813.jpg)\n\n\n\n* **Sample application scenario**\n\n 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.\n\n - Step1: Pick Your Favorite color\n 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.\n\n - Step 2: Open the Virtual Try-On Camera\n With just one click, the virtual try-on tool activates. No need for complicated setup instructions or additional downloads.\n\n - Step 3: Use Live Camera or Upload a Photo\n 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.\n\n ![](https://plugins-media.makeupar.com/smb/blog/post/2025-03-28/2732a9f0-9cae-4639-b765-15866550b109.jpg)\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n|Type|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|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|\n\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n|error_below_min_image_size|If your image is smaller than 320 pixels in width or height, it's too small to use|\n|error_face_position_invalid|Your face needs to be fully visible in the image, without any parts cut off|\n|error_face_position_too_small|The face in your photo is too small to analyze properly|\n|error_face_position_out_of_boundary|Your face is either too large or partially outside the edges of the photo|\n|error_insufficient_lighting|The lighting is too dim, which makes analysis difficult|\n|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|\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"}},{"type":"group","fsPath":"reference/ai_teeth_whitening.yaml","link":"/reference/ai_teeth_whitening","routeSlug":"/reference/ai_teeth_whitening","label":"AI Teeth Whitening","items":[{"type":"group","label":"Overview","link":"/reference/ai_teeth_whitening/section/overview","routeSlug":"/reference/ai_teeth_whitening/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_teeth_whitening/section/overview/integration-guide","routeSlug":"/reference/ai_teeth_whitening/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_teeth_whitening/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_teeth_whitening/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_teeth_whitening/v1.0","routeSlug":"/reference/ai_teeth_whitening/v1.0","items":[{"label":"Run an AI Teeth Whiten detection task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten~1pre-process/post","routeSlug":"/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten~1pre-process/post","metadata":{"seo":{"title":"Run an AI Teeth Whiten detection task.","description":"Use the pre-process task when the source image may contain more than one valid target, or when your integration needs to explicitly choose which detected target receives the effect. For single-target images, pre-process can be skipped when the feature supports a default index value and your application does not need manual target selection."}},"httpPath":"/s2s/v2.0/task/teeth-whiten/pre-process"},{"label":"Check the status of a AI Teeth Whiten detection task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten~1pre-process~1{task_id}/get","routeSlug":"/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten~1pre-process~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Teeth Whiten detection task.","description":"Check the status of a AI Teeth Whiten detection task."}},"httpPath":"/s2s/v2.0/task/teeth-whiten/pre-process/{task_id}"},{"label":"Run an AI Teeth Whiten task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten/post","routeSlug":"/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten/post","metadata":{"seo":{"title":"Run an AI Teeth Whiten 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/teeth-whiten"},{"label":"Check the status of a AI Teeth Whiten task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten~1{task_id}/get","routeSlug":"/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Teeth Whiten task.","description":"Check the status of a AI Teeth Whiten task."}},"httpPath":"/s2s/v2.0/task/teeth-whiten/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Teeth Whitening","version":"","description":"# Overview\n**AI Teeth Whitening API**\n\nThe 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.\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2023-07-28/f05fda4d-8ca8-4661-b4b5-135067280a10.jpg)\n\n\n\n\n**How It Removes Yellow Teeth in Photos**\n\n**Smart Whitening** \nThe API automatically detects teeth and applies a natural-looking whitening effect without making the image appear artificial.\n\n**Adjustable Levels** \nA built-in adjustment feature allows users to control the degree of whitening, from a subtle enhancement to a more pronounced, camera-ready finish.\n\n\n\n**Key Features**\n\n**Quick and Easy Enhancement** \nAchieve a noticeably brighter smile in just a few seconds.\n\n**Accurate AI Detection** \nAdvanced detection ensures that only teeth are modified, maintaining a realistic and balanced appearance.\n\n**Adjustable Whitening Intensity** \nUsers can fine-tune the whitening strength to match their preferred style.\n\n**Natural Results with Advanced Algorithms**\n\nThe 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.\n\n---\n\n## Integration Guide\n\n* Take a Selfie\n\n * Face the camera directly with proper lighting.\n * Use the JS Camera Kit to capture the photo.\n\n* Retrieve upload URLs and File IDs via ***/s2s/v2.0/file*** API\n\n Upload the following files using the upload URLs returned in the file API response:\n * Your selfie photo\n\n* Execute AI Task ***/s2s/v2.0/task/teeth-whiten***\n\n Run the AI task using file IDs or image URLs as the input source. Configure the effect parameters as desired.\n\n* Poll Task Status\n\n Use the returned **task\\_id** to monitor task progress. \n Poll **GET /s2s/v2.0/task/teeth-whiten/{task_id}** to check the engine's status. \n The task will remain in a **“running”** state until it is completed. No units are consumed while the task is running.\n\n\n\n* **Usage demonstration**\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2022-05-13/26c04462-d183-4392-937b-f6173ff9e814.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-07-01/webp_a4cd3779-2966-4b8f-888e-032dffc003c0.webp)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-11-13/webp_5824c85f-813e-4c14-b036-38cba206ee0b.webp)\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n|Type|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|AI Teeth Whitening|Selfie Image:
* Long side ≤ 1920 px
* Short side ≥ 320 px |< 10MB|jpg/png|\n\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| error_exceed_max_image_size | If the longer side of an image exceeds 1920 pixels |\n|error_below_min_image_size|If your image is smaller than 320 pixels in width or height, it's too small to use|\n|error_face_position_invalid|Your face needs to be fully visible in the image, without any parts cut off|\n|error_face_position_too_small|The face in your photo is too small to analyze properly|\n|error_face_position_out_of_boundary|Your face is either too large or partially outside the edges of the photo|\n|error_insufficient_lighting|The lighting is too dim, which makes analysis difficult|\n|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|\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"}},{"type":"separator","label":"Hair & Beard"},{"type":"group","fsPath":"reference/ai_hairstyle.yaml","link":"/reference/ai_hairstyle","routeSlug":"/reference/ai_hairstyle","label":"AI Hair Style Virtual Try-On","items":[{"type":"group","label":"Overview","link":"/reference/ai_hairstyle/section/overview","routeSlug":"/reference/ai_hairstyle/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_hairstyle/section/overview/integration-guide","routeSlug":"/reference/ai_hairstyle/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_hairstyle/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_hairstyle/section/overview/file-specs-and-errors"},{"type":"link","label":"FAQ","link":"/reference/ai_hairstyle/section/overview/faq","routeSlug":"/reference/ai_hairstyle/section/overview/faq"}]},{"type":"group","label":"V2.1","link":"/reference/ai_hairstyle/v2.1","routeSlug":"/reference/ai_hairstyle/v2.1","items":[{"label":"List predefined templates v2.1.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hairstyle/v2.1/paths/~1s2s~1v2.1~1task~1template~1hair-transfer/get","routeSlug":"/reference/ai_hairstyle/v2.1/paths/~1s2s~1v2.1~1task~1template~1hair-transfer/get","metadata":{"seo":{"title":"List predefined templates v2.1.","description":"List predefined templates v2.1."}},"httpPath":"/s2s/v2.1/task/template/hair-transfer"},{"label":"Run an AI Hairstyle Generator v2.1 task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hairstyle/v2.1/paths/~1s2s~1v2.1~1task~1hair-transfer/post","routeSlug":"/reference/ai_hairstyle/v2.1/paths/~1s2s~1v2.1~1task~1hair-transfer/post","metadata":{"seo":{"title":"Run an AI Hairstyle Generator 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 for setup and verification details."}},"httpPath":"/s2s/v2.1/task/hair-transfer"},{"label":"Check the status of a AI Hairstyle Generator v2.1 task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hairstyle/v2.1/paths/~1s2s~1v2.1~1task~1hair-transfer~1{task_id}/get","routeSlug":"/reference/ai_hairstyle/v2.1/paths/~1s2s~1v2.1~1task~1hair-transfer~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Hairstyle Generator v2.1 task.","description":"Check the status of a AI Hairstyle Generator v2.1 task."}},"httpPath":"/s2s/v2.1/task/hair-transfer/{task_id}"}]},{"type":"group","label":"V2.0","link":"/reference/ai_hairstyle/v2.0","routeSlug":"/reference/ai_hairstyle/v2.0","items":[{"label":"Run an AI Hairstyle Generator task with reference.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hairstyle/v2.0/paths/~1s2s~1v2.0~1task~1hair-transfer/post","routeSlug":"/reference/ai_hairstyle/v2.0/paths/~1s2s~1v2.0~1task~1hair-transfer/post","metadata":{"seo":{"title":"Run an AI Hairstyle Generator task with reference.","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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/hair-transfer"},{"label":"Check the status of a AI Hairstyle Generator task with reference.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hairstyle/v2.0/paths/~1s2s~1v2.0~1task~1hair-transfer~1{task_id}/get","routeSlug":"/reference/ai_hairstyle/v2.0/paths/~1s2s~1v2.0~1task~1hair-transfer~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Hairstyle Generator task with reference.","description":"Check the status of a AI Hairstyle Generator task with reference."}},"httpPath":"/s2s/v2.0/task/hair-transfer/{task_id}"}]},{"type":"group","label":"V1.0","link":"/reference/ai_hairstyle/v1.0","routeSlug":"/reference/ai_hairstyle/v1.0","items":[{"label":"List predefined templates.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hairstyle/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-style/get","routeSlug":"/reference/ai_hairstyle/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-style/get","metadata":{"seo":{"title":"List predefined templates.","description":"List predefined templates."}},"httpPath":"/s2s/v2.0/task/template/hair-style"},{"label":"Run an AI Hairstyle Generator task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hairstyle/v1.0/paths/~1s2s~1v2.0~1task~1hair-style/post","routeSlug":"/reference/ai_hairstyle/v1.0/paths/~1s2s~1v2.0~1task~1hair-style/post","metadata":{"seo":{"title":"Run an AI Hairstyle Generator 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/hair-style"},{"label":"Check the status of a AI Hairstyle Generator task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hairstyle/v1.0/paths/~1s2s~1v2.0~1task~1hair-style~1{task_id}/get","routeSlug":"/reference/ai_hairstyle/v1.0/paths/~1s2s~1v2.0~1task~1hair-style~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Hairstyle Generator task.","description":"Check the status of a AI Hairstyle Generator task."}},"httpPath":"/s2s/v2.0/task/hair-style/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Hair Style Virtual Try-On","version":"","description":"# Overview\nUsing the latest AI technology to try a wide variety of hairstyles, catering to both women and men, meeting different gender and style preference.\nDiscover a world of styles: curly, long, buzz cut, and more. Our AI-powered hair changer lets you experiment effortlessly. Find your ideal hairstyle now!\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_style_v3_poster_bb1c7aad10.jpg)\n\n---\n\n## Integration Guide\n\n* API Playground\nYou 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.\n\nAccess the API Playground at:\n\n\n---\n\n* API Workflow\nThis guide walks you through:\n\nWorkflow for AI Hairstyle Generator API:\n\n**Endpoint:** `/s2s/v2.1/task/hair-transfer`\n\n**Authentication Required:** `Authorization: Bearer YOUR_API_KEY`\n\n**Workflow Steps:**\n\n1. **Image Upload Preparation:**\n - The process begins with preparing a selfie.\n\n2. **List predefined templates or using your own reference photo**\n **Choose Reference Source**\nYou have two options for styling references:\n\n| Option | Use Case | Implementation Tip |\n|-------|-----------|---------------------|\n| **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`. |\n| **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. |\n\n3. **Initiate AI Task and Obtain Task ID:**\n - Send the uploaded image along with the style configuration via an HTTP POST request to `/s2s/v2.0/file`.\n - Await a unique task ID in the response, which identifies this interaction.\n\n4. **Poll Task Status (Continuous Check):**\n - Use the obtained `task_id` to periodically poll the task status using an HTTP GET request (e.g., `GET /task/${task_id}`).\n - Continuously monitor for:\n - `Task_status = \"success\"` (process completed).\n - `Task_status = \"error\"` (resolve or retry if applicable).\n - Update the workflow accordingly once the status transitions to success.\n\nThis structured workflow ensures efficient integration with user inputs, automated monitoring of tasks, and seamless retrieval of results.\n\n---\n\n* Authentication\n- Include your API key in the request header using **Bearer Token**:\n ```\n Authorization: Bearer YOUR_API_KEY\n ```\nYou can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.\n\n---\n\n* API Usage Guide\n\nThis guide explains how to upload images, prepare reference images, and create virtual try-on tasks using the AI Hairstyle Generator API.\n\n***\n\n * Step 1. Upload a File Using the File API or provide a valid image URL\n\nUse the **File API** (`/s2s/v2.0/file`) to upload a target user image.\n\nAlternatively, skip step 1 to 3 if you already have a public image URL.\n\n**Image Requirements:**\n\n* Upload a high-resolution selfie photo.\n* Ensure the photo clearly shows the entire body.\n* Avoid backgrounds with multiple people or distracting objects.\n\n**Example Request:**\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/jpg\",\n \"file_name\": \"selfie_01_3dbd1b6683.jpg\",\n \"file_size\": 547541\n }\n ]\n }'\n```\n\n***\n\n * Step 2. Retrieve File API Response\n\nThe response includes:\n\n* `file_id` for creating an AI task.\n* `requests.url` for uploading the actual image file.\n\n**Sample Response:**\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"files\": [\n {\n \"content_type\": \"image/jpg\",\n \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\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/jpg\"\n }\n }\n ]\n }\n ]\n }\n}\n```\n\n***\n\n * Step 3. Upload Image to Provided URL\n\nUse the `requests.url` from the File API response to upload the image:\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n --header 'Content-Type: image/jpg' \\\n --header 'Content-Length: 547541' \\\n --data-binary @'./full_body_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n * Step 4. Prepare a Reference Image\n\n * 4.1 Fetch Predefined Image Templates\n\nUse the **Template API** (`/s2s/v2.1/task/template/hair-transfer`) to retrieve a list of predefined reference templates:\n\n```bash\ncurl --request GET \\\n --url 'https://yce-api-01.makeupar.com/s2s/v2.1/task/template/hair-transfer?page_size=20&starting_token=73a3c9e69b89' \\\n --header 'Authorization: Bearer YOUR_API_KEY'\n```\n\n * 4.2 Upload a Reference Image\n\nYou can:\n\n* Upload an reference image using the File API (`/s2s/v2.0/file`), or\n* Provide a valid image URL.\n\n**Supported Images:**\n\n* Another selfie photo as an reference image.\n\nRefer to **[File Specs and Errors](#section/overview/File-Specs-and-Errors)** for detailed specifications.\n\n***\n\n * Step 5. Create an AI Hairstyle Generator Task\n\nUse the **AI Task API** (`/s2s/v2.1/task/hair-transfer`) to create a virtual try-on task.\n\n**Parameters:**\n\n* For the user image: `src_file_id` or `src_file_url`.\n* For the reference image: `ref_file_id`, `ref_file_url`, or `template_id`.\n\n**Example Request:**\n\n```bash\ncurl --request POST \\\n --url https://yce-api-01.makeupar.com/s2s/v2.1/task/hair-transfer \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json' \\\n --data '{\n \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/selfie_03_cccd5d4803.jpeg\",\n \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/style_reference_full_body_01_5a000d999f.png\"\n }'\n```\n\n**Sample 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 for Task Result\n\nUse the task ID to check the status:\n\n```bash\ncurl --request GET \\\n --url https://yce-api-01.makeupar.com/s2s/v2.1/task/hair-transfer/ \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json'\n```\n\n***\n\n * Step 7. Retrieve Result\n\nA successful response includes a download URL for the result image:\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"error\": null,\n \"results\": {\n \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n },\n \"task_status\": \"success\"\n }\n}\n```\n\nInvalid API Key error response:\n\n```json\n{\n \"status\": 401,\n \"error\": \"Unauthorized\",\n \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\nUse cases:\nUse case:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_style_v1_video_08513beb46.jpg)\n\nSuggestions for How to Shoot:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png)\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|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|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n|error_no_shoulder\t|Shoulders are not visible in the source image\n|error_large_face_angle\t|The face angle in the uploaded image is too large\n|error_insufficient_landmarks\t|Cannot detect sufficient face or body landmarks in the source image\n|error_hair_too_short\t|Input hair is too short\n|error_face_pose\t|The face pose of source image is unsupported\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## FAQ\n**Q: Can I try on a custom hairstyle?**\n\n**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:\n\n1. **Upload your own reference image**\n 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.\n\n2. **Provide a valid image URL**\n 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`.\n\nWhen submitting the task via `/s2s/v2.1/task/hair-transfer`, include either:\n- `src_file_id` (your selfie) and `ref_file_id` (your custom reference image),\nor\n- `src_file_url` and `ref_file_url`.\n\nEnsure both images meet the specified requirements:\n- Supported format: JPG/JPEG only\n- File size under 10 MB\n- Long side ≤ 1024 pixels\n- Face width ≥ 128 pixels\n- Head pose within allowed range (pitch: −10° to +10°, yaw: −45° to +45°, roll: −15° to +15°)\n- Single face visible, full frontal view with clear hair visibility\n\nThis flexibility allows you to apply virtually any hairstyle from a photo reference, not just predefined templates.\n\n---\n"}},{"type":"group","fsPath":"reference/ai_hair_color.yaml","link":"/reference/ai_hair_color","routeSlug":"/reference/ai_hair_color","label":"AI Hair Color Virtual Try-On","items":[{"type":"group","label":"Overview","link":"/reference/ai_hair_color/section/overview","routeSlug":"/reference/ai_hair_color/section/overview","items":[{"type":"link","label":"File Specs & Errors","link":"/reference/ai_hair_color/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_hair_color/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_hair_color/v1.0","routeSlug":"/reference/ai_hair_color/v1.0","items":[{"label":"Run a Hair Color task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hair_color/v1.0/paths/~1s2s~1v2.0~1task~1hair-color/post","routeSlug":"/reference/ai_hair_color/v1.0/paths/~1s2s~1v2.0~1task~1hair-color/post","metadata":{"seo":{"title":"Run a Hair Color task.","description":"This endpoint initiates the hair color change process. You must provide a source file (via URL or File ID) and specify the color settings (preset, pattern, or palettes). The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/hair-color"},{"label":"Check a Hair Color task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hair_color/v1.0/paths/~1s2s~1v2.0~1task~1hair-color~1{task_id}/get","routeSlug":"/reference/ai_hair_color/v1.0/paths/~1s2s~1v2.0~1task~1hair-color~1{task_id}/get","metadata":{"seo":{"title":"Check a Hair Color task status.","description":"Check a Hair Color task status."}},"httpPath":"/s2s/v2.0/task/hair-color/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Hair Color Virtual Try-On","version":"","description":"# Overview\nExplore 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.\n\n * Upload Your Image\n\nUpload the photo you want to change hair color for.\n\n * Choose Preset Colors or Customize by Pattern and Palettes\n\nChoose from predefined color presets or fine tune by adjusting the ombre coverage and blend for unlimited possibilities!\n\n> **Warning:** If both a preset and pattern + palettes are specified, the preset will take priority.\n\n> **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.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_color_s2_poster_dt_v2_49198cabc0.png)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/01_1_1_8365c3b503.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/01_2_1_abfcdb7eba.jpg)\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|AI Hair Color|long side < 1920, face width >= 100|< 10MB|jpg/jpeg/png|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n|error_below_min_image_size|the size of the source image is smaller than minimum (expect: width >= 320px, height >= 320px)\n|error_exceed_max_image_size|the size of the source image is larger than maximum (expect: width < 1920px, height < 1080px)\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"}},{"type":"group","fsPath":"reference/ai_hair_extension.yaml","link":"/reference/ai_hair_extension","routeSlug":"/reference/ai_hair_extension","label":"AI Hair Extension Virtual Try-On","items":[{"type":"group","label":"Overview","link":"/reference/ai_hair_extension/section/overview","routeSlug":"/reference/ai_hair_extension/section/overview","items":[{"type":"link","label":"File Specs & Errors","link":"/reference/ai_hair_extension/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_hair_extension/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_hair_extension/v1.0","routeSlug":"/reference/ai_hair_extension/v1.0","items":[{"label":"List predefined templates.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hair_extension/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-ext/get","routeSlug":"/reference/ai_hair_extension/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-ext/get","metadata":{"seo":{"title":"List predefined templates.","description":"List predefined templates."}},"httpPath":"/s2s/v2.0/task/template/hair-ext"},{"label":"Run an AI Hair Extension task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hair_extension/v1.0/paths/~1s2s~1v2.0~1task~1hair-ext/post","routeSlug":"/reference/ai_hair_extension/v1.0/paths/~1s2s~1v2.0~1task~1hair-ext/post","metadata":{"seo":{"title":"Run an AI Hair Extension task.","description":"This endpoint initiates the hair extension generation process using a template and source image. The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/hair-ext"},{"label":"Check the status of a AI Hair Extension task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hair_extension/v1.0/paths/~1s2s~1v2.0~1task~1hair-ext~1{task_id}/get","routeSlug":"/reference/ai_hair_extension/v1.0/paths/~1s2s~1v2.0~1task~1hair-ext~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Hair Extension task.","description":"Check the status of a AI Hair Extension task."}},"httpPath":"/s2s/v2.0/task/hair-ext/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Hair Extension Virtual Try-On","version":"","description":"# Overview\nDiscover Your Perfect Hair Extension Match with AI​\nExperiment 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.​\nWith 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.\n\nUse case:\n![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\")\n\n![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\")\n\nSuggestions for How to Shoot:\n![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\")\n\n---\n\n## File Specs & Errors\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|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|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n|error_no_shoulder\t|Shoulders are not visible in the source image\n|error_large_face_angle\t|The face angle in the uploaded image is too large\n|error_insufficient_landmarks\t|Cannot detect sufficient face or body landmarks in the source image\n|error_hair_too_short\t|Input hair is too short\n|error_face_pose\t|The face pose of source image is unsupported\n|error_bald_image\t|Input hairstyle is bald\n"}},{"type":"group","fsPath":"reference/ai_bangs.yaml","link":"/reference/ai_bangs","routeSlug":"/reference/ai_bangs","label":"AI Bangs Filter Virtual Try-On","items":[{"type":"group","label":"Overview","link":"/reference/ai_bangs/section/overview","routeSlug":"/reference/ai_bangs/section/overview","items":[{"type":"link","label":"File Specs & Errors","link":"/reference/ai_bangs/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_bangs/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_bangs/v1.0","routeSlug":"/reference/ai_bangs/v1.0","items":[{"label":"List predefined templates.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_bangs/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-bang/get","routeSlug":"/reference/ai_bangs/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-bang/get","metadata":{"seo":{"title":"List predefined templates.","description":"List predefined templates."}},"httpPath":"/s2s/v2.0/task/template/hair-bang"},{"label":"Run an AI Hair Bang Generator task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_bangs/v1.0/paths/~1s2s~1v2.0~1task~1hair-bang/post","routeSlug":"/reference/ai_bangs/v1.0/paths/~1s2s~1v2.0~1task~1hair-bang/post","metadata":{"seo":{"title":"Run an AI Hair Bang Generator task.","description":"This endpoint initiates the hair bang generation process using a template and source image. The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/hair-bang"},{"label":"Check the status of a AI Hair Bang Generator task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_bangs/v1.0/paths/~1s2s~1v2.0~1task~1hair-bang~1{task_id}/get","routeSlug":"/reference/ai_bangs/v1.0/paths/~1s2s~1v2.0~1task~1hair-bang~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Hair Bang Generator task.","description":"Check the status of a AI Hair Bang Generator task."}},"httpPath":"/s2s/v2.0/task/hair-bang/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Bangs Filter Virtual Try-On","version":"","description":"# Overview\nTry on Your Perfect Hair Bangs with AI\nRealistic Looks: Experiment with realistic bangs and discover the style that best complements your face.​\nVersatile Styling Options: Explore a wide range of bangs styles to suit every personality and occasion.​\nEffortless Experience: Enjoy a user-friendly interface that makes trying new bangs easy and fun​.\n\nWant to see more Hair Bang styles? Please refer to https://yce.makeupar.com/bangs-filter.\n\nUse case:\n\n![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\")\n\n![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\")\n\n\nSuggestions for How to Shoot:\n![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\")\n\n---\n\n## File Specs & Errors\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|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|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n|error_no_shoulder\t|Shoulders are not visible in the source image\n|error_large_face_angle\t|The face angle in the uploaded image is too large\n|error_insufficient_landmarks\t|Cannot detect sufficient face or body landmarks in the source image\n|error_hair_too_short\t|Input hair is too short\n|error_face_pose\t|The face pose of source image is unsupported\n|error_bald_image\t|Input hairstyle is bald\n"}},{"type":"group","fsPath":"reference/ai_hair_volume.yaml","link":"/reference/ai_hair_volume","routeSlug":"/reference/ai_hair_volume","label":"AI Hair Volume Virtual Try-On","items":[{"type":"group","label":"Overview","link":"/reference/ai_hair_volume/section/overview","routeSlug":"/reference/ai_hair_volume/section/overview","items":[{"type":"link","label":"File Specs & Errors","link":"/reference/ai_hair_volume/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_hair_volume/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_hair_volume/v1.0","routeSlug":"/reference/ai_hair_volume/v1.0","items":[{"label":"List predefined templates.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hair_volume/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-vol/get","routeSlug":"/reference/ai_hair_volume/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-vol/get","metadata":{"seo":{"title":"List predefined templates.","description":"List predefined templates."}},"httpPath":"/s2s/v2.0/task/template/hair-vol"},{"label":"Run an AI Hair Volume Generator task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hair_volume/v1.0/paths/~1s2s~1v2.0~1task~1hair-vol/post","routeSlug":"/reference/ai_hair_volume/v1.0/paths/~1s2s~1v2.0~1task~1hair-vol/post","metadata":{"seo":{"title":"Run an AI Hair Volume Generator 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/hair-vol"},{"label":"Check the status of a AI Hair Volume Generator task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hair_volume/v1.0/paths/~1s2s~1v2.0~1task~1hair-vol~1{task_id}/get","routeSlug":"/reference/ai_hair_volume/v1.0/paths/~1s2s~1v2.0~1task~1hair-vol~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Hair Volume Generator task.","description":"Check the status of a AI Hair Volume Generator task."}},"httpPath":"/s2s/v2.0/task/hair-vol/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Hair Volume Virtual Try-On","version":"","description":"# Overview\nEnhance Your Look with Fuller, More Voluminous Hair Instantly!​\nAdd 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.\nOur 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.\n\nUse case:\n![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\")\n\n![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\")\n\nSuggestions for How to Shoot:\n![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\")\n\n---\n\n## File Specs & Errors\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|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|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n|error_no_shoulder\t|Shoulders are not visible in the source image\n|error_large_face_angle\t|The face angle in the uploaded image is too large\n|error_insufficient_landmarks\t|Cannot detect sufficient face or body landmarks in the source image\n|error_hair_too_short\t|Input hair is too short\n|error_face_pose\t|The face pose of source image is unsupported\n|error_bald_image\t|Input hairstyle is bald\n"}},{"type":"group","fsPath":"reference/ai_wavy_hair.yaml","link":"/reference/ai_wavy_hair","routeSlug":"/reference/ai_wavy_hair","label":"AI Wavy Hair Virtual Try-On","items":[{"type":"group","label":"Overview","link":"/reference/ai_wavy_hair/section/overview","routeSlug":"/reference/ai_wavy_hair/section/overview","items":[{"type":"link","label":"File Specs & Errors","link":"/reference/ai_wavy_hair/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_wavy_hair/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_wavy_hair/v1.0","routeSlug":"/reference/ai_wavy_hair/v1.0","items":[{"label":"List predefined templates.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_wavy_hair/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-curl/get","routeSlug":"/reference/ai_wavy_hair/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-curl/get","metadata":{"seo":{"title":"List predefined templates.","description":"List predefined templates."}},"httpPath":"/s2s/v2.0/task/template/hair-curl"},{"label":"Run an AI Wavy Hair task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_wavy_hair/v1.0/paths/~1s2s~1v2.0~1task~1hair-curl/post","routeSlug":"/reference/ai_wavy_hair/v1.0/paths/~1s2s~1v2.0~1task~1hair-curl/post","metadata":{"seo":{"title":"Run an AI Wavy Hair task.","description":"Please refer to the polling guide for checking task status."}},"httpPath":"/s2s/v2.0/task/hair-curl"},{"label":"Check the status of a AI Wavy Hair task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_wavy_hair/v1.0/paths/~1s2s~1v2.0~1task~1hair-curl~1{task_id}/get","routeSlug":"/reference/ai_wavy_hair/v1.0/paths/~1s2s~1v2.0~1task~1hair-curl~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Wavy Hair task.","description":"Check the status of a AI Wavy Hair task."}},"httpPath":"/s2s/v2.0/task/hair-curl/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Wavy Hair Virtual Try-On","version":"","description":"# Overview\nWhether 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.\n\nWhether you’re testing a soft wave or a wild afro, YouCam delivers precision and realism that other tools can’t match. It’s perfect for anyone wanting to experiment nobel hairstyle risk-free and make people look forward to their next salon visit.\n\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-04-01/webp_03963789-fb1e-4ad8-be4d-48932e247376.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-03-20/b25b228a-259b-4efb-a7c1-31d200b62e8c.jpg)\n\nSuggestions for How to Shoot:\n![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\")\n\n---\n\n## File Specs & Errors\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|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|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n|error_no_shoulder\t|Shoulders are not visible in the source image\n|error_large_face_angle\t|The face angle in the uploaded image is too large\n|error_insufficient_landmarks\t|Cannot detect sufficient face or body landmarks in the source image\n|error_hair_too_short\t|Input hair is too short\n|error_face_pose\t|The face pose of source image is unsupported\n"}},{"type":"group","fsPath":"reference/ai_beard_style.yaml","link":"/reference/ai_beard_style","routeSlug":"/reference/ai_beard_style","label":"AI Beard Style Generator","items":[{"type":"group","label":"Overview","link":"/reference/ai_beard_style/section/overview","routeSlug":"/reference/ai_beard_style/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_beard_style/section/overview/integration-guide","routeSlug":"/reference/ai_beard_style/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_beard_style/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_beard_style/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_beard_style/v1.0","routeSlug":"/reference/ai_beard_style/v1.0","items":[{"label":"List predefined templates.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1template~1beard-style/get","routeSlug":"/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1template~1beard-style/get","metadata":{"seo":{"title":"List predefined templates.","description":"List predefined templates."}},"httpPath":"/s2s/v2.0/task/template/beard-style"},{"label":"Run an AI Beard Style Generator task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1beard-style/post","routeSlug":"/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1beard-style/post","metadata":{"seo":{"title":"Run an AI Beard Style Generator 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/beard-style"},{"label":"Check the status of a AI Beard Style Generator task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1beard-style~1{task_id}/get","routeSlug":"/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1beard-style~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Beard Style Generator task.","description":"Check the status of a AI Beard Style Generator task."}},"httpPath":"/s2s/v2.0/task/beard-style/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Beard Style Generator","version":"","description":"# Overview\nAI Simulation for Men's Beard Styles\n\nThe AI algorithm also empowers men to have the complete freedom to virtualy try different beard styles with the highly sophisticated beard simulation technology, including trim beard, stubble beard, full beard, circle beard, mustache, goatee, and others.\n\nShoppers can also see before and after results, without the commitment of putting a razor to the skin.\nThe beard filters include mustache, short box, ducktail, circle and a dozen more.\n\n## Integration Guide\n\n1. **Upload a Selfie**\n You can provide the source image in one of two ways:\n\n - **Use an Existing Public Image URL**\n Instead of uploading, you may supply a publicly accessible image URL directly when initiating the AI task.\n\n - **Upload via File API**\n Use the endpoint:\n ```\n POST /s2s/v2.0/file\n ```\n This returns a `file_id` for subsequent task execution.\n\n - ***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.

\n 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.\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\n2. **List Predefined Styles**\n * Use /s2s/v2.0/task/template/beard-style to fetch a predefined template list and select a ``template_id`` to run an AI task.\n\n3. **Run an AI Task to Obtain a Task ID**\n 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``.\n\n4. **Poll to Check the Status of a Task Until It Succeeds or Fails**\n 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.\n 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.\n\n > **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.\n\n > **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.\n\n5. **Retrieve the Result of an AI Task Once Successful**\n 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.\n\n---\n\n## File Specs & Errors\n * Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|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|\n\n * Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n|error_no_face\t|Face are not visible in the source image\n|error_src_face_too_small\t|The face is too small\n|error_inference\t|Beard removal error or beard generation error\n|error_face_pose\t|The face pose of source image is unsupported\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"}},{"type":"group","fsPath":"reference/ai_hair_type_detection.yaml","link":"/reference/ai_hair_type_detection","routeSlug":"/reference/ai_hair_type_detection","label":"AI Hair Type Detection","items":[{"type":"group","label":"Overview","link":"/reference/ai_hair_type_detection/section/overview","routeSlug":"/reference/ai_hair_type_detection/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_hair_type_detection/section/overview/integration-guide","routeSlug":"/reference/ai_hair_type_detection/section/overview/integration-guide"},{"type":"link","label":"Hair Type Classification","link":"/reference/ai_hair_type_detection/section/overview/hair-type-classification","routeSlug":"/reference/ai_hair_type_detection/section/overview/hair-type-classification"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_hair_type_detection/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_hair_type_detection/section/overview/file-specs-and-errors"},{"type":"link","label":"JS Camera Kit","link":"/reference/ai_hair_type_detection/section/overview/js-camera-kit","routeSlug":"/reference/ai_hair_type_detection/section/overview/js-camera-kit"}]},{"type":"group","label":"V1.0","link":"/reference/ai_hair_type_detection/v1.0","routeSlug":"/reference/ai_hair_type_detection/v1.0","items":[{"label":"Run an Hair Type Detection task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hair_type_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-type-detection/post","routeSlug":"/reference/ai_hair_type_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-type-detection/post","metadata":{"seo":{"title":"Run an Hair Type Detection task.","description":"Please refer to the polling guide for checking task status."}},"httpPath":"/s2s/v2.0/task/hair-type-detection"},{"label":"Check an Hair Type Detection task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hair_type_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-type-detection~1{task_id}/get","routeSlug":"/reference/ai_hair_type_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-type-detection~1{task_id}/get","metadata":{"seo":{"title":"Check an Hair Type Detection task status.","description":"Check an Hair Type Detection task status."}},"httpPath":"/s2s/v2.0/task/hair-type-detection/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Hair Type Detection","version":"","description":"# Overview\nImagine 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.\n\n## Integration Guide\n* How to Take Photos for AI Hair Type Detection\n* Take 3 Photos from left, front facing to right.\n - 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.\n - 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.\n\n* How to Detect Hair Type by AI\n* Using the ***/s2s/v2.0/file*** API, please upload the following assets:\n - Photos from the front, the right side, and the left side.\n\n* Execute AI task ***/s2s/v2.0/task/hair-type-detection***
\nRun 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.\n\n* Polling to check the status of a task until it succeed or error
\nThis ***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.\n\n## Hair Type Classification\n|Category|Thumbnail|Hair Type Classification|Description|\n| ---- | ---- | ---- | ---- |\n|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|\n|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|\n|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|\n|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|\n|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|\n|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|\n|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|\n|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|\n|4B|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t4B.4a6300fe.jpg)|Coily|Densely packed coils tightly wound into sharp, zigzag angles|\n|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|\n\n* Result Arguments\n* mapping: result is a string showing the detected hair type category. Here lists all the possible result strings in an array:\n ```json\n [\"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\"]\n ```\n* term: a one-to-one mapping string between hair type categories and their classifications. Here lists all the possible result strings in an array:\n ```json\n [\"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\"]\n ```\n\n* Suggestions for How to Shoot\n![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\")\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Skin%20Analysis_camera.png)\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n|Type|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|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|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n|error_mismatch_image_size|Make sure all your face photos (front, left, and right) are the same size|\n|error_below_min_image_size|If your image is smaller than 320 pixels in width or height, it's too small to use|\n|error_face_position_invalid|Your face needs to be fully visible in the image, without any parts cut off|\n|error_face_position_too_small|The face in your photo is too small to analyze properly|\n|error_face_position_out_of_boundary|Your face is either too large or partially outside the edges of the photo|\n|error_insufficient_lighting|The lighting is too dim, which makes analysis difficult|\n|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|\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"}},{"type":"group","fsPath":"reference/ai_hair_length_detection.yaml","link":"/reference/ai_hair_length_detection","routeSlug":"/reference/ai_hair_length_detection","label":"AI Hair Length Detection","items":[{"type":"group","label":"Overview","link":"/reference/ai_hair_length_detection/section/overview","routeSlug":"/reference/ai_hair_length_detection/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_hair_length_detection/section/overview/integration-guide","routeSlug":"/reference/ai_hair_length_detection/section/overview/integration-guide"},{"type":"link","label":"Hair Length Classification","link":"/reference/ai_hair_length_detection/section/overview/hair-length-classification","routeSlug":"/reference/ai_hair_length_detection/section/overview/hair-length-classification"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_hair_length_detection/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_hair_length_detection/section/overview/file-specs-and-errors"},{"type":"link","label":"JS Camera Kit","link":"/reference/ai_hair_length_detection/section/overview/js-camera-kit","routeSlug":"/reference/ai_hair_length_detection/section/overview/js-camera-kit"}]},{"type":"group","label":"V1.0","link":"/reference/ai_hair_length_detection/v1.0","routeSlug":"/reference/ai_hair_length_detection/v1.0","items":[{"label":"Run an Hair Length Detection task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hair_length_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-length-detection/post","routeSlug":"/reference/ai_hair_length_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-length-detection/post","metadata":{"seo":{"title":"Run an Hair Length Detection task.","description":"Please refer to the polling guide for checking task status."}},"httpPath":"/s2s/v2.0/task/hair-length-detection"},{"label":"Check an Hair Length Detection task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hair_length_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-length-detection~1{task_id}/get","routeSlug":"/reference/ai_hair_length_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-length-detection~1{task_id}/get","metadata":{"seo":{"title":"Check an Hair Length Detection task status.","description":"Check an Hair Length Detection task status."}},"httpPath":"/s2s/v2.0/task/hair-length-detection/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Hair Length Detection","version":"","description":"# Overview\nAI 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.\nOur 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.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_length_S1_01_enu_b03bd393af.jpg)\n\n## Integration Guide\n* How to Take Photos for AI Hair Length Detection\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* How to Detect Hair Length by AI\n* Using the ***/s2s/v2.0/file*** API, please upload the following assets:\n - Your selfie photo.\n\n* Execute AI task ***/s2s/v2.0/task/hair-length-detection***
\nRun the hair-length detection task by sending one front facing selfie image. Use it's file ID as the source input for the AI.\n\n* Polling to check the status of a task until it succeed or error
\nThis ***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.\n\n## Hair Length Classification\n|Thumbnail|Hair Length Classification|Description|\n| ---- | ---- | ---- |\n|![](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.|\n|![](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.|\n|![](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.|\n|![](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.|\n|![](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.|\n\n* Result Arguments\n* term: result is a string showing the detected hair length type. Here lists all the possible result strings in an array:\n ```json\n [\"above the ears\", \"ear length\", \"ear length or longer\", \"short hair\", \"short hair or longer\", \"above chest\", \"above chest or longer\", \"long hair\"]\n ```\n\n* Suggestions for How to Shoot\n![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\")\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Skin%20Analysis_camera.png)\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n|Type|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|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|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n|error_below_min_image_size|If your image is smaller than 320 pixels in width or height, it's too small to use|\n|error_face_position_invalid|Your face needs to be fully visible in the image, without any parts cut off|\n|error_face_position_too_small|The face in your photo is too small to analyze properly|\n|error_face_position_out_of_boundary|Your face is either too large or partially outside the edges of the photo|\n|error_insufficient_lighting|The lighting is too dim, which makes analysis difficult|\n|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|\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"}},{"type":"group","fsPath":"reference/ai_hair_frizziness_detection.yaml","link":"/reference/ai_hair_frizziness_detection","routeSlug":"/reference/ai_hair_frizziness_detection","label":"AI Hair Frizziness Detection","items":[{"type":"group","label":"Overview","link":"/reference/ai_hair_frizziness_detection/section/overview","routeSlug":"/reference/ai_hair_frizziness_detection/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_hair_frizziness_detection/section/overview/integration-guide","routeSlug":"/reference/ai_hair_frizziness_detection/section/overview/integration-guide"},{"type":"link","label":"Inputs & Outputs","link":"/reference/ai_hair_frizziness_detection/section/overview/inputs-and-outputs","routeSlug":"/reference/ai_hair_frizziness_detection/section/overview/inputs-and-outputs"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_hair_frizziness_detection/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_hair_frizziness_detection/section/overview/file-specs-and-errors"},{"type":"link","label":"JS Camera Kit","link":"/reference/ai_hair_frizziness_detection/section/overview/js-camera-kit","routeSlug":"/reference/ai_hair_frizziness_detection/section/overview/js-camera-kit"}]},{"type":"group","label":"V1.0","link":"/reference/ai_hair_frizziness_detection/v1.0","routeSlug":"/reference/ai_hair_frizziness_detection/v1.0","items":[{"label":"Run an Hair Frizziness Detection task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hair_frizziness_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-frizziness-detection/post","routeSlug":"/reference/ai_hair_frizziness_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-frizziness-detection/post","metadata":{"seo":{"title":"Run an Hair Frizziness Detection task.","description":"Please refer to the polling guide for checking task status."}},"httpPath":"/s2s/v2.0/task/hair-frizziness-detection"},{"label":"Check an Hair Frizziness Detection task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hair_frizziness_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-frizziness-detection~1{task_id}/get","routeSlug":"/reference/ai_hair_frizziness_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-frizziness-detection~1{task_id}/get","metadata":{"seo":{"title":"Check an Hair Frizziness Detection task status.","description":"Check an Hair Frizziness Detection task status."}},"httpPath":"/s2s/v2.0/task/hair-frizziness-detection/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Hair Frizziness Detection","version":"","description":"# Overview\n180° Full View Hair Frizz Analysis with Just 3 Photos\n\nOur AI Frizzy Hair Analyzer delivers precise hair frizz analysis in seconds by simply uploading 3 photos—front, left, and right views of the hair.\n\nThis 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.\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_frizzy_S_02_enu_b80c238858.jpg)\n\n## Integration Guide\n\n1. **Upload a Selfie**\n You can provide the source image in one of two ways:\n\n - **Use an Existing Public Image URL**\n Instead of uploading, you may supply a publicly accessible image URL directly when initiating the AI task.\n\n - **Upload via File API**\n Use the endpoint:\n ```\n POST /s2s/v2.0/file\n ```\n This returns a `file_id` for subsequent task execution.\n\n - ***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.\n\n 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.\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\n2. **Run an AI Task to Obtain a Task ID**\n 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``.\n\n3. **Poll to Check the Status of a Task Until It Succeeds or Fails**\n 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.\n 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.\n\n > **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.\n\n > **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.\n\n4. **Retrieve the Result of an AI Task Once Successful**\n 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.\n\n## Inputs & Outputs\n* Input format\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_frizzy_step_01_ac5c651ea4.png)\nUpload 3 photos - front, left, and right views of the hair.\nYou can utilize the JS Camera Kit to implement a Javascript camera module to take 3 qualified photos.\n\n\n* Output format\nAI 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.\n\n| **Mapping (0–3)** | **Term** | **Description** |\n| ----------------- | ------------------- | --------------------------------------------------------- |\n| 0 | Not Frizzy | Hair appears smooth with minimal or no visible frizz. |\n| 1 | Slightly Frizzy | Light frizz visible; mild surface texture irregularities. |\n| 2 | Frizzy | Noticeable frizz across hair; clear texture disruption. |\n| 3 | Extreme Frizzy | Strong, widespread frizz; highly irregular hair texture. |\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_frizzy_S_01_enu_fcd10905ff.jpg)\n\n* Sample Output\n```json\n{\n \"mapping\": 1, // number; the key to map of result, alternatives: [0, 1, 2, 3]\n \"term\": \"Slightly Frizzy\" // string; 1-1 map to the \"mapping\", alternatives: [\"Not Frizzy\", \"Slightly Frizzy\", \"Frizzy\", \"Extreme Frizzy\"]\n}\n```\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n|Type|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|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|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n|error_mismatch_image_size|Make sure all your face photos (front, left, and right) are the same size|\n|error_below_min_image_size|If your image is smaller than 320 pixels in width or height, it's too small to use|\n|error_face_position_invalid|Your face needs to be fully visible in the image, without any parts cut off|\n|error_face_position_too_small|The face in your photo is too small to analyze properly|\n|error_face_position_out_of_boundary|Your face is either too large or partially outside the edges of the photo|\n|error_insufficient_lighting|The lighting is too dim, which makes analysis difficult|\n|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|\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"}},{"type":"group","fsPath":"reference/ai_hair_density_detection.yaml","link":"/reference/ai_hair_density_detection","routeSlug":"/reference/ai_hair_density_detection","label":"AI Hair Density Detection","items":[{"type":"group","label":"Overview","link":"/reference/ai_hair_density_detection/section/overview","routeSlug":"/reference/ai_hair_density_detection/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_hair_density_detection/section/overview/integration-guide","routeSlug":"/reference/ai_hair_density_detection/section/overview/integration-guide"},{"type":"link","label":"Hair Density Classification","link":"/reference/ai_hair_density_detection/section/overview/hair-density-classification","routeSlug":"/reference/ai_hair_density_detection/section/overview/hair-density-classification"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_hair_density_detection/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_hair_density_detection/section/overview/file-specs-and-errors"},{"type":"link","label":"JS Camera Kit","link":"/reference/ai_hair_density_detection/section/overview/js-camera-kit","routeSlug":"/reference/ai_hair_density_detection/section/overview/js-camera-kit"}]},{"type":"group","label":"V1.0","link":"/reference/ai_hair_density_detection/v1.0","routeSlug":"/reference/ai_hair_density_detection/v1.0","items":[{"label":"Run an AI Hair Density Detection task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hair_density_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-density-detection/post","routeSlug":"/reference/ai_hair_density_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-density-detection/post","metadata":{"seo":{"title":"Run an AI Hair Density Detection task.","description":"Polling is required to check the status of the task. Refer to polling guide for details."}},"httpPath":"/s2s/v2.0/task/hair-density-detection"},{"label":"Check the status of a AI Hair Density Detection task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hair_density_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-density-detection~1{task_id}/get","routeSlug":"/reference/ai_hair_density_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-density-detection~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Hair Density Detection task.","description":"Check the status of a AI Hair Density Detection task."}},"httpPath":"/s2s/v2.0/task/hair-density-detection/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Hair Density Detection","version":"","description":"# Overview\nAI 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.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_hair_density_S3_02_b34f2db2ce.jpg)\n\n## Integration Guide\n* How to Take Photos for AI Hair Density Detection\n* Take a selfie\n - 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.\n\n ![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_popup_step_animated_02.aadf7a34.png)\n\n - Instead, use the JS Camera Kit to take a photo.\n\n* How to Detect Hair Density by AI\n* Using the ***/s2s/v2.0/file*** API, please upload the following assets:\n - Your selfie photo.\n\n* Execute AI task ***/s2s/v2.0/task/hair-density-detection***
\nRun 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.\n\n* Polling to check the status of a task until it succeed or error
\nThis ***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.\n\n\n## Hair Density Classification\n\n|Thumbnail|Hair Density Classification|Description|\n| ---- | ---- | ---- |\n|![](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.|\n|![](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.|\n|![](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.|\n|![](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.|\n\n\n* Suggestions for How to Shoot\n\n![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\")\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_hair_density_S1_02_f60369b14d.jpg)\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n|Type|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|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|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n|error_below_min_image_size|If your image is smaller than 100 pixels in width or height, it's too small to use|\n|error_face_position_invalid|Your face needs to be fully visible in the image, without any parts cut off|\n|error_face_position_too_small|The face in your photo is too small to analyze properly|\n|error_face_position_out_of_boundary|Your face is either too large or partially outside the edges of the photo|\n|error_insufficient_lighting|The lighting is too dim, which makes analysis difficult|\n|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|\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"}},{"type":"separator","label":"Fashion"},{"type":"group","fsPath":"reference/ai_clothes.yaml","link":"/reference/ai_clothes","routeSlug":"/reference/ai_clothes","label":"AI Clothes Virtual Try-On","items":[{"type":"group","label":"Overview","link":"/reference/ai_clothes/section/overview","routeSlug":"/reference/ai_clothes/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_clothes/section/overview/integration-guide","routeSlug":"/reference/ai_clothes/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_clothes/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_clothes/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V4.0","link":"/reference/ai_clothes/v4.0","routeSlug":"/reference/ai_clothes/v4.0","items":[{"label":"Run an AI Cloth V4 task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_clothes/v4.0/paths/~1s2s~1v2.0~1task~1cloth-v4/post","routeSlug":"/reference/ai_clothes/v4.0/paths/~1s2s~1v2.0~1task~1cloth-v4/post","metadata":{"seo":{"title":"Run an AI Cloth V4 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/cloth-v4"},{"label":"Check the status of a AI Cloth V4 task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_clothes/v4.0/paths/~1s2s~1v2.0~1task~1cloth-v4~1{task_id}/get","routeSlug":"/reference/ai_clothes/v4.0/paths/~1s2s~1v2.0~1task~1cloth-v4~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Cloth V4 task.","description":"Check the status of a AI Cloth V4 task."}},"httpPath":"/s2s/v2.0/task/cloth-v4/{task_id}"}]},{"type":"group","label":"V3.0","link":"/reference/ai_clothes/v3.0","routeSlug":"/reference/ai_clothes/v3.0","items":[{"label":"Run an AI Cloth V3 task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_clothes/v3.0/paths/~1s2s~1v2.0~1task~1cloth-v3/post","routeSlug":"/reference/ai_clothes/v3.0/paths/~1s2s~1v2.0~1task~1cloth-v3/post","metadata":{"seo":{"title":"Run an AI Cloth V3 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/cloth-v3"},{"label":"Check the status of a AI Cloth V3 task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_clothes/v3.0/paths/~1s2s~1v2.0~1task~1cloth-v3~1{task_id}/get","routeSlug":"/reference/ai_clothes/v3.0/paths/~1s2s~1v2.0~1task~1cloth-v3~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Cloth V3 task.","description":"Check the status of a AI Cloth V3 task."}},"httpPath":"/s2s/v2.0/task/cloth-v3/{task_id}"}]},{"type":"group","label":"V2.0","link":"/reference/ai_clothes/v2.0","routeSlug":"/reference/ai_clothes/v2.0","items":[{"label":"List predefined templates.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1template~1cloth/get","routeSlug":"/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1template~1cloth/get","metadata":{"seo":{"title":"List predefined templates.","description":"List predefined templates."}},"httpPath":"/s2s/v2.0/task/template/cloth"},{"label":"Run an AI Cloths task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1cloth/post","routeSlug":"/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1cloth/post","metadata":{"seo":{"title":"Run an AI Cloths task.","description":"This endpoint initiates the clothing virtual try-on process. You can use a template ID or provide reference images (source and reference files). The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/cloth"},{"label":"Check the status of a AI Cloths task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1cloth~1{task_id}/get","routeSlug":"/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1cloth~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Cloths task.","description":"Check the status of a AI Cloths task."}},"httpPath":"/s2s/v2.0/task/cloth/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Clothes Virtual Try-On","version":"","description":"# Overview\nAI 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.\n\n---\n\n## Integration Guide\n\n* API Playground\nYou 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.\n\nAccess the API Playground at:\n\n\n---\n\n* AI Clothes API Usage Guide\n\nThis guide explains how to upload images, prepare reference outfits, and create virtual try-on tasks using the AI Clothes API.\n\n***\n\n * Step 1. Upload a File Using the File API\n\nUse the **File API** (`/s2s/v2.0/file`) to upload a target user image.\n\n**Image Requirements:**\n\n* Upload a high-resolution full-body photo.\n* Ensure the photo clearly shows the entire body.\n* Avoid backgrounds with multiple people or distracting objects.\n\n**Example Request:**\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/jpg\",\n \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\n \"file_size\": 547541\n }\n ]\n }'\n```\n\n***\n\n * Step 2. Retrieve File API Response\n\nThe response includes:\n\n* `file_id` for creating an AI task.\n* `requests.url` for uploading the actual image file.\n\n**Sample Response:**\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"files\": [\n {\n \"content_type\": \"image/jpg\",\n \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\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/jpg\"\n }\n }\n ]\n }\n ]\n }\n}\n```\n\n***\n\n * Step 3. Upload Image to Provided URL\n\nUse the `requests.url` from the File API response to upload the image:\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n --header 'Content-Type: image/jpg' \\\n --header 'Content-Length: 547541' \\\n --data-binary @'./full_body_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n * Step 4. Prepare a Reference Outfit\n\n * 4.1 Upload a Reference Outfit Image\n\nYou can:\n\n* Upload an outfit image using the File API (`/s2s/v2.0/file`), or\n* Provide a valid image URL.\n\n**Supported Outfit Images:**\n\n* Product image of the clothing.\n* Full-body photo as an outfit reference.\n\nRefer to **[File Specs and Errors](#section/overview/File-Specs-and-Errors)** for detailed specifications.\n\n***\n\n * Step 5. Create an AI Task\n\nUse the **AI Task API** (`/s2s/v2.0/task/cloth-v4`) to create a virtual try-on task.\n\n**Parameters:**\n\n* For the user image: `src_file_id` or `src_file_url`.\n* For the outfit image: `ref_file_id`, `ref_file_url`, or `template_id`.\n\n**Example Request:**\n\n```bash\ncurl --request POST \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/cloth-v4 \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json' \\\n --data '{\n \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/clothes_03_cccd5d4803.jpeg\",\n \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/clothes_reference_full_body_01_5a000d999f.png\",\n \"garment_category\": \"full_body\"\n }'\n```\n\n**Sample 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 for Task Result\n\nUse the task ID to check the status:\n\n```bash\ncurl --request GET \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/cloth-v4/ \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json'\n```\n\n***\n\n * Step 7. Retrieve Result\n\nA successful response includes a download URL for the result image:\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"error\": null,\n \"results\": {\n \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n },\n \"task_status\": \"success\"\n }\n}\n```\n\nInvalid API Key error response:\n\n```json\n{\n \"status\": 401,\n \"error\": \"Unauthorized\",\n \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\nUse cases:\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-05-08/b80f4ae1-c905-4ec0-b491-e42c15e65575.gif)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/01%20ai%20clothes%20changer.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2023-12-01/45f451aa-4b4f-466d-9da7-4538573c92af.jpg)\n\nSuggestions for How to Shoot:\n![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\")\n\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n|Type|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|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|\n|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|\n\n* Error Codes\n\n* Error code (Preprocess)\n\n| Error code | Description |\n| ---------- | ----------- |\n| exceed_max_filesize | The SRC or REF image is too large. The long side must not exceed 4096 pixels. |\n| error_below_min_image_size | The SRC or REF image is too small. The long side must be at least 128 pixels. |\n| error_pose | The pose could not be detected from the uploaded human SRC image. |\n| error_invalid_ref | The REF image is invalid, for example, it is empty or the subject is not fully visible. |\n| error_apply_region_mismatch | The apply region in the SRC image does not match the REF image, so no edits can be applied. |\n| error_invalid_src | When the source image shows only the lower body or only the feet. |\n\n* Error code (Engine)\n\n| Error code | Description |\n| ---------- | ----------- |\n| 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. |\n| error_download_image | The SRC or REF image could not be downloaded. |\n| exceed_max_filesize | The SRC or REF image is too large. The file size must not exceed 10 MB. |\n| error_nsfw_content_detected | Potential NSFW content was detected in the result image. |\n| error_editing_failed | The editing process failed because the result image is too similar to the source image. |\n| unknown_internal_error | - Failed to load the model.
- Invalid scheduler algorithm type.
- No engine loaded.
- The file is not in the upload results. |\n\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"}},{"type":"group","fsPath":"reference/ai_hat.yaml","link":"/reference/ai_hat","routeSlug":"/reference/ai_hat","label":"AI Hat Virtual Try-On","items":[{"type":"group","label":"Overview","link":"/reference/ai_hat/section/overview","routeSlug":"/reference/ai_hat/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_hat/section/overview/integration-guide","routeSlug":"/reference/ai_hat/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_hat/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_hat/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_hat/v1.0","routeSlug":"/reference/ai_hat/v1.0","items":[{"label":"Run an AI Hat task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hat/v1.0/paths/~1s2s~1v2.0~1task~1hat/post","routeSlug":"/reference/ai_hat/v1.0/paths/~1s2s~1v2.0~1task~1hat/post","metadata":{"seo":{"title":"Run an AI Hat task.","description":"This endpoint initiates the hat virtual try-on process. You must provide a source file, reference files (URL or ID), specify gender and style parameters. The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/hat"},{"label":"Check the status of a AI Hat task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_hat/v1.0/paths/~1s2s~1v2.0~1task~1hat~1{task_id}/get","routeSlug":"/reference/ai_hat/v1.0/paths/~1s2s~1v2.0~1task~1hat~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Hat task.","description":"Check the status of a AI Hat task."}},"httpPath":"/s2s/v2.0/task/hat/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Hat Virtual Try-On","version":"","description":"# Overview\nStep 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.\nFrom 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.\n\n## Integration Guide\nThis guide walks you through:\n\n* **Endpoint:** `/s2s/v2.0/task/hat`\n* **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY`\n* **Workflow:**\n 1. **Prepare a selfie image:** Uploading an image or providing a valid image URL of yourself as the virtual try-on target.\n 1. **Prepare a hat image:** Upload a hat product image or a photo of a person wearing hat.\n 1. **Select a style and a gender:** Select a preferred style and the gender you wish to visualize.\n 1. **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response.\n 1. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `\"success\"` or `\"error\"`.\n\n---\n\n* Authentication\n- Include your API key in the request header using **Bearer Token**:\n```\nAuthorization: Bearer YOUR_API_KEY\n```\nYou can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.\n\n---\n\n* AI Hat API Usage Guide\n\nThis guide explains how to upload images, prepare reference hat, and create virtual try-on tasks using the AI Hat API.\n\n***\n\n * Step 1. Prepare a Selfie Image\n\nYou can:\n* Upload a selfie image using the File API (`/s2s/v2.0/file`), or\n* Provide a valid image URL.\n\n * Step 1.1 Upload a File Using the File API\n\nUse the **File API** (`/s2s/v2.0/file`) to upload a target user image.\n\n**Image Requirements:**\n\n* Upload a selfie photo.\n* Ensure the photo clearly shows the upper body.\n* Avoid backgrounds with multiple people or distracting objects.\n\n**Example Request:**\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/jpg\",\n \"file_name\": \"selfie_photo_01_3dbd1b6683.jpg\",\n \"file_size\": 547541\n }\n ]\n }'\n```\n\n***\n\n * Step 1.2. Retrieve File API Response\n\nThe response includes:\n\n* `file_id` for creating an AI task.\n* `requests.url` for uploading the actual image file.\n\n**Sample Response:**\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"files\": [\n {\n \"content_type\": \"image/jpg\",\n \"file_name\": \"selfie_photo_01_3dbd1b6683.jpg\",\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/jpg\"\n }\n }\n ]\n }\n ]\n }\n}\n```\n\n***\n\n * Step 1.3. Upload Image to Provided URL\n\nUse the `requests.url` from the File API response to upload the image:\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n --header 'Content-Type: image/jpg' \\\n --header 'Content-Length: 547541' \\\n --data-binary @'./selfie_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n * Step 2. Prepare a Reference Hat Image\n\nYou can:\n\n* Upload a hat image using the File API (`/s2s/v2.0/file`), or\n* Provide a valid image URL.\n\n**Supported Hat Images:**\n\n* A hat product image.\n* A photo of a person wearing hat.\n\nRefer to **[File Specs and Errors](#section/overview/File-Specs-and-Errors)** for detailed specifications.\n\n***\n\n * Step 3. Create an AI Task\n\nSelect a preferred style and the gender you wish to visualize.\nUse the **AI Task API** (`/s2s/v2.0/task/hat`) to create a virtual try-on task.\n\n**Parameters:**\n\n* For the user image: `src_file_id` or `src_file_url`.\n* For the hat image: `ref_file_id`, or `ref_file_url`.\n\n**Example Request:**\n\n```bash\ncurl --request POST \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/hat \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json' \\\n --data '{\n \"src_file_url\": \"https://example.com/selfie.jpg\",\n \"ref_file_url\": \"https://example.com/accessory.jpg\",\n \"gender\": \"female\",\n \"style\": \"random\"\n}'\n```\n\n**Sample 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 4. Poll for Task Result\n\nUse the task ID to check the status:\n\n```bash\ncurl --request GET \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/hat/SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json'\n```\n\n***\n\n * Step 5. Retrieve Result\n\nA successful response includes a download URL for the result image:\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"error\": null,\n \"results\": {\n \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n },\n \"task_status\": \"success\"\n }\n}\n```\n\nInvalid API Key error response:\n\n```json\n{\n \"status\": 401,\n \"error\": \"Unauthorized\",\n \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\n## File Specs & Errors\n\n* AI Hat Virtual Try-On Specification\n\n * Image Requirements\n\n| Type | Minimum Resolution | Notes |\n| ------ | ------------------ | ----- |\n| Selfie | 512 × 512 | Face visible, head-to-chest preferred |\n| Hat | 512 × 512 (product)
800 × 800 (worn) | Clear, unobstructed hat view |\n\n**Supported Hat Image**\n\n* Product Image Requirements\n * Minimum resolution: 512 × 512 pixels\n * Only one product per image\n * The product should cover more than 25% of the image height\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/026_thumb_dca334af3c.jpg)\n\n* Worn Image Requirements\n * Minimum resolution: 800 × 800 pixels\n * Single Item Requirement: The model must wear exactly one item. Multiple items or accessories are not permitted.\n * 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.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/010_thumb_51490eebeb.jpg)\n\n**Supported Selfie View**\n\n* Recommended image resolution: at least 512 × 512 pixels.\n* Recommended face coverage: more than 15% of the image height.\n* Single Subject Requirement: The image must contain exactly one human subject. No additional people or partial figures are allowed.\n* Face Visibility: The subject's face must be fully visible without obstruction. Hair, accessories, or objects should not cover key facial features.\n* 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.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/lashana_lynch_thumb_7a900b811e.jpg)\n\n**Try-on Styles**\n\n* 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.\n\n![style_vacation_casual](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/5f42385b_6aef_44cd_b576_2ec10e31305d_824cc2019b.jpg)\n\n---\n\n* Supported Formats & Dimensions\n\n| AI Feature | Supported Dimensions | Supported File Size | Supported Formats |\n| ---- | ---- | ---- | ---- |\n| AI Hat Virtual Try-On | Input: long side <= 4096
Output: 896 x 1152 | < 10MB | jpg/jpeg/png/heic |\n\n* Error Codes\n\n| Error Code | Description |\n| ------------------------------ | -------------------------------------------- |\n| error\\_download\\_image | Failed to download source or reference image |\n| error\\_inference | Inference pipeline error |\n| error\\_no\\_face | No face detected in source image |\n| error\\_nsfw\\_content\\_detected | NSFW content detected in result |\n| exceed\\_max\\_filesize | File size exceeds 10 MB |\n| invalid\\_parameter | Invalid gender or style value |\n| unknown\\_internal\\_error | Other internal errors |\n\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)
- jquery >= 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"}},{"type":"group","fsPath":"reference/ai_scarf.yaml","link":"/reference/ai_scarf","routeSlug":"/reference/ai_scarf","label":"AI Scarf Virtual Try-On","items":[{"type":"group","label":"Overview","link":"/reference/ai_scarf/section/overview","routeSlug":"/reference/ai_scarf/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_scarf/section/overview/integration-guide","routeSlug":"/reference/ai_scarf/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_scarf/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_scarf/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V2.0","link":"/reference/ai_scarf/v2.0","routeSlug":"/reference/ai_scarf/v2.0","items":[{"label":"Run an AI Scarf task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_scarf/v2.0/paths/~1s2s~1v2.0~1task~1scarf/post","routeSlug":"/reference/ai_scarf/v2.0/paths/~1s2s~1v2.0~1task~1scarf/post","metadata":{"seo":{"title":"Run an AI Scarf task.","description":"This endpoint initiates the scarf virtual try-on process. You must provide a source file, reference files (URL or ID), specify gender and style parameters. The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/scarf"},{"label":"Check the status of a AI Scarf task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_scarf/v2.0/paths/~1s2s~1v2.0~1task~1scarf~1{task_id}/get","routeSlug":"/reference/ai_scarf/v2.0/paths/~1s2s~1v2.0~1task~1scarf~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Scarf task.","description":"Check the status of a AI Scarf task."}},"httpPath":"/s2s/v2.0/task/scarf/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Scarf Virtual Try-On","version":"","description":"# Overview\nEnhance 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.\nThis 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.\n\n## Integration Guide\nThis guide walks you through:\n\n* **Endpoint:** `/s2s/v2.0/task/scarf`\n* **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY`\n* **Workflow:**\n 1. **Prepare a selfie image:** Uploading an image or providing a valid image URL of yourself as the virtual try-on target.\n 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.\n 1. **Select a style and a gender:** Select a preferred style and the gender you wish to visualize.\n 1. **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response.\n 1. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `\"success\"` or `\"error\"`.\n\n---\n\n* Authentication\n- Include your API key in the request header using **Bearer Token**:\n```\nAuthorization: Bearer YOUR_API_KEY\n```\nYou can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.\n\n---\n\n* AI Scarf API Usage Guide\n\nThis guide explains how to upload images, prepare reference scarfs, and create virtual try-on tasks using the AI Scarf API.\n\n***\n\n * Step 1. Prepare a Selfie Image\n\nYou can:\n* Upload a selfie image using the File API (`/s2s/v2.0/file`), or\n* Provide a valid image URL.\n\n * Step 1.1 Upload a File Using the File API\n\nUse the **File API** (`/s2s/v2.0/file`) to upload a target user image.\n\n**Image Requirements:**\n\n* Upload a selfie photo.\n* Ensure the photo clearly shows the upper body.\n* Avoid backgrounds with multiple people or distracting objects.\n\n**Example Request:**\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/jpg\",\n \"file_name\": \"selfie_photo_01_3dbd1b6683.jpg\",\n \"file_size\": 547541\n }\n ]\n }'\n```\n\n***\n\n * Step 1.2. Retrieve File API Response\n\nThe response includes:\n\n* `file_id` for creating an AI task.\n* `requests.url` for uploading the actual image file.\n\n**Sample Response:**\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"files\": [\n {\n \"content_type\": \"image/jpg\",\n \"file_name\": \"selfie_photo_01_3dbd1b6683.jpg\",\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/jpg\"\n }\n }\n ]\n }\n ]\n }\n}\n```\n\n***\n\n * Step 1.3. Upload Image to Provided URL\n\nUse the `requests.url` from the File API response to upload the image:\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n --header 'Content-Type: image/jpg' \\\n --header 'Content-Length: 547541' \\\n --data-binary @'./selfie_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n * Step 2. Prepare a Reference Scarf Image\n\nYou can:\n\n* Upload a scarf image using the File API (`/s2s/v2.0/file`), or\n* Provide a valid image URL.\n\n**Supported Scarf Images:**\n\n* Product image of the scarf.\n* A person carrying a scarf without any obstruction as a scarf reference.\n\nRefer to **[File Specs and Errors](#section/overview/File-Specs-and-Errors)** for detailed specifications.\n\n***\n\n * Step 3. Create an AI Task\n\nSelect a preferred style and the gender you wish to visualize.\nUse the **AI Task API** (`/s2s/v2.0/task/scarf`) to create a virtual try-on task.\n\n**Parameters:**\n\n* For the user image: `src_file_id` or `src_file_url`.\n* For the scarf image: `ref_file_id`, or `ref_file_url`.\n\n**Example Request:**\n\n```bash\ncurl --request POST \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/scarf \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json' \\\n --data '{\n \"src_file_url\": \"https://example.com/selfie.jpg\",\n \"ref_file_url\": \"https://example.com/accessory.jpg\",\n \"gender\": \"female\",\n \"style\": \"random\"\n}'\n```\n\n**Sample 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 4. Poll for Task Result\n\nUse the task ID to check the status:\n\n```bash\ncurl --request GET \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/scarf/SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json'\n```\n\n***\n\n * Step 5. Retrieve Result\n\nA successful response includes a download URL for the result image:\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"error\": null,\n \"results\": {\n \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n },\n \"task_status\": \"success\"\n }\n}\n```\n\nInvalid API Key error response:\n\n```json\n{\n \"status\": 401,\n \"error\": \"Unauthorized\",\n \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\n## File Specs & Errors\n\n* AI Scarf Virtual Try-On Specification\n\n * Image Requirements\n\n| Type | Minimum Resolution | Notes |\n| ------ | ------------------ | ----- |\n| Selfie | 512 × 512 | Face visible, head-to-chest preferred |\n| Scarf | 512 × 512 (product)
800 × 800 (worn) | Clear, unobstructed scarf view |\n\n**Supported Scarf Image**\n\n* Product Image Requirements\n * Minimum resolution: 512 × 512 pixels\n * Only one product per image\n * The product should cover more than 25 per cent of the image height\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/021_thumb_e356d121b3.jpg)\n\n* Worn Image Requirements\n * Minimum resolution: 800 × 800 pixels\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/008_thumb_5dd8b1be93.jpg)\n\n**Supported Selfie View**\n\n* Recommended image resolution: at least 512 × 512 pixels.\n* Recommended face coverage: more than 15 per cent of the image height.\n* 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.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/lashana_lynch_thumb_7a900b811e.jpg)\n\n**Try-on Styles**\n\n* 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.\n\n![style_french_elegance](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/3d88ad75_41ca_4bf8_b81d_f52adf5db263_4a06b3e174.jpg)\n\n---\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|AI Scarf Virtual Try-On|Input: long side <= 4096
Output: 896 x 1152 |< 10MB|jpg/jpeg/png/heic|\n\n* Error Codes\n\n| Error Code | Description |\n| ------------------------------ | -------------------------------------------- |\n| error\\_download\\_image | Failed to download source or reference image |\n| error\\_inference | Inference pipeline error |\n| error\\_no\\_face | No face detected in source image |\n| error\\_nsfw\\_content\\_detected | NSFW content detected in result |\n| exceed\\_max\\_filesize | File size exceeds 10 MB |\n| invalid\\_parameter | Invalid gender or style value |\n| unknown\\_internal\\_error | Other internal errors |\n\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)
- jquery >= 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"}},{"type":"group","fsPath":"reference/ai_bag.yaml","link":"/reference/ai_bag","routeSlug":"/reference/ai_bag","label":"AI Bag Virtual Try-On","items":[{"type":"group","label":"Overview","link":"/reference/ai_bag/section/overview","routeSlug":"/reference/ai_bag/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_bag/section/overview/integration-guide","routeSlug":"/reference/ai_bag/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_bag/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_bag/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V2.0","link":"/reference/ai_bag/v2.0","routeSlug":"/reference/ai_bag/v2.0","items":[{"label":"Run an AI Bag task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_bag/v2.0/paths/~1s2s~1v2.0~1task~1bag/post","routeSlug":"/reference/ai_bag/v2.0/paths/~1s2s~1v2.0~1task~1bag/post","metadata":{"seo":{"title":"Run an AI Bag task.","description":"This endpoint initiates the bag virtual try-on process. You must provide a source file, reference files (URL or ID), and specify gender and style parameters. The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/bag"},{"label":"Check the status of a AI Bag task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_bag/v2.0/paths/~1s2s~1v2.0~1task~1bag~1{task_id}/get","routeSlug":"/reference/ai_bag/v2.0/paths/~1s2s~1v2.0~1task~1bag~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Bag task.","description":"Check the status of a AI Bag task."}},"httpPath":"/s2s/v2.0/task/bag/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Bag Virtual Try-On","version":"","description":"# Overview\nAR 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.\n\n## Integration Guide\nThis guide walks you through:\n\n* **Endpoint:** `/s2s/v2.0/task/bag`\n* **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY`\n* **Workflow:**\n 1. **Prepare a selfie image:** Uploading an image or providing a valid image URL of yourself as the virtual try-on target.\n 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.\n 1. **Select a style and a gender:** Select a preferred style and the gender you wish to visualize.\n 1. **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response.\n 1. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `\"success\"` or `\"error\"`.\n\n---\n\n* Authentication\n- Include your API key in the request header using **Bearer Token**:\n```\nAuthorization: Bearer YOUR_API_KEY\n```\nYou can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.\n\n---\n\n* AI Bag API Usage Guide\n\nThis guide explains how to upload images, prepare reference bags, and create virtual try-on tasks using the AI Bag API.\n\n***\n\n * Step 1. Upload a File Using the File API\n\nUse the **File API** (`/s2s/v2.0/file`) to upload a target user image.\n\n**Image Requirements:**\n\n* Upload a selfie photo.\n* Ensure the photo clearly shows the upper body.\n* Avoid backgrounds with multiple people or distracting objects.\n\n**Example Request:**\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/jpg\",\n \"file_name\": \"selfie_photo_01_3dbd1b6683.jpg\",\n \"file_size\": 547541\n }\n ]\n }'\n```\n\n***\n\n * Step 2. Retrieve File API Response\n\nThe response includes:\n\n* `file_id` for creating an AI task.\n* `requests.url` for uploading the actual image file.\n\n**Sample Response:**\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"files\": [\n {\n \"content_type\": \"image/jpg\",\n \"file_name\": \"selfie_photo_01_3dbd1b6683.jpg\",\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/jpg\"\n }\n }\n ]\n }\n ]\n }\n}\n```\n\n***\n\n * Step 3. Upload Image to Provided URL\n\nUse the `requests.url` from the File API response to upload the image:\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n --header 'Content-Type: image/jpg' \\\n --header 'Content-Length: 547541' \\\n --data-binary @'./selfie_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n * Step 4. Prepare a Reference Bag Image\n\nYou can:\n\n* Upload a bag image using the File API (`/s2s/v2.0/file`), or\n* Provide a valid image URL.\n\n**Supported Bag Images:**\n\n* Product image of the bag.\n* A person carrying a bag without any obstruction as a bag reference.\n\nRefer to **[File Specs and Errors](#section/overview/File-Specs-and-Errors)** for detailed specifications.\n\n***\n\n * Step 5. Create an AI Task\n\nSelect a preferred style and the gender you wish to visualize.\nUse the **AI Task API** (`/s2s/v2.0/task/bag`) to create a virtual try-on task.\n\n**Parameters:**\n\n* For the user image: `src_file_id` or `src_file_url`.\n* For the bag image: `ref_file_id`, or `ref_file_url`.\n\n**Example Request:**\n\n```bash\ncurl --request POST \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/bag \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json' \\\n --data '{\n \"src_file_url\": \"https://example.com/selfie.jpg\",\n \"ref_file_url\": \"https://example.com/accessory.jpg\",\n \"gender\": \"female\",\n \"style\": \"random\"\n}'\n```\n\n**Sample 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 for Task Result\n\nUse the task ID to check the status:\n\n```bash\ncurl --request GET \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/bag/SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json'\n```\n\n***\n\n * Step 7. Retrieve Result\n\nA successful response includes a download URL for the result image:\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"error\": null,\n \"results\": {\n \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n },\n \"task_status\": \"success\"\n }\n}\n```\n\nInvalid API Key error response:\n\n```json\n{\n \"status\": 401,\n \"error\": \"Unauthorized\",\n \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\n## File Specs & Errors\n\n* AI Bag Virtual Try-On Specification\n\n**Supported Bag Image**\n\n* Product Image Requirements\n * Minimum resolution: 512 × 512 pixels\n * Only one product per image\n * The product should cover more than 25 per cent of the image height\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/040_thumb_c5f4d2af8e.jpg)\n\n* Worn Image Requirements\n * Minimum resolution: 800 × 800 pixels\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/003_thumb_c73b207cae.jpg)\n\n**Supported Selfie View**\n\n* Recommended image resolution: at least 512 × 512 pixels.\n* Recommended face coverage: more than 15 per cent of the image height.\n* 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.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/lashana_lynch_thumb_7a900b811e.jpg)\n\n**Try-on Styles**\n\n* 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.\n\n![style_parisian_chic](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/fca6a904_b13a_4c90_bc52_d9200a473c70_4d994afa3e.jpg)\n\n---\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|AI Bag Virtual Try-On|Input: long side <= 4096
Output: 1104 x 1472 |< 10MB|jpg/jpeg/png/heic|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| error_download_image | Download srcKeys/refKeys error |\n| error_inference | Inference pipeline error |\n| error_no_face | No face detected in source image |\n| error_nsfw_content_detected| NSFW content detected in result image |\n| exceed_max_filesize | Input file size exceeds the maximum limit (10 MB) |\n| invalid_parameter | Invalid gender option value
Invalid style option value |\n| unknown_internal_error | Others |\n\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"}},{"type":"group","fsPath":"reference/ai_shoes.yaml","link":"/reference/ai_shoes","routeSlug":"/reference/ai_shoes","label":"AI Shoes Virtual Try-On","items":[{"type":"group","label":"Overview","link":"/reference/ai_shoes/section/overview","routeSlug":"/reference/ai_shoes/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_shoes/section/overview/integration-guide","routeSlug":"/reference/ai_shoes/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_shoes/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_shoes/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V2.0","link":"/reference/ai_shoes/v2.0","routeSlug":"/reference/ai_shoes/v2.0","items":[{"label":"Run an AI Shoes task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_shoes/v2.0/paths/~1s2s~1v2.0~1task~1shoes/post","routeSlug":"/reference/ai_shoes/v2.0/paths/~1s2s~1v2.0~1task~1shoes/post","metadata":{"seo":{"title":"Run an AI Shoes task.","description":"This endpoint initiates the shoes virtual try-on process. You must provide a source file, reference files (URL or ID), specify gender and style parameters. The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/shoes"},{"label":"Check the status of a AI Shoes task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_shoes/v2.0/paths/~1s2s~1v2.0~1task~1shoes~1{task_id}/get","routeSlug":"/reference/ai_shoes/v2.0/paths/~1s2s~1v2.0~1task~1shoes~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Shoes task.","description":"Check the status of a AI Shoes task."}},"httpPath":"/s2s/v2.0/task/shoes/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Shoes Virtual Try-On","version":"","description":"# Overview\nStep 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.\nExplore 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.\n\n## Integration Guide\nThis guide walks you through:\n\n* **Endpoint:** `/s2s/v2.0/task/shoes`\n* **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY`\n* **Workflow:**\n 1. **Prepare a selfie image:** Uploading an image or providing a valid image URL of yourself as the virtual try-on target.\n 1. **Prepare a shoes image:** Upload a shoe product image or a photo of a person wearing shoes.\n 1. **Select a style and a gender:** Select a preferred style and the gender you wish to visualize.\n 1. **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response.\n 1. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `\"success\"` or `\"error\"`.\n\n---\n\n* Authentication\n- Include your API key in the request header using **Bearer Token**:\n```\nAuthorization: Bearer YOUR_API_KEY\n```\nYou can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.\n\n---\n\n* AI Shoes API Usage Guide\n\nThis guide explains how to upload images, prepare reference shoes, and create virtual try-on tasks using the AI Shoes API.\n\n***\n\n * Step 1. Prepare a Selfie Image\n\nYou can:\n* Upload a selfie image using the File API (`/s2s/v2.0/file`), or\n* Provide a valid image URL.\n\n * Step 1.1 Upload a File Using the File API\n\nUse the **File API** (`/s2s/v2.0/file`) to upload a target user image.\n\n**Image Requirements:**\n\n* Upload a selfie photo.\n* Ensure the photo clearly shows the upper body.\n* Avoid backgrounds with multiple people or distracting objects.\n\n**Example Request:**\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/jpg\",\n \"file_name\": \"selfie_photo_01_3dbd1b6683.jpg\",\n \"file_size\": 547541\n }\n ]\n }'\n```\n\n***\n\n * Step 1.2. Retrieve File API Response\n\nThe response includes:\n\n* `file_id` for creating an AI task.\n* `requests.url` for uploading the actual image file.\n\n**Sample Response:**\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"files\": [\n {\n \"content_type\": \"image/jpg\",\n \"file_name\": \"selfie_photo_01_3dbd1b6683.jpg\",\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/jpg\"\n }\n }\n ]\n }\n ]\n }\n}\n```\n\n***\n\n * Step 1.3. Upload Image to Provided URL\n\nUse the `requests.url` from the File API response to upload the image:\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n --header 'Content-Type: image/jpg' \\\n --header 'Content-Length: 547541' \\\n --data-binary @'./selfie_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n * Step 2. Prepare a Reference Shoes Image\n\nYou can:\n\n* Upload a shoe image using the File API (`/s2s/v2.0/file`), or\n* Provide a valid image URL.\n\n**Supported Shoes Images:**\n\n* A shoe product image.\n* A photo of a person wearing shoes.\n\nRefer to **[File Specs and Errors](#section/overview/File-Specs-and-Errors)** for detailed specifications.\n\n***\n\n * Step 3. Create an AI Task\n\nSelect a preferred style and the gender you wish to visualize.\nUse the **AI Task API** (`/s2s/v2.0/task/shoes`) to create a virtual try-on task.\n\n**Parameters:**\n\n* For the user image: `src_file_id` or `src_file_url`.\n* For the shoes image: `ref_file_id`, or `ref_file_url`.\n\n**Example Request:**\n\n```bash\ncurl --request POST \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/shoes \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json' \\\n --data '{\n \"src_file_url\": \"https://example.com/selfie.jpg\",\n \"ref_file_url\": \"https://example.com/accessory.jpg\",\n \"gender\": \"female\",\n \"style\": \"random\"\n}'\n```\n\n**Sample 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 4. Poll for Task Result\n\nUse the task ID to check the status:\n\n```bash\ncurl --request GET \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/shoes/SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json'\n```\n\n***\n\n * Step 5. Retrieve Result\n\nA successful response includes a download URL for the result image:\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"error\": null,\n \"results\": {\n \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n },\n \"task_status\": \"success\"\n }\n}\n```\n\nInvalid API Key error response:\n\n```json\n{\n \"status\": 401,\n \"error\": \"Unauthorized\",\n \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\n## File Specs & Errors\n\n* AI Shoes Virtual Try-On Specification\n\n * Image Requirements\n\n| Type | Minimum Resolution | Notes |\n| ------ | ------------------ | ----- |\n| Selfie | 512 × 512 | Face visible, head-to-chest preferred |\n| Shoes | 512 × 512 (product)
800 × 800 (worn) | Clear, unobstructed shoes view |\n\n**Supported Shoes Image**\n\n* Product Image Requirements\n * Minimum resolution: 512 × 512 pixels\n * Only one product per image\n * The product should cover more than 25% of the image height\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/0019_thumb_06a4a9cc5f.jpg)\n\n* Worn Image Requirements\n * Minimum resolution: 800 × 800 pixels\n * Single Item Requirement: The model must wear exactly one item. Multiple items or accessories are not permitted.\n * 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.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/0006_thumb_50a0a0640c.jpg)\n\n**Supported Selfie View**\n\n* Recommended image resolution: at least 512 × 512 pixels.\n* Recommended face coverage: more than 15% of the image height.\n* Single Subject Requirement: The image must contain exactly one human subject. No additional people or partial figures are allowed.\n* Face Visibility: The subject's face must be fully visible without obstruction. Hair, accessories, or objects should not cover key facial features.\n* 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.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/lashana_lynch_thumb_7a900b811e.jpg)\n\n**Try-on Styles**\n\n* There are five predefined styles for generating the virtual try-on output: \"style_minimalist\" \"style_bohemian\" \"style_cottagecore\" \"style_french_elegance\" and \"style_retro_fashion\". You can specify this style parameter when creating an AI task or allow the system to select a style at random by default.\n\n![style_bohemian](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/cc55fe0d_aec9_4ead_b2e9_bc70f48c58b9_670a875b29.jpg)\n\n---\n\n* Supported Formats & Dimensions\n\n| AI Feature | Supported Dimensions | Supported File Size | Supported Formats |\n| ---- | ---- | ---- | ---- |\n| AI Shoes Virtual Try-On | Input: long side <= 4096
Output: 1008 x 1344 | < 10MB | jpg/jpeg/png/heic |\n\n* Error Codes\n\n| Error Code | Description |\n| ------------------------------ | -------------------------------------------- |\n| error\\_download\\_image | Failed to download source or reference image |\n| error\\_inference | Inference pipeline error |\n| error\\_no\\_face | No face detected in source image |\n| error\\_nsfw\\_content\\_detected | NSFW content detected in result |\n| exceed\\_max\\_filesize | File size exceeds 10 MB |\n| invalid\\_parameter | Invalid gender or style value |\n| unknown\\_internal\\_error | Other internal errors |\n\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)
- jquery >= 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"}},{"type":"group","fsPath":"reference/ai_fabric.yaml","link":"/reference/ai_fabric","routeSlug":"/reference/ai_fabric","label":"AI Fabric Virtual Try-On","items":[{"type":"group","label":"Overview","link":"/reference/ai_fabric/section/overview","routeSlug":"/reference/ai_fabric/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_fabric/section/overview/integration-guide","routeSlug":"/reference/ai_fabric/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_fabric/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_fabric/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_fabric/v1.0","routeSlug":"/reference/ai_fabric/v1.0","items":[{"label":"List predefined templates.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_fabric/v1.0/paths/~1s2s~1v2.0~1task~1template~1fabric/get","routeSlug":"/reference/ai_fabric/v1.0/paths/~1s2s~1v2.0~1task~1template~1fabric/get","metadata":{"seo":{"title":"List predefined templates.","description":"List predefined templates."}},"httpPath":"/s2s/v2.0/task/template/fabric"},{"label":"Run an Fabric task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_fabric/v1.0/paths/~1s2s~1v2.0~1task~1fabric/post","routeSlug":"/reference/ai_fabric/v1.0/paths/~1s2s~1v2.0~1task~1fabric/post","metadata":{"seo":{"title":"Run an Fabric task.","description":"Please refer to the polling guide for checking task status."}},"httpPath":"/s2s/v2.0/task/fabric"},{"label":"Check the status of the Fabric task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_fabric/v1.0/paths/~1s2s~1v2.0~1task~1fabric~1{task_id}/get","routeSlug":"/reference/ai_fabric/v1.0/paths/~1s2s~1v2.0~1task~1fabric~1{task_id}/get","metadata":{"seo":{"title":"Check the status of the Fabric task.","description":"Check the status of the Fabric task."}},"httpPath":"/s2s/v2.0/task/fabric/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Fabric Virtual Try-On","version":"","description":"# Overview\nTransform 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!\n\n---\n\n## Integration Guide\n\n* AI Fabric API Usage Guide\n\nThis guide explains how to upload images, fetch predefined fabric styles, and create virtual try-on tasks using the AI Fabric API.\n\n***\n\n * Step 1. Upload a File Using the File API\n\nUse the **File API** (`/s2s/v2.0/file`) to upload a target user image.\n\n**Image Requirements:**\n\n* Upload a high-resolution full-body photo.\n* Ensure the photo clearly shows the entire body.\n* Avoid backgrounds with multiple people or distracting objects.\n\n**Example Request:**\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/jpg\",\n \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\n \"file_size\": 547541\n }\n ]\n }'\n```\n\n***\n\n * Step 2. Retrieve File API Response\n\nThe response includes:\n\n* `file_id` for creating an AI task.\n* `requests.url` for uploading the actual image file.\n\n**Sample Response:**\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"files\": [\n {\n \"content_type\": \"image/jpg\",\n \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\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/jpg\"\n }\n }\n ]\n }\n ]\n }\n}\n```\n\n***\n\n * Step 3. Upload Image to Provided URL\n\nUse the `requests.url` from the File API response to upload the image:\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n --header 'Content-Type: image/jpg' \\\n --header 'Content-Length: 547541' \\\n --data-binary @'./full_body_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n * Step 4. Fetch Predefined Fabric Templates\n\nUse the **Template API** (`/s2s/v2.0/task/template/fabric`) to retrieve a list of predefined fabric templates:\n\n```bash\ncurl --request GET \\\n --url 'https://yce-api-01.makeupar.com/s2s/v2.0/task/template/fabric?page_size=20&starting_token=73a3c9e69b89' \\\n --header 'Authorization: Bearer YOUR_API_KEY'\n```\n\n***\n\n * Step 5. Create an AI Task\n\nUse the **AI Task API** (`/s2s/v2.0/task/fabric`) to create a virtual try-on task.\n\n**Parameters:**\n\n* For the user image: `src_file_id` or `src_file_url`.\n* For the fabric style: `template_id`.\n\n**Example Request:**\n\n```bash\ncurl --request POST \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/fabric \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json' \\\n --data '{\n \"template_id\":\"good_template_001\",\n \"src_file_url\":\"https://example.com/selfie.jpg\"\n }'\n```\n\n**Sample 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 for Task Result\n\nUse the task ID to check the status:\n\n```bash\ncurl --request GET \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/fabric/ \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json'\n```\n\n***\n\n * Step 7. Retrieve Result\n\nA successful response includes a download URL for the result image:\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"error\": null,\n \"results\": {\n \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n },\n \"task_status\": \"success\"\n }\n}\n```\n\nInvalid API Key error response:\n\n```json\n{\n \"status\": 401,\n \"error\": \"Unauthorized\",\n \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\n\nUse cases:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Fabric.png)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2024-05-07/b103976d-1b0e-4bed-aab4-9307308b84d7.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/03%20ai%20clothes%20changer.jpg)\n\nSuggestions for How to Shoot:\n![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\")\n\n---\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|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|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n|error_apply_region_not_detected|The clothing area is either too small or wasn’t detected in the input image\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---"}},{"type":"separator","label":"Jewelry & Watches"},{"type":"group","fsPath":"reference/ring_vto.yaml","link":"/reference/ring_vto","routeSlug":"/reference/ring_vto","label":"AI Ring Virtual Try-On","items":[{"type":"group","label":"Overview","link":"/reference/ring_vto/section/overview","routeSlug":"/reference/ring_vto/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ring_vto/section/overview/integration-guide","routeSlug":"/reference/ring_vto/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ring_vto/section/overview/file-specs-and-errors","routeSlug":"/reference/ring_vto/section/overview/file-specs-and-errors"},{"type":"link","label":"JS Camera Kit","link":"/reference/ring_vto/section/overview/js-camera-kit","routeSlug":"/reference/ring_vto/section/overview/js-camera-kit"}]},{"type":"group","label":"V1.0","link":"/reference/ring_vto/v1.0","routeSlug":"/reference/ring_vto/v1.0","items":[{"label":"Create a new file.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1file~12d-vto~1ring/post","routeSlug":"/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1file~12d-vto~1ring/post","metadata":{"seo":{"title":"Create a new file.","description":"To upload a new file, you'll first need to use the File API. It will give you a URL – use that URL to upload your file. Once the upload is finished, you can use the file_id from the same response to start using our AI features."}},"httpPath":"/s2s/v2.0/file/2d-vto/ring"},{"label":"Run an AI 2D Virtual Try On Ring task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1ring/post","routeSlug":"/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1ring/post","metadata":{"seo":{"title":"Run an AI 2D Virtual Try On Ring 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/2d-vto/ring"},{"label":"Check the status of a AI 2D Virtual Try On Ring task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1ring~1{task_id}/get","routeSlug":"/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1ring~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI 2D Virtual Try On Ring task.","description":"Check the status of a AI 2D Virtual Try On Ring task."}},"httpPath":"/s2s/v2.0/task/2d-vto/ring/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Ring Virtual Try-On","version":"","description":"# Overview\nEasily 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.\n\n## Integration Guide\nThis guide walks you through:\n\n* **Endpoint:** `/s2s/v2.0/task/2d-vto/ring`\n* **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY`\n* **Workflow:**\n 1. **Prepare a hand image:** Uploading an image or provide a valid image URL of your hand\n 1. **Prepare a ring image:** Uploading an image or provide a valid image URL of a ring product\n 1. **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response.\n 1. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `\"success\"` or `\"error\"`.\n\n---\n\n* API Playground\n\nInteractively explore and test the API using our official playground:\n\n**API Playground:**\n[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/)\n\n---\n\n* Authentication\n- Include your API key in the request header using **Bearer Token**:\n ```\n Authorization: Bearer YOUR_API_KEY\n ```\nYou can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.\n\n\n* 1. Upload an Image\n\nYou may upload a file directly to the server or provide a valid image URL in the VTO task payload.\n\n * Upload Endpoint\n\n```\nPOST /s2s/v2.0/file\n```\n\nAlternatively, skip this step if you already have a public image URL.\n\nYou 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.\n\nYou 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`.\n\nThe 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.\n\n---\n\n* 2. Create a Ring VTO Task and Poll for Results\n\nOnce 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`.\n\n * Create Task Endpoint\n\n```\nPOST /s2s/v2.0/task/2d-vto/ring\n```\n\n * Polling Endpoint\n\n```\nGET /s2s/v2.0/task/2d-vto/ring/{task_id}\n```\n\n---\n\n## File Specs & Errors\n\n* AI Ring Virtual Try-On Specification\n\n**Supported Ring View**\nThe ring image must be provided in a three-quarter front view (approximately 45 degrees).\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_product_01_9a4d0680f2_b46afe9a53.jpg)\n\n**Supported Hand View**\nThe back of the hand should be fully visible with all five fingers clearly shown and without any occlusion.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_user_01_6d9893abd0_c7427cdb78.jpg)\n\n**ring\\_wearing\\_finger: integer (0–4)**\nSpecifies the finger on which the ring is worn:\n0 = Thumb\n1 = Index finger\n2 = Middle finger\n3 = Ring finger\n4 = Little finger\n\n**ring\\_wearing\\_location: float (0.0–1.0)**\nIndicates the position along the finger:\n0.0 = Near the MCP joint (large knuckle)\n1.0 = Near the PIP joint (middle joint)\n\n![ring_wearing_location](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_wearing_location_59567be4af.jpg)\n\n**ring\\_shadow\\_intensity: float (0.0–1.0)**\nControls the shadow strength:\n0.0 = No shadow\n1.0 = Maximum shadow\nDefault: 0.15\n\n**ring\\_ambient\\_light\\_intensity: float (0.0–1.0)**\nDefines how much the lighting references the target hand image:\n0.0 = Ignore the hand image lighting\n1.0 = Fully match the hand image lighting and shadow rendering\nDefault: 1.0\n\n**ring\\_anchor\\_point: array of two points in pixel coordinate (optional)**\nMarks 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.\nIf this parameter is not provided, the AI engine will automatically detect the anchor points.\n\n![ring_anchor_point](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_anchor_point_e6eb241ef8.jpg)\n\n\n---\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|AI Ring Virtual Try-On|long side <= 4096 |< 10MB|jpg/jpeg/png|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| RUNTIME_ERROR | An unexpected error occurred during runtime |\n| PHOTO_DETECTION_FAIL | The user photo could not be processed correctly, for example no hand detected |\n| OBJECT_DETECTION_FAIL | The object photo could not be processed correctly, for example no product detected |\n| PHOTO_CHECK_INVALID | The pose or size of the user photo is invalid |\n| INPUT_ERROR | The input file format is incorrect |\n| INPUT_MAIN_IMAGE_EMPTY | A user image is required |\n\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"}},{"type":"group","fsPath":"reference/ai_bracelet.yaml","link":"/reference/ai_bracelet","routeSlug":"/reference/ai_bracelet","label":"AI Bracelet Virtual Try-On","items":[{"type":"group","label":"Overview","link":"/reference/ai_bracelet/section/overview","routeSlug":"/reference/ai_bracelet/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_bracelet/section/overview/integration-guide","routeSlug":"/reference/ai_bracelet/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_bracelet/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_bracelet/section/overview/file-specs-and-errors"},{"type":"link","label":"JS Camera Kit","link":"/reference/ai_bracelet/section/overview/js-camera-kit","routeSlug":"/reference/ai_bracelet/section/overview/js-camera-kit"}]},{"type":"group","label":"V1.0","link":"/reference/ai_bracelet/v1.0","routeSlug":"/reference/ai_bracelet/v1.0","items":[{"label":"Run an AI 2D Virtual Try On Bracelet task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_bracelet/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1bracelet/post","routeSlug":"/reference/ai_bracelet/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1bracelet/post","metadata":{"seo":{"title":"Run an AI 2D Virtual Try On Bracelet task.","description":"This endpoint initiates the bracelet virtual try-on process. You must provide source file(s) and reference image(s) (via URL or File ID), along with specific parameters for alignment and shadowing. The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/2d-vto/bracelet"},{"label":"Check the status of a AI 2D Virtual Try On Bracelet task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_bracelet/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1bracelet~1{task_id}/get","routeSlug":"/reference/ai_bracelet/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1bracelet~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI 2D Virtual Try On Bracelet task.","description":"Check the status of a AI 2D Virtual Try On Bracelet task."}},"httpPath":"/s2s/v2.0/task/2d-vto/bracelet/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Bracelet Virtual Try On","version":"","description":"# Overview\nThe Ultimate AI Bracelet Virtual Try-On\nEmploy AI-powered solutions to assist your customers with online purchases, ensuring perfect fit and great shopping satisfaction every time. Only One 2D Image Needed.\n\nCreate 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.\n\n## Integration Guide\nThis guide walks you through:\n\n* **Endpoint:** `/s2s/v2.0/task/2d-vto/bracelet`\n* **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY`\n* **Workflow:**\n 1. **Prepare a wrist image:** Uploading an image or provide a valid image URL of your wrist\n 1. **Prepare a bracelet image:** Uploading an image or provide a valid image URL of a bracelet product\n 1. **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response.\n 1. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `\"success\"` or `\"error\"`.\n\n---\n\n* API Playground\n\nInteractively explore and test the API using our official playground:\n\n**API Playground:**\n[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/)\n\n---\n\n* Authentication\n- Include your API key in the request header using **Bearer Token**:\n ```\n Authorization: Bearer YOUR_API_KEY\n ```\nYou can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.\n\n\n* 1. Upload an Image\n\nYou may upload a file directly to the server or provide a valid image URL in the VTO task payload.\n\n * Upload Endpoint\n\n```\nPOST /s2s/v2.0/file\n```\n\nAlternatively, skip this step if you already have a public image URL.\n\nYou 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.\n\nYou 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`.\n\nThe 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.\n\n---\n\n* 2. Create a Bracelet VTO Task and Poll for Results\n\nOnce 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`.\n\n * Create Task Endpoint\n\n```\nPOST /s2s/v2.0/task/2d-vto/bracelet\n```\n\n * Polling Endpoint\n\n```\nGET /s2s/v2.0/task/2d-vto/bracelet/{task_id}\n```\n\n---\n\n## File Specs & Errors\n\n* AI Bracelet Virtual Try-On Specification\n\n**Supported Bracelet View**\nA bracelet image must be provided in a three-quarter front view (approximately 45 degrees).\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/bracelet_product_09_2cb9721d77_2f8d90ab9f.jpg)\n\n**Supported Wrist View**\nThe back of the wrist should be fully visible with all five fingers clearly shown and without any occlusion.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/watch_and_bracelet_user_01_09f16603cb_878dc89179.jpg)\n\n**bracelet\\_wearing\\_location: float (−0.3 to 1.0)**\nIndicates the position along the wrist:\n−0.3 represents near the main wrist joint\n1.0 represents far from the main wrist joint\nDefault value: null (use engine default)\n\n![bracelet_wearing_location](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/bracelet_wearing_location_01ac0a048e.jpg)\n\n**bracelet\\_shadow\\_intensity: float (0.0 to 1.0)**\nControls the strength of the shadow:\n0.0 represents no shadow\n1.0 represents maximum shadow\nDefault value: 0.15\n\n**bracelet\\_ambient\\_light\\_intensity: float (0.0 to 1.0)**\nDefines the extent to which lighting references the target hand image:\n0.0 ignores the hand image lighting\n1.0 fully matches the hand image lighting and shadow rendering\nDefault value: 1.0\n\n**Bracelet Anchor Points: array of 2 points in pixel coordinate (optional)**\nMarks the inner edge of the bracelet where it contacts the wrist, specifying the left and right points.\nIf this parameter is not provided, the AI engine will automatically detect the anchor points.\n![bracelet_anchor_point](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/bracelet_anchor_point_c353245edc.jpg)\n\n---\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|AI Bracelet Virtual Try-On|long side <= 4096 |< 10MB|jpg/jpeg/png|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| RUNTIME_ERROR | An unexpected error occurred dubracelet runtime |\n| PHOTO_DETECTION_FAIL | The user photo could not be processed correctly, for example no hand detected |\n| OBJECT_DETECTION_FAIL | The object photo could not be processed correctly, for example no product detected |\n| PHOTO_CHECK_INVALID | The pose or size of the user photo is invalid |\n| INPUT_ERROR | The input file format is incorrect |\n| INPUT_MAIN_IMAGE_EMPTY | A user image is required |\n\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"}},{"type":"group","fsPath":"reference/ai_watch.yaml","link":"/reference/ai_watch","routeSlug":"/reference/ai_watch","label":"AI Watch Virtual Try-On","items":[{"type":"group","label":"Overview","link":"/reference/ai_watch/section/overview","routeSlug":"/reference/ai_watch/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_watch/section/overview/integration-guide","routeSlug":"/reference/ai_watch/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_watch/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_watch/section/overview/file-specs-and-errors"},{"type":"link","label":"JS Camera Kit","link":"/reference/ai_watch/section/overview/js-camera-kit","routeSlug":"/reference/ai_watch/section/overview/js-camera-kit"}]},{"type":"group","label":"V2.0","link":"/reference/ai_watch/v2.0","routeSlug":"/reference/ai_watch/v2.0","items":[{"label":"Run an AI 2D Virtual Try On Watch task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_watch/v2.0/paths/~1s2s~1v2.0~1task~12d-vto~1watch/post","routeSlug":"/reference/ai_watch/v2.0/paths/~1s2s~1v2.0~1task~12d-vto~1watch/post","metadata":{"seo":{"title":"Run an AI 2D Virtual Try On Watch task.","description":"This endpoint initiates the watch virtual try-on process. You must provide source file(s) and reference image(s) (via URL or File ID), along with specific parameters for alignment, shadowing, and wearing location. The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/2d-vto/watch"},{"label":"Check the status of a AI 2D Virtual Try On Watch task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_watch/v2.0/paths/~1s2s~1v2.0~1task~12d-vto~1watch~1{task_id}/get","routeSlug":"/reference/ai_watch/v2.0/paths/~1s2s~1v2.0~1task~12d-vto~1watch~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI 2D Virtual Try On Watch task.","description":"Check the status of a AI 2D Virtual Try On Watch task."}},"httpPath":"/s2s/v2.0/task/2d-vto/watch/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Watch Virtual Try On","version":"","description":"# Overview\nVirtually Try-On AR Watches with Ease! Only One 2D Image Needed.\n\nWith 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.\n\n## Integration Guide\nThis guide walks you through:\n\n* **Endpoint:** `/s2s/v2.0/task/2d-vto/watch`\n* **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY`\n* **Workflow:**\n 1. **Prepare a wrist image:** Uploading an image or provide a valid image URL of your wrist\n 1. **Prepare a watch image:** Uploading an image or provide a valid image URL of a watch product\n 1. **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response.\n 1. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `\"success\"` or `\"error\"`.\n\n---\n\n* API Playground\n\nInteractively explore and test the API using our official playground:\n\n**API Playground:**\n[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/)\n\n---\n\n* Authentication\n- Include your API key in the request header using **Bearer Token**:\n ```\n Authorization: Bearer YOUR_API_KEY\n ```\nYou can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.\n\n\n* 1. Upload an Image\n\nYou may upload a file directly to the server or provide a valid image URL in the VTO task payload.\n\n * Upload Endpoint\n\n```\nPOST /s2s/v2.0/file\n```\n\nAlternatively, skip this step if you already have a public image URL.\n\nYou 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.\n\nYou 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`.\n\nThe 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.\n\n---\n\n* 2. Create a Watch VTO Task and Poll for Results\n\nOnce 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`.\n\n * Create Task Endpoint\n\n```\nPOST /s2s/v2.0/task/2d-vto/watch\n```\n\n * Polling Endpoint\n\n```\nGET /s2s/v2.0/task/2d-vto/watch/{task_id}\n```\n\n---\n\n## File Specs & Errors\n\n* AI Watch Virtual Try-On Specification\n\n**Supported Watch View**\nA watch image in a clear front view with the watch face unobstructed. The strap should be cropped to resemble a realistic wearing length.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/watch_product_01_aab8053028_50ab7fe9a5.jpg)\n\n**Supported Wrist View**\nThe back of the wrist should be fully visible with all five fingers clearly shown and without any occlusion.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/watch_and_bracelet_user_01_09f16603cb_878dc89179.jpg)\n\n**watch\\_wearing\\_location: float (−0.3 to 1.0)**\nIndicates the position along the wrist:\n−0.3 represents near the main wrist joint\n1.0 represents far from the main wrist joint\nDefault value: null (use engine default)\n\n![watch_wearing_location](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/bracelet_wearing_location_01ac0a048e.jpg)\n\n**watch\\_shadow\\_intensity: float (0.0 to 1.0)**\nControls the strength of the shadow:\n0.0 represents no shadow\n1.0 represents maximum shadow\nDefault value: 0.15\n\n**watch\\_ambient\\_light\\_intensity: float (0.0 to 1.0)**\nDefines the extent to which lighting references the target hand image:\n0.0 ignores the hand image lighting\n1.0 fully matches the hand image lighting and shadow rendering\nDefault value: 1.0\n\n**Watch Anchor Points: array of 4 points in pixel coordinate (optional)**\nThe first two points mark the beginning and end of the strap when worn.\nThe remaining two points mark the upper and lower edges of the watch case.\n\n![watch_anchor_point](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Product_anchors_ece6851c88.jpg)\n\n---\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|AI Watch Virtual Try-On|long side <= 4096 |< 10MB|jpg/jpeg/png|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| RUNTIME_ERROR | An unexpected error occurred duwatch runtime |\n| PHOTO_DETECTION_FAIL | The user photo could not be processed correctly, for example no hand detected |\n| OBJECT_DETECTION_FAIL | The object photo could not be processed correctly, for example no product detected |\n| PHOTO_CHECK_INVALID | The pose or size of the user photo is invalid |\n| INPUT_ERROR | The input file format is incorrect |\n| INPUT_MAIN_IMAGE_EMPTY | A user image is required |\n\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"}},{"type":"group","fsPath":"reference/ai_earrings.yaml","link":"/reference/ai_earrings","routeSlug":"/reference/ai_earrings","label":"AI Earrings Virtual Try-On","items":[{"type":"group","label":"Overview","link":"/reference/ai_earrings/section/overview","routeSlug":"/reference/ai_earrings/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_earrings/section/overview/integration-guide","routeSlug":"/reference/ai_earrings/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_earrings/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_earrings/section/overview/file-specs-and-errors"},{"type":"link","label":"JS Camera Kit","link":"/reference/ai_earrings/section/overview/js-camera-kit","routeSlug":"/reference/ai_earrings/section/overview/js-camera-kit"}]},{"type":"group","label":"V1.0","link":"/reference/ai_earrings/v1.0","routeSlug":"/reference/ai_earrings/v1.0","items":[{"label":"Run an AI 2D Virtual Try On Earring task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1earring/post","routeSlug":"/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1earring/post","metadata":{"seo":{"title":"Run an AI 2D Virtual Try On Earring task.","description":"This endpoint initiates the earring virtual try-on process. You must provide source file(s) and reference image(s) (via URL or File ID), along with specific parameters for alignment, shadowing, and wearing location. The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/2d-vto/earring"},{"label":"Check the status of a AI 2D Virtual Try On Earring task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1earring~1{task_id}/get","routeSlug":"/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1earring~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI 2D Virtual Try On Earring task.","description":"Check the status of a AI 2D Virtual Try On Earring task."}},"httpPath":"/s2s/v2.0/task/2d-vto/earring/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Earrings Virtual Try On","version":"","description":"# Overview\nThe Ultimate AI Earring Virtual Try-On\nTop AI ear piercing simulator for virtual earring try-on and virtual piercing try-on\n\nCreate realistic and dynamic earrings vitual 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.\n\n## Integration Guide\nThis guide walks you through:\n\n* **Endpoint:** `/s2s/v2.0/task/2d-vto/earring`\n* **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY`\n* **Workflow:**\n 1. **Prepare a selfie image:** Uploading an image or provide a valid image URL\n 2. **Prepare an earring image:** Uploading an image or provide a valid image URL of an earring product\n 3. **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response.\n 4. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `\"success\"` or `\"error\"`.\n\n---\n\n* API Playground\n\nInteractively explore and test the API using our official playground:\n\n**API Playground:**\n[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/)\n\n---\n\n* Authentication\n- Include your API key in the request header using **Bearer Token**:\n ```\n Authorization: Bearer YOUR_API_KEY\n ```\nYou can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.\n\n\n* 1. Upload an Image\n\nYou may upload a file directly to the server or provide a valid image URL in the VTO task payload.\n\n * Upload Endpoint\n\n```\nPOST /s2s/v2.0/file\n```\n\nAlternatively, skip this step if you already have a public image URL.\n\nYou 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.\n\nYou 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`.\n\nThe 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.\n\n---\n\n* 2. Create a Earring VTO Task and Poll for Results\n\nOnce 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`.\n\n * Create Task Endpoint\n\n```\nPOST /s2s/v2.0/task/2d-vto/earring\n```\n\n * Polling Endpoint\n\n```\nGET /s2s/v2.0/task/2d-vto/earring/{task_id}\n```\n\n---\n\n## File Specs & Errors\n\n* AI Earring Virtual Try-On Specification\n\n**Supported Earring Reference Image**\n* A single earring image in a clear front view without obstruction.\n* All parameters (including anchor points, masks, location, etc.) apply **only** when the reference image shows a **single earring** being worn.\n* If the try-on reference image shows **both earrings**, all parameters will use **auto-detection and default settings**.\n* When trying on **both earrings**, the clearer ear will be used as the source, and the other ear will be generated by mirroring it.\n\n![](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)\n\n**Supported Selfie View**\n\n* The AI Earring Virtual Try-On supports front-facing images, but the best results are achieved with side-facing images.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Earring_restriction_cdf1de3c7b.png)\n\n**earring\\_wearing\\_location: integer array of size 2**\nSpecifies the target location in the selfie where the earring should be placed.\nDefault value: null (engine default)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/wearing_location_b4f6f4453a.jpg)\n\n**earring\\_scale: number greater than 0**\nControls the earring size in centimetres.\nDefault value: null (engine default)\n\n**earring\\_is\\_right\\_ear: boolean**\nIndicates whether the earring is worn on the right ear. By default, it is worn on the right ear.\nDefault value: true\n\n**earring\\_occluded\\_type: number (Enum: 0, 1, 2)**\nSpecifies the occlusion type:\n0 means auto-detect\n1 means occluded\n2 means no occlusion\nDefault value: 0\n\n**earring\\_shadow\\_intensity: float (0.0 to 1.0)**\nControls the shadow strength:\n0.0 represents no shadow\n1.0 represents maximum shadow\nDefault value: 0.15\n\n**earring\\_ambient\\_light\\_intensity: float (0.0 to 1.0)**\nDefines how much the lighting references the selfie image:\n0.0 ignores the selfie image lighting\n1.0 fully matches the selfie image lighting and shadow rendering\nDefault value: 1.0\n\n**earring\\_anchor\\_point: array of one point in pixel coordinate (optional)**\nSpecifies the wearing position in the earring product image.\nDefault value: null (engine default)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/anchor_point_787282aa19.jpg)\n\n\n---\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|AI Earring Virtual Try-On|long side <= 4096 |< 10MB|jpg/jpeg/png|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| RUNTIME_ERROR | An unexpected error occurred duearring runtime |\n| PHOTO_DETECTION_FAIL | The user photo could not be processed correctly, for example no hand detected |\n| OBJECT_DETECTION_FAIL | The object photo could not be processed correctly, for example no product detected |\n| PHOTO_CHECK_INVALID | The pose or size of the user photo is invalid |\n| INPUT_ERROR | The input file format is incorrect |\n| INPUT_MAIN_IMAGE_EMPTY | A user image is required |\n\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"}},{"type":"group","fsPath":"reference/ai_necklace.yaml","link":"/reference/ai_necklace","routeSlug":"/reference/ai_necklace","label":"AI Necklace Virtual Try-On","items":[{"type":"group","label":"Overview","link":"/reference/ai_necklace/section/overview","routeSlug":"/reference/ai_necklace/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_necklace/section/overview/integration-guide","routeSlug":"/reference/ai_necklace/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_necklace/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_necklace/section/overview/file-specs-and-errors"},{"type":"link","label":"JS Camera Kit","link":"/reference/ai_necklace/section/overview/js-camera-kit","routeSlug":"/reference/ai_necklace/section/overview/js-camera-kit"}]},{"type":"group","label":"V1.0","link":"/reference/ai_necklace/v1.0","routeSlug":"/reference/ai_necklace/v1.0","items":[{"label":"Run an AI 2D Virtual Try On Necklace task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_necklace/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1necklace/post","routeSlug":"/reference/ai_necklace/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1necklace/post","metadata":{"seo":{"title":"Run an AI 2D Virtual Try On Necklace task.","description":"This endpoint initiates the necklace virtual try-on process. You must provide source file(s) and reference image(s) (via URL or File ID), along with specific parameters for alignment, shadowing, and wearing location. The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/2d-vto/necklace"},{"label":"Check the status of a AI 2D Virtual Try On Necklace task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_necklace/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1necklace~1{task_id}/get","routeSlug":"/reference/ai_necklace/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1necklace~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI 2D Virtual Try On Necklace task.","description":"Check the status of a AI 2D Virtual Try On Necklace task."}},"httpPath":"/s2s/v2.0/task/2d-vto/necklace/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Necklace Virtual Try On","version":"","description":"# Overview\nLuxurious Look and Feel with State-of-the-Art Virtual Try-On for Necklace\nPrecise AI neck and clavicle tracking gives users an ultra-realistic AR try-on experience, recreating the luxurious look and feel of physical necklace sampling.\n\nCreate 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.\n\n## Integration Guide\nThis guide walks you through:\n\n* **Endpoint:** `/s2s/v2.0/task/2d-vto/necklace`\n* **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY`\n* **Workflow:**\n 1. **Prepare a selfie image:** Uploading an image or provide a valid image URL\n 2. **Prepare a necklace image:** Uploading an image or provide a valid image URL of a necklace product\n 3. **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response.\n 4. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `\"success\"` or `\"error\"`.\n\n---\n\n* API Playground\n\nInteractively explore and test the API using our official playground:\n\n**API Playground:**\n[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/)\n\n---\n\n* Authentication\n- Include your API key in the request header using **Bearer Token**:\n ```\n Authorization: Bearer YOUR_API_KEY\n ```\nYou can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.\n\n\n* 1. Upload an Image\n\nYou may upload a file directly to the server or provide a valid image URL in the VTO task payload.\n\n * Upload Endpoint\n\n```\nPOST /s2s/v2.0/file\n```\n\nAlternatively, skip this step if you already have a public image URL.\n\nYou 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.\n\nYou 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`.\n\nThe 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.\n\n---\n\n* 2. Create a Necklace VTO Task and Poll for Results\n\nOnce 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`.\n\n * Create Task Endpoint\n\n```\nPOST /s2s/v2.0/task/2d-vto/necklace\n```\n\n * Polling Endpoint\n\n```\nGET /s2s/v2.0/task/2d-vto/necklace/{task_id}\n```\n\n---\n\n## File Specs & Errors\n\n* AI Necklace Virtual Try-On Specification\n\n**Supported Necklace View**\nA front-facing image of the necklace worn, with the background removed.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/necklace_product_01_124206cfbe_3993a2128d.jpg)\n\n**Supported Selfie View**\nA 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.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Necklace_restriction_83410fb6c1.png)\n\n**necklace\\_wearing\\_location: array of two points (optional)**\nSpecifies the target locations in the photo where the necklace should be placed.\nDefault: null (engine default)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/wearing_location_874264bb70.jpg)\n\n**necklace\\_shadow\\_intensity: float (0.0 to 1.0)**\nControls the shadow strength:\n0.0 represents no shadow\n1.0 represents maximum shadow\nDefault value: 0.15\n\n**necklace\\_ambient\\_light\\_intensity: float (0.0 to 1.0)**\nDefines how much the lighting references the selfie image:\n0.0 ignores the selfie image lighting\n1.0 fully matches the selfie image lighting and shadow rendering\nDefault value: 1.0\n\n**necklace\\_anchor\\_point: array of two points in pixel coordinate (optional)**\nSpecifies the anchor points for the left and right visible ends of the necklace chain in the product image, used for alignment.\nDefault: null (engine default)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/anchor_point_7f9b254ca4.jpg)\n\n---\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|AI Necklace Virtual Try-On|long side <= 4096 |< 10MB|jpg/jpeg/png|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| RUNTIME_ERROR | An unexpected error occurred dunecklace runtime |\n| PHOTO_DETECTION_FAIL | The user photo could not be processed correctly, for example no neck detected |\n| OBJECT_DETECTION_FAIL | The object photo could not be processed correctly, for example no product detected |\n| PHOTO_CHECK_INVALID | The pose or size of the user photo is invalid |\n| INPUT_ERROR | The input file format is incorrect |\n| INPUT_MAIN_IMAGE_EMPTY | A user image is required |\n\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"}},{"type":"separator","label":"Image"},{"type":"group","fsPath":"reference/ai_face_swap.yaml","link":"/reference/ai_face_swap","routeSlug":"/reference/ai_face_swap","label":"AI Face Swap","items":[{"type":"group","label":"Overview","link":"/reference/ai_face_swap/section/overview","routeSlug":"/reference/ai_face_swap/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_face_swap/section/overview/integration-guide","routeSlug":"/reference/ai_face_swap/section/overview/integration-guide"},{"type":"link","label":"Inputs & Outputs","link":"/reference/ai_face_swap/section/overview/inputs-and-outputs","routeSlug":"/reference/ai_face_swap/section/overview/inputs-and-outputs"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_face_swap/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_face_swap/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_face_swap/v1.0","routeSlug":"/reference/ai_face_swap/v1.0","items":[{"label":"Run an AI Face Swap face detection task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1pre-process/post","routeSlug":"/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1pre-process/post","metadata":{"seo":{"title":"Run an AI Face Swap face detection task.","description":"Use the pre-process task when the source image may contain more than one valid target, or when your integration needs to explicitly choose which detected target receives the effect. For single-target images, pre-process can be skipped when the feature supports a default index value and your application does not need manual target selection."}},"httpPath":"/s2s/v2.0/task/face-swap/pre-process"},{"label":"Check a AI Face Swap face detection task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1pre-process~1{task_id}/get","routeSlug":"/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1pre-process~1{task_id}/get","metadata":{"seo":{"title":"Check a AI Face Swap face detection task status.","description":"Check a AI Face Swap face detection task status."}},"httpPath":"/s2s/v2.0/task/face-swap/pre-process/{task_id}"},{"label":"Run an AI Face Swap task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap/post","routeSlug":"/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap/post","metadata":{"seo":{"title":"Run an AI Face Swap 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/face-swap"},{"label":"Check a AI Face Swap task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1{task_id}/get","routeSlug":"/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1{task_id}/get","metadata":{"seo":{"title":"Check a AI Face Swap task status.","description":"Check a AI Face Swap task status."}},"httpPath":"/s2s/v2.0/task/face-swap/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Face Swap","version":"","description":"# Overview\nUsing 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.\n\n## Integration Guide\n* How to implement AI Face Swap\n\n * Step 1: Upload source and reference images\n\n 1. Request upload URLs from the API:\n\n ```\n POST https://yce-api-01.makeupar.com/s2s/v2.0/file\n Authorization: Bearer YOUR_API_KEY\n Content-Type: application/json\n ```\n\n Body:\n\n ```json\n {\n \"files\": [\n {\n \"file_name\": \"target.jpg\",\n \"file_size\": 123456,\n \"content_type\": \"image/jpeg\"\n }\n ]\n }\n ```\n 1. The response provides a pre-signed **upload URL** and a `file_id`.\n 2. Upload your file with an HTTP PUT request to the given URL.\n 3. Store the `file_id` for later use. Repeat this for both **target** and **reference** images.\n\n 2. Upload the actual file to the **upload URL**.\n\n---\n\n * Step 2: Pre-process the source and reference images (face detection)\n\n 1. Create a pre-process task:\n\n ```\n POST https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process\n Authorization: Bearer YOUR_API_KEY\n Content-Type: application/json\n ```\n\n Body:\n\n ```json\n {\n \"request_id\": 1,\n \"payload\": {\n \"file_sets\": {\n \"src_ids\": [\"TARGET_FILE_ID\"]\n },\n \"actions\": [\n { \"id\": 0 }\n ]\n }\n }\n ```\n 1. The API returns a `task_id`.\n 2. Poll task status at:\n\n ```\n GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process?task_id=TASK_ID\n ```\n 1. When finished, you receive a list of detected faces with bounding boxes.\n\n---\n\n * Step 3: Run the face swap task\n 1. Define which reference image will substitute each source image\n 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.\n\n * Structure\n\n Each element in the array is an object containing two properties:\n\n | Parameter | Type | Description |\n | :--- | :--- | :--- |\n | `position` | `integer` | The index of the face detected in the **Source Image** (e.g., 0, 1, 2). |\n | `index` | `integer` | The index of the face image in the **Reference Image List** to swap with. |\n\n * Logic Rules\n 1. **Index Mapping:** The `index` maps directly to the order of images provided in your reference list.\n * `0`: First Reference Image.\n * `1`: Second Reference Image.\n 2. **Skipping Swaps:** To skip swapping a specific face detected in the source, set both `index` and `position` to `-1`.\n 3. **Array Order:** The order of objects in the array should match based on `position`.\n\n * Example Use Case\n\n **Scenario:**\n * **Reference List:** 2 images provided (Image A, Image B).\n * **Source Image:** Contains 3 faces detected (Face 0, Face 1, Face 2).\n\n **Goal:**\n * Swap **Face 0** (Source) with **Image 1** (Reference).\n * Skip swapping **Face 1** (Source).\n * Swap **Face 2** (Source) with **Image 0** (Reference).\n\n **Configuration:**\n\n ```json\n \"face_mapping\": [\n {\n \"index\": 1, // Use the second reference image\n \"position\": 0 // Apply to the first detected face in source\n },\n {\n \"index\": -1, // Skip swapping\n \"position\": -1 // Skip swapping\n },\n {\n \"index\": 0, // Use the first reference image\n \"position\": 2 // Apply to the third detected face in source\n }\n ]\n ```\n\n 1. Send the main task request:\n\n ```\n POST https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap\n Authorization: Bearer YOUR_API_KEY\n Content-Type: application/json\n ```\n\n Body:\n\n ```json\n {\n \"request_id\": 2,\n \"payload\": {\n \"file_sets\": {\n \"src_ids\": [\"TARGET_FILE_ID\"],\n \"ref_ids\": [\"REFERENCE_FILE_ID\"]\n },\n \"actions\": [\n {\n \"id\": 0,\n \"params\": {\n \"face_mapping\": [\n { \"index\": 0, \"position\": 0 },\n { \"index\": -1, \"position\": -1 }\n ]\n }\n }\n ]\n }\n }\n ```\n 1. The response returns a `task_id`.\n\n---\n\n * Step 4: Poll task status and retrieve result\n It’s necessary to implement a timed loop that queries the task status at regular intervals within the allowed polling window.\n 1. Poll at:\n\n ```\n GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap?task_id=TASK_ID\n ```\n 2. When `status` is `success`, the response contains a URL for the generated image.\n 3. Download or display the image from that URL.\n\n---\n\n * Step 5: Integrate into your platform\n\n * On a **web frontend**, you can directly implement this with JavaScript using fetch or Axios.\n * On a **backend** (Node.js, Python, Java, PHP, etc.), you can use the same endpoints with standard HTTP libraries.\n * Implement retry and error handling since the tasks run asynchronously.\n\n---\n\n * Debugging Guide\n 1. **Invalid TaskId Error**\n
**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.\n
**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.\n\n 2. **Why are some faces not detected in my source image**\n
**Why:** Reason: The face must be clearly visible, not covered or obstructed, and large enough within the image\n
**Solution:** Try taking a photo where the face appears larger and is clearly visible without any covering or obstruction\n\n---\n\n## Inputs & Outputs\n\n* Real-world examples:\nMultiple faces swap sample:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_face_swap_S2_img_04_d4b747a41d.jpg)\n\nSingle face swap sample:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_face_swap_S2_img_05_8e68faff2c.jpg)\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\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|AI Face Swap|Input and output: the long side must be less than or equal to 4096 pixels|< 10MB|jpg/jpeg/png|\n\n\n* Error Codes\n\n| Error Code | Description |\n| ------------------ | ----------- |\n| exceed_max_filesize | The input file size exceeds the maximum limit |\n| invalid_parameter | The parameter value is invalid |\n| error_download_image | There was an error downloading the source image |\n| error_download_mask | There was an error downloading the mask image |\n| error_decode_image | There was an error decoding the source image |\n| error_decode_mask | There was an error decoding the mask image |\n| error_download_video | There was an error downloading the source video |\n| error_decode_video | There was an error decoding the source video |\n| error_nsfw_content_detected | NSFW content was detected in the source image |\n| error_no_face | No face was detected in the source image |\n| error_pose | Failed to detect pose in the source image |\n| error_face_parsing | Failed to perform face parsing on the source image |\n| error_inference | An error occurred in the inference pipeline |\n| exceed_nsfw_retry_limits | Retry limits exceeded to avoid generating NSFW image |\n| error_upload | There was an error uploading the result image |\n| error_multiple_people | People count exceeds the maximum limit |\n| error_no_shoulder | Shoulders are not visible in the source image |\n| error_large_face_angle | The face angle in the uploaded image is too large |\n| error_unsupport_ratio | The aspect ratio of the input image is unsupported |\n| unknown_internal_error | Other internal errors |\n"}},{"type":"group","fsPath":"reference/ai_image_extender.yaml","link":"/reference/ai_image_extender","routeSlug":"/reference/ai_image_extender","label":"AI Image Extender","items":[{"type":"group","label":"Overview","link":"/reference/ai_image_extender/section/overview","routeSlug":"/reference/ai_image_extender/section/overview","items":[{"type":"link","label":"File Specs & Errors","link":"/reference/ai_image_extender/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_image_extender/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V2.0","link":"/reference/ai_image_extender/v2.0","routeSlug":"/reference/ai_image_extender/v2.0","items":[{"label":"Run an AI Image Extender task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_image_extender/v2.0/paths/~1s2s~1v2.0~1task~1out-paint/post","routeSlug":"/reference/ai_image_extender/v2.0/paths/~1s2s~1v2.0~1task~1out-paint/post","metadata":{"seo":{"title":"Run an AI Image Extender task.","description":"Please refer to the polling guide for checking task status. The API takes 3 key parameters: input image, pivot point, and output image."}},"httpPath":"/s2s/v2.0/task/out-paint"},{"label":"Check an AI Image Extender task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_image_extender/v2.0/paths/~1s2s~1v2.0~1task~1out-paint~1{task_id}/get","routeSlug":"/reference/ai_image_extender/v2.0/paths/~1s2s~1v2.0~1task~1out-paint~1{task_id}/get","metadata":{"seo":{"title":"Check an AI Image Extender task status.","description":"Check an AI Image Extender task status."}},"httpPath":"/s2s/v2.0/task/out-paint/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Image Extender","version":"","description":"# Overview\nExperience 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.\n\n![AI Image Extender](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_outpainting_S1_img_03_cf19a018d9.jpg \"AI Image Extender\")\n\nWhether 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.\n\n![AI Image Extender](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_outpainting_S1_img_01_1876fb85a5.jpg \"AI Image Extender\")\n\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n| AI Feature | Supported Dimensions | Supported File Size | Supported Formats |\n| ---- | ---- | ---- | ---- |\n| AI Image Extender | long side <= 4096 | < 10MB | jpg/jpeg |\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| exceed_max_filesize |\tInput file size exceeds the maximum limit |\n| invalid_parameter |\tInvalid parameter value |\n| error_download_image\t| Download source image error |\n| error_decode_image\t| Decode source image error |\n| error_nsfw_content_detected\t| NSFW content detected in source image |\n"}},{"type":"group","fsPath":"reference/ai_object_removal_pro.yaml","link":"/reference/ai_object_removal_pro","routeSlug":"/reference/ai_object_removal_pro","label":"AI Object Removal Pro","items":[{"type":"link","label":"Overview","link":"/reference/ai_object_removal_pro/section/overview","routeSlug":"/reference/ai_object_removal_pro/section/overview"},{"type":"group","label":"V4.0","link":"/reference/ai_object_removal_pro/v4.0","routeSlug":"/reference/ai_object_removal_pro/v4.0","items":[{"label":"Run an AI Object Removal Pro task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_object_removal_pro/v4.0/paths/~1s2s~1v2.0~1task~1generative-fill/post","routeSlug":"/reference/ai_object_removal_pro/v4.0/paths/~1s2s~1v2.0~1task~1generative-fill/post","metadata":{"seo":{"title":"Run an AI Object Removal Pro 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/generative-fill"},{"label":"Check an AI Object Removal Pro task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_object_removal_pro/v4.0/paths/~1s2s~1v2.0~1task~1generative-fill~1{task_id}/get","routeSlug":"/reference/ai_object_removal_pro/v4.0/paths/~1s2s~1v2.0~1task~1generative-fill~1{task_id}/get","metadata":{"seo":{"title":"Check an AI Object Removal Pro task status.","description":"Check an AI Object Removal Pro task status."}},"httpPath":"/s2s/v2.0/task/generative-fill/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Object Removal Pro","version":"","description":"# Overview\nExperience flawless photo editing with our advanced AI Object Removal Pro technology.\nRemove unwanted elements such as people, reflections and shadows while keeping every fine detail intact.\nUpload your photo along with a simple grayscale mask and receive clean and natural looking results that elevate your visual content.\n\nSample usage:\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/YCE_web_relayout_sign_in_index_Object_Removal_b93ad75683.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2026-02-26/webp_6b27a29f-eab0-4205-a69d-d001fffd12ea.jpg)\n"}},{"type":"group","fsPath":"reference/ai_photo_enhance.yaml","link":"/reference/ai_photo_enhance","routeSlug":"/reference/ai_photo_enhance","label":"AI Photo Enhance","items":[{"type":"group","label":"Overview","link":"/reference/ai_photo_enhance/section/overview","routeSlug":"/reference/ai_photo_enhance/section/overview","items":[{"type":"link","label":"File Specs & Errors","link":"/reference/ai_photo_enhance/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_photo_enhance/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_photo_enhance/v1.0","routeSlug":"/reference/ai_photo_enhance/v1.0","items":[{"label":"Run an AI Photo Enhance task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_photo_enhance/v1.0/paths/~1s2s~1v2.0~1task~1enhance/post","routeSlug":"/reference/ai_photo_enhance/v1.0/paths/~1s2s~1v2.0~1task~1enhance/post","metadata":{"seo":{"title":"Run an AI Photo Enhance task.","description":"This endpoint initiates the photo enhancement process. You must provide a file ID obtained from the file upload API. The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/enhance"},{"label":"Check an AI Photo Enhance task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_photo_enhance/v1.0/paths/~1s2s~1v2.0~1task~1enhance~1{task_id}/get","routeSlug":"/reference/ai_photo_enhance/v1.0/paths/~1s2s~1v2.0~1task~1enhance~1{task_id}/get","metadata":{"seo":{"title":"Check an AI Photo Enhance task status.","description":"Check an AI Photo Enhance task status."}},"httpPath":"/s2s/v2.0/task/enhance/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Photo Enhance","version":"","description":"# Overview\nAI Photo Enhance uses advanced AI and deep learning to analyze image details and improve resolution, making low-resolution images clear & fix motion blur.\n * No More Pixelation: Eliminate pixelation for smoother, more defined images.\n * Fix Blurry Photos: Remove blurriness to reveal sharper, crisper details.\n * Enhance Quality: Bring out finer details, making every part of your image stand out.\n * Sharpen Images: Increase sharpness for clearer and more vivid images.\n * Improve Clarity: Boost overall clarity to make your photos look fresh and professional.\n * Face Enhancement: Refine facial features for more lifelike, enhanced portraits in motional images.\n\nBefore sample:\n![AI Photo Enhance](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_s5_poster_1_0779bbdbdb.jpg \"AI Photo Enhance\")\n\nAfter sample:\n![AI Photo Enhance](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_s5_poster_2_a2e15250ef.jpg \"AI Photo Enhance\")\n\n\nBefore sample:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_s2_poster_1_4cd6425807.jpg)\n\nAfter sample:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_s2_poster_2_7674281362.jpg)\n\n---\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n| AI Feature | Supported Dimensions | Supported File Size | Supported Formats |\n| ---- | ---- | ---- | ---- |\n| AI Photo Enhance | long side <= 4096 | < 10MB | jpg/jpeg/png |\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| exceed_max_filesize |\tInput file size exceeds the maximum limit |\n| invalid_parameter |\tInvalid parameter value |\n| error_download_image\t| Download source image error |\n| error_decode_image\t| Decode source image error |\n| error_nsfw_content_detected\t| NSFW content detected in source image |\n"}},{"type":"group","fsPath":"reference/ai_background_removal.yaml","link":"/reference/ai_background_removal","routeSlug":"/reference/ai_background_removal","label":"AI Photo Background Removal","items":[{"type":"group","label":"Overview","link":"/reference/ai_background_removal/section/overview","routeSlug":"/reference/ai_background_removal/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_background_removal/section/overview/integration-guide","routeSlug":"/reference/ai_background_removal/section/overview/integration-guide"},{"type":"link","label":"Inputs & Outputs","link":"/reference/ai_background_removal/section/overview/inputs-and-outputs","routeSlug":"/reference/ai_background_removal/section/overview/inputs-and-outputs"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_background_removal/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_background_removal/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_background_removal/v1.0","routeSlug":"/reference/ai_background_removal/v1.0","items":[{"label":"Run an AI Photo Background Removal task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_background_removal/v1.0/paths/~1s2s~1v2.0~1task~1sod/post","routeSlug":"/reference/ai_background_removal/v1.0/paths/~1s2s~1v2.0~1task~1sod/post","metadata":{"seo":{"title":"Run an AI Photo Background Removal task.","description":"This endpoint initiates the background removal process. You must provide a file ID obtained from the file upload API. The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/sod"},{"label":"Check an AI Photo Background Removal task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_background_removal/v1.0/paths/~1s2s~1v2.0~1task~1sod~1{task_id}/get","routeSlug":"/reference/ai_background_removal/v1.0/paths/~1s2s~1v2.0~1task~1sod~1{task_id}/get","metadata":{"seo":{"title":"Check an AI Photo Background Removal task status.","description":"Check an AI Photo Background Removal task status."}},"httpPath":"/s2s/v2.0/task/sod/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Photo Background Removal","version":"","description":"# Overview\nRemove background from photo with impeccable accuracy, ensuring the high quality of images.\n* Automatic Background Detection: : Uses AI to identify and separate the subject from the background.\n* High Precision Editing: : Provides clean and precise edges around the subject.\n* Supports various categories: People, Products, Animals, Cars, Graphics & more.\n* Easy to chain with other AI tasks: The output file ID can be chained into other AI tasks in a flash.\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2023-11-03/54285311-7c65-4658-9e27-11bf5c8dfe56.jpg)\n\n## Integration Guide\n* How to run AI Photo Background Removal\n1. **Resize your source image**
\n Resize your photo to fit the supported dimensions. See details in **[File Specs & Errors](#section/overview/File-Specs-and-Errors)**\n\n2. **Upload file using the File API**
\n Using the ***/s2s/v2.0/file*** API to upload a target user image.\n - Image Requirements\n - See details in **[File Specs & Errors](#section/overview/File-Specs-and-Errors)**.\n - ***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.
\n 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.\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\n3. **Run an AI task**
\n 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.\n\n4. **Polling to check the status of a task until it succeed or error**
\nThis ***task_id*** is used to monitor the task's status through polling GET 'task/sod' 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\n **Warning:** Please note that, **Polling** to check the status of a task based on it's ***polling_interval*** is mandotary. A task will be timed out if there is no polling request within the ***polling_interval***, even if the task is processed succefully(Your unit(s) will be consumed).\n\n > **Warning:** You will get a ***InvalidTaskId*** error once you check the status of a timed out task. So, once you run an AI task, you need to **polling** to check the status within the ***polling_interval*** until the status become either *success* or *error*.\n\n5. **Get the result of an AI task once success**
\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.\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* Demonstrative scenarios:\nCommon implementation cases:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Transparen_Background_aca3cdbd83.jpg)\n\n## Inputs & Outputs\n* Inputs\n * `Image`\n- **Type:** `image`\n- **Description:** An image with clear foreground.\n\nReal-world application (input): \n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_removal_bg_s4_poster_1_289b8eaf81.png)\n\n---\n\n* Outputs\n * `Foreground image`\n- **Type:** `image`\n- **Description:** A background removed image.\n\nReal-world application (output):\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_removal_bg_s4_poster_2_a6bc3c5f6a.png)\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|File Size|Accepted formats|\n| ---- | ---- | ---- | ---- |\n|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|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\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_download_video|Download source video error|\n|error_decode_video|Decode source video 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|error_multiple_people|Multiple people detected in the source image|\n|error_no_shoulder|Shoulders are not visible in the source image|\n|error_large_face_angle|The face angle in the uploaded image is too large|\n|error_hair_too_short|Input hair is too short|\n|error_unexpected_video_duration|Video durateion is not equal to the dstDuration|\n|error_bald_image|Input hairstyle is bald|\n|error_unsupport_ratio|The aspect ratio of input image is unsupported|\n|unknown_internal_error|Others|\n"}},{"type":"group","fsPath":"reference/ai_photo_colorize.yaml","link":"/reference/ai_photo_colorize","routeSlug":"/reference/ai_photo_colorize","label":"AI Photo Colorize","items":[{"type":"group","label":"Overview","link":"/reference/ai_photo_colorize/section/overview","routeSlug":"/reference/ai_photo_colorize/section/overview","items":[{"type":"link","label":"File Specs & Errors","link":"/reference/ai_photo_colorize/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_photo_colorize/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_photo_colorize/v1.0","routeSlug":"/reference/ai_photo_colorize/v1.0","items":[{"label":"Run an AI Photo Colorize task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_photo_colorize/v1.0/paths/~1s2s~1v2.0~1task~1colorize/post","routeSlug":"/reference/ai_photo_colorize/v1.0/paths/~1s2s~1v2.0~1task~1colorize/post","metadata":{"seo":{"title":"Run an AI Photo Colorize task.","description":"Please refer to the polling guide for checking task status."}},"httpPath":"/s2s/v2.0/task/colorize"},{"label":"Check a AI Photo Colorize task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_photo_colorize/v1.0/paths/~1s2s~1v2.0~1task~1colorize~1{task_id}/get","routeSlug":"/reference/ai_photo_colorize/v1.0/paths/~1s2s~1v2.0~1task~1colorize~1{task_id}/get","metadata":{"seo":{"title":"Check a AI Photo Colorize task status.","description":"Check a AI Photo Colorize task status."}},"httpPath":"/s2s/v2.0/task/colorize/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Photo Colorize","version":"","description":"# Overview\nUsing 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.\n\n![AI Photo Colorize](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_colorize_s4_poster_11c0bdfead.jpg \"AI Photo Colorize\")\n\n---\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n| AI Feature | Supported Dimensions | Supported File Size | Supported Formats |\n| ---- | ---- | ---- | ---- |\n| AI Photo Colorize | long side <= 4096 | < 10MB | jpg/jpeg/png |\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| exceed_max_filesize |\tInput file size exceeds the maximum limit |\n| invalid_parameter |\tInvalid parameter value |\n| error_download_image\t| Download source image error |\n| error_decode_image\t| Decode source image error |\n| error_nsfw_content_detected\t| NSFW content detected in source image |\n"}},{"type":"group","fsPath":"reference/ai_photo_lighting.yaml","link":"/reference/ai_photo_lighting","routeSlug":"/reference/ai_photo_lighting","label":"AI Photo Lighting","items":[{"type":"group","label":"Overview","link":"/reference/ai_photo_lighting/section/overview","routeSlug":"/reference/ai_photo_lighting/section/overview","items":[{"type":"link","label":"File Specs & Errors","link":"/reference/ai_photo_lighting/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_photo_lighting/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V2.0","link":"/reference/ai_photo_lighting/v2.0","routeSlug":"/reference/ai_photo_lighting/v2.0","items":[{"label":"Run an AI Photo Lighting task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_photo_lighting/v2.0/paths/~1s2s~1v2.0~1task~1lighting/post","routeSlug":"/reference/ai_photo_lighting/v2.0/paths/~1s2s~1v2.0~1task~1lighting/post","metadata":{"seo":{"title":"Run an AI Photo Lighting task.","description":"Please refer to the polling guide for checking task status."}},"httpPath":"/s2s/v2.0/task/lighting"},{"label":"Check an AI Photo Lighting task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_photo_lighting/v2.0/paths/~1s2s~1v2.0~1task~1lighting~1{task_id}/get","routeSlug":"/reference/ai_photo_lighting/v2.0/paths/~1s2s~1v2.0~1task~1lighting~1{task_id}/get","metadata":{"seo":{"title":"Check an AI Photo Lighting task status.","description":"Check an AI Photo Lighting task status."}},"httpPath":"/s2s/v2.0/task/lighting/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Photo Lighting","version":"","description":"# Overview\nBrighten your images with Our AI image brightening tool effortlessly. With the legendary AI technology, lighten up any image of your choice.\nBrighten your dark photos or images with our AI Photo Lighting tool, illuminating your memories in a flash.\n\nBefore\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_lighting_v3_poster_1_b7d976b686.jpg)\nAfter\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_lighting_v3_poster_2_79d3be33bc.jpg)\nBrighten low-light photos effortlessly using AI tool, bringing out stunning details and vibrant colors.\n\n\n\nBefore\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_lighting_v6_poster_1_2422530612.jpg)\nAfter\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_lighting_v6_poster_2_63f1ecc244.jpg)\nBrighten your product pictures with AI Lighting tool for a captivating and stunning presentation.\n\n---\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n| AI Feature | Supported Dimensions | Supported File Size | Supported Formats |\n| ---- | ---- | ---- | ---- |\n| AI Photo Lighting | long side <= 4096 | < 10MB | jpg/jpeg/png |\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| exceed_max_filesize |\tInput file size exceeds the maximum limit |\n| invalid_parameter |\tInvalid parameter value |\n| error_download_image\t| Download source image error |\n| error_decode_image\t| Decode source image error |\n| error_nsfw_content_detected\t| NSFW content detected in source image |\n"}},{"type":"group","fsPath":"reference/ai_color_correction.yaml","link":"/reference/ai_color_correction","routeSlug":"/reference/ai_color_correction","label":"AI Color Correction","items":[{"type":"group","label":"Overview","link":"/reference/ai_color_correction/section/overview","routeSlug":"/reference/ai_color_correction/section/overview","items":[{"type":"link","label":"File Specs & Errors","link":"/reference/ai_color_correction/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_color_correction/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_color_correction/v1.0","routeSlug":"/reference/ai_color_correction/v1.0","items":[{"label":"Run an AI Photo Color Correction task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_color_correction/v1.0/paths/~1s2s~1v2.0~1task~1colorize~1color-correct/post","routeSlug":"/reference/ai_color_correction/v1.0/paths/~1s2s~1v2.0~1task~1colorize~1color-correct/post","metadata":{"seo":{"title":"Run an AI Photo Color Correction task.","description":"Please refer to the polling guide for checking task status."}},"httpPath":"/s2s/v2.0/task/colorize/color-correct"},{"label":"Check an AI Photo Color Correction task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_color_correction/v1.0/paths/~1s2s~1v2.0~1task~1colorize~1color-correct~1{task_id}/get","routeSlug":"/reference/ai_color_correction/v1.0/paths/~1s2s~1v2.0~1task~1colorize~1color-correct~1{task_id}/get","metadata":{"seo":{"title":"Check an AI Photo Color Correction task status.","description":"Check an AI Photo Color Correction task status."}},"httpPath":"/s2s/v2.0/task/colorize/color-correct/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Color Correction","version":"","description":"# Overview\nPerfect 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.\n\nSample\nBefore:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/color_correction_topbanner_before_dt_100_45429e8625.jpg)\n\nAfter:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/color_correction_topbanner_after_dt_100_ef9f9c48ed.jpg)\n\n\n\nBefore:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/color_correction_s1_image_before_dt_fa73b5d41a.jpg)\n\nAfter\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/color_correction_s1_image_after_dt_a3e88a101b.jpg)\n\n\n---\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n| AI Feature | Supported Dimensions | Supported File Size | Supported Formats |\n| ---- | ---- | ---- | ---- |\n| AI Color Correction | long side <= 4096 | < 10MB | jpg/jpeg/png |\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| exceed_max_filesize |\tInput file size exceeds the maximum limit |\n| invalid_parameter |\tInvalid parameter value |\n| error_download_image\t| Download source image error |\n| error_decode_image\t| Decode source image error |\n| error_nsfw_content_detected\t| NSFW content detected in source image |\n"}},{"type":"group","fsPath":"reference/ai_photo_background_change.yaml","link":"/reference/ai_photo_background_change","routeSlug":"/reference/ai_photo_background_change","label":"AI Photo Background Change","items":[{"type":"group","label":"Overview","link":"/reference/ai_photo_background_change/section/overview","routeSlug":"/reference/ai_photo_background_change/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_photo_background_change/section/overview/integration-guide","routeSlug":"/reference/ai_photo_background_change/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_photo_background_change/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_photo_background_change/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V2.0","link":"/reference/ai_photo_background_change/v2.0","routeSlug":"/reference/ai_photo_background_change/v2.0","items":[{"label":"List predefined AI photo Background Change V2 templates.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_photo_background_change/v2.0/paths/~1s2s~1v2.0~1task~1template~1bg-replace/get","routeSlug":"/reference/ai_photo_background_change/v2.0/paths/~1s2s~1v2.0~1task~1template~1bg-replace/get","metadata":{"seo":{"title":"List predefined AI photo Background Change V2 templates.","description":"List predefined AI photo Background Change V2 templates."}},"httpPath":"/s2s/v2.0/task/template/bg-replace"},{"label":"Run an AI photo Background Change V2 task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_photo_background_change/v2.0/paths/~1s2s~1v2.0~1task~1bg-replace/post","routeSlug":"/reference/ai_photo_background_change/v2.0/paths/~1s2s~1v2.0~1task~1bg-replace/post","metadata":{"seo":{"title":"Run an AI photo Background Change V2 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/bg-replace"},{"label":"Check an AI photo Background Change V2 task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_photo_background_change/v2.0/paths/~1s2s~1v2.0~1task~1bg-replace~1{task_id}/get","routeSlug":"/reference/ai_photo_background_change/v2.0/paths/~1s2s~1v2.0~1task~1bg-replace~1{task_id}/get","metadata":{"seo":{"title":"Check an AI photo Background Change V2 task status.","description":"Check an AI photo Background Change V2 task status."}},"httpPath":"/s2s/v2.0/task/bg-replace/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Photo Background Change","version":"","description":"# Overview\nThe 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.\n\nThis API enables developers to replace the background using custom prompts or predefined templates.\n\n**Sample Usage**\n\nBefore:\n![](https://yce.makeupar.com/assets/images/sod/banner/change/yce-topbanner-dt-before.jpg)\n\nAfter:\n![](https://yce.makeupar.com/assets/images/sod/banner/change/yce-topbanner-dt-after.jpg)\n\n\nBefore:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_change_bg_s5_poster_before_0753db3e02.jpg)\n\nAfter:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_change_bg_s5_poster_after_7fb288fde2.jpg)\n\n---\n\n## Integration Guide\n\n**1. Upload Image**\n\nRequest upload URLs and file IDs via:\n\n```\nPOST /s2s/v2.0/file\n```\n\nUpload the image using the returned URL.\nAlternatively, provide a publicly accessible image URL hosted on your own storage.\n\n\n**2. Prepare a background description prompt or select a background template.**\n\n```\nGET /s2s/v2.0/task/template/bg-replace\n```\n\nRetrieve 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.\n\n\n**3. Execute Analysis Task**\n\n```\nPOST /s2s/v2.0/task/bg-replace\n```\n\nSubmit the task using file IDs or image URLs as input, along with the desired background prompt.\nThe response returns a task_id for tracking and retrieving the result.\n\n\n**4. Retrieve Task Result**\n\n```\nGET /s2s/v2.0/task/bg-replace/{task_id}\n```\n\nUse the task ID to track status and obtain results.\n\n[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.\n\nUsage is only charged when the task completes successfully.\n\n---\n\n## File Specs & Errors\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n| AI Photo Background Change | The length of the longer side shall not exceed 4096 pixels. | < 10MB | jpg/jpeg/png |\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| exceed_max_filesize |\tThe input file size exceeds the maximum allowed limit. |\n| size_mismatch_on_input_image_and_mask | The input image size must match the input mask image dimensions. |\n| invalid_parameter | Invalid parameter value. The request parameter is missing, in an invalid format, or contains an unsupported value.|\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"}},{"type":"group","fsPath":"reference/ai_photo_background_blur.yaml","link":"/reference/ai_photo_background_blur","routeSlug":"/reference/ai_photo_background_blur","label":"AI Photo Background Blur","items":[{"type":"group","label":"Overview","link":"/reference/ai_photo_background_blur/section/overview","routeSlug":"/reference/ai_photo_background_blur/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_photo_background_blur/section/overview/integration-guide","routeSlug":"/reference/ai_photo_background_blur/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_photo_background_blur/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_photo_background_blur/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V2.0","link":"/reference/ai_photo_background_blur/v2.0","routeSlug":"/reference/ai_photo_background_blur/v2.0","items":[{"label":"Run an AI Photo Background Blur task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_photo_background_blur/v2.0/paths/~1s2s~1v2.0~1task~1bg-blur/post","routeSlug":"/reference/ai_photo_background_blur/v2.0/paths/~1s2s~1v2.0~1task~1bg-blur/post","metadata":{"seo":{"title":"Run an AI Photo Background Blur 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/bg-blur"},{"label":"Check an AI Photo Background Blur task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_photo_background_blur/v2.0/paths/~1s2s~1v2.0~1task~1bg-blur~1{task_id}/get","routeSlug":"/reference/ai_photo_background_blur/v2.0/paths/~1s2s~1v2.0~1task~1bg-blur~1{task_id}/get","metadata":{"seo":{"title":"Check an AI Photo Background Blur task status.","description":"Check an AI Photo Background Blur task status."}},"httpPath":"/s2s/v2.0/task/bg-blur/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Photo Background Blur","version":"","description":"# Overview\nThe 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.\n\nCreate 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.\n\n\n**Sample Usage Scenarios:**\n\n* Portrait Enhancement\nApply a natural bokeh effect to make subjects stand out and improve the visual quality of profile or portrait photos.\n\n Before:\n ![](https://yce.makeupar.com/assets/images/sod/banner/blur/yce-topbanner-dt-before.jpg)\n\n After:\n ![](https://yce.makeupar.com/assets/images/sod/banner/blur/yce-topbanner-dt-after.jpg)\n\n* Professional Headshots\nCreate studio-like background blur effects from standard photos for business profiles and corporate directories.\n\n Before:\n ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_blur_bg_s3_poster_1_50a314e3f9.jpg)\n\n After:\n ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_blur_bg_s3_poster_2_afb0548cb7.jpg)\n\n---\n\n## Integration Guide\n\n**Input Requirements & Processing Criteria:**\n\n- Upload an image containing a clear, prominent foreground subject.\n- The image's longest side must not exceed **4,096 px**.\n- The source file size must be under **10 MB**.\n- At least one clearly visible foreground subject is required.\n- Only single-subject analysis is supported. If multiple people are present, the API automatically selects the subject with the largest visible area.\n\n\n**Workflow:**\n\n1. Call the File API.\n2. Retrieve the signed upload URL from the response.\n3. Upload the actual image to the returned URL.\n4. Create an AI task.\n5. Setup a Webhook or Poll the task status until completion.\n6. Download the generated result image when processing is successful.\n\n---\n\n**Step 1 — Upload File Metadata Using the File API**\n\nUse `POST /s2s/v2.0/file` to create a file record and receive upload details for the source image.\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/jpg\",\n \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\n \"file_size\": 547541\n }\n ]\n }'\n```\n\n**File API Sample Response:**\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"files\": [\n {\n \"content_type\": \"image/jpg\",\n \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\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/jpg\"\n }\n }\n ]\n }\n ]\n }\n}\n```\n\n---\n\n**Step 2 — Retrieve File API Response Details**\n\nThe response contains:\n\n| Field | Description |\n| --- | --- |\n| `file_id` | Identifier used to create the AI task. |\n| `requests.url` | Signed URL for uploading the actual image file. |\n| `requests.method` | Upload method, usually `PUT`. |\n| `requests.headers` | Required headers for the upload request. |\n\n---\n\n**Step 3 — Upload Image to Provided URL**\n\nUse the `requests.url` from the File API response to upload the source image.\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n --header 'Content-Type: image/jpg' \\\n --header 'Content-Length: 547541' \\\n --data-binary @'./full_body_photo_01_3dbd1b6683.jpg'\n```\n\n---\n\n**Step 4 — Create an AI Task**\n\nUse `POST /s2s/v2.0/task/bg-blur` to create an AI task.\n\n| Parameter | Description | Example |\n| --- | --- | --- |\n| `src_file_id` | File ID returned from the File API upload flow. Required when using uploaded-file workflow. | `\"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\"` |\n| `src_file_url` | Direct URL of the source image. Use this alternative to `src_file_id`. | `\"https://example.com/selfie.jpg\"` |\n| `intensity` | Blue intensity. 0 means no blur, and 100 means the maximum blur. | 50 |\n\n**Example Request:**\n\n```javascript\nconst resp = await fetch(\n 'https://yce-api-01.makeupar.com/s2s/v2.0/task/bg-blur',\n {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n Authorization: 'Bearer '\n },\n body: JSON.stringify({\n src_file_url: 'https://example.com/selfie.jpg',\n intensity: 50\n })\n }\n);\n\nconst data = await resp.json();\nconsole.log(data);\n```\n\n**AI Task API 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 5 — Setup a Webhook or Poll for Task Result**\n\nSee the [webhook integration guide](/develop/webhook.md) for setup and verification details.\n\nFor polling, use the returned `task_id` to check task status.\n\n```bash\ncurl --request GET \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/bg-blur/ \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json'\n```\n\n---\n\n**Step 6 — Retrieve Result Image**\n\nWhen processing is successful, the response includes a download URL in `data.results.url`.\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"error\": null,\n \"results\": {\n \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n },\n \"task_status\": \"success\"\n }\n}\n```\n\n**Invalid API Key Response:**\n\nIf the access token is invalid, the API returns a `401` response.\n\n```json\n{\n \"status\": 401,\n \"error\": \"Unauthorized\",\n \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\n## File Specs & Errors\n\n**File Specifications:**\n\n| Specification | Requirement |\n| --- | --- |\n| Image type | The image must contain one clear and prominent foreground subject or person. |\n| Maximum long-side resolution | Long side must not exceed **4096 px**. |\n| File size limit | Must be less than **10 MB**. |\n| Supported formats | `jpg`, `png`. |\n\n**Error Codes:**\n\n| Error Code | Description |\n| --- | --- |\n| `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. |\n| `error_nsfw_content_detected` | Potential NSFW content was detected in the source image or generated result image. |\n| `invalid_parameter` | Invalid parameters were provided for source keys, destination keys, actions, mode values, intensity levels, or task configuration. |\n| `error_download_image` | The source image could not be downloaded successfully. |\n| `error_decode_image` | The source image could not be decoded successfully. |\n\n**Environment & Dependencies:**\n\n| Tool / Language | Recommended Runtime Versions |\n| --- | --- |\n| cURL | Bash ≥ 3.2; curl ≥ 7.58 with modern TLS/HTTP support; jq ≥ 1.6 for robust JSON parsing. |\n| Node.js | Node ≥ 18 for global `fetch` support. |\n| JavaScript Browser Support | Chrome / Edge ≥ 80, Firefox ≥ 74, Safari ≥ 13.1. |\n| PHP | PHP ≥ 7.4 with modern TLS compatibility; ext-curl recommended or `allow_url_fopen=On` with OpenSSL and JSON support. |\n| Python | Python ≥ 3.10 for f-strings; requests ≥ 2.20.0. |\n| Java | Java 11+ for HttpClient; Jackson Databind ≥ 2.12.0. |\n"}},{"type":"group","fsPath":"reference/ai_replace.yaml","link":"/reference/ai_replace","routeSlug":"/reference/ai_replace","label":"AI Replace","items":[{"type":"group","label":"Overview","link":"/reference/ai_replace/section/overview","routeSlug":"/reference/ai_replace/section/overview","items":[{"type":"link","label":"File Specs & Errors","link":"/reference/ai_replace/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_replace/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_replace/v1.0","routeSlug":"/reference/ai_replace/v1.0","items":[{"label":"Run an AI Replace task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_replace/v1.0/paths/~1s2s~1v2.0~1task~1obj-replace/post","routeSlug":"/reference/ai_replace/v1.0/paths/~1s2s~1v2.0~1task~1obj-replace/post","metadata":{"seo":{"title":"Run an AI Replace task.","description":"Please refer to the polling guide for checking task status. This API requires a source image, mask file, and prompt describing what should replace the masked area."}},"httpPath":"/s2s/v2.0/task/obj-replace"},{"label":"Check an AI Replace task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_replace/v1.0/paths/~1s2s~1v2.0~1task~1obj-replace~1{task_id}/get","routeSlug":"/reference/ai_replace/v1.0/paths/~1s2s~1v2.0~1task~1obj-replace~1{task_id}/get","metadata":{"seo":{"title":"Check an AI Replace task status.","description":"Check an AI Replace task status."}},"httpPath":"/s2s/v2.0/task/obj-replace/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Replace","version":"","description":"# Overview\nReplace 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.​\n\nSample:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_replace_S3_feature_img_02_a73a26bcc3.jpg)\n\n\nFor 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.\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_replace_S3_feature_img_03_42c9cd98d0.jpg)\n\n\nCreate stunning room mockups with AI Replace by filling empty spaces with aesthetically pleasing furniture and objects, transforming the perception of any space.\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_replace_S3_feature_img_04_4d2d82f76e.jpg)\n\n---\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n| AI Feature | Supported Dimensions | Supported File Size | Supported Formats |\n| ---- | ---- | ---- | ---- |\n| AI Replace | long side <= 2048 | < 10MB | jpg/jpeg/png |\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| exceed_max_filesize |\tInput file size exceeds the maximum limit |\n| invalid_parameter |\tInvalid parameter value |\n| error_download_image\t| Download source image error |\n| error_decode_image\t| Decode source image error |\n| error_nsfw_content_detected\t| NSFW content detected in source image |\n"}},{"type":"group","fsPath":"reference/ai_avatar_generator.yaml","link":"/reference/ai_avatar_generator","routeSlug":"/reference/ai_avatar_generator","label":"AI Avatar Generator","items":[{"type":"group","label":"Overview","link":"/reference/ai_avatar_generator/section/overview","routeSlug":"/reference/ai_avatar_generator/section/overview","items":[{"type":"link","label":"File Specs & Errors","link":"/reference/ai_avatar_generator/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_avatar_generator/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V3.0","link":"/reference/ai_avatar_generator/v3.0","routeSlug":"/reference/ai_avatar_generator/v3.0","items":[{"label":"List predefined templates.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_avatar_generator/v3.0/paths/~1s2s~1v2.0~1task~1template~1ai-avatar/get","routeSlug":"/reference/ai_avatar_generator/v3.0/paths/~1s2s~1v2.0~1task~1template~1ai-avatar/get","metadata":{"seo":{"title":"List predefined templates.","description":"List predefined templates."}},"httpPath":"/s2s/v2.0/task/template/ai-avatar"},{"label":"Run an AI Avatar task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_avatar_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-avatar/post","routeSlug":"/reference/ai_avatar_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-avatar/post","metadata":{"seo":{"title":"Run an AI Avatar 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/ai-avatar"},{"label":"Check the status of the AI Avatar task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_avatar_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-avatar~1{task_id}/get","routeSlug":"/reference/ai_avatar_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-avatar~1{task_id}/get","metadata":{"seo":{"title":"Check the status of the AI Avatar task.","description":"Check the status of the AI Avatar task."}},"httpPath":"/s2s/v2.0/task/ai-avatar/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Avatar Generator","version":"","description":"# Overview\nFor 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.\n\nFor more avatar styles, please refer to https://yce.makeupar.com/avatar\n\nUse cases:\n![AI Avatar Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Christmas_Avatar_b861c35edf.jpg \"AI Avatar Generator\")\n\n![AI Avatar Generator](https://plugins-media.makeupar.com/smb/blog/post/2023-04-06/fc2c3b2e-2b7f-48c9-96c1-cdb780f9dc1d.jpg \"AI Avatar Generator\")\n\n\nSuggestions for How to Shoot:\n![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\")\n\n---\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n| AI Feature | Supported Dimensions | Supported File Size | Supported Formats |\n| ---- | ---- | ---- | ---- |\n| AI Avatar Generator | Input: long side <= 4096, Output: long side <= 1024 | < 10MB | jpg/jpeg/png |\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| exceed_max_filesize |\tInput file size exceeds the maximum limit |\n| invalid_parameter |\tInvalid parameter value |\n| error_download_image\t| Download source image error |\n| error_decode_image\t| Decode source image error |\n| error_nsfw_content_detected\t| NSFW content detected in source image |\n"}},{"type":"group","fsPath":"reference/ai_headshot_generator.yaml","link":"/reference/ai_headshot_generator","routeSlug":"/reference/ai_headshot_generator","label":"AI Headshot Generator","items":[{"type":"group","label":"Overview","link":"/reference/ai_headshot_generator/section/overview","routeSlug":"/reference/ai_headshot_generator/section/overview","items":[{"type":"link","label":"File Specs & Errors","link":"/reference/ai_headshot_generator/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_headshot_generator/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_headshot_generator/v1.0","routeSlug":"/reference/ai_headshot_generator/v1.0","items":[{"label":"List predefined templates.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_headshot_generator/v1.0/paths/~1s2s~1v2.0~1task~1template~1headshot/get","routeSlug":"/reference/ai_headshot_generator/v1.0/paths/~1s2s~1v2.0~1task~1template~1headshot/get","metadata":{"seo":{"title":"List predefined templates.","description":"List predefined templates."}},"httpPath":"/s2s/v2.0/task/template/headshot"},{"label":"Run an AI Headshot Generator task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_headshot_generator/v1.0/paths/~1s2s~1v2.0~1task~1headshot/post","routeSlug":"/reference/ai_headshot_generator/v1.0/paths/~1s2s~1v2.0~1task~1headshot/post","metadata":{"seo":{"title":"Run an AI Headshot Generator 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/headshot"},{"label":"Check the status of the AI Headshot Generator task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_headshot_generator/v1.0/paths/~1s2s~1v2.0~1task~1headshot~1{task_id}/get","routeSlug":"/reference/ai_headshot_generator/v1.0/paths/~1s2s~1v2.0~1task~1headshot~1{task_id}/get","metadata":{"seo":{"title":"Check the status of the AI Headshot Generator task.","description":"Check the status of the AI Headshot Generator task."}},"httpPath":"/s2s/v2.0/task/headshot/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Headshot Generator","version":"","description":"# Overview\nTransform your photos into stunning professional deadshots with our AI Headshot Generator. Elevate your headshots quickly and effectively using our powerful AI tools designed to deliver professional-quality results.\n* 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.\n* Professional Results: Leveraging AI to ensure your headshots look natural and flattering, making a strong impression on potential employers and clients.\n* Convenience: Generate multiple AI headshots anytime, anywhere, without the need for a photographer. Perfect for busy professionals.\n\nFor more AI Headshot styles, please refer to https://yce.makeupar.com/ai-headshot-generator.\n\nUse cases:\n![AI Headshot Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_headshot_s2_img_03_4b55742358.jpg \"AI Headshot Generator\")\n\n![AI Headshot Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_headshot_s1_img_1_d03183d7e0.jpg \"AI Headshot Generator\")\n\n\nSuggestions for How to Shoot:\n![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\")\n\n\n---\n\n## File Specs & Errors\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n| 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 |\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| exceed_max_filesize |\tInput file size exceeds the maximum limit |\n| invalid_parameter |\tInvalid parameter value |\n| error_download_image\t| Download source image error |\n| error_decode_image\t| Decode source image error |\n| error_nsfw_content_detected\t| NSFW content detected in source image |\n"}},{"type":"group","fsPath":"reference/ai_studio_generator.yaml","link":"/reference/ai_studio_generator","routeSlug":"/reference/ai_studio_generator","label":"AI Studio Generator","items":[{"type":"group","label":"Overview","link":"/reference/ai_studio_generator/section/overview","routeSlug":"/reference/ai_studio_generator/section/overview","items":[{"type":"link","label":"File Specs & Errors","link":"/reference/ai_studio_generator/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_studio_generator/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V3.0","link":"/reference/ai_studio_generator/v3.0","routeSlug":"/reference/ai_studio_generator/v3.0","items":[{"label":"List predefined templates.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_studio_generator/v3.0/paths/~1s2s~1v2.0~1task~1template~1ai-studio/get","routeSlug":"/reference/ai_studio_generator/v3.0/paths/~1s2s~1v2.0~1task~1template~1ai-studio/get","metadata":{"seo":{"title":"List predefined templates.","description":"List predefined templates."}},"httpPath":"/s2s/v2.0/task/template/ai-studio"},{"label":"Run an AI Studio task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_studio_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-studio/post","routeSlug":"/reference/ai_studio_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-studio/post","metadata":{"seo":{"title":"Run an AI Studio task.","description":"Please refer to the polling guide for checking task status. Requires a source image, template ID, and output count configuration."}},"httpPath":"/s2s/v2.0/task/ai-studio"},{"label":"Check the status of the AI Studio task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_studio_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-studio~1{task_id}/get","routeSlug":"/reference/ai_studio_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-studio~1{task_id}/get","metadata":{"seo":{"title":"Check the status of the AI Studio task.","description":"Check the status of the AI Studio task."}},"httpPath":"/s2s/v2.0/task/ai-studio/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Studio Generator","version":"","description":"# Overview\nEmbrace the excellence of studio kike AI Portrait Generator. Transform your selfie into a studio-quality portrait in a flash​.\n* Studio-Free Convenience: No need for a photographer or studio visits—create studio-quality artistic photos anytime, anywhere​\n* Quick Photo Transformation: Fast processing for instant high-quality artistic photo results, ideal for quick updates\n* High-Quality Artistic Output: Delivers professional-standard artistic photos with clear details, perfect lighting, just like you've taken the photos in a studio \n\nUse cases:\n![AI Studio Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_studio_S1_img_19b627b6af.jpg \"AI Studio Generator\")\n\n![AI Studio Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_studio_S2_img_01_2e318817e9.jpg \"AI Studio Generator\")\n\n\nSuggestions for How to Shoot:\n![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\")\n\n\n---\n\n## File Specs & Errors\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|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|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n|error_below_min_image_size\t|Input image resolution is too small|\n|error_exceed_max_image_size\t|Input image resolution is too large|\n"}},{"type":"group","fsPath":"reference/ai_image_generator.yaml","link":"/reference/ai_image_generator","routeSlug":"/reference/ai_image_generator","label":"AI Image Generator","items":[{"type":"group","label":"Overview","link":"/reference/ai_image_generator/section/overview","routeSlug":"/reference/ai_image_generator/section/overview","items":[{"type":"link","label":"File Specs & Errors","link":"/reference/ai_image_generator/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_image_generator/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V2.0","link":"/reference/ai_image_generator/v2.0","routeSlug":"/reference/ai_image_generator/v2.0","items":[{"label":"Run an AI Image Generator task V2 for text to image.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-image~1youcam/post","routeSlug":"/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-image~1youcam/post","metadata":{"seo":{"title":"Run an AI Image Generator task V2 for text to image.","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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/text-to-image/youcam"},{"label":"Check the status of a AI Image Generator task V2 for text to image.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-image~1youcam~1{task_id}/get","routeSlug":"/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-image~1youcam~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Image Generator task V2 for text to image.","description":"Check the status of a AI Image Generator task V2 for text to image."}},"httpPath":"/s2s/v2.0/task/text-to-image/youcam/{task_id}"},{"label":"Run an AI Image Generator task V2 for image to image.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-image~1youcam/post","routeSlug":"/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-image~1youcam/post","metadata":{"seo":{"title":"Run an AI Image Generator task V2 for image to image.","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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/image-to-image/youcam"},{"label":"Check the status of a AI Image Generator task V2 for image to image.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-image~1youcam~1{task_id}/get","routeSlug":"/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-image~1youcam~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Image Generator task V2 for image to image.","description":"Check the status of a AI Image Generator task V2 for image to image."}},"httpPath":"/s2s/v2.0/task/image-to-image/youcam/{task_id}"}]},{"type":"group","label":"V1.0","link":"/reference/ai_image_generator/v1.0","routeSlug":"/reference/ai_image_generator/v1.0","items":[{"label":"List predefined templates.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_image_generator/v1.0/paths/~1s2s~1v2.0~1task~1template~1text-to-image/get","routeSlug":"/reference/ai_image_generator/v1.0/paths/~1s2s~1v2.0~1task~1template~1text-to-image/get","metadata":{"seo":{"title":"List predefined templates.","description":"List predefined templates."}},"httpPath":"/s2s/v2.0/task/template/text-to-image"},{"label":"Run an AI Image Generator task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_image_generator/v1.0/paths/~1s2s~1v2.0~1task~1text-to-image/post","routeSlug":"/reference/ai_image_generator/v1.0/paths/~1s2s~1v2.0~1task~1text-to-image/post","metadata":{"seo":{"title":"Run an AI Image Generator 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/text-to-image"},{"label":"Check a AI Image Generator task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_image_generator/v1.0/paths/~1s2s~1v2.0~1task~1text-to-image~1{task_id}/get","routeSlug":"/reference/ai_image_generator/v1.0/paths/~1s2s~1v2.0~1task~1text-to-image~1{task_id}/get","metadata":{"seo":{"title":"Check a AI Image Generator task status.","description":"Check a AI Image Generator task status."}},"httpPath":"/s2s/v2.0/task/text-to-image/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Image Generator","version":"","description":"# Overview\nDiscover 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.\n\nWant more inspirations? Please refer to https://yce.makeupar.com/ai-art-generator.\n\nUse cases:\n![AI Image Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_v3_video_02f161f909.jpg \"AI Image Generator\")\n\n![AI Image Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_v4_poster_092d2fbb9f.jpg \"AI Image Generator\")\n\nSample output:\n![AI Image Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_topbanner_dt_2_e325681588.jpg \"AI Image Generator\")\n\n![AI Image Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_topbanner_dt_5_8b4fa13c6a.jpg \"AI Image Generator\")\n\n## File Specs & Errors\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n| V1.0 Text to Image | Output: 1024 pixels on the long side. | Prompt cannot exceed 500 characters | N/A |\n| 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 |\n| 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. |\n\n* Error Codes\n\n| Error Code | Description |\n| ---------- | ----------- |\n| exceed_max_filesize | The uploaded file size exceeds the maximum allowed limit. |\n| invalid_parameter | One or more parameters are missing or invalid |\n| error_download_image | Failed to download the source image. |\n| error_decode_image | Failed to decode or parse the source image. |\n| error_nsfw_content_detected | Not Safe For Work content was detected in the source image. |\n| error_unsupport_ratio | The aspect ratio of the input image is not supported. |\n| unknown_internal_error | An unspecified internal error occurred. |\n"}},{"type":"separator","label":"Video"},{"type":"group","fsPath":"reference/ai_video_generator.yaml","link":"/reference/ai_video_generator","routeSlug":"/reference/ai_video_generator","label":"AI Video Generator","items":[{"type":"group","label":"Overview","link":"/reference/ai_video_generator/section/overview","routeSlug":"/reference/ai_video_generator/section/overview","items":[{"type":"link","label":"File Specs & Errors","link":"/reference/ai_video_generator/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_video_generator/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V2.0","link":"/reference/ai_video_generator/v2.0","routeSlug":"/reference/ai_video_generator/v2.0","items":[{"label":"Run an AI Image to Video Generator V2 task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-video~1youcam/post","routeSlug":"/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-video~1youcam/post","metadata":{"seo":{"title":"Run an AI Image to Video Generator V2 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/image-to-video/youcam"},{"label":"Check the status of a AI Image to Video Generator V2 task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-video~1youcam~1{task_id}/get","routeSlug":"/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-video~1youcam~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Image to Video Generator V2 task.","description":"Check the status of a AI Image to Video Generator V2 task."}},"httpPath":"/s2s/v2.0/task/image-to-video/youcam/{task_id}"},{"label":"Run an AI Text To Video task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-video~1youcam/post","routeSlug":"/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-video~1youcam/post","metadata":{"seo":{"title":"Run an AI Text To Video 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/text-to-video/youcam"},{"label":"Check the status of a AI Text To Video task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-video~1youcam~1{task_id}/get","routeSlug":"/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-video~1youcam~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Text To Video task.","description":"Check the status of a AI Text To Video task."}},"httpPath":"/s2s/v2.0/task/text-to-video/youcam/{task_id}"}]},{"type":"group","label":"V1.0","link":"/reference/ai_video_generator/v1.0","routeSlug":"/reference/ai_video_generator/v1.0","items":[{"label":"List predefined templates.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_video_generator/v1.0/paths/~1s2s~1v2.0~1task~1template~1image-to-video/get","routeSlug":"/reference/ai_video_generator/v1.0/paths/~1s2s~1v2.0~1task~1template~1image-to-video/get","metadata":{"seo":{"title":"List predefined templates.","description":"List predefined templates."}},"httpPath":"/s2s/v2.0/task/template/image-to-video"},{"label":"Run an Image to Video task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_video_generator/v1.0/paths/~1s2s~1v2.0~1task~1image-to-video/post","routeSlug":"/reference/ai_video_generator/v1.0/paths/~1s2s~1v2.0~1task~1image-to-video/post","metadata":{"seo":{"title":"Run an Image to Video task.","description":"This endpoint initiates the image to video conversion process. You must provide a template ID and source file (via URL or File ID). The task will be processed asynchronously, and you can check its status using the task_id returned in this response."}},"httpPath":"/s2s/v2.0/task/image-to-video"},{"label":"Check the status of the Image to Video task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_video_generator/v1.0/paths/~1s2s~1v2.0~1task~1image-to-video~1{task_id}/get","routeSlug":"/reference/ai_video_generator/v1.0/paths/~1s2s~1v2.0~1task~1image-to-video~1{task_id}/get","metadata":{"seo":{"title":"Check the status of the Image to Video task.","description":"Check the status of the Image to Video task."}},"httpPath":"/s2s/v2.0/task/image-to-video/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Video Generator","version":"","description":"# Overview\nYouCam 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.\n\nTo 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.\n\nUse cases:\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_Animate%20Photo_047_d9e1cff579.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Dance_Video_61cf4c58d1.png)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/241216_AI_Kiss_image05_c3b7f1ac5b.jpg)\n\n\n## File Specs & Errors\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n| 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|\n| 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|\n| 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|\n\n* Error Codes\n\n| Error Category | Scenario / Description | Suggested Action |\n| -------------- | ---------------------- | ---------------- |\n| Invalid request parameters | Request parameters are invalid or missing | Verify that all request parameters are correct |\n| | Invalid parameter values (e.g., incorrect key or illegal value) | Check the error message field in the response and update the request parameters |\n| | Invalid request method | Review the API documentation and use the correct HTTP method |\n| | Requested resource does not exist (e.g., model not found) | Refer to the response error message field and correct the request parameters|\n| Trigger strategy | Platform policy has been triggered | Check whether any platform policies were violated |\n| | Content security policy triggered | Review and modify the input content, then resend the request |\n| | Request rate too high (rate limit exceeded)| Reduce request frequency, retry later, or contact customer service to increase limits |\n| | Concurrency or QPS exceeds quota | Reduce request frequency, or retry later |\n| Internal error | Internal server error | Retry later or contact customer service |\n| | Server temporarily unavailable | Retry later or contact customer service |\n| | Internal timeout due to request backlog| Retry later or contact customer service |\n"}},{"type":"group","fsPath":"reference/ai_video_enhancer.yaml","link":"/reference/ai_video_enhancer","routeSlug":"/reference/ai_video_enhancer","label":"AI Video Enhancer","items":[{"type":"group","label":"Overview","link":"/reference/ai_video_enhancer/section/overview","routeSlug":"/reference/ai_video_enhancer/section/overview","items":[{"type":"link","label":"File Specs & Errors","link":"/reference/ai_video_enhancer/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_video_enhancer/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_video_enhancer/v1.0","routeSlug":"/reference/ai_video_enhancer/v1.0","items":[{"label":"Run an AI Video Enhance task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_video_enhancer/v1.0/paths/~1s2s~1v2.0~1task~1video-sr/post","routeSlug":"/reference/ai_video_enhancer/v1.0/paths/~1s2s~1v2.0~1task~1video-sr/post","metadata":{"seo":{"title":"Run an AI Video Enhance 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/video-sr"},{"label":"Check a AI Video Enhance task status.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_video_enhancer/v1.0/paths/~1s2s~1v2.0~1task~1video-sr~1{task_id}/get","routeSlug":"/reference/ai_video_enhancer/v1.0/paths/~1s2s~1v2.0~1task~1video-sr~1{task_id}/get","metadata":{"seo":{"title":"Check a AI Video Enhance task status.","description":"Check a AI Video Enhance task status."}},"httpPath":"/s2s/v2.0/task/video-sr/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Video Enhancer","version":"","description":"# Overview\n\nThe 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.\n\nThis 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.\n\n\n**Core Capabilities**\n\n1. Blur correction\n The API detects motion blur and soft details, then reconstructs sharper frames using AI enhancement models.\n\n2. Sharpness optimization\n Edges and textures are enhanced to create a more defined and visually crisp video.\n\n3. Brightness and exposure adjustment\n Lighting inconsistencies are automatically corrected to improve visibility and color balance.\n\n4. AI upscaling\n Resolution is intelligently increased from lower quality formats such as 480p to HD quality while preserving details.\n\n5. Quality boosting\n Noise reduction and artifact removal are applied to produce clean and professional results.\n\nSample usage cases:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_video_enhancer_S2_feature_video_03_S_0_10169a6902.jpg)\n\n---\n\n## File Specs & Errors\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n| 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 |\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| error_download_video | Download source video error |\n| error_decode_video | Decode source video error |\n| error_unsupported_video | Unsupported video format |\n| exceed_max_filesize | Input file size exceeds the maximum limit|\n| error_nsfw_content_detected | NSFW content detected in the source file |\n| error_decode_mask | Decode mask image error |\n| invalid_parameter | Invalid parameter value|\n"}},{"type":"group","fsPath":"reference/ai_video_face_swap.yaml","link":"/reference/ai_video_face_swap","routeSlug":"/reference/ai_video_face_swap","label":"AI Video Face Swap","items":[{"type":"group","label":"Overview","link":"/reference/ai_video_face_swap/section/overview","routeSlug":"/reference/ai_video_face_swap/section/overview","items":[{"type":"link","label":"File Specs & Errors","link":"/reference/ai_video_face_swap/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_video_face_swap/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_video_face_swap/v1.0","routeSlug":"/reference/ai_video_face_swap/v1.0","items":[{"label":"Run an AI Face Swap (video) task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_video_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap-vid/post","routeSlug":"/reference/ai_video_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap-vid/post","metadata":{"seo":{"title":"Run an AI Face Swap (video) 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/face-swap-vid"},{"label":"Check the status of the AI Face Swap (video) task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_video_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap-vid~1{task_id}/get","routeSlug":"/reference/ai_video_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap-vid~1{task_id}/get","metadata":{"seo":{"title":"Check the status of the AI Face Swap (video) task.","description":"Check the status of the AI Face Swap (video) task."}},"httpPath":"/s2s/v2.0/task/face-swap-vid/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Video Face Swap","version":"","description":"# Overview\nVideo 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.\nWith 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.\n\n> **Note:** This API supports video with single face only. For customizable solution, please [contact us](mailto:YouCamOnlineEditor_API@perfectcorp.com).\n\nSample usage cases:\n![](https://plugins-media.makeupar.com/smb/blog/post/2024-08-23/b1f96100-37d6-4c28-b467-d397e9c3a25d.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_video_face_swap_S3_video_03_28785ebe0c.jpg)\n\n![](https://plugins-media.makeupar.com/smb/story/2024-09-12/3582f617-e88e-4219-9e72-43d4c26791cd.png)\n\n---\n\n## File Specs & Errors\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n| 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 |\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| error_download_video | Download source video error |\n| error_decode_video | Decode source video error |\n| error_unsupported_video | Unsupported video format |\n| exceed_max_filesize | Input file size exceeds the maximum limit|\n| error_nsfw_content_detected | NSFW content detected in the source file |\n| error_decode_mask | Decode mask image error |\n| invalid_parameter | Invalid parameter value|\n"}},{"type":"group","fsPath":"reference/ai_video_style_transfer.yaml","link":"/reference/ai_video_style_transfer","routeSlug":"/reference/ai_video_style_transfer","label":"AI Video Style Transfer","items":[{"type":"group","label":"Overview","link":"/reference/ai_video_style_transfer/section/overview","routeSlug":"/reference/ai_video_style_transfer/section/overview","items":[{"type":"link","label":"File Specs & Errors","link":"/reference/ai_video_style_transfer/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_video_style_transfer/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V1.0","link":"/reference/ai_video_style_transfer/v1.0","routeSlug":"/reference/ai_video_style_transfer/v1.0","items":[{"label":"List predefined templates.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_video_style_transfer/v1.0/paths/~1s2s~1v2.0~1task~1template~1video-trans/get","routeSlug":"/reference/ai_video_style_transfer/v1.0/paths/~1s2s~1v2.0~1task~1template~1video-trans/get","metadata":{"seo":{"title":"List predefined templates.","description":"List predefined templates."}},"httpPath":"/s2s/v2.0/task/template/video-trans"},{"label":"Run an AI Style Transfer (video) task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_video_style_transfer/v1.0/paths/~1s2s~1v2.0~1task~1video-trans/post","routeSlug":"/reference/ai_video_style_transfer/v1.0/paths/~1s2s~1v2.0~1task~1video-trans/post","metadata":{"seo":{"title":"Run an AI Style Transfer (video) 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/video-trans"},{"label":"Check the status of the AI Style Transfer (video) task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_video_style_transfer/v1.0/paths/~1s2s~1v2.0~1task~1video-trans~1{task_id}/get","routeSlug":"/reference/ai_video_style_transfer/v1.0/paths/~1s2s~1v2.0~1task~1video-trans~1{task_id}/get","metadata":{"seo":{"title":"Check the status of the AI Style Transfer (video) task.","description":"Check the status of the AI Style Transfer (video) task."}},"httpPath":"/s2s/v2.0/task/video-trans/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Video Style Transfer","version":"","description":"# Overview\nCreate 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.\n\nSample usage cases:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_video_style_transfer_S1_video_1_0_6d571a8bbb.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_video_style_transfe_S2_feature_03_0_6dd652a6f2.jpg)\n\n---\n\n## File Specs & Errors\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n| AI Video Face Swap | The input video must not exceed 30 seconds, 4K resolution, or 30 FPS, and the output is limited to 1280 long-side resolution, 16 FPS, and up to 30 seconds. | Length limit: 30s | container: mov, mp4
video: MPEG-4, MPEG-4 AVC,
audio: aac, amr, mp3 |\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| error_download_video | Download source video error |\n| error_decode_video | Decode source video error |\n| error_unsupported_video | Unsupported video format |\n| exceed_max_filesize | Input file size exceeds the maximum limit|\n| error_nsfw_content_detected | NSFW content detected in the source file |\n| error_decode_mask | Decode mask image error |\n| invalid_parameter | Invalid parameter value|\n"}},{"type":"group","fsPath":"reference/ai_video_object_removal.yaml","link":"/reference/ai_video_object_removal","routeSlug":"/reference/ai_video_object_removal","label":"AI Video Object Removal","items":[{"type":"group","label":"Overview","link":"/reference/ai_video_object_removal/section/overview","routeSlug":"/reference/ai_video_object_removal/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_video_object_removal/section/overview/integration-guide","routeSlug":"/reference/ai_video_object_removal/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_video_object_removal/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_video_object_removal/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V2.0","link":"/reference/ai_video_object_removal/v2.0","routeSlug":"/reference/ai_video_object_removal/v2.0","items":[{"label":"Create a new file.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_video_object_removal/v2.0/paths/~1s2s~1v2.0~1file~1obj-rem-vid/post","routeSlug":"/reference/ai_video_object_removal/v2.0/paths/~1s2s~1v2.0~1file~1obj-rem-vid/post","metadata":{"seo":{"title":"Create a new file.","description":"To upload a new file, you'll first need to use the File API. It will give you a URL – use that URL to upload your file. Once the upload is finished, you can use the file_id from the same response to start using our AI features."}},"httpPath":"/s2s/v2.0/file/obj-rem-vid"},{"label":"Run an AI Video Object Removal task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_video_object_removal/v2.0/paths/~1s2s~1v2.0~1task~1obj-rem-vid/post","routeSlug":"/reference/ai_video_object_removal/v2.0/paths/~1s2s~1v2.0~1task~1obj-rem-vid/post","metadata":{"seo":{"title":"Run an AI Video Object Removal 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/obj-rem-vid"},{"label":"Check the status of a AI Video Object Removal task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_video_object_removal/v2.0/paths/~1s2s~1v2.0~1task~1obj-rem-vid~1{task_id}/get","routeSlug":"/reference/ai_video_object_removal/v2.0/paths/~1s2s~1v2.0~1task~1obj-rem-vid~1{task_id}/get","metadata":{"seo":{"title":"Check the status of a AI Video Object Removal task.","description":"Check the status of a AI Video Object Removal task."}},"httpPath":"/s2s/v2.0/task/obj-rem-vid/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Video Object Removal","version":"","description":"# Overview\n\n**AI Video Object Removal**\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-02-04/webp_537ec670-48c0-49fc-b96b-8073de21a64b.webp)\n\nThe 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.\n\n\n---\n\n## Integration Guide\n\n**1. Prepare a Source Video and a Mask Image**\nThe 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.\n\n\n**2. Upload File**\nRequest upload URLs and file IDs via:\n\n```\nPOST /s2s/v2.0/file\n```\n\nInput video:\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_video_object_removal_input_edd43a2470.png)\n\n\nReference input mask:\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_video_object_removal_mask_4a1c9fb658.png)\n\n\n**3. Execute AI Task**\n\n```\nPOST /s2s/v2.0/task/obj-rem-vid\n```\n\nSubmit the task using file IDs or image URLs as input. The response returns a task_id for tracking and retrieving the result.\n\n\n**4. Retrieve Task Result**\n\n```\nGET /s2s/v2.0/task/obj-rem-vid/{task_id}\n```\n\nUse the task ID to track status and obtain results.\n\n[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.\n\nUsage is only charged when the task completes successfully.\n\n\nOutput video sample:\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_video_object_removal_output_eb7670cd9e.png)\n\n\n---\n\n## File Specs & Errors\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n| 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 |\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| error_download_video | Download source video error |\n| error_decode_video | Decode source video error |\n| error_unsupported_video | Unsupported video format |\n| exceed_max_filesize | Input file size exceeds the maximum limit|\n| error_nsfw_content_detected | NSFW content detected in the source file |\n| error_decode_mask | Decode mask image error |\n| invalid_parameter | Invalid parameter value|\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"}},{"type":"group","fsPath":"reference/ai_video_background_replace.yaml","link":"/reference/ai_video_background_replace","routeSlug":"/reference/ai_video_background_replace","label":"AI Video Background Replace","items":[{"type":"group","label":"Overview","link":"/reference/ai_video_background_replace/section/overview","routeSlug":"/reference/ai_video_background_replace/section/overview","items":[{"type":"link","label":"Integration Guide","link":"/reference/ai_video_background_replace/section/overview/integration-guide","routeSlug":"/reference/ai_video_background_replace/section/overview/integration-guide"},{"type":"link","label":"File Specs & Errors","link":"/reference/ai_video_background_replace/section/overview/file-specs-and-errors","routeSlug":"/reference/ai_video_background_replace/section/overview/file-specs-and-errors"}]},{"type":"group","label":"V2.0","link":"/reference/ai_video_background_replace/v2.0","routeSlug":"/reference/ai_video_background_replace/v2.0","items":[{"label":"Run an AI Video Background Replace task.","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_video_background_replace/v2.0/paths/~1s2s~1v2.0~1task~1bg-replace-vid/post","routeSlug":"/reference/ai_video_background_replace/v2.0/paths/~1s2s~1v2.0~1task~1bg-replace-vid/post","metadata":{"seo":{"title":"Run an AI Video Background Replace 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 for setup and verification details."}},"httpPath":"/s2s/v2.0/task/bg-replace-vid"},{"label":"Check the status of an AI Video Background Replace task.","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/reference/ai_video_background_replace/v2.0/paths/~1s2s~1v2.0~1task~1bg-replace-vid~1{task_id}/get","routeSlug":"/reference/ai_video_background_replace/v2.0/paths/~1s2s~1v2.0~1task~1bg-replace-vid~1{task_id}/get","metadata":{"seo":{"title":"Check the status of an AI Video Background Replace task.","description":"Check the status of an AI Video Background Replace task."}},"httpPath":"/s2s/v2.0/task/bg-replace-vid/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Video Background Replace","version":"","description":"# Overview\n\n**AI Video Background Replace**\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Green_Screen_ddb7892393.png)\n\nThe 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.\nThere 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.\n\n\n---\n\n## Integration Guide\n\n**1. Prepare a Source Video and a Background Image**\nThe 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.\n\nThe 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.\n\n\n**2. Upload File**\nRequest upload URLs and file IDs via:\n\n```\nPOST /s2s/v2.0/file\n```\n\n\n**3. Execute AI Task**\n\n```\nPOST /s2s/v2.0/task/bg-replace-vid\n```\n\nSubmit the task using file IDs or image URLs as input. The response returns a task_id for tracking and retrieving the result.\n\n\n**4. Retrieve Task Result**\n\n```\nGET /s2s/v2.0/task/bg-replace-vid/{task_id}\n```\n\nUse the task ID to track status and obtain results.\n\n[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.\n\nUsage is only charged when the task completes successfully.\n\n\n\n---\n\n## File Specs & Errors\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n| 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 |\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| error_download_video | Download source video error |\n| error_decode_video | Decode source video error |\n| error_unsupported_video | Unsupported video format |\n| exceed_max_filesize | Input file size exceeds the maximum limit|\n| error_nsfw_content_detected | NSFW content detected in the source file |\n| error_decode_mask | Decode mask image error |\n| invalid_parameter | Invalid parameter value|\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"}}]}