Timeline render_strategy_unsafe: why single fails above 12 slots

Sume Timeline returns render_strategy_unsafe when you set render.strategy to single on a request with more than 12 slots. The fix is to remove the field or set auto, which chunks the render past 12 segments, or to set chunked yourself.

The strategy options

The docs list three values for render.strategy.

Related limits

A request has 1 to 200 video[] slots, an audio length of 1 to 1800 seconds, and a minimum slot length of 0.2 seconds. Transitions go only on slots after the first, last at most 1 second and no more than 50% of the shorter neighbor. More than 8 adjacent fades returns too_many_chained_transitions; put in a hard cut.

• Slots: 1 to 200
• Audio: 1 to 1800 s
• Slot length: at least 0.2 s
• Chained fades: at most 8
• Single render: 12 slots or fewer

What to do

Most requests should leave the field out. A 40-slot montage then renders in chunks with no change to your request. Use single only if you have a reason, such as a short sequence where you want one encode pass, and keep it at 12 or fewer slots.

Pricing does not depend on the strategy. Render is $0.10 per ceil(output minute), so a 3-minute montage is $0.30 whether it was chunked or not.

Reading the error

The error comes back on the request, before any render work, so a mistake here is cheap to find. Look at your payload for a render object that someone added to speed up a short test and then forgot. Remove it, or change the strategy value, and send again with a fresh idempotency key if the previous attempt was recorded.

When a request is short

With 12 slots or fewer, auto and single are both accepted. If you cannot tell which is better for your clip, leave auto. The strategy changes how the work is split, not the picture you ordered.

A fix in code

If you build requests in a script, set the strategy from the slot count rather than hard-coding it. Use single only when len(video) <= 12 and otherwise omit the field. That way a table that grows from 10 to 14 rows does not suddenly start failing.

def render_block(slots):
    # single is refused above 12 slots; auto chunks past 12
    return {"strategy": "single"} if len(slots) <= 12 else {"strategy": "auto"}

Where to verify

The Timeline page lists every error code with its cause, and the code for this one is render_strategy_unsafe. If you see a different code on the same payload, such as invalid_segment_timing, fix that first, because the slot starts must increase and video[0].start must be 0.

Practical advice

Keep requests small while you debug. Render a 6-slot version first to confirm the order, the fit modes, and the audio, then scale to the full list. Fit modes are cover, contain, stretch, and blur, and the default output is 1080x1920. Still images become static holds, so a photo slot needs a duration of at least 0.2 seconds like any other. Once the short version looks right, the long one differs only in the number of slots, and auto handles the chunking.