Backdrop API

Video background removal, built into your workflow.

Upload a video, start an asynchronous processing job, then download a transparent or composited result. The API uses JSON, Bearer keys, and signed storage URLs.

RESTJSONHTTPSAsync jobs

01
Reserve an upload
Create a signed slot, then send the file directly to storage.
02
Process the video
Choose transparent, colour, image, or alpha output and start a job.
03
Receive the result
Poll the job or verify a signed webhook, then fetch a fresh download URL.

Get started

Authentication

Backdrop authenticates API requests with keys beginning in vbr_live_. Send the key as a Bearer token on every request.

Keep keys on the server

Never place an API key in browser code, public repositories, mobile applications, or client-visible environment variables.

Create an API key

Get started

Quickstart

A complete integration has two uploads and one asynchronous job. File bytes go directly to signed storage, so they never pass through your application server or a Vercel Function.

Create an upload slot with the filename, content type, and byte size.
PUT the raw video to the returned upload_url before it expires.
Create a processing job using the returned upload_id.
Poll GET /v1/jobs/{id} or wait for a signed webhook.

Complete flow

export BASE="https://backdrop.softfieldlabs.com"
export API_KEY="vbr_live_..."
# 1. Reserve an upload slot
UPLOAD=$(curl -s -X POST "$BASE/v1/uploads" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"filename":"talk.mp4","content_type":"video/mp4","size_bytes":1234567}')
UPLOAD_ID=$(printf '%s' "$UPLOAD" | jq -r '.upload_id')
UPLOAD_URL=$(printf '%s' "$UPLOAD" | jq -r '.upload_url')
# 2. Upload the raw file bytes to upload_url
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: video/mp4" \
--data-binary @talk.mp4
# 3. Start background removal
JOB=$(curl -s -X POST "$BASE/v1/jobs" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d "{"upload_id":"$UPLOAD_ID","output_type":"transparent","duration_seconds":42}")
JOB_ID=$(printf '%s' "$JOB" | jq -r '.job.id')
# 4. Retrieve the current state (or poll until completed)
curl "$BASE/v1/jobs/$JOB_ID" \
-H "Authorization: Bearer $API_KEY"

API reference

Create an upload

POST/v1/uploads

Reserve a signed upload slot. Then send the raw file bytes to upload_url with a plain HTTP PUT. Slots expire after two hours.

Parameters

filenamestringrequired: The original filename. Backdrop sanitises it before storage.
content_typestringrequired: video/mp4, video/quicktime, video/webm, or video/x-m4v.
size_bytesintegerrequired: Exact file size in bytes. Videos are limited to 50 MB during beta.
kindstringoptional: video by default, or background for a JPEG, PNG, or WebP composite image.

Responses

201Upload slot created

400Invalid file metadata

401Invalid or missing API key

API reference

Create a job

POST/v1/jobs

Start background removal for an uploaded video. The job returns immediately in queued state while GPU processing continues asynchronously.

Parameters

upload_idstringrequired: The upload_id returned by POST /v1/uploads after the file has been uploaded.
output_typeenumrequired: transparent, color, image, or alpha. Transparent produces VP9 WebM with alpha.
background_colorstringrequired for color: A #RRGGBB colour such as #00b140.
background_image_idstringrequired for image: An upload_id created with kind: background.
qualityenumoptional: standard by default, or high for difficult edges and smaller subjects.
duration_secondsnumberrecommended: Used to reserve credits. The final charge settles to measured duration.
downsample_rationumberoptional: Advanced internal analysis scale from 0.1 to 1.0. Omit for automatic selection.
webhook_urlstringoptional: A public HTTPS URL that receives the signed terminal job event.

Responses

201Job queued

400Invalid processing options

402Not enough credits

503Processing service unavailable

Request

curl -X POST "https://backdrop.softfieldlabs.com/v1/jobs" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"upload_id": "usr_123/video/7ed4-talk.mp4",
"output_type": "transparent",
"quality": "standard",
"duration_seconds": 42,
"webhook_url": "https://example.com/webhooks/backdrop"
}'

201 Created

{
"job": {
"id": "fd0663e4-01e7-486c-92ec-9d7cdfbdbbb4",
"status": "completed",
"output_type": "transparent",
"quality": "standard",
"duration_seconds": 12.012,
"width": 854,
"height": 480,
"credits_used": 13,
"output_format": "webm",
"download_url": "https://storage.example/signed-download",
"error": null,
"created_at": "2026-07-15T08:31:31.720Z",
"completed_at": "2026-07-15T08:32:41.100Z"
}
}

