Sume Agent Completions or a Format run: which should code call?
Pick between POST /v1/agent/completions and a Format run: open-ended instruction versus a reusable recipe, fresh thread each time, schema output, and cost cap.
Call a Format run when you have a repeatable recipe with a known output: a named Format, optional output_schema, input data and attachments. Call Agent Completions when the task is open ended and you want the Sume video agent to decide the steps from an instruction or messages. Both are asynchronous and return a receipt to poll.
Completions give you a fresh thread every call, no streaming, and a required generation_spend_cap_usd. The only model value is sume-agent.
Side by side
| Aspect | Format run | Agent Completion |
|---|---|---|
| Path | /v1/formats/{handle}/{slug}/runs | /v1/agent/completions |
| Receipt id | arun_ | agrun_ |
| Poll | status_url | /v1/agent-runs/{id} |
| Spend cap | Optional, default applies | Required |
| Scopes | formats:read, formats:write | agent_completions:read, agent_completions:write |
Rule of thumb
If you can name the recipe, use the Format: its output is predictable and its schema is validated. If you cannot, use a completion and plan to inspect the result.
Sources
Related posts
More in Agents
- Sume Action spend cap: 1 dollar default, per-run cap only lowers
A Sume Action carries a default spend cap of 1 dollar. A per-run cap can lower it but not raise it, so a heavy video job needs the cap changed on the Action.
- Sume Action overlap: on_active_run skip gives 200, reject gives 409
What happens when a Sume Action run starts while the last one is active: skip gives 200 with status skipped, reject gives 409 action_run_in_progress.
- What is an AI video agent? One that talks, or one that makes
An AI video agent can mean a live on-camera persona like a Tavus PAL, or an agent that makes videos for you. Which one Sume is, and how to call it from code.
- Run the Sume video agent from your backend with Agent Completions
POST /v1/agent/completions runs the same agent as the Sume Agents chat, with tools and media generation, and returns an async run receipt you poll or webhook.
Written by Sume