> ## Documentation Index
> Fetch the complete documentation index at: https://docs.videobgremover.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Remove Video Background | Guide

> Step-by-step guide to remove video backgrounds with AI. Learn SDK methods, API calls, and troubleshooting for professional video background removal.

## Choose Your Approach

There are two main ways to remove backgrounds from videos:

<CardGroup cols={2}>
  <Card title="🛠️ SDK Method" icon="code">
    **Best for**: Complete workflows, video composition
    **Language**: Node.js, Python
    **Features**: Automatic error handling, progress tracking
  </Card>

  <Card title="🌐 Direct API" icon="globe">
    **Best for**: Simple scripts, custom integrations
    **Language**: Any (HTTP requests)
    **Features**: Full control, webhook integration
  </Card>
</CardGroup>

## SDK Method (Recommended)

The easiest way to get started with background removal:

<Tabs group="code-examples">
  <Tab title="Node.js">
    ```typescript theme={"dark"}
    import { VideoBGRemoverClient, Video, RemoveBGOptions, Prefer } from '@videobgremover/sdk'

    const client = new VideoBGRemoverClient('vbr_your_api_key')

    // Load video from file or URL
    const video = Video.open('https://example.com/video.mp4')

    // Configure output format (optional)
    const options = new RemoveBGOptions(Prefer.WEBM_VP9)

    // Remove background (handles everything automatically)
    const transparent = await video.removeBackground({ client, options })

    console.log('Background removed! Download URL:', transparent.primaryPath)
    console.log('Format:', transparent.getFormat())
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"dark"}
    from videobgremover import VideoBGRemoverClient, Video, RemoveBGOptions, Prefer
    import os

    client = VideoBGRemoverClient(os.getenv('VIDEOBGREMOVER_API_KEY'))

    # Load video from file or URL
    video = Video.open('https://example.com/video.mp4')

    # Configure output format (optional)
    options = RemoveBGOptions(prefer=Prefer.WEBM_VP9)

    # Remove background (handles everything automatically)
    transparent = video.remove_background(client, options)

    print(f'Background removed! Download URL: {transparent.primary_path}')
    print(f'Format: {transparent.format}')
    ```
  </Tab>
</Tabs>

### SDK Features

* **Automatic Error Handling**: SDK catches and explains common errors
* **Progress Tracking**: Optional callbacks for processing status
* **Format Selection**: Easy format configuration
* **File Management**: Handles uploads and downloads automatically

## Direct API Method

For custom integrations and maximum control:

### URL Workflow

Perfect when your videos are already hosted online:

<Steps>
  <Step title="Create Job from URL">
    ```json theme={"dark"}
    POST /v1/jobs
    {
      "video_url": "https://example.com/video.mp4"
    }
    ```

    **Response:** Job ID with `uploaded` status (ready to process)
  </Step>

  <Step title="Start Processing">
    ```json theme={"dark"}
    POST /v1/jobs/{id}/start
    {
      "background": {
        "type": "transparent",
        "transparent_format": "webm_vp9"
      }
    }
    ```

    **Credits deducted here** based on video length
  </Step>

  <Step title="Monitor & Download">
    ```bash theme={"dark"}
    GET /v1/jobs/{id}/status
    ```

    Poll until status is `completed`, then download from provided URLs
  </Step>
</Steps>

## Real-time Notifications with Webhooks

Instead of polling the status endpoint, get instant notifications when processing completes:

<CodeGroup>
  ```typescript Node.js SDK theme={"dark"}
  // Start processing with webhook notification
  const result = await video.removeBackground({client, {
    webhookUrl: 'https://your-app.com/api/webhooks',
    background: {
      type: 'transparent',
      transparentFormat: 'webm_vp9'
    }
  }})

  console.log('✅ Job started! Webhook will notify when complete')
  ```

  ```python Python SDK theme={"dark"}
  # Start processing with webhook notification
  result = video.remove_background(client, RemoveBGOptions(
      webhook_url='https://your-app.com/api/webhooks',
      background_type='transparent',
      transparent_format='webm_vp9'
  ))

  print('✅ Job started! Webhook will notify when complete')
  ```

  ```bash cURL theme={"dark"}
  curl -X POST https://api.videobgremover.com/v1/jobs/$JOB_ID/start \
    -H "X-Api-Key: $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "webhook_url": "https://your-app.com/api/webhooks",
      "background": {
        "type": "transparent",
        "transparent_format": "webm_vp9"
      }
    }'
  ```