API reference

Retrieve a job

GET/v1/jobs/{id}

Retrieve current processing state and metadata. Completed jobs include a signed download_url that remains valid for one hour.

Job lifecycle

queued

processing

encoding

completed

Refresh signed downloads

List responses omit download URLs. Retrieve the individual job whenever you need a fresh signed URL.

Responses

200Job retrieved

401Invalid or missing API key

404Job not found

API reference

List jobs

GET/v1/jobs

Return jobs newest first. List responses are intentionally compact and do not include signed download URLs.

Parameters

limitintegeroptional: Number of jobs to return. Defaults to 20 and is capped at 100.

Responses

200Jobs returned

API reference

Retrieve usage

GET/v1/usage

Retrieve the current credit balance, processing totals, and the fifty most recent credit ledger entries.

Failed jobs are refunded

Jobs charge one credit per measured second. System and processing failures return the reserved credits automatically.

Responses

200Usage summary returned

Webhooks

Event delivery

Add webhook_url when creating a job. Backdrop sends one immutable job.completed or job.failed event when processing reaches a terminal state.

Parameters

idstringstable: Unique event identifier. It remains unchanged across every retry.
typeenum: job.completed or job.failed.
created_attimestamp: When the terminal event was created in ISO 8601 format.
jobobject: The terminal job state. Fetch GET /v1/jobs/{id} for authoritative state and a fresh download URL.

At-least-once delivery

Event IDs and payloads stay stable across retries. Your receiver must deduplicate before applying side effects.

Webhooks

Verify signatures

Find the account signing secret in Dashboard → API keys. Compute HMAC-SHA256 over {id}.{timestamp}.{rawBody}, Base64-encode it, then compare it with the value after v1, using a constant-time comparison.

Read the exact raw request body before parsing JSON.
Reject timestamps more than five minutes from the current time.
Insert Webhook-Id under a unique constraint before applying side effects.
Return 200 for duplicate events without processing them again.
Respond with any 2xx status quickly, then perform slow work asynchronously.

Retry schedule

Network failures and non-2xx responses are retried after 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours. Six total delivery attempts are made.

verify-webhook.mjs

import {
createHmac,
timingSafeEqual,
} from "node:crypto";
export function verifyBackdropWebhook(rawBody, headers) {
const id = headers.get("webhook-id");
const timestamp = headers.get("webhook-timestamp");
const signature = headers.get("webhook-signature");
if (!id || !timestamp || !signature?.startsWith("v1,")) {
throw new Error("Missing signature headers");
}
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
throw new Error("Stale webhook timestamp");
}
const signed = `${id}.${timestamp}.${rawBody}`;
const expected = createHmac(
"sha256",
process.env.BACKDROP_WEBHOOK_SECRET,
).update(signed).digest();
const received = Buffer.from(signature.slice(3), "base64");
if (
received.length !== expected.length ||
!timingSafeEqual(received, expected)
) throw new Error("Invalid signature");
return JSON.parse(rawBody);
}

test-webhook.sh

export WEBHOOK_URL="https://example.com/webhooks/backdrop"
export WEBHOOK_SECRET="whsec_..."
WEBHOOK_ID="evt_test_123"
WEBHOOK_TIMESTAMP="$(date +%s)"
BODY='{"id":"evt_test_123","type":"job.completed","job":{"id":"job_test"}}'
SIGNATURE="$(printf '%s' "$WEBHOOK_ID.$WEBHOOK_TIMESTAMP.$BODY" \
| openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -binary \
| openssl base64 -A)"
curl -X POST "$WEBHOOK_URL" \
-H "Content-Type: application/json" \
-H "Webhook-Id: $WEBHOOK_ID" \
-H "Webhook-Timestamp: $WEBHOOK_TIMESTAMP" \
-H "Webhook-Signature: v1,$SIGNATURE" \
--data-raw "$BODY"

Resources

Errors

Errors return JSON with a human-readable errormessage. Do not parse message text to control application behavior; branch on the HTTP status.

Responses

400Invalid parameters or malformed JSON

401Missing, invalid, or revoked API key

402Not enough credits

404Resource not found

500Unexpected server error

503Processing service unavailable

Resources

Limits

Current beta limits keep processing predictable while the service scales. Contact Soft Field Labs before launch if your workflow needs longer videos or higher throughput.

Parameters

video size50 MB: Maximum per uploaded video.
duration5 minutes: Maximum measured video duration.
resolution4K: Up to 3840 × 2160 pixels.
API keys10: Maximum active keys per account.
list limit100: Maximum jobs returned by one list request.
pricing1 credit / second: Settled to measured duration; failed jobs are refunded.

