{
"openapi": "3.0.0",
"info": {
"title": "AI Skin simulation",
"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\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\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\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\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\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\n---\n\n## Unit Consumption\n\n* Skin Simulation\n\n| AI Feature | Unit Consumed |\n|---|---|\n| 1~4 concerns analysis | 4 |\n| 5~10 concerns analysis | 6 |\n\n---\n",
"version": "",
"termsOfService": "https://www.makeupar.com/perfectbeauty/youcam/terms-of-service-api",
"contact": {
"email": "YouCamOnlineEditor_API@perfectcorp.com"
},
"license": {
"name": "Privacy policy",
"url": "https://www.makeupar.com/perfectbeauty/youcam/privacy-policy-api"
}
},
"servers": [
{
"url": "https://yce-api-01.makeupar.com"
}
],
"tags": [
{
"name": "V1.0",
"description": "Simulate skin texture changes (wrinkles, radiance, oiliness, etc.) on uploaded images using AI processing."
}
],
"paths": {
"/s2s/v2.0/task/skin-simulation": {
"post": {
"summary": "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.\n",
"tags": [
"V1.0"
],
"security": [
{
"BearerAuthenticationV2": []
}
],
"requestBody": {
"required": true,
"description": "Simulation intensity cannot be all zero.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunSkinSimulationTaskV2"
}
}
}
},
"responses": {
"200": {
"description": "Successful execution of the task",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BasicRunTaskResponseV2"
}
}
}
},
"400": {
"description": "Failed execution of task",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/RunError"
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/InvalidApiKey"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
}
}
},
"/s2s/v2.0/task/skin-simulation/{task_id}": {
"get": {
"summary": "Check the status of a AI Skin Simulation task.",
"tags": [
"V1.0"
],
"security": [
{
"BearerAuthenticationV2": []
}
],
"parameters": [
{
"name": "task_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
},
"description": "ID of task to check"
}
],
"responses": {
"200": {
"description": "Successful check of the task status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskStatusResponseV2"
}
}
}
},
"400": {
"$ref": "#/components/responses/InvalidTaskId"
},
"401": {
"$ref": "#/components/responses/InvalidApiKey"
},
"500": {
"$ref": "#/components/responses/TaskTimeout"
}
}
}
}
},
"components": {
"securitySchemes": {
"BearerAuthenticationV2": {
"type": "http",
"scheme": "bearer",
"description": "Use the standard 'Bearer authentication'. Put your 'API Key' in header: `Authorization:Bearer YOUR_API_KEY`. Notice that there is ' ' a space between 'Bearer' and the 'YOUR_API_KEY'."
}
},
"schemas": {
"RunSkinSimulationTaskV2": {
"title": "Run Skin Simulation Task V2",
"allOf": [
{
"$ref": "#/components/schemas/BasicRunTaskV2"
},
{
"type": "object",
"properties": {
"wrinkle": {
"type": "number",
"description": "Reduce the appearance of wrinkles and fine lines while restoring smoother, firmer, visibly rejuvenated and youthful-looking skin.
0.0 for original skin, 1.0 for most wrinkle removed skin.",
"example": 1,
"minimum": 0,
"maximum": 1
},
"radiance": {
"type": "number",
"description": "Enhance skin radiance and luminosity, unveiling a refreshed, revitalized glow with a brighter, more radiant complexion.
0.0 for original skin luminosity, 1.0 for maximum radiant/glowing skin.",
"example": 1,
"minimum": 0,
"maximum": 1
},
"oiliness": {
"type": "number",
"description": "Control excess shine for a fresh, clean, shine-free complexion that feels balanced and comfortably matte.
0.0 for original skin, 1.0 for maximum oil/shine added to skin.",
"example": 1,
"minimum": 0,
"maximum": 1
},
"acne": {
"type": "number",
"description": "Purify and clear blemish-prone skin by reducing breakouts and blackheads, revealing a smoother, refined, and visibly flawless radiant complexion.
0.0 for original skin, 1.0 for most acne/pimples removed.",
"example": 1,
"minimum": 0,
"maximum": 1
},
"eye_bags": {
"type": "number",
"description": "Visibly reduce under-eye puffiness, restoring a smoother, firmer, and more refreshed, well-rested appearance.
0.0 for original under-eye appearance, 1.0 for most eye bags removed.",
"example": 1,
"minimum": 0,
"maximum": 1
},
"dark_circle": {
"type": "number",
"description": "Visibly diminish dark circles, revealing a brighter, well-rested eye area with a refreshed and radiant appearance.
0.0 for original under-eye color, 1.0 for most dark circles removed.",
"example": 1,
"minimum": 0,
"maximum": 1
},
"spots": {
"type": "number",
"description": "Target and visibly fade age spots while refining skin clarity, revealing a smoother, and more even-toned, youthful glow.
0.0 for original skin, 1.0 for most age spots/blemishes removed.",
"example": 1,
"minimum": 0,
"maximum": 1
},
"pores": {
"type": "number",
"description": "Refine and visibly minimize enlarged pores, revealing smoother, more polished, and flawlessly refined skin.
0.0 for original pore visibility, 1.0 for most refined/invisible pores.",
"example": 1,
"minimum": 0,
"maximum": 1
},
"texture": {
"type": "number",
"description": "Refine skin texture to couture-level smoothness, visibly perfecting irregularities and unveiling a silky, impeccably polished, and luminous complexion.
0.0 for original skin texture, 1.0 for smoothest skin texture.",
"example": 1,
"minimum": 0,
"maximum": 1
},
"redness": {
"type": "number",
"description": "Calm and rebalance sensitive skin by visibly reducing redness, soothing rosacea-prone areas, and restoring a clearer, more even-toned and comfortingly refined complexion.
0.0 for original skin tone, 1.0 for most redness/irritation removed.",
"example": 1,
"minimum": 0,
"maximum": 1
}
},
"not": {
"properties": {
"wrinkle": {
"type": "number",
"enum": [
0
]
},
"radiance": {
"type": "number",
"enum": [
0
]
},
"oiliness": {
"type": "number",
"enum": [
0
]
},
"acne": {
"type": "number",
"enum": [
0
]
},
"eye_bags": {
"type": "number",
"enum": [
0
]
},
"dark_circle": {
"type": "number",
"enum": [
0
]
},
"spots": {
"type": "number",
"enum": [
0
]
},
"pores": {
"type": "number",
"enum": [
0
]
},
"texture": {
"type": "number",
"enum": [
0
]
},
"redness": {
"type": "number",
"enum": [
0
]
}
}
}
}
]
},
"BasicRunTaskV2SrcFileUrl": {
"type": "object",
"required": [
"src_file_url"
],
"properties": {
"src_file_url": {
"type": "string",
"description": "Url of the file to run task. The url should be publicly accessible.",
"example": "https://example.com/selfie.jpg"
}
}
},
"BasicRunTaskV2SrcFileId": {
"type": "object",
"required": [
"src_file_id"
],
"properties": {
"src_file_id": {
"type": "string",
"description": "ID of file to run task. File ID from upload file API.",
"example": "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE="
}
}
},
"BasicRunTaskV2": {
"title": "BasicRunTaskV2",
"anyOf": [
{
"title": "Run task with src file url",
"allOf": [
{
"$ref": "#/components/schemas/BasicRunTaskV2SrcFileUrl"
}
]
},
{
"title": "Run task with src file ID",
"allOf": [
{
"$ref": "#/components/schemas/BasicRunTaskV2SrcFileId"
}
]
}
]
},
"BasicRunTaskResponseV2": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Response status",
"example": 200
},
"data": {
"type": "object",
"properties": {
"task_id": {
"type": "string",
"description": "ID of this task. Task result is valid to query by this ID for 24 hours.",
"example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
}
}
}
}
},
"RunError": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Response status",
"example": 400
},
"error": {
"type": "string",
"description": "Error message",
"example": "The operation could not be completed"
},
"error_code": {
"type": "string",
"enum": [
"InvalidParameters",
"CreditInsufficiency",
"InvalidStyleGroup",
"InvalidStyle",
"BadRequest"
],
"description": "Error code:\n * InvalidParameters - Invalid request parameters\n * CreditInsufficiency - Insufficient unit to run\n * BadRequest - Unexpected request parameter\n * InvalidStyleGroup - Invalid style group id\n * InvalidStyle - Invalid style id\n"
}
}
},
"EngineErrorCode": {
"type": "string",
"nullable": true,
"enum": [
"error_exceed_max_image_size",
"exceed_max_filesize",
"invalid_parameter",
"error_download_image",
"error_download_mask",
"error_decode_image",
"error_decode_mask",
"error_nsfw_content_detected",
"error_no_face",
"error_pose",
"error_face_parsing",
"error_inference",
"exceed_nsfw_retry_limits",
"error_upload",
"unknown_internal_error"
],
"description": "Errors:\n- \\`error_exceed_max_image_size\\` - Input image size exceeds the maximum limit\n- \\`exceed_max_filesize\\` - Input file size exceeds the maximum limit\n- \\`invalid_parameter\\` - Invalid parameter value\n- \\`error_download_image\\` - Download source image error\n- \\`error_download_mask\\` - Download mask image error\n- \\`error_decode_image\\` - Decode source image error\n- \\`error_decode_mask\\` - Decode mask image error\n- \\`error_nsfw_content_detected\\` - NSFW content detected in source image\n- \\`error_no_face\\` - No face detected on source image\n- \\`error_pose\\` - Failed to detect pose on source image\n- \\`error_face_parsing\\` - Failed to do face segmentation on source image\n- \\`error_inference\\` - Inference pipeline error\n- \\`exceed_nsfw_retry_limits\\` - Exceed the retry limits to avoid generated NSFW image\n- \\`error_upload\\` - Upload result image error\n- \\`unknown_internal_error\\` - Others\n"
},
"TaskStatusResponseBodySingleUrlResultsV2": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "URL to download this result. Valid for 2 hours",
"example": "https://example.com/sample-result-url"
}
}
},
"TaskStatusResponseV2": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Response status",
"example": 200
},
"data": {
"type": "object",
"properties": {
"task_status": {
"type": "string",
"enum": [
"running",
"success",
"error"
],
"description": "Status of this task"
},
"error": {
"$ref": "#/components/schemas/EngineErrorCode"
},
"error_message": {
"type": "string",
"description": "Detailed description of error"
},
"results": null
}
}
},
"$ref": "#/components/schemas/TaskStatusResponseBodySingleUrlResultsV2"
}
},
"responses": {
"InvalidApiKey": {
"description": "Invalid or missing API key",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 401,
"description": "Response status"
},
"error": {
"type": "string",
"example": "Invalid API key"
}
}
}
}
}
},
"TooManyRequests": {
"description": "Too many requests",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 429,
"description": "Response status"
},
"error": {
"type": "string",
"example": "Too many requests"
}
}
}
}
}
},
"InvalidTaskId": {
"description": "Invalid task ID",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 400,
"description": "Response status"
},
"error": {
"type": "string",
"example": "Invalid task ID"
}
}
}
}
}
},
"TaskTimeout": {
"description": "Task execution timeout",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 500,
"description": "Response status"
},
"error": {
"type": "string",
"example": "Task execution timed out"
}
}
}
}
}
}
}
}
}