Sume API glossary: Format run, spend cap, idempotency key
Sume API terms in one or two sentences each: Format, run, job, spend cap, idempotency key, wallet, agent fee, webhook, artifact, and more, with links.
In the Sume API, a Format run is one execution of a saved recipe: one fresh sandbox, one agent turn, one receipt. A spend cap is the most one run may spend on generation, and an idempotency key is a header that turns a retried create into a replay of the original instead of a second, paid run.
Each term gets one or two sentences from Sume's docs, read on 2026-09-27, plus a link to the post that covers it. For the product map, start with Sume basics.
What are Formats, runs, and jobs?
Runs execute the agent; jobs are single model calls.
| Term | What it means | Read more |
|---|---|---|
| Format | A saved production recipe: a SKILL.md body plus reference files, called by handle and slug. | What is a Sume Format? |
| Format run | One fresh sandbox, one agent turn, one receipt (arun_…). A run that cannot finish comes back failed. | Format run lifecycle |
| Formats by Sume | Ready-made Formats at the reserved sume handle; the run and its spend belong to the calling key. | The Sume Format catalog |
| Bulk run | Up to 100 Format runs queued in one request, with a concurrency window of 1–16. | Format bulk runs |
| Agent Completion | The agent on an ad-hoc task you send with every call. It stores nothing, and generation_spend_cap_usd is required. | Agent Completions |
| Scheduled | A saved agent automation that runs on a cadence; its API namespace is /v1/actions. | Scheduled agent runs |
| Generation job | One model invocation, read back from /v1/jobs/{id}; runs are a separate resource. | Sume job vs run |
What do spend cap, wallet, and agent fee mean?
What a call may cost, and when it is refused.
| Term | What it means | Read more |
|---|---|---|
| Spend cap | generation_spend_cap_usd: a run's generation ceiling, up to the $500 platform maximum. A Format that never set one reports $400. | Spend caps for AI agents |
| Wallet | One balance: video generation, the Sume Agent, Formats, and the API all draw from it. | How Sume pricing works |
| Agent fee | Charged on top of the model amount: usage is billed at each model's published rate plus a 5.5% agent fee by default. | The Sume agent fee |
| Reserve, capture, refund | Paid generation reserves an estimate at submit, captures it on success, and refunds it on failure or cancellation before capture. | Do failed jobs cost money? |
debited_usd_micros | What the wallet actually deducted for a run, in USD micros (1,000,000 is $1.00). | What one run cost |
| Concurrency | How many paid generation jobs can be processing at once, set by plan. Extra jobs wait as queued; a full queue is 429 queue_full. | Concurrency and queueing |
| Rate limit | A per-minute request budget per key, with separate read and write buckets. Over it is 429 rate_limited. | Errors and rate limits |
What is an idempotency key, and which request terms matter?
How a request is retried, reported, and traced.
| Term | What it means | Read more |
|---|---|---|
| Idempotency key | The Idempotency-Key header. The same key and body returns the original run; a different body is 409 idempotency_conflict. | Idempotency keys |
| Receipt | The run object a create returns: its status, plus status_url, result_url, events_url, and cancel_url to follow. | Sume API status values |
| Webhook | One signed POST when a run completes or fails, format.run.terminal for Formats. Jobs send job.completed, job.failed, or job.canceled. | Signed webhooks |
mode | How a job submit reports back: async, sync or subscribe (a wait of at most 30 seconds), or webhook. Omitted, it is async, except on POST /v1/images, which defaults to sync. | Sync vs async |
request_id | Its value depends on where it appears. In an error body it is the req_… id to quote to support, also sent as the x-sume-request-id header that every response carries. | request_id vs job_id vs run_id |
Which terms describe output and access?
What comes back, and who may ask for it.
| Term | What it means | Read more |
|---|---|---|
| Artifact | A durable file a run generated, on a media.sume.com URL that does not expire and is public to anyone holding it. | Do video URLs expire? |
primary_output_url | The one thing to show from a run. It is null unless the run completed. | Embed AI video in your product |
output_schema | A JSON Schema, inside a strict subset, that shapes a run's output. A schema outside it is 400 output_schema_invalid. | Output schema templates |
sume/auto | A model value that lets Sume pick the video model family. Responses never disclose which family ran. | OpenRouter-compatible video API |
| API key and scopes | Workspace-scoped keys, sent server-side. Scopes such as formats:read and formats:write are fixed when the key is created. | How Sume API keys work |
| Workspace | Where keys and spend resolve. A team Format needs a key created in that team's workspace. | Share a Format with another workspace |
Sources
Related posts
More in Developers
- Sume API headers: auth, idempotency, If-Match, rate limits
Every HTTP header the Sume API reads or sends: the API key, Content-Type, Idempotency-Key, If-Match, request ids, rate limits, and webhook signatures.
- Sume API output file formats: MP4, PNG, WebP, WAV, MP3
The file each Sume API endpoint returns: MP4 from Timeline and the editing tools, PNG, JPEG, or WebP images, WAV or MP3 audio, and JSON transcripts.
- Sume API pagination: cursor, starting_after, and page limits
How each Sume list endpoint pages: cursor and has_more on Formats and runs, starting_after on /v1/jobs, and limit-only lists that have no cursor.
- Sume API status values: jobs, runs, queues, and webhooks
Sume API status values in one place: jobs, /v1/videos, Format and Agent runs, bulk queues, webhook deliveries, usage rows, grants, and balance.
Written by Sume