Batch API.
Wire it in.
A REST API that connects your scripts, render farms and pipeline tools to Batch. Quote a job, submit it, upload the footage, track it and download the results.
Same workspace, same credits and same engine as Batch Portal. API jobs show up in Portal with everything else.
One Batch workspace and one pool of credits across Portal, the API and ComfyUI.
Batch Roto V3.2, Batch Depth V3 and Batch Upres, the same as Batch Portal.
Every job is quoted before it runs. Set a ceiling and nothing is submitted above it.
Start with one handoff.
Pick one thing your pipeline already does and hand that step to Batch. A finished VFX pull. A watch folder. A Send to Batch button for your artists. A shot marked ready in your tracker.
You write the bridge. Batch does the roto, depth and upscale, and hands back files your pipeline can check and publish.
Combine services in one job. Send video files (ProRes MOV, H.264 MP4 or DNxHD MXF). Results come back as ProRes movies.
Eight steps. One shot.
Run one small job end to end. Everything lives under one base URL: https://backend.batch.film/api/public/v1
Get a key
A workspace admin opens Batch Portal, then Integrations, API keys, Create key from the account menu at the top right (in Portal 1.1.6 and earlier, API keys sit under Settings). Name the key after the tool that will use it, tick the permissions it needs, and set an expiry if you want one.
The key is shown once. Copy it straight into your secret manager. Keys belong to the workspace, not the person, so a key keeps working if whoever made it leaves.
A key that runs the whole flow needs the first five. Read billing is optional. The ComfyUI preset ticks the five job permissions; the Read-only preset ticks Read jobs and Read artifacts. Permissions can't be changed on an existing key: make a new one and revoke the old. No Portal yet? Download Batch Portal for Mac or Windows.
Send it with every request
Every request carries the key as a Bearer token. Load it from your secret manager, never from a script or your shell history. Check the wiring with GET /me: it needs no permission, uses no credits, and shows the key's name, permissions, rate limit and daily cap.
# BATCH_API_KEY comes from your secret manager
curl -s "$BATCH_API_URL/me" \
-H "Authorization: Bearer $BATCH_API_KEY"
Get an estimate
A job is a set of services applied to a set of clips. Write it once as job.json, quote it, then submit the same file.
"services": ["roto"],
"subjects": ["people"],
"individual_mattes": false,
"clips": [
{"name": "SH010/plate.mov", "duration_seconds": 4.2, "size_bytes": 104857600}
],
"max_credits": 20,
"job_name": "SH010 roto"
}
-H "Authorization: Bearer $BATCH_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @job.json
The estimate creates nothing and charges nothing. It returns credits (a whole number), an exact breakdown and the pricing version it used.
Create the job
-H "Authorization: Bearer $BATCH_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: show42-SH010-v1" \
--data-binary @job.json
Idempotency-Key is required. Use an ID from your own system. If a response gets lost, retry with the same key, the same body and the same API key, and Batch hands back the original job instead of making a second one. Keys are honored for 24 hours.
The job comes back as awaiting_upload with its id. Save the id right away.
Upload the footage
-H "Authorization: Bearer $BATCH_API_KEY" \
-H "Content-Type: application/json" \
--data '{"artifact_names": []}'
curl -s -X PUT --upload-file /footage/SH010/plate.mov "$UPLOAD_URL"
You get one temporary upload link per clip, named in the order you submitted them (0/plate.mov, 1/plate.mov). Match links to files by position, not by file name. PUT each file straight to its link, without your API key.
Files over 5 GB must use multipart upload with POST /jobs/{job_id}/upload-artifacts/multipart; it is recommended above 100 MB. Interrupted? POST /jobs/{job_id}/resume-upload returns fresh links for whatever is still missing.
Confirm the upload
-H "Authorization: Bearer $BATCH_API_KEY"
Confirming seals the footage and starts the security check. Confirming twice is safe.
Poll the status
-H "Authorization: Bearer $BATCH_API_KEY"
Poll every 10 seconds or slower, back off toward 30, and honor Retry-After. Stop at completed or failed. status is the source of truth; progress is a rough signal, not an estimate of time left.
Download the results
-H "Authorization: Bearer $BATCH_API_KEY"
Each result comes with a name, a delivery_path and a temporary url. Write each file to its delivery_path under your staging folder, which restores your submitted folders, or to its name when delivery_path is empty. Check the files, then publish.
Links are temporary and carry expires_in_seconds. Ask again for fresh ones, and never write them to a log. A job that failed partway may have output at GET /jobs/{job_id}/artifacts/partial: treat it as review material, never as a delivery.
Every call.
Base URL https://backend.batch.film/api/public/v1. The OpenAPI 3.1 spec is at /openapi.json, and the full interactive reference is at backend.batch.film/api/public/v1/docs.
GET /jobs takes page and page_size and nothing else. Filter by status on your side.
Six states. One waits on you.
When a job fails
A failed job carries a terminal_reason. Branch on it, and treat anything unfamiliar as processing_failed. A cancelled job reads failed with the message "This job was cancelled." There is no separate cancelled status.
Quoted before it runs. Billed on what it uses.
API jobs use the same rates as Batch Portal, from the same workspace credits. There is no separate API price.
The limits.
Limits are per file, not per job, so a big delivery splits across clips and jobs. GET /me shows a key's current limits. Need more? Write to support@batch.film.
When it says no.
Every failure uses one envelope. Branch on the HTTP status, then on error_code.
For support, send the job ID, the endpoint, the time and the error_code. Never send a key or a download link.
Keys are credentials.
Questions.
Who can make keys?
Workspace admins, in Batch Portal under Integrations, API keys.
Do API jobs show up in Portal?
Yes. In Processing and History with everything else, marked as sent by API key.
Can I cancel a job?
Yes, with POST /jobs/{job_id}/cancel and the Submit jobs permission, until the job is completed or failed. Credits are held once processing starts, so a job cancelled before then leaves your balance as it was. Its estimate still counts toward the key's daily cap.
Can a key buy credits?
No. Add credits in Batch Portal.
How do I know a job is done?
Poll GET /jobs/{job_id} until it reads completed or failed.
Image sequences?
Send video files. Results are ProRes movies.
Where do I get help?
Support and technical questions go to support@batch.film. Sales, studios and anything else go to lets@batch.film.
Get a key.
Send a shot.
Make a key in Batch Portal, quote one shot, and run it. Running a whole show through it? Write to lets@batch.film.