Getting Started

Public API Workflow

End-to-end /v1 workflow: create job, start processing, poll status, and download output.

4-Step Flow

Step	Endpoint	Purpose
1	POST /v1/jobs	Create a job and receive job_id
2	POST /v1/jobs/{job_id}/start	Start processing with model and composition config
3	GET /v1/jobs/{job_id}	Poll until completed or failed
4	Use output_url	Download or relay output to your users

1) Create Job

Create a draft job first when you need to configure model/composition separately at start time.

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",
    "output_format": "webm",
    "background": { "type": "transparent" },
    "auto_start": false
  }'

2) Start Job

Use the returned job_id from step 1.

This is the most common place to pass model, text_prompt, background, and composition.

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 }
      }
    }
  }'

3) Poll Status

Poll every 2-5 seconds. Add exponential backoff on 429 or transient 5xx errors.

curl -X GET https://api.removebgvideo.com/v1/jobs/{job_id} \
  -H "X-Api-Key: YOUR_API_KEY"

Production Notes

Store job_id, api_key_id (or key alias), and external request id for auditability.
Return 202/processing to your frontend and complete via webhook or background worker.
Treat output_url as time-bound and fetch to your own storage if long-term retention is required.

Production Readiness

Pin SDK/API versions in deployment manifests and release notes.
Record request_id/job_id in logs for every API interaction.
Run smoke tests after each deploy using a known short test video.
Separate dev/staging/prod keys and rotate keys regularly.

Tip: Treat docs examples as baseline templates; finalize payload defaults in your own backend policy layer.

Acceptance Checklist

Validate one success path and one failure path end-to-end.
Confirm credits, usage metrics, and output links are consistent.
Set retry and timeout policy for 429/5xx response handling.
Document rollback procedure for integration incidents.

Job State Machine

State	Meaning	Next
created	Job exists but not started	processing / failed
processing	Worker is running segmentation/composition	completed / failed
completed	Output generated and ready	terminal
failed	Processing stopped due to error	terminal (retry by new start flow)

Latency & Throughput Planning

Measure p50/p95 processing time per model and resolution.
Route burst traffic into queue workers, not sync request threads.
Use separate concurrency pools for pro vs light/human workloads.

Quick Start

Installation