Name: Video Matting – Remove Backgrounds | Free · $5/mo | API.market
Brand: magicapi
SKU: api-magicapi-video-foreground-extraction-api
Availability: InStock
Rating: 5.00 (1 reviews)
Author: API Market

Shashank Agarwal

# 🎬 Video Foreground Extraction API – Fast, Accurate Results (Robust Video Matting)

## Overview
This API provides a powerful solution for extracting moving subjects from videos with high accuracy. Whether you need to replace backgrounds, add special effects, or perform other video manipulations, this model offers an efficient way to isolate the foreground from any video source. Designed for speed and precision, the API is ideal for professionals and enthusiasts in film, video editing, social media content creation, and more.

![Example input video showing a moving subject](https://replicate.delivery/pbxt/HqiGGuuwynO7sCHpcQdYQsIf04NotwOrDdbhBf4M6Pou6MGg/butter.mp4)

## Features
- Highly accurate foreground extraction for videos of various complexities
- Fast processing for quick turnarounds
- Allows output in multiple formats (green-screen, alpha-mask, or foreground-mask)
- Works seamlessly with video editing pipelines and special effects workflows
- Asynchronous processing to handle long or large video inputs efficiently

## Use Cases
1. Replacing the background of a talking-head or product demonstration video.  
2. Social media content creation, allowing creators to drop subjects into various creative backdrops.  
3. Film post-production workflows where time-saving automation is required for rotoscoping.  
4. Real-time broadcast overlays for live streaming events or news segments.  
5. E-learning video creation, seamlessly placing educators in front of digital backgrounds.

## Examples

Below are examples of input and output videos, illustrating how the API segments the core subject:

• Input video (original content with a moving subject):  
  ![Input video showing a person or object to be masked](https://replicate.delivery/pbxt/HqiGGuuwynO7sCHpcQdYQsIf04NotwOrDdbhBf4M6Pou6MGg/butter.mp4)

• Output video (green-screened result, allowing easy background replacement):  
  ![Output video showing the foreground subject with a green screen](https://replicate.delivery/pbxt/V3iFlL5JotpbLtkUqGcnrpsiRfXume3Jm0020Iu0hX0hBoDQA/green-screen.mp4)

## Pricing
• 1 API unit equals 1 video processed.  
• GET requests to check prediction status (GET /api/v1/magicapi/video-foreground-extraction-api/predictions/{id}) are free.  
• Different pricing tiers are available based on usage volume.  

Contact us for more details on pricing options tailored to your needs.

## API Documentation

### Base URL
All requests should be made to:
```
https://prod.api.market/api/v1/magicapi/video-foreground-extraction-api
```

### Authentication
Include your API key in the header of every request:
```
x-magicapi-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
This API relies on asynchronous processing for video predictions. The workflow is:

1. Submit a prediction request to the POST /predictions endpoint.  
2. Receive a unique prediction ID in the response.  
3. Poll the GET /predictions/{id} endpoint to check the status of your prediction.  
4. When the status is "succeeded," your video output is ready.  
5. Handle errors if the status becomes "failed," or if a timeout occurs.

Implementation guidelines for this workflow:
- Start polling 1 second after the initial response.  
- Continue polling every 1 second until completion.  
- Use a maximum timeout of 600 seconds (10 minutes).  
- End polling if status reaches "succeeded" or "failed," or if timeout is exceeded.

### Endpoints

#### 1. Create a Prediction
• Method: POST  
• URL: /api/v1/magicapi/video-foreground-extraction-api/predictions  

Request Body (JSON):
```json
{
  "input": {
    "input_video": "https://your-video-url-goes-here.mp4",
    "output_type": "green-screen"
  }
}
```
- input_video (string, required): The URL of the video to be processed.  
- output_type (string, optional): "green-screen", "alpha-mask", or "foreground-mask". Defaults to "green-screen".

Example Request (cURL):
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/video-foreground-extraction-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "input": {
      "input_video": "https://replicate.delivery/pbxt/HqiGGuuwynO7sCHpcQdYQsIf04NotwOrDdbhBf4M6Pou6MGg/butter.mp4",
      "output_type": "green-screen"
    }
  }'
```

Expected Response (201 Created on success):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "73d2128a371922d5d1abf0712a1d974be0e4e2358cc1218e4e34714767232bac",
  "status": "starting",
  "created_at": "2025-04-21T10:44:07.040Z"
}
```
- id: Unique identifier for the prediction.  
- status: Indicates the initial status of the prediction.

#### 2. Check Prediction Status
• Method: GET  
• URL: /api/v1/magicapi/video-foreground-extraction-api/predictions/{id}  

Path Parameter:  
• id (string, required): The unique ID returned from the create prediction step.

Example Request (cURL):
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/video-foreground-extraction-api/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

Example Response (200 OK when successful):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://replicate.delivery/pbxt/V3iFlL5JotpbLtkUqGcnrpsiRfXume3Jm0020Iu0hX0hBoDQA/green-screen.mp4",
  "created_at": "2023-01-01T12:00:00.000Z",
  "started_at": "2023-01-01T12:00:05.000Z",
  "completed_at": "2023-01-01T12:01:00.000Z"
}
```
- status: "starting", "processing", "succeeded", "failed", or "canceled".  
- output: The URL of the processed video (if successful).

## Status Codes
Below are the primary status codes you may encounter:

- 200 OK: Request succeeded.  
- 201 Created: The resource (prediction) was successfully created.  
- 400 Bad Request: Missing or invalid parameters in the request body.  
- 401 Unauthorized: Invalid or missing API key in the request header.  
- 403 Forbidden: The request is understood but not allowed.  
- 404 Not Found: The requested resource (prediction ID, etc.) was not found.  
- 429 Too Many Requests: You have exceeded a rate limit.  
- 500 Internal Server Error: An unexpected error occurred on the server.  
- 503 Service Unavailable: The service is currently unavailable.

## Rate Limits
The API enforces rate limits based on your plan. If you encounter a 429 Too Many Requests error, reduce the request frequency or upgrade your plan to a higher tier.

## Error Handling
When an error occurs, an appropriate JSON response is returned:

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'input_video' is required",
    "status": 400
  }
}
```

• Retry Strategy:  
  - If the error is due to rate limiting (429), implement exponential backoff before retrying.  
  - If the error indicates invalid input (400), review your request parameters.  
  - If the server error (500 or 503) persists, wait and retry or contact support.

## Implementation Guide

### Example Code

Below are examples in JavaScript, Python, and cURL.

#### JavaScript (Node.js)
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/video-foreground-extraction-api";

async function createAndWaitForPrediction(inputData) {
  try {
    // Step 1: Create the prediction
    const response = await fetch(`${baseUrl}/predictions`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-magicapi-key": apiKey
      },
      body: JSON.stringify({ input: inputData })
    });

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

    const prediction = await response.json();
    const predictionId = prediction.id;

    // Step 2: Poll for results with timeout
    return await pollForResults(predictionId);
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function pollForResults(predictionId) {
  const MAX_TIMEOUT = 600000; // 600 seconds (10 minutes)
  const POLL_INTERVAL = 1000; // 1 second

  const startTime = Date.now();

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

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

    const prediction = await response.json();

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

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

    await delay(POLL_INTERVAL);
  }

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

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

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/video-foreground-extraction-api"

def create_and_wait_for_prediction(input_data):
    headers = {
        "Content-Type": "application/json",
        "x-magicapi-key": API_KEY
    }

    # Step 1: Create the prediction
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"input": input_data}
    )

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

    prediction = response.json()
    prediction_id = prediction["id"]

    # Step 2: Poll for results with timeout
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 600 seconds (10 minutes)
    POLL_INTERVAL = 1  # 1 second
    start_time = time.time()

    headers = {"x-magicapi-key": API_KEY}

    while time.time() - start_time < MAX_TIMEOUT:
        # Check prediction status
        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"] == "failed":
            raise Exception(f"Prediction failed: {prediction.get('error', 'Unknown error')}")

        time.sleep(POLL_INTERVAL)

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

#### cURL

```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/video-foreground-extraction-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "input": {
      "input_video": "https://replicate.delivery/pbxt/HqiGGuuwynO7sCHpcQdYQsIf04NotwOrDdbhBf4M6Pou6MGg/butter.mp4",
      "output_type": "green-screen"
    }
  }'

# Example response:
# {
#   "id": "ufawqhfynnddngldkgtslldrkq",
#   "status": "starting"
# }

# Step 2: Check prediction status
curl -X GET "https://prod.api.market/api/v1/magicapi/video-foreground-extraction-api/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"

# Poll until "status" changes to "succeeded" or "failed".
```

### Performance Optimization
- Reduce the size of input videos if possible (shorter clips or lower resolutions) to optimize processing time.  
- Poll at one-second intervals (as recommended) to limit overhead.  
- Cache results if you need repeated access to the same processed output.

## FAQ
1. Can I process multiple videos in parallel?  
   • Yes, you can submit multiple POST requests concurrently as long as you stay within rate limits.

2. What output formats are supported?  
   • You can specify "green-screen", "alpha-mask", or "foreground-mask" in your requests.

3. What happens if my video is very long?  
   • Longer videos might take substantially more time to process. Be sure to implement the asynchronous workflow and maintain your polling for up to 10 minutes.

4. Are the GET requests for checking status billed?  
   • No, status checks are free of charge.

5. Can I retrieve partial progress or partial results?  
   • Partial progress is not provided. You will receive the fully processed video when the status reaches "succeeded."

## 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[at]api.market.

Extract moving subjects and remove backgrounds from any video. Free 5 calls/mo, from $5/mo. Start free on API.market.

Video Matting – Remove Backgrounds | Free · $5/mo | API.market

🎬 Video Foreground Extraction API – Fast, Accurate Results (Robust Video Matting)

FREE

MagicAPI

PAYG

START

ULTRA

ELITE

MEGA

GIGA

BULK

Automatically extract moving subjects from videos with high accuracy and speed using Robust Video Matting—perfect for seamless backgrounds, effects, and video editing tools.