API reference/POST /video/remove

Video background removal

Remove the background from a video and get back real alpha-channel footage. Submit a clip, poll the job, download the result. ProRes 4444 drops straight into DaVinci Resolve, Premiere Pro, After Effects, and Final Cut. No green screen. Async and paid tier only.

POSThttps://useknockout--api.modal.run/video/remove

Parameters

Send as multipart/form-data unless noted otherwise.

filerequiredfile–Video file: mp4, mov, avi, webm, or mkv. Max 30 seconds and 200 MB. Frames above 1080p are downscaled.
formatstringprores4444Output format. prores4444 (MOV, 10-bit alpha), webm (VP9 with alpha), or mp4 (H.264, opaque, requires bg_color).
bg_colorstring–Hex color composited onto every frame. Required when format=mp4, ignored for prores4444 and webm.
bg_imagefile–Optional image (multipart) to composite the subject onto instead of a color. Used as the new backdrop behind every frame.
bg_blurint 1-100–Composite the subject over a blurred copy of its own source background. Higher is blurrier. Alternative to bg_color / bg_image.
speedfloat 0.25-4.01.0Playback speed. Also tempo-shifts the audio. Billing is on OUTPUT seconds, so speed=2.0 halves both duration and cost. Output length (duration / speed) must be 15 seconds or less.
smoothingint 0-10030Temporal alpha smoothing. Reduces edge flicker between frames. Lower it for fast-moving subjects.

Request

# 1. Submit the clip
curl -X POST "https://useknockout--api.modal.run/video/remove" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@clip.mp4" \
  -F "format=prores4444"

# 2. Poll until status is done, then download result_url
curl "https://useknockout--api.modal.run/jobs/JOB_ID" \
  -H "Authorization: Bearer $TOKEN"

Response

HTTP/1.1 202 Accepted
content-type: application/json

Errors

400invalid_format–Unsupported container, or format=mp4 without bg_color.
401unauthorized–Missing or invalid token.
402payment_required–Video is paid-tier only. Free and demo keys get 402. Add a card or upgrade.
413payload_too_large–Video exceeds 200 MB or 30 seconds.
429rate_limit_exceeded–Slow down. Retry-After header tells you when.
500video_failed–Processing failed. Not billed on failure.
Every error response also includes a request_id in the JSON body. Quote it when reporting issues.

Notes

  • Async: POST returns a job_id immediately, then poll GET /jobs/{job_id} until status is done.
  • $0.10 per output second on Pay-as-you-go, $0.08 per output second on Knockout Plus. Billed only on successful completion. A 10-second clip is $1.00 (or $0.80 on Plus). The job result includes output_seconds, the exact quantity billed.
  • Caps: 30 seconds max upload, 30fps processing, 200 MB upload, frames processed at up to 1080p. Output length (duration / speed) must be 15 seconds or less. Audio is preserved.
  • Background options are mutually exclusive: pick one of bg_color (solid), bg_image (composite onto an uploaded image), or bg_blur (blurred copy of the original background). prores4444 and webm can also just keep transparency.
  • prores4444 and webm carry a real alpha channel. mp4 is opaque, so it needs a background (bg_color, bg_image, or bg_blur).
  • Use cases: real alpha video for editors (Resolve, Premiere, After Effects, Final Cut), webm alpha for web playback, mp4 on a solid color for marketplaces.
  • EXIF-style rotation from phone clips is auto-corrected.
  • bg_image, bg_blur, and speed are currently form-field only. The SDKs do not expose typed params for them yet (coming in 0.7.1), so send them as raw multipart fields.
← POST /colorizeGET /jobs/{job_id} →