Backdrop API

Video background removal, built into your workflow.

Upload a video, start an asynchronous processing job, then download a transparent or composited result. The API uses JSON, Bearer keys, and signed storage URLs.

RESTJSONHTTPSAsync jobs

01
Reserve an upload
Create a signed slot, then send the file directly to storage.
02
Process the video
Choose transparent, colour, image, or alpha output and start a job.
03
Receive the result
Poll the job or verify a signed webhook, then fetch a fresh download URL.

Get started

Authentication

Backdrop authenticates API requests with keys beginning in vbr_live_. Send the key as a Bearer token on every request.

Keep keys on the server

Never place an API key in browser code, public repositories, mobile applications, or client-visible environment variables.

Create an API key

Get started

Quickstart

A complete integration has two uploads and one asynchronous job. File bytes go directly to signed storage, so they never pass through your application server or a Vercel Function.

Create an upload slot with the filename, content type, and byte size.
PUT the raw video to the returned upload_url before it expires.
Create a processing job using the returned upload_id.
Poll GET /v1/jobs/{id} or wait for a signed webhook.

Complete flow

export BASE="https://backdrop.softfieldlabs.com"
export API_KEY="vbr_live_..."
# 1. Reserve an upload slot
UPLOAD=$(curl -s -X POST "$BASE/v1/uploads" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"filename":"talk.mp4","content_type":"video/mp4","size_bytes":1234567}')
UPLOAD_ID=$(printf '%s' "$UPLOAD" | jq -r '.upload_id')
UPLOAD_URL=$(printf '%s' "$UPLOAD" | jq -r '.upload_url')
# 2. Upload the raw file bytes to upload_url
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: video/mp4" \
--data-binary @talk.mp4
# 3. Start background removal
JOB=$(curl -s -X POST "$BASE/v1/jobs" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d "{"upload_id":"$UPLOAD_ID","output_type":"transparent","duration_seconds":42}")
JOB_ID=$(printf '%s' "$JOB" | jq -r '.job.id')
# 4. Retrieve the current state (or poll until completed)
curl "$BASE/v1/jobs/$JOB_ID" \
-H "Authorization: Bearer $API_KEY"

API reference

Create an upload

POST/v1/uploads

Reserve a signed upload slot. Then send the raw file bytes to upload_url with a plain HTTP PUT. Slots expire after two hours.

Parameters

filenamestringrequired: The original filename. Backdrop sanitises it before storage.
content_typestringrequired: video/mp4, video/quicktime, video/webm, or video/x-m4v.
size_bytesintegerrequired: Exact file size in bytes. Videos are limited to 50 MB during beta.
kindstringoptional: video by default, or background for a JPEG, PNG, or WebP composite image.

Responses

201Upload slot created

400Invalid file metadata

401Invalid or missing API key

API reference

Create a job

POST/v1/jobs

Start background removal for an uploaded video. The job returns immediately in queued state while GPU processing continues asynchronously.

Parameters

upload_idstringrequired: The upload_id returned by POST /v1/uploads after the file has been uploaded.
output_typeenumrequired: transparent, color, image, or alpha. Transparent produces VP9 WebM with alpha.
background_colorstringrequired for color: A #RRGGBB colour such as #00b140.
background_image_idstringrequired for image: An upload_id created with kind: background.
qualityenumoptional: standard by default, or high for difficult edges and smaller subjects.
duration_secondsnumberrecommended: Used to reserve credits. The final charge settles to measured duration.
downsample_rationumberoptional: Advanced internal analysis scale from 0.1 to 1.0. Omit for automatic selection.
webhook_urlstringoptional: A public HTTPS URL that receives the signed terminal job event.

Responses

201Job queued

400Invalid processing options

402Not enough credits

503Processing service unavailable

Request

curl -X POST "https://backdrop.softfieldlabs.com/v1/jobs" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"upload_id": "usr_123/video/7ed4-talk.mp4",
"output_type": "transparent",
"quality": "standard",
"duration_seconds": 42,
"webhook_url": "https://example.com/webhooks/backdrop"
}'

201 Created

{
"job": {
"id": "fd0663e4-01e7-486c-92ec-9d7cdfbdbbb4",
"status": "completed",
"output_type": "transparent",
"quality": "standard",
"duration_seconds": 12.012,
"width": 854,
"height": 480,
"credits_used": 13,
"output_format": "webm",
"download_url": "https://storage.example/signed-download",
"error": null,
"created_at": "2026-07-15T08:31:31.720Z",
"completed_at": "2026-07-15T08:32:41.100Z"
}
}

