Timeline error too_many_chained_transitions: how to fix it
Timeline 1.0 refuses more than 8 adjacent fades with too_many_chained_transitions. Insert a hard cut. Also transition_too_long, transition_not_frame_aligned.
too_many_chained_transitions means a Timeline 1.0 render has more than 8 adjacent fades in a row. The fix in the docs is to insert a hard cut, that is, a slot with no transition, somewhere in the run so no chain exceeds 8.
Codes and rules come from Timeline 1.0, read 2026-09-29. Run POST /v1/timeline-1.0/plan first: it is an unbilled compile preflight, so you see the refusal before you reserve any spend.
Which transition errors exist?
| Code | Cause | Fix |
|---|---|---|
too_many_chained_transitions | More than 8 adjacent fades | Insert a hard cut |
transition_too_long | Duration over 1 s, or over 50% of the shorter neighbor | Shorten it |
transition_not_frame_aligned | Duration is not a whole output frame | Pick a length that is a multiple of a frame at your output.fps |
transition_on_first_segment | video[0].transition was set | Remove it; transitions go on slots after the first |
How do I add a hard cut?
Leave transition off every ninth slot (or any slot that suits the edit). A cut costs no time, and the declared start values stay authoritative: the compiler compensates for the transitions, it never shifts your starts.
What transitions are available?
fade, wipeleft, wiperight, slideup, slidedown and dissolve. Duration is at most 1 second and at least one output frame. See transitions in the API.
Can chunking help?
Not with this error. render.strategy auto already chunks past 12 segments, and single is refused above 12 slots with render_strategy_unsafe. Those are separate limits from the chained-transition cap. The render is $0.10 per output minute either way.
How do I preflight a transition-heavy timeline?
Send the same body you would render to POST /v1/timeline-1.0/plan. It runs the schema and URL checks and the compiler, and returns duration_seconds, segment_count, billable_minutes, estimated_cost_usd_micros and a filtergraph_summary. It creates no job and reserves nothing. It cannot predict warnings such as padded or looped short sources.
Sources
Related posts
More in Developers
- Render a vertical 1080x1920 video from clips with an API
Timeline 1.0 defaults to a 1080x1920 MP4. Set output width, height and fps, and pick fit cover, contain, stretch or blur for clips that do not match the frame.
- Text to speech long text limit: 1,200 seconds, not just characters
Sume TTS 1.0 has two limits: 20,000 characters in, 1,200 seconds of audio out. Over the audio limit it fails with tts_duration_exceeded and captures no credit.
- Text to speech sentence timestamps API: one lip-sync clip each
Sume TTS 1.0 returns gapless sentence segments; with wav output each gets its own audio_url, ready to drive a lip-sync clip. Request shape and the 5 s catch.
- TTS WAV or MP3 for video: keep WAV until the last mux
Sume TTS 1.0 defaults to mp3 at 44100 Hz and 128 kbps. If the audio will be joined, sliced or muxed into video, ask for wav; mp3 adds padding at every edge.
Written by Sume