​
Overview

The VideoBGRemover API supports two distinct workflows for processing videos:

📁 File Upload

Best for local files, server-side processing, or when you have direct file access.

🌐 URL Download

Best for videos already hosted online (S3, CDN, direct links).

​
File Upload Workflow

​
When to Use

  • Processing videos from your local device
  • Server-side applications with file storage
  • When you have direct access to video files
  • Maximum control over upload process

​
Step-by-Step Process

1

Create Job

POST /v1/jobs
{
  "filename": "my-video.mp4",
  "content_type": "video/mp4"
}
Response: Upload URL and job ID
2

Upload Video

PUT [upload_url]
Content-Type: video/mp4
[Raw video file bytes]
Note: This is a direct upload to Google Cloud Storage
3

Start Processing

POST /v1/jobs/{id}/start
{
  "background": {
    "type": "transparent",
    "transparent_format": "webm_vp9"
  }
}
Credits deducted here based on video length
4

Monitor & Download

GET /v1/jobs/{id}/status
Poll until status is completed, then download from provided URLs

​
Complete Example

# 1. 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.mp4", "content_type": "video/mp4"}')

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

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

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

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

​
URL Download Workflow

​
When to Use

  • Videos hosted on S3, CDN, or public URLs
  • Webhook-based processing
  • When you want to avoid handling file uploads
  • Simpler integration with fewer steps

​
Requirements

  • Video must be publicly accessible (no authentication required)
  • Supported formats: MP4, MOV, AVI
  • Maximum file size: 100MB

​
Step-by-Step Process

1

Create Job from URL

POST /v1/jobs
{
  "video_url": "https://example.com/video.mp4"
}
Response: Job ID with uploaded status (ready to process)
2

Start Processing

POST /v1/jobs/{id}/start
{
  "background": {
    "type": "color",
    "color": "#FF0000"
  }
}
Credits deducted here based on video length
3

Monitor & Download

GET /v1/jobs/{id}/status
Poll until status is completed, then download from provided URLs

​
Complete Example

# 1. Create job from URL (video downloads automatically)
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 immediately
curl -X POST https://api.videobgremover.com/v1/jobs/$JOB_ID/start \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

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

​
Workflow Comparison

FeatureFile UploadURL Download
Steps4 steps3 steps
ComplexityHigherLower
File AccessDirectMust be public
Upload ControlFull controlAutomatic
Use CaseLocal filesHosted videos
Error HandlingUpload + processingProcessing only

​
Common Patterns

​
Batch Processing

# Process multiple videos
for video in *.mp4; do
  # Create job
  JOB_ID=$(create_job "$video")
  
  # Upload (file workflow) or skip (URL workflow)
  upload_video "$video" "$JOB_ID"
  
  # Start processing
  start_processing "$JOB_ID"
  
  # Add to monitoring queue
  echo "$JOB_ID" >> jobs_to_monitor.txt
done

​
Webhook Integration

// Webhook receives video URL
app.post('/webhook/new-video', async (req, res) => {
  const { video_url } = req.body;
  
  // Use URL workflow for immediate processing
  const job = await createJob({ video_url });
  await startProcessing(job.id);
  
  res.json({ job_id: job.id });
});

​
Error Handling

Both workflows share the same error handling for processing, but file upload has additional upload-related errors:

​
File Upload Specific Errors

  • Upload URL expired (1 hour limit)
  • File size too large (100MB limit)
  • Upload failed (network issues)

​
Common Processing Errors

  • Insufficient credits (402 Payment Required)
  • Unsupported format (400 Bad Request)
  • Job not found (404 Not Found)
For complete error scenarios and solutions, check the error responses in each API endpoint documentation.