> ## 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.

# API Response Reference - VideoBGRemover API

> Complete guide to VideoBGRemover API response formats, status codes, and error handling. Learn to parse responses and handle job states effectively.

# API Response Reference

This page provides detailed examples of API responses to help you understand what to expect when integrating with the VideoBGRemover API.

## Job Status Responses

The `/v1/jobs/{id}/status` endpoint returns different response formats depending on the job's current state.

### Created Status

When a job is first created but processing hasn't started:

```json theme={"dark"}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "created",
  "filename": "my-video.mp4",
  "created_at": "2023-12-01T10:00:00Z",
  "length_seconds": null,
  "thumbnail_url": null,
  "processed_video_url": null,
  "message": null,
  "background": null,
  "output_format": null,
  "export_id": null
}
```

### Processing Status

When the video is being analyzed and processed:

```json theme={"dark"}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "filename": "my-video.mp4",
  "created_at": "2023-12-01T10:00:00Z",
  "length_seconds": 30.5,
  "thumbnail_url": "https://storage.googleapis.com/videobg-processed/550e8400-e29b-41d4-a716-446655440000_thumb.jpg?X-Goog-Expires=3600",
  "processed_video_url": null,
  "message": "Processing video with red background",
  "background": {
    "type": "color",
    "color": "#FF0000"
  },
  "output_format": "mp4",
  "export_id": "exp_red_bg_123"
}
```

### Completed Status (Default Green Screen)

When processing is complete with default settings:

```json theme={"dark"}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "filename": "my-video.mp4",
  "created_at": "2023-12-01T10:00:00Z",
  "length_seconds": 30.5,
  "thumbnail_url": "https://storage.googleapis.com/videobg-processed/550e8400-e29b-41d4-a716-446655440000_thumb.jpg?X-Goog-Expires=3600",
  "transparent_thumbnail_url": "https://storage.googleapis.com/videobg-processed/550e8400-e29b-41d4-a716-446655440000_transparent_thumb.png?X-Goog-Expires=3600",
  "processed_video_url": "https://storage.googleapis.com/videobg-processed/550e8400-e29b-41d4-a716-446655440000.mp4?X-Goog-Expires=3600",
  "processed_mask_url": "https://storage.googleapis.com/videobg-processed/550e8400-e29b-41d4-a716-446655440000_mask.mp4?X-Goog-Expires=3600",
  "message": "Processing completed successfully",
  "background": null,
  "output_format": null,
  "export_id": null
}
```

### Completed Status (Transparent WebM)

When processing is complete with transparent background:

```json theme={"dark"}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "filename": "my-video.mp4",
  "created_at": "2023-12-01T10:00:00Z",
  "length_seconds": 30.5,
  "thumbnail_url": "https://storage.googleapis.com/videobg-processed/550e8400-e29b-41d4-a716-446655440000_thumb.jpg?X-Goog-Expires=3600",
  "transparent_thumbnail_url": "https://storage.googleapis.com/videobg-processed/550e8400-e29b-41d4-a716-446655440000_transparent_thumb.png?X-Goog-Expires=3600",
  "processed_video_url": "https://storage.googleapis.com/videobg-processed/550e8400-e29b-41d4-a716-446655440000.webm?X-Goog-Expires=3600",
  "processed_mask_url": "https://storage.googleapis.com/videobg-processed/550e8400-e29b-41d4-a716-446655440000_mask.mp4?X-Goog-Expires=3600",
  "message": "Processing completed successfully",
  "background": {
    "type": "transparent",
    "transparent_format": "webm_vp9"
  },
  "output_format": "webm",
  "export_id": "exp_webm_vp9_456"
}
```

### Failed Status

When processing encounters an error:

```json theme={"dark"}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "filename": "my-video.mp4",
  "created_at": "2023-12-01T10:00:00Z",
  "length_seconds": null,
  "thumbnail_url": null,
  "processed_video_url": null,
  "message": "Video too large: 1250.5MB",
  "background": {
    "type": "color",
    "color": "#FF0000"
  },
  "output_format": "mp4",
  "export_id": "exp_red_bg_123"
}
```

## Error Responses

### 400 Bad Request

Invalid request parameters or malformed data:

```json theme={"dark"}
{
  "error": "Must provide either (filename + content_type) OR video_url"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={"dark"}
{
  "error": "Invalid API key"
}
```

### 413 Payload Too Large

File exceeds the 1GB size limit:

```json theme={"dark"}
{
  "error": "Video too large: 1250.5MB"
}
```

### 402 Payment Required

Insufficient credits for processing:

```json theme={"dark"}
{
  "error": "Not enough credits available"
}
```

### 404 Not Found

Job ID doesn't exist:

```json theme={"dark"}
{
  "error": "Job not found"
}
```

## Credit Balance Response

The `/v1/credits` endpoint returns:

```json theme={"dark"}
{
  "user_id": "usr_abc123def456",
  "total_credits": 1000,
  "remaining_credits": 750,
  "credits_used": 250
}
```

## Response Field Explanations

| Field                       | Type        | Description                                                               |
| --------------------------- | ----------- | ------------------------------------------------------------------------- |
| `id`                        | string      | Unique job identifier (UUID format)                                       |
| `status`                    | string      | Current processing status: `created`, `processing`, `completed`, `failed` |
| `filename`                  | string      | Original uploaded filename                                                |
| `created_at`                | string      | ISO 8601 timestamp of job creation                                        |
| `length_seconds`            | number/null | Video duration in seconds (null until analyzed)                           |
| `thumbnail_url`             | string/null | Signed URL for video thumbnail (expires in 1 hour)                        |
| `transparent_thumbnail_url` | string/null | Signed URL for transparent thumbnail                                      |
| `processed_video_url`       | string/null | Signed URL for processed video (expires in 1 hour)                        |
| `processed_mask_url`        | string/null | Signed URL for video mask                                                 |
| `message`                   | string/null | Human-readable status message                                             |
| `background`                | object/null | Background configuration used for processing                              |
| `output_format`             | string/null | Output video format (mp4, webm, etc.)                                     |
| `export_id`                 | string/null | Export identifier for custom background processing                        |

## Important Notes

<Warning>
  **Signed URLs Expire**: All `*_url` fields contain signed URLs that expire after 1 hour. Download files immediately or call the status endpoint again to get fresh URLs.
</Warning>

<Info>
  **Polling Frequency**: When monitoring job status, poll every 5-10 seconds. Faster polling may result in rate limiting.
</Info>

<Tip>
  **Error Handling**: Always check the `status` field first. If it's `failed`, check the `message` field for error details.
</Tip>