Test a video dim first: video-filter check is free, encode is $0.02

To test a video filter without paying, post the same body to POST /v1/video-filter/check. It runs the schema check, the op whitelist, the filtergraph allowlist, and the source preflight, and returns diagnostics instead of a 400. It creates no job, reserves no credits, and never starts the encoder. The encode itself, POST /v1/video-filter, costs $0.02 per job.

What the check returns

No Idempotency-Key is needed for the check. A valid response has object: video_filter_check and these fields:

• valid: true or false.
• encode: "not_run": confirms nothing was rendered.
• diagnostics[]: what is wrong with the program.
• program.filters: the compiled filter names, without argv.
• estimate: present when the program is valid.
• next_action: submit_video_filter or fix_program_and_recheck.

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 }]
  }'

What dim does

dim multiplies the luma of the full clip. The amount must be in the interval (0, 1]: 0.45 darkens the clip, 1 changes nothing, and 0 or anything above 1 is refused with video_filter_amount_out_of_range. Black stays black. A typical use is darkening a background clip so that text or a plate on top of it is readable.

The other op is crop, and you can send up to 8 ops in order. Sume applies ops[] before any filtergraph.

The cost of experimenting

Suppose you try five values of amount before choosing one. Using the check for all five and the encode once is 5 x $0 + $0.02 = $0.02. Encoding each variant would be 5 x $0.02 = $0.10. The check cannot catch everything: the docs warn that a program that passes can still fail on the box (a bad expression, memory, or time), and then you get a structured job error.

The check does verify the source preflight, so a dead media.sume.com URL (source_not_found) or an off-host URL (unsupported_media_source) shows up here too. The source must be at most 300 seconds.

Reading diagnostics

Treat next_action as the branch point. If it is submit_video_filter, the program passed every pre-encode check and you can send the encode request unchanged. If it is fix_program_and_recheck, read diagnostics[], correct the program, and call the check again; each retry is free. Typical diagnostics are an unknown filter in the graph (the error names the token and the allowlist), a filtergraph over 2,048 characters or 32 filters, a dim amount outside (0, 1], or a crop rectangle outside the frame.

Do not send ffmpeg fields. Keys such as vf, filter, ffmpeg, cmd, codec, and crf are refused with ffmpeg_fields_rejected, because the server compiles ffmpeg itself.

Dim and crop together

Ops run in order and Sume applies them before any filtergraph, so you can darken and crop in a single $0.02 job. For example [{"op":"crop","x":0.3418,"y":0,"width":0.3164,"height":1},{"op":"dim","amount":0.6}] crops a vertical window and then darkens it to 60% luma. Two separate jobs would cost $0.04 and re-encode the clip twice, so combine ops whenever you can.

The limit is 8 ops per request. For anything beyond dim and crop you need a filters-only filtergraph, which Sume applies after the ops, with a maximum of 2,048 characters and 32 named filters. The graph may not name inputs, outputs, or paths.

Then encode

Submit the same body to POST /v1/video-filter with an Idempotency-Key. The result, at GET /v1/jobs/:id/result, has kind: video_filter, a new video_url, ops_applied, the compiled filters[], and warnings[]. The allowlist excludes drawtext, subtitles, movie, lut3d, and trim or setpts; use video trim for cuts.