cURL Examples

Prerequisites

Set your API key as an environment variable:

export API_KEY="vbr_your_api_key_here"

Method 1: File Upload Workflow

Complete Example Script

#!/bin/bash

# Set your API key
API_KEY="vbr_your_api_key_here"
VIDEO_FILE="my-video.mp4"

echo "🚀 Starting video background removal process..."

# Step 1: Create job and get upload URL
echo "📝 Creating job..."
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\"
  }")

echo "Job Response: $JOB_RESPONSE"

# Extract job ID and upload URL
JOB_ID=$(echo $JOB_RESPONSE | jq -r '.id')
UPLOAD_URL=$(echo $JOB_RESPONSE | jq -r '.upload_url')

echo "📋 Job ID: $JOB_ID"
echo "📤 Upload URL: $UPLOAD_URL"

# Step 2: Upload video file
echo "📤 Uploading video..."
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @"$VIDEO_FILE"

echo "✅ Video uploaded successfully"

# Step 3: Start processing
echo "⚡ Starting background removal..."
START_RESPONSE=$(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 '{}')

echo "Start Response: $START_RESPONSE"

# Step 4: Monitor status
echo "👀 Monitoring job status..."
while true; do
  STATUS_RESPONSE=$(curl -s -X GET https://api.videobgremover.com/v1/jobs/$JOB_ID/status \
    -H "X-Api-Key: $API_KEY")
  
  STATUS=$(echo $STATUS_RESPONSE | jq -r '.status')
  echo "Current status: $STATUS"
  
  if [ "$STATUS" = "completed" ]; then
    echo "🎉 Processing completed!"
    
    # Get download URLs
    PROCESSED_URL=$(echo $STATUS_RESPONSE | jq -r '.processed_video_url')
    MASK_URL=$(echo $STATUS_RESPONSE | jq -r '.processed_mask_url')
    
    echo "📥 Downloading processed video..."
    curl -o "processed_$VIDEO_FILE" "$PROCESSED_URL"
    
    echo "📥 Downloading mask video..."
    curl -o "mask_$VIDEO_FILE" "$MASK_URL"
    
    echo "✅ All done! Files saved as processed_$VIDEO_FILE and mask_$VIDEO_FILE"
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "❌ Processing failed"
    break
  else
    echo "⏳ Still processing... waiting 10 seconds"
    sleep 10
  fi
done

Step-by-Step Commands

Create Job

curl -X POST https://api.videobgremover.com/v1/jobs \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "my-video.mp4",
    "content_type": "video/mp4"
  }'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "created",
  "filename": "my-video.mp4",
  "upload_url": "https://storage.googleapis.com/...",
  "expires_at": "2024-12-28T15:30:00Z"
}

Upload Video

curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
  -H "Content-Type: video/mp4" \
  --data-binary @my-video.mp4

Note: Replace UPLOAD_URL_FROM_STEP_1 with the actual URL from the previous response.

Start Processing

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 '{}'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "credits_used": 30,
  "video_length_seconds": 30
}

Check Status

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

Response (Processing):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "message": "Video is being processed"
}

Response (Completed):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "processed_video_url": "https://storage.googleapis.com/...",
  "processed_mask_url": "https://storage.googleapis.com/...",
  "message": "Video processing completed successfully"
}

Method 2: URL Download Workflow

Complete Example Script

#!/bin/bash

# Set your API key and video URL
API_KEY="vbr_your_api_key_here"
VIDEO_URL="https://example.com/video.mp4"

echo "🚀 Starting URL-based video processing..."

# Step 1: Create job from URL (video downloads automatically)
echo "📝 Creating 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\": \"$VIDEO_URL\"
  }")

echo "Job Response: $JOB_RESPONSE"

# Extract job ID
JOB_ID=$(echo $JOB_RESPONSE | jq -r '.id')
echo "📋 Job ID: $JOB_ID"

# Step 2: Start processing immediately
echo "⚡ Starting background removal..."
START_RESPONSE=$(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 '{}')

echo "Start Response: $START_RESPONSE"

# Step 3: Monitor and download (same as file upload method)
echo "👀 Monitoring job status..."
while true; do
  STATUS_RESPONSE=$(curl -s -X GET https://api.videobgremover.com/v1/jobs/$JOB_ID/status \
    -H "X-Api-Key: $API_KEY")
  
  STATUS=$(echo $STATUS_RESPONSE | jq -r '.status')
  echo "Current status: $STATUS"
  
  if [ "$STATUS" = "completed" ]; then
    echo "🎉 Processing completed!"
    
    PROCESSED_URL=$(echo $STATUS_RESPONSE | jq -r '.processed_video_url')
    curl -o "processed_video.mp4" "$PROCESSED_URL"
    
    echo "✅ Downloaded processed video as processed_video.mp4"
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "❌ Processing failed"
    break
  else
    echo "⏳ Still processing... waiting 10 seconds"
    sleep 10
  fi
done

Background Options

Color Background

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"
    }
  }'

Transparent WebM

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"
    }
  }'

Professional ProRes

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"
    }
  }'

Pro Bundle (Complete Workflow)

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"
    }
  }'

Stacked Video (Analysis Format)

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"
    }
  }'

Utility Commands

Check Credit Balance

curl -X GET https://api.videobgremover.com/v1/credits \
  -H "X-Api-Key: $API_KEY"

Response:

{
  "user_id": "user-uuid",
  "total_credits": 100,
  "remaining_credits": 70,
  "used_credits": 30
}

Quick Status Check

# One-liner to check job status
curl -s -X GET https://api.videobgremover.com/v1/jobs/YOUR_JOB_ID/status \
  -H "X-Api-Key: $API_KEY" | jq -r '.status'

Error Handling Examples

Handle Insufficient Credits

START_RESPONSE=$(curl -s -w "%{http_code}" -X POST https://api.videobgremover.com/v1/jobs/$JOB_ID/start \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}')

HTTP_CODE="${START_RESPONSE: -3}"
RESPONSE_BODY="${START_RESPONSE%???}"

if [ "$HTTP_CODE" = "402" ]; then
  echo "❌ Insufficient credits. Please purchase more credits."
  echo "Error: $(echo $RESPONSE_BODY | jq -r '.error')"
elif [ "$HTTP_CODE" = "200" ]; then
  echo "✅ Processing started successfully"
else
  echo "❌ Error: HTTP $HTTP_CODE"
  echo "Response: $RESPONSE_BODY"
fi

Retry Logic with Exponential Backoff

check_status_with_retry() {
  local job_id=$1
  local max_retries=5
  local retry_count=0
  local wait_time=1

  while [ $retry_count -lt $max_retries ]; do
    STATUS_RESPONSE=$(curl -s -X GET https://api.videobgremover.com/v1/jobs/$job_id/status \
      -H "X-Api-Key: $API_KEY")
    
    if [ $? -eq 0 ]; then
      echo $STATUS_RESPONSE
      return 0
    else
      retry_count=$((retry_count + 1))
      echo "Retry $retry_count/$max_retries failed, waiting ${wait_time}s..."
      sleep $wait_time
      wait_time=$((wait_time * 2))
    fi
  done
  
  echo "Failed after $max_retries retries"
  return 1
}

Batch Processing

Process Multiple Videos

#!/bin/bash

API_KEY="vbr_your_api_key_here"
VIDEOS=("video1.mp4" "video2.mp4" "video3.mp4")
JOB_IDS=()

# Start all jobs
for video in "${VIDEOS[@]}"; do
  echo "Starting job for $video..."
  
  # Create job
  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\", \"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"
  
  # Start processing
  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 '{}'
  
  JOB_IDS+=($JOB_ID)
  echo "Job $JOB_ID started for $video"
done

# Monitor all jobs
echo "Monitoring ${#JOB_IDS[@]} jobs..."
for job_id in "${JOB_IDS[@]}"; do
  echo "Checking job $job_id..."
  # Add your status checking logic here
done

Tips and Best Practices

1. Use jq for JSON Processing

# Install jq if you don't have it
# macOS: brew install jq
# Ubuntu: sudo apt-get install jq

# Extract specific fields
JOB_ID=$(echo $RESPONSE | jq -r '.id')
STATUS=$(echo $RESPONSE | jq -r '.status')

2. Set Timeouts

# Add timeout to prevent hanging
curl --max-time 300 -X POST https://api.videobgremover.com/v1/jobs \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "video.mp4", "content_type": "video/mp4"}'

3. Save Responses for Debugging

# Save response to file for debugging
curl -X GET https://api.videobgremover.com/v1/jobs/$JOB_ID/status \
  -H "X-Api-Key: $API_KEY" \
  -o "status_response.json"

4. Progress Indication

# Show progress with dots
echo -n "Processing"
while [ "$STATUS" != "completed" ]; do
  echo -n "."
  sleep 5
  STATUS=$(curl -s -X GET https://api.videobgremover.com/v1/jobs/$JOB_ID/status \
    -H "X-Api-Key: $API_KEY" | jq -r '.status')
done
echo " Done!"

Getting Started

Guides

API Reference

Examples

Prerequisites

Method 1: File Upload Workflow

Complete Example Script

Step-by-Step Commands

Method 2: URL Download Workflow

Complete Example Script

Background Options

Color Background

Transparent WebM

Professional ProRes

Pro Bundle (Complete Workflow)

Stacked Video (Analysis Format)

Utility Commands

Check Credit Balance

Quick Status Check

Error Handling Examples

Handle Insufficient Credits

Retry Logic with Exponential Backoff

Batch Processing

Process Multiple Videos

Tips and Best Practices

1. Use jq for JSON Processing

2. Set Timeouts

3. Save Responses for Debugging

4. Progress Indication

Getting Started

Guides

API Reference

Examples

​Prerequisites

​Method 1: File Upload Workflow

​Complete Example Script

​Step-by-Step Commands

​Method 2: URL Download Workflow

​Complete Example Script

​Background Options

​Color Background

​Transparent WebM

​Professional ProRes

​Pro Bundle (Complete Workflow)

​Stacked Video (Analysis Format)

​Utility Commands

​Check Credit Balance

​Quick Status Check

​Error Handling Examples

​Handle Insufficient Credits

​Retry Logic with Exponential Backoff

​Batch Processing

​Process Multiple Videos

​Tips and Best Practices

​1. Use jq for JSON Processing

​2. Set Timeouts

​3. Save Responses for Debugging

​4. Progress Indication

Prerequisites

Method 1: File Upload Workflow

Complete Example Script

Step-by-Step Commands

Method 2: URL Download Workflow

Complete Example Script

Background Options

Color Background

Transparent WebM

Professional ProRes

Pro Bundle (Complete Workflow)

Stacked Video (Analysis Format)

Utility Commands

Check Credit Balance

Quick Status Check

Error Handling Examples

Handle Insufficient Credits

Retry Logic with Exponential Backoff

Batch Processing

Process Multiple Videos

Tips and Best Practices

1. Use jq for JSON Processing

2. Set Timeouts

3. Save Responses for Debugging

4. Progress Indication