Fade a Short in and out with Timeline 1.0: fade seconds and limits

Set output.fade_in_seconds and output.fade_out_seconds in a Timeline 1.0 request, each from 0 to 5 seconds, with a sum no longer than the output. If the sum is longer, the API refuses the request with edge_fades_exceed_output.

Edge fades and transitions are different fields

These are edge fades on the whole output, not a transition between two slots. The Timeline 1.0 docs keep those separate: video[].transition goes on slots after the first, and the output fades go at the start and end of the finished file.

The limits

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

When to use them

A short fade in can hide a rough first frame, and a short fade out can avoid a hard stop at the end. A half-second on each side is usually enough; a long fade eats into the part of a Short that carries the message. I did not read any platform page that asks for fades, so treat this as a style choice and not a requirement.

A request

A 20 second Short with a 0.4 second fade in and a 0.6 second fade out:

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-edges-001" \
  -d '{
    "audio": { "mode": "silence", "duration_seconds": 20 },
    "video": [{
      "source_url": "https://media.sume.com/artifacts/artf_demo/clip.mp4",
      "start": 0,
      "duration": 20
    }],
    "output": { "fade_in_seconds": 0.4, "fade_out_seconds": 0.6 }
  }'

Check the sum

The sum is 1.0 second, which is well under the 20 second output. If you set both to 5 on a 8 second output, the sum of 10 is longer than the file and the request is refused.

Fading a music bed

If you add a music bed with soundtrack, it has its own fade_out_seconds of up to 10, and that must also fit inside the output. A soundtrack fade longer than the output is refused with soundtrack_fade_exceeds_output. duck_db from 0 to 20 lowers the bed under the spine, and it needs a real audio spine, not silence.

Plan first

Run POST /v1/timeline-1.0/plan first. The plan runs the same checks as the render, so a fade that is too long fails there at no cost. YouTube Help (read 2026-10-05) gives 3 minutes as the Shorts maximum, and the plan does not check a platform limit, so keep that in your own script.

Sources stay untouched

Fades touch only the file you render, not the sources. The original clip is unchanged, so you can render a second version with different fades from the same source at the cost of another render, which is $0.10 for the first minute. If you try two or three fade lengths, use the plan to check each body and the render only for the one you keep.

Pick the right tool

Timeline fades are also a quick way to avoid a visible jump when two clips of different brightness meet at a cut. For that, use video[].transition with a fade type and a short duration, such as 0.25 seconds as the docs example does, instead of an edge fade. The two tools solve different problems: transitions join slots, and edge fades shape the start and the end.

Frame rate and fades

A last point is the frame rate. If you omit output.fps, the render follows the rate of the sources, and a fade is computed on whichever rate results. Set fps to 24, 25, 30 or 60 if you need a particular rate, and read warnings[] in the result for output_fps_resamples_sources if it differs from the source rate.

No provider cost

Nothing here needs a special model. A fade is an ffmpeg operation on the worker, and the docs say a timeline job uses no provider inference, so the cost of the render stays at the per-minute rate.

A safe default

If you are not sure what to choose, start with no edge fades and add them only when you see a problem. A fade changes the first and last frames, and those frames are the ones a viewer sees first and last. A plain cut is a perfectly good default for a Short that loops or ends on a clear beat.

The takeaway

Keep edge fades short, make sure their sum fits the output, and plan before you render.