openapi: 3.0.0
info:
  title: AI Aging Simulation
  description: >
    # Overview

    AI aging generator utilizing generative AI model to generate a series of
    photos from youth to age from a single selfie image. With the help of AI
    technology, not only can it measure your current age, but it also lets you
    see yourself in the future or the past.


    ![AI Aging
    Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/f42f1504_79e3_461c_a3f1_a254623d113b_b068736afb.jpg
    "AI Aging Generator")


    The AI aging generator can generate a series of photos based on one single
    input selfie image. A sample generated photos are shown below as a quick
    reference of this feature.

    ![AI Aging
    Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/U_2024_04_17_cr_12112b83e2.png
    "AI Aging Generator")



    ## File Specs & Errors

    * Supported Formats & Dimensions


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

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

    | AI Aging | long side <= 4096, single person only. Face pose constraints:
    yaw within ±30°, roll within ±20°, and pitch within ±20°. | < 10MB |
    jpg/jpeg |


    * Error Codes


    |Error Code|Description|

    |  ----  | ----  |

    | error_below_min_image_size | Source image dimensions must be at least 320
    pixels. |

    | error_face_position_invalid | Face must be fully visible, forward-facing,
    and centered in the image. |

    | error_face_position_too_small | Detected face is too small for analysis. |

    | error_face_position_out_of_boundary | Face extends beyond image
    boundaries. |

    | error_face_not_forward_facing | Face must be directly facing the camera. |

    | error_face_angle_upward | Face is angled too far upward—slightly tilt head
    down. |

    | error_face_angle_downward | Face is angled too far downward — slightly
    tilt head up. |

    | error_face_angle_leftward | Face is turned too far left — slightly rotate
    head right. |

    | error_face_angle_rightward | Face is turned too far right — slightly
    rotate head left. |

    | error_face_angle_left_tilt | Face is tilted too far left — gently tilt
    head right. |

    | error_face_angle_right_tilt | Face is tilted too far right — gently tilt
    head left. |


    ---


    ## Unit Consumption


    | AI Feature | Unit Consumed |

    |---|---|

    | AI Aging Simulation V1.0 | 2 |


    ---
  version: ''
  termsOfService: https://www.makeupar.com/perfectbeauty/youcam/terms-of-service-api
  contact:
    email: YouCamOnlineEditor_API@perfectcorp.com
  license:
    name: Privacy policy
    url: https://www.makeupar.com/perfectbeauty/youcam/privacy-policy-api
servers:
  - url: https://yce-api-01.makeupar.com
paths:
  /s2s/v2.0/task/aging:
    post:
      summary: Run a AI Aging Generator task.
      description: >
        This endpoint initiates the aging generation process. You must provide a
        source file (via URL or File ID). The task will be processed
        asynchronously, and you can check its status using the task_id returned
        in this response.
      tags:
        - V1.0
      security:
        - BearerAuthenticationV2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/BasicRunTaskV2'
      responses:
        '200':
          description: Successful execution of the AI Aging Simulation 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/aging/{task_id}:
    get:
      summary: Check the status of a AI Aging 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/AgingResponseV2'
        '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:
    AgingResponseV2:
      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:
              type: object
              properties:
                output:
                  type: array
                  items:
                    type: object
                    properties:
                      url:
                        type: string
                        description: URL to download this result. Valid for 2 hours
                        example: https://example.com/sample-result-url
                      res_age:
                        type: integer
                        description: |
                          Age of the result that the AI engine attempts to
                          generate. Please note that the 'res_age' of the
                          uploaded file may not correspond to the 'age' in the
                          results.
                        example: 12
                age:
                  type: integer
                  description: |
                    Estimation of the age of the uploaded file by AI engine.
                    Please be aware that the 'res_age' of the uploaded file, as
                    found in the 'output' section, may not align with this 'age'
                    value.
                  example: 21
                agd_idx:
                  type: integer
                  description: |
                    Index of the uploaded file in the 'output'. Index is
                    starting from 0. The first file has index 0, the second file
                    has index 1, and so on.
                  example: 2
                age_min:
                  type: integer
                  description: Minimum age among files in 'output'
                  example: 12
                age_max:
                  type: integer
                  description: Maximum age among files in 'output'
                  example: 70
                num_of_photos:
                  type: integer
                  description: Number of photos in 'output'
                  example: 16
    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
  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
