openapi: 3.0.0
info:
  title: AI Face Lift
  description: >
    # Overview

    AI Face Lift is a generative AI facial enhancement feature that allows
    precise and natural facial refinement through adjustable parameters. Instead
    of applying filters, the system intelligently analyzes facial structure,
    skin quality, and proportions, then reconstructs the image to produce
    realistic improvements that preserve the individual's identity.


    Users can control specific facial areas such as eye bags, cheeks, forehead,
    overall face shape, and mouth using numeric values from 0 to 100. Each
    parameter increases the level of enhancement gradually, allowing subtle
    touch ups or more polished results depending on user preference. All
    adjustments are designed to remain natural and balanced, avoiding
    exaggerated or artificial outcomes.


    AI Face Lift provides flexible, feature level control for creating a
    refreshed, confident, and professional appearance suitable for social media,
    profile photos, creative content, or business use.



    ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/01_1_6c0d97eb51.jpg)


    ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/01_2_8c428a25dc.jpg)



    ## Integration Guide

    This guide walks you through:


    Workflow for AI Face Lift API:


    **Endpoint:** `/s2s/v2.0/task/face-lift`


    **Authentication Required:** `Authorization: Bearer YOUR_API_KEY`


    **Workflow Steps:**


    1. **Image Upload Preparation:**
      - Prepare a selfie image for upload.
      - Call the File API `/s2s/v2.0/file` to obtain the upload URL and associated `file_id`.
      - Upload the selfie image using the provided upload URL.

    2. **Optional Preprocessing For Multiple Faces:**
        - Preprocess the selfie image if there are more than one face in the image.

    3. **Face Lift Effect Setup:**
       - Begin by selecting suitable face lift parameters.

    4. **Initiate AI Task and Obtain Task ID:**
       - Send the `file_id` along with the chosen effect configuration via an HTTP POST request to `/s2s/v2.0/task/face-lift`.
       - Await a unique task ID in the response, which identifies this interaction.

    5. **Poll Task Status (Continuous Check):**
       - Use the obtained `task_id` to periodically poll the task status using an HTTP GET request (e.g., `GET /s2s/v2.0/task/face-lift${task_id}`).
       - Continuously monitor for:
         - `Task_status = "success"` (process completed).
         - `Task_status = "error"` (resolve or retry if applicable).
       - Update the workflow accordingly once the status transitions to success.

    This structured workflow ensures efficient integration with user inputs,
    automated monitoring of tasks, and seamless retrieval of results.



    ---


    1.  Authentication
        - Include your API key in the request header using **Bearer Token**:
            ```
            Authorization: Bearer YOUR_API_KEY
            ```
        You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.


    2.  Upload an Image

        You may upload a file directly to the server or provide a valid image URL in the AI task payload.

        * Upload Endpoint

            ```
            POST /s2s/v2.0/file
            ```

        Alternatively, skip this step if you already have a public image URL.

    ---


    3. Select the target face to be enhanced by preprocessing

       * Calling the preprocessing API
        Output detected bounding boxes in pixel coordinate. Use the index of result to create a Face Lift AI task later.
            ```
            POST /s2s/v2.0/task/face-lift/pre-process
            ```

            ```
            {
                "timed": number,
                "result": [
                    {
                        "left": number,
                        "top": number,
                        "width": number,
                        "height": number
                    }
                ]
            }
            ```

    4. Create a Face Lift AI Task and Poll for Results

        Once you have an image and a complete effect payload, create a task. The API processes the request asynchronously. You must poll the task status until it reaches `success` or `error`.

       * Create Task Endpoint

            ```
            POST /s2s/v2.0/task/face-lift
            ```

       * Polling Endpoint

            ```
            GET /s2s/v2.0/task/face-lift/{task_id}
            ```

    ---


    ## File Specs & Errors


    * AI Face Lift Specification


    **Supported Selfie View**

    Images must be no larger than 1920 x 1920, contain a clearly visible face of
    sufficient size exceeding 32 x 32 pixels when the long edge is 640, and be
    captured with a roll angle within plus or minus 75 degrees and a yaw angle
    within plus or minus 90 degrees to ensure reliable face detection.


    ![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_face_reshape_01_85c8ffc055.jpg)



    ---


    * Supported Formats & Dimensions


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

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

    | AI Face Lift | long side <= 1920 | < 10MB | jpg/jpeg/png |


    * Error Codes


    | Error Code | Description |

    |  ----  | ----  |

    | RUNTIME_ERROR | An unexpected error occurred duface lift runtime |

    | PHOTO_DETECTION_FAIL | The user photo could not be processed correctly,
    for example no hand detected |

    | OBJECT_DETECTION_FAIL | The object photo could not be processed correctly,
    for example no product detected |

    | PHOTO_CHECK_INVALID | The pose or size of the user photo is invalid |

    | INPUT_ERROR | The input file format is incorrect |

    | INPUT_MAIN_IMAGE_EMPTY | A user image is required |



    * 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

    {% partial file="/_partials/js-camera-kit.md" /%}


    ---


    ## Unit Consumption


    | AI Feature | Unit Consumed |

    |---|---|

    | AI Face Lift V1.0 | 1 |


    ---
  version: ''
  termsOfService: https://www.makeupar.com/perfectbeauty/youcam/terms-of-service-api
  contact:
    email: YouCamOnlineEditor_API@perfectcorp.com
  license:
    name: Privacy policy
    url: https://www.makeupar.com/perfectbeauty/youcam/privacy-policy-api
