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.
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
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.
Format reads inactive but still runs: the 409 codes
A never-run Format may read inactive until its first API run. The real refusal is a 409 format_inactive or format_api_trigger_disabled.
Format run failed with incomplete_assembly: continue it, do not re-run
incomplete_assembly means a Sume Format run hit its time limit mid-generation. Continue with previous_run_id; finished clips are not regenerated.
Format run failed with unattended_blocked: why it never half-finishes
Over the API, a Sume Format run is told approvals are granted. If it still cannot finish it fails with unattended_blocked, never a half-done completed.
Pick a Format from the list: io profile and showcase before you run
GET /v1/formats returns each Format with an io profile (input_kind and output_kind) and a showcase output, so you can choose one without paying for a trial run.
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.
Renamed a Format handle? Old URLs work for 90 days: store invoke_url
A renamed Sume Format handle keeps resolving for 90 days. For stored integrations, persist the opaque skl_ invoke_url, which never changes across renames.
Retry one scene of a Format run without paying for the whole run
Send previous_run_id to continue a Sume Format run as another turn: redo one scene, keep the rest. The refusals, 404, 400 and 409, and what each means.
Send a video to a Format run: URLs in input, not attachments
Format and Agent Completion attachments take images only. For video, put the media.sume.com URL in input; Format runs count it toward 10 videos per run.
Service-account key gets 403 on a Format run: use a user or team key
Sume service-account keys cannot create Format runs and fail with 403 insufficient_scope and a service_account_format_runs_unsupported reason. Here is the fix.