</CodeGroup>

**Webhook Payload:**

```json theme={"dark"}
{
  "event": "job.completed",
  "timestamp": "2025-10-02T10:30:00Z",
  "job": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "processed_video_url": "https://storage.googleapis.com/.../video.webm",
    // ... full job status (same as GET /v1/jobs/{id}/status)
  }
}
```

Your webhook endpoint must return a 2xx status code within 30 seconds. For detailed webhook implementation, see the [webhook deliveries endpoint documentation](/api-reference/all-endpoints).

### File Upload Workflow

For local video files:

<Steps>
  <Step title="Create Job">
    ```json theme={"dark"}
    POST /v1/jobs
    {
      "filename": "my-video.mp4",
      "content_type": "video/mp4"
    }
    ```

    **Response:** Upload URL and job ID
  </Step>

  <Step title="Upload Video">
    ```bash theme={"dark"}
    PUT [upload_url]
    Content-Type: video/mp4
    [Raw video file bytes]
    ```

    **Note:** This is a direct upload to cloud storage
  </Step>

  <Step title="Start Processing">
    ```json theme={"dark"}
    POST /v1/jobs/{id}/start
    {
      "background": {
        "type": "transparent",
        "transparent_format": "webm_vp9"
      }
    }
    ```

    **Credits deducted here** based on video length
  </Step>

  <Step title="Monitor & Download">
    ```bash theme={"dark"}
    GET /v1/jobs/{id}/status
    ```

    Poll until status is `completed`, then download from provided URLs
  </Step>
</Steps>

### Complete Examples

<Tabs group="code-examples">
  <Tab title="cURL - URL Workflow">
    ```bash theme={"dark"}
    # 1. Create 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": "https://example.com/video.mp4"}')

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

    # 2. Start processing with color background
    curl -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": "color",
          "color": "#FF0000"
        }
      }'

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

  <Tab title="cURL - File Upload Workflow">
    ```bash theme={"dark"}
    # 1. Create job for file upload
    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": "my-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 file
    curl -X PUT "$UPLOAD_URL" \
      -H "Content-Type: video/mp4" \
      --data-binary @my-video.mp4

    # 3. Start processing with transparent background
    curl -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"
        }
      }'

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

  <Tab title="Node.js SDK - URL Workflow">
    ```typescript theme={"dark"}
    import { VideoBGRemoverClient, Video } from '@videobgremover/sdk'

    const client = new VideoBGRemoverClient('vbr_your_api_key')
    const video = Video.open('https://example.com/video.mp4')

    const transparent = await video.removeBackground({ client })

    console.log('Background removed! Download URL:', transparent.primaryPath)
    console.log('Format:', transparent.getFormat())
    ```
  </Tab>

  <Tab title="Node.js SDK - File Workflow">
    ```typescript theme={"dark"}
    import { VideoBGRemoverClient, Video } from '@videobgremover/sdk'

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

    const transparent = await video.removeBackground({ client })

    console.log('Background removed! Download URL:', transparent.primaryPath)
    console.log('Format:', transparent.getFormat())
    ```
  </Tab>

  <Tab title="Python SDK - URL Workflow">
    ```python theme={"dark"}
    from videobgremover import VideoBGRemoverClient, Video
    import os

    client = VideoBGRemoverClient(os.getenv('VIDEOBGREMOVER_API_KEY'))
    video = Video.open(src='https://example.com/video.mp4')

    transparent = video.remove_background(client)

    print(f'Background removed! Download URL: {transparent.primary_path}')
    print(f'Format: {transparent.format}')
    ```
  </Tab>

  <Tab title="Python SDK - File Workflow">
    ```python theme={"dark"}
    from videobgremover import VideoBGRemoverClient, Video
    import os

    client = VideoBGRemoverClient(os.getenv('VIDEOBGREMOVER_API_KEY'))
    video = Video.open(src='path/to/local/video.mp4')

    transparent = video.remove_background(client)

    print(f'Background removed! Download URL: {transparent.primary_path}')
    print(f'Format: {transparent.format}')
    ```
  </Tab>
</Tabs>

## Error Handling

### Common Issues

