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
Cancel one episode in a running Sume bulk queue: what it frees
There is no cancel-queue endpoint on Sume. Cancel one item run and its slot frees for the next episode. A canceled run delivers no webhook; read cancel_effect.
Render a Short and wait for it in one request? Timeline sync mode
Timeline 1.0 can answer a Short render in one request when mode is sync and the job finishes within 30 seconds. Otherwise it returns 202 and you poll.
Previously on: add a recap to a YouTube Shorts series episode
Open a Shorts episode with a Previously on recap: build it with Timeline 1.0 audio.parts and see what it costs per minute.
Shorts series sequential playback: fade out or hard cut each episode?
YouTube plays Shorts series episodes in order. Pick a hard cut or a short fade at the end of each one, with the Timeline 1.0 fade limits.
Continue a scene in the next Shorts episode: last frame as first frame
Pull the last frame of episode 1 with Sume video frames and use it as the first frame of an Omni clip for episode 2. Sequence, API calls and an 8-second price.
Does each Shorts series episode need to stand alone?
Each Shorts episode may be the first one a viewer sees. Add a recap overlay with Sume trim, compose and Timeline 1.0 for about $0.15.
Animate a photo in a Short: why Timeline stills stay static
A still in a Timeline 1.0 slot is a static hold and its motion field is ignored. To move a photo, generate a 3-second Omni image-to-video clip and cut that in.
How do I cap what one Shorts episode run can spend in Sume?
Set generation_spend_cap_usd on each Format run: up to $500, 0 is rejected, null means the $500 platform maximum, and omitting it inherits the Format's cap.
Queue a 100-episode Shorts season in one Sume call?
Yes: one bulk-runs call queues up to 100 Format runs, 1 to 16 at a time. Here is what it returns, what it skips, and how to poll a season.
Why did my Shorts episode Format run fail after 90 minutes?
A Sume Format run has an expires_at deadline of 90 minutes from creation, after which it is force-finalized as failed. Split an episode into scene runs.
Redo one scene of a Shorts episode without redoing the episode
Continue the same Format thread with previous_run_id and a new instruction to redo a single scene. Sume treats it as one more turn of the same conversation.
Format run webhook receiver in Python: HMAC and a 5-minute window
Verify a Sume format.run.terminal webhook in Python: HMAC-SHA256 over timestamp.raw_body, stale-timestamp rejection, empty-secret refusal, run_id dedupe.
Format run limits: 64 input keys, 2 MiB, 8,000-character instruction
Put episode data in input (64 top-level keys, 2 MiB) and the task in instruction (8,000 characters). The body cap is 4 MiB; unknown top-level fields return 400.
Format vanity URL or skl_ invoke_url: store the opaque path
A Format has a vanity URL (handle/slug) and an opaque skl_ invoke_url. Renamed handles keep resolving for 90 days, but only the skl_ path survives every rename.
Format run create: 202 fresh, 200 replay, 409 conflict in Python
A Format create returns 202 for a fresh run and 200 with idempotency_hit true for a replay. 409 means conflict or in-flight. A Python classifier.
Micro-drama episode manifest as a Format output schema (strict rules)
Bind an output_schema to a Format run and get typed JSON: episode number, title and a SumeMediaFile video. Strict subset: object root, every property required.
One bad item in a 100-item Format bulk request: 400, nothing runs
A Format bulk create validates every item first. One invalid item returns 400 with details.index and queues nothing.
No queue webhook on Sume bulk runs: count item webhooks instead
Sume bulk queues have no queue-level webhook. Put a webhook_url on each item and count terminal events to know a season is finished.
Poll a Sume bulk queue every 10 seconds: read limits by plan
How often can you poll a Sume bulk queue? Reads are 40 times the write limit, so a 10-second poll fits every plan. The math, and when to back off.
Sume webhook payload is null: receipt over 1 MiB, fetch result_url
A Sume format.run.terminal webhook with payload null means the receipt was over 1 MiB. Read error.result_url and fetch the receipt instead of failing the run.
enum and const in a Sume output schema: a status that cannot drift
Use enum and const in a Sume output_schema to pin a status field to values your publisher expects, since oneOf and allOf are rejected. Examples that pass.
Retry only the failed episodes from a Sume bulk queue
A Sume bulk queue shows completed even when items failed. Find the failed children and re-queue only those, with fresh keys and untouched keys for the rest.
Season 2 of a Shorts series: same Sume Format, new input, new keys
Start season 2 without rebuilding anything. Keep the Format, change the input and idempotency keys, and keep season 1 receipts as a style reference.
Shorts series bulk queue finishes out of order: publish by number
Episodes in a Sume bulk queue run in parallel and finish in any order. Sort by an episode number in your output schema, not by completion time.
Shorts series: episode video and thumbnail from one Format run
YouTube Shorts series take a custom thumbnail per episode. Bind one output schema so each Sume Format run returns the video and the thumbnail together.
Sume Format run expires_at: 90 minutes, and how to set your timeout
A non-terminal Sume Format run carries an expires_at, 90 minutes from creation. Use it as your client timeout instead of inventing a number.
Sume output schema limits: depth 10, 5,000 properties, 120,000 chars
How big can a Sume output_schema be? Depth 10, 5,000 properties and 120,000 characters, and a refusal before any spend. What to flatten and where it fails.
Format run output_extraction_failed: it stays completed, read again
output_extraction_failed is a transport failure, not a verdict. The run stays completed and Sume projects the output again on your next read of the receipt.
Format run scene status stand-in vs failed: which scenes to retry
Give each scene a status of succeeded, stand-in or failed, then retry only the bad ones with previous_run_id. The schema, the receipt rule and the call.
Does a Format run webhook fire per clip? No, once per turn
A Format run sends one format.run.terminal webhook per agent turn, however many clips it made. A continued run is new and sends its own.
Output schema 400 missing_items: an array node needs items
A Format output_schema with an array and no items fails with 400 and rule missing_items before anything runs. The bad schema, the fix, the violation.
Output schema max_enum_values: 1,000 values per enum, then what
Sume refuses an enum of more than 1,000 values with rule max_enum_values. Use a string with a pattern or format, or split the list into two enums.
Output schema max_string_length: descriptions use a 120,000 budget
A big Format output_schema can fail with max_string_length although no field is long. The 120,000-character budget covers every key, name and string in it.
Output schema required_completeness: list every property in required
Sume's strict output_schema wants every declared property in required, and no required entry without a property. Make a field optional with a null union.
Why did my Format run do that? Read the first message of its thread
A Format run's first thread message is the text the agent received: Format pointer, your instruction, unattended note and input file path. Read it first.
Format run failed primary_not_deliverable: audio under a video key
A Format that makes video fails with agent_reported_failure and primary_not_deliverable when the primary output is audio or a still. How to read and fix it.
Format run unattended_blocked: assembled_deliverable is false
unattended_blocked means the run stopped instead of claiming a deliverable it did not make. The harvested media are intermediates, not the cut.
Output schema unsupported_ref: $defs must live at the schema root
A $ref to a nested $defs, an external URL or a missing name fails with unsupported_ref in a Sume output_schema. Move $defs to the root and fix the pointer.
Output schema max_depth: 10 levels, and $defs recursion is free
Sume's output_schema allows 10 levels of literal nesting. Past that you get max_depth. A self-referencing $defs entry does not add to the depth count.
Output schema node with only a description: missing_type violation
A property with only a description is legal JSON Schema, but Sume rejects it with missing_type. Give it a type, a $ref or an anyOf, and move constraints.
Output schema type float or date rejected: unsupported_type
Sume's output_schema accepts seven types only. A float, date or any type gets the rule unsupported_type. Map each to number, string with format, or an enum.
AI video generator for advertising: check a Format's sample first
GET /v1/formats returns an io profile and a showcase for each Format. How to read both before you run a paid ad, and what a null means.
Black Friday ads for electronics and furniture: Sume Formats
Adobe forecasts $63.3B in electronics and $33.4B in furniture online this season. Which Sume Formats show a gadget in use or a room before and after.
Black Friday ads for cosmetics and apparel: which Sume Formats
Adobe expects $9.2B in cosmetics and $51.3B in apparel online this season. Which Sume beauty and fashion Formats fit, and which are still, video or try-on.
AI video generator for YouTube: get 16:9 from a Sume Format
Sume's first-party example prompts are vertical. To get a 16:9 YouTube video from a Format, say so in instruction and check the width and height.
Make a music video from your own footage with AI: Sume restyle
sume-restyle redoes a clip you own with the same motion and cuts, in chunks of up to 30 seconds. What to supply, what stays, and the audio rule.
Which video model does a Sume Format use? Not the model field
The model field on a Sume Format run picks the orchestrating LLM, default gpt-6-sol. The Format's tools choose the image, video and audio models.
A/B test two hooks in one bulk queue: instruction beats the recipe
Run two opening hooks on one product by sending two items to the same Sume Format. Your instruction is placed after the recipe, so it wins where they disagree.