openapi: 3.0.0
info:
  title: AI Makeup Virtual Try-On
  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 <TOKEN>`\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 <API Key>\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.<br></br>\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\": \"<string>\"\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/<task_id>`\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\": \"<string>\", // 'success', 'error', or a processing state (e.g., 'queued',\
    \ 'processing')\n    \"results\": [ // present only when task_status is 'success'\n      {\n     \
    \   \"download_url\": \"<string>\" // URL to download the processed image\n      }\n    ],\n    \"\
    failure_reason\": \"<string>\" // 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<Effect> — 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<BlushPalette>, 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:**\n\
    https://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</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>\
    \   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n\
    | JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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| AI Feature | Unit Consumed |\n|---|---|\n| AI Makeup Virtual\
    \ Try-On V1.0 | 1 |\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
paths:
  /s2s/v2.0/task/makeup-vto:
    post:
      summary: 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.

        '
      tags:
      - V1.0
      security:
      - BearerAuthenticationV2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/BasicRunTaskV2'
              - type: object
                required:
                - effects
                properties:
                  version:
                    type: string
                    description: 'Version of the makeup effect specification. Defaults to `"1.0"` unless
                      otherwise specified.

                      '
                    default: '1.0'
                    example: '1.0'
                  effects:
                    type: array
                    description: 'Array of makeup effects to apply. Each effect object MUST specify a
                      `category` and match the schema for that makeup type.

                      '
                    items:
                      anyOf:
                      - $ref: '#/components/schemas/SkinSmoothEffect'
                      - $ref: '#/components/schemas/BlushEffect'
                      - $ref: '#/components/schemas/BronzerEffect'
                      - $ref: '#/components/schemas/ConcealerEffect'
                      - $ref: '#/components/schemas/ContourEffect'
                      - $ref: '#/components/schemas/EyebrowsEffect'
                      - $ref: '#/components/schemas/EyelinerEffect'
                      - $ref: '#/components/schemas/EyeshadowEffect'
                      - $ref: '#/components/schemas/EyelashesEffect'
                      - $ref: '#/components/schemas/FoundationEffect'
                      - $ref: '#/components/schemas/HighlighterEffect'
                      - $ref: '#/components/schemas/LipColorEffect'
                      - $ref: '#/components/schemas/LipLinerEffect'
      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/responses/RunError'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /s2s/v2.0/task/makeup-vto/{task_id}:
    get:
      summary: Check the status of a AI Makeup Virtual Try On 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:
    EngineErrorCode:
      type: string
      nullable: true
      enum:
      - exceed_max_filesize
      - invalid_parameter
      - error_download_image
      - error_decode_image
      - error_nsfw_content_detected
      - error_inference
      - unknown_internal_error
      description: 'Errors:


        - `exceed_max_filesize` - Input file size exceeds the maximum limit


        - `invalid_parameter` - Invalid parameter value


        - `error_download_image` - Download source image error


        - `error_decode_image` - Decode source image error


        - `unknown_internal_error` - Others

        '
    FileV1.1:
      title: File V1.1
      description: This object represents a file.
      type: object
      required:
      - files
      properties:
        files:
          type: array
          items:
            type: object
            required:
            - content_type
            - file_name
            - file_size
            properties:
              content_type:
                type: string
                example: image/jpg
                description: Content MIME type for this file. Currently available values are listed in
                  the enum.
              file_name:
                type: string
                example: my-selfie.jpg
                description: Name of this file
              file_size:
                type: integer
                example: 50000
                description: Content length for this file in bytes. Should not be larger than 10MB.
    BasicFileResponse:
      type: object
      properties:
        files:
          type: array
          items:
            type: object
            properties:
              content_type:
                type: string
                example: image/jpg
                description: Content MIME type for this file.
              file_name:
                type: string
                example: my-selfie.jpg
                description: Name of this file
              file_id:
                type: string
                example: U8aqJbsXGT537jtGnEDFHqxdDXqh8+oTF/cSkLimzuvVwMP+Jb1XbjPsf7ZgUgLY
                description: ID of this file. Other run task API will need this `file_id`.
              requests:
                type: array
                description: Using upload `url`, `headers`, `method` below to upload file. After completion,
                  the `file_id` is used to proceed with calling run task API.
                items:
                  type: object
                  properties:
                    headers:
                      type: object
                      example:
                        Content-Type: image/jpg
                        Content-Length: 50000
                      description: Headers to include when uploading the file
                    url:
                      type: string
                      example: https://example.com/presigned-upload-url
                      description: URL to upload this file
                    method:
                      type: string
                      example: PUT
                      description: HTTP method to upload this file
    FileResponseV2:
      type: object
      properties:
        status:
          type: integer
          example: 200
          description: Response status
        data:
          $ref: '#/components/schemas/BasicFileResponse'
    BasicRunTaskV2SrcFileUrl:
      title: Run task with src file url
      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:
      title: Run task with src file ID
      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:
      - $ref: '#/components/schemas/BasicRunTaskV2SrcFileUrl'
      - $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
    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:
              $ref: '#/components/schemas/TaskStatusResponseBodySingleUrlResultsV2'
    SkinSmoothEffect:
      type: object
      description: 'Controls the AI-generated smoothing applied to the skin. If no skin_smooth effect
        is provided, the system will automatically apply a smoothing strength of 50 for realistic blending.

        '
      required:
      - category
      properties:
        category:
          type: string
          enum:
          - skin_smooth
          description: 'Identifies this effect as a skin smoothing effect. Must always be "skin_smooth".

            '
        skinSmoothStrength:
          type: integer
          minimum: 0
          maximum: 100
          default: 50
          description: 'Strength of smoothing applied to overall skin texture. Higher values result in
            softer, more airbrushed skin appearance.

            '
        skinSmoothColorIntensity:
          type: integer
          minimum: 0
          maximum: 100
          default: 50
          description: 'Intensity of color blending applied during smoothing. Helps unify skin tones and
            reduce color inconsistency.

            '
      example:
        category: skin_smooth
        skinSmoothStrength: 50
        skinSmoothColorIntensity: 50
    BlushEffect:
      type: object
      description: 'Applies blush to the cheeks using predefined patterns and customizable color palettes.
        Pattern names must correspond to labels from the official blush.json pattern catalog.

        '
      required:
      - category
      - pattern
      - palettes
      properties:
        category:
          type: string
          enum:
          - blush
          description: 'Identifies this effect as a blush effect. Must always be "blush".

            '
        pattern:
          type: object
          description: 'Defines how the blush is placed on the face. Each pattern corresponds to a face
            shape and layout from blush.json.

            '
          required:
          - name
          properties:
            name:
              type: string
              description: 'Name of the blush pattern. Must be equal to a `label` from the blush.json
                pattern catalog.

                '
              example: 1color1
        palettes:
          type: array
          minItems: 1
          description: 'List of color palette entries. The number of palettes required depends on the
            `colorNum` field defined in the selected blush pattern.

            '
          items:
            type: object
            required:
            - color
            - texture
            - colorIntensity
            properties:
              color:
                type: string
                description: 'Primary blush color in hex format (#RRGGBB). Used as the dominant pigment
                  for the blush application.

                  '
                pattern: ^#?[0-9A-Fa-f]{6}$
              texture:
                type: string
                enum:
                - matte
                - satin
                - shimmer
                description: "Texture of the blush:\n  - matte: pure pigment, no shine\n  - satin: soft\
                  \ glow, requires glowStrength\n  - shimmer: sparkly or luminous, requires shimmer parameters\n"
              glowStrength:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Glow intensity for satin blush textures. Required when texture = "satin"
                  or "shimmer".

                  '
              shimmerColor:
                type: string
                description: 'Color of shimmer particles. Required when texture = "shimmer".

                  '
              shimmerDensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Density of shimmer particles in the blush application. Required when texture
                  = "shimmer".

                  '
              colorIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Strength of the blush color relative to the base pigment.

                  '
      example:
        category: blush
        pattern:
          name: 1color1
        palettes:
        - color: '#ff7777'
          texture: matte
          colorIntensity: 60
    BronzerEffect:
      type: object
      description: 'Applies bronzer to warm up skin tone and add sun-kissed contours. Pattern names must
        match bronzer.json entries.

        '
      required:
      - category
      - pattern
      - palettes
      properties:
        category:
          type: string
          enum:
          - bronzer
          description: 'Identifies this effect as a bronzer effect. Must always be "bronzer".

            '
        pattern:
          type: object
          required:
          - name
          description: 'Defines the bronzer application layout. Pattern name must match a `label` in bronzer.json.

            '
          properties:
            name:
              type: string
              example: Bronzer1
              description: 'Name of the bronzer pattern from the bronzer.json catalog.

                '
        palettes:
          type: array
          description: 'The bronzer palette contains pigment color and intensity controls.

            '
          items:
            type: object
            required:
            - color
            - colorIntensity
            properties:
              color:
                type: string
                description: 'Bronzer color in hex format (#RRGGBB).

                  '
              colorIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Intensity of bronzer pigmentation.

                  '
      example:
        category: bronzer
        pattern:
          name: Bronzer1
        palettes:
        - color: '#c08050'
          colorIntensity: 50
    ConcealerEffect:
      type: object
      description: 'Adds concealer for neutralizing blemishes, evening skin tone, and brightening under-eye
        regions. Concealer does not use a pattern — only pigment and intensity controls. All palette fields
        are required to ensure consistent behavior across face zones.

        '
      required:
      - category
      - palettes
      properties:
        category:
          type: string
          enum:
          - concealer
          description: 'Identifies this effect as a concealer effect. Must always be "concealer".

            '
        palettes:
          type: array
          minItems: 1
          description: 'One or more concealer palettes defining color and intensity properties. The same
            palette is applied to relevant facial areas, such as under-eye, forehead, and chin correction
            zones.

            '
          items:
            type: object
            required:
            - color
            - colorIntensity
            - colorUnderEyeIntensity
            - coverageLevel
            properties:
              color:
                type: string
                description: 'Concealer shade in hex RGB format (#RRGGBB). Should typically match or slightly
                  brighten the skin tone.

                  '
              colorIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'General concealer pigmentation strength applied across the face.

                  '
              colorUnderEyeIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Specific pigmentation control for the under-eye region. Helps brighten dark
                  circles without over-applying to other zones.

                  '
              coverageLevel:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Determines opacity of concealer coverage. Higher values hide more discoloration
                  or blemishes.

                  '
      example:
        category: concealer
        palettes:
        - color: '#e6c7a8'
          colorIntensity: 50
          colorUnderEyeIntensity: 50
          coverageLevel: 60
    ContourEffect:
      type: object
      description: 'Defines contouring for facial sculpting using patterns tailored to specific face shapes.
        Contour patterns determine highlight/shadow placement, while palettes control the contour shade.

        '
      required:
      - category
      - pattern
      - palettes
      properties:
        category:
          type: string
          enum:
          - contour
          description: 'Identifies this effect as a contour effect. Must always be "contour".

            '
        pattern:
          type: object
          required:
          - name
          description: 'Defines where contour shadowing is applied on the face. Must use a pattern name
            defined in contour.json (e.g., HeartFace2, OvalFace6).

            '
          properties:
            name:
              type: string
              description: 'Name of the contour pattern. Must be equal to a `label` from contour.json.

                '
              example: OvalFace6
        palettes:
          type: array
          minItems: 1
          description: 'Defines the pigment used for contouring. Usually a cool-tone or neutral shade
            darker than foundation.

            '
          items:
            type: object
            required:
            - color
            - colorIntensity
            properties:
              color:
                type: string
                description: 'Contour pigment color in #RRGGBB hex format.

                  '
              colorIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Strength of contour pigmentation. Higher values result in deeper shadows.

                  '
      example:
        category: contour
        pattern:
          name: OvalFace6
        palettes:
        - color: '#8a5b3e'
          colorIntensity: 55
    EyebrowsEffect:
      type: object
      description: 'Shapes and colors the eyebrows using customizable geometry and color palettes. When
        `pattern.type = shape`, the pattern defines the brow geometry (arch, curvature, thickness). When
        `pattern.type = color`, only pigment changes are applied.

        '
      required:
      - category
      - pattern
      - palettes
      properties:
        category:
          type: string
          enum:
          - eyebrows
          description: 'Identifies this effect as an eyebrow styling effect. Must always be "eyebrows".

            '
        pattern:
          type: object
          description: 'This setting defines the eyebrow pattern mode, which can either adjust the shape
            or apply color only. Pattern names must match the labels in eyebrows.json when required.

            '
          required:
          - type
          oneOf:
          - title: ShapePattern
            description: Shape-based eyebrow styling (geometry + optional color).
            required:
            - name
            properties:
              type:
                type: string
                enum:
                - shape
                description: Use customized eyebrow pattern shape
              name:
                type: string
                description: 'Name of the eyebrow shape pattern. Must match a `label` from eyebrows.json.

                  '
                example: SoftArch1
              curvature:
                type: integer
                minimum: -100
                maximum: 100
                description: 'Adjusts how curved the brow is. Negative = flatter / straighter, positive
                  = more curved.

                  '
              thickness:
                type: integer
                minimum: -100
                maximum: 100
                description: 'Controls eyebrow thickness adjustment relative to the detected brow. Positive
                  = thicker, negative = thinner.

                  '
              definition:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Sharpness and clarity of the brows. Higher values increase brow edge definition
                  for a cleaner look.

                  '
          - title: ColorPattern
            description: Color-only eyebrow styling (no geometry change).
            properties:
              type:
                type: string
                enum:
                - color
                description: Use user's original eyebrow shape
        palettes:
          type: array
          minItems: 1
          description: 'Eyebrow color palettes. Each palette controls pigment and optional shimmer effects
            (for shimmer textures only).

            '
          items:
            type: object
            required:
            - color
            - colorIntensity
            - texture
            properties:
              color:
                type: string
                description: 'Eyebrow pigment color in #RRGGBB format.

                  '
              colorIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Pigmentation strength used when applying eyebrow color.

                  '
              texture:
                type: string
                enum:
                - matte
                - shimmer
                description: 'Brow pigment texture style. Shimmer adds reflective highlights to brow hairs.

                  '
              shimmerColor:
                type: string
                description: 'Shimmer color applied when texture = shimmer.

                  '
              shimmerIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Strength of shimmer glow. Required only if texture = shimmer.

                  '
              shimmerSize:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Size of shimmer particles. Required for shimmer textures.

                  '
              shimmerDensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Density of shimmer particles in the brow. Required for shimmer textures.

                  '
      example:
        category: eyebrows
        pattern:
          type: shape
          name: SoftArch1
          curvature: 10
          thickness: 5
          definition: 50
        palettes:
        - color: '#3b2f2f'
          colorIntensity: 70
          texture: matte
    EyelinerEffect:
      type: object
      description: 'Applies eyeliner using customizable patterns and pigment settings. Patterns define
        the eyeliner layout (e.g., Arabic shapes, winged styles), while palettes specify color, texture,
        shimmer/metallic effects, and intensity.

        '
      required:
      - category
      - pattern
      - palettes
      properties:
        category:
          type: string
          enum:
          - eye_liner
          description: 'Identifies this effect as an eyeliner effect. Must always be "eye_liner".

            '
        pattern:
          type: object
          required:
          - name
          description: 'Defines the eyeliner shape and placement. Pattern names must match labels from
            eyeliner.json.

            '
          properties:
            name:
              type: string
              description: 'Name of the eyeliner pattern. Must be equal to a label from eyeliner.json.

                '
              example: Arabic3
        palettes:
          type: array
          minItems: 1
          description: 'Eyeliner color palette entries. Each palette controls pigment color, shimmer/metallic
            effects, and overall intensity. More palettes are used when the selected eyeliner pattern
            requires multiple colors.

            '
          items:
            type: object
            required:
            - color
            - texture
            - colorIntensity
            properties:
              color:
                type: string
                description: 'Eyeliner pigment color in #RRGGBB format.

                  '
              texture:
                type: string
                enum:
                - matte
                - shimmer
                - metallic
                description: 'Eyeliner texture finish specifies the look of the liner, whether it''s matte
                  for a flat opaque effect, shimmer for a sparkling reflective finish (with shimmer fields),
                  or metallic for a glossy metallic sheen (requiring shimmer fields and metallic intensity).

                  '
              shimmerColor:
                type: string
                description: 'Color used for shimmer or metallic reflective particles. Required if texture
                  is shimmer or metallic.

                  '
              shimmerIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Strength of reflective sparkle. Required when texture is shimmer or metallic.

                  '
              metallicIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Metallic reflectivity level. Required when texture = metallic.

                  '
              colorIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Pigmentation strength for the eyeliner color.

                  '
      example:
        category: eye_liner
        pattern:
          name: Arabic3
        palettes:
        - color: '#000000'
          texture: matte
          colorIntensity: 80
    EyeshadowEffect:
      type: object
      description: 'Applies eyeshadow with customizable multi-color palettes and textures. Eyeshadow patterns
        define layout (e.g., 1 to 5 colors), while palettes specify pigmentation and shimmer/metallic
        properties.

        '
      required:
      - category
      - pattern
      - palettes
      properties:
        category:
          type: string
          enum:
          - eye_shadow
          description: 'Identifies this effect as an eyeshadow effect. Must always be "eye_shadow".

            '
        pattern:
          type: object
          required:
          - name
          description: 'Defines the eyeshadow placement pattern. Must match a `label` in eyeshadow.json
            (e.g., 1color1, 2colors1, etc.).

            '
          properties:
            name:
              type: string
              description: 'Pattern name from eyeshadow.json determining number of colors and shadow placement
                zones.

                '
              example: 2colors1
        palettes:
          type: array
          minItems: 1
          description: 'One or more pigment palette entries. The number of palettes required depends on
            the pattern''s `colorNum`. Each palette defines a specific layer/color in the eyeshadow pattern.

            '
          items:
            type: object
            required:
            - color
            - texture
            - colorIntensity
            properties:
              color:
                type: string
                description: 'Eyeshadow pigment color in HEX format (#RRGGBB).

                  '
              texture:
                type: string
                enum:
                - matte
                - shimmer
                - metallic
                description: 'Eyeshadow surface appearance determines whether the finish is matte for
                  a smooth flat look, shimmer for a sparkling effect (requiring shimmer parameters), or
                  metallic for a bold metallic sheen (requiring shimmer parameters and metallic intensity).

                  '
              shimmerColor:
                type: string
                description: 'Color of shimmer particles. Required if texture = shimmer or metallic.

                  '
              shimmerIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Reflective sparkle strength for shimmer or metallic textures.

                  '
              metallicIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Metallic reflectivity level; required for metallic textures.

                  '
              colorIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Overall pigmentation level of each shadow color.

                  '
      example:
        category: eye_shadow
        pattern:
          name: 2colors1
        palettes:
        - color: '#b07baf'
          texture: shimmer
          shimmerColor: '#f2d3f5'
          shimmerIntensity: 60
          colorIntensity: 70
        - color: '#8e5c9c'
          texture: matte
          colorIntensity: 65
    EyelashesEffect:
      type: object
      description: 'Enhances eyelashes by applying pigment to detected lash strands. Lash extensions or
        density enhancements depend on the selected pattern, while the palette controls lash color and
        intensity.

        '
      required:
      - category
      - pattern
      - palettes
      properties:
        category:
          type: string
          enum:
          - eyelashes
          description: 'Identifies this effect as an eyelashes effect. Must always be "eyelashes".

            '
        pattern:
          type: object
          required:
          - name
          description: 'Defines which eyelash style is applied (natural, artistic, winged, upper/lower,
            etc.). Must match a `label` from eyelashes.json.

            '
          properties:
            name:
              type: string
              description: 'Name of the eyelash pattern from eyelashes.json.

                '
              example: Upper1
        palettes:
          type: array
          minItems: 1
          description: 'Eyelash color palettes. Eyelashes do not support shimmer/metallic effects — only
            color and intensity.

            '
          items:
            type: object
            required:
            - color
            - colorIntensity
            properties:
              color:
                type: string
                description: 'Eyelash color in HEX format (#RRGGBB).

                  '
              colorIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Darkness/pigment strength applied to the lashes.

                  '
      example:
        category: eyelashes
        pattern:
          name: Upper1
        palettes:
        - color: '#000000'
          colorIntensity: 80
    FoundationEffect:
      type: object
      description: 'Applies foundation to even skin tone using pigment, coverage, and glow controls. Unlike
        blush/contour, foundation has no pattern — it is applied globally based on skin segmentation.

        '
      required:
      - category
      - palettes
      properties:
        category:
          type: string
          enum:
          - foundation
          description: 'Identifies this effect as a foundation effect. Must always be "foundation".

            '
        palettes:
          type: array
          minItems: 1
          description: 'Foundation palette entries controlling tone, coverage, glow, and color intensity.

            '
          items:
            type: object
            required:
            - color
            - colorIntensity
            - glowIntensity
            - coverageIntensity
            properties:
              color:
                type: string
                description: 'Foundation shade in #RRGGBB format. Typically close to natural skin tone.

                  '
              colorIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Intensity of foundation coloration.

                  '
              glowIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Adds luminosity to the skin finish. Higher values produce a radiant or dewy
                  effect.

                  '
              coverageIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Controls opacity of foundation coverage. Higher values hide more imperfections.

                  '
      example:
        category: foundation
        palettes:
        - color: '#eac595'
          colorIntensity: 50
          glowIntensity: 10
          coverageIntensity: 50
    HighlighterEffect:
      type: object
      description: 'Adds reflective highlights to the high points of the face (cheekbones, cupid''s bow,
        nose bridge, etc.). Patterns determine highlight placement based on face shape. Palettes control
        shimmer, glow, density, particle size, and coloration.

        '
      required:
      - category
      - pattern
      - palettes
      properties:
        category:
          type: string
          enum:
          - highlighter
          description: 'Identifies this effect as a highlighter effect. Must always be "highlighter".

            '
        pattern:
          type: object
          required:
          - name
          description: 'Highlight placement pattern. Must match a `label` from highlighter.json (e.g.,
            HeartFace4, Oblong11, OvalFace2).

            '
          properties:
            name:
              type: string
              description: 'Name of the highlight pattern from the highlighter.json catalog.

                '
              example: SquareFace3
        palettes:
          type: array
          minItems: 1
          description: 'Highlighter palette entries defining shimmer, glow, density, and color.

            '
          items:
            type: object
            required:
            - color
            - glowIntensity
            - shimmerIntensity
            - shimmerDensity
            - shimmerSize
            - colorIntensity
            properties:
              color:
                type: string
                description: 'Highlighter pigment color in #RRGGBB HEX format. Usually white, champagne,
                  gold, or pink tones.

                  '
              glowIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Amount of non-shimmer glow added to the skin. Higher values result in a
                  more luminous, radiant finish.

                  '
              shimmerIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Strength of shimmer reflections. Higher values = more sparkle.

                  '
              shimmerDensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Number of shimmer particles per area. Higher density creates a more glittery
                  effect.

                  '
              shimmerSize:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Size of shimmer particles. Larger particles create a glitter-like effect;
                  small = fine shimmer.

                  '
              colorIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Strength of the highlighter color pigment.

                  '
      example:
        category: highlighter
        pattern:
          name: SquareFace3
        palettes:
        - color: '#FFF7F8'
          glowIntensity: 60
          shimmerIntensity: 50
          shimmerDensity: 40
          shimmerSize: 50
          colorIntensity: 50
    LipColorEffect:
      type: object
      description: 'Applies lipstick in a variety of shapes, finishes, and artistic styles. Includes control
        over lip morphology (fullness, wrinkles), texture (matte, gloss, metallic, shimmer, sheer, etc.),
        shimmer/gloss parameters, multi-color patterns, and ombre/two-tone styles.

        '
      required:
      - category
      - shape
      - palettes
      - style
      properties:
        category:
          type: string
          enum:
          - lip_color
          description: 'Identifies this effect as a lipstick/lip color effect. Must always be "lip_color".

            '
        shape:
          type: object
          description: 'Defines the lip boundary and shape modification. Pattern names must match lipshape.json
            (e.g., plump, original, pouty).

            '
          required:
          - name
          properties:
            name:
              type: string
              description: 'Lip shape style used to modify the lip edges and silhouette. Must be equal
                to a `label` from lipshape.json.

                '
              example: plump
        morphology:
          type: object
          description: 'Optional morphological adjustments to lips. Enhances fullness and reduces lip
            wrinkles.

            '
          properties:
            fullness:
              type: integer
              default: 0
              minimum: 0
              maximum: 100
              description: 'Controls how plump or full the lips appear. Higher values = larger, more voluminous
                lips.

                '
            wrinkless:
              type: integer
              default: 0
              minimum: 0
              maximum: 100
              description: 'Smooths wrinkles and texture on the lips. Higher values result in smoother
                lip appearance.

                '
        palettes:
          type: array
          minItems: 1
          description: 'Lip color palette entries controlling pigment, texture, shimmer, and gloss. Multiple
            palettes can be used for ombre or two-tone styles.

            '
          items:
            type: object
            required:
            - color
            - texture
            - colorIntensity
            properties:
              color:
                type: string
                description: 'Lipstick color in HEX format (#RRGGBB).

                  '
              texture:
                type: string
                enum:
                - matte
                - gloss
                - holographic
                - metallic
                - satin
                - sheer
                - shimmer
                description: 'This setting tells you the texture of lip finish. If you choose gloss, make
                  sure to include gloss properties. For shimmer, metallic or holographic finishes, add
                  the shimmer-related fields. And if you go for sheer, shimmer or gloss, don''t forget
                  to include transparency intensity.

                  '
              colorIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Intensity of lipstick pigmentation.

                  '
              gloss:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Glossiness level for gloss/holographic/metallic/sheer/shimmer textures.

                  '
              shimmerColor:
                type: string
                description: 'Color of shimmer particles for shimmer, metallic, or holographic textures.

                  '
              shimmerIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Strength of shimmer reflectivity.

                  '
              shimmerDensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Density of shimmer particles.

                  '
              shimmerSize:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Size of shimmer particles.

                  '
              transparencyIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Transparency effect strength. Used for sheer, shimmer, or gloss textures.

                  '
        style:
          type: object
          description: 'Styles describe the artistic look of lip colour, whether it''s a full uniform
            shade, an ombre gradient blending tones, or a two-tone effect with contrasting colors on different
            parts of the lips.

            '
          required:
          - type
          properties:
            type:
              type: string
              enum:
              - full
              - ombre
              - twoTone
              description: 'Style of lip coloration.

                '
            innerColorRatio:
              type: integer
              minimum: 0
              maximum: 100
              description: 'Determines how far inward the secondary color extends (ombre only). Required
                if type = ombre.

                '
            blendStrength:
              type: integer
              minimum: 0
              maximum: 100
              description: 'Blending softness between colors. Required if type = ombre.

                '
      example:
        category: lip_color
        shape:
          name: plump
        morphology:
          fullness: 20
          wrinkless: 10
        style:
          type: full
        palettes:
        - color: '#C2185B'
          texture: gloss
          colorIntensity: 80
          gloss: 70
          transparencyIntensity: 30
    LipLinerEffect:
      type: object
      description: 'Applies lip liner around the edges of the lips, enhancing shape definition. Useful
        for refining lip borders, adjusting symmetry, and supporting ombre/two-tone looks.

        '
      required:
      - category
      - pattern
      - palettes
      properties:
        category:
          type: string
          enum:
          - lip_liner
          description: 'Identifies this effect as a lip liner effect. Must always be "lip_liner".

            '
        pattern:
          type: object
          required:
          - name
          description: 'Defines lip liner placement based on pattern from lipliner.json.

            '
          properties:
            name:
              type: string
              description: 'Name of lip liner pattern (e.g., Natural1, LargerUpper1).

                '
              example: Natural1
        palettes:
          type: array
          minItems: 1
          description: 'Lip liner palette entries defining color, thickness, and smoothness.

            '
          items:
            type: object
            required:
            - color
            - texture
            - colorIntensity
            - thickness
            - smoothness
            properties:
              color:
                type: string
                description: 'Lip liner pigment color in HEX format.

                  '
              texture:
                type: string
                enum:
                - matte
                - satin
                description: 'Lip liner finish type.

                  '
              colorIntensity:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Intensity of lip liner pigmentation.

                  '
              thickness:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Thickness of the lip liner stroke — higher values create bolder outlines.

                  '
              smoothness:
                type: integer
                minimum: 0
                maximum: 100
                description: 'Smoothness of the stroke edges. Higher values produce softer, blended lines.

                  '
      example:
        category: lip_liner
        pattern:
          name: Natural1
        palettes:
        - color: '#A63A50'
          texture: matte
          colorIntensity: 70
          thickness: 40
          smoothness: 50
  responses:
    InvalidParameters:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 400
                description: Response status
              error:
                type: string
                description: Error message
                example: The operation could not be completed
              error_code:
                type: string
                enum:
                - InvalidParameters
    InvalidApiKey:
      description: Invalid API Key or Inactive API Key or Expired API Key
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 401
                description: Response status
              error_code:
                type: string
                enum:
                - InvalidApiKey
                - InactiveApiKey
                - ExpiredApiKey
    TooManyRequests:
      description: Too many requests within a given amount of time
    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:
          - CreditInsufficiency
          - InvalidStyleGroup
          - InvalidStyle
          - BadRequest
          - InvalidParameters
    TaskTimeout:
      description: The task has no response in the expected time
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                description: Response status
                example: 500
              error_code:
                type: string
                enum:
                - TaskTimeout
    InvalidTaskId:
      description: Invalid task id
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                description: Response status
                example: 400
              error_code:
                type: string
                enum:
                - InvalidTaskId