API & SDK Documentation for Video Background Removal with AI

Overview

The VideoBGRemover API offers multiple background options for different use cases. This guide covers all formats and shows you how to use transparent videos in your own projects.

🎨 Color Backgrounds

Replace background with solid colors using hex codes

✨ Transparent Videos

Create videos with transparency for custom overlays

🎨 Color Backgrounds

Simple Colors
Popular Colors
Custom Hex Codes

✨ Transparent Formats

WebM VP9 (Recommended)
MOV ProRes (Professional)
PNG Sequence (Frame-by-Frame)
Pro Bundle (Advanced)
Stacked Video (Analysis)

Color Backgrounds

Perfect for simple background replacement with solid colors. No additional processing needed - just specify a hex color code.

Simple Color Replacement

Replace the background with any solid color using hex codes:

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

Popular Colors

Color	Hex Code	Use Case
🔴 Red	`#FF0000`	Bold, attention-grabbing
🟢 Green	`#00FF00`	Chroma key standard
🔵 Blue	`#0000FF`	Professional, clean
⚪ White	`#FFFFFF`	Clean, minimal
⚫ Black	`#000000`	Dramatic, cinematic
🎨 Custom	`#7C3AED`	Any hex code

Transparent Formats

For advanced compositing, custom backgrounds, and professional workflows. These formats preserve transparency for maximum flexibility. What are transparent formats? Video files that preserve the alpha channel (transparency) so you can overlay them on custom backgrounds. However, they can be tricky to use - WebM works in Chrome but not all browsers, MOV works in Safari but requires specific codecs. When you need custom backgrounds or advanced compositing, use transparent formats:

Format Comparison

Format	File Size	Quality	Use Case	Compatibility
WebM VP9	🟢 Small	🟢 Excellent	Easy overlay, API usage	Requires VP9 decoder
MOV ProRes	🔴 Very Large	🟢 Perfect	Large files, professional editing	Video editors
PNG Sequence	🔴 Very Large	🟢 Perfect	GIF creation, frame-by-frame	Universal
Pro Bundle	🟡 Medium	🟢 Perfect	Unscreen workflows, ZIP handling	Universal
Stacked Video	🟡 Medium	🟢 Perfect	Universal, single file (top: video, bottom: mask)	Universal

WebM VP9 (Recommended)

Best for: Easy overlay workflows, API usage, small file sizes

Decoder Required: WebM VP9 transparency requires libvpx-vp9 decoder. Works most of the time, but not guaranteed on all systems.

curl -X POST https://api.videobgremover.com/v1/jobs/YOUR_JOB_ID/start \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "background": {
      "type": "transparent",
      "transparent_format": "webm_vp9"
    }
  }'

Using WebM Videos in Your Projects

FFmpeg
Python

# Overlay WebM on custom background
ffmpeg -i background.jpg -i transparent_video.webm \
  -c:v libvpx-vp9 \
  -filter_complex "[1:v]setpts=PTS-STARTPTS[video]; \
                   [0:v][video]overlay=x=(W-w)/2:y=(H-h)/2:shortest=1" \
  -c:v libx264 -c:a aac output.mp4

Important: Use -c:v libvpx-vp9 decoder to preserve alpha channels!

import ffmpeg

# Load inputs
background = ffmpeg.input('background.jpg', loop=1)
video = ffmpeg.input('transparent_video.webm', **{'c:v': 'libvpx-vp9'})

# Normalize timestamps and overlay
video_norm = ffmpeg.filter(video, 'setpts', 'PTS-STARTPTS')
output = ffmpeg.overlay(background, video_norm, 
                       x='(W-w)/2', y='(H-h)/2', shortest=1)

# Export
ffmpeg.output(output, 'output.mp4', 
              vcodec='libx264', acodec='aac').run()

WebM Alpha Channel Issue: The default VP9 decoder strips alpha channels. Always use libvpx-vp9 decoder for proper transparency. If unavailable, use Stacked Video format instead.

MOV ProRes (Professional)

Best for: Professional video editing (Final Cut Pro, Premiere Pro)

curl -X POST https://api.videobgremover.com/v1/jobs/YOUR_JOB_ID/start \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "background": {
      "type": "transparent",
      "transparent_format": "mov_prores"
    }
  }'

