Dim a bright 9:16 clip before captions: video-filter dim at 0.45

Use ops: [{ "op": "dim", "amount": 0.45 }] on POST /v1/video-filter to make a bright clip darker before you burn captions. The video filter docs say dim multiplies the luma of the full clip, 1 makes no change, and the API refuses 0 and anything above 1.

Why dim before captioning

White caption text over a bright shot loses contrast. Some caption styles add an outline or a card, but a dimmer picture makes any of them easier to read. The dim op darkens the picture itself and leaves color information alone: the docs say black stays black and the chroma does not change.

The rules

The rules below are from the docs (read 2026-10-05).

Check, then encode

Run the check first. POST /v1/video-filter/check does the same validation as the encode and returns valid, diagnostics and an estimate, but it does not create a job or use the encoder. It does not need an Idempotency-Key:

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/bright.mp4",
    "ops": [{ "op": "dim", "amount": 0.45 }]
  }'

Then run the job

If valid is true, send the same body to POST /v1/video-filter with an Idempotency-Key. The default mode is async, and mode: "sync" waits up to 30 seconds. The result is a new MP4 with a new artifact URL; the source is not changed.

Then caption the dimmed file

Take the video_url from the filter result and send it to the captions API. The captions endpoint takes a public HTTPS video URL, so the dimmed file feeds straight in. Order matters: filter first, captions second, so the text is burned over the final picture and not dimmed with it.

Limits to remember

A pass that goes wrong can still fail on the worker. The docs say a program that passes the check can fail on the box, for example from a bad expression, memory or time, and in that case you get a structured job error. A source longer than 300 seconds is refused with output_duration_exceeded.

What it does not do

The filter does not cut. For a range, use video trim, and to assemble clips use Timeline 1.0. The docs are explicit that this surface is a pixel pass and does not do either.

Pick the amount by eye

Choose the amount by looking, not by a formula. Take a still from the brightest part of the clip with video inspect, apply a trial dim, and compare. An amount of 0.45 is the number in the docs example and a good first try, but a clip that is already moody may need a gentler 0.8, and a clip with a white background may need less than 0.45. Because the check is free and the encode is $0.02, a few trials cost little.

A limit of the op

Dim applies to the full frame. If only the bottom third needs to be darker, where captions usually sit, the dim op alone will not do it, because it has no region. The docs list a crop op and a filters-only filtergraph, but I did not read an example of a graduated dim, and I will not describe one. If you need that, use the check endpoint to test a filtergraph and read its diagnostics.

Try a style change first

Most caption styles in the captions docs already carry an outline or a card. For example black-outline uses white fill on a thick black outline, and design.colors.card can set a card color. Try a style change before you reach for a filter, and use the dim only when the picture itself is the problem.

Keep the source

Keep the original file. The filter returns a new artifact and the source does not change, so you can always go back to the undimmed clip and try a different amount.

Record the amount

Write the dim amount into your job notes next to the clip id. If a later batch uses the same look, you can reuse it, and if the captions are hard to read again, you know which value you already tried. The filter is deterministic for a given source and program, so the note is enough to reproduce it.

The takeaway

Dim in small steps, check first, and caption last.