Timeline plan call: price a narrated render before you spend

Call POST /v1/timeline-1.0/plan before a render. It is unbilled, creates no job, reserves no credits and downloads no media, and it returns duration_seconds, segment_count, billable_minutes and estimated_cost_usd_micros. For a 12-minute narration with a music bed, expect billable_minutes of 12 and an estimate of 1,200,000 micro-dollars, which is $1.20.

What the plan checks

The plan runs the same schema validation, the Sume-host URL checks and the pure compiler as the render. It does not need an Idempotency-Key. A plan cannot predict warnings about short sources that are padded or looped, so treat it as a price and validity check, not a preview of the picture.

Catching errors for free

Typical mistakes surface in the plan: audio_url_required when there is no url or parts and no silence, audio_url_and_parts_exclusive when you send both, audio_parts_shorter_than_duration when your slices add up to less than audio.duration_seconds, and soundtrack_fade_exceeds_output when a fade is longer than the spine. Fixing these at plan time costs nothing.

duck_db without a real spine fails with duck_requires_audio_spine, so a silence-mode render cannot duck a bed.

Budgeting a batch

Plan every render in a batch and sum estimated_cost_usd_micros. Twenty 3-minute narrated clips are 20 x 3 x $0.10 = $6.00 of render, plus their TTS and music lines. Send the same body to render once the numbers pass your budget check, and note that the render needs an Idempotency-Key where the plan did not.

A short example

Send the same JSON body you would send to render: an audio object with duration_seconds 720 and a url, a video list, and a soundtrack with duck_db. The response reports billable_minutes 12. Multiply by $0.10 to get $1.20, which should match estimated_cost_usd_micros / 1,000,000. If the numbers disagree, trust the live catalog and check your duration.

Then add TTS (characters x 47.5 micro-dollars) and music ($0.125) for the full bill.