openapi: 3.0.0
info:
  title: AI Replace
  description: "# Overview\nReplace unwanted elements with new objects using AI Replace. By using this\
    \ API, you can instantly remove unwanted object from your photo and replace it with a new one just\
    \ by using text. Eliminate anything from bags to cars and beyond.​\n\nSample:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_replace_S3_feature_img_02_a73a26bcc3.jpg)\n\
    \n\nFor content creators aiming to perfect their social media presence, AI Replace offers a hassle-free\
    \ way to polish travel photos or promotional images. Remove and replace elements with ease, ensuring\
    \ your content stands out.\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_replace_S3_feature_img_03_42c9cd98d0.jpg)\n\
    \n\nCreate stunning room mockups with AI Replace by filling empty spaces with aesthetically pleasing\
    \ furniture and objects, transforming the perception of any space.\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_replace_S3_feature_img_04_4d2d82f76e.jpg)\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 Replace | long\
    \ side <= 2048 | < 10MB | jpg/jpeg/png |\n\n* Error Codes\n\n|Error Code|Description|\n|  ----  |\
    \ ----  |\n| exceed_max_filesize |\tInput file size exceeds the maximum limit |\n| invalid_parameter\
    \ |\tInvalid parameter value |\n| error_download_image\t| Download source image error |\n| error_decode_image\t\
    | Decode source image error |\n| error_nsfw_content_detected\t| NSFW content detected in source image\
    \ |\n\n---\n\n## Unit Consumption\n\n| AI Feature | Unit Consumed |\n|---|---|\n| AI Replace V1.0\
    \ | 1 |\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 Replace API allows you to replace specific objects in images using generative fill technology.
    Requires source image, mask for the area to replace, and a text prompt describing what should be generated.
paths:
  /s2s/v2.0/task/obj-replace:
    post:
      summary: Run an AI Replace task.
      description: Please refer to the polling guide for checking task status. This API requires a source
        image, mask file, and prompt describing what should replace the masked area.
      tags:
      - V1.0
      security:
      - BearerAuthenticationV2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/BasicRunTaskV2WithRequiredMsk'
              - type: object
                required:
                - prompt
                properties:
                  prompt:
                    type: string
                    description: Prompt for generating objects in the masked area.
                    example: a cute cat
      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/obj-replace/{task_id}:
    get:
      summary: Check an AI Replace task status.
      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:
  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
    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.
    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.
    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=
    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'
    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"
    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'
  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