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
Same Idempotency-Key replay: bulk run answers 202, single run 200
Replaying a Format bulk-run create returns 202 and the original queue with no idempotency_hit flag. A single run returns 200 with idempotency_hit true.
Lost the bulk-run queue id? There is no list endpoint; replay the key
Sume has no list-queues or cancel-queue endpoint. If you lost the frq_ id, replay the create with the same key and body to get the queue back.
Route tickets with Clef, then pick a Sume Format by its io profile
Clef routes a ticket by team and urgency. Then read GET /v1/formats/{handle}/{slug} for io.input_kind before you call POST .../runs. A short Python router.
Continue a Sume Format run with previous_run_id after a review gate
Send previous_run_id on a new POST .../runs so the agent redoes one part. A yes/no review model decides whether to continue; each new run gets its own webhook.
Sume bulk Format runs: 100 items, one concurrency window, cost control
POST /v1/formats/{handle}/{slug}/bulk-runs queues up to 100 ordinary Format runs. Set concurrency and a per-run cap, and poll the queue with format-run-queues.
LinkedIn Lead Gen Form headline 60 characters: variants in bulk
A LinkedIn Lead Gen Form headline holds 60 characters and the details line 160. Queue copy variants as Sume bulk items and check lengths before you paste.
Bulk run for an ad matrix: 3 hooks by 4 ratios in 12 queue items
Build a 3 by 4 creative matrix as one Sume bulk run: 12 items, concurrency 4, and an index-to-name map so every finished file has a clear label.
Image API n or a bulk Format run: which to use for ad variants
Use Image API n for same-prompt variants at one ratio, and a bulk Format run when each variant needs its own instruction, input, spend cap or webhook.
Which Sume catalog Format for which holiday ad: 27 slugs by job
Sume's first-party Format catalog has 27 slugs at the sume handle. Match product commercials, UGC, try-on and text-led ads to the right one, and read io first.
Format run, schedule or Agent Completion for repeatable holiday ads
Use a Format when only inputs change, Scheduled when the clock starts the work, Agent Completions when the task changes. Set a spend cap on each.
Accept a Format grant: personal key 403, wrong workspace 404
POST /v1/format-grants/{id}/accept needs formats:write and a team-workspace key. A personal key gets 403, and a grant meant for another workspace reads as 404.
Audit who can run your Format: list grants, pending versus accepted
GET .../grants lists pending and accepted workspace grants on a Format, newest first, without revoked ones. Script a weekly audit and revoke what is stale.
Change a Format grant role: PATCH run to write and back
PATCH .../grants/{workspace} with {role} changes a pending or accepted grant. Raising to write applies on the next authoring call; lowering to run closes it now
Format grant 404 workspace_not_found: only team handles resolve
workspace_not_found on POST .../grants means the handle matches no team workspace. User handles are not grantable, so pass a team handle or an org_ id.
Format grant 409: exists, self, or workspace_required
A 409 on POST .../grants is format_grant_exists, format_grant_self or format_workspace_required. Each has its own fix, and none is a retry.
Invite a workspace to run your Format: POST grants stays pending
POST /v1/formats/{handle}/{slug}/grants invites a team workspace with role run or write. The grant is pending and confers nothing until their admin accepts.
Can a partner bulk-run your shared Format? Queue and spend are theirs
A grantee can POST .../bulk-runs at your handle and slug with its own team key. The queue, child runs and spend are theirs, and you cannot poll their queue.
Retry two scenes in one Format run: scene_ids with previous_run_id
Continue the thread with previous_run_id and put scene_ids in input to redo two clips in one run. Voice and other clips stay; send a cap.
Revoke a Format grant: in-flight runs finish, new calls fail closed
DELETE .../grants/{workspace} revokes a pending or accepted grant. The grantee's running runs finish, and every new list, read or invoke fails closed at once.
Client needs your Format: a grant, or a key from your workspace?
A grant bills the client and keeps the roster on your side; a team key you mint bills you. Pick the grant unless you intend to resell the output.
Shared Format 409 format_inactive: the owner's switch hits partners
format_inactive and format_api_trigger_disabled are set on the owner's API tab and apply to every caller, including workspaces the Format was shared with.
Shared Format run stuck queued: whose concurrency limit applies?
A partner's run on your shared Format uses the partner's concurrency slot, so the partner's plan limit and queue decide when it starts, not yours.
Format run input extra keys: context only, not echoed in output
Keys your Format does not read, like a sheet row number, reach the run as context and do not return in output. Store them beside the 202's id and thread id.
Formats shared with my workspace: GET /v1/format-grants inbox
GET /v1/format-grants lists grants shared with your team workspace, pending and accepted, newest first. A personal key sees an empty list, not an error.
Who pays when a partner runs your shared Format? The grantee does
A grantee runs your Format at your address with its own team key. The run, spend, concurrency slot and media belong to the grantee, and runs list per workspace.
App ad from a store link: sume-mobile-app-ugc and the 30-file budget
Calling the sume-mobile-app-ugc Format with an app page URL and screenshots: what counts toward the 30-file budget, what does not, and the idempotency key.
Logo animation with sume-logo-motion-design: one call, a cap, a retry
Animate a logo with the sume-logo-motion-design Format: attach the PNG, set a spend cap, keep a stable idempotency key, and continue a run to fix one detail.
Change only the CTA of a finished ad: previous_run_id on a Format
Re-do one line of a finished Sume Format ad without paying for the whole ad again: previous_run_id, a new key and cap, and the four refusals to expect.
sume-virtual-try-on or sume-virtual-fitting: read the io profile first
Two catalog Formats sound alike. Before you send a model photo and a garment to either, read GET /v1/formats/sume/{slug} for its io profile and spend cap.
Sume catalog Formats for ads: which of 27 slugs to read first
The Sume Format catalog lists 27 slugs. Group them by the ad job their names suggest, then confirm each with GET /v1/formats/sume/{slug} before you call it.
Live-commerce clip retry: looks yes, words no
A scene retry re-renders named scene ids on the same thread. New words, host or product need a new production, because the voice track sets the limit.
Live-commerce Format: instruction past 4,000 characters is cut
A Format run rejects input above 2 MiB with a 400, but silently keeps only the first 4,000 characters of instruction. Put the broadcast script in input.
YouTube template videos need distinct storylines: vary each brief
YouTube monetization policy flags mass-produced, repetitive template content. Vary the brief for every item in a Sume Format bulk run and test similarity.
Three Demand Gen video hooks in one Sume bulk run
Queue three hook variants of one video in a single Sume Format bulk run (up to 100 items per request) so you can test which opening works.
Retry one scene and keep the voice track: Format previous_run_id
A new voice is not a reason to redo a whole video. Continue a finished Format run with previous_run_id and an instruction that touches one scene only.
Stocking stuffer ads for 100 products: one bulk run, 16 at a time
One Sume bulk run takes 1-100 items and 1-16 parallel workers. Here is how to set it up for a stocking stuffer catalog and check the failed count at the end.
Cyber Monday email header: a magazine cover Format with room for type
sume-magazine-cover-campaign returns a cover-style still with space for headline text. Add the sale line in your email builder so it stays editable.
A gift portrait for your store homepage: model product portrait Format
The sume-model-product-portrait Format returns one finished still of a person with your product. Use it for a homepage hero, not for a motion ad.
Wall of text or Video Hook: which Fastlane Format for a doorbuster?
Use sume-wall-of-text when the offer itself is the ad and sume-video-hook when the first seconds must stop the scroll. Both deliver a Blitz, not Seedance.
Selling on many channels: queue 100 product videos overnight
Amazon says over 95% of independent sellers sell on several channels. Queue up to 100 Sume Format runs with a concurrency window and wake up to a media set.
GPT-6.1 Sol errs less, but still pass prices as Format input
OpenAI says GPT-6.1 Sol cut factual errors from 11.4% to 7.7%. For ad video, give the run your prices and claims as input data instead of trusting recall.
Format run queue.position is always null: no queue depth published
The status response has a queue object, but position is null on purpose. Use queue.state and expires_at for waiting UX instead of a fake countdown.
Argon targets long-horizon work; a Sume Format run ends at 90 minutes
Google positions Gemini 4 Argon for long tasks. A Sume Format run is force-finalized as failed 90 minutes after creation, so split long jobs into runs.
Argon 1M output tokens vs Sume Format 120,000-character schema cap
A 1M-token output limit does not lift Sume's output_schema limits. The 120,000 characters bound the schema, and the fallback projection reads 8,000 characters.
Image types a Sume Format run accepts: JPEG, PNG, WebP, GIF, AVIF
A Format run accepts five image types, 30 files and 500 MB in total. Convert HEIC and TIFF first, and prefer public HTTPS URLs over asset ids.
Compare orchestrator models in one Sume bulk queue with per-item model
A bulk item can carry its own model. Send the same input under several orchestrators, then compare debited spend and output across the receipts.
Flat Sume output schema for a spreadsheet row: null is an empty cell
Design a Sume output_schema that maps to one spreadsheet row. Optional fields become nullable strings, and a null becomes an empty cell when you write the CSV.
Hashtag and caption limits in a Sume output schema, checked post-run
Use pattern, maxItems and maxLength in a Sume output_schema so captions and hashtags are checked after the run. A violation returns null output, not bad data.