API Reference
Start Job
Start a previously created v1 job and pass model/background/composition settings.
Endpoint
POST /v1/jobs/{job_id}/start
Headers
| Header | Required | Description |
|---|---|---|
| X-Api-Key | Yes | API authentication |
| Content-Type: application/json | Yes | JSON request body |
Request Fields
| Field | Required | Description |
|---|---|---|
| model | No | original | light | pro | human (uses job default when omitted) |
| text_prompt | No | Used by pro model for subject targeting |
| background | No | transparent | color | image settings |
| composition | No | Canvas + foreground placement config |
| preview_duration | No | Preview-only processing duration in seconds |
Example Request
curl -X POST https://api.removebgvideo.com/v1/jobs/{JOB_ID}/start \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "pro",
"text_prompt": "person, clothing accessories, glowing ring",
"background": { "type": "transparent" },
"composition": {
"canvas": { "width": 1920, "height": 1080 },
"foreground": {
"anchor": "center",
"scale": 1,
"offset": { "x": 0, "y": 0 }
}
}
}'Response
{
"success": true,
"id": "job_123",
"status": "processing",
"message": "Job started"
}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 |
Model/Feature Compatibility
| Model | text_prompt | Best Use Case |
|---|---|---|
| original | No | High quality general scenes |
| light | No | Fast/simple scenes |
| pro | Yes | Complex object targeting |
| human | No | Portrait and people workflows |
Server-side Validation Recommendations
- Reject unsupported model/output_format combinations early.
- Reject empty text_prompt when model=pro and prompt mode is required by your policy.
- Normalize composition defaults to avoid inconsistent render placement.