Skip to main content

​
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' }
})

​
Parameters

ParameterTypeDescription
api_keystringYour VideoBGRemover API key (format: vbr_ + 32 characters)
options.baseUrlstringAPI base URL (default: production)
options.timeoutnumberRequest timeout in milliseconds (Node.js) or seconds (Python)
options.headersobjectAdditional 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
}

​
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)

​
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

​
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'
  }
})

​
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)
}

​
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}`)
  }
})

​
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)
  }
}

​
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 })

​
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
})