Perfect Corp V4.0 API

openapi: 3.2.0
info:
  title: Perfect Corp V4.0 API
  version: ''
  contact:
    email: YouCamOnlineEditor_API@perfectcorp.com
  license:
    name: Privacy policy
    url: https://www.makeupar.com/perfectbeauty/youcam/privacy-policy-api
  termsOfService: https://www.makeupar.com/perfectbeauty/youcam/terms-of-service-api
  description: 'Operations tagged V4.0 across 2 of this provider''s published API definitions: perfect-corp-ai_clothes-openapi.yml, perfect-corp-ai_object_removal_pro-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://yce-api-01.makeupar.com
tags:
- name: V4.0
  description: Enhanced capabilities to include virtual try-on for outerwear, including jackets and vests. You can now choose from Full Body, Upper Body, Lower Body, Shoes, or Outerwear for virtual try-on, or simply select Auto and let the AI engine create the perfect outfit for you.
paths:
  /s2s/v2.0/task/cloth-v4:
    post:
      summary: Run an AI Cloth V4 task
      x-display-name: AI Clothes Virtual Try-On
      x-engine-version: V4.0
      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 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:
      - V4.0
      security:
      - BearerAuthenticationV2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/RunClothV4Task'
      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'
      operationId: postS2sV20TaskClothV4
      x-operation-id-source: derived
    servers:
    - url: https://yce-api-01.makeupar.com
  /s2s/v2.0/task/cloth-v4/{task_id}:
    get:
      summary: Check the status of a AI Cloth V4 task
      x-display-name: AI Clothes Virtual Try-On
      x-engine-version: V4.0
      tags:
      - V4.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'
      operationId: getS2sV20TaskClothV4ByTaskId
      x-operation-id-source: derived
    servers:
    - url: https://yce-api-01.makeupar.com
  /s2s/v2.0/task/generative-fill:
    post:
      summary: Run an AI Object Removal Pro 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 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:
      - V4.0
      security:
      - BearerAuthenticationV2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/BasicRunTaskV2WithRequiredMsk'
      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'
      operationId: postS2sV20TaskGenerativeFill
      x-operation-id-source: derived
    servers:
    - url: https://yce-api-01.makeupar.com
  /s2s/v2.0/task/generative-fill/{task_id}:
    get:
      summary: Check an AI Object Removal Pro task status
      tags:
      - V4.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'
      operationId: getS2sV20TaskGenerativeFillByTaskId
      x-operation-id-source: derived
    servers:
    - url: https://yce-api-01.makeupar.com
components:
  schemas:
    BasicRunTaskV2RefFileId:
      type: object
      properties:
        ref_file_id:
          type: string
          description: ID of the reference file to run task. File ID from upload file API.
          example: pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=
    RunClothV4Task:
      allOf:
      - anyOf:
        - allOf:
          - title: Run task with src file url & ref file url
            required:
            - ref_file_url
          - $ref: '#/components/schemas/BasicRunTaskV2SrcFileUrl'
          - $ref: '#/components/schemas/BasicRunTaskV2RefFileUrl'
          - $ref: '#/components/schemas/RunClothsTaskV4GarmentCategory'
        - allOf:
          - title: Run task with src file url & ref file ID
            required:
            - ref_file_id
          - $ref: '#/components/schemas/BasicRunTaskV2SrcFileUrl'
          - $ref: '#/components/schemas/BasicRunTaskV2RefFileId'
          - $ref: '#/components/schemas/RunClothsTaskV4GarmentCategory'
        - allOf:
          - title: Run task with src file ID & ref file url
            required:
            - ref_file_url
          - $ref: '#/components/schemas/BasicRunTaskV2SrcFileId'
          - $ref: '#/components/schemas/BasicRunTaskV2RefFileUrl'
          - $ref: '#/components/schemas/RunClothsTaskV4GarmentCategory'
        - allOf:
          - title: Run task with src file ID & ref file ID
            required:
            - ref_file_id
          - $ref: '#/components/schemas/BasicRunTaskV2SrcFileId'
          - $ref: '#/components/schemas/BasicRunTaskV2RefFileId'
          - $ref: '#/components/schemas/RunClothsTaskV4GarmentCategory'
      - properties:
          change_shoes:
            type: boolean
            default: true
            description: 'Control whether shoes should be swapped when a full body reference image with shoes is available for processing.

              <br> Have effect when `garment_category` is `full_body` or `lower_body`

              '
    RunClothsTaskV4GarmentCategory:
      required:
      - garment_category
      properties:
        garment_category:
          type: string
          enum:
          - full_body
          - lower_body
          - upper_body
          - shoes
          - auto
          - outer
          description: The category of garment of reference image. It's required if reference image provided. Utilize the "auto" parameter to allow the AI engine to automatically identify and classify garment categories.
    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=
    TaskStatusResponseBodySingleUrlResultsV2:
      type: object
      properties:
        url:
          type: string
          description: URL to download this result. Valid for 2 hours
          example: https://example.com/sample-result-url
    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
    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:\n  * InvalidParameters - Invalid request parameters\n  * CreditInsufficiency - Insufficient unit to run\n  * BadRequest - Unexpected request parameter\n  * InvalidStyleGroup - Invalid style group id\n  * InvalidStyle - Invalid style id\n"
    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'
    BasicRunTaskV2RefFileUrl:
      type: object
      properties:
        ref_file_url:
          type: string
          description: Url of the reference file to run task. The url should be publicly accessible.
          example: https://example.com/accessory.jpg
    EngineErrorCode:
      type:
      - string
      - 'null'
      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

        '
    BasicRunTaskV2MskFileId:
      type: object
      properties:
        msk_file_id:
          type: string
          example: eA1CCL3kG4w2s0kpbo2pkah59VfxzIjxahJD2wWm7zw=
          description: ID of the mask file. This should be a grey scale mask image with the exact same width and height with the input image where white pixels indicate foreground and black pixels represent background. File ID from upload file API.
    BasicRunTaskV2WithRequiredMsk:
      title: BasicRunTaskV2WithRequiredMsk
      anyOf:
      - allOf:
        - title: Run task with src file url & msk file url
          required:
          - msk_file_url
        - $ref: '#/components/schemas/BasicRunTaskV2SrcFileUrl'
        - $ref: '#/components/schemas/BasicRunTaskV2MskFileUrl'
      - allOf:
        - title: Run task with src file url & msk file ID
          required:
          - msk_file_id
        - $ref: '#/components/schemas/BasicRunTaskV2SrcFileUrl'
        - $ref: '#/components/schemas/BasicRunTaskV2MskFileId'
      - allOf:
        - title: Run task with src file ID & msk file url
          required:
          - msk_file_url
        - $ref: '#/components/schemas/BasicRunTaskV2SrcFileId'
        - $ref: '#/components/schemas/BasicRunTaskV2MskFileUrl'
      - allOf:
        - title: Run task with src file ID & msk file ID
          required:
          - msk_file_id
        - $ref: '#/components/schemas/BasicRunTaskV2SrcFileId'
        - $ref: '#/components/schemas/BasicRunTaskV2MskFileId'
    BasicRunTaskV2MskFileUrl:
      type: object
      properties:
        msk_file_url:
          type: string
          example: https://example.com/mask.jpg
          description: URL of the mask file. This should be a grey scale mask image with the exact same width and height with the input image where white pixels indicate foreground and black pixels represent background. The URL should be publicly accessible.
  responses:
    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
    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
    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
    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
  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''.'
x-refined-from:
- perfect-corp-ai_clothes-openapi.yml
- perfect-corp-ai_object_removal_pro-openapi.yml