Green screen removal API
Send a clip shot on a green, blue or teal screen to the Zapmatte API and get the subject back with transparency: ProRes 4444 with alpha for Premiere, After Effects, Final Cut and Resolve, a transparent WebM for the web and OBS, a black-and-white alpha matte, or an MP4 on a solid colour.
Plain HTTPS + JSON · Bearer key · Same credits and processing as the website · Failed jobs refunded automatically
Authentication
Every call except downloads needs a personal key in the Authorization: Bearer header. Create one here after signing in; it is shown once.
Your API key
A key lets your code upload videos, spend your Zapmatte credits on green screen removal, and read your balance and results. It expires after 30 days, and you can have up to five at once. The same key also works with MCP clients. Keep it on your server, never in a web page or app.
Loading account…
Endpoints
Base URL https://zapmatte.com. Full request and response schemas are in the OpenAPI spec.
- GET /api/me/credits
- Your spendable credit balance.
- POST /api/upload/video
- Screens 1-4 frames of the clip and returns a one-time URL to PUT the video to.
- POST /api/generate
- Starts the removal on the uploaded clip and charges the exact quoted credits.
- GET /api/generate/status?taskId=…
- Follows the job; on success returns URLs of the ProRes, WebM, matte, preview and colour MP4.
- GET /api/download?task=…&file=mov
- Downloads one output as a file (no key needed).
From clip to transparent video
The video never passes through the API: you screen four frames, get a one-time upload URL, and upload the file straight to storage. With curl and ffmpeg:
KEY=zap_mcp_... # create it above
BASE=https://zapmatte.com
# 1. Read the clip and grab four frames for screening
ffprobe -v error -show_entries format=duration:stream=width,height -of json intro.mp4
for t in 1 3 5 7; do ffmpeg -loglevel error -y -ss $t -i intro.mp4 -frames:v 1 -vf scale=640:-2 f$t.jpg; done
# 2. Ask for an upload slot (frames as JPEG data URLs)
curl -s $BASE/api/upload/video -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{
"name": "intro.mp4", "type": "video/mp4", "size": 48213004,
"duration": 12.4, "width": 1920, "height": 1080,
"frames": ["data:image/jpeg;base64,/9j/4AAQ...", "..."]
}'
# -> { "ok": true, "key": "up/…", "putUrl": "https://…", "contentType": "video/mp4" }
# 3. Upload the video itself to putUrl
curl -T intro.mp4 -H "Content-Type: video/mp4" "<putUrl>"
# 4. Start the job: 12.4 s rounds up to 13 s x 1 credit = 13
curl -s $BASE/api/generate -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{
"requestId": "'$(uuidgen)'", "uploadKey": "up/…", "mode": "standard",
"durationSeconds": 12.4, "expectedCredits": 13, "background": { "type": "transparent" }
}'
# -> { "ok": true, "taskId": "…", "creditsCharged": 13, "newBalance": 137 }
# 5. Poll every 5 seconds until state is success or fail
curl -s "$BASE/api/generate/status?taskId=<taskId>" -H "Authorization: Bearer $KEY"
# -> { "ok": true, "state": "success", "outputs": { "mov": "https://…", "webm": "https://…", "matte": "https://…" } }Quality and cost
| mode | Credits per second | Best for |
|---|---|---|
| standard | 1 | Clean edges on most green and blue screens. Recommended. |
| fine | 2 | Fills in loose hair more fully. Slower, slightly softer, and saved at 30 fps. |
Billable seconds are the clip length rounded up. Send that exact total as expectedCredits; a mismatch is refused before anything is charged. Credits come from one-time packs on the pricing page and never expire.
Limits and retries
- Clips up to 3 minutes, 500 MB and 4K, in MP4, MOV, M4V, WebM or MKV, shot on a green, blue or teal screen.
- One request per account and endpoint at a time; poll status no faster than every 5 seconds. Over the limit you get 429 with
Retry-After. requestIdmakes a submission safe to retry: the same id with the same parameters returns the stored answer for 24 hours. If a call times out, retry with the same id or check My videos; a new id starts another paid job.- Frames and the uploaded file are checked for content. Blocked clips are refused at upload; a job blocked or failing later is refunded.
- Accounts that have never bought credits see results a minute after submitting, like on the website.
- Picture backgrounds are website-only; the API offers transparent and solid colour.
Prefer to run it yourself? The Standard pipeline is open source (GPL-3.0) on GitHub. Questions: contact and support.