Timeline plan endpoint: a free estimate before a 91 s render ($0.20)

A 91-second timeline render bills 2 minutes, which is $0.20 at the public rate of $0.10 per ceil output minute. You can get that number without paying: POST /v1/timeline-1.0/plan returns billable_minutes and estimated_cost_usd_micros for a program, and it does not create a job, reserve credits or download media.

Because the plan call is free and needs no idempotency key, it is the right first call for any program where you are not sure which side of a minute boundary the output lands on.

Where the minute boundaries fall

Billing rounds up to the next whole output minute, with a one-minute minimum and a 30-minute maximum. The docs set audio.duration_seconds to 1-1800, so 1,800 seconds is the longest render.

What the plan can and cannot tell you

The plan runs schema checks, Sume-host URL checks and the pure compiler, so it catches a malformed program, a missing slot or a media URL that is not a media.sume.com artifact before any money is held. It also returns a filtergraph_summary and segment_count.

The docs name one limit: a plan cannot predict short-source pad or loop warnings. A source clip shorter than its slot is padded or looped at render time, and that appears as a soft warning on the finished job, not as a failure and not as a different price. The price depends only on output minutes, so the warning does not change the bill.

A shape for the call

Send the same program you intend to render. The example follows the render example in the docs with the output length set to 91 seconds; a response with billable_minutes: 2 confirms the $0.20 reading.

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": 91
    },
    "video": [
      {
        "source_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
        "start": 0,
        "duration": 91
      }
    ]
  }'

Cutting a render to fit a cheaper minute

If a program lands at 121 seconds, trimming one second takes it from 3 billable minutes ($0.30) to 2 ($0.20), a one-third saving on that render. Plan first, trim second, then render. The render itself uses no provider inference, only worker ffmpeg, which is why the rate is a flat per-minute figure.

Using the plan in automation

In a pipeline, call the plan first and compare estimated_cost_usd_micros with a ceiling per video. At 200,000 micros the 91-second render is within a $0.25 budget. Fail the build when the plan returns diagnostics or a figure above the ceiling, and only then submit the render with an Idempotency-Key. The render defaults to asynchronous mode and returns 202; pass mode: "sync" to wait up to 30 seconds for a finished job. The plan itself needs neither.