API reference

Retrieve a job

GET/v1/jobs/{id}

Retrieve current processing state and metadata. Completed jobs include a signed download_url that remains valid for one hour.

Job lifecycle

queued

processing

encoding

completed

Refresh signed downloads

List responses omit download URLs. Retrieve the individual job whenever you need a fresh signed URL.

Responses

200Job retrieved

401Invalid or missing API key

404Job not found

API reference

List jobs

GET/v1/jobs

Return jobs newest first. List responses are intentionally compact and do not include signed download URLs.

Parameters

limitintegeroptional: Number of jobs to return. Defaults to 20 and is capped at 100.

Responses

200Jobs returned

API reference

Retrieve usage

GET/v1/usage

Retrieve the current credit balance, processing totals, and the fifty most recent credit ledger entries.

Failed jobs are refunded

Jobs charge one credit per measured second. System and processing failures return the reserved credits automatically.

Responses

200Usage summary returned

Webhooks

Event delivery

Add webhook_url when creating a job. Backdrop sends one immutable job.completed or job.failed event when processing reaches a terminal state.

Parameters

idstringstable: Unique event identifier. It remains unchanged across every retry.
typeenum: job.completed or job.failed.
created_attimestamp: When the terminal event was created in ISO 8601 format.
jobobject: The terminal job state. Fetch GET /v1/jobs/{id} for authoritative state and a fresh download URL.

At-least-once delivery

Event IDs and payloads stay stable across retries. Your receiver must deduplicate before applying side effects.

Webhooks

Verify signatures

Read the exact raw request body before parsing JSON.
Reject timestamps more than five minutes from the current time.
Insert Webhook-Id under a unique constraint before applying side effects.
Return 200 for duplicate events without processing them again.
Respond with any 2xx status quickly, then perform slow work asynchronously.

Retry schedule

Network failures and non-2xx responses are retried after 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours. Six total delivery attempts are made.

verify-webhook.mjs

import {
createHmac,
timingSafeEqual,
} from "node:crypto";
export function verifyBackdropWebhook(rawBody, headers) {
const id = headers.get("webhook-id");
const timestamp = headers.get("webhook-timestamp");
const signature = headers.get("webhook-signature");
if (!id || !timestamp || !signature?.startsWith("v1,")) {
throw new Error("Missing signature headers");
}
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
throw new Error("Stale webhook timestamp");
}
const signed = `${id}.${timestamp}.${rawBody}`;
const expected = createHmac(
"sha256",
process.env.BACKDROP_WEBHOOK_SECRET,
).update(signed).digest();
const received = Buffer.from(signature.slice(3), "base64");
if (
received.length !== expected.length ||
!timingSafeEqual(received, expected)
) throw new Error("Invalid signature");
return JSON.parse(rawBody);
}

test-webhook.sh

export WEBHOOK_URL="https://example.com/webhooks/backdrop"
export WEBHOOK_SECRET="whsec_..."
WEBHOOK_ID="evt_test_123"
WEBHOOK_TIMESTAMP="$(date +%s)"
BODY='{"id":"evt_test_123","type":"job.completed","job":{"id":"job_test"}}'
SIGNATURE="$(printf '%s' "$WEBHOOK_ID.$WEBHOOK_TIMESTAMP.$BODY" \
| openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -binary \
| openssl base64 -A)"
curl -X POST "$WEBHOOK_URL" \
-H "Content-Type: application/json" \
-H "Webhook-Id: $WEBHOOK_ID" \
-H "Webhook-Timestamp: $WEBHOOK_TIMESTAMP" \
-H "Webhook-Signature: v1,$SIGNATURE" \
--data-raw "$BODY"

Resources

Errors

Errors return JSON with a human-readable errormessage. Do not parse message text to control application behavior; branch on the HTTP status.

Responses

400Invalid parameters or malformed JSON

401Missing, invalid, or revoked API key

402Not enough credits

404Resource not found

500Unexpected server error

503Processing service unavailable

Resources

Limits

Current beta limits keep processing predictable while the service scales. Contact Soft Field Labs before launch if your workflow needs longer videos or higher throughput.

Parameters

video size50 MB: Maximum per uploaded video.
duration5 minutes: Maximum measured video duration.
resolution4K: Up to 3840 × 2160 pixels.
API keys10: Maximum active keys per account.
list limit100: Maximum jobs returned by one list request.
pricing1 credit / second: Settled to measured duration; failed jobs are refunded.