Public API Workflow

4-Step Flow

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.

Acceptance Checklist

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

Job State Machine

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.

When to Use Public API Workflow

Public API Workflow belongs to the Getting Started section and covers end-to-end /v1 workflow: create job, start processing, poll status, and download output.

The page is written for developers and operators who need predictable video background removal behavior in production, not just a one-off demo request.

• Use Public API Workflow when you are setting up a new RemoveBGVideo integration or onboarding another engineer.
• Convert each checklist item into a small staging test before enabling production traffic.
• Keep these defaults in your own backend configuration so UI clients do not need to understand every API detail.

Implementation Notes

Before you promote this workflow, test it with at least one short clip, one longer clip, and one visually difficult clip from your actual product or customer segment.

For support and debugging, persist the original input reference, selected model, output format, credit usage, and final job status alongside your internal user or project id.

• Do not ship with a personal sandbox API key in production.
• Do not skip failure-path testing; invalid files, insufficient credits, and transient worker errors need visible handling.
• Do not hardcode model and output defaults in multiple services without one owner for changes.

Related Documentation

FAQ