Dim an avatar clip to 0.45 for overlay text: run the free check first

To darken a Sume avatar clip so that text on top of it reads, send it to Video filter with one dim op at amount: 0.45. Call POST /v1/video-filter/check first. The check is unbilled, returns diagnostics instead of a 400, and tells you whether the program is valid. The encode itself is $0.02 per job.

Dim multiplies the luma of the full clip. An amount of 1 changes nothing, and 0.45 makes the clip noticeably less bright. Black stays black and chroma is unchanged, so skin and clothing keep their hue but lose brightness.

What dim accepts

The ops array is ordered, with at most 8 entries, and it applies before any filtergraph. For dim, the only fields are op and amount; any extra key fails with unsupported_filter_op_field. An amount of 0 or above 1 fails with video_filter_amount_out_of_range.

Run the check, then the encode

The check validates the schema, the op whitelist, the filtergraph allowlist and a HEAD preflight of the source. It does not boot a box or encode. A program that passes can still fail on the worker, for example on memory, and that returns a structured job error. The video must be a media.sume.com artifact of your workspace; an avatar result already is.

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

Where it fits in a pipeline

A dimmed avatar clip is useful as a backdrop when the face should stay recognisable but a headline or a price needs contrast. The cost of that step is small next to the avatar render: a 15-second standard clip is $2.76 and the dim pass adds $0.02, which is under 1 percent. Do the dim before assembling clips in Timeline 1.0, since the filter returns a new MP4 that can go into a video[] slot.

Dim darkens the whole frame, including the face. If you only want the background darker, this op is the wrong tool, because it has no mask. Use it when the whole picture can be quieter. Crop is the other documented op, and both are listed in the Video filter page.

Choosing the amount

There is no single right amount, since it depends on how bright the avatar background is. Start at 0.6 for a light studio backdrop and 0.45 for a bright window or white wall. Because each encode is $0.02, you can render three versions (0.7, 0.55 and 0.45) for six cents and compare them with your headline on top. Keep the original file, as dim returns a new MP4 and never changes the source. Chaining a crop in the same call is also allowed, since ops run in the order given.