openapi: 3.0.0
info:
  title: AI Video Background Replace
  description: >
    # Overview


    **AI Video Background Replace**


    ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Green_Screen_ddb7892393.png)


    The AI Video Background Replace API enables you to seamlessly add any
    background you choose. You can select from a wide range of options,
    including scenic landscapes, custom images, or even lighthearted visuals,
    giving you complete creative control to design the ideal setting for your
    content.

    There is no need for a studio or green screen. You can easily replace video
    backgrounds to achieve a clean and professional look. Whether you want to
    introduce a new environment or remove unwanted distractions, this solution
    is ideal for producing engaging videos and tutorials without requiring
    expensive equipment.



    ---


    ## Integration Guide


    **1. Prepare a Source Video and a Background Image**

    The output must be in MP4 format with the same resolution as the input, a
    frame rate capped at 30 frames per second with automatic conversion if the
    input exceeds this limit, and a maximum duration of 600 seconds with only
    the first 600 seconds retained if the input video is longer.


    The background image must be in JPG or PNG format with a maximum resolution
    of 4096 by 4096 pixels with the long side not exceeding 4096 pixels and a
    file size limit of 10 megabytes.



    **2. Upload File**

    Request upload URLs and file IDs via:


    ```

    POST /s2s/v2.0/file

    ```



    **3. Execute AI Task**


    ```

    POST /s2s/v2.0/task/bg-replace-vid

    ```


    Submit the task using file IDs or image URLs as input. The response returns
    a task_id for tracking and retrieving the result.



    **4. Retrieve Task Result**


    ```

    GET /s2s/v2.0/task/bg-replace-vid/{task_id}

    ```


    Use the task ID to track status and obtain results.


    [Webhooks](/develop/webhook.md) can be configured to receive asynchronous
    notifications on task completion with a success or error status. Polling is
    also supported by repeatedly calling the task endpoint until the status is
    updated from running to success or error.


    Usage is only charged when the task completes successfully.




    ---


    ## File Specs & Errors


    * Supported Formats & Dimensions


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

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

    | AI Video Background Replace | The output must be in MP4 format with the
    same resolution as the input, a frame rate capped at 30 frames per second
    with automatic conversion if the input exceeds this limit, and a maximum
    duration of 600 seconds with only the first 600 seconds retained if the
    input video is longer. <br>The background image must be in JPG or PNG format
    with a maximum resolution of 4096 by 4096 pixels with the long side not
    exceeding 4096 pixels and a file size limit of 10 megabytes. | Video length
    limit: 600s <br> Background image: <10MB | container: mp4 <br>video: MPEG-4,
    MPEG-4 AVC, <br>audio: aac, amr, mp3 |


    * Error Codes


    |Error Code|Description|

    |  ----  | ----  |

    | error_download_video | Download source video error |

    | error_decode_video | Decode source video error |

    | error_unsupported_video | Unsupported video format |

    | exceed_max_filesize | Input file size exceeds the maximum limit|

    | error_nsfw_content_detected | NSFW content detected in the source file |

    | error_decode_mask | Decode mask image error |

    | invalid_parameter | Invalid parameter value|


    * Environment & Dependency


    | Sample Code Language / Tool | Recommended Runtime Versions |

    |---|---|

    | cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP
    support)</br>   - jq >= 1.6 (robust JSON parsing) |

    | Node.js (JavaScript) | Node >= 18 (for global fetch) |

    | JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari
    >= 13.1 |

    | PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) or
    allow_url_fopen=On + ext-openssl, ext-json |

    | Python | Python >= 3.10 (for f-strings), requests >= 2.20.0 |

    | Java | Java 11+ (for HttpClient), Jackson Databind >= 2.12.0 |
  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: V2.0
    description: AI Video Background Replace
paths:
  /s2s/v2.0/task/bg-replace-vid:
    post:
      summary: Run an AI Video Background Replace 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:
        - V2.0
      security:
        - BearerAuthenticationV2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/BasicRunTaskV2VidSrcWithRequiredRefImg'
                - type: object
                  properties:
                    background_mode:
                      type: string
                      enum:
                        - crop
                        - stretch
                      default: crop
                      description: >-
                        How the background image (the ref file) is fit onto the
                        source video. `crop` keeps the background's aspect ratio
                        and crops it to fill; `stretch` scales the background to
                        the source video's dimensions.
      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/bg-replace-vid/{task_id}:
    get:
      summary: Check the status of an AI Video Background Replace task.
      tags:
        - V2.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:
    BasicRunTaskV2VidSrcFileUrl:
      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/cat_video.mp4
    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
    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=
    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=
    BasicRunTaskV2VidSrcWithRequiredRefImg:
      title: BasicRunTaskV2VidSrcWithRequiredRefImg
      anyOf:
        - allOf:
            - title: Run task with src video url & ref file url
              required:
                - ref_file_url
            - $ref: '#/components/schemas/BasicRunTaskV2VidSrcFileUrl'
            - $ref: '#/components/schemas/BasicRunTaskV2RefFileUrl'
        - allOf:
            - title: Run task with src video url & ref file ID
              required:
                - ref_file_id
            - $ref: '#/components/schemas/BasicRunTaskV2VidSrcFileUrl'
            - $ref: '#/components/schemas/BasicRunTaskV2RefFileId'
        - allOf:
            - title: Run task with src video ID & ref file url
              required:
                - ref_file_url
            - $ref: '#/components/schemas/BasicRunTaskV2SrcFileId'
            - $ref: '#/components/schemas/BasicRunTaskV2RefFileUrl'
        - allOf:
            - title: Run task with src video ID & ref file ID
              required:
                - ref_file_id
            - $ref: '#/components/schemas/BasicRunTaskV2SrcFileId'
            - $ref: '#/components/schemas/BasicRunTaskV2RefFileId'
    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'
  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
