# Remove Background

[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/video-editing/video-remove-background)
**Description**
Initiates an asynchronous background removal job for a video.
> **Need real-time / low-latency background removal?** See [Streaming Background Removal](/video-editing/streaming) for the WebSocket-based variant.

Response behavior:
- Returns HTTP 202 with `request_id` and `status_url`
- Check job status by polling `status_url` or by calling the [status endpoint](/status) with the `request_id` until a terminal status is returned

Supported input containers:
- .mp4, .mov, .webm, .avi, .gif

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

Input attributes preserved in output:
- Aspect Ratio and resolution (unless `auto_zoom` is enabled - see Auto Zoom below)
- Frame Rate
- Audio if present

Limits:
- Max input duration: 60 seconds
- Resolutions: Input resolution up to 16000x16000 (16K). Inputs larger than this return 413 Payload Too Large. Output resolution matches the input resolution. When `auto_zoom` is enabled, the output is cropped to the foreground subject and may be smaller than the input.

Background and transparency control:
- `background_color` must be one of the predefined string values listed below. Hex values are not supported. Default is `Transparent`.
- If `background_color` is `Transparent` and the selected output preset cannot carry alpha, the request is not rejected. `background_color` falls back to `Black` and the completed result carries a `warning` field naming the preset, the colour used, and the presets that do support transparency. Poll the [status endpoint](/status) and check `result.warning` if you need to detect this.

Output transparency support by preset:
- Alpha supported: `webm_vp9`, `mov_proresks`, `mkv_vp9`
- Alpha not supported: `mp4_h264`, `mp4_h265`, `mov_h265`, `mkv_h264`, `mkv_h265`, `gif`

Auto Zoom:
- Set `auto_zoom` to `true` to automatically crop the output video to the foreground subject, creating a zoom-in effect.
- The crop is calculated once for the entire video - the smallest rectangle that contains the subject across all frames - so the framing is stable throughout, with no per-frame movement.
- If the subject moves across a large portion of the frame, the crop is minimal and the output may match the input framing.
- When cropping is applied, the output resolution and aspect ratio differ from the input.
- Enabling this option increases processing time.

Endpoint: POST /remove_background
Security: api_token

## Request fields (application/json):

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

  - `background_color` (string)
    Predefined string only - one of the enum values below. Hex values are not supported. If `Transparent` is used with an output preset that cannot carry alpha, it falls back to `Black` and the result includes a `warning`.
    Enum: "Transparent", "Black", "White", "Gray", "Red", "Green", "Blue", "Yellow", "Cyan", "Magenta", "Orange"

  - `auto_zoom` (boolean)
    When set to `true`, the output video is automatically cropped to the foreground subject, creating a zoom-in effect. The crop is fixed for the entire video (the smallest rectangle containing the subject in all frames), so the framing is stable with no per-frame movement. If the subject moves across most of the frame, little or no cropping is applied. When cropping occurs, output resolution and aspect ratio may differ from the input. Enabling this option increases processing time.

  - `output_container_and_codec` (string)
    Output container and codec preset
    Enum: "mp4_h264", "mp4_h265", "webm_vp9", "mov_h265", "mov_proresks", "mkv_h264", "mkv_h265", "mkv_vp9", "gif"

  - `preserve_audio` (boolean)

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

  - `spill_suppression` (number)
    Strength of green-spill suppression on the retained foreground. Green screens cast a green fringe onto the subject; raising this pulls the green channel toward the red/blue average on green-dominant pixels, removing that fringe. `0` disables it.

## 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 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)