Formats
Sume Formats over the API: create and version a Format, call it, run bulk batches, get structured output, take webhooks, and debug failed runs.
Start with What is a Sume Format? Turn an agent thread into one API call
Know a Sume bulk batch is done: count terminal webhooks vs item count
A Sume bulk queue has no webhook. Put a webhook_url on each item, verify the signature, dedupe by request_id and count terminal events to the item count.
Localized video batch: one Sume bulk queue per language
Split a multilingual batch into one Sume bulk queue per language so each language gets its own concurrency, spend cap, idempotency key and retry.
Make Iterator and Array aggregator: build a Sume bulk items array
In Make, an Iterator splits an array into bundles and an Array aggregator joins them. Use the pair to turn sheet rows into a Sume bulk items array.
Map Sume bulk queue results back to spreadsheet rows by item index
A Sume bulk queue lists items in the order you submitted. Use each item's index to write results back to the right spreadsheet row, and handle run_id null.
Pilot 3 rows before a Sume bulk batch and estimate spend from receipts
Run three rows first, read usage.debited_usd_micros from each receipt, and scale up. Skip billable_amount_usd_micros: it leaves out the agent turn.
Send more than 100 spreadsheet rows to a Sume Format in chunks
One Sume bulk queue takes 1 to 100 items. For a 450-row sheet, split it into chunks and key each chunk so a retry never doubles spend.
Spreadsheet with more than 64 columns: nest them in one Sume input key
A Sume run input allows 64 top-level keys and 2 MiB. Nested keys do not count toward the 64, so a 90-column sheet row fits under a single key.
Sume bulk item expires_at: 90 minutes start at dispatch, not at submit
A Sume run's expires_at is 90 minutes from created_at. A bulk child is created when dispatched, so a queued item's clock has not started.
Sume schedule cron: why @weekly and 6-field cron are rejected
Sume schedules take only standard 5-field cron. Macros like @weekly and 6-field expressions with seconds are rejected, so convert them before you create one.
Sume scheduled run across daylight saving: Monday 9am New York
A Sume schedule takes a 5-field cron and an IANA timezone. Across the 2026 clock changes a Monday 9am New York job fires once, and its UTC hour shifts by one.
Weekly content calendar as JSON: a Sume Format output schema
Bind a JSON Schema to a Sume Format run and get a seven-day content calendar back as validated JSON, with real dates, enums and media references.
Worst-case spend of a 100-item Sume bulk queue and its spend caps
Each bulk item can carry its own spend cap up to $500, and caps are not clamped to the Format cap. Do the worst-case math before you submit.
Zapier Catch Hook as a Sume per-item webhook receiver: 10 MB, 200
A Zapier Catch Hook can receive a Sume run webhook. Zapier's own help sets the payload cap and the response, which decide what Sume sees on delivery.
Detect that someone edited your Sume Format before the weekly run
Pin the Format's package_sha and version, and compare them right before a weekly run. If a teammate edited the Format, stop the run instead of paying for it.
Edit a Format mid-batch: which version do queued items use?
A bulk queue dispatches items over time. If you edit the Format while it runs, later items can run the new package. Here is how to tell from the receipts.
Stage a Sume Format change with no branches: second slug, If-Match
Sume Formats have no branches or revert. Test a change in a second Format slug, then promote it to the live one with a single If-Match PUT of the files.
Bulk virtual try-on videos for a catalog: 100 SKUs per queue
Queue up to 100 try-on runs in one POST: concurrency 1 to 16, one garment image per item, a spend cap each, and how to read the failures afterwards.
Shorts ad copy: 40-character headline, 90-character description
Google recommends 40-character headlines and 90-character descriptions for the Shorts ad CTA card. Draft copy in bulk with Sume and check lengths before upload.
Shop Creative Hub limits: 50 per upload, 10k a month, batch math
Creative Hub for GMV Max takes 50 videos per upload and 10k a month. What that means for Sume bulk queues of 100, and where the 200-video link cap bites.
Run a 5,000-SKU product video catalog in 50 bulk queues
Split 5,000 SKUs into 50 Formats bulk-run queues of 100, key each shard so a crashed script resumes, and read counts.failed before you call a shard done.
Revise 20 finished videos in one Sume bulk queue with previous_run_id
Each bulk item can carry previous_run_id, so one queue re-edits twenty finished runs. A preflight for thread_id, the repeated schema, and the cost per item.
Bulk Format runs: 100 items, 16 at once, what completed means
Sume bulk runs take 1 to 100 items at concurrency 1 to 16. A queue marked completed means every item is terminal, not that every item succeeded.
Format output_schema for partial results: nullable and primary key
How to design a Sume Format output_schema so a run that makes the video but misses a caption still passes: nullable fields, no minItems, and primary_output_key.
Format run expires_at: 90 minutes from created_at, or sooner
How long a Sume Format run can live, which statuses are terminal, and how to poll the status_url without waiting on an event stream that does not exist.
Format run spend cap: generation_spend_cap_usd max 500, zero rejected
How generation_spend_cap_usd works on a Sume Format run: the 500 ceiling, why 0 is rejected, null meaning 500, and what the receipt does and does not include.
Format run retry: same key and body gives 200, changed body 409
Retrying POST /v1/formats/{handle}/{slug}/runs with the same idempotency_key and body returns the first run; a changed body or a parallel duplicate returns 409.
Webhook or polling for Sume Format runs, and the 1 MiB payload rule
Pick between the signed terminal webhook and polling status_url for Sume Format runs: delivery limits, dedupe keys, and what a payload over 1 MiB looks like.
Format structured output: anyOf passes, oneOf and allOf are rejected
Which JSON Schema keywords a Sume Format output_schema accepts, the 400 output_schema_invalid shape, and how it lines up with OpenAI strict structured outputs.
Format output filled_by: agent versus projection, exact URLs
Sume Format runs fill structured output either through the agent or by projection. Learn which one ran, what projection can see, and the exact-URL gate.
Sume webhook missed? POST /v1/format-runs/{run_id}/webhook/redeliver
Replay a Format run webhook without rerunning: the redeliver endpoint, the formats:write scope, and the two 409 errors for no webhook or a run still going.
Verify a Sume Format webhook in Python with an empty-secret guard
Verify x-sume-webhook-signature in Python: HMAC-SHA256 over timestamp.raw_body, a five-minute window, constant-time compare, empty secret refused.
Sume SDK subscribeFormatRun: 20-minute timeout vs 90-minute runs
subscribeFormatRun in @sume-com/sdk polls every 2 seconds and times out at 20 minutes by default, while a Format run can live 90. Set the timeout on purpose.
Calling a Formats by Sume entry: the sume handle, not yours
Formats by Sume run at POST /v1/formats/sume/{slug}/runs with any key holding formats:write. Your own handle returns 404, and a fork lives at your handle.
Format output_schema keywords: pattern and minLength yes, not no
Which JSON Schema keywords a Sume Format output_schema accepts (pattern, minLength, multipleOf, enum, const) and which fail as unsupported_keyword.
Format output_schema nullable: true is rejected, use a type union
OpenAPI nullable: true fails a Sume output_schema as unsupported_keyword. Declare optional fields as type [string, null] and keep them in required.
Format output_schema: $ref "#" fails, a $defs self-reference works
Sume rejects root recursion via $ref "#" in output_schema as unsupported_ref but accepts a $defs entry that references itself. How to write a tree.
Format output_schema root must be an object: wrap an array root
A Sume Format run rejects an output_schema whose root is an array or type union with 400 and rule root_must_be_object. Wrap it in a named key.
Format output_schema strict false: no loose JSON mode on Sume
Sending strict: false with a Sume Format output_schema is accepted but relaxes nothing, and there is no json_object mode. Bind a schema or use the built-in.
Format run media URLs are public: copy on webhook or proxy
Sume Format run media lives at durable public media.sume.com URLs. If customer A must not see customer B's video, copy it at receipt time or proxy it.
Format run webhook retries: dedupe on request_id, order by created_at
Sume Format run webhook retries repeat request_id, which equals run_id. Dedupe on it and order deliveries by created_at, which changes per built body.
Sume webhook retry schedule: 30s doubling, 10 tries, 1h cap
Sume Format run webhooks retry up to 10 times with min(max(30s x 2^(attempt-1), Retry-After), 1h). The arithmetic of that schedule and what to do when it ends.
Format batch commit: files is a change set, so delete is separate
A batch PUT to a Format's contents commits many files at once. Unnamed files stay, deletes need DELETE, and one stale sha lands nothing.
Format output rejects an uploaded file's URL: generated media only
The Sume output URL gate admits only media the run generated. An uploaded file's URL in your schema fails the projection and takes all of output.
Continued Format run: artifacts span the thread, usage is per run
A Sume Format run continued with previous_run_id gets a new id and cap. Its artifacts[] lists the whole conversation, while usage stays per run.
SumeMediaFile duration_ms is checked within 10% of the real file
A duration_ms in Format output must match the run's artifact ledger within 10%, or the projection fails. A null means not measured, not zero.
output_schema max_string_length: descriptions can spend 120,000
A Sume Format output_schema has a document-wide 120,000-character string budget, plus depth 10, 5,000 properties and 1,000 values per enum.
Format run spend: wait for usage.final before you quote a cost
On a Sume Format receipt, debited is the cost, held and refunded are not spend, and final turns true only once no hold is open.
Magazine cover and model portrait Formats for beauty sellers
Two Sume Formats make 9:16 beauty images from a packshot: a magazine-cover campaign and a model product portrait. When each helps and what to verify.