<Tabs group="code-examples">
  <Tab title="Insufficient Credits">
    ```typescript theme={"dark"}
    try {
      const transparent = await video.removeBackground({ client })
    } catch (error) {
      if (error.message.includes('credits')) {
        console.log('❌ Not enough credits. Please top up your account.')
      }
    }
    ```

    ```python theme={"dark"}
    try:
        transparent = video.remove_background(client)
    except Exception as e:
        if 'credits' in str(e).lower():
            print('❌ Not enough credits. Please top up your account.')
    ```
  </Tab>

  <Tab title="Invalid API Key">
    ```typescript theme={"dark"}
    try {
      const transparent = await video.removeBackground({ client })
    } catch (error) {
      if (error.message.includes('API key')) {
        console.log('❌ Invalid API key. Check your credentials.')
      }
    }
    ```

    ```python theme={"dark"}
    try:
        transparent = video.remove_background(client)
    except Exception as e:
        if 'api key' in str(e).lower():
            print('❌ Invalid API key. Check your credentials.')
    ```
  </Tab>

  <Tab title="File Too Large">
    ```bash theme={"dark"}
    # Check file size before processing
    FILE_SIZE=$(stat -f%z video.mp4 2>/dev/null || stat -c%s video.mp4)
    MAX_SIZE=$((100*1024*1024)) # 100MB in bytes

    if [ "$FILE_SIZE" -gt "$MAX_SIZE" ]; then
      echo "❌ File too large: $FILE_SIZE bytes (max: $MAX_SIZE)"
      exit 1
    fi
    ```
  </Tab>
</Tabs>

### API-Specific Errors

| Error Code | Description          | Solution                             |
| ---------- | -------------------- | ------------------------------------ |
| `401`      | Invalid API key      | Check key format and permissions     |
| `402`      | Insufficient credits | Top up your account                  |
| `413`      | File too large       | Reduce file size or use URL workflow |
| `404`      | Job not found        | Verify job ID and API key match      |
| `422`      | Invalid parameters   | Check request format                 |

## Background Options with cURL

Here are the correct cURL commands for different background types:

<Tabs group="code-examples">
  <Tab title="Color Backgrounds">
    ```bash theme={"dark"}
    # Red background
    curl -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": "color",
          "color": "#FF0000"
        }
      }'

    # Green screen (chroma key)
    curl -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": "color",
          "color": "#00FF00"
        }
      }'

    # Blue background
    curl -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": "color",
          "color": "#0000FF"
        }
      }'
    ```
  </Tab>

  <Tab title="Transparent Backgrounds">
    ```bash theme={"dark"}
    # WebM VP9 (recommended)
    curl -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"
        }
      }'

    # MOV ProRes (professional editing)
    curl -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": "mov_prores"
        }
      }'

    # Stacked Video (universal compatibility)
    curl -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": "stacked_video"
        }
      }'
    ```
  </Tab>
</Tabs>

## Format Selection

Choose the format that best fits your workflow:

| Format            | Best For                | File Size | SDK Support    |
| ----------------- | ----------------------- | --------- | -------------- |
| **WebM VP9**      | Web apps, APIs          | Small     | ✅ Full support |
| **MOV ProRes**    | Professional editing    | Large     | ✅ Full support |
| **Stacked Video** | Universal compatibility | Medium    | ✅ Full support |
| **Pro Bundle**    | Advanced workflows      | Medium    | ✅ Full support |
| **PNG Sequence**  | Frame-by-frame work     | Large     | ✅ Full support |

**Note**: For detailed technical usage of each format, see the [Output Formats Guide](/video-background-removal/output-formats).

## Performance Tips

### For Large Files

* Use URL workflow for files >100MB
* Process long videos in segments
* Consider reducing resolution before processing

### For Batch Processing

* Process videos sequentially, not in parallel
* Implement retry logic for network issues
* Monitor credit usage to avoid depletion

### For Production Use

* Use webhooks for real-time notifications (see above)
* Use background threads for processing
* Implement proper error handling and retry logic
* Store job IDs for status tracking
* Monitor your credit usage and balance

## What's Next?

<CardGroup cols={2}>
  <Card title="🎨 Add Custom Backgrounds" icon="palette" href="/video-composition/backgrounds">
    Layer your transparent video with colors, images, or videos
  </Card>

  <Card title="📖 Output Formats Guide" icon="file-video" href="/video-background-removal/output-formats">
    Technical details for using different transparent video formats
  </Card>
</CardGroup>