openapi: 3.2.0
info:
title: Video API Reference Editing Endpoints API
version: ''
description: "Bria's Video APIs empower builders with powerful tools for programmatically transforming video content while maintaining original quality.\n\nThe Video API is organized into two transport paradigms:\n\n- **REST API (Async)** — Standard HTTP request/response. You submit a job, receive a `request_id` and `status_url`, and poll the [Status Service](https://docs.bria.ai/status) until the job completes. Use this for editing, masking, and most batch-style workflows.\n- **Streaming API (WebSocket)** — Persistent bidirectional connection for low-latency, frame-by-frame processing. Use this when you need real-time output (e.g., live video feeds, interactive previews).\n\n**Asynchronous Requests and the Status Service** \nBria API v2 REST endpoints process requests asynchronously by default. When you make an asynchronous request, the API immediately returns a `request_id` and a `status_url` instead of the final result. Use the Status Service to track the request's progress until it reaches a completed state.\n\nSee the full guide at [Status Service Documentation](https://docs.bria.ai/status) for complete details and usage examples.\n"
servers:
- url: https://engine.prod.bria-api.com/v2/video/edit
- url: https://engine.prod.bria-api.com/v2/video/generate
- url: https://engine.prod.bria-api.com/v2/video/segment
tags:
- name: Editing Endpoints
description: Tools for modifying video content (Erase, Upscale, Remove BG, Green Screen, Replace Background). REST async.
paths:
/erase:
servers:
- url: https://engine.prod.bria-api.com/v2/video/edit
post:
summary: Eraser
tags:
- Editing Endpoints
description: '[**Try out this capability in Bria''s sandbox**](https://platform.bria.ai/video-editing/eraser-video)
**Description**
Initiates an asynchronous object erasure job. Removes objects defined by the mask input and reconstructs the background.
**Mask Input**
This endpoint requires a mask definition object. You can provide a direct `mask_url`, or use one of our masking endpoints (`mask_by_prompt`, `mask_by_key_points`) to define the mask area.
Response 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) with the `request_id` until a terminal status is returned
Constraints & Limits:
- **Max Duration:** 5 seconds. Videos longer than 5s will be truncated if `auto_trim` is true, or rejected if false.
- **Max Resolution:** 750p. Inputs higher than 750p will be automatically downscaled.
- **Frame Rate:** Recommended 24 FPS (preserved in output).
Preservation Rules:
- Aspect Ratio (within 16:9 constraint)
- Frame Rate
- Audio (preserved by default)'
operationId: erase-object
parameters:
- in: header
name: api_token
schema:
type: string
required: true
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
video:
type: string
description: Publicly accessible URL of the input video.
mask:
type: string
description: Required. A URL with mask video defining the area to erase.
preserve_audio:
type: boolean
default: true
description: Whether to keep the original audio track.
auto_trim:
type: boolean
default: false
description: If true, videos longer than 5 seconds are trimmed to the first 5 seconds.
output_container_and_codec:
type: string
description: Output container and codec preset.
enum:
- mp4_h264
- mp4_h265
- webm_vp9
- mov_h265
- mov_proresks
- mkv_h264
- mkv_h265
- mkv_vp9
- gif
default: mp4_h264
webhook_url:
type: string
format: uri
description: Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks).
required:
- video
- mask
example:
video: https://bria-test-images.s3.us-east-1.amazonaws.com/videos/eraser/video1_video.mp4
mask: https://bria-test-images.s3.us-east-1.amazonaws.com/videos/eraser/video1_mask.mp4
output_container_and_codec: mp4_h264
responses:
'202':
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncInitialResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'405':
description: Method not allowed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'415':
description: Unsupported input container or codec
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Unprocessable entity
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/increase_resolution:
servers:
- url: https://engine.prod.bria-api.com/v2/video/edit
post:
summary: Increase Resolution - up to 8K
tags:
- Editing Endpoints
description: '[**Try out this capability in Bria''s sandbox**](https://platform.bria.ai/video-editing/video-increase-resolution)
**Description**
Initiates an asynchronous resolution upscaling job for a video.
**Upscales up to 8K output!**
Response 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) 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
- Frame Rate
- Color Bit Depth
- Audio if present
- Transparency if present and supported by the selected output preset
Limits:
- Max input duration: 60 seconds
- Max output resolution: 7680x4320 (8K). If the selected `desired_increase` would exceed this limit the server returns 422 Unprocessable Entity.
Encoding:
- Bitrate is adjusted automatically to match the target resolution to preserve quality.'
operationId: increase-resolution
parameters:
- in: header
name: api_token
schema:
type: string
required: true
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
video:
type: string
description: Publicly accessible URL of the input video
desired_increase:
type: integer
description: Integer scale factor for upscaling
enum:
- 2
- 4
default: 2
output_container_and_codec:
type: string
description: Output container and codec preset
enum:
- mp4_h264
- mp4_h265
- webm_vp9
- mov_h265
- mov_proresks
- mkv_h264
- mkv_h265
- mkv_vp9
- gif
default: mp4_h264
preserve_audio:
type: boolean
default: true
webhook_url:
type: string
format: uri
description: Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks).
required:
- video
example:
video: https://labs-assets.bria.ai/sandbox-example-inputs/3446608-sd_426_240_25fps.mp4
responses:
'202':
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncInitialResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'405':
description: Method not allowed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'415':
description: Unsupported input container or codec
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Unprocessable entity
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/remove_background:
servers:
- url: https://engine.prod.bria-api.com/v2/video/edit
post:
summary: Remove Background
tags:
- Editing Endpoints
description: '[**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](#tag/Streaming-Endpoints) 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 Service](https://docs.bria.ai/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`, the selected output preset must support alpha. Otherwise the server responds with 422 Unprocessable Entity.
Output transparency support by preset:
- Alpha supported: `webm_vp9`, `mov_proresks`, `mkv_vp9`, `mkv_raw`, `gif`, `mov_h265` when encoded as HEVC with Alpha
- Alpha not supported: `mp4_h264`, `mp4_h265`, `mkv_h264`, `mkv_h265`, `avi_h264`
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.'
operationId: remove-background
parameters:
- in: header
name: api_token
schema:
type: string
required: true
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
video:
type: string
description: Publicly accessible URL of the input video. Input resolution supported up to 16000x16000 (16K)
background_color:
type: string
description: Predefined string only - one of the enum values below. Hex values are not supported
default: Black
enum:
- Transparent
- Black
- White
- Gray
- Red
- Green
- Blue
- Yellow
- Cyan
- Magenta
- Orange
auto_zoom:
type: boolean
default: false
description: 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:
type: string
description: Output container and codec preset
enum:
- mp4_h264
- mp4_h265
- webm_vp9
- mov_h265
- mov_proresks
- mkv_h264
- mkv_h265
- mkv_vp9
- gif
default: mp4_h264
preserve_audio:
type: boolean
default: true
webhook_url:
type: string
format: uri
description: Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks).
required:
- video
example:
video: https://labs-assets.bria.ai/sandbox-example-inputs/5586521-uhd_3840_2160_25fps_original.mp4
responses:
'202':
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncInitialResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'405':
description: Method not allowed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'413':
description: Payload Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Unprocessable entity
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/replace_background:
servers:
- url: https://engine.prod.bria-api.com/v2/video/edit
post:
summary: Replace Background
tags:
- Editing Endpoints
description: '[**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).'
operationId: replace-background
parameters:
- in: header
name: api_token
schema:
type: string
required: true
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
video:
type: string
description: Publicly accessible URL of the input (foreground) video. Input resolution supported up to 16000x16000 (16K).
background_url:
type: string
description: 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:
type: string
description: Output container and codec preset. Alpha is not needed for replace-background output.
enum:
- mp4_h264
- mp4_h265
- webm_vp9
- mov_h265
- mov_proresks
- mkv_h264
- mkv_h265
- mkv_vp9
- gif
default: webm_vp9
preserve_audio:
type: boolean
description: Preserve foreground audio if present.
default: true
webhook_url:
type: string
format: uri
description: Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks).
required:
- video
- background_url
example:
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:
'202':
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncInitialResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'405':
description: Method not allowed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'413':
description: Payload Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'415':
description: Unsupported input container or codec (foreground or background)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Unprocessable entity (e.g., unreachable background URL, background URL not provided, unsupported background format, background exceeds 60s)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/green_screen:
servers:
- url: https://engine.prod.bria-api.com/v2/video/edit
post:
summary: Green Screen
tags:
- Editing Endpoints
description: '[**Try out this capability in Bria''s sandbox**](https://platform.bria.ai/video-editing/video-green-screen)
**Description**
Initiates an asynchronous job that detects the video background and replaces it with a solid green (or blue) screen, producing a chroma-key-ready output for downstream compositing tools.
Response 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
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
- Frame Rate
- Audio if present and `preserve_audio` is true
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.
Green shade selection:
- `broadcast_green` (#00B140) - industry standard for professional pipelines. Default.
- `chroma_green` (#00FF00) - works with consumer editors.
- `blue_screen` (#0000FF) - use when the subject wears green.
Output transparency:
- Output is fully opaque (no alpha channel needed). `mp4_h264` is recommended for broad editor compatibility.'
operationId: green-screen
parameters:
- in: header
name: api_token
schema:
type: string
required: true
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
video:
type: string
description: Publicly accessible URL of the input video. Input resolution supported up to 16000x16000 (16K)
green_shade:
type: string
description: Predefined screen color. `broadcast_green` (#00B140) is the industry standard for professional pipelines. `chroma_green` (#00FF00) works with consumer editors. `blue_screen` (#0000FF) is used when the subject wears green.
default: broadcast_green
enum:
- broadcast_green
- chroma_green
- blue_screen
output_container_and_codec:
type: string
description: Output container and codec preset. Alpha is not needed for green screen output; `mp4_h264` is recommended for broad editor compatibility.
enum:
- mp4_h264
- mp4_h265
- webm_vp9
- mov_h265
- mov_proresks
- mkv_h264
- mkv_h265
- mkv_vp9
- gif
default: webm_vp9
preserve_audio:
type: boolean
default: true
webhook_url:
type: string
format: uri
description: Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks).
required:
- video
example:
video: https://labs-assets.bria.ai/sandbox-example-inputs/5586521-uhd_3840_2160_25fps_original.mp4
green_shade: broadcast_green
responses:
'202':
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncInitialResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'405':
description: Method not allowed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'413':
description: Payload Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'415':
description: Unsupported input container or codec
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Unprocessable entity
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
ErrorResponse:
type: object
properties:
error:
$ref: '#/components/schemas/ErrorObject'
request_id:
type: string
required:
- error
- request_id
AsyncInitialResponse:
type: object
properties:
request_id:
type: string
status_url:
type: string
required:
- request_id
- status_url
ErrorObject:
type: object
properties:
code:
type: integer
example: 123
message:
type: string
details:
type: string
required:
- code
- message
- details
externalDocs:
description: Register and get API Access
url: https://platform.bria.ai/organization-management/api-keys
x-tagGroups:
- name: REST API (Async)
tags:
- Editing Endpoints
- Masking Endpoints
- name: Streaming API