Enterprise
Enterprise
Formats and Agents for Sume Enterprise workspaces, documented beside the public API.
Formats and Agents are part of Sume Enterprise. They run in enterprise workspaces. The public API (Images, Video, Media tools) is open to every API key; the pages in this section need an enterprise workspace and keys with the scopes each page names.
Pricing is the same as everywhere on Sume: generations are charged at the provider's cost, with no markup.
Formats
A Format is a saved production recipe that your backend calls by name. Start with the Format API.
| Page | What it covers |
|---|---|
| Create a run | POST /v1/formats/{handle}/{slug}/runs, field by field. The request body, idempotency, spend caps, keys and scopes, and every error the create call returns. |
| Runs and results | The Format run receipt, and the two ways to get it. Poll the run, or take one signed webhook. Lifecycle, progress, continuing, canceling, listing. |
| Bulk runs | Queue up to 100 Format runs with a concurrency window — POST …/bulk-runs, poll GET /v1/format-run-queues/{id}, and read each child at GET /v1/format-runs/{run_id}. |
| Editing a Format package | Read and commit the files behind your own Format over /v1, the same way you would use the GitHub Contents API. |
| Structured output | Bind a JSON Schema to a Format run and get typed, validated JSON back — supported schema rules, the post-run projection, and every failure mode. |
| Format catalog | Ready-made Sume Formats you can call from your own backend, with the scopes, curl, and run lifecycle for each. |
| Errors and spend | Every error the Formats API returns, by stage. The envelope, what to do per code, what a failed run carries, webhook delivery outcomes, credits and spend caps, and rate limits. |
| Cookbook | Copy-paste recipes shaped like production traffic. A live-commerce run with typed output and a webhook, a webhook receiver in Node and Python, a scene retry on the same thread, a sheet-driven batch, and a wait loop. |
| Embed a Format in your product | Run a Sume Format from your own dashboard on behalf of your customer — key custody, idempotency, webhooks, spend caps, artifacts, and failures. |
| Waiting for runs and jobs | The SDKs wait for generation jobs for you. Format, Action and Agent runs are waited on over HTTP, with the loop on this page. Prefer webhooks in production. |
Agents
Agent Completions and Actions run Sume's agent from your backend. Start with Agents.
| Page | What it covers |
|---|---|
| Agent Completions | Call the Sume Studio Agent like a model — messages or an instruction in, an async agent.run receipt out, with tools, media generation, and a sandbox. |
| Scheduled | Run a saved Agents automation on a recurring schedule, and how its runs differ from one-shot generation jobs. |
| Create a schedule | Author a recurring Agents automation in the dashboard, and pick a cadence. |
| Advanced: run a schedule via API | Advanced path — authenticate, invoke POST /v1/actions/{action_id}/runs or the {handle}/{slug} vanity path, and handle every error the invoke path returns. |
| Runs and results | Poll a schedule run, read its structured output and artifacts, and cancel it. |
| Run webhooks | Receive one signed POST when an Action, Format, or Agent Completion run completes or fails. |
| Safe automation | Guidelines for using Sume APIs and tools from agents without leaking secrets or crossing workspace boundaries. |
Patterns
- Best practices: Short patterns for calling Formats and Agent Completions well — with copy-paste examples.