​
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

​
Quick Navigation

​
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"
    }
  }'
ColorHex CodeUse Case
🔴 Red#FF0000Bold, attention-grabbing
🟢 Green#00FF00Chroma key standard
🔵 Blue#0000FFProfessional, clean
⚪ White#FFFFFFClean, minimal
⚫ Black#000000Dramatic, cinematic
🎨 Custom#7C3AEDAny 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

FormatFile SizeQualityUse CaseCompatibility
WebM VP9🟢 Small🟢 ExcellentEasy overlay, API usageRequires VP9 decoder
MOV ProRes🔴 Very Large🟢 PerfectLarge files, professional editingVideo editors
PNG Sequence🔴 Very Large🟢 PerfectGIF creation, frame-by-frameUniversal
Pro Bundle🟡 Medium🟢 PerfectUnscreen workflows, ZIP handlingUniversal
Stacked Video🟡 Medium🟢 PerfectUniversal, single file (top: video, bottom: mask)Universal
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

# 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!
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

# 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

​
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

# 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

​
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

# 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

​
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

# 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

​
Advanced Positioning & Scaling

​
Positioning Options

# 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

​
Format Recommendations

​
Choose Your Format

​
Testing Your Setup

Before processing videos, test your FFmpeg installation: 
# Check if libvpx-vp9 decoder is available
ffmpeg -decoders | grep libvpx-vp9

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

​
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: 
#!/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"
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!