openapi: 3.0.0
info:
  title: AI Skin Analysis
  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/youcamapps/youcam/privacy-policy.html
  description: >
    # Overview


    ![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_demostore_skincarelive_topbanner.0cffe3a7.jpg)

    AI skincare analysis technology harnesses the power of artificial
    intelligence to analyze various aspects of the skin, from texture and
    pigmentation to hydration and pore size, with remarkable precision. By
    employing advanced algorithms and machine learning, AI skin analysis can
    offer personalized recommendations and skincare routines tailored to an
    individual's unique skin type and concerns.


    This not only enhances the effectiveness of skincare products but also
    empowers users to make informed decisions about their skincare regimen. With
    the integration of AI skin analysis, individuals can now embark on a journey
    towards healthier, more radiant skin, guided by data-driven insights and the
    promise of more effective skincare solutions.



    ## Integration Guide

     * Step 1 — Initialize the Module

    Call `YMK.init()` before calling `YMK.openCameraKit()`:


    ```javascript

    YMK.init({
      faceDetectionMode: 'skincare',
      imageFormat: 'base64',
      language: 'enu'
    });

    ```

     * Supported Detection Modes

    Set faceDetectionMode in InitOptions to one of:

    | Mode             |
    Description                                               |

    | ---------------- |
    --------------------------------------------------------- |

    | `makeup`         | Standard camera mode for virtual cosmetic try-on |

    | `skincare`       | Standard skin analysis mode, close-up face
    capture        |

    | `hdskincare`     | HD Skin capture using webcams with ≥ 2560px width |

    | `shadefinder`    | Skin Tone Analysis front-face
    capture                           |

    | `hairlength`     | Full hair-length capture (from a
    distance)                |

    | `hairfrizziness` | 3-phase capture: front, right-turn,
    left-turn             |

    | `hairtype`       | Same 3-phase multi-angle capture
    flow                     |

    | `ring` | Hand capture for ring try‑on |

    | `wrist` | Wrist capture for watch or bracelet try‑on |

    | `necklace` | Selfie capture for necklace try-on |

    | `earring` |  Selfie capture for earring try-on  |


    ---

     * Step 2 — Add Event Handlers

    Event examples:


    ```javascript

    YMK.addEventListener('faceQualityChanged', function(q) {
      console.log('Quality updated:', q);
    });

    ```


    See the full Events List below.


    ---

     * Step 3 — Open Camera Kit

    ```javascript

    YMK.openCameraKit();

    ```


    This automatically:


    * Shows the UI

    * Opens webcam

    * Begins real-time face quality monitoring

    * Automatically captures when conditions are acceptable


    ---

     * Step 4 — Receiving Captured Result

    Captured images arrive via:


    ```javascript

    YMK.addEventListener('faceDetectionCaptured', function(result) {
      console.log(result.images);
    });

    ```


    ---

     * Step 5 — Close Module

    ```javascript

    YMK.close();

    ```


    ## Inputs & Outputs

     * Input Paramenter Description
    There are two options for controlling the visual output of AI Skin Analysis
    results: either generate multiple images, with each skin concern displayed
    as an independent mask, or produce a single blended image using the
    ``enable_mask_overlay`` parameter. By default, the system outputs multiple
    masks, giving you full control over how to blend each skin concern mask with
    the image.


    * Default: enable_mask_overlay false
      ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/mask_overlay_false_1920_ea1cde0ead.png)

    * Set enable_mask_overlay to true
      ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/mask_overlay_1920_0fbb4786cc.png)

    ----

     * Output ZIP Data Structure Description
    The system provides a ZIP file with a 'skinanalysisResult' folder inside.
    This folder contains a 'score_info.json' file that includes all the
    detection scores and references to the result images.


    The 'score_info.json' file contains all the skin analysis detection results,
    with numerical scores and the names of the corresponding output mask files.


    The PNG files are detection result masks that can be overlaid on your
    original image. Simply use the alpha values in these PNG files to blend them
    with your original image, allowing you to see the detection results directly
    on the source image.

     * File Structure in the Skin Analysis Result ZIP
    * HD Skincare ZIP
      * skinanalysisResult
        - score_info.json
        - hd_acne_output.png
        - hd_age_spot_output.png
        - hd_dark_circle_output.png
        - hd_droopy_lower_eyelid_output.png
        - hd_droopy_upper_eyelid_output.png
        - hd_eye_bag_output.png
        - hd_firmness_output.png
        - hd_moisture_output.png
        - hd_oiliness_output.png
        - hd_radiance_output.png
        - hd_redness_output.png
        - hd_texture_output.png
        - hd_pore_output_all.png
        - hd_pore_output_cheek.png
        - hd_pore_output_forehead.png
        - hd_pore_output_nose.png
        - hd_wrinkle_output_all.png
        - hd_wrinkle_output_crowfeet.png
        - hd_wrinkle_output_forehead.png
        - hd_wrinkle_output_glabellar.png
        - hd_wrinkle_output_marionette.png
        - hd_wrinkle_output_nasolabial.png
        - hd_wrinkle_output_periocular.png

    * SD Skincare ZIP
      * skinanalysisResult
        - score_info.json
        - acne_output.png
        - age_spot_output.png
        - dark_circle_v2_output.png
        - droopy_lower_eyelid_output.png
        - droopy_upper_eyelid_output.png
        - eye_bag_output.png
        - firmness_output.png
        - moisture_output.png
        - oiliness_output.png
        - pore_output.png
        - radiance_output.png
        - redness_output.png
        - texture_output.png
        - wrinkle_output.png

    * JSON Data Structure (score_info.json)
      * "all": A floating-point value between 1 and 100 representing the general skin condition. A higher score indicates healthier and more aesthetically pleasing skin condition.
      * "skin_age": AI-derived skin age relative to the general population distribution across all age groups.
      * Each category contains:
        * "raw_score": A floating-point value ranging from 1 to 100. A higher score indicates healthier and more aesthetically pleasing skin condition.
        * "ui_score": An integer ranging from 1 to 100. The UI Score functions primarily as a psychological motivator in beauty assessment. We adjust the raw scores to produce more favorable results, acknowledging that consumers generally prefer positive evaluations regarding their skin health. This calibration serves to instill greater confidence in users while maintaining the underlying beauty psychology framework.
        * "output_mask_name": The filename of the corresponding output mask image.

      * Categories and Descriptions
        * HD Skincare:
            * "hd_redness": Measures skin redness severity.
            * "hd_oiliness": Determines skin oiliness level.
            * "hd_age_spot": Detects age spots and pigmentation.
            * "hd_radiance": Evaluates skin radiance.
            * "hd_moisture": Assesses skin hydration levels.
            * "hd_dark_circle": Analyzes the presence of dark circles under the eyes.
            * "hd_eye_bag": Detects eye bags.
            * "hd_droopy_upper_eyelid": Measures upper eyelid drooping severity.
            * "hd_droopy_lower_eyelid": Measures lower eyelid drooping severity.
            * "hd_firmness": Evaluates skin firmness and elasticity.
            * "hd_texture": Subcategories[whole]; Analyzes overall skin texture.
            * "hd_acne": Subcategories[whole]; Detects acne presence.
            * "hd_pore": Subcategories[forehead, nose, cheek, whole]; Detects and evaluates pores in different facial regions.
            * "hd_wrinkle": Subcategories[forehead, glabellar, crowfeet, periocular, nasolabial, marionette, whole]; Measures the severity of wrinkles in various facial areas.

        * SD Skincare:
            * "wrinkle": General wrinkle analysis.
            * "droopy_upper_eyelid": Measures upper eyelid drooping severity.
            * "droopy_lower_eyelid": Measures lower eyelid drooping severity.
            * "firmness": Evaluates skin firmness and elasticity.
            * "acne": Evaluates acne presence.
            * "moisture": Measures skin hydration.
            * "eye_bag": Detects eye bags.
            * "dark_circle_v2": Analyzes dark circles using an alternative method.
            * "age_spot": Detects age spots.
            * "radiance": Evaluates skin brightness.
            * "redness": Measures skin redness.
            * "oiliness": Determines skin oiliness.
            * "pore": Measures pore visibility.
            * "texture": Analyzes overall skin texture.

      * Sample score_info.json of HD Skincare
        ```json
        {
            "hd_redness": {
                "raw_score": 72.011962890625,
                "ui_score": 77,
                "output_mask_name": "hd_redness_output.png"
            },
            "hd_oiliness": {
                "raw_score": 60.74365234375,
                "ui_score": 72,
                "output_mask_name": "hd_oiliness_output.png"
            },
            "hd_age_spot": {
                "raw_score": 83.23274230957031,
                "ui_score": 77,
                "output_mask_name": "hd_age_spot_output.png"
            },
            "hd_radiance": {
                "raw_score": 76.57244205474854,
                "ui_score": 79,
                "output_mask_name": "hd_radiance_output.png"
            },
            "hd_moisture": {
                "raw_score": 48.694559931755066,
                "ui_score": 70,
                "output_mask_name": "hd_moisture_output.png"
            },
            "hd_dark_circle": {
                "raw_score": 80.1993191242218,
                "ui_score": 76,
                "output_mask_name": "hd_dark_circle_output.png"
            },
            "hd_eye_bag": {
                "raw_score": 76.67280435562134,
                "ui_score": 79,
                "output_mask_name": "hd_eye_bag_output.png"
            },
            "hd_droopy_upper_eyelid": {
                "raw_score": 79.05348539352417,
                "ui_score": 80,
                "output_mask_name": "hd_droopy_upper_eyelid_output.png"
            },
            "hd_droopy_lower_eyelid": {
                "raw_score": 79.97175455093384,
                "ui_score": 81,
                "output_mask_name": "hd_droopy_lower_eyelid_output.png"
            },
            "hd_firmness": {
                "raw_score": 89.66898322105408,
                "ui_score": 85,
                "output_mask_name": "hd_firmness_output.png"
            },
            "hd_texture": {
                "whole": {
                    "raw_score": 66.3921568627451,
                    "ui_score": 75,
                    "output_mask_name": "hd_texture_output.png"
                }
            },
            "hd_acne": {
                "whole": {
                    "raw_score": 59.92677688598633,
                    "ui_score": 76,
                    "output_mask_name": "hd_acne_output.png"
                }
            },
            "hd_pore": {
                "forehead": {
                    "raw_score": 79.59770965576172,
                    "ui_score": 80,
                    "output_mask_name": "hd_pore_output_forehead.png"
                },
                "nose": {
                    "raw_score": 29.139814376831055,
                    "ui_score": 58,
                    "output_mask_name": "hd_pore_output_nose.png"
                },
                "cheek": {
                    "raw_score": 44.11081314086914,
                    "ui_score": 65,
                    "output_mask_name": "hd_pore_output_cheek.png"
                },
                "whole": {
                    "raw_score": 49.23978805541992,
                    "ui_score": 67,
                    "output_mask_name": "hd_pore_output_all.png"
                }
            },
            "hd_wrinkle": {
                "forehead": {
                    "raw_score": 55.96956729888916,
                    "ui_score": 67,
                    "output_mask_name": "hd_wrinkle_output_forehead.png"
                },
                "glabellar": {
                    "raw_score": 76.7251181602478,
                    "ui_score": 75,
                    "output_mask_name": "hd_wrinkle_output_glabellar.png"
                },
                "crowfeet": {
                    "raw_score": 83.4361481666565,
                    "ui_score": 78,
                    "output_mask_name": "hd_wrinkle_output_crowfeet.png"
                },
                "periocular": {
                    "raw_score": 67.88706302642822,
                    "ui_score": 72,
                    "output_mask_name": "hd_wrinkle_output_periocular.png"
                },
                "nasolabial": {
                    "raw_score": 74.03312683105469,
                    "ui_score": 74,
                    "output_mask_name": "hd_wrinkle_output_nasolabial.png"
                },
                "marionette": {
                    "raw_score": 71.94477319717407,
                    "ui_score": 73,
                    "output_mask_name": "hd_wrinkle_output_marionette.png"
                },
                "whole": {
                    "raw_score": 49.64699745178223,
                    "ui_score": 65,
                    "output_mask_name": "hd_wrinkle_output_all.png"
                }
            },
            "all": {
                "score": 75.75757575757575
            },
            "skin_age": 37
        }
        ```
      * Sample score_info.json of SD Skincare
        ```json
        {
            "wrinkle": {
                "raw_score": 36.09360456466675,
                "ui_score": 60,
                "output_mask_name": "wrinkle_output.png"
            },
            "droopy_upper_eyelid": {
                "raw_score": 79.05348539352417,
                "ui_score": 80,
                "output_mask_name": "droopy_upper_eyelid_output.png"
            },
            "droopy_lower_eyelid": {
                "raw_score": 79.97175455093384,
                "ui_score": 81,
                "output_mask_name": "droopy_lower_eyelid_output.png"
            },
            "firmness": {
                "raw_score": 89.66898322105408,
                "ui_score": 85,
                "output_mask_name": "firmness_output.png"
            },
            "acne": {
                "raw_score": 92.29713000000001,
                "ui_score": 88,
                "output_mask_name": "acne_output.png"
            },
            "moisture": {
                "raw_score": 48.694559931755066,
                "ui_score": 70,
                "output_mask_name": "moisture_output.png"
            },
            "eye_bag": {
                "raw_score": 76.67280435562134,
                "ui_score": 79,
                "output_mask_name": "eye_bag_output.png"
            },
            "dark_circle_v2": {
                "raw_score": 80.1993191242218,
                "ui_score": 76,
                "output_mask_name": "dark_circle_v2_output.png"
            },
            "age_spot": {
                "raw_score": 83.23274230957031,
                "ui_score": 77,
                "output_mask_name": "age_spot_output.png"
            },
            "radiance": {
                "raw_score": 76.57244205474854,
                "ui_score": 79,
                "output_mask_name": "radiance_output.png"
            },
            "redness": {
                "raw_score": 72.011962890625,
                "ui_score": 77,
                "output_mask_name": "redness_output.png"
            },
            "oiliness": {
                "raw_score": 60.74365234375,
                "ui_score": 72,
                "output_mask_name": "oiliness_output.png"
            },
            "pore": {
                "raw_score": 88.38014125823975,
                "ui_score": 84,
                "output_mask_name": "pore_output.png"
            },
            "texture": {
                "raw_score": 80.09742498397827,
                "ui_score": 76,
                "output_mask_name": "texture_output.png"
            },
            "all": {
                "score": 75.75757575757575
            },
            "skin_age": 37
        }
        ```

    ## File Specs & Errors

     * Supported Formats & Dimensions

    |AI Feature|Supported Dimensions|Supported File Size|Supported Formats|

    |  ----  | ----  | ----  | ----  |

    |SD Skincare|**long side <= 1920, short side >= 480**|< 10MB|jpg/jpeg/png|

    |HD Skincare|**long side <= 2560, short side >= 1080**|< 10MB|jpg/jpeg/png|


    > **Warning:** It is your resposibility to resize input images based on the
    ***Supported Dimensions*** of HD or SD Skincare before runing AI Skin
    Analysis. It is highly recommended to use **portrait** rather than landscape
    aspect ratio as input.

     * Suggestions for How to Shoot:
    ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png)

     * Get Ready to Start Skin Analysis Instructions
    * Take off your glasses and make sure bangs are not covering your forehead

    * Make sure that you’re in a well-lit environment

    * Remove makeup to get more accurate results

    * Look straight into the camera and keep your face in the center

     * Photo requirement

    We will check the image quality to ensure it is suitable for AI Skin
    Analysis. Please make sure the face occupies approximately 60–80% of the
    image width, without any overlays or obstructions. The lighting should be
    bright and evenly distributed, avoiding overexposure or blown-out
    highlights. The pose should be front-facing, neutral, and relaxed, with the
    mouth closed and eyes open.


    You should fully reveal your forehead and brush your fringe back or tie your
    hair to ensure the best quality. It is recommended that you remove your
    spectacles for optimal AI Skin Analysis performance, although this is not
    mandatory.

    > **Warning:** The width of the face needs to be greater than 60% of the
    width of the image.


    ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_error_src_face_too_small_cr_725792a7fb.png)


     * Error Codes

    |Error Code|Description|

    |  ----  | ----  |

    |error_below_min_image_size|Input image resolution is too small|

    |error_exceed_max_image_size|Input image resolution is too large|

    |error_src_face_too_small|The face area in the uploaded image is too small.
    The width of the face needs to be greater than 60% of the width of the
    image.|

    |error_src_face_out_of_bound|The face area in the uploaded image is out of
    bound|

    |error_lighting_dark|The lighting in the uploaded image is too dark|

     * Environment & Dependency

    | Sample Code Language / Tool | Recommended Runtime Versions |

    |---|---|

    | cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP
    support)</br>   - jq >= 1.6 (robust JSON parsing) |

    | Node.js (JavaScript) | Node >= 18 (for global fetch) |

    | JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari
    >= 13.1 |

    | PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) or
    allow_url_fopen=On + ext-openssl, ext-json |

    | Python | Python >= 3.10 (for f-strings), requests >= 2.20.0 |

    | Java | Java 11+ (for HttpClient), Jackson Databind >= 2.12.0 |


    ## JS Camera Kit

     * Overview

    The **JavaScript Camera Kit** provides a complete in-browser camera solution
    designed for high-accuracy face-based imaging tasks. It includes:


    * Camera permission handling

    * Real-time face detection

    * Automatic face quality validation (lighting, pose, angle, distance)

    * Guided capture UI

    * Multi-step capture flows for advanced hair/face tasks

    * Support for both **base64** and **blob** output formats


    The module is particularly optimized for **AI-driven image analysis**, such
    as AI Skin Analysis (SD/HD), AI Face Tone Analysis, and hair-related
    analysis.


    ---

     * Download the JS Camera Kit
    Include the JS Camera Kit SDK via CDN:


    ```

    https://plugins-media.makeupar.com/v2.2-camera-kit/sdk.js

    ```


    Once loaded, the SDK installs a global `YMK` object.


    ---

     * Quick Start Example

    The following sample demonstrates:


    * Loading the JS Camera Kit SDK

    * Implementing `window.ymkAsyncInit`

    * Initializing the module

    * Opening the camera

    * Receiving captured images


    ```html

    <!DOCTYPE html>

    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Camera Kit Sample</title>
      </head>

      <body>
        <script>
          window.ymkAsyncInit = function() {
            YMK.addEventListener('loaded', function() {
              /* Module fully loaded and ready */
            });

            YMK.addEventListener('faceDetectionCaptured', function(capturedResult) {
              /* Display all captured images */
              const container = document.getElementById('captured-results');
              container.innerHTML = '';

              for (const image of capturedResult.images) {
                const img = document.createElement('img');
                img.src = typeof image.image === 'string'
                  ? image.image
                  : URL.createObjectURL(image.image);

                container.appendChild(img);
              }
            });
          };

          function openCameraKit() {
            YMK.init({
              faceDetectionMode: 'skincare',
              imageFormat: 'base64',
              language: 'enu',
            });
            YMK.openCameraKit();
          }
        </script>

        <!-- Load SDK -->
        <script>
          window.addEventListener('load', function() {
            (function(d) {
              const s = d.createElement('script');
              s.type = 'text/javascript';
              s.async = true;
              s.src = 'https://plugins-media.makeupar.com/v2.2-camera-kit/sdk.js';
              d.getElementsByTagName('script')[0].parentNode.insertBefore(s, null);
            })(document);
          });
        </script>

        <button onClick="openCameraKit()">Open Camera Kit</button>

        <div id="YMK-module"></div>

        <h3>Captured Results:</h3>
        <div id="captured-results"></div>
      </body>
    </html>

    ```


    ---

     * Prerequisites

    You must define the asynchronous initialization entry point:


    ```html

    <script>
      window.ymkAsyncInit = function() {
        YMK.init(); // default settings
      };
    </script>

    ```


    Additional requirements:


    | Requirement             | Description                                 |

    | ----------------------- | ------------------------------------------- |

    | Browser                 | Must support `getUserMedia`                 |

    | HTTPS                   | Required on most browsers for webcam access |

    | `<div id="YMK-module">` | Mandatory mount point for the UI            |
