Check a video filter program for free before you encode it

Before you encode a filter, call POST /v1/video-filter/check. It runs the same schema validation, op whitelist, filtergraph allowlist and source preflight as the real call, returns diagnostics instead of a 400, and does not create a job, reserve credits or touch the encoder. The encode itself is $0.02 per job, so the check mostly saves time and failed jobs, not large sums.

What the check returns

A valid response is object: video_filter_check with valid, encode: "not_run", diagnostics[], the compiled program.filters (names only), an estimate when the program is valid, and a next_action of submit_video_filter or fix_program_and_recheck. Idempotency-Key is not required on the check, but it is required on the encode.

A flow

1. Check the program. 2. If valid is false, read diagnostics[], fix, check again. 3. When next_action is submit_video_filter, post the same body to the encode endpoint with an Idempotency-Key. 4. Poll GET /v1/jobs/:id/status, then /result.

For hosted MCP the same flow is video_filter with check_only: true, then video_filter, then jobs_wait and jobs_result.

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": "dim", "amount": 0.45}]
  }'

Using it in CI

Because the check is unbilled and needs no idempotency key, it fits a pre-merge test: store a few representative programs, run each through the check on every change to your pipeline, and fail the build when valid is false. That catches a typo in a filter name before it reaches production, where it would otherwise surface as a failed job.

Limits

A program that passes the check can still fail on the encode box (a bad expression, memory, time), which comes back as a structured job error. The check does not download the media; it preflights the source. And filters are not for cutting or text: use trim for cuts and captions for burned-in words. The encode returns a new file and leaves the original alone.