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
Resolve 21.1 batch render with AI assistants vs Formats bulk runs
Resolve 21.1 lets AI assistants like Claude batch render. Sume Formats bulk runs queue 1 to 100 items at concurrency 1 to 16 over one API call.
Water splash, sunscreen, formula texture: heroes from a packshot
Three Sume Formats turn one packshot into a 9:16 beauty hero image: water splash, sunscreen splash and formula texture. What each does and what to check.
Check a Format output schema against Sume size limits first
Sume rejects schemas deeper than 10 levels, over 5000 properties or 120,000 characters. A local counter that catches max_depth and max_string_length early.
Format run media budget: 30 files, 10 videos, 10 audio for a lookbook
A Sume Format run shares one attachment budget: 30 files, 30 images, 10 videos, 10 audio. Plan a lookbook run so it stays under invalid_attachment.
Format run `model` picks the orchestrator, not the video model
A new image or video model launches and you set model on a Sume Format run. That field picks the orchestrating LLM only; media models come from Format tools.
Rebuild your best product ad with a new product: sume-recreate Format
Use the sume-recreate Format to keep a winning ad's scene order and timing, cast a new presenter and generate everything fresh with your own packshot.
Failed Format run codes: retry, continue, fix input or wait
Eleven error.code values a failed Sume Format run can carry, grouped by response: continue with previous_run_id, retry with a new key, fix input, or wait.
sume-virtual-try-on Format: first frame, then Seedance 2.5
The sume-virtual-try-on Format builds a first frame with ChatGPT Image 2, then animates it with Seedance 2.5. What goes in, what comes back.
Wallet runs dry mid-bulk: items fail with a null run_id, rest go on
A Sume bulk queue does not pause when credits run out: children that cannot start become failed items with run_id null. Sort them and resubmit after a top-up.
Beauty-studio Format for a holiday makeup launch, plus a still
Pair Sume's beauty-studio video Format with the model-and-product portrait still Format for a holiday makeup launch from the same product image.
Bulk run items ignore on_active_run skip and reject
A Format bulk queue runs every item with on_active_run allow, so skip or reject on an item will not serialize it. Set concurrency to control parallel runs.
Cinematic studio commercial Format for a holiday tech gift teaser
Use Sume's cinematic-studio-commercial Format for a macro, high-end camera-move teaser of a flagship gadget or luxury object aimed at gift season.
Close-camera UGC for Black Friday: six hook variants in one queue
Run Sume's close-camera UGC Format as one bulk queue to test six Black Friday testimonial hooks, with the TikTok in-feed file limits to check afterward.
Fashion-editorial Format for a holiday-party lookbook clip
Call Sume's fashion-editorial Format for a magazine-grade holiday-party lookbook clip with a strong pose and restrained motion, from one garment image.
Four places a Format run fails, and a message for each
Format runs fail at submit, during the run, as a non-failure terminal state, or at webhook delivery. Each needs its own retry rule and its own UI message.
Watch a Format run's spend against its cap while it runs
A Format run's receipt reports usage.cap with limit, counted and remaining while it is in flight. Read it to see how close a video run is to failing on its cap.
Fruits Drama Format: talking produce for a Thanksgiving push
Call Sume's fruits-drama Format for about 5 second vertical clips where a fruit character speaks your line, queued as five runs for the produce aisle.
Green-screen Format reaction clip, revised with previous_run_id
Call Sume's green-screen Format for a talking-head overlay ad, then fix one thing with previous_run_id instead of paying for a full re-run.
Mobile-app UGC Format: holiday app ads vs App Store previews
Use Sume's mobile-app UGC Format for creator-style app ads this holiday season, and check Apple's 15 to 30 second App Preview limits before reusing a clip.
Product-commercial Format: one gift-set hero clip for a store page
Make a premium hero clip of one gift set with Sume's product-commercial Format: controlled composition, tactile detail, one camera move, then reuse it.
Product-usage-demo Format: a kitchen gift shown in one real action
Use Sume's product-usage-demo Format to show one real action with a kitchen or household gift in a casual social setting, so buyers see it working.
Recreate Format for Singles' Day: remake a structure, not the footage
Use Sume's recreate Format to remake a reference clip's beats and caption rhythm for your 11.11 offer, and preflight it with reference ingest.
Slideshow Format: a holiday gift guide from up to 30 product images
Send up to 30 product images to Sume's slideshow Format for a gift-guide clip, then check Pinterest's video ad specs before you promote it.
Video-hook Format for Cyber Week: cold opens, no overlapping runs
Call Sume's video-hook Format for cold-open variants of a Cyber Week ad, and use on_active_run to stop overlapping runs of the same Format.
Virtual try-on Format for holiday party outfits in social commerce
Call Sume's virtual-try-on Format to show a person switching into a supplied party outfit, as a short vertical clip for a shop's feed.
Wall-of-text Format for a sale announcement, typed output
Call Sume's wall-of-text Format for a kinetic-type sale clip and bind an output_schema so the video URL lands in your own JSON shape.
Water-splash hero Format: a winter-hydration skincare still
Make a dramatic water-splash hero image of a hydrating skincare product with Sume's water-splash-hero image Format, for a winter-dry-skin push.
Season output schema: episode videos and final cut as SumeMediaFile
Bind an output_schema with SumeMediaFile fields so a Sume run returns typed episode videos. The URL gate, 10% duration check and parts-versus-cut rule.
Series bible for a Format: SKILL.md index, references and run input
Where to keep a series bible in a Sume Format: a short SKILL.md index, detail in references/*, and only the per-episode beat in the run input.
TikTok's Next Episode: a brand series as one Format and one queue
TikTok's The Next Episode funds creator-led series. Here is how to produce a season with Sume: one Format recipe, one bulk queue of up to 100 runs.
What the agent receives for an episode run, in order
A Sume Format run composes the Format, your instruction, an unattended block and a pointer to input, in that order. Your instruction wins a conflict.
Can I continue this Format run? A previous_run_id check in Python
A run can be continued with previous_run_id only if it has a thread_id and is completed or has artifacts. Check first, or handle four named errors.
Format run 400 on an empty body: what a create request must include
A Format run create must name instruction, input, previous_run_id or attachments. An empty object or an empty input object is a 400 invalid_request.
Format run Idempotency-Key: header or body, and four replay outcomes
Send Idempotency-Key as a header or idempotency_key in the body; the header wins. Same key and body gives 200 idempotency_hit true; a new body is a 409.
Format run structured output: output_schema or response_format
Pass one JSON Schema as output_schema or response_format on a Format run. Sending both is a 400, and a schema-valid run can still fail with output_error.
Format run webhook plus polling: one idempotent finalize in SQLite
A webhook and a poll can both see the same terminal run. Insert the run id with insert or ignore, and do the work only when a row was added.
List every run of a Sume Format in Python: the keyset cursor pager
GET /v1/formats/{handle}/{slug}/runs returns data, has_more and next_cursor. Pass next_cursor back until has_more is false; limit is 1 to 100.
Sume Format run routes that do not exist, and the call to use instead
There is no GET /v1/format-runs, no per-Format GET for one run, and no /messages route. Use the per-Format runs list and GET /v1/format-runs/{run_id}.
Sume Format run usage is null: not zero cost, and a safe cost helper
usage is null when spend could not be read, which is not 0. Read usage.debited_usd_micros as an integer, and keep unknown runs separate from free ones.
Which Sume Format run receipt fields to store in your database
Store id, format, status, created_at, finished_at, model, usage.debited_usd_micros, output and artifacts. Fetch the rest, because URLs and expires_at change.
Format batch of 100 runs: writes bind first, reads do not (by plan)
Format runs poll cheaply: about one read a minute per run in flight. Creates are the scarce budget, 120 a minute on Free. Poll math for a 100-run batch by plan.
SaaS AI video feature: spend cap per plan and per-customer keys
To embed Format runs in a SaaS plan, set generation_spend_cap_usd from the customer's tier and derive Idempotency-Key from customer, order and version.
Real estate listing video: a typed output schema with SumeMediaFile
Bind an output_schema to a Format run so a listing video returns as your JSON: address, headline, caption and a SumeMediaFile to store beside the MLS ID.
Bulk Format run 403 workspace_key_required: an agency's fix
A personal key on a team workspace Format returns 403 workspace_key_required, and a service-account key fails too. Which key to mint for Sume bulk runs.
Retrying a bulk Format queue: same Idempotency-Key, same queue
Resend a Sume bulk queue with the same Idempotency-Key and payload and you get 202 and the original queue. Change one item and you get 409. How to retry safely.
Is there a webhook when a Sume bulk Format queue finishes? No
No queue-level webhook on Sume bulk queues. Only per-item webhook_url, so poll the queue with backoff and read counts. A Python loop that handles 429 and 503.
Run 100 Formats overnight for an agency: Sume bulk queue explained
One POST queues up to 100 Format runs with a concurrency window of 1 to 16. Why a completed queue is not all succeeded, and the poll loop to run overnight.
Q4 creative test matrix: 3 hooks by 3 Formats in one 9-item bulk run
Test creative style and hook together: nine Format runs for one SKU in a single Sume bulk queue, with a worst-case spend you can read before you submit.