servers:
  - url: https://yce-api-01.makeupar.com
tags:
  - name: API Reference
    description: >
      AI skincare analysis technology harnesses the power of artificial
      intelligence to analyze various aspects

      of the skin, from texture and pigmentation to hydration and pore size,
      with remarkable precision.

      By employing advanced algorithms and machine learning, AI skin analysis
      can offer personalized

      recommendations and skincare routines tailored to an individual's unique
      skin type and concerns.
paths:
  /s2s/v2.0/file/skin-analysis:
    post:
      summary: Create a new file.
      description: >-
        To upload a new file, you'll first need to use the File API. It will
        give you a URL – use that URL to upload your file. Once the upload is
        finished, you can use the file_id from the same response to start using
        our AI features.
      tags:
        - API Reference
      security:
        - BearerAuthenticationV2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileV1.1'
      responses:
        '200':
          description: Successful retrieval of file upload information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileResponseV2'
        '400':
          $ref: '#/components/responses/InvalidParameters'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
  /s2s/v2.0/task/skin-analysis:
    post:
      summary: Run a Skin Analysis task.
      description: >
        Create a skin analysis task using either a file_id (from the File API)
        or a publicly accessible image URL.

        The task will analyze various skin attributes based on the specified
        dst_actions.
      tags:
        - API Reference
      security:
        - BearerAuthenticationV2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunSkincareTaskV2'
      responses:
        '200':
          description: Successful execution of Skin Analysis task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicRunTaskResponseV2'
        '400':
          $ref: '#/components/responses/RunError'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /s2s/v2.0/task/skin-analysis/{task_id}:
    get:
      summary: Check a Skin Analysis task status.
      tags:
        - API Reference
      security:
        - BearerAuthenticationV2: []
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
            example: grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe
          description: ID of task to check
      responses:
        '200':
          $ref: '#/components/responses/SkinAnalysisResponse'
        '400':
          $ref: '#/components/responses/InvalidTaskId'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '500':
          $ref: '#/components/responses/TaskTimeout'
  /s2s/v2.1/file/skin-analysis:
    post:
      summary: Create a new file V2.1.
      description: >-
        To upload a new file, you'll first need to use the File API. It will
        give you a URL – use that URL to upload your file. Once the upload is
        finished, you can use the file_id from the same response to start using
        our AI features.
      tags:
        - API Reference
      security:
        - BearerAuthenticationV2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileV1.1'
      responses:
        '200':
          description: Successful retrieval of file upload information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileResponseV2'
        '400':
          $ref: '#/components/responses/InvalidParameters'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
  /s2s/v2.1/task/skin-analysis:
    post:
      summary: Run a Skin Analysis V2.1 task.
      description: >
        Once you start an AI task, you need to keep polling at given
        polling_interval to check its status until it shows either success or
        error because if you don't, the task will time out and when you try to
        check the status later, you'll get an InvalidTaskId error even if the
        task did finish successfully and your units will still be consumed.
      tags:
        - API Reference
      security:
        - BearerAuthenticationV2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/RunSkincareTaskV2'
                - type: object
                  properties:
                    pf_camera_kit:
                      type: boolean
                      example: true
      responses:
        '200':
          description: Successful execution of Skin Analysis task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicRunTaskResponseV2'
        '400':
          $ref: '#/components/responses/RunError'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /s2s/v2.1/task/skin-analysis/{task_id}:
    get:
      summary: Check a Skin Analysis V2.1 task status.
      tags:
        - API Reference
      security:
        - BearerAuthenticationV2: []
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
            example: grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe
          description: ID of task to check
      responses:
        '200':
          $ref: '#/components/responses/SkinAnalysisResponse'
        '400':
          $ref: '#/components/responses/InvalidTaskId'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '500':
          $ref: '#/components/responses/TaskTimeout'
