Share a Sume Format with a partner using its docs call sheet URL
Every Format with a handle and slug has a call sheet at docs.sume.com/formats/{handle}/{slug}: curl, scopes and polling, without the Format body.
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
Before/after ad from one packshot: how the Sume Format builds it
sume-before-after builds a matched first frame with ChatGPT Image 2, then animates a reveal with Seedance 2.5. What to brief, what to check, and the limits.
Gift set image for holiday listings: the Editorial Product Set Format
Turn a packshot of a three-item gift set into a clean editorial image for holiday listings and ads. What sume-editorial-product-set returns and its limits.
A brand end card for holiday ads with the Logo Motion Design Format
Make a short animated logo end card for Q4 video ads from one logo image. What sume-logo-motion-design takes and how to attach it to a clip with a timeline.
The product usage demo Format: a person using your product, by API
sume-product-usage-demo makes a 9:16 clip of a person using a product from a packshot. What it takes, how to call it, and where it falls short.
Restyle an existing ad clip for Q4 with the Sume Restyle Format
Reskin last quarter's winning ad for the holiday season while keeping its motion and timing. How the sume-restyle Format works and what it cannot do.
Virtual try-on or virtual fitting: which Sume Format for apparel?
Both Formats start from a garment still and make a 9:16 video. Virtual try-on shows a creator changing into the garment; fitting shows its silhouette and drape.
Serum drip, toner pour or cream squeeze: which Sume image Format?
Eight Sume catalog Formats make a single beauty hero image from a packshot. What each one shows, so you can pick one for holiday skincare ads.
Sume Format API staging: api.dev.sume.com and the 401 on a wrong host
Sume serves the Format API on api.sume.com and api.dev.sume.com with the same routes. A key works only on its own host; the other answers 401 unauthorized.
Format bulk queue: no queue webhook, no cancel-queue endpoint
A Sume bulk queue has no webhook and no cancel call. Poll the queue, put webhooks on items, and cancel the child runs one by one with their run ids.
Format Contents API: read the whole package, commit many files at once
Read a Sume Format package with ?recursive=1 and write several files as one commit and one version bump. A change set, not the package; deletes stay separate.
Optional field in a Sume Format output_schema: use a null union
A Sume output_schema has no optional properties. List every key in required and give optional ones a type of ["string","null"], or the create fails with 400.
output_schema_unsatisfied with rejected_urls: the Sume URL gate
A Format run that returns output_schema_unsatisfied and rejected_urls named a media URL it did not generate. How the URL gate works and how to fix the schema.
Format run failed provider_unavailable or mcp_unavailable: retry rules
provider_unavailable and mcp_unavailable are Sume-side Format run failures: retry with a new Idempotency-Key. provider_credits_exhausted waits.
Format run instruction: 8000 characters accepted, about 4000 carried
A Sume Format run instruction accepts 8,000 characters, but only the first ~4,000 reach the agent as prompt text. Put long data in input, carried whole.
Format run status_url or result_url: which one do I poll?
Poll status_url for a small payload, then read result_url once the run is terminal. result_url answers 409 run_not_completed while the run is in flight.
Format run stuck in queued: read queue.state and retry_after_seconds
A Sume Format run that stays queued carries a queue block. waiting is normal; runtime_unavailable means nothing claimed it. What to read, and when to ticket.
OpenAI response_format json_schema to a Sume output_schema
Moving a json_schema from OpenAI structured outputs to a Sume Format run: the field name, what transfers, no JSON mode, and why output comes once, post-run.
Why your order_id comes back null in a Sume structured output
If a Sume run's filled_by is projection, the fallback never sees your input or instruction, so an order_id you sent comes back null. Keep ids on your side.
Sume agent_reported_failure: the three reasons and what to do
agent_reported_failure on a Sume run means the run's own receipt said it did not deliver. Its details.reason tells you which of three cases it was.
Sume primary_output_missing: schema satisfied, run still failed
A Sume run can match your output_schema and still end failed with primary_output_missing. It means the key named in primary_output_key had no value.
Sume output_extraction_failed: the run stays completed, reread it
output_extraction_failed with reason harvest_unavailable is transient. The Sume run stays completed and fills in on your next read; retry only if it persists.
Claude 'Schema is too complex' 400: strict tool limits vs Sume
Claude caps strict tools at 20, optional parameters at 24 and union parameters at 16 per request. Sume checks 10 levels and 5000 properties at submit.
Claude structured output refusal or max_tokens: what Sume does
Claude can return a 200 that does not match your schema on refusal or max_tokens. Sume reports a failed projection as output_error on the receipt instead.
Format run agent_reported_failure vs deliverable_missing: retry or not
agent_reported_failure means the run said it did not deliver; deliverable_missing means it made no media at all. Both leave a failed run, but the retry differs.
Format run provider_credits_exhausted: not your balance, wait
provider_credits_exhausted means Sume's model provider account ran out of credit, not your balance. Do not retry right away; wait, then use a new key.
Gemini batch structured output per request vs Sume per-item schema
Gemini batch requests can each carry a JSON schema. A Sume bulk item is a full run body, so each item can bind its own output_schema; read output on each child.
gpt-5.6-sol retired: it now runs on gpt-6-sol in Formats
A Format run that still sends model gpt-5.6-sol is not rejected: Sume runs it on gpt-6-sol. The receipt proof, the default, and how to update payloads.
List all Sume Format runs: no cross-Format endpoint, page per Format
GET /v1/format-runs does not exist. List runs per Format with limit and next_cursor, or keep your own index of the run ids you stored at create.
Sume bulk item format_run_failed_to_start: run_id null, queue goes on
One Sume bulk item can fail before it starts: format_run_failed_to_start, run_id null, and the rest of the queue continues. How to read and retry it.
SumeMediaFile in a Format output_schema: fields and URL rules
Put a run's image or video in typed JSON with $ref SumeMediaFile#: the nine fields, which are nullable, and why url must be media the run generated.
POST /v1/formats: skill_slug_taken, skill_slug_reserved, 503
Creating a Format over the API can return 409 for a taken or reserved slug and 503 format_git_unavailable. What each means, and what to keep from the reply.
Format output rejects a scene clip in the final video field
A Format schema with scenes and a full_video field fails when full_video reuses a scene file. The exact two-part rule, and how to report an unassembled show.
Format package rules: skill_path_invalid, file names, and limits
What a Format package may contain over the Contents API: SKILL.md name equals slug, two directories, a file-name pattern, five extensions, and 1000 paths.
The built-in Format output schema: sume/action-run-output/v1
No output_schema on a Format run returns sume/action-run-output/v1: text plus four media arrays, filled without a model, so it cannot fail like a custom schema.
Media URLs in a Format run input count: 30 files, 10 videos, 10 audio
Media links inside a Format run's input share one budget with attachments: 30 files, at most 10 videos and 10 audio, counted by file extension, else 400.
What a Format run receives: instruction order and the input file
A Format run composes the Format pointer, the package, your instruction, an unattended block and an input file at /workspace/inputs. Order and what wins.
OpenAI text.format json_schema to a Sume Format response_format
Move an OpenAI Responses API text.format schema onto a Sume Format run: nest it under response_format.json_schema, or lift it into output_schema.
previous_run_not_resumable: a Format run with nothing to continue
Continuing a Format run with previous_run_id returns 400 previous_run_not_resumable when the run left no thread or artifacts. The four refusals and what to do.
primary_output_key: how a Format run picks primary_output_url
A Format run resolves primary_output_url from three places in order. Why a text key gives a null URL, and when a failed run still returns no pointer.
Cancel a Format run: cancel_effect canceled vs no_op
POST /v1/format-runs/{run_id}/cancel is idempotent and returns the current receipt. Read cancel_effect to know if you stopped it, and what still bills.
Sume output_schema anyOf: two result shapes without oneOf
Model a Format result that is either a video or an image set with anyOf in a Sume output_schema. Wrap it below the root and put constraints in each branch.
Format run 401 with a valid key: Bearer and x-api-key both sent
A Sume Format run returns 401 unauthorized when a request carries two credentials at once. Send Authorization Bearer or x-api-key, never both.
Format run stalled or just slow? Read the events phase timeline
GET /v1/format-runs/{run_id}/events shows preparing, running and finalizing phases. If the last at stops moving for minutes, the run is stalled, not slow.
Format run input 400: 64 top-level keys, 2 MiB, objects only
A Sume Format run rejects input that is not an object, has over 64 top-level keys, or exceeds 2 MiB. Group nested keys and check size before you send.
Which schema shaped my Format run? output_schema.source explained
Every Sume Format receipt names the schema that shaped output. source is default, action_default or request_override. Here is how each is chosen and checked.
previous_run_id errors on a Format run: 404, 400 and 409 decoded
Continuing a Sume Format run can fail with previous_run_not_found, format_mismatch, not_terminal or not_resumable. Which are retryable and how to fix each.
Format run webhook payload is null: receipt over 1 MiB
A Sume format.run.terminal webhook carries payload null when the receipt is over 1 MiB. Read error.result_url, fetch the receipt, and guard your handler.