Using MOV Videos

FFmpeg
Python

# Overlay MOV ProRes on background
ffmpeg -i background.jpg -i transparent_video.mov \
  -filter_complex "[1:v]setpts=PTS-STARTPTS[video]; \
                   [0:v][video]overlay=x=100:y=200:shortest=1" \
  -c:v libx264 -c:a aac output.mp4

import ffmpeg

background = ffmpeg.input('background.jpg', loop=1)
video = ffmpeg.input('transparent_video.mov')

# Position at specific coordinates
video_norm = ffmpeg.filter(video, 'setpts', 'PTS-STARTPTS')
output = ffmpeg.overlay(background, video_norm, 
                       x=100, y=200, shortest=1)

ffmpeg.output(output, 'output.mp4', 
              vcodec='libx264', acodec='aac').run()

PNG Sequence

Best for: GIF creation, frame-by-frame editing, maximum quality

curl -X POST https://api.videobgremover.com/v1/jobs/YOUR_JOB_ID/start \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "background": {
      "type": "transparent",
      "transparent_format": "png_sequence"
    }
  }'

Using PNG Sequences

FFmpeg
Python

# Extract ZIP and create video from PNG sequence
unzip png_sequence.zip -d frames/

# Overlay PNG sequence on background
ffmpeg -loop 1 -i background.jpg \
       -framerate 24 -i frames/frame_%04d.png \
       -filter_complex "[1:v]setpts=PTS-STARTPTS[video]; \
                        [0:v][video]overlay=x=(W-w)/2:y=(H-h)/2:shortest=1" \
       -c:v libx264 -t 5 output.mp4

import ffmpeg
import zipfile

# Extract PNG sequence
with zipfile.ZipFile('png_sequence.zip', 'r') as zip_ref:
    zip_ref.extractall('frames/')

# Create video from sequence
background = ffmpeg.input('background.jpg', loop=1)
frames = ffmpeg.input('frames/frame_%04d.png', framerate=24)

frames_norm = ffmpeg.filter(frames, 'setpts', 'PTS-STARTPTS')
output = ffmpeg.overlay(background, frames_norm, 
                       x='(W-w)/2', y='(H-h)/2', shortest=1)

ffmpeg.output(output, 'output.mp4', t=5, vcodec='libx264').run()

Pro Bundle (Professional Workflow)

Best for: Unscreen workflows, ZIP handling, maximum flexibility

curl -X POST https://api.videobgremover.com/v1/jobs/YOUR_JOB_ID/start \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "background": {
      "type": "transparent",
      "transparent_format": "pro_bundle"
    }
  }'

Pro Bundle Contents

The Pro Bundle ZIP contains:

color.mp4 - Normalized foreground video
alpha.mp4 - 8-bit grayscale matte
audio.m4a - Audio track (if present)
manifest.json - Technical specifications

Using Pro Bundle

FFmpeg
Python

# Extract bundle
unzip pro_bundle.zip -d bundle/

# Combine color and alpha for transparency
ffmpeg -i bundle/color.mp4 -i bundle/alpha.mp4 \
       -filter_complex "[0:v]format=rgba[color]; \
                        [1:v]format=gray[alpha]; \
                        [color][alpha]alphamerge[transparent]" \
       transparent_video.mov

# Overlay on background
ffmpeg -i background.jpg -i transparent_video.mov \
       -filter_complex "[1:v]setpts=PTS-STARTPTS[video]; \
                        [0:v][video]overlay=x=(W-w)/2:y=(H-h)/2:shortest=1" \
       -c:v libx264 -c:a aac final_output.mp4

import ffmpeg
import zipfile

# Extract bundle
with zipfile.ZipFile('pro_bundle.zip', 'r') as zip_ref:
    zip_ref.extractall('bundle/')

# Combine color and alpha
color = ffmpeg.input('bundle/color.mp4')
alpha = ffmpeg.input('bundle/alpha.mp4')

color_rgba = ffmpeg.filter(color, 'format', 'rgba')
alpha_gray = ffmpeg.filter(alpha, 'format', 'gray')
transparent = ffmpeg.filter([color_rgba, alpha_gray], 'alphamerge')

