Skip to content
Video Editing
/
/
Remove Background

Remove Background

Request

Try out this capability in Bria's sandbox

Description Initiates an asynchronous background removal job for a video.

Need real-time / low-latency background removal? See Streaming Background Removal 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 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 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.

Security
api_token
Bodyapplication/jsonrequired
videostringrequired

Publicly accessible URL of the input video. Input resolution supported up to 16000x16000 (16K)

background_colorstring

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.

Default:"Black"
Enum:"Transparent""Black""White""Gray""Red""Green""Blue""Yellow""Cyan""Magenta"
auto_zoomboolean

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.

Default:false
output_container_and_codecstring

Output container and codec preset

Default:"mp4_h264"
Enum:"mp4_h264""mp4_h265""webm_vp9""mov_h265""mov_proresks""mkv_h264""mkv_h265""mkv_vp9""gif"
preserve_audioboolean
Default:true
webhook_urlstring, (uri)

Optional URL for receiving the result via webhook when the async job completes. See webhooks.

spill_suppressionnumber, [ 0 .. 1 ]

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.

Default:0
POST
/remove_background
from bria_client import BriaSyncClient

client = BriaSyncClient()  # reads BRIA_API_TOKEN

job = client.submit(
    endpoint="video/edit/remove_background",
    payload={
        "video": "https://labs-assets.bria.ai/sandbox-example-inputs/5586521-uhd_3840_2160_25fps_original.mp4",
    },
)
result = client.poll(job, interval=5, timeout=600)
print(result.result.video_url)

Responses

Accepted

Bodyapplication/json
request_idstringrequired
status_urlstringrequired
Response
{
  "request_id": "string",
  "status_url": "string"
}