Name: sprited BiRefNet Video Background Removal API
Brand: magicapi
SKU: api-magicapi-video-background-removal-sprited-birefnet-video
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎞️ Video Background Removal API (sprited BiRefNet Video)

## Overview
BiRefNet Video removes the background from a video by running a BiRefNet model on every frame. Its developer describes it as covering every BiRefNet variant plus ToonOut, with transparent WebM output by default (MP4, MOV and GIF are also available), and MIT-licensed for commercial use.

Send a video (mp4, mov, webm or m4v) as `video`. Pick the model with `variant`, choose between a `cutout` of the foreground and the raw grayscale `mask` with `output_format`, and pick the container with `video_output_type`. Each request returns the URL of one video.

## Features
- **11 model variants**: `general` (default), `general-hr`, `portrait`, `matting`, `matting-hr`, `dynamic`, `dynamic-matting`, `lite`, `lite-2k`, `lite-matting` and `toonout` (the anime and stylized fine-tune).
- **Cutout or matte**: `output_format` `cutout` returns the foreground with the background removed; `mask` returns the single-channel alpha matte as a grayscale video.
- **Transparent output**: `webm` (VP9, default) and `mov` (ProRes 4444) keep transparency; `mp4` (x264) has no alpha, so cutouts are placed on `background_color`; `gif` is palette-based.
- **Matte controls**: `mask_blur` (0 to 64), `mask_offset` (-64 to 64) and `refine_fg` (default `true`) for cleaner soft edges.
- **Encoding controls**: `video_quality` (`low` to `maximum`, default `high`) and `video_write_mode` (`fast`, `balanced` or `small`).
- **Precision and resolution**: `precision` `fp16` (default, about 2x faster) or `fp32`; `resolution` 0 uses the variant's native resolution.

## Use Cases
1. **Green-screen-free compositing**: cut people or characters out of footage and place them on new backgrounds.
2. **Transparent overlays**: WebM or MOV clips with alpha for web pages, streams and video editors.
3. **Animated characters**: remove backgrounds from anime or game animation clips with the `toonout` variant.
4. **Matte passes**: export the grayscale alpha matte for use in your own compositing pipeline.

