openapi: 3.0.0
info:
  title: AI Studio Generator
  description: "# Overview\nEmbrace the excellence of studio kike AI Portrait Generator. Transform your selfie into a studio-quality portrait in a flash​.\n* Studio-Free Convenience: No need for a photographer or studio visits—create studio-quality artistic photos anytime, anywhere​\n* Quick Photo Transformation: Fast processing for instant high-quality artistic photo results, ideal for quick updates\n* High-Quality Artistic Output: Delivers professional-standard artistic photos with clear details, perfect lighting, just like you've taken the photos in a studio \n\nUse cases:\n![AI Studio Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_studio_S1_img_19b627b6af.jpg \"AI Studio Generator\")\n\n![AI Studio Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_studio_S2_img_01_2e318817e9.jpg \"AI Studio Generator\")\n\n\nSuggestions for How to Shoot:\n![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png \"Suggestions for How to Shoot\")\n\n\n---\n\n## File Specs & Errors\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n|  ----  | ----  | ----  | ----  |\n|AI Studio|Please ensure the input image has one face, a short side of at least 200 pixels, and a long side no greater than 1920 pixels; the engine will select the largest face if multiple are present, and the output resolution will not exceed 960×1280 (W×H)|< 10MB|jpg/jpeg/png|\n\n* Error Codes\n\n|Error Code|Description|\n|  ----  | ----  |\n|error_below_min_image_size\t|Input image resolution is too small|\n|error_exceed_max_image_size\t|Input image resolution is too large|\n\n---\n\n## Unit Consumption\n\n| AI Feature | Unit Consumed |\n|---|---|\n| AI Studio Generator V3.0 | 1 unit for 2 images * |\n\n    > *If the number of images or video duration isn’t evenly divisible, units round up.\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: V3.0
    description: >-
      AI Studio Generator API allows you to generate studio-style images from a
      source image using predefined templates and output count settings.
paths:
  /s2s/v2.0/task/template/ai-studio:
    get:
      summary: List predefined templates.
      tags:
        - V3.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':
          description: Successful retrieval of styles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateResponseSchema'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidParametersSchema'
        '401':
          description: Invalid API Key or Inactive API Key or Expired API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidApiKeySchema'
  /s2s/v2.0/task/ai-studio:
    post:
      summary: Run an AI Studio task.
      description: >-
        Please refer to the polling guide for checking task status. Requires a
        source image, template ID, and output count configuration.
      tags:
        - V3.0
      security:
        - BearerAuthenticationV2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/RunWithSingleTemplateAndSrcUrl'
                - $ref: '#/components/schemas/RunWithOutputCntCustom200'
      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/RunErrorSchema'
        '401':
          description: Invalid API Key or Inactive API Key or Expired API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidApiKeySchema'
        '429':
          description: Too many requests within a given amount of time
          content:
            application/json:
              schema:
                type: object
  /s2s/v2.0/task/ai-studio/{task_id}:
    get:
      summary: Check the status of the AI Studio task.
      tags:
        - V3.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/TaskStatusResponseMultiResV2'
        '400':
          description: Invalid task id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidTaskIdSchema'
        '401':
          description: Invalid API Key or Inactive API Key or Expired API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidApiKeySchema'
        '500':
          description: The task has no response in the expected time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskTimeoutSchema'
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.
    TemplateResponseSchema:
      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:
      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=
    BasicRunTaskV2:
      title: BasicRunTaskV2
      anyOf:
        - $ref: '#/components/schemas/BasicRunTaskV2SrcFileUrl'
        - $ref: '#/components/schemas/BasicRunTaskV2SrcFileId'
    RunWithOutputCntCustom200:
      type: object
      required:
        - output_count
      properties:
        output_count:
          type: integer
          minimum: 1
          maximum: 200
          description: The number of generated images. It must be between 1 to 200.
          example: 20
    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
    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
    TaskStatusResponseBodyMultiUrlResultsV2:
      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
    TaskStatusResponseMultiResV2:
      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:
              $ref: '#/components/schemas/TaskStatusResponseBodyMultiUrlResultsV2'
    InvalidParametersSchema:
      type: object
      properties:
        status:
          type: integer
          example: 400
          description: Response status
        error:
          type: string
          description: Error message
          example: The operation could not be completed
        error_code:
          type: string
          enum:
            - InvalidParameters
          description: |
            Error code:
              * InvalidParameters - Invalid request parameters or body
    InvalidApiKeySchema:
      type: object
      properties:
        status:
          type: integer
          example: 401
          description: Response status
        error_code:
          type: string
          enum:
            - InvalidApiKey
            - InactiveApiKey
            - ExpiredApiKey
          description: |
            Error code:
              * InvalidApiKey - API Key is not given or not valid
              * InactiveApiKey - API Key is inactivated
              * ExpiredApiKey - API Key is expired
    RunErrorSchema:
      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:
            - CreditInsufficiency
            - InvalidStyleGroup
            - InvalidStyle
            - BadRequest
            - InvalidParameters
          description: |
            Error code:
              * CreditInsufficiency - Insufficient unit to run
              * BadRequest - Unexpected request parameter
              * InvalidStyleGroup - Invalid style group id
              * InvalidStyle - Invalid style id
              * InvalidParameters - Invalid request parameters
    InvalidTaskIdSchema:
      type: object
      properties:
        status:
          type: integer
          description: Response status
          example: 400
        error_code:
          type: string
          enum:
            - InvalidTaskId
          description: |
            Error code:
              * InvalidTaskId - Invalid task id
    TaskTimeoutSchema:
      type: object
      properties:
        status:
          type: integer
          description: Response status
          example: 500
        error_code:
          type: string
          enum:
            - TaskTimeout
          description: |
            Error code:
              * TaskTimeout - The task has no response in the expected time
  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'.