components:
  securitySchemes:
    BearerAuthenticationV2:
      type: http
      scheme: bearer
      description: >-
        Use the standard 'Bearer authentication'. Put your 'API Key' in header:
        `Authorization:Bearer YOUR_API_KEY`. Notice that there is ' ' a space
        between 'Bearer' and the 'YOUR_API_KEY'.
  schemas:
    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
                    method:
                      type: string
                      example: PUT
                      description: HTTP method to use for upload
                    url:
                      type: string
                      example: https://example.com/upload
                      description: Pre-signed URL for uploading the file
    FileResponseV2:
      type: object
      properties:
        status:
          type: integer
          example: 200
          description: Response status
        data:
          $ref: '#/components/schemas/BasicFileResponse'
    BasicRunTaskV2:
      title: BasicRunTaskV2
      anyOf:
        - $ref: '#/components/schemas/BasicRunTaskV2SrcFileUrl'
        - $ref: '#/components/schemas/BasicRunTaskV2SrcFileId'
    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=
    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
    RunSkincareTaskV2:
      allOf:
        - $ref: '#/components/schemas/BasicRunTaskV2'
        - title: RunSkincareTaskV2
          description: This object represents a run Skin Analysis task.
          type: object
          properties:
            dst_actions:
              $ref: '#/components/schemas/RunSkincareTaskDstActions'
            miniserver_args:
              $ref: '#/components/schemas/RunSkincareTaskMiniserverArgs'
            format:
              type: string
              enum:
                - json
                - zip
              description: >
                Response format of the analysis results. Default is 'zip'. -
                `zip`: Results will be packaged as a downloadable ZIP file
                containing a skinanalysisResult folder with score_info.json and
                all detection result images. The response will include a URL to
                download the ZIP file. - `json`: Results will be returned
                directly in the response body as JSON format. Note: The response
                schema differs between format=json and format=zip.
              example: zip
          required:
            - dst_actions
    RunSkincareTaskDstActions:
      type: array
      description: |
        The actions for Skin Analysis.
        There are 2 types of features: HD and SD.
        You can choose one or more features, either all in SD or all in HD.
        Note: HD and SD features cannot be mixed.
        HD features:
          - hd_redness: Measures skin redness severity.
          - hd_oiliness: Determines skin oiliness level.
          - hd_age_spot: Detects age spots and pigmentation.
          - hd_radiance: Evaluates skin radiance.
          - hd_moisture: Assesses skin hydration levels.
          - hd_dark_circle: Analyzes the presence of dark circles under the eyes.
          - hd_eye_bag: Detects eye bags.
          - hd_droopy_upper_eyelid: Measures upper eyelid drooping severity.
          - hd_droopy_lower_eyelid: Measures lower eyelid drooping severity.
          - hd_firmness: Evaluates skin firmness and elasticity.
          - hd_texture: Analyzes overall skin texture.
          - hd_acne: Detects acne presence.
          - hd_pore: Detects and evaluates pores in different facial regions (forehead, nose, cheek, whole).
          - hd_wrinkle: Measures the severity of wrinkles in various facial areas (forehead, glabellar, crowfeet, periocular, nasolabial, marionette, whole).
          - hd_tear_trough: Detects tear trough.
          - hd_skin_type: Evalutate skin type.

        SD features:
          - wrinkle: General wrinkle analysis.
          - droopy_upper_eyelid: Measures upper eyelid drooping severity.
          - droopy_lower_eyelid: Measures lower eyelid drooping severity.
          - firmness: Evaluates skin firmness and elasticity.
          - acne: Evaluates acne presence.
          - moisture: Measures skin hydration.
          - eye_bag: Detects eye bags.
          - dark_circle_v2: Analyzes dark circles.
          - age_spot: Detects age spots.
          - radiance: Evaluates skin brightness.
          - redness: Measures skin redness.
          - oiliness: Determines skin oiliness.
          - pore: Measures pore visibility.
          - texture: Analyzes overall skin texture.
          - tear_trough: Detects tear trough.
          - skin_type: Evalutate skin type.
      items:
        type: string
        enum:
          - hd_wrinkle
          - hd_pore
          - hd_texture
          - hd_acne
          - hd_oiliness
          - hd_radiance
          - hd_eye_bag
          - hd_age_spot
          - hd_dark_circle
          - hd_droopy_upper_eyelid
          - hd_droopy_lower_eyelid
          - hd_firmness
          - hd_moisture
          - hd_redness
          - hd_tear_trough
          - hd_skin_type
          - wrinkle
          - pore
          - texture
          - acne
          - oiliness
          - radiance
          - eye_bag
          - age_spot
          - dark_circle_v2
          - droopy_upper_eyelid
          - droopy_lower_eyelid
          - firmness
          - moisture
          - redness
          - tear_trough
          - skin_type
      example:
        - hd_wrinkle
        - hd_pore
        - hd_texture
        - hd_acne
    RunSkincareTaskMiniserverArgs:
      type: object
      properties:
        enable_mask_overlay:
          type: boolean
          description: >-
            Controls whether the mask is blended onto the image. True returns
            the overlaid image as a .jpg. False returns the raw mask as a .png.
            Default is false.
        enable_dark_background_hd_pore:
          type: boolean
          description: Enable dark background for HD pore visualization
        color_dark_background_hd_pore:
          type: string
          description: Color for HD pore dark background visualization (hex format)
          example: 3D3D3D
        opacity_dark_background_hd_pore:
          type: number
          minimum: 0
          maximum: 1
          description: Opacity for HD pore dark background visualization
          example: 0.4
        enable_dark_background_hd_wrinkle:
          type: boolean
          description: Enable dark background for HD wrinkle visualization
        color_dark_background_hd_wrinkle:
          type: string
          description: Color for HD wrinkle dark background visualization (hex format)
          example: 3D3D3D
        opacity_dark_background_hd_wrinkle:
          type: number
          minimum: 0
          maximum: 1
          description: Opacity for HD wrinkle dark background visualization
          example: 0.4
    SkinAnalysisResponseV2:
      type: object
      properties:
        status:
          type: integer
          description: Response status
          example: 200
        data:
          type: object
          properties:
            task_status:
              type: string
              enum:
                - running
                - success
                - error
              description: Status of this task
            error:
              $ref: '#/components/schemas/EngineErrorCode'
            error_message:
              type: string
              description: Detailed description of error
            results:
              oneOf:
                - $ref: '#/components/schemas/SkinAnalysisResultsV2Zip'
                - $ref: '#/components/schemas/SkinAnalysisResultsV2Json'
    SkinAnalysisResultsV2Zip:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          description: >-
            URL to download this result. Valid for 2 hours. The returned ZIP
            file contains a skinanalysisResult folder of a score_info.json file
            with all detection result scores and images of all detection
            results. Only available when format is `zip`.
          example: >-
            https://s3-us-west-2.amazonaws.com/yce-us/gst_tsk/a29e54f4-03a8-4ff1-9226-d6c83ae86053/34516942129/cf4d1764-4517-44af-aed8-fc78fc186072.zip
    SkinAnalysisResultsV2Json:
      type: object
      required:
        - output
      properties:
        output:
          type: array
          description: >-
            The analysis result returned directly in the response body as JSON
            format. Only available when format is `json`.
          items:
            type: object
            properties:
              type:
                type: string
                description: The action of Skin Analysis
                example: hd_skin_type
              region:
                type: string
                description: The region of the face where the analysis is focused
                example: whole
              raw_score:
                type: number
                description: >-
                  A floating-point value ranging from 1 to 100. The raw_score
                  refers to the score directly predicted by the AI model
                example: 98.5
              ui_score:
                type: integer
                description: >-
                  An integer ranging from 1 to 100. The ui_score is the adjusted
                  score based on the raw score
                example: 97
              score:
                type: number
                description: >-
                  A floating-point value between 1 and 100 representing the
                  general skin condition.
                example: 97.66
              mask_urls:
                type: array
                description: >-
                  The URLs of the mask images or resized images generated during
                  analysis
                items:
                  type: string
                  example: https://example.com/mask_image_1.png
    EngineErrorCode:
      type: string
      nullable: true
      enum:
        - 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:

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

        - `invalid_parameter` - Invalid parameter value

        - `error_download_image` - Download source image error

        - `error_download_mask` - Download mask image error

        - `error_decode_image` - Decode source image error

        - `error_decode_mask` - Decode mask image error

        - `error_nsfw_content_detected` - NSFW content detected in source image

        - `error_no_face` - No face detected on source image

        - `error_pose` - Failed to detect pose on source image

        - `error_face_parsing` - Failed to do face segmentation on source image

        - `error_inference` - Inference pipeline error

        - `exceed_nsfw_retry_limits` - Exceed the retry limits to avoid
        generated NSFW image

        - `error_upload` - Upload result image error

        - `unknown_internal_error` - Others
  responses:
    InvalidParameters:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 400
                description: Response status
              error:
                type: string
                example: Invalid parameter value
              error_code:
                type: string
                example: InvalidParameters
    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: Rate limit exceeded
    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
    RunError:
      description: Task execution error
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 500
                description: Response status
              error:
                type: string
                example: Task execution timed out
    SkinAnalysisResponse:
      description: Successful check of Skin Analysis task status
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SkinAnalysisResponseV2'
          examples:
            format_zip_success:
              summary: Response when format=zip (success)
              description: Task completed successfully. Results are packaged as a ZIP file.
              value:
                status: 200
                data:
                  task_status: success
                  results: https://example.com/sample-result-url
            format_json_success:
              summary: Response when format=json (success)
              description: >-
                Task completed successfully. Results are returned directly as
                JSON with detailed scores and image URLs.
              value:
                status: 200
                data:
                  task_status: success
                  results:
                    output:
                      - type: hd_wrinkle
                        region: whole
                        raw_score: 25.3
                        ui_score: 25
                        mask_urls:
                          - >-
                            https://s3-us-west-2.amazonaws.com/yce-us/results/hd_wrinkle_whole.jpg
                      - type: hd_wrinkle
                        region: forehead
                        raw_score: 20.1
                        ui_score: 20
                        mask_urls:
                          - >-
                            https://s3-us-west-2.amazonaws.com/yce-us/results/hd_wrinkle_forehead.jpg
                      - type: hd_wrinkle
                        region: glabellar
                        raw_score: 15.8
                        ui_score: 16
                        mask_urls:
                          - >-
                            https://s3-us-west-2.amazonaws.com/yce-us/results/hd_wrinkle_glabellar.jpg
                      - type: hd_wrinkle
                        region: crowfeet
                        raw_score: 30.5
                        ui_score: 31
                        mask_urls:
                          - >-
                            https://s3-us-west-2.amazonaws.com/yce-us/results/hd_wrinkle_crowfeet.jpg
                      - type: hd_pore
                        region: whole
                        raw_score: 35.2
                        ui_score: 35
                        mask_urls:
                          - >-
                            https://s3-us-west-2.amazonaws.com/yce-us/results/hd_pore_whole.jpg
                      - type: hd_pore
                        region: forehead
                        raw_score: 30
                        ui_score: 30
                        mask_urls:
                          - >-
                            https://s3-us-west-2.amazonaws.com/yce-us/results/hd_pore_forehead.jpg
                      - type: hd_pore
                        region: nose
                        raw_score: 45.7
                        ui_score: 46
                        mask_urls:
                          - >-
                            https://s3-us-west-2.amazonaws.com/yce-us/results/hd_pore_nose.jpg
                      - type: hd_pore
                        region: cheek
                        raw_score: 32.1
                        ui_score: 32
                        mask_urls:
                          - >-
                            https://s3-us-west-2.amazonaws.com/yce-us/results/hd_pore_cheek.jpg
                      - type: hd_acne
                        region: whole
                        raw_score: 12.5
                        ui_score: 13
                        mask_urls:
                          - >-
                            https://s3-us-west-2.amazonaws.com/yce-us/results/hd_acne_whole.jpg
                      - type: skin_age
                        score: 29
                      - type: all
                        score: 28.5
                      - type: resize_image
                        mask_urls:
                          - >-
                            https://s3-us-west-2.amazonaws.com/yce-us/results/resized_image.jpg
