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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "error": "Must provide either (filename + content_type) OR video_url"
}

401 Unauthorized

Invalid or missing API key:

{
  "error": "Invalid API key"
}

413 Payload Too Large

File exceeds the 1GB size limit:

{
  "error": "Video too large: 1250.5MB"
}

402 Payment Required

Insufficient credits for processing:

{
  "error": "Not enough credits available"
}

404 Not Found

Job ID doesn’t exist:

{
  "error": "Job not found"
}

Credit Balance Response

The /v1/credits endpoint returns:

{
  "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

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.

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

Error Handling: Always check the status field first. If it’s failed, check the message field for error details.

Getting Started

Guides

API Reference

SDK Reference

Examples & Integrations

API Response Reference - VideoBGRemover API

API Response Reference

Job Status Responses

Created Status

Processing Status

Completed Status (Default Green Screen)

Completed Status (Transparent WebM)

Failed Status

Error Responses

400 Bad Request

401 Unauthorized

413 Payload Too Large

402 Payment Required

404 Not Found

Credit Balance Response

Response Field Explanations

Important Notes

​API Response Reference

​Job Status Responses

​Created Status

​Processing Status

​Completed Status (Default Green Screen)

​Completed Status (Transparent WebM)

​Failed Status

​Error Responses

​400 Bad Request

​401 Unauthorized

​413 Payload Too Large

​402 Payment Required

​404 Not Found

​Credit Balance Response

​Response Field Explanations

​Important Notes

API Response Reference

Job Status Responses

Created Status

Processing Status

Completed Status (Default Green Screen)

Completed Status (Transparent WebM)

Failed Status

Error Responses

400 Bad Request

401 Unauthorized

413 Payload Too Large

402 Payment Required

404 Not Found

Credit Balance Response

Response Field Explanations

Important Notes