API Reference
Process Video
Create and start background removal job.
Endpoint
POST /v1/jobs
Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
| video_url | string | yes | Input video URL (from upload or external URL) |
| output_format | string | no | Default webm; webm/mov/mp4/gif/webp/png_sequence |
| bg_type | string | no | Default transparent; transparent/green/white/black/blue/custom |
| model | string | no | Default original; original/light/pro/human |
| text_prompt | string | no | Used with pro model |
| webhook_url | string | no | Receive job.started/completed/failed callbacks |
| bg_color | number[] | no | RGB array for custom background |
| auto_start | boolean | no | Default true; create draft job when false |
Example Request
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",
"background": { "type": "transparent" },
"output_format": "webm",
"auto_start": true
}'Response
| Field | Type | Description |
|---|---|---|
| success | boolean | Request accepted |
| id | string | Track this id for status polling |
| status | string | Initial status, usually processing |
| message | string | Submission result message |
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 |
Process Request Pattern
| Pattern | When to Use |
|---|---|
| Direct /api/process | Simple integrations and legacy compatibility |
| Draft + /v1/jobs/{job_id}/start | Enterprise workflows requiring pre-validation |