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.
