Darken a video with an API: the dim operation and its amount

To darken a video by API, send ops: [{ "op": "dim", "amount": 0.45 }] to POST /v1/video-filter. dim multiplies the whole clip's luma by amount, which must be greater than 0 and at most 1. 0.45 is noticeably darker, and 1 leaves the clip unchanged.

Behavior below is from the Video filter docs, read 2026-09-29.

What does the amount do?

It is a luma multiply: black stays black and chroma does not shift. It does not brighten; a value above 1 is an error, not a boost. For a fade to black over time, that is a different job; see dip to black.

What does the request look like?

The source must be a media.sume.com clip in your workspace, and an Idempotency-Key is required.

curl -X POST https://api.sume.com/v1/video-filter \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-filter-001" \
  -d '{"video_url":"https://media.sume.com/artifacts/artf_demo/talk.mp4","ops":[{"op":"dim","amount":0.45}]}'

What are the limits?

• Source up to 300 seconds.
• At most 8 entries in ops[]; they run in order, before any filtergraph.
• The output keeps the source's geometry, frame rate and audio unless the program changes them.
• The result is a new MP4 (kind: video_filter); the source is untouched.

What does it cost?

The docs list $0.02 per encode job and say to confirm it in GET /v1/catalog. Check the program first with /v1/video-filter/check, which is free.