# Replace Background

[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/video-editing/video-replace-background)
**Description**
an asynchronous job that detects the video background and composites a user-provided image or video asset behind the subject. Size and duration mismatches between the input video and the background asset are handled automatically.
**behavior:**
- Returns HTTP 202 with `request_id` and `status_url`
- Check job status by polling `status_url` or by calling the [status endpoint](/status/job-status/get_status) with the `request_id` until a terminal status is returned

**foreground input containers:**
- .mp4, .mov, .webm, .avi, .gif

**foreground input codecs:*
- H.264, H.265 (HEVC), VP9, AV1, PhotoJPEG

**background input formats:**
- Image: .jpg, .png, .webp, .gif
- Video: .mp4, .mov, .webm, .avi

**attributes preserved in output:**
- Aspect Ratio and resolution (matches foreground video)
- Frame Rate (matches foreground video)
- Foreground audio if present and `preserve_audio` is true. Background audio is always discarded.

**Limitations**:
- Max foreground duration: 60 seconds
- Max background video duration: 60 seconds
- Resolutions: Input resolution up to 16000x16000 (16K) for both foreground and background. Inputs larger than this return 413 Payload Too Large. Output resolution matches the foreground input resolution.
- Video Background spect ratio: provided background video must be of same aspect ratio as the foeground video.

**mismatch handling (image bakground)**:
- Background is scaled to cover the full frame, then center-cropped to exactly match the foreground resolution. Some background edges may be clipped.

**mismatch handling (video backgrounds only)**:
- Background video shorter than foreground: loop from 0s until foreground ends.
- Background video longer than foreground: play from 0s, trim at foreground end.

**Output transparency**:
- Output is fully opaque (composited).

Endpoint: POST /replace_background
Security: api_token

## Request fields (application/json):

  - `video` (string, required)
    Publicly accessible URL of the input (foreground) video. Input resolution supported up to 16000x16000 (16K).

  - `background_url` (string, required)
    Publicly accessible URL of the background asset. Accepts images (.jpg, .png, .webp, .gif) or videos (MP4, MOV, WebM, AVI, GIF). Max resolution 16000x16000.

  - `output_container_and_codec` (string)
    Output container and codec preset. Alpha is not needed for replace-background output.
    Enum: "mp4_h264", "mp4_h265", "webm_vp9", "mov_h265", "mov_proresks", "mkv_h264", "mkv_h265", "mkv_vp9", "gif"

  - `preserve_audio` (boolean)
    Preserve foreground audio if present.

  - `webhook_url` (string)
    Optional URL for receiving the result via webhook when the async job completes. See [webhooks](/getting-started/async-requests#webhooks).

## Response 202 fields (application/json):

  - `request_id` (string, required)

  - `status_url` (string, required)

## Response 400 fields (application/json):

  - `error` (object, required)

  - `error.code` (integer, required)
    Example: 123

  - `error.message` (string, required)

  - `error.details` (string, required)

  - `request_id` (string, required)

## Response 403 fields (application/json):

  - `error` (object, required)

  - `error.code` (integer, required)
    Example: 123

  - `error.message` (string, required)

  - `error.details` (string, required)

  - `request_id` (string, required)

## Response 405 fields (application/json):

  - `error` (object, required)

  - `error.code` (integer, required)
    Example: 123

  - `error.message` (string, required)

  - `error.details` (string, required)

  - `request_id` (string, required)

## Response 413 fields (application/json):

  - `error` (object, required)

  - `error.code` (integer, required)
    Example: 123

  - `error.message` (string, required)

  - `error.details` (string, required)

  - `request_id` (string, required)

## Response 415 fields (application/json):

  - `error` (object, required)

  - `error.code` (integer, required)
    Example: 123

  - `error.message` (string, required)

  - `error.details` (string, required)

  - `request_id` (string, required)

## Response 422 fields (application/json):

  - `error` (object, required)

  - `error.code` (integer, required)
    Example: 123

  - `error.message` (string, required)

  - `error.details` (string, required)

  - `request_id` (string, required)

## Response 429 fields (application/json):

  - `error` (object, required)

  - `error.code` (integer, required)
    Example: 123

  - `error.message` (string, required)

  - `error.details` (string, required)

  - `request_id` (string, required)

## Response 500 fields (application/json):

  - `error` (object, required)

  - `error.code` (integer, required)
    Example: 123

  - `error.message` (string, required)

  - `error.details` (string, required)

  - `request_id` (string, required)