API & SDK Documentation for Video Background Removal with AI

Choose Your Approach

There are two main ways to remove backgrounds from videos:

🛠️ SDK Method

Best for: Complete workflows, video composition Language: Node.js, Python Features: Automatic error handling, progress tracking

🌐 Direct API

Best for: Simple scripts, custom integrations Language: Any (HTTP requests) Features: Full control, webhook integration

SDK Method (Recommended)

The easiest way to get started with background removal:

Node.js
Python

import { VideoBGRemoverClient, Video, RemoveBGOptions, Prefer } from '@videobgremover/sdk'

const client = new VideoBGRemoverClient('vbr_your_api_key')

// Load video from file or URL
const video = Video.open('https://example.com/video.mp4')

// Configure output format (optional)
const options = new RemoveBGOptions(Prefer.WEBM_VP9)

// Remove background (handles everything automatically)
const transparent = await video.removeBackground({ client, options })

console.log('Background removed! Download URL:', transparent.primaryPath)
console.log('Format:', transparent.getFormat())

SDK Features

Automatic Error Handling: SDK catches and explains common errors
Progress Tracking: Optional callbacks for processing status
Format Selection: Easy format configuration
File Management: Handles uploads and downloads automatically

Direct API Method

For custom integrations and maximum control:

URL Workflow

Perfect when your videos are already hosted online:

Create Job from URL

POST /v1/jobs
{
  "video_url": "https://example.com/video.mp4"
}

Response: Job ID with uploaded status (ready to process)

Start Processing

POST /v1/jobs/{id}/start
{
  "background": {
    "type": "transparent",
    "transparent_format": "webm_vp9"
  }
}

Credits deducted here based on video length

Monitor & Download

GET /v1/jobs/{id}/status

Poll until status is completed, then download from provided URLs

Real-time Notifications with Webhooks

Instead of polling the status endpoint, get instant notifications when processing completes:

// Start processing with webhook notification
const result = await video.removeBackground({client, {
  webhookUrl: 'https://your-app.com/api/webhooks',
  background: {
    type: 'transparent',
    transparentFormat: 'webm_vp9'
  }
}})

console.log('✅ Job started! Webhook will notify when complete')

Webhook Payload:

{
  "event": "job.completed",
  "timestamp": "2025-10-02T10:30:00Z",
  "job": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "processed_video_url": "https://storage.googleapis.com/.../video.webm",
    // ... full job status (same as GET /v1/jobs/{id}/status)
  }
}

Your webhook endpoint must return a 2xx status code within 30 seconds. For detailed webhook implementation, see the webhook deliveries endpoint documentation.

File Upload Workflow

For local video files:

Create Job

POST /v1/jobs
{
  "filename": "my-video.mp4",
  "content_type": "video/mp4"
}

Response: Upload URL and job ID

Upload Video

PUT [upload_url]
Content-Type: video/mp4
[Raw video file bytes]

Note: This is a direct upload to cloud storage

Start Processing

POST /v1/jobs/{id}/start
{
  "background": {
    "type": "transparent",
    "transparent_format": "webm_vp9"
  }
}

Credits deducted here based on video length

Monitor & Download

GET /v1/jobs/{id}/status

Poll until status is completed, then download from provided URLs

Complete Examples

cURL - URL Workflow
cURL - File Upload Workflow
Node.js SDK - URL Workflow
Node.js SDK - File Workflow
Python SDK - URL Workflow
Python SDK - File Workflow

# 1. Create job from URL
JOB_RESPONSE=$(curl -s -X POST https://api.videobgremover.com/v1/jobs \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video_url": "https://example.com/video.mp4"}')

JOB_ID=$(echo $JOB_RESPONSE | jq -r '.id')

# 2. Start processing with color background
curl -X POST https://api.videobgremover.com/v1/jobs/$JOB_ID/start \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "background": {
      "type": "color",
      "color": "#FF0000"
    }
  }'

