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
Queue-level webhook_url in a Sume bulk body fails: set it per item
A Sume bulk body takes concurrency, items and an optional key. A top-level webhook_url is an unknown field; set communication.webhook_url on each item.
Bulk queue finished_at: measure the wall time of a 100-item batch
A Sume bulk queue sets finished_at when every item is terminal, so created_at to finished_at is your wall time. It does not mean every item succeeded.
Bulk run concurrency 3 with 8 items: what the 202 receipt shows
With concurrency 3 and 8 items, the Sume 202 shows three running and five queued. Item 3 starts when item 0 finishes. Here is how the window and counts behave.
Bulk run has no empty item: skip sheet rows without a finished script
A Sume bulk item must name at least one of instruction, input, previous_run_id or attachments. Filter unfinished sheet rows on your side before you send.
One dead image URL fails the whole 100-item Sume bulk create
Sume fetches every attachment at create time, so one broken image URL in a bulk body fails the create before any queue exists. Check URLs first.
A failed Format run webhook still has the receipt: salvage artifacts
When a Sume Format run fails, the webhook has status ERROR but payload is still the full receipt, with artifacts and output_error. Read them before you retry.
Format io is null on older Formats: pick by your own input kind
On Sume's Format list, the io block is null for Formats saved before the field existed. Do not route on it alone; read input_kind and output_kind when present.
Free plan 120 writes a minute: a 100-item bulk queue is one request
A Sume bulk create is one POST against the write budget, and polling spends the separate read budget. Here are the per-plan limits and what that means.
Localize one Sume Format into six languages: one bulk item each
To make one ad in six languages, send six items to one Sume bulk queue with the language in input and one Idempotency-Key scheme. Here is the shape and limits.
Log format.version on every bulk child: which recipe made which video
A Sume bulk queue can span a Format edit. Store format.version from each child receipt so you know which recipe made which video.
primary_output_key on a headline string: primary_output_url is null
If primary_output_key names a text field in your Sume output_schema, the receipt echoes the key but primary_output_url is null. Point it at the media field.
Refresh last year's holiday Format: one commit, rerun with v2 keys
Update a Sume Format for this holiday season with one Contents API commit, then re-queue with v2 Idempotency-Keys. Runs read the package they started with.
Seasonal Format: a new slug per season, or edit the same one in place?
Edit one Sume Format in place and keep one address, or create a slug per season and keep each look reproducible. Contents API has no revert, which tips it.
Share one packshot across 100 bulk items with an asset_id
To reuse one product image in a 100-item Sume bulk run, upload it once and pass asset_id. Sume does not copy an asset_id or a media.sume.com URL again.
Can a Sume Format package hold a product CSV? Only five file types
A Format package accepts .md, .json, .yaml, .yml and .txt files. Put the product feed row in each run's input, not in the package. Here are the limits.
Same Idempotency-Key on two Formats starts two runs: holiday A/B
A Sume Idempotency-Key is scoped to one Format. Reusing a key across two holiday Formats starts two runs, so make the key carry the variant.
Sume Format run timeout: your client stops, the run keeps billing
A client timeout on a Sume Format run does not cancel it. The run continues and bills. Store the run id, read expires_at, and call cancel_url to stop it.
Create a Sume Format over the API: auto_init and the first package sha
POST /v1/formats with auto_init (default true) commits a minimal SKILL.md and returns package_sha, contents_url and vanity_invoke_url. Keep all three.
Sume Format webhook: verify the timestamp, register the final URL
Sume signs format.run.terminal with HMAC-SHA256, expects a response in 10 seconds, retries up to 10 times and does not follow redirects. Register the final URL.
Sume Format run idempotency key: order id plus version, not uuidgen
Derive the Sume Format run Idempotency-Key from your order id plus a version. A fresh uuidgen per request makes the header do nothing and double-bills retries.
List Sume Format runs: cursor pages, newest first, one Format only
Sume lists Format runs per Format, newest first, limit 1 to 100 and a next_cursor. There is no cross-Format list, so keep your own index of run ids.
Sume Format output_schema: strict false does not loosen the rules
Setting strict to false in a Sume Format output_schema does not relax the OpenAI-strict subset. Fix the schema instead. Responses-style text.format is refused.
Commit several Sume Format files in one PUT: a change set
PUT a files list to a Sume Format's contents URL and it is one commit with one version bump. Files you do not name stay as they are. Existing paths need a sha.
Bulk Format runs on Sume: concurrency 1-16, 1-100 items, fail early
A Sume bulk run takes concurrency 1 to 16 and 1 to 100 items. A bad item fails the whole create with details.index before any queue exists. Nothing dispatches.
Which JSON Schema keywords a Sume Format output_schema accepts
Sume Format schemas use an allowlist: unknown keywords fail with unsupported_keyword. Number bounds are allowed; oneOf and allOf are not. Table inside.
A queue of 100 Shorts: unique input and a cap per item
Sume bulk runs queue up to 100 Format runs. Give each item its own input and spend cap so no two Shorts read alike. Limits and a request shape from the docs.
Is running the same Format weekly a template to YouTube?
A Sume Format is a saved recipe, not a saved video. How to separate the repeatable process from the repeatable output so weekly Shorts do not read as templated.
Release a 50-SKU holiday batch in two bulk queues: 5 first, 45 after
Submit 5 SKUs as a pilot queue, review the clips, then queue the other 45. Sume bulk queues take 1-100 items at concurrency 1-16. Runnable payload builder.
Back-in-stock video for one SKU: send the facts as input, not prose
One restock clip is one Format run: put SKU, stock count and ship date in an input object, add a short instruction, and key the run by SKU and date.
Black Friday ad copy and video in one call: an output_schema example
Bind an output_schema with headline, caption and a SumeMediaFile video so one Format run returns typed copy and the clip together, with primary_output_key set.
Bulk queue concurrency 16 but fewer runs start: workspace concurrency
Concurrency 16 is a ceiling on the queue, not a promise. Workspace generation concurrency still applies to every child, so some start late or fail to start.
Cyber Monday price changed after render: rerun one SKU or continue it?
One SKU's price changed after its video rendered. Send a new run with new input, or continue the old run with previous_run_id. Here is when each fits.
Gift message field in a strict output schema: optional means nullable
In a Sume output_schema every property must be required, so an optional gift message is a string-or-null union, not an omitted key. Here is the shape.
Holiday gift set video from 30 photos: the Sume attachments limit
A gift set has many parts. Sume accepts up to 30 images in attachments and a 30-file media budget per run, so plan which shots go in before you call.
Price-drop sale videos for 200 SKUs: two bulk queues, one key each
A bulk queue holds at most 100 items. For 200 marked-down SKUs, send two queues, give each its own Idempotency-Key, and track both queue ids yourself.
Which Sume Format for holiday product video? Read its io profile
Do not guess from the slug. GET /v1/formats/sume/{slug} returns description, io profile and a verified showcase, so you can match input shape to your catalog.
Format status_url never holds output: poll it, then fetch the result
A Sume Format run's status_url returns a small poll payload with no output or artifacts. Poll it with backoff up to expires_at, then call result_url once.
Five ad variants in one Format run: a variants[] output schema
Bind a schema with a variants array, a nullable video_url per variant and maxItems 5, so a partial run still returns the variants it finished.
One Format run with five variants or a five-item bulk queue?
One run gives you five variants under one cap and one receipt. A bulk queue gives five receipts, a concurrency window up to 16 and per-item retry.
Retry only the missing ad variants with previous_run_id on a Format
When a variants run returns some clips as null, continue it with previous_run_id and name the missing slots, so you do not pay for the finished variants again.
Check a Format run's video with ffprobe: duration and audio stream
Before you publish a Format run's clip, run ffprobe on primary_output_url, confirm an audio stream exists and compare its length with duration_ms.
MAI-Voice-2.1 and Format runs: get the voiceover as its own file
A Format run cannot be told to use MAI-Voice-2.1, since its tools pick the audio model. Bind an audio field to get the voiceover track as a file.
One Idempotency-Key, two Sume Formats: you start two runs
A Sume idempotency key is scoped to one Format, so one key sent to two Formats starts two paid runs. Build keys from order, Format and version.
Gemini Omni edit: direct Video Router call or a Sume Format run?
Use the Video Router edit call for one precise change to one clip. Use a Format run when the job has steps, a schema and a spend cap around the edit.
A failed Format run still lists its media: read artifacts[], continue
A Sume Format run that ends failed still lists its media in artifacts[], and you can continue it with previous_run_id. Here is when that works.
Cancel one bulk-run child: pay for what finished, slot moves on
Cancel a Format run inside a bulk queue with POST /v1/format-runs/{run_id}/cancel. The item turns canceled, its slot starts the next one, no webhook fires.
Cost per Reel from Format run receipts: sum billable_amount_usd_micros
Each Sume Format run receipt reports usage.billable_amount_usd_micros. Divide by 1,000,000 for dollars. A Python loop prices a Reel batch from its run ids.
ElevenLabs Flows templates API vs a Sume Format run with a webhook
ElevenLabs added Flows template endpoints on Sep 28: list, details and run with a webhook. Sume Formats give the same three steps for image, video and audio.