2026-10-08

Video filter /check is free: validate 8 ops before you pay $0.02

POST /v1/video-filter/check runs the same validation as the encode and bills nothing. See what it catches, the 8-op limit, and when a valid program still fails.

3 min readSume

All posts

Send your program to POST /v1/video-filter/check first: it runs the schema, the op whitelist, the filtergraph allowlist and the source preflight, and it creates no job, reserves no credits and costs nothing. The real encode is $0.02 per job (Video filter).

What the check returns

A valid response has object: video_filter_check, valid, encode: "not_run", diagnostics[], the compiled filter names, and, for a valid program, an estimate and a next_action of submit_video_filter or fix_program_and_recheck. Problems come back as diagnostics, not as a 400. No Idempotency-Key is needed.

curl -X POST https://api.sume.com/v1/video-filter/check \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "ops": [
      {"op": "crop", "x": 0.34, "y": 0, "width": 0.3164, "height": 1},
      {"op": "dim", "amount": 0.45}
    ]
  }'

Rules the check enforces

Sume docs, read 2026-10-08
Rule	Limit	Refusal code
Ops per program	Max 8	`video_filter_too_many_ops`
Op names	`dim` or `crop` only	`unsupported_filter_op`
Dim `amount`	Greater than 0, up to 1	`video_filter_amount_out_of_range`
Crop box	x+width <= 1, y+height <= 1, sides >= 0.05	`video_filter_crop_out_of_bounds`
Filtergraph	2048 chars, 32 filters, no stream specifiers	`invalid_filtergraph`
Source length	Up to 300 s	`output_duration_exceeded` (worker)

What a pass does not promise

The docs are explicit: a program that passes can still fail on the box, for a bad expression, memory or time, and you then get a structured job error. Treat the check as a gate against contract mistakes, not a render guarantee.

A failing program, caught for free

Add {"op": "crop", "x": 0.8, "y": 0, "width": 0.3, "height": 1} to a program and the box runs past the frame, since x + width is 1.1. The check reports the refusal video_filter_crop_out_of_bounds in its diagnostics and next_action is fix_program_and_recheck, with no job created and nothing reserved. The encode would be $0.02 only once you submit a valid program.

video_url must be a media.sume.com artifact or asset of your workspace, and the check runs the same source preflight as the encode. An off-host URL comes back as unsupported_media_source, and a dead one as source_not_found. For a batch of 20 clips the valid encodes cost 20 x $0.02 = $0.40; the checks add nothing.

Sources

Video filter (Sume docs)