Name: Bria Video Erase Object Removal API
Brand: magicapi
SKU: api-magicapi-video-object-erasing-bria-video-erase-object
Availability: InStock
Author: API Market

Shashank Agarwal

# 🧽 Video Object Eraser API - Mask-Based Removal (Bria Video Erase Object)

## Overview
Bria Video Erase Object removes objects, people or other visual elements from a video. Its developer describes it as erasing unwanted elements while keeping visual quality and consistency from frame to frame.

Send the source clip as `video_url` and a mask video as `mask_url`. The mask is a black-and-white video of the same size and length as the source, where white marks the area to erase in every frame. Each request returns the URL of one video: the same clip with the masked area removed and filled in.

## Features
- **Mask-based erasing**: you decide exactly what is removed by painting it white in the mask video, frame by frame.
- **Moving objects**: because the mask is a video, the erased area can follow an object that moves through the clip.
- **Clips up to 5 seconds**: videos longer than 5 seconds are rejected unless you set `auto_trim` to `true`, which keeps only the first 5 seconds.
- **Audio**: `preserve_audio` (default `true`) keeps the original soundtrack in the output.
- **Output formats**: choose the container and codec with `output_container_and_codec`: `mp4_h264` (default), `mp4_h265`, `webm_vp9`, `mov_h265`, `mov_proresks`, `mkv_h264`, `mkv_h265`, `mkv_vp9` or `gif`.

## Use Cases
1. **Cleaning up footage**: remove a distracting sign, light or object from the background of a shot.
2. **Removing branding**: erase logos or labels that cannot appear in the final video.
3. **Removing passers-by**: take a person or vehicle out of a short clip when you can mask them in each frame.
4. **Product and social video**: tidy short clips before publishing without reshooting.

## Visual Examples
### Example Input
`video_url`: a 5 second talking-head clip of a woman with a lit window to the right of her head.

[Watch the input video](https://blog.api.market/wp-content/uploads/2026/10/video-erase-object-input-api-market.mp4)

`mask_url`: a black-and-white mask video of the same size and length. A white box covers the lit window in every frame; everything else is black.

[Watch the mask video](https://blog.api.market/wp-content/uploads/2026/10/video-erase-object-mask-api-market.mp4)

All other fields were left at their defaults (`auto_trim` `false`, `preserve_audio` `true`, `output_container_and_codec` `mp4_h264`).

### Example Output
The same clip with the window removed and the wall filled in where it was.

[Watch the example output](https://blog.api.market/wp-content/uploads/2026/10/video-erase-object-output-api-market.mp4)

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `video_url` | string (URL) | Needed (see note) |  |  | URL of the video file |
| `mask_url` | string (URL) | Needed (see note) |  |  | URL of the mask video file defining the area to erase. White marks what to erase in each frame. |
| `auto_trim` | boolean | No | `false` |  | If true, videos longer than 5 seconds are trimmed to the first 5 seconds. If false, videos over 5 seconds are rejected. |
| `output_container_and_codec` | string | No | `mp4_h264` | `mp4_h264`, `mp4_h265`, `webm_vp9`, `mov_h265`, `mov_proresks`, `mkv_h264`, `mkv_h265`, `mkv_vp9`, `gif` | Output format and codec |
| `preserve_audio` | boolean | No | `true` |  | Whether to keep the original audio in the output |

Note: the input schema does not mark any field as required, but a request needs both `video_url` and `mask_url` to erase anything.

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.063 per API unit.
- **1 API unit = 1 second of output video**, billed on the length of the output video and rounded up per request. The output has the same length as the input clip, which is at most 5 seconds.
- The example clip is 5 seconds long, so the example request costs 5 API units ($0.315).
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/video-object-erasing-bria-video-erase-object`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 2 seconds and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/video-object-erasing-bria-video-erase-object/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "cbecc9042f041609a958facb1396732166d03ebf5eddd20738b449d22ab9f463",
    "input": {
      "video_url": "https://blog.api.market/wp-content/uploads/2026/10/video-erase-object-input-api-market.mp4",
      "mask_url": "https://blog.api.market/wp-content/uploads/2026/10/video-erase-object-mask-api-market.mp4"
    }
  }'
```

Response (201 Created):
```json
{
  "id": "gd64g8ygqdrmy0d17sn8m3d5fc",
  "version": "cbecc9042f041609a958facb1396732166d03ebf5eddd20738b449d22ab9f463",
  "status": "starting",
  "created_at": "2026-10-15T07:15:50.234Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/video-object-erasing-bria-video-erase-object/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "gd64g8ygqdrmy0d17sn8m3d5fc",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/10/video-erase-object-output-api-market.mp4",
  "error": null,
  "created_at": "2026-10-15T07:15:50.234Z",
  "started_at": "2026-10-15T07:15:51.234Z",
  "completed_at": "2026-10-15T07:16:50.234Z"
}
```

`output` is a single URL string pointing to the edited video, in the format set by `output_container_and_codec`.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example an `output_container_and_codec` that is not in the list.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits

All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/video-object-erasing-bria-video-erase-object";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "cbecc9042f041609a958facb1396732166d03ebf5eddd20738b449d22ab9f463", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 2000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
  "video_url": "https://blog.api.market/wp-content/uploads/2026/10/video-erase-object-input-api-market.mp4",
  "mask_url": "https://blog.api.market/wp-content/uploads/2026/10/video-erase-object-mask-api-market.mp4"
}).then((output) => console.log(output)).catch((error) => console.error(error));
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/video-object-erasing-bria-video-erase-object"

def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "cbecc9042f041609a958facb1396732166d03ebf5eddd20738b449d22ab9f463", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])

def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 2
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")

print(create_and_wait_for_prediction({
    "video_url": "https://blog.api.market/wp-content/uploads/2026/10/video-erase-object-input-api-market.mp4",
    "mask_url": "https://blog.api.market/wp-content/uploads/2026/10/video-erase-object-mask-api-market.mp4"
}))
```

## FAQ
- **What should the mask video look like?**
  - A black-and-white video with the same size and length as `video_url`. White marks the area to erase in each frame; black areas are kept. If the object moves, the white area has to move with it.
- **What happens with a video longer than 5 seconds?**
  - With `auto_trim` set to `false` (the default) it is rejected. Set `auto_trim` to `true` to process only the first 5 seconds.
- **Is the original audio kept?**
  - Yes, by default. Set `preserve_audio` to `false` to drop it.
- **How much does a request cost?**
  - $0.063 per second of output video, rounded up per request. A 5 second clip costs 5 API units ($0.315). Failed predictions are not billed.
- **Is the 201 response from POST an error?**
  - No. 201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Remove unwanted objects from short videos with Bria Video Erase Object: send a video and a mask video, get the clip back filled in. $0.063 per second.