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 endpoint 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).
Security
api_token
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
from bria_client import BriaSyncClient

client = BriaSyncClient()  # reads BRIA_API_TOKEN

job = client.submit(
    endpoint="video/edit/replace_background",
    payload={
        "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",
    },
)
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"
}