openapi: 3.0.0
info:
  title: AI Teeth Whitening
  description: >
    # Overview

    **AI Teeth Whitening API**


    The AI Teeth Whitening API provides an advanced, automated solution for
    enhancing smiles in photos. Using intelligent image processing, it brightens
    teeth naturally and accurately, creating polished, professional results
    within seconds.


    ![](https://plugins-media.makeupar.com/smb/blog/post/2023-07-28/f05fda4d-8ca8-4661-b4b5-135067280a10.jpg)





    **How It Removes Yellow Teeth in Photos**


    **Smart Whitening**  

    The API automatically detects teeth and applies a natural-looking whitening
    effect without making the image appear artificial.


    **Adjustable Levels**  

    A built-in adjustment feature allows users to control the degree of
    whitening, from a subtle enhancement to a more pronounced, camera-ready
    finish.




    **Key Features**


    **Quick and Easy Enhancement**  

    Achieve a noticeably brighter smile in just a few seconds.


    **Accurate AI Detection**  

    Advanced detection ensures that only teeth are modified, maintaining a
    realistic and balanced appearance.


    **Adjustable Whitening Intensity**  

    Users can fine-tune the whitening strength to match their preferred style.


    **Natural Results with Advanced Algorithms**


    The AI Teeth Whitening API uses sophisticated algorithms designed to
    identify teeth precisely and apply whitening effects that remain true to
    life. Users can refine the intensity to achieve a subtle, natural
    improvement, ensuring that the final result looks authentic and visually
    appealing.


    ---


    ## Integration Guide


    * Take a Selfie

        *   Face the camera directly with proper lighting.
        *   Use the JS Camera Kit to capture the photo.

    * Retrieve upload URLs and File IDs via ***/s2s/v2.0/file*** API

        Upload the following files using the upload URLs returned in the file API response:
        *   Your selfie photo

    * Execute AI Task ***/s2s/v2.0/task/teeth-whiten***

        Run the AI task using file IDs or image URLs as the input source. Configure the effect parameters as desired.

    * Poll Task Status

        Use the returned **task\_id** to monitor task progress.  
        Poll **GET /s2s/v2.0/task/teeth-whiten/{task_id}** to check the engine's status.  
        The task will remain in a **“running”** state until it is completed. No units are consumed while the task is running.



    * **Usage demonstration**


    ![](https://plugins-media.makeupar.com/smb/blog/post/2022-05-13/26c04462-d183-4392-937b-f6173ff9e814.jpg)


    ![](https://plugins-media.makeupar.com/smb/blog/post/2025-07-01/webp_a4cd3779-2966-4b8f-888e-032dffc003c0.webp)


    ![](https://plugins-media.makeupar.com/smb/blog/post/2025-11-13/webp_5824c85f-813e-4c14-b036-38cba206ee0b.webp)


    ## File Specs & Errors

    * Supported Formats & Dimensions


    |Type|Supported Dimensions|Supported File Size|Supported Formats|

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

    |AI Teeth Whitening|Selfie Image:<br>    *   Long side ≤ 1920 px <br>    *  
    Short side ≥ 320 px |< 10MB|jpg/png|



    * Error Codes


    |Error Code|Description|

    |  ----  | ----  |

    | error_exceed_max_image_size | If the longer side of an image exceeds 1920
    pixels |

    |error_below_min_image_size|If your image is smaller than 320 pixels in
    width or height, it's too small to use|

    |error_face_position_invalid|Your face needs to be fully visible in the
    image, without any parts cut off|

    |error_face_position_too_small|The face in your photo is too small to
    analyze properly|

    |error_face_position_out_of_boundary|Your face is either too large or
    partially outside the edges of the photo|

    |error_insufficient_lighting|The lighting is too dim, which makes analysis
    difficult|

    |error_face_angle_invalid|Your face angle isn't quite right. For
    front-facing shots, keep your head within 10 degrees of straight. For
    side-facing shots, the angle should be more than 15 degrees|


    * 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 |


    ---


    ## Unit Consumption


    | AI Feature | Unit Consumed |

    |---|---|

    | AI Teeth Whitening 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: Whitening teeth in photos using AI technology.
paths:
  /s2s/v2.0/task/teeth-whiten/pre-process:
    post:
      summary: Run an AI Teeth Whiten detection task.
      description: >
        Use the pre-process task when the source image may contain more than one
        valid target, or when your integration needs to explicitly choose which
        detected target receives the effect. For single-target images,
        pre-process can be skipped when the feature supports a default `index`
        value and your application does not need manual target selection.


        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/teeth-whiten/pre-process/{task_id}:
    get:
      summary: Check the status of a AI Teeth Whiten 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:
                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
        '400':
          $ref: '#/components/responses/InvalidTaskId'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '500':
          $ref: '#/components/responses/TaskTimeout'
  /s2s/v2.0/task/teeth-whiten:
    post:
      summary: Run an AI Teeth Whiten task.
      description: >
        AI tasks are asynchronous. Prefer webhook-based completion handling when
        the feature supports webhooks. Configure your webhook endpoint, verify
        webhook signatures, and use the received `task_id` to query the task
        result after a `success` or `error` notification. See the [webhook
        integration guide](/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:
              allOf:
                - $ref: '#/components/schemas/BasicRunTaskV2'
                - type: object
                  required:
                    - version
                    - effect
                  properties:
                    version:
                      type: string
                      enum:
                        - '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.
                    effect:
                      type: object
                      required:
                        - whitening_intensity
                      properties:
                        whitening_intensity:
                          type: integer
                          maximum: 100
                          minimum: 0
                        skin_smooth_strength:
                          type: integer
                          minimum: 0
                          maximum: 100
                          default: 50
                        skin_smooth_color_intensity:
                          type: integer
                          minimum: 0
                          maximum: 100
                          default: 50
      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/teeth-whiten/{task_id}:
    get:
      summary: Check the status of a AI Teeth Whiten 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:
                allOf:
                  - $ref: '#/components/schemas/TaskStatusResponseV2'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          results:
                            type: object
                            properties:
                              timed:
                                type: number
                              timed_apply:
                                type: number
        '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:
    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
    TaskStatusResponseBodySingleUrlResultsV2:
      type: object
      properties:
        url:
          type: string
          description: URL to download this result. Valid for 2 hours
          example: https://example.com/sample-result-url
    TaskStatusResponseV2:
      type: object
      properties:
        status:
          type: integer
          description: Response status
          example: 200
        data:
          type: object
          properties:
            task_status:
              type: string
              enum:
                - running
                - success
                - error
              description: Status of this task
            error:
              $ref: '#/components/schemas/EngineErrorCode'
            error_message:
              type: string
              description: Detailed description of error
            results: null
      $ref: '#/components/schemas/TaskStatusResponseBodySingleUrlResultsV2'
  responses:
    InvalidApiKey:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 401
                description: Response status
              error:
                type: string
                example: Invalid API key
    TooManyRequests:
      description: Too many requests
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 429
                description: Response status
              error:
                type: string
                example: Too many requests
    InvalidTaskId:
      description: Invalid task ID
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 400
                description: Response status
              error:
                type: string
                example: Invalid task ID
    TaskTimeout:
      description: Task execution timeout
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 500
                description: Response status
              error:
                type: string
                example: Task execution timed out