# Overlay on background
background = ffmpeg.input('background.jpg', loop=1)
transparent_norm = ffmpeg.filter(transparent, 'setpts', 'PTS-STARTPTS')

output = ffmpeg.overlay(background, transparent_norm, 
                       x='(W-w)/2', y='(H-h)/2', shortest=1)

ffmpeg.output(output, 'final_output.mp4', 
              vcodec='libx264', acodec='aac').run()

Stacked Video (Universal Format)

Best for: Universal compatibility, single file handling (top: video, bottom: mask)

curl -X POST https://api.videobgremover.com/v1/jobs/YOUR_JOB_ID/start \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "background": {
      "type": "transparent",
      "transparent_format": "stacked_video"
    }
  }'

Stacked Video Structure

Top Half: Original video (1080x1080)
Bottom Half: Grayscale mask (1080x1080)
Total Dimensions: 1080x2160 (2:1 aspect ratio)

Using Stacked Videos

FFmpeg
Python

# Extract and apply mask in one command
ffmpeg -i background.jpg -i stacked_video.mp4 \
  -filter_complex "
    [1:v]split=2[original][mask_source];
    [original]crop=1080:1080:0:0[top];
    [mask_source]crop=1080:1080:0:1080,format=gray,geq='if(gte(lum(X,Y),128),255,0)'[binary_mask];
    [top]format=rgba[top_rgba];
    [top_rgba][binary_mask]alphamerge[masked_video];
    [0:v][masked_video]overlay=x=(W-w)/2:y=(H-h)/2:shortest=1
  " \
  -c:v libx264 -c:a aac output.mp4

import ffmpeg

background = ffmpeg.input('background.jpg', loop=1)
stacked = ffmpeg.input('stacked_video.mp4')

# Extract top half (original video)
top = ffmpeg.filter(stacked, 'crop', 1080, 1080, 0, 0)
top_rgba = ffmpeg.filter(top, 'format', 'rgba')

# Extract bottom half (mask) and make binary
mask = ffmpeg.filter(stacked, 'crop', 1080, 1080, 0, 1080)
mask_gray = ffmpeg.filter(mask, 'format', 'gray')
binary_mask = ffmpeg.filter(mask_gray, 'geq', 
                            "if(gte(lum(X,Y),128),255,0)")

# Apply mask and overlay
masked_video = ffmpeg.filter([top_rgba, binary_mask], 'alphamerge')
masked_norm = ffmpeg.filter(masked_video, 'setpts', 'PTS-STARTPTS')

output = ffmpeg.overlay(background, masked_norm, 
                       x='(W-w)/2', y='(H-h)/2', shortest=1)

ffmpeg.output(output, 'output.mp4', 
              vcodec='libx264', acodec='aac').run()

Advanced Positioning & Scaling

Positioning Options

FFmpeg
Python

# Center position
overlay=x=(W-w)/2:y=(H-h)/2

# Top-left corner
overlay=x=0:y=0

# Top-right corner  
overlay=x=W-w:y=0

# Bottom-center
overlay=x=(W-w)/2:y=H-h

# Custom coordinates
overlay=x=100:y=200

# With scaling (50% size)
scale=iw*0.5:ih*0.5,overlay=x=(W-w)/2:y=(H-h)/2

import ffmpeg

# Scale video to 50% size
video_scaled = ffmpeg.filter(video, 'scale', 'iw*0.5', 'ih*0.5')

# Position options
positions = {
    'center': 'x=(W-w)/2:y=(H-h)/2',
    'top_left': 'x=0:y=0', 
    'top_right': 'x=W-w:y=0',
    'bottom_center': 'x=(W-w)/2:y=H-h',
    'custom': 'x=100:y=200'
}

# Apply overlay with position
output = ffmpeg.overlay(background, video_scaled, 
                       **{'x': '(W-w)/2', 'y': '(H-h)/2'})

Format Recommendations

Choose Your Format

🌐 Web Applications & APIs

Use WebM VP9 - Small files, excellent quality, but requires VP9 decoderFallback: Use Stacked Video if VP9 decoder unavailable

"transparent_format": "webm_vp9"

🎬 Professional Video Editing

Use MOV ProRes - Highest quality, works with all professional editors

"transparent_format": "mov_prores"

🔧 Custom Processing Workflows

