End a vertical Short on a fade: Timeline fade_out_seconds 0.5

To end a vertical Short on a clean fade, add output.fade_out_seconds: 0.5 to the Timeline 1.0 render. Both fade_in_seconds and fade_out_seconds accept 0 to 5 seconds, and their sum must not exceed the output length, or the job is refused with edge_fades_exceed_output. The fade applies to the whole rendered output, not to one clip, so it is the right tool for the first and last half second of a Short and the wrong one for a mid-video transition.

Edge fades versus transitions

Timeline has two fade features and they are easy to mix up. output.fade_in_seconds and fade_out_seconds act on the beginning and the end of the whole render. video[].transition acts between two adjacent slots, is not allowed on the first slot, and is limited to 1 second and half of the shorter neighbor. The Timeline docs list the types: fade, wipeleft, wiperight, slideup, slidedown and dissolve.

The request

A 20-second, one-slot Short with a 0.25 second fade in and a 0.5 second fade out. The slot's duration can stop at most 0.5 seconds before the end of the audio spine, so give the video the full length. The output audio comes from the spine: with audio.mode: "silence" the render is silent, so use a real spine file when you need the clip's own speech or music.

Import the clip first with POST /v1/media-imports, and send an Idempotency-Key on writes.

curl -X POST https://api.sume.com/v1/timeline-1.0/render \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fade-out-001" \
  -d '{
    "audio": {"url": "https://media.sume.com/artifacts/artf_demo/voice.wav", "duration_seconds": 20},
    "video": [{"source_url": "https://media.sume.com/artifacts/artf_demo/a.mp4", "start": 0, "duration": 20}],
    "output": {"fade_in_seconds": 0.25, "fade_out_seconds": 0.5}
  }'

Notes

The render is $0.10 per started output minute, so these 20 seconds bill as one minute whether or not they fade; confirm the live rate in GET /v1/catalog. Run POST /v1/timeline-1.0/plan first if you want the compile check without a job.

Checking the sum

The refusal triggers on the sum of the two edge fades against the output length. For a 20-second Short, 0.25 + 0.5 = 0.75 is fine. For a 1-second output, fades of 0.6 and 0.6 total 1.2 and are refused. Each fade is also capped at 5 seconds, so a long Short cannot use a 6-second fade even though the sum would fit.

A fade to black at the end is a stylistic choice. If you want a Short to loop cleanly into its first frame, leave fade_out_seconds at 0, because a fade ends on black while the first frame does not.

Frame rate and the fade

Fades are rendered frame by frame, so a very short fade at a low frame rate is only a few frames long. At 30 fps, 0.25 seconds is 7 or 8 frames; at 24 fps it is 6. If you leave output.fps out, the render follows your sources, and a clip at 23.976 fps keeps that rate rather than being resampled. Setting a different fps repeats or drops frames and raises the output_fps_resamples_sources warning, so keep the fade and the frame rate decisions separate.

A fade-in of 0.25 seconds is long enough to soften a hard first frame without delaying the hook. If your first second carries the hook, consider leaving fade_in_seconds at 0 and using the fade-out only; a viewer deciding whether to keep watching has little patience for a black frame at the start.