API Reference
Public API v1 Jobs
Authenticated jobs API for external customers.
Endpoints
| Endpoint | Method | Description |
|---|---|---|
| /v1/jobs | POST | Create job (supports auto_start) |
| /v1/jobs/{job_id}/start | POST | Start pending job |
| /v1/jobs/{job_id} | GET | Get job details |
| /v1/jobs | GET | List jobs (limit/offset/status) |
Create Job
curl -X POST https://api.removebgvideo.com/v1/jobs \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://cdn.example.com/input.mp4",
"model": "original",
"bg_type": "green",
"output_format": "webm",
"auto_start": true
}'Get Job
curl -X GET https://api.removebgvideo.com/v1/jobs/{job_id} \
-H "X-Api-Key: YOUR_API_KEY"Job Response Fields
| Field | Description |
|---|---|
| id | Job identifier |
| status | created | processing | completed | failed |
| output_url | Output URL when completed |
| webhook_url | Configured callback URL |
| webhook_events | Per-event delivery state (sent/failed) |
List Jobs
curl -X GET "https://api.removebgvideo.com/v1/jobs?limit=20&offset=0" \
-H "X-Api-Key: YOUR_API_KEY"Access Control
- Each API key can only access jobs created by that same key.
- Cross-key job access returns not_found behavior.
API Contract Notes
- All clients should handle non-2xx responses as structured error payloads.
- Use explicit JSON schema validation for request payloads on your side.
- Treat output_url as an asynchronous artifact and not an immediate response contract.
- Persist job lifecycle state transitions for auditing and support.
Integration Verification
| Check | How to Verify |
|---|---|
| Authentication | Call endpoint with valid and invalid key, confirm 200 vs 401 |
| Rate limits | Burst test and confirm 429 handling with backoff |
| Idempotency | Retry same request and verify no duplicate side effects |
| Observability | Confirm request_id/job_id appears in logs and dashboards |
Jobs Contract Examples
| Operation | Minimal Required Fields |
|---|---|
| Create | video_url + model/output defaults |
| Start | job_id + model/background/composition override |
| Get/List | X-Api-Key + job identifier/filter params |