Preflight a 3-minute Short with Timeline plan before you pay

Send your Short's Timeline document to POST /v1/timeline-1.0/plan first: it validates the schema and the Sume-host URLs, compiles the render, and returns duration_seconds, segment_count, billable_minutes and estimated_cost_usd_micros without creating a job, reserving credits or downloading media. For a 180-second Short that means a wrong start time costs nothing. YouTube's help page allows Shorts up to three minutes (read 2026-10-08).

A runnable check

The script builds six 30-second slots from placeholder artifact URLs, so replace them with your own media.sume.com files. Python's standard library is enough.

import json, os, urllib.request

slots = []
for i in range(6):
    s = {"source_url": f"https://media.sume.com/artifacts/artf_demo/c{i+1}.mp4",
         "start": i * 30, "duration": 30}
    if i:
        s["transition"] = {"type": "fade", "duration": 0.25}
    slots.append(s)

body = {"audio": {"url": "https://media.sume.com/artifacts/artf_demo/voice.wav",
                  "duration_seconds": 180}, "video": slots}
req = urllib.request.Request(
    "https://api.sume.com/v1/timeline-1.0/plan",
    data=json.dumps(body).encode(),
    headers={"Authorization": "Bearer " + os.environ["SUME_API_KEY"],
             "Content-Type": "application/json"})
plan = json.load(urllib.request.urlopen(req))
print(plan["billable_minutes"], plan["estimated_cost_usd_micros"])

What the plan does not know

A plan cannot predict warnings about short sources being padded or looped, so a clip that is a second shorter than its slot still renders and reports a soft warning afterwards. It also carries no Idempotency-Key requirement, unlike the render.

Plan arithmetic for a Short

The render is priced per started output minute, so a 181-second spine bills as four minutes.

Then render

Once the plan is clean, send the same body to POST /v1/timeline-1.0/render with an Idempotency-Key and poll GET /v1/jobs/:id/status. Past 12 slots the default auto strategy renders in chunks; asking for single above 12 slots is refused with render_strategy_unsafe.

Using the estimate in code

Treat the plan response as a gate. Compare estimated_cost_usd_micros with the balance you are willing to spend on this Short, fail the job in your own pipeline if it is higher, and only then call render. The plan also returns segment_count, so you can assert that the number of slots matches the number of clips you expected. Because plan needs no idempotency key and creates no job, it is safe to call on every edit in an editor UI, though you should still respect your rate limit and debounce rapid changes rather than calling it on every keystroke.