Skip to content
Video Editing
/
/
Generate Mask by Key Poin...

Overview

Bria's Video Editing APIs empowers builders with powerful tools for programmatically transforming video content while maintaining original quality.

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.

See the full guide at Status Service Documentation for complete details and usage examples.

Register and get API Access
Download OpenAPI description
video-editing.json
video-editing.yaml
Languages
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

Editing Endpoints

Tools for modifying video content (Erase, Upscale, Remove BG)

Operations

Masking Endpoints

Tools for generating segmentation masks

Operations

Generate Mask by Prompt

Request

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.
Headers
api_tokenstringrequired
Bodyapplication/jsonrequired
videostringrequired

Publicly accessible URL for the input video file.

promptstringrequired

The text instruction describing the object to be masked.

auto_trimboolean

If true, trims the video to the 5s limit.

Default false
output_container_and_codecstring
Default "mp4_h264"
Enum"mp4_h264""mp4_h265""webm_vp9""mov_h265""mov_proresks""mkv_h264""mkv_h265""mkv_vp9""gif"
curl -i -X POST \
  https://engine.prod.bria-api.com/v2/video/segment/mask_by_prompt \
  -H 'Content-Type: application/json' \
  -H 'api_token: string' \
  -d '{
    "video": "example",
    "prompt": "example"
  }'

Responses

Accepted

Bodyapplication/json
request_idstringrequired
status_urlstringrequired
Response
application/json
{
  "request_id": "string",
  "status_url": "string"
}

Generate Mask by Key Points

Request

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.
Headers
api_tokenstringrequired
Bodyapplication/jsonrequired
videostringrequired

Publicly accessible URL for the input video file.

frame_indexinteger

The frame number to apply key points to.

key_pointsArray of objectsrequired

An array of coordinate objects defining the mask hints.

key_points[].​xinteger
key_points[].​yinteger
key_points[].​typestring
Enum"positive""negative"
auto_trimboolean

If true, trims the video to the 5s limit.

Default false
output_container_and_codecstring
Default "mp4_h264"
Enum"mp4_h264""mp4_h265""webm_vp9""mov_h265""mov_proresks""mkv_h264""mkv_h265""mkv_vp9""gif"
curl -i -X POST \
  https://engine.prod.bria-api.com/v2/video/segment/mask_by_key_points \
  -H 'Content-Type: application/json' \
  -H 'api_token: string' \
  -d '{
    "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

Accepted

Bodyapplication/json
request_idstringrequired
status_urlstringrequired
Response
application/json
{
  "request_id": "string",
  "status_url": "string"
}

Foreground Mask

Request

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.
Headers
api_tokenstringrequired
Bodyapplication/jsonrequired
videostringrequired

Publicly accessible URL of the input video. Input resolution supported up to 16000x16000 (16K)

output_container_and_codecstring

Output container and codec preset

Default "mp4_h264"
Enum"mp4_h264""mp4_h265""webm_vp9""mov_h265""mov_proresks""mkv_h264""mkv_h265""mkv_vp9""gif"
curl -i -X POST \
  https://engine.prod.bria-api.com/v2/video/generate/foreground_mask \
  -H 'Content-Type: application/json' \
  -H 'api_token: string' \
  -d '{
    "video": "example"
  }'

Responses

Accepted

Bodyapplication/json
request_idstringrequired
status_urlstringrequired
Response
application/json
{
  "request_id": "string",
  "status_url": "string"
}