---
title: "Replace Background"
method: POST
path: "/replace_background"
tags: ["Editing Endpoints"]
---

# Replace Background

`POST /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 Service](https://docs.bria.ai/status/endpoints/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).

## Headers

- `api_token` string, required

## Request body

- object
  - `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` 'mp4_h264' | 'mp4_h265' | 'webm_vp9' | 'mov_h265' | 'mov_proresks' | 'mkv_h264' | 'mkv_h265' | 'mkv_vp9' | 'gif' — Output container and codec preset. Alpha is not needed for replace-background output.
  - `preserve_audio` boolean — Preserve foreground audio if present.
  - `webhook_url` string, uri — Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks).

## Response `202`

Accepted

- AsyncInitialResponse
  - `request_id` string, required
  - `status_url` string, required

## Other responses

- `400` — Bad request
- `403` — Forbidden
- `405` — Method not allowed
- `413` — Payload Too Large
- `415` — Unsupported input container or codec (foreground or background)
- `422` — Unprocessable entity (e.g., unreachable background URL, background URL not provided, unsupported background format, background exceeds 60s)
- `429` — Too many requests
- `500` — Internal server error

---

[API](https://skmtc.net/bria-ai/apis/video-api-reference.md) · [All operations](https://skmtc.net/bria-ai/apis/video-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bria-ai/video-api-reference/revisions/fa6d2efc9689/schema)