API & SDK Documentation for Video Background Removal with AI

Overview

The VideoBGRemoverClient handles all communication with the VideoBGRemover API for background removal operations. This is the API layer of the SDK - it handles authentication, job management, and credit tracking.

API Layer: This class makes HTTP requests to our servers and consumes credits. For local video composition (no credits), see Composition.

Constructor

Node.js
Python

import { VideoBGRemoverClient } from '@videobgremover/sdk'

// Basic initialization
const client = new VideoBGRemoverClient('vbr_your_api_key')

// With custom options
const client = new VideoBGRemoverClient('vbr_your_api_key', {
  baseUrl: 'https://api.videobgremover.com', // Custom API endpoint
  timeout: 60000, // 60 second timeout
  headers: { 'Custom-Header': 'value' }
})

from videobgremover import VideoBGRemoverClient

# Basic initialization
client = VideoBGRemoverClient('vbr_your_api_key')

# With custom options
client = VideoBGRemoverClient(
    'vbr_your_api_key',
    base_url='https://api.videobgremover.com',  # Custom API endpoint
    timeout=60.0  # 60 second timeout
)

Parameters

Parameter	Type	Description
`api_key`	`string`	Your VideoBGRemover API key (format: `vbr_` + 32 characters)
`options.baseUrl`	`string`	API base URL (default: production)
`options.timeout`	`number`	Request timeout in milliseconds (Node.js) or seconds (Python)
`options.headers`	`object`	Additional HTTP headers

Methods

credits()

Check your current credit balance.

Node.js
Python

const credits = await client.credits()

console.log(`Total: ${credits.totalCredits}`)
console.log(`Remaining: ${credits.remainingCredits}`)
console.log(`Used: ${credits.usedCredits}`)

Returns: Promise<Credits>

interface Credits {
  totalCredits: number
  remainingCredits: number
  usedCredits: number
}

credits = client.credits()

print(f"Total: {credits.total_credits}")
print(f"Remaining: {credits.remaining_credits}")
print(f"Used: {credits.used_credits}")

Returns: CreditBalance

class CreditBalance:
    total_credits: int
    remaining_credits: int
    used_credits: int

Low-Level API Methods

These methods provide direct access to the REST API. Most users should use the high-level Video.removeBackground() method instead.

createJobFile()

Create a job for file upload.

Node.js
Python

const job = await client.createJobFile({
  filename: 'my-video.mp4',
  content_type: 'video/mp4'
})

console.log('Job ID:', job.id)
console.log('Upload URL:', job.upload_url)
console.log('Expires:', job.expires_at)

from videobgremover.client.models import CreateJobFileUpload

job = client.create_job_file(CreateJobFileUpload(
    filename='my-video.mp4',
    content_type='video/mp4'
))

print(f"Job ID: {job['id']}")
print(f"Upload URL: {job['upload_url']}")

createJobUrl()

Create a job for URL download.

Node.js
Python

const job = await client.createJobUrl({
  video_url: 'https://example.com/video.mp4'
})

console.log('Job ID:', job.id)
// Video downloads automatically

from videobgremover.client.models import CreateJobUrlDownload

job = client.create_job_url(CreateJobUrlDownload(
    video_url='https://example.com/video.mp4'
))

print(f"Job ID: {job['id']}")

startJob()

Start processing a job.

Node.js
Python

// Start with default settings (green screen)
const result = await client.startJob(jobId)

// Start with transparent output
const result = await client.startJob(jobId, {
  background: {
    type: 'transparent',
    transparent_format: 'webm_vp9'
  }
})

// Start with color background
const result = await client.startJob(jobId, {
  background: {
    type: 'color',
    color: '#FF0000'
  }
})

from videobgremover.client.models import StartJobRequest, BackgroundOptions

# Start with default settings (green screen)
result = client.start_job(job_id)

# Start with transparent output
result = client.start_job(job_id, StartJobRequest(
    background=BackgroundOptions(
        type='transparent',
        transparent_format='webm_vp9'
    )
))

# Start with color background
result = client.start_job(job_id, StartJobRequest(
    background=BackgroundOptions(
        type='color',
        color='#FF0000'
    )
))

status()

Check job processing status.

Node.js
Python

const status = await client.status(jobId)

console.log('Status:', status.status) // 'created', 'processing', 'completed', 'failed'
console.log('Message:', status.message)

if (status.status === 'completed') {
  console.log('Download URL:', status.processed_video_url)
}

status = client.status(job_id)

print(f'Status: {status.status}')  # 'created', 'processing', 'completed', 'failed'
print(f'Message: {status.message}')

if status.status == 'completed':
    print(f'Download URL: {status.processed_video_url}')

wait()

Wait for a job to complete with polling.

Node.js
Python

// Wait with default settings
const finalStatus = await client.wait(jobId)