Use Stacked Video - Universal compatibility, perfect for analysis

"transparent_format": "stacked_video"

🎯 Frame-by-Frame Work

Use PNG Sequence - Maximum quality, individual frame access

"transparent_format": "png_sequence"

⚡ Advanced Workflows

Use Pro Bundle - Complete separation of color, alpha, and audio

"transparent_format": "pro_bundle"

Testing Your Setup

Before processing videos, test your FFmpeg installation:

Test WebM Support
Python Test

# Check if libvpx-vp9 decoder is available
ffmpeg -decoders | grep libvpx-vp9

# Should output:
# V..... libvpx-vp9           libvpx VP9 (codec vp9)

import subprocess

def test_webm_support():
    try:
        result = subprocess.run(['ffmpeg', '-decoders'], 
                              capture_output=True, text=True)
        if 'libvpx-vp9' in result.stdout:
            print("✅ WebM alpha channels supported")
            return True
        else:
            print("❌ Use stacked video format instead")
            return False
    except:
        print("❌ FFmpeg not found")
        return False

test_webm_support()

Common Issues & Solutions

WebM Transparency Not Working

Problem: WebM video appears opaque instead of transparent Solution: Use the correct decoder

# ❌ Wrong - strips alpha channels
ffmpeg -i video.webm ...

# ✅ Correct - preserves alpha channels  
ffmpeg -c:v libvpx-vp9 -i video.webm ...

Timing Synchronization Issues

Problem: Video and background don’t sync properly Solution: Normalize timestamps

# Add this filter to your video stream
setpts=PTS-STARTPTS

Large File Sizes

Problem: MOV ProRes files are too large Solutions:

Smallest files: Use WebM format (10-50x smaller than MOV ProRes)
Universal compatibility: Use Stacked Video format (good balance of size and compatibility)

Complete Example Project

Here’s a complete example showing how to process a video and overlay it on a custom background:

Bash Script
Python Script

#!/bin/bash

API_KEY="vbr_your_api_key_here"
VIDEO_FILE="input.mp4"
BACKGROUND="custom_background.jpg"

# 1. Process video with API
echo "Processing video..."
JOB_RESPONSE=$(curl -s -X POST https://api.videobgremover.com/v1/jobs \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"filename\": \"$VIDEO_FILE\", \"content_type\": \"video/mp4\"}")

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

# Upload video
curl -X PUT "$UPLOAD_URL" -H "Content-Type: video/mp4" --data-binary @"$VIDEO_FILE"

# Start processing with WebM format
curl -s -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": "transparent", 
      "transparent_format": "webm_vp9"
    }
  }'

# Wait for completion and get result
while true; do
  STATUS=$(curl -s -X GET https://api.videobgremover.com/v1/jobs/$JOB_ID/status \
    -H "X-Api-Key: $API_KEY" | jq -r '.status')
  
  if [ "$STATUS" = "completed" ]; then
    WEBM_URL=$(curl -s -X GET https://api.videobgremover.com/v1/jobs/$JOB_ID/status \
      -H "X-Api-Key: $API_KEY" | jq -r '.processed_video_url')
    break
  fi
  sleep 10
done

# 2. Download transparent video
curl -o transparent_video.webm "$WEBM_URL"

# 3. Overlay on custom background
ffmpeg -i "$BACKGROUND" -i transparent_video.webm \
  -c:v libvpx-vp9 \
  -filter_complex "[1:v]setpts=PTS-STARTPTS[video]; \
                   [0:v][video]overlay=x=(W-w)/2:y=(H-h)/2:shortest=1" \
  -c:v libx264 -c:a aac final_result.mp4

echo "✅ Final video created: final_result.mp4"

import requests
import time
import ffmpeg

API_KEY = "vbr_your_api_key_here"

