Video filter check passed but the encode failed: what to do next

A passing Sume POST /v1/video-filter/check does not guarantee a successful encode. The check runs the schema, the op whitelist, the filtergraph allowlist and the source preflight, then returns encode: "not_run". A valid program can still fail on the worker for a bad expression, memory or time, and in that case the job returns a structured error you can read.

This is stated on the video filter page. The check creates no job, reserves no credits and boots no box, so passing it only means the request is well formed.

What the check proves

The response has object: video_filter_check, valid, diagnostics[], the compiled program.filters (names only), and, for a valid program, an estimate and next_action set to submit_video_filter or fix_program_and_recheck. Diagnostics come back as data and not as a 400.

A practical order of work

Run the check first on every program, since it is free. Submit the encode with an Idempotency-Key, then poll GET /v1/jobs/:id/status and read GET /v1/jobs/:id/result for the outcome. If the job fails, read the public error metadata (category, stage, retryability) described in errors and credits before changing anything.

• Source clips must be 300 seconds or shorter; longer sources fail with output_duration_exceeded.
• Shrink the program: at most 8 ops[], and a filtergraph of at most 2048 characters and 32 named filters.
• Test a risky expression on a short trimmed piece first, since a trim is $0.02 and the clip then fits the worker budget.
• Use a new idempotency key when you change the program, so the changed request is not read as a replay.

Cost of being wrong

Because the check is free and an encode is $0.02, five trial encodes cost 5 x $0.02 = $0.10. I would not guess how a failed job is billed from this page; the public docs tell you where to read the job outcome, and the live price stays in GET /v1/catalog.

Typical failure causes to look for

The docs name three families: an expression the filter engine cannot evaluate, a program that needs more memory than the worker allows, and an encode that runs out of time. The first is usually a typo in an expression inside filtergraph; shorten it to the smallest program that reproduces the failure and re-check.

A crop that is larger than the source is caught earlier, by the check, with a diagnostic. The failures this page is about are the ones the check cannot see because they depend on the frames themselves.