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