servers:
  - url: https://yce-api-01.makeupar.com
tags:
  - name: V1.0
    description: >-
      AI Face Lift is a generative AI facial enhancement feature that allows
      precise and natural facial refinement through adjustable parameters.
paths:
  /s2s/v2.0/task/face-lift/pre-process:
    post:
      summary: Run an AI Face Lift detection task.
      description: >
        Use the pre-process task when the source image may contain more than one
        valid target, or when your integration needs to explicitly choose which
        detected target receives the effect. For single-target images,
        pre-process can be skipped when the feature supports a default `index`
        value and your application does not need manual target selection.


        The pre-process task detects candidate targets in the source image and
        returns their coordinates in `data.results.result`. Each item in the
        result array represents one detected target. Review the returned
        coordinates, map them to the intended face or region in the source
        image, and use that item's zero-based array index as the `index` value
        when creating the effect task.


        For images with multiple detected faces or regions, do not rely on the
        default `index` value without checking the pre-process result. The
        effect is applied only to the target selected by `index`, so the
        integration must confirm the result item that corresponds to the
        intended target before running the effect task.


        This task is asynchronous. After creating the task, handle completion
        with webhook if the feature supports it, or poll the corresponding
        pre-process status endpoint until `data.task_status` is `success` or
        `error`.
      tags:
        - V1.0
      security:
        - BearerAuthenticationV2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/BasicRunTaskV2'
      responses:
        '200':
          description: Successful execution of the task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicRunTaskResponseV2'
        '400':
          description: Failed execution of task
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/RunError'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /s2s/v2.0/task/face-lift/pre-process/{task_id}:
    get:
      summary: Check the status of an AI Face Lift detection 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/TaskStatusResponsePreProcessSingleIndexWithTimed
        '400':
          $ref: '#/components/responses/InvalidTaskId'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '500':
          $ref: '#/components/responses/TaskTimeout'
  /s2s/v2.0/task/face-lift:
    post:
      summary: Run an AI Face Lift task.
      description: >
        AI tasks are asynchronous. Prefer webhook-based completion handling when
        the feature supports webhooks. Configure your webhook endpoint, verify
        webhook signatures, and use the received `task_id` to query the task
        result after a `success` or `error` notification. See the [webhook
        integration guide](/develop/webhook.md) for setup and verification
        details.


        If webhooks are not supported for the feature, or if your integration
        cannot use webhooks, implement polling. After starting an AI task, keep
        polling the task status endpoint at the given `polling_interval` until
        the task status is either `success` or `error`.


        Do not stop polling a running task for longer than the allowed polling
        window. If the task is not polled in time, the task may expire; a later
        status check can return `InvalidTaskId` even if processing finished, and
        the consumed units may still be charged.
      tags:
        - V1.0
      security:
        - BearerAuthenticationV2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FaceLiftRunTask'
      responses:
        '200':
          description: Successful execution of the task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicRunTaskResponseV2'
        '400':
          description: Failed execution of task
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/RunError'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /s2s/v2.0/task/face-lift/{task_id}:
    get:
      summary: Check the status of a AI Face Lift 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/TaskStatusResponseV2WithTimedAndTimedApply
        '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:
    FaceLiftRunTask:
      allOf:
        - anyOf:
            - allOf:
                - title: Run task with src_file_url & 'auto' type
                - $ref: '#/components/schemas/BasicRunTaskV2SrcFileUrl'
                - required:
                    - src_file_url
                  properties:
                    type:
                      type: string
                      enum:
                        - auto
            - allOf:
                - title: Run task with src_file_url & 'custom' type
                - $ref: '#/components/schemas/BasicRunTaskV2SrcFileUrl'
                - required:
                    - src_file_url
                    - features
                  properties:
                    type:
                      type: string
                      enum:
                        - custom
                    features:
                      minProperties: 1
                - title: Features cannot be all zero
                  not:
                    properties:
                      features:
                        properties:
                          eye_bag:
                            enum:
                              - 0
                          cheek:
                            enum:
                              - 0
                          forehead:
                            enum:
                              - 0
                          shape:
                            enum:
                              - 0
                          mouth:
                            enum:
                              - 0
            - allOf:
                - title: Run task with src_file_id & 'auto' type
                - $ref: '#/components/schemas/BasicRunTaskV2SrcFileId'
                - required:
                    - src_file_id
                  properties:
                    type:
                      type: string
                      enum:
                        - auto
                    features:
                      minProperties: 1
            - allOf:
                - title: Run task with src_file_id & 'custom' type
                - $ref: '#/components/schemas/BasicRunTaskV2SrcFileId'
                - required:
                    - src_file_id
                    - features
                  properties:
                    type:
                      type: string
                      enum:
                        - custom
                - title: Features cannot be all zero
                  not:
                    properties:
                      features:
                        properties:
                          eye_bag:
                            enum:
                              - 0
                          cheek:
                            enum:
                              - 0
                          forehead:
                            enum:
                              - 0
                          shape:
                            enum:
                              - 0
                          mouth:
                            enum:
                              - 0
        - type: object
          required:
            - version
          properties:
            version:
              type: string
              description: >
                Version of the features specification. Defaults to `"1.0"`
                unless otherwise specified.
              default: '1.0'
              example: '1.0'
            index:
              type: integer
              example: 0
              default: 0
              description: >-
                Zero-based index of the target object to apply the effect to.
                For multi-objects images, run the pre-process task first,
                inspect the object coordinates in `data.results.result`, and
                pass the index of the selected object here.


                The pre-processing step analyzes the input image to identify all
                detectable objects before any effect is applied. It runs a
                detection task that returns structured data for each object,
                including a list of bounding box coordinates. The position of
                each entry in this list serves as its zero-based index, which is
                then used to specify the target object for the effect.


                This information is returned in a structured format, commonly
                under `data.results.result`.

                By running this step first, you can:
                    * Understand how many objects are present in the image
                    * Inspect their positions and sizes
                    * Select the correct target object by its index

                Always run the pre-processing step for images with multiple
                objects.

                Review `data.results.result` to identify objects and their
                indices.

                Use the corresponding zero-based index to select the correct
                target.
            type:
              type: string
              default: custom
            features:
              type: object
              additionalProperties: false
              description: Cannot be all zero when using 'custom' type.
              properties:
                eye_bag:
                  type: integer
                  default: 0
                  minimum: 0
                  maximum: 100
                cheek:
                  type: integer
                  default: 0
                  minimum: 0
                  maximum: 100
                forehead:
                  type: integer
                  default: 0
                  minimum: 0
                  maximum: 100
                shape:
                  type: integer
                  default: 0
                  minimum: 0
                  maximum: 100
                mouth:
                  type: integer
                  default: 0
                  minimum: 0
                  maximum: 100
            global:
              $ref: '#/components/schemas/GlobalSkinSmoothCommon'
    BasicRunTaskV2SrcFileUrl:
      type: object
      required:
        - src_file_url
      properties:
        src_file_url:
          type: string
          description: Url of the file to run task. The url should be publicly accessible.
          example: https://example.com/selfie.jpg
    BasicRunTaskV2SrcFileId:
      type: object
      required:
        - src_file_id
      properties:
        src_file_id:
          type: string
          description: ID of file to run task. File ID from upload file API.
          example: pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=
    BasicRunTaskV2:
      title: BasicRunTaskV2
      anyOf:
        - title: Run task with src file url
          allOf:
            - $ref: '#/components/schemas/BasicRunTaskV2SrcFileUrl'
        - title: Run task with src file ID
          allOf:
            - $ref: '#/components/schemas/BasicRunTaskV2SrcFileId'
    BasicRunTaskResponseV2:
      type: object
      properties:
        status:
          type: integer
          description: Response status
          example: 200
        data:
          type: object
          properties:
            task_id:
              type: string
              description: >-
                ID of this task. Task result is valid to query by this ID for 24
                hours.
              example: grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe
    RunError:
      type: object
      properties:
        status:
          type: integer
          description: Response status
          example: 400
        error:
          type: string
          description: Error message
          example: The operation could not be completed
        error_code:
          type: string
          enum:
            - InvalidParameters
            - CreditInsufficiency
            - InvalidStyleGroup
            - InvalidStyle
            - BadRequest
          description: |
            Error code:
              * InvalidParameters - Invalid request parameters
              * CreditInsufficiency - Insufficient unit to run
              * BadRequest - Unexpected request parameter
              * InvalidStyleGroup - Invalid style group id
              * InvalidStyle - Invalid style id
    EngineErrorCode:
      type: string
      nullable: true
      enum:
        - error_exceed_max_image_size
        - exceed_max_filesize
        - invalid_parameter
        - error_download_image
        - error_download_mask
        - error_decode_image
        - error_decode_mask
        - error_nsfw_content_detected
        - error_no_face
        - error_pose
        - error_face_parsing
        - error_inference
        - exceed_nsfw_retry_limits
        - error_upload
        - unknown_internal_error
      description: >
        Errors:

        - \`error_exceed_max_image_size\`  - Input image size exceeds the
        maximum limit

        - \`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
    TaskStatusResponsePreProcessNoUrlBase:
      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
    TaskStatusResponsePreProcessSingleIndexWithTimed:
      allOf:
        - $ref: '#/components/schemas/TaskStatusResponsePreProcessNoUrlBase'
        - type: object
          properties:
            data:
              type: object
              properties:
                results:
                  type: object
                  properties:
                    timed:
                      type: number
                    result:
                      type: array
                      items:
                        type: object
                        properties:
                          left:
                            type: number
                          top:
                            type: number
                          width:
                            type: number
                          height:
                            type: number
    GlobalSkinSmoothCommon:
      type: object
      properties:
        skin_smooth_strength:
          type: integer
          minimum: 0
          maximum: 100
          default: 0
        skin_smooth_color_intensity:
          type: integer
          minimum: 0
          maximum: 100
          default: 0
    TaskStatusResponseBodySingleUrlResultsV2:
      type: object
      properties:
        url:
          type: string
          description: URL to download this result. Valid for 2 hours
          example: https://example.com/sample-result-url
    TaskStatusResponseV2:
      type: object
      properties:
        status:
          type: integer
          description: Response status
          example: 200
        data:
          type: object
          properties:
            task_status:
              type: string
              enum:
                - running
                - success
                - error
              description: Status of this task
            error:
              $ref: '#/components/schemas/EngineErrorCode'
            error_message:
              type: string
              description: Detailed description of error
            results: null
      $ref: '#/components/schemas/TaskStatusResponseBodySingleUrlResultsV2'
    TaskStatusResponseV2WithTimedAndTimedApply:
      allOf:
        - $ref: '#/components/schemas/TaskStatusResponseV2'
        - type: object
          properties:
            data:
              type: object
              properties:
                results:
                  type: object
                  properties:
                    timed:
                      type: number
                    timed_apply:
                      type: number
                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
  responses:
    InvalidApiKey:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 401
                description: Response status
              error:
                type: string
                example: Invalid API key
    TooManyRequests:
      description: Too many requests
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 429
                description: Response status
              error:
                type: string
                example: Too many requests
    InvalidTaskId:
      description: Invalid task ID
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 400
                description: Response status
              error:
                type: string
                example: Invalid task ID
    TaskTimeout:
      description: Task execution timeout
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 500
                description: Response status
              error:
                type: string
                example: Task execution timed out