def process_video_with_api(video_file):
    # Create job
    response = requests.post(
        "https://api.videobgremover.com/v1/jobs",
        headers={"X-Api-Key": API_KEY, "Content-Type": "application/json"},
        json={"filename": video_file, "content_type": "video/mp4"}
    )
    job_data = response.json()
    
    # Upload video
    with open(video_file, 'rb') as f:
        requests.put(job_data['upload_url'], 
                    headers={"Content-Type": "video/mp4"}, 
                    data=f)
    
    # Start processing
    requests.post(
        f"https://api.videobgremover.com/v1/jobs/{job_data['id']}/start",
        headers={"X-Api-Key": API_KEY, "Content-Type": "application/json"},
        json={
            "background": {
                "type": "transparent",
                "transparent_format": "webm_vp9"
            }
        }
    )
    
    # Wait for completion
    while True:
        status_response = requests.get(
            f"https://api.videobgremover.com/v1/jobs/{job_data['id']}/status",
            headers={"X-Api-Key": API_KEY}
        )
        status_data = status_response.json()
        
        if status_data['status'] == 'completed':
            return status_data['processed_video_url']
        time.sleep(10)

def overlay_on_background(webm_url, background_image, output_file):
    # Download transparent video
    response = requests.get(webm_url)
    with open('transparent_video.webm', 'wb') as f:
        f.write(response.content)
    
    # Create overlay
    background = ffmpeg.input(background_image, loop=1)
    video = ffmpeg.input('transparent_video.webm', **{'c:v': 'libvpx-vp9'})
    
    video_norm = ffmpeg.filter(video, 'setpts', 'PTS-STARTPTS')
    output = ffmpeg.overlay(background, video_norm, 
                           x='(W-w)/2', y='(H-h)/2', shortest=1)
    
    ffmpeg.output(output, output_file, 
                  vcodec='libx264', acodec='aac').run(overwrite_output=True)

# Main workflow
webm_url = process_video_with_api('input.mp4')
overlay_on_background(webm_url, 'custom_background.jpg', 'final_result.mp4')
print("✅ Final video created: final_result.mp4")

This guide covers everything you need to work with transparent videos from the VideoBGRemover API. Choose the format that best fits your workflow and follow the examples for your preferred tool!

Getting Started

Guides

API Reference

SDK Reference

Examples & Integrations

Output Formats

Overview

🎨 Color Backgrounds

✨ Transparent Videos

Quick Navigation

Color Backgrounds

Simple Color Replacement

Popular Colors

Transparent Formats

Format Comparison

WebM VP9 (Recommended)

Using WebM Videos in Your Projects

MOV ProRes (Professional)

Using MOV Videos

PNG Sequence

Using PNG Sequences

Pro Bundle (Professional Workflow)

Pro Bundle Contents

Using Pro Bundle

Stacked Video (Universal Format)

Stacked Video Structure

Using Stacked Videos

Advanced Positioning & Scaling

Positioning Options

Format Recommendations

Choose Your Format

Testing Your Setup

Common Issues & Solutions

WebM Transparency Not Working

Timing Synchronization Issues

Large File Sizes

Complete Example Project

​Overview

🎨 Color Backgrounds

✨ Transparent Videos

​Quick Navigation

​Color Backgrounds

​Simple Color Replacement

​Popular Colors

​Transparent Formats

​Format Comparison

​WebM VP9 (Recommended)

​Using WebM Videos in Your Projects

​MOV ProRes (Professional)

​Using MOV Videos

​PNG Sequence

​Using PNG Sequences

​Pro Bundle (Professional Workflow)

​Pro Bundle Contents

​Using Pro Bundle

​Stacked Video (Universal Format)

​Stacked Video Structure

​Using Stacked Videos

​Advanced Positioning & Scaling

​Positioning Options

​Format Recommendations

​Choose Your Format

​Testing Your Setup

​Common Issues & Solutions

​WebM Transparency Not Working

​Timing Synchronization Issues

​Large File Sizes

​Complete Example Project

Overview

Quick Navigation

Color Backgrounds

Simple Color Replacement

Popular Colors

Transparent Formats

Format Comparison

WebM VP9 (Recommended)

Using WebM Videos in Your Projects

MOV ProRes (Professional)

Using MOV Videos

PNG Sequence

Using PNG Sequences

Pro Bundle (Professional Workflow)

Pro Bundle Contents

Using Pro Bundle

Stacked Video (Universal Format)

Stacked Video Structure

Using Stacked Videos

Advanced Positioning & Scaling

Positioning Options

Format Recommendations

Choose Your Format

Testing Your Setup

Common Issues & Solutions

WebM Transparency Not Working

Timing Synchronization Issues

Large File Sizes

Complete Example Project