Skip to content
Video Editing
/
/
Replace Background

Replace Background

Request

Try out this capability in Bria's sandbox

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 Service 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).
Headers
api_tokenstringrequired
Bodyapplication/jsonrequired
videostringrequired

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

background_urlstringrequired

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_codecstring

Output container and codec preset. Alpha is not needed for replace-background output.

Default:"webm_vp9"
Enum:"mp4_h264""mp4_h265""webm_vp9""mov_h265""mov_proresks""mkv_h264""mkv_h265""mkv_vp9""gif"
preserve_audioboolean

Preserve foreground audio if present.

Default:true
webhook_urlstring, (uri)

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

POST
/replace_background
curl -i -X POST \
  https://engine.prod.bria-api.com/v2/video/edit/replace_background \
  -H 'Content-Type: application/json' \
  -H 'api_token: string' \
  -d '{
    "video": "https://labs-assets.bria.ai/sandbox-example-inputs/5586521-uhd_3840_2160_25fps_original.mp4",
    "background_url": "https://labs-assets.bria.ai/sandbox-example-inputs/batch_replace_example_input.png"
  }'

Responses

Accepted

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