## Visual Examples
### Example Input
[Watch the input video](https://blog.api.market/wp-content/uploads/2026/10/birefnet-video-input-w14-api-market.mp4): an animated anime-style character running on a green background.

Settings: `variant` `toonout`, `output_format` `cutout`, `video_output_type` `webm`, `precision` `fp32`, `refine_fg` `true`, `video_quality` `high`, `video_write_mode` `balanced`, `resolution` 0 (native), `batch_size` 1, `mask_blur` 0, `mask_offset` 0, `background_color` `#000000`.

### Example Output
[Watch the example output](https://blog.api.market/wp-content/uploads/2026/10/birefnet-video-output-h6nah4ff-api-market.webm)

The character cut out of every frame, as a WebM video with a transparent background.

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `video` | string (URL) | Yes |  |  | Input video URL (mp4, mov, webm, m4v) |
| `variant` | string | No | `general` | `general`, `general-hr`, `portrait`, `matting`, `matting-hr`, `dynamic`, `dynamic-matting`, `lite`, `lite-2k`, `lite-matting`, `toonout` | Which BiRefNet model to use. `general` is the all-purpose default; `toonout` is the anime and stylized fine-tune; the rest are specialized BiRefNet models. |
| `output_format` | string | No | `cutout` | `cutout`, `mask` | `cutout` = foreground with background removed; `mask` = the raw single-channel alpha matte (grayscale video) |
| `video_output_type` | string | No | `webm` | `webm`, `mp4`, `mov`, `gif` | Output container and codec. `webm` (VP9) and `mov` (ProRes 4444) keep transparency; `mp4` (x264) has no alpha, so cutouts are composited on `background_color`; `gif` is palette-based. |
| `background_color` | string | No | `#000000` |  | Background colour (hex) for cutouts in formats without alpha (mp4, gif) |
| `resolution` | integer | No | `0` | 0 to 2048 | Inference resolution (square). 0 = the variant's native resolution. |
| `refine_fg` | boolean | No | `true` |  | Refine foreground colours to remove background bleed on soft edges. Ignored for `mask` output. |
| `mask_blur` | integer | No | `0` | 0 to 64 | Gaussian blur radius applied to the matte |
| `mask_offset` | integer | No | `0` | -64 to 64 | Grow (+) or shrink (-) the matte by this many pixels |
| `video_quality` | string | No | `high` | `low`, `medium`, `high`, `maximum` | Encoding quality |
| `video_write_mode` | string | No | `balanced` | `fast`, `balanced`, `small` | Encoding speed versus file size |
| `precision` | string | No | `fp16` | `fp16`, `fp32` | GPU inference precision. `fp16` is about 2x faster than `fp32` with negligible quality difference; choose `fp32` only if you need exact full-precision output. |
| `batch_size` | integer | No | `1` | 1 to 16 | Frames per GPU forward pass. Leave at 1: batching adds no speed and only uses more GPU memory. |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.097 per API unit.
- **1 API unit = 1 request with up to 89 seconds of processing.** A request that runs longer is billed one more unit for each started 89-second block (for example, more than 89 and up to 178 seconds of processing is 2 units, $0.194).
- Processing time grows with the number of frames and the resolution, so long or high-resolution videos can use several units. The default `fp16` precision runs faster than `fp32`, which the example used.
- **Example cost**: the example request took 27.4 seconds of processing, which fits in one 89-second block: 1 API unit, $0.097.
- **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-background-removal-sprited-birefnet-video`

### 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 900 seconds (15 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/video-background-removal-sprited-birefnet-video/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "d4fd02a2eaddddfd6fbe77570e7408b3f15ee4dcf2ded407ace7a0f9d114ae87",
    "input": {
      "video": "https://blog.api.market/wp-content/uploads/2026/10/birefnet-video-input-w14-api-market.mp4",
      "variant": "toonout",
      "mask_blur": 0,
      "precision": "fp32",
      "refine_fg": true,
      "batch_size": 1,
      "resolution": 0,
      "mask_offset": 0,
      "output_format": "cutout",
      "video_quality": "high",
      "background_color": "#000000",
      "video_write_mode": "balanced",
      "video_output_type": "webm"
    }
  }'
```

Response (201 Created):
```json
{
  "id": "h6nah4ff79rmt0d1f1svadqpa4",
  "version": "d4fd02a2eaddddfd6fbe77570e7408b3f15ee4dcf2ded407ace7a0f9d114ae87",
  "status": "starting",
  "created_at": "2026-10-26T13:43:46.415Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/video-background-removal-sprited-birefnet-video/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "h6nah4ff79rmt0d1f1svadqpa4",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/10/birefnet-video-output-h6nah4ff-api-market.webm",
  "error": null,
  "created_at": "2026-10-26T13:43:46.415Z",
  "started_at": "2026-10-26T13:44:10.178Z",
  "completed_at": "2026-10-26T13:44:37.627Z"
}
```

`output` is a single URL string pointing to the processed video in the format set by `video_output_type`.

### 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 a missing `video` or a `variant` 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
Requests are rate limited to keep usage fair. If you receive a 429 response, wait and retry with exponential backoff.

## 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-background-removal-sprited-birefnet-video";

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: "d4fd02a2eaddddfd6fbe77570e7408b3f15ee4dcf2ded407ace7a0f9d114ae87", 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 = 900000;
  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 15 minutes");
}

createAndWaitForPrediction({
  "video": "https://blog.api.market/wp-content/uploads/2026/10/birefnet-video-input-w14-api-market.mp4",
  "variant": "toonout",
  "mask_blur": 0,
  "precision": "fp32",
  "refine_fg": true,
  "batch_size": 1,
  "resolution": 0,
  "mask_offset": 0,
  "output_format": "cutout",
  "video_quality": "high",
  "background_color": "#000000",
  "video_write_mode": "balanced",
  "video_output_type": "webm"
}).then((output) => console.log(output));
```

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

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/video-background-removal-sprited-birefnet-video"


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": "d4fd02a2eaddddfd6fbe77570e7408b3f15ee4dcf2ded407ace7a0f9d114ae87", "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 = 900
    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 15 minutes")


print(create_and_wait_for_prediction({
    "video": "https://blog.api.market/wp-content/uploads/2026/10/birefnet-video-input-w14-api-market.mp4",
    "variant": "toonout",
    "mask_blur": 0,
    "precision": "fp32",
    "refine_fg": True,
    "batch_size": 1,
    "resolution": 0,
    "mask_offset": 0,
    "output_format": "cutout",
    "video_quality": "high",
    "background_color": "#000000",
    "video_write_mode": "balanced",
    "video_output_type": "webm"
}))
```

## FAQ
- **Which output keeps transparency?**
  - `webm` (default) and `mov`. `mp4` has no alpha channel, so the cutout is placed on `background_color`; `gif` is palette-based.
- **Which `variant` should I pick?**
  - `general` is the all-purpose default and `toonout` is fine-tuned for anime and stylized footage. The other variants (such as `portrait`, `matting`, `dynamic` and the `lite` models) are specialized BiRefNet models; try them on a short clip first.
- **Can I get only the alpha matte?**
  - Yes. Set `output_format` to `mask` to receive the single-channel matte as a grayscale video.
- **Can I send an animated GIF?**
  - No. The `video` input accepts mp4, mov, webm and m4v files.
- **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`.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, adjust the input and try again.

## 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 video backgrounds frame by frame with 11 BiRefNet variants including ToonOut, as transparent WebM, MOV, MP4 or GIF. $0.097 per request.