# 3. Check status
curl -X GET https://api.videobgremover.com/v1/jobs/$JOB_ID/status \
  -H "X-Api-Key: $API_KEY"

Error Handling

Common Issues

Insufficient Credits
Invalid API Key
File Too Large

try {
  const transparent = await video.removeBackground({ client })
} catch (error) {
  if (error.message.includes('credits')) {
    console.log('❌ Not enough credits. Please top up your account.')
  }
}

try:
    transparent = video.remove_background(client)
except Exception as e:
    if 'credits' in str(e).lower():
        print('❌ Not enough credits. Please top up your account.')

API-Specific Errors

Error Code	Description	Solution
`401`	Invalid API key	Check key format and permissions
`402`	Insufficient credits	Top up your account
`413`	File too large	Reduce file size or use URL workflow
`404`	Job not found	Verify job ID and API key match
`422`	Invalid parameters	Check request format

Background Options with cURL

Here are the correct cURL commands for different background types:

Color Backgrounds
Transparent Backgrounds

# Red background
curl -X POST https://api.videobgremover.com/v1/jobs/$JOB_ID/start \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "background": {
      "type": "color",
      "color": "#FF0000"
    }
  }'

# Green screen (chroma key)
curl -X POST https://api.videobgremover.com/v1/jobs/$JOB_ID/start \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "background": {
      "type": "color",
      "color": "#00FF00"
    }
  }'

# Blue background
curl -X POST https://api.videobgremover.com/v1/jobs/$JOB_ID/start \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "background": {
      "type": "color",
      "color": "#0000FF"
    }
  }'

Format Selection

Choose the format that best fits your workflow:

Format	Best For	File Size	SDK Support
WebM VP9	Web apps, APIs	Small	✅ Full support
MOV ProRes	Professional editing	Large	✅ Full support
Stacked Video	Universal compatibility	Medium	✅ Full support
Pro Bundle	Advanced workflows	Medium	✅ Full support
PNG Sequence	Frame-by-frame work	Large	✅ Full support

Note: For detailed technical usage of each format, see the Output Formats Guide.

Performance Tips

For Large Files

Use URL workflow for files >100MB
Process long videos in segments
Consider reducing resolution before processing

For Batch Processing

Process videos sequentially, not in parallel
Implement retry logic for network issues
Monitor credit usage to avoid depletion

For Production Use

Use webhooks for real-time notifications (see above)
Use background threads for processing
Implement proper error handling and retry logic
Store job IDs for status tracking
Monitor your credit usage and balance

Getting Started

Guides

API Reference

SDK Reference

Examples & Integrations

How to Remove Video Background | Guide

Choose Your Approach

🛠️ SDK Method

🌐 Direct API

SDK Method (Recommended)

SDK Features

Direct API Method

URL Workflow

Real-time Notifications with Webhooks

File Upload Workflow

Complete Examples

Error Handling

Common Issues

API-Specific Errors

Background Options with cURL

Format Selection

Performance Tips

For Large Files

For Batch Processing

For Production Use

What’s Next?

🎨 Add Custom Backgrounds

📖 Output Formats Guide

Getting Started

Guides

API Reference

SDK Reference

Examples & Integrations

​Choose Your Approach

🛠️ SDK Method

🌐 Direct API

​SDK Method (Recommended)

​SDK Features

​Direct API Method

​URL Workflow

​Real-time Notifications with Webhooks

​File Upload Workflow

​Complete Examples

​Error Handling

​Common Issues

​API-Specific Errors

​Background Options with cURL

​Format Selection

​Performance Tips

​For Large Files

​For Batch Processing

​For Production Use

​What’s Next?

🎨 Add Custom Backgrounds

📖 Output Formats Guide

Choose Your Approach

SDK Method (Recommended)

SDK Features

Direct API Method

URL Workflow

Real-time Notifications with Webhooks

File Upload Workflow

Complete Examples

Error Handling

Common Issues

API-Specific Errors

Background Options with cURL

Format Selection

Performance Tips

For Large Files

For Batch Processing

For Production Use

What’s Next?