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
Does Synthesia Syren have an API? A backend route with Sume Formats
Synthesia's Syren beta launched Oct 9 as an in-app button; its launch post mentions no API. How to call a saved video recipe from your server with Sume.
Holiday Format run cap in credits: 8,000 to create, 600 to retry
Set generation_spend_cap_credits per Format run for Black Friday: the docs' 8,000 for a full create, 600 for one scene retry, and how the cap fails a run.
Three app previews show in search: queue three hook variants at once
Apple shows up to three app previews in search results. Queue three hook variants of one app video as one Sume bulk run.
Green screen ad API: run the sume-green-screen Format
A green-screen or talking-head overlay ad from code: call Sume's sume-green-screen Format, set a spend cap, and read the finished video from the run receipt.
Slideshow ad API: call the sume-slideshow Format from code
Need a slideshow ad from a script or a cron job? Sume's sume-slideshow Format starts from one POST. What it is for, what it is not, and how to read the result.
Skincare product stills by API: sume-water-splash-hero
Hydration stills for skincare: call Sume's sume-water-splash-hero Format for a splash hero image, plus sibling still Formats for texture and set.
Handing a Format to another team: the API key checklist
Before another workspace calls your Sume Format, check key scope, key type, the API tab, the spend cap and the webhook secret. Lists each 403/409.
How many Format runs can one API key poll at once?
Read budgets per minute by Sume plan, turned into a count of Format runs you can poll at 5-second and 30-second intervals, and why a bulk queue saves writes.
Make a partial Format result legal in your output_schema
Sume Format output_schema has no optional properties. Use nullable unions, SumeMediaFile refs and honest nulls so a run that makes 2 of 3 clips still returns.
Which failed Format runs can you retry without paying twice?
A decision table for failed Sume Format runs: which codes mean retry, which mean continue with previous_run_id, and which mean fix your input first.
Re-run a Format on purpose: version the Idempotency-Key
How Sume Format idempotency works, why a fresh uuid per request defeats it, and how an order id plus a version number gives safe retries and deliberate re-runs.
Format works in chat but fails over the API? The approval gate
A Sume Format that pauses for approval in chat runs unattended over the API. See what changes, why unattended_blocked appears, and a pre-flight list.
Does your Format webhook receiver pass OWASP's checklist?
Check a Sume Format webhook receiver against OWASP's webhook cheat sheet: raw body, HMAC, five-minute window, dedupe on request_id, and where docs are silent.
Sume Format instruction limit: why long briefs belong in input
A Format instruction accepts 8000 characters but only about the first 4000 reach the prompt. Put long briefs in the input field, which is stored whole as data.
Which Format version ran my API call? Check the receipt
Every Sume Format run receipt carries format.version. Read it after you edit a package, so a bulk batch or schedule is never judged against the wrong version.
Sume Format run image attachments: 30 images, 30 MB, 500 MB
A Sume Format run takes up to 30 images, 30 MB each and 500 MB per run, in JPEG, PNG, WebP, GIF, or AVIF. Here is what invalid_attachment means.
Customer text in a video prompt: input vs instruction in Sume
Put customer-supplied text in the Sume Format input object, stored as data, and keep your own directive in the instruction. Here is why that split helps.
Is there an endpoint to list all Format runs? No, build an index
Sume lists runs per Format with a cursor, but there is no GET /v1/format-runs across Formats. Here is the small run index that fills the gap, and what to store.
How long to poll a Format run: use expires_at, not your own timeout
A non-terminal Format run receipt carries expires_at, 90 minutes after created_at or earlier if the run goes silent. Set your poll ceiling from it and back off.
Format run media URLs never expire and anyone can open them
Media from a Sume Format run lives at durable media.sume.com URLs that anyone with the link can open. What that means for per-customer access and retention.
Share a Format with another workspace: grants, accept and the 404
A Format owner can share a team Format with another workspace by grant. The other workspace accepts, calls it with its own key, and pays its own bill.
Format input vs instruction: where scraped product copy should go
Put scraped or customer text in the input object, not in instruction. Sume writes input to a file and marks it as data. Limits: 64 keys, 2 MiB, 4000 characters.
Format webhook outcome: ok, degraded or error, and what to do
The format.run.terminal webhook has three outcomes. Verify the sume-v1 signature, then branch: ok uses output, degraded uses artifacts, error is a failed run.
Spreadsheet to Format bulk queue in Node: 100-row limit and key rules
Turn a CSV of products into one bulk-runs request in Node. Items are capped at 100, concurrency at 16, and the Idempotency-Key must be new for each batch.
Course intro video output_schema: optional fields must be nullable
Bind a strict output_schema to a course-intro Format run so the intro and title card come back as typed fields. Optional keys must allow null.
Team Format returns 403 workspace_key_required: which key to mint
A personal key on a team Format gets 403 workspace_key_required. details.workspace_id names the workspace. Create the key there. Other keys see 404.
Format package files: which types and paths the Contents API accepts
A Sume Format package accepts only .md, .json, .yaml, .yml and .txt files, one folder deep, with SKILL.md required. The full rule list and the error you get.
Format Contents API: If-Match stops two agents overwriting each other
Per-file sha checks do not catch two agents editing different files. Send If-Match with package_sha and handle 409 format_package_sha_mismatch.
Cancel a Format run: cancel_effect, no_op and what you still pay
POST cancel on a Format run is idempotent. cancel_effect says canceled or no_op. You pay for generation done before the cancel, and no webhook is sent.
Same idempotency key, new body: Sume Format run 409 vs 200 replay
Same Idempotency-Key and body on a Sume Format run gives 200 with idempotency_hit true. A changed body or attachments gives 409. Bulk replays stay 202.
Sume Format output_error codes: which to retry and which to fix
output_extraction_failed is transient: re-read the run, then retry with a new key. output_schema_unsatisfied means the schema or recipe is wrong. Six codes.
Bulk queue item with run_id null and format_run_failed_to_start
In a Sume Format bulk queue, an item that never started has run_id null and an error like format_run_failed_to_start. The queue goes on; resubmit that row.
Format webhook: 10 s timeout, 10 attempts, about 3 h 5 min of retries
A slow Format webhook gets 10 tries. Without jitter, the last starts 11,010 s after the first; with 10 s timeouts the span is about 3 h 5 min. Code included.
Fix one wrong number: Claude Motion edit vs a Sume Format retake
Claude Motion edits a number in place. In a Sume Format run a changed word or number means a new production; a look change is a retry at about 1/20 the cost.
Format API: webhook or polling for a run that takes 15-30 minutes
A Sume Format run returns 202 and finishes in minutes, not seconds. Take the result by signed format.run.terminal webhook or poll the run; no SSE stream.
Queue 100 Format runs at concurrency 16: 7 waves, one idempotency key
Sume bulk runs accept 1 to 100 items and a concurrency window of 1 to 16. The queue has no webhook, and completed does not mean all succeeded.
Reels ad safe zone in pixels: 358 top, 896 bottom, 86 sides
Meta's Reels ad page keeps about 14% top, 35% bottom and 6% per side clear on a 1440x2560 frame. Here is the pixel math and a Sume caption anchor.
LinkedIn Page video: 10 or 15 minutes, and is MOV allowed?
Two LinkedIn help pages give different Page video limits (10 vs 15 minutes, MOV in or out). Ship MP4 under 10 minutes and use Sume video trim to get there.
LinkedIn video uploads but never processes: ProRes fix
LinkedIn says a ProRes file may upload but not process. Probe the codec with Sume video inspect, then re-encode to H.264 MP4 with an exact video trim.
LinkedIn video 10 to 60 fps: conform a 120 fps phone clip
LinkedIn Page video accepts 10 to 60 fps. A 120 fps phone clip or an 8 fps timelapse is outside that. Probe the rate, then conform it with Sume trim output.fps.
LinkedIn video ad sound rate: under 64 kHz, read it with a probe
LinkedIn's video ad spec lists AAC or MPEG4 sound at under 64 kHz. Sume video inspect returns the audio codec and sample rate so you can test a file first.
Pinterest video ad 4-second minimum: trim allows 0.2, so check
Pinterest video ads need 4 seconds minimum, 15 minutes maximum. Sume trim cuts from 0.2 seconds, so read duration_seconds on the result before you upload.
Reconcile an overnight Sume Format batch: list runs, limit and cursor
List a Format's runs newest first with limit 1 to 100 and a cursor. There is no cross-Format list, so one call per Format. Curl loop to page through a batch.
Shortest ad video: Pinterest 4 s, LinkedIn 3 s, Google action 10 s
Minimum video length per ad platform, read from each vendor page on 2026-10-08, against the 0.2 second floor of Sume video trim. One cut, one duration check.
Stop a Sume Format bulk run mid-batch: cancel starts the next item
The bulk API has no cancel-queue endpoint, and canceling a running child frees its slot for the next item. How to stop a runaway batch, and how to size queues.
Wallet 402 or spend cap: which stops a Sume holiday batch first
A low wallet blocks a Format run at create with 402 insufficient_credits; a spend cap ends a running run as failed. Sizing a cap per item.
Which ready-made Sume Formats can I call today? 27 slugs
Sume's first-party Format catalog answers at the sume handle with 27 slugs, from UGC and product demos to try-on, product splashes and recreate. List and call.
Format run usage after a cancel: debited, held, refunded and final
After you cancel a Sume Format run, usage shows the spend. How debited, held, refunded and final differ, and when the number is settled in a holiday batch.