# Video API Reference Bria's Video APIs empower builders with powerful tools for programmatically transforming video content while maintaining original quality. The Video API is organized into two transport paradigms: - **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. - **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). **Asynchronous Requests and the Status Service** Bria 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. See the full guide at [Status Service Documentation](https://docs.bria.ai/status) for complete details and usage examples. ## Servers ``` https://engine.prod.bria-api.com/v2/video/edit ``` ``` https://engine.prod.bria-api.com/v2/video/generate ``` ``` https://engine.prod.bria-api.com/v2/video/segment ``` ## Download OpenAPI description [Video API Reference](https://docs.bria.ai/_bundle/video-editing.yaml) ## Editing Endpoints Tools for modifying video content (Erase, Upscale, Remove BG, Green Screen, Replace Background). REST async. ### Eraser - [POST /erase](https://docs.bria.ai/video-editing/editing-endpoints/erase-object.md): Try out this capability in Bria's sandbox 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 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) ### Increase Resolution - up to 8K - [POST /increase_resolution](https://docs.bria.ai/video-editing/editing-endpoints/increase-resolution.md): Try out this capability in Bria's sandbox 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 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. ### Remove Background - [POST /remove_background](https://docs.bria.ai/video-editing/editing-endpoints/remove-background.md): 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 Service 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 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. 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 ### Replace Background - [POST /replace_background](https://docs.bria.ai/video-editing/editing-endpoints/replace-background.md): 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). ### Green Screen - [POST /green_screen](https://docs.bria.ai/video-editing/editing-endpoints/green-screen.md): Try out this capability in Bria's sandbox 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 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. ## Masking Endpoints Tools for generating segmentation masks (by prompt, by key points, foreground). REST async. ### Generate Mask by Prompt - [POST /mask_by_prompt](https://docs.bria.ai/video-editing/masking-endpoints/mask-by-prompt.md): Generates a segmentation mask video based on a text prompt. Response behavior: - Returns HTTP 202 with request_id and status_url - The final result (via Status Service) will contain a mask_url. Constraints: - Max Duration: 5 seconds (Truncated if auto_trim=true). - Max Resolution: 750p. ### Generate Mask by Key Points - [POST /mask_by_key_points](https://docs.bria.ai/video-editing/masking-endpoints/mask-by-key-points.md): Generates a segmentation mask video based on coordinate key points. Response behavior: - Returns HTTP 202 with request_id and status_url - The final result (via Status Service) will contain a mask_url. Constraints: - Max Duration: 5 seconds (Truncated if auto_trim=true). - Max Resolution: 750p. ### Foreground Mask - [POST /foreground_mask](https://docs.bria.ai/video-editing/masking-endpoints/foreground-mask.md): Initiates an asynchronous foreground mask generation job for a video. Response 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 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 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.