openapi: 3.0.0
info:
  title: AI Beard Style Generator
  description: "# Overview\nAI Simulation for Men's Beard Styles\n\nThe AI algorithm also empowers men to have the complete freedom to virtualy try different beard styles with the highly sophisticated beard simulation technology, including trim beard, stubble beard, full beard, circle beard, mustache, goatee, and others.\n\nShoppers can also see before and after results, without the commitment of putting a razor to the skin.\nThe beard filters include mustache, short box, ducktail, circle and a dozen more.\n\n## Integration Guide\n\n1. **Upload a Selfie**\n  You can provide the source image in one of two ways:\n\n  - **Use an Existing Public Image URL**\n    Instead of uploading, you may supply a publicly accessible image URL directly when initiating the AI task.\n\n  - **Upload via File API**\n    Use the endpoint:\n    ```\n    POST /s2s/v2.0/file\n    ```\n    This returns a `file_id` for subsequent task execution.\n\n    - ***Important***: Simply calling the File API does not upload your file. You must **manually upload** the file to the **URL provided in the File API response**. That URL is your upload destination, make sure the file is successfully transferred there before proceeding.<br></br>\n    Before calling the AI API, ensure your file has been successfully uploaded. Use the File API to retrieve an upload URL, then upload your file to that location. Once the upload is complete, you'll receive a ***file_id*** in the response, this ID is what you'll use to access AI features related to that file.\n\n      > **Warning:** Please note that, you will get an 500 Server Error / unknown_internal_error or 404 Not Found error when using AI APIs if you do not upload the file to the URL provided in the File API response.\n\n2.  **List Predefined Styles**\n    *   Use /s2s/v2.0/task/template/beard-style to fetch a predefined template list and select a ``template_id`` to run an AI task.\n\n3.  **Run an AI Task to Obtain a Task ID**\n    Execute the AI task using /s2s/v2.0/task/beard-style. For the target user image, provide either ``src_file_url`` or ``src_file_id``. And a stype ``template_id`` to apply and obtain a ``task_id``.\n\n4.  **Poll to Check the Status of a Task Until It Succeeds or Fails**\n    Use the ``task_id`` to monitor the task status by polling GET /s2s/v2.0/task/beard-style to retrieve the current engine status. Until the engine completes the task, the status will remain as running, and no units will be consumed during this stage.\n    You can also implement a webhook to receive notifications when an AI task succeeds or fails. Refer to the **[Webhook](../../../develop/webhook)** section for details.\n\n    > **Warning:** Polling to check the status of a task within its retention period is mandatory. A task will time out if there is no polling request within the retention period, even if the task is processed successfully. Your units will still be consumed.\n\n    > **Warning:** You will receive an InvalidTaskId error if you check the status of a timed-out task. Therefore, once you run an AI task, you must poll to check the status within the retention period until the status becomes either success or error.\n\n5.  **Retrieve the Result of an AI Task Once Successful**\n    The task status will change to success after the engine processes your input file and generates the resulting image. You will receive a URL for the processed image.\n\n---\n\n## File Specs & Errors\n   * Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n|  ----  | ----  | ----  | ----  |\n|AI Beardstyle Generator|Resolution: Long side < 1024 <br>face width > 256 <br>face pose: -30 < yaw < 30, <br>single face only, <br>need to show full face|< 10MB|jpg/jpeg|\n\n   * Error Codes\n\n|Error Code|Description|\n|  ----  | ----  |\n|error_no_face\t|Face are not visible in the source image\n|error_src_face_too_small\t|The face is too small\n|error_inference\t|Beard removal error or beard generation error\n|error_face_pose\t|The face pose of source image is unsupported\n\n   * Environment & Dependency\n\n| Sample Code Language / Tool | Recommended Runtime Versions |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) or allow_url_fopen=On + ext-openssl, ext-json |\n| Python | Python >= 3.10 (for f-strings), requests >= 2.20.0 |\n| Java | Java 11+ (for HttpClient), Jackson Databind >= 2.12.0 |\n\n---\n"
  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 Beard Style Generator API allows you to apply beard styles to images
      using predefined templates and source images.
paths:
  /s2s/v2.0/task/template/beard-style:
    get:
      summary: List predefined templates.
      tags:
        - V1.0
      security:
        - BearerAuthenticationV2: []
      parameters:
        - name: page_size
          in: query
          schema:
            type: integer
            example: 20
          description: >-
            Number of results to return in this page. Valid value should be
            between 1 and 20. Default 20.
        - name: starting_token
          in: query
          schema:
            type: string
            example: 73a3c9e69b89
          description: >-
            Token for current page. Start with `null` for the first page, and
            use `next_token` from the previous response to start next page
      responses:
        '200':
          $ref: '#/components/schemas/TemplateResponse'
        '400':
          $ref: '#/components/responses/InvalidParameters'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
  /s2s/v2.0/task/beard-style:
    post:
      summary: Run an AI Beard Style Generator 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/RunWithSingleTemplateAndSrcUrl'
      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/beard-style/{task_id}:
    get:
      summary: Check the status of a AI Beard Style Generator task.
      tags:
        - V1.0
      security:
        - BearerAuthenticationV2: []
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
            example: grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe
          description: ID of task to check
      responses:
        '200':
          description: Successful check of the task status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStatusResponseV2'
        '400':
          $ref: '#/components/responses/InvalidTaskId'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '500':
          $ref: '#/components/responses/TaskTimeout'
components:
  schemas:
    Template:
      type: object
      properties:
        id:
          type: string
          description: The ID of the template. Use this as `template_id` when run task.
          example: good_template_001
        thumb:
          type: string
          description: The thumbnail of style.
        title:
          type: string
          description: The title of the template.
        category_name:
          type: string
          description: The category name of the template.
    TemplateResponse:
      type: object
      properties:
        status:
          type: integer
          description: Response status
          example: 200
        data:
          type: object
          properties:
            templates:
              type: array
              items:
                $ref: '#/components/schemas/Template'
            next_token:
              type: string
              example: 73a3c9e69b89
              description: Token to query next page.
    RunWithSingleTemplateAndSrcUrl:
      title: RunWithSingleTemplateAndSrcUrl
      allOf:
        - $ref: '#/components/schemas/RunWithSingleTemplate'
        - $ref: '#/components/schemas/BasicRunTaskV2'
    RunWithSingleTemplate:
      title: RunWithSingleTemplate
      type: object
      properties:
        template_id:
          type: string
          description: >-
            ID of the template. List predefined templates first, and use the id
            of a template.
          example: good_template_001
      required:
        - template_id
    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
    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'
  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'.
  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: 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
