{ "openapi": "3.0.0", "info": { "title": "Video Editing API Reference", "version": "", "description": "Bria's Video Editing APIs empowers builders with powerful tools for programmatically transforming video content while maintaining original quality.\n\n\n**Asynchronous Requests and the Status Service** Bria API v2 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" }, "externalDocs": { "description": "Register and get API Access", "url": "https://platform.bria.ai/console/account/api-keys" }, "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)" }, { "name": "Masking Endpoints", "description": "Tools for generating segmentation masks" } ], "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)\n\n\n**Description**\nInitiates an asynchronous object erasure job. Removes objects defined by the mask input and reconstructs the background.\n\n\n**Mask Input**\n\n\nThis 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.\n\n\nResponse behavior:\n\n- Returns HTTP 202 with `request_id` and `status_url`\n\n- 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\n\n\nConstraints & Limits:\n\n- **Max Duration:** 5 seconds. Videos longer than 5s will be truncated if `auto_trim` is true, or rejected if false.\n\n- **Max Resolution:** 750p. Inputs higher than 750p will be automatically downscaled.\n\n- **Frame Rate:** Recommended 24 FPS (preserved in output).\n\n\nPreservation Rules:\n\n- Aspect Ratio (within 16:9 constraint)\n\n- Frame Rate\n\n- 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" } }, "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" } } } } } } }, "/mask_by_prompt": { "servers": [ { "url": "https://engine.prod.bria-api.com/v2/video/segment" } ], "post": { "summary": "Generate Mask by Prompt", "tags": [ "Masking Endpoints" ], "description": "Generates a segmentation mask video based on a text prompt.\n\nResponse behavior:\n- Returns HTTP 202 with `request_id` and `status_url`\n- The final result (via Status Service) will contain a `mask_url`.\n\nConstraints:\n- Max Duration: 5 seconds (Truncated if `auto_trim`=true).\n- Max Resolution: 750p.", "operationId": "mask-by-prompt", "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 for the input video file." }, "prompt": { "type": "string", "description": "The text instruction describing the object to be masked." }, "auto_trim": { "type": "boolean", "default": false, "description": "If true, trims the video to the 5s limit." }, "output_container_and_codec": { "type": "string", "default": "mp4_h264", "enum": [ "mp4_h264", "mp4_h265", "webm_vp9", "mov_h265", "mov_proresks", "mkv_h264", "mkv_h265", "mkv_vp9", "gif" ] } }, "required": [ "video", "prompt" ] }, "example": { "video": "example", "prompt": "example" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncInitialResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "NoObjectDetected": { "summary": "Prompt Detection Failed", "value": { "error": { "code": 400, "message": "No objects detected for prompt in image", "details": "Object detection failed. We could not find a match for your description. Please refine your prompt: 'XXXX'" } } } } } } }, "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" } } } } } } }, "/mask_by_key_points": { "servers": [ { "url": "https://engine.prod.bria-api.com/v2/video/segment" } ], "post": { "summary": "Generate Mask by Key Points", "tags": [ "Masking Endpoints" ], "description": "Generates a segmentation mask video based on coordinate key points.\n\nResponse behavior:\n- Returns HTTP 202 with `request_id` and `status_url`\n- The final result (via Status Service) will contain a `mask_url`.\n\nConstraints:\n- Max Duration: 5 seconds (Truncated if `auto_trim`=true).\n- Max Resolution: 750p.", "operationId": "mask-by-key-points", "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 for the input video file." }, "frame_index": { "type": "integer", "description": "The frame number to apply key points to." }, "key_points": { "type": "array", "description": "An array of coordinate objects defining the mask hints.", "items": { "type": "object", "properties": { "x": { "type": "integer" }, "y": { "type": "integer" }, "type": { "type": "string", "enum": [ "positive", "negative" ] } } } }, "auto_trim": { "type": "boolean", "default": false, "description": "If true, trims the video to the 5s limit." }, "output_container_and_codec": { "type": "string", "default": "mp4_h264", "enum": [ "mp4_h264", "mp4_h265", "webm_vp9", "mov_h265", "mov_proresks", "mkv_h264", "mkv_h265", "mkv_vp9", "gif" ] } }, "required": [ "video", "key_points" ] }, "example": { "video": "example", "frame_index": 88, "key_points": [ { "x": 650, "y": 400, "type": "positive" }, { "x": 655, "y": 405, "type": "positive" }, { "x": 50, "y": 100, "type": "negative" } ] } } } }, "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)\n\n\n**Description**\nInitiates an asynchronous resolution upscaling job for a video.\n\n**Upscales up to 8K output!**\n\n\nResponse behavior:\n\n- Returns HTTP 202 with `request_id` and `status_url`\n\n- 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\n\n\nSupported input containers:\n\n- .mp4, .mov, .webm, .avi, .gif\n\n\nSupported input codecs:\n\n- H.264, H.265 (HEVC), VP9, AV1, PhotoJPEG\n\n\nInput attributes preserved in output:\n\n- Aspect Ratio\n\n- Frame Rate\n\n- Color Bit Depth\n\n- Audio if present\n\n- Transparency if present and supported by the selected output preset\n\n\nLimits:\n\n- Max input duration: 60 seconds\n\n- Max output resolution: 7680x4320 (8K). If the selected `desired_increase` would exceed this limit the server returns 422 Unprocessable Entity.\n\n\nEncoding:\n\n- 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 } }, "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)\n\n\n**Description**\nInitiates an asynchronous background removal job for a video.\n\n\nResponse behavior:\n\n- Returns HTTP 202 with `request_id` and `status_url`\n\n- 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\n\n\nSupported input containers:\n\n- .mp4, .mov, .webm, .avi, .gif\n\n\nSupported input codecs:\n\n- H.264, H.265 (HEVC), VP9, AV1, PhotoJPEG\n\n\nInput attributes preserved in output:\n\n- Aspect Ratio and resolution\n\n- Frame Rate\n\n- Audio if present\n\n\nLimits:\n\n- Max input duration: 60 seconds\n\n- Resolutions: Input resolution up to 16000x16000 (16K). Inputs larger than this return 413 Payload Too Large. Output resolution matches the input resolution.\n\n\nBackground and transparency control:\n\n- `background_color` must be one of the predefined string values listed below. Hex values are not supported. Default is `Transparent`.\n\n- If `background_color` is `Transparent`, the selected output preset must support alpha. Otherwise the server responds with 422 Unprocessable Entity.\n\n\nOutput transparency support by preset:\n\n- Alpha supported: `webm_vp9`, `mov_proresks`, `mkv_vp9`, `mkv_raw`, `gif`, `mov_h265` when encoded as HEVC with Alpha\n\n- Alpha not supported: `mp4_h264`, `mp4_h265`, `mkv_h264`, `mkv_h265`, `avi_h264`", "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": "Transparent", "enum": [ "Transparent", "Black", "White", "Gray", "Red", "Green", "Blue", "Yellow", "Cyan", "Magenta", "Orange" ] }, "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": "webm_vp9" }, "preserve_audio": { "type": "boolean", "default": true } }, "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" } } } }, "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" } } } } } } }, "/foreground_mask": { "servers": [ { "url": "https://engine.prod.bria-api.com/v2/video/generate" } ], "post": { "summary": "Foreground Mask", "tags": [ "Masking Endpoints" ], "description": "Initiates an asynchronous foreground mask generation job for a video.\n\nResponse behavior:\n- Returns HTTP 202 with `request_id` and `status_url`\n- 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\n\nSupported input containers:\n- .mp4, .mov, .webm, .avi, .gif\n\nSupported input codecs:\n- H.264, H.265 (HEVC), VP9, AV1, PhotoJPEG\n\nInput attributes preserved in output:\n- Aspect Ratio and resolution\n- Frame Rate\n- Audio if present\n\nLimits:\n- Max input duration: 60 seconds\n- Resolutions: Input resolution up to 16000x16000 (16K). Inputs larger than this return 413 Payload Too Large. Output resolution matches the input resolution.", "operationId": "foreground-mask", "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)" }, "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" } }, "required": [ "video" ] }, "example": { "video": "example" } } } }, "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": { "ErrorObject": { "type": "object", "properties": { "code": { "type": "integer", "example": 123 }, "message": { "type": "string" }, "details": { "type": "string" } }, "required": [ "code", "message", "details" ] }, "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" ] } } } }