Timeline plan: 421 seconds of audio is 8 billable minutes, $0.80

To price a timeline render before you pay for it, call POST /v1/timeline-1.0/plan with the same body you would send to render. It creates no job, reserves no credits, and downloads no media. It returns billable_minutes and estimated_cost_usd_micros. For a 421-second audio spine that is 8 billable minutes, which is $0.80, because Sume rounds the output length up to a whole minute before it applies the rate.

What the plan call returns

The plan runs the schema check, the Sume-host URL check, and the pure compiler. It is the cheapest place to learn that a request is wrong. You do not need an Idempotency-Key for it.

The response is an object of type timeline_plan. These are the fields the docs list:

• duration_seconds: the output length, taken from audio.duration_seconds.
• segment_count: how many video[] slots compiled.
• billable_minutes: the minutes the render would be charged for.
• estimated_cost_usd_micros: the same number in millionths of a dollar.
• filtergraph_summary: a short summary of the compiled graph, not the ffmpeg arguments.

curl -X POST https://api.sume.com/v1/timeline-1.0/plan \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio": { "url": "https://media.sume.com/artifacts/artf_demo/voice.wav",
               "duration_seconds": 421 },
    "video": [
      { "source_url": "https://media.sume.com/artifacts/artf_demo/a.mp4",
        "start": 0, "duration": 421 }
    ]
  }'

The arithmetic

The public rate is $0.10 per output minute, rounded up, with a one-minute minimum and a 30-minute maximum (audio.duration_seconds from 1 to 1800). The render job uses no provider inference, only worker ffmpeg, so the rate does not change with the content.

For 421 seconds: 421 / 60 = 7.02, which rounds up to 8 minutes. 8 x $0.10 = $0.80. A 420-second spine is exactly 7 minutes and costs $0.70. One extra second costs ten cents.

The credit reserve at submit uses the same formula, ceil(audio.duration_seconds / 60) minutes, so the plan matches what the render holds.

What a plan cannot tell you

The docs state one limit: a plan cannot predict short-source pad or loop warnings. If a clip is shorter than the slot you gave it, the render pads or loops it and reports a soft warning in the result. The warning is not a failure and does not change the price.

Trimming the spine to a minute boundary is the one lever the plan shows you. If you land at 421 seconds and the last second is a tail you do not need, set audio.duration_seconds to 420. For the full field list, see the Timeline 1.0 reference.

Using the plan in a pipeline

Put the plan call in front of every render in your code. Read billable_minutes and compare estimated_cost_usd_micros with a budget you hold in the same units: $0.80 is 800,000 micros. If the estimate is above the budget, stop before you create a job and before any credit is reserved. Because the plan needs no idempotency key and creates nothing, it is safe to retry and safe to call from a preview screen where a user edits slots and sees the price change live.

Two habits help. First, plan with the final audio.duration_seconds, not a rough guess, because the rounding is applied to that number. Second, when the plan reports more minutes than you expected, look at duration_seconds before anything else: a spine that is a few seconds over a minute boundary is the usual cause, and trimming the tail often removes a whole billable minute.

After the plan

Submit the same body to POST /v1/timeline-1.0/render with an Idempotency-Key. The default mode is async, so you get a 202 and poll GET /v1/jobs/:id/status and GET /v1/jobs/:id/result; pass mode: "sync" to wait up to 30 seconds. Confirm the live rate in the public catalog before you hard-code it.