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
A 340-product catalog: four Sume bulk queues of 100, 100, 100 and 40
A bulk queue holds 1 to 100 items, so 340 product videos need four queues. Split the list, key each queue, and remember workspace concurrency still applies.
Python: poll a Sume bulk queue, then list the item indexes to redo
A short Python loop that polls GET /v1/format-run-queues/{id} with backoff, waits for completed, and lists failed or canceled item indexes for a second queue.
Sume webhook signature fails: check the secret fingerprint first
When a Sume webhook signature will not verify, compare the 12-character secret fingerprint header before you debug the HMAC. Includes a Python verifier.
Re-queue only failed items of a Sume Format bulk queue
A completed bulk queue is not all succeeded. Read counts.failed, pick the failed indexes, and resend them under a new Idempotency-Key. Python, offline.
Format run incomplete_assembly: continue it, do not pay twice
incomplete_assembly means the run hit its time limit with generation jobs unfinished. Read pending_job_count, then continue with previous_run_id.
primary_output_missing: your schema passed but the key is empty
A Format run can satisfy your output_schema and still fail because primary_output_key is empty. Here is how to read it and fill the gap.
Is a 4:5 video a YouTube Short? 1080x1350 on Sume Timeline
YouTube's Shorts page names square or vertical videos up to 3 minutes. 4:5 is taller than wide. Sume Timeline renders 1080x1350, so verify it after upload.
Sume has no JSON mode: strict false changes nothing, bind a schema
Coming from OpenAI json_object? Sume Format runs have no equivalent. strict false relaxes nothing. Bind a schema or take the built-in output shape.
Bulk queue, empty wallet: failed items, fresh key, check balance
If the wallet runs out during a bulk run, later child runs fail admission and become failed items. Check the balance, then resubmit with a fresh key.
Format run mcp_unavailable: failed before the model, charged false
mcp_unavailable means the per-turn tools never attached, so the run stopped before any turn. details.charged is false. Retry with a new Idempotency-Key.
output_extraction_failed: harvest_unavailable or harvest_threw?
output_extraction_failed has two reasons with opposite handling: reread a completed run, or report a host defect. Here is how to tell them apart.
provider_credits_exhausted: why a Format run says retryable false
This Format run error is on Sume's side, not your balance or input. details.retryable is false, so do not re-fire in a loop. Here is the handling.
Same ad Format, new model: log three receipt fields on every run
To keep an ad format steady when the model changes, pin the Format, treat model as the orchestrator only, and log version, model and schema.
Sume's 27 catalog Formats: slugs, 404 rule and the io profile
Sume lists 27 catalog Formats at the sume handle. An unlisted slug gives 404. Read description and io before you run one, then fork it to change it.
Sume Format list empty or 404? Check which key you are using first
A missing Format is usually the wrong key: a personal key cannot see team Formats, and 403 workspace_key_required means the right team with the wrong key.
Edited one ad hook and resent the bulk run? Same key gives 409
Reusing an Idempotency-Key with a changed Sume bulk-run payload returns 409 idempotency_conflict. Send only the edited hook under a new key.
Bulk queue key from a payload hash: same body 202, new body 409
Derive a Format bulk queue Idempotency-Key from a sha256 of its body. The same body replays 202 with the old queue; a changed body gives 409.
Which Sume Format for a UGC ad? Read io, then call by name
Sume's catalog lists UGC-style Formats such as sume-close-camera-ugc and sume-mobile-app-ugc. Read each Format's io profile, then run it with a spend cap.
LinkedIn GIF ads cap at 250 frames: 10 seconds at 25 fps
LinkedIn's image ad page allows GIFs of up to 250 frames. At 25 fps that is 10 seconds. For anything longer, send a video made with Sume trim or Timeline.
LinkedIn video ad sizes for four ratios and the Timeline output to use
LinkedIn lists min and max sizes for 16:9, 1:1, 4:5 and 9:16 video ads. Set Timeline output width and height to a size inside each range: $0.10 per render.
Cancel a Sume bulk queue: there is no queue cancel, so cancel children
Sume's API has no cancel-queue endpoint. Cancel each child with POST /v1/format-runs/{run_id}/cancel; the item frees its slot, and you pay for what already ran.
Remix a reference ad in two calls: ingest, then a sume-recreate run
Read a reference clip with Sume reference ingest (300 s max, shots, OCR, audio), then start a sume-recreate Format run with your product and a spend cap.
Which Sume Formats return images, not video? 9 of the 27 slugs
Of the 27 Formats by Sume, 18 declare video output and 9 declare image output. The slug lists, how to read the io profile, and why to check before you call.
Bulk queue concurrency 16 on Sume is a window, not a speed promise
Sume bulk Format runs accept concurrency 1 to 16. It limits how many children start at once and does not promise throughput. What 100 ad items really do.
Which Sume catalog Formats make ad creative: the slugs by ad type
Sume ships 27 ready-made Formats at the sume handle. Which slugs fit which ad type, and how to read one with GET /v1/formats/sume/{slug} before paying.
Can a 4:5 or 2:3 video run in Google Ads? What the specs allow
Google Ads lists 16:9, 9:16 and 1:1 as primary and says ratios in between are allowed; a spec page also names 4:3, 2:3 and 4:5. Exact sizes for Sume Timeline.
Hook line in instruction or input? Sume Format run for ad variants
Put the hook text in the instruction field, and put product data in input. Rules, limits and errors for varying an ad hook across Sume Format runs.
Instagram says upload the highest resolution possible: what's the max?
Instagram's creator page says upload the highest resolution possible but gives no pixel number. Sume Timeline's ceiling is 2160 per edge, so 1214x2160 vertical.
Smallest vertical video size that passes Google Ads and TikTok
Google lists 720x1280 as the vertical minimum, TikTok in-feed 540x960 and its app bundle 720x1280. One Timeline output size clears them all, with the table.
Put your 16 strongest hooks first: Sume bulk queues start in order
A bulk queue returns 202 with the first `concurrency` items already running, up to 16. Order your 100 weekly ads so the best hooks are the first ones you see.
Bulk queue item error: format_run_canceled vs format_run_failed
In a Sume bulk queue, a failed child reads format_run_failed and a canceled child reads format_run_canceled. The real reason is in the child run receipt.
After Sora: keep the recipe, not the prompt, as your stable layer
OpenAI named no replacement for the Sora Videos API. Put house style and output rules in a Sume Format so the next model change does not rewrite your code.
Format showcase field: judge a Format by a real output first
GET /v1/formats returns showcase, a verified sample output. Use it with description and io to pick a Sume Format before you spend credits on a run.
List the Formats by Sume that return video, in Python
Call GET /v1/formats, page with next_cursor, and filter on the sume handle and io.output_kind to find ready-made video Formats. Standard library only.
TikTok 60-minute uploads vs Sume's 30-minute source limit
Sociality.io reports TikTok uploads up to 60 minutes. Sume trims and Timelines stop at 1800 seconds (30 minutes). What fits, and the cut points for the rest.
Recreate a winning ad's structure for your product with Sume
sume-recreate keeps a reference video's scene order, beat timing and caption rhythm, casts a new presenter and generates every shot fresh. How to call it.
Sume Formats that return a product still instead of a video
Nine Sume catalog Formats are declared with text input and image output, from water-splash-hero to magazine-cover-campaign. Use them for 9:16 hero stills.
A Sume bulk queue item failed: read the child receipt first
A Sume queue item only says format_run_failed. Open the child run by run_id, compare spend to the cap, read output_error, then retry with previous_run_id.
Run 300 ad variants as three bulk queues on Sume
One Sume bulk queue holds 1 to 100 Format runs, so 300 variants means three queues with their own idempotency keys, caps and failure checks. The limits to plan.
Sume product commercial vs cinematic studio vs beauty studio
Three Sume catalog Formats make premium 9:16 product films: product-commercial, cinematic-studio-commercial and beauty-studio. How to call each.
Python: find the Sume Format that takes your input and returns video
Page through GET /v1/formats and filter on the io profile (input_kind, output_kind) to pick a Sume Format by shape. Includes the null-io case.
Python: turn a product CSV into Sume bulk Format queues
A short Python script splits a product manifest into batches of 100, builds one bulk body per batch with per-item spend caps, and keeps idempotency keys stable.
Restyle your own footage with the Sume restyle Format
sume-restyle keeps the motion, timing and cuts of a clip you attach, rewrites its look chunk by chunk, and reassembles it with your original audio.
Virtual try-on or virtual fitting: which Sume Format for clothing?
Both are Sume catalog Formats that take a garment still and return 9:16 video. Try-on is an outfit-change reveal; fitting is a fit preview with a small turn.
Cast pack for a series Format run: the 30-file attachment budget
One Format run carries 30 media files in total, at most 30 images, 10 videos and 10 audio, counting URLs in input. How to fit a cast and two locations in.
Weekly series drop: on_active_run reject stops a second render
Set on_active_run to reject and a second episode run on the same Format answers 409 format_run_in_progress instead of starting. skip records a skipped run.
Season outline as nested input: one key, 64-key limit, 2 MiB
Put a whole season outline under one key of a Format run's input. Only top-level keys count toward 64, and the body can be up to 2 MiB, so 40 episodes fit.
Bulk queue says completed: it does not mean every episode rendered
A Sume Format queue is completed when every item is terminal, failed and canceled included. Check counts.failed and counts.canceled before publishing a season.