// Wait with custom options
const finalStatus = await client.wait(jobId, {
  pollSeconds: 3.0,     // Check every 3 seconds
  timeout: 300,         // 5 minute timeout
  onStatus: (status) => {
    console.log(`Current status: ${status}`)
  }
})

# Wait with default settings
final_status = client.wait(job_id)

# Wait with custom options
def status_callback(status):
    print(f'Current status: {status}')

final_status = client.wait(
    job_id,
    poll_seconds=3.0,     # Check every 3 seconds
    timeout=300,          # 5 minute timeout
    on_status=status_callback
)

deleteJob()

Delete a job and all associated files.

This action is permanent and cannot be undone. No credit refunds are provided.

Node.js
Python

const result = await client.deleteJob(jobId)

console.log('Deleted:', result.id)
console.log('Message:', result.message)

result = client.delete_job(job_id)

print(f"Deleted: {result['id']}")
print(f"Message: {result['message']}")

Returns: { id: string, message: string }

Field	Type	Description
`id`	`string`	ID of the deleted job
`message`	`string`	Confirmation message

Error Handling

The client throws specific exceptions for different error conditions:

Node.js
Python

import { 
  ApiError, 
  InsufficientCreditsError, 
  JobNotFoundError, 
  ProcessingError 
} from '@videobgremover/sdk'

try {
  const transparent = await video.removeBackground({ client })
} catch (error) {
  if (error instanceof InsufficientCreditsError) {
    console.log('❌ Not enough credits')
    console.log('Remaining:', error.remainingCredits)
  } else if (error instanceof JobNotFoundError) {
    console.log('❌ Job not found')
  } else if (error instanceof ProcessingError) {
    console.log('❌ Processing failed:', error.message)
  } else if (error instanceof ApiError) {
    console.log('❌ API error:', error.message)
  }
}

from videobgremover.client.models import (
    InsufficientCreditsError,
    JobNotFoundError, 
    ProcessingError,
    ApiError
)

try:
    transparent = video.remove_background(client)
except InsufficientCreditsError as e:
    print('❌ Not enough credits')
    print(f'Remaining: {e.remaining_credits}')
except JobNotFoundError:
    print('❌ Job not found')
except ProcessingError as e:
    print(f'❌ Processing failed: {e}')
except ApiError as e:
    print(f'❌ API error: {e}')

Usage with Video Class

The recommended way to use the client is through the Video class:

Node.js
Python

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

const client = new VideoBGRemoverClient('your_api_key')
const video = Video.open('path/to/video.mp4')

// High-level method (recommended)
const transparent = await video.removeBackground({ client })

// With options
const options = new RemoveBGOptions(Prefer.WEBM_VP9)
const transparent = await video.removeBackground({ client, options })

from videobgremover import VideoBGRemoverClient, Video, RemoveBGOptions, Prefer

client = VideoBGRemoverClient('your_api_key')
video = Video.open('path/to/video.mp4')

# High-level method (recommended)
transparent = video.remove_background(client)

# With options
options = RemoveBGOptions(prefer=Prefer.WEBM_VP9)
transparent = video.remove_background(client, options)

Best Practices

Credit Management

// Always check credits before processing
const credits = await client.credits()
if (credits.remainingCredits < videoLengthInSeconds) {
  throw new Error('Not enough credits for this video')
}

Error Recovery

// Implement retry logic for network issues
async function removeBackgroundWithRetry(video, client, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await video.removeBackground({ client })
    } catch (error) {
      if (error instanceof InsufficientCreditsError) {
        throw error // Don't retry credit issues
      }
      if (i === maxRetries - 1) throw error
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)))
    }
  }
}

Timeout Handling

// Use appropriate timeouts for long videos
const client = new VideoBGRemoverClient('your_key', {
  timeout: 120000 // 2 minutes for long videos
})

Video: Video loading and background removal
Composition: Local video composition
EncoderProfile: Export format configuration

Getting Started

Guides

API Reference

SDK Reference

Examples & Integrations

VideoBGRemoverClient - Complete SDK API Reference

Overview

Constructor

Parameters

Methods

credits()

Low-Level API Methods

createJobFile()

createJobUrl()

startJob()

status()

wait()

deleteJob()

Error Handling

Usage with Video Class

Best Practices

Credit Management

Error Recovery

Timeout Handling

Getting Started

Guides

API Reference

SDK Reference

Examples & Integrations

​Overview

​Constructor

​Parameters

​Methods

​credits()

​Low-Level API Methods

​createJobFile()

​createJobUrl()

​startJob()

​status()

​wait()

​deleteJob()

​Error Handling

​Usage with Video Class

​Best Practices

​Credit Management

​Error Recovery

​Timeout Handling

​Related Classes

Overview

Constructor

Parameters

Methods

credits()

Low-Level API Methods

createJobFile()

createJobUrl()

startJob()

status()

wait()

deleteJob()

Error Handling

Usage with Video Class

Best Practices

Credit Management

Error Recovery

Timeout Handling

Related Classes