Fade 0.25 s between two vertical clips: Timeline transition limits

A 0.25 second fade between two vertical clips is one field on the second slot: "transition": {"type": "fade", "duration": 0.25}. The limits that decide whether Timeline accepts it are in the Timeline docs: the duration is at most 1 second, at most 50% of the shorter neighbor, and at least one output frame, and the first slot cannot carry a transition at all.

The limits as a table

Each limit has its own refusal code, so a failed submit tells you which rule you broke.

Worked numbers

Two 1.0 second slots can take a fade of at most 0.5 seconds, because 50% of the shorter neighbor is 0.5. Two 6 second slots can take the 1 second maximum. Declared starts are authoritative and the compiler compensates for the overlap, so write start values as if the clips were butted together: slot 2 starts at 6, not 5.75.

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-two-clips-001" \
  -d '{
    "audio": {"url": "https://media.sume.com/artifacts/artf_demo/voice.wav", "duration_seconds": 12},
    "video": [
      {"source_url": "https://media.sume.com/artifacts/artf_demo/a.mp4", "start": 0, "duration": 6},
      {"source_url": "https://media.sume.com/artifacts/artf_demo/b.mp4", "start": 6, "duration": 6,
       "transition": {"type": "fade", "duration": 0.25}}
    ]
  }'

When to skip the fade

Short-form edits usually use hard cuts. Use a fade only where a dissolve helps the story, because every extra transition adds one more rule to satisfy. Past eight adjacent transitions, put a hard cut between them. The render bills $0.10 per started output minute (confirm in GET /v1/catalog), and POST /v1/timeline-1.0/plan checks the document without a job.

Longest fade by slot length

Because the limit is 50% of the shorter neighbor, short slots allow only short fades. The table gives the longest fade that two equal slots can take; the 1-second cap wins for slots of 2 seconds or more. The compiler also needs at least one output frame, so a fade must be a whole number of frames at your fps.

Choosing the type

Six transition types are available: fade, dissolve, wipeleft, wiperight, slideup and slidedown. In a vertical frame, slideup and slidedown move along the long axis and read as a scroll, which matches the way people use the feed. wipeleft and wiperight move along the short axis and are quicker to read. Pick one type for the whole video; mixing four types in a 20-second Short looks like a template, not an edit.

The same limits apply to every type. If a submit is refused with transition_too_long, shorten the fade or lengthen the slot. If it is refused with segment_overlap, check that each start is the previous start plus the previous duration.

If you chain more than a few clips, remember the chain rule. More than eight adjacent fades is refused with too_many_chained_transitions, and the fix is to put a hard cut between groups. Render strategy also changes past 12 segments: auto splits the render into chunks, and single is refused above 12 slots with render_strategy_unsafe, so leave render.strategy at its default.