Price a Sume timeline render before you pay: the unbilled plan call

Sume lets you price a timeline render before you pay for it. POST /v1/timeline-1.0/plan runs the same schema checks, Sume-host URL checks and compiler as the render, then returns duration_seconds, segment_count, billable_minutes and estimated_cost_usd_micros. It does not create a job, reserve credits or download media (read 2026-10-06).

That makes it the cheapest guard in a batch pipeline: a plan call is free, needs no Idempotency-Key, and tells you the minute count that the render will bill at $0.10 per started minute. For an agency that renders hundreds of cuts, the call turns "I think this is under budget" into a number from the service.

What a plan can and cannot tell you

A plan is a compile, not a render. It validates the document and prices it, but it cannot predict warnings that appear only when the worker opens the sources, such as a short source that has to be padded or looped. Those are soft warnings in the result, not failures, and they do not change the price.

The price is a function of the output length alone: the reserve is ceil(audio.duration_seconds / 60) minutes, and the job uses no provider inference, only worker ffmpeg. A 61-second cut costs two minutes. If a plan says two minutes for a cut that you meant to be one, shorten the spine by a second and plan again.

• Plan every cut in a batch first and reject any that bill more minutes than the brief allows.
• Sum estimated_cost_usd_micros across the batch and compare it with GET /v1/balance before you submit.
• Plan after you change the audio spine, since the spine sets the length.
• A plan does not replace the live rate. Confirm it in GET /v1/catalog.

Limits that bound the price

The Timeline docs set audio.duration_seconds between 1 and 1800 seconds, so the largest single render is 30 minutes and the largest render line is $3.00 at the published rate, which matches the last row of the table. Up to 20 audio.parts[] slices can be joined into one spine, and the output defaults to a 1080 by 1920 MP4, so a plan for a vertical short needs no output block at all (Sume docs: Timeline, read 2026-10-06).

A plan that fails validation is also useful information. The same schema and Sume-host URL checks run as in the render, so a source URL that is not on a Sume host, a first clip that does not start at 0, or a silence spine that carries a gain_db field is rejected at plan time, before any credits are reserved.

Build the request and the local estimate

The script below builds a plan body for a silent cut, prints the local estimate, and calls the plan endpoint only when SUME_API_KEY is set. The clip URL is a placeholder: replace it with a Sume-hosted clip that your workspace owns.

import json
import math
import os
import urllib.request

CLIP = "https://media.sume.com/artifacts/example/hook.mp4"


def plan_body(seconds: int) -> dict:
    return {
        "audio": {"mode": "silence", "duration_seconds": seconds},
        "video": [{"source_url": CLIP, "start": 0, "duration": seconds}],
    }


def local_dollars(seconds: int) -> float:
    return math.ceil(seconds / 60) * 0.10


body = plan_body(75)
print(json.dumps(body), local_dollars(75))
key = os.environ.get("SUME_API_KEY")
if key:
    req = urllib.request.Request(
        "https://api.sume.com/v1/timeline-1.0/plan",
        data=json.dumps(body).encode(),
        headers={"Authorization": f"Bearer {key}",
                 "Content-Type": "application/json"},
    )
    print(urllib.request.urlopen(req).read().decode())

Reading the plan response

The cost field is in USD micros, which are millionths of a dollar. A one-minute render comes back as 100000, which is $0.10, and a two-minute render as 200000. Divide by 1,000,000 before you compare it with a dollar budget, and keep the micros if you add many plans together, because micros are integers and do not drift.

The segment count matters for a second reason. Sume refuses a single-pass render above 12 slots and chunks longer programs on its own by default, so a plan with more than 12 segments tells you the render will be chunked. That is a runtime detail and does not change the price, but it explains why a long cut takes longer than a short one.

A pre-flight for a 200-cut batch

Imagine 200 cuts of 58 to 64 seconds. At 58 seconds each bills one minute, $0.10, and at 64 seconds each bills two, $0.20, so a batch that drifts over the minute doubles its render line from $20 to $40. A plan pass over all 200 documents is free and finds the 64-second cuts before the render does.

Do the pass in the same script that builds the documents, and let it fail the batch when the estimated total is more than the line you approved. The Timeline docs list every field and the refusal codes, and the error docs list the status codes that a real submit can return.