Developers
Building on the Sume API: keys and hosts, jobs and runs, polling, webhooks, idempotency, errors and rate limits, the SDK, the CLI, and MCP auth.
Start with Sume API quickstart: your first video generation call in five steps
Bulk run item completed is not success: check before you publish
A Sume Format bulk child can be completed without being a success. Read each result and use per-child webhooks; no queue webhook exists.
Cancel queued video jobs when the offer changes: Pro plan example
On Pro, 4 jobs process and 20 wait in the queue (24 accepted). Only queued jobs can be canceled; a started job returns 409 job_generation_already_started.
Check a new Sume video model against your clip spec before you pay
Four catalog fields decide if a new video model fits your pipeline: durations, resolutions, ratios, and references. A Python check that submits no job.
gemini-nano-banana-2.1 or google/nano-banana-2.1: which id Sume takes
Google's pricing page names the model gemini-nano-banana-2.1. Sume's image API takes google/nano-banana-2.1 and runs the old nano-banana-2 as 2.1.
Go httptest for a Sume poll loop: assert next_poll_after_seconds
A 29-line Go test: httptest answers in_progress with next_poll_after_seconds 30 twice, then completed, and asserts the loop slept 30 seconds twice.
Go net/http: a Sume video submit retry loop with one Idempotency-Key
A 30-line Go function using net/http that retries a Sume video submit on 429 and 503, reads Retry-After, and reuses one Idempotency-Key. Run on a stub.
Google made Omni Flash its default video model: pin it or sume/auto?
Google's docs now say to use Gemini Omni Flash as the default video model. On Sume you can pin gemini-omni-flash-1.1 or send sume/auto. What each one fixes.
Google says Imagen is shut down: test your Imagen call on Sume now
Google's Imagen page says Imagen models are shut down. Sume lists Imagen 4 Fast and Ultra separately. One catalog check and one request tell you if yours works.
Hosted video instead of a GPU: a Python submit-poll-download script
Replace a local H3 or Wan pipeline with three HTTP calls. A Python script that submits a minimax-h3 job to Sume, polls it and saves the MP4, with job states.
Nano Banana 2.1 4K batch: handle 200 and 202, reuse the key
A 4K Nano Banana 2.1 call can return 200 with the image or 202 with a job. A short Python handler, the retry rule, and what 4K costs: $0.20 per image on Sume.
One idempotency key per model when a video fallback changes payload
Reusing an Idempotency-Key after switching video models returns 409 idempotency_conflict. Build the key from order, model, and prompt hash so retries stay safe.
Python argparse CLI that checks seconds per Sume model first
A 25-line argparse CLI: choices reject unknown models, a duration check uses the documented limits, and --dry-run prints the body. Runs offline.
Python fallback chain for Sume video models: 404 and 503 only
After the Sora API shutdown, a model chain must not retry everything. This Python function moves on at 404 and 503 and stops on 429, 402, 400, 409.
Parse Retry-After as seconds or HTTP-date before retrying a Sume 429
A 21-line Python helper that reads retry-after as integer seconds or an HTTP-date, caps the wait, and falls back to exponential delay when the header is absent.
Python urllib: retry a Sume video submit on 429 and 503, no requests
A standard-library Python function that retries a Sume video submit on 429 and 503, reusing one Idempotency-Key and reading Retry-After. Tested on a stub.
Test Sume retry code with a unittest fake server: 429 then 202
A stdlib fake server answers 429 with Retry-After, then 202. The test asserts your retry reuses the same Idempotency-Key and waits 7 seconds, with no sleep.
A Veo 3.1 call becomes a Sume Omni job in under 30 lines of Python
Replace a Veo 3.1 request with a Sume gemini-omni-flash-1.1 job: submit, poll every 30 seconds, download the mp4 and read usage.cost. Standard library only.
Which Sume errors mean switch the video model, and which mean wait
Eleven documented Sume error codes and job categories sorted into three actions: fix the request, retry the same model later, or fall back to another model id.
Retry a timed-out Sume Agent Completion without a second run
Send an Idempotency-Key on POST /v1/agent/completions. A retry returns the original receipt with idempotency_hit true; a changed payload returns a 409.
Agent Completions 403 insufficient_scope: old key or service account?
A 403 insufficient_scope on POST /v1/agent/completions has two causes: a key made before the feature, or a service-account key. details.reason tells which.
Does Sume trim output match YouTube's H.264 and AAC recommendations?
YouTube recommends MP4, H.264 High Profile, closed GOP, AAC-LC. Sume trim docs state libx264, yuv420p and AAC. What matches, what is undocumented, how to check.
Free plan accepts 6 paid jobs: submit 7 and read queue_full
Free allows 1 processing job and 5 queued, so 6 are accepted. A Python script submits 7 in parallel and prints which are accepted and which get 429 queue_full.
GLM 5.3 Flash JSON output vs Sume's strict output_schema rules
GLM-5.3-Flash supports JSON output. Sume's run output_schema is stricter: object root, additionalProperties false, all properties required. A schema that works.
Imagen 4 with a reference image: Sume rejects it, use Nano Banana 2.1
Sume lists Imagen 4 Fast and Ultra as text-to-image only: input_references is 0 to 0. To edit a photo, use Nano Banana 2.1 at $0.10 per 1K image.
Can I use my own LoRA on a hosted video API? Sume has no LoRA field
Sume's /v1/videos has no LoRA, seed or provider-option fields. MiniMax's H3 license allows LoRAs on the open weights. What that means for a character or style.
A Python Sume webhook verifier for the two-signature rotation header
In a 24-hour secret rotation Sume sends two sume-v1 signatures. This 25-line Python verifier accepts either, refuses an empty secret, and prints its own test.
Ratio check before a batch: 4:5, 9:16 and 8:1 on three Sume rows
Imagen 4 lists 5 ratios, GPT Image 2.5 lists 9 and Nano Banana 2.1 lists 15. Which of 4:5, 9:16 and 8:1 each Sume row accepts, and the fallback.
Refresh 1,200 SKU video ads before Black Friday: waves by plan
On an empty workspace, 1,200 jobs take 300 submission waves on Free, 67 on Pro and 14 on Scale, using Sume's wave_size_hint of 75% of accepted capacity.
How many images can I attach to a Sume agent run? 30, up to 500 MB
An Agent Completion takes at most 30 images, each up to 30 MB, 500 MB total. So 30 images of 30 MB cannot all fit; 16 can. Error codes inside.
Sume job 404 for an id you created: check which member's key made it
A 404 on GET /v1/jobs/{id} can mean the job belongs to another member or workspace. A Python helper separates unknown from not visible.
Limit an agent's paid MCP calls with script_run max_paid_calls
script_run runs a short program on the Sume side with max_calls, max_paid_calls and a 5-55 second timeout. What it can bound, and what it does not cap.
Sume run webhook retries: ten attempts span about 3 hours
Ten delivery attempts with 30-second doubling backoff capped at one hour add up to 11,010 seconds before jitter. The timeline, and what to do after exhaustion.
Sume run webhook says OK but output is null: handle degraded
A Sume run can complete, bill you, and still have output null. Branch on outcome, not status, and read artifacts and output_error before you retry.
Swap the Sume video model with an env var and a catalog check in Node
Read the model id from VIDEO_MODEL, confirm it appears in GET /v1/videos/models, and fall back to sume/auto when it does not. A Node 20 script of 21 lines.
TikTok 500 MB cap and 10 minutes: the bitrate that fits is 6.67 Mbps
TikTok's non-Spark in-feed ad page allows 10 minutes and 500 MB or less. A full 10 minute ad fits only at 6.67 Mbps or below. The arithmetic and a Sume render.
TikTok 516 kbps minimum bitrate: a 30 second ad is at least 1.94 MB
TikTok's non-Spark spec lists bitrate of 516 kbps or more. The smallest file for 15, 30 and 60 seconds is shown with the math, plus how to check a Sume render.
TikTok ad caption rules: no links, @ or hashtags, and a 4-line limit
TikTok's in-feed ad page says captions can't hold links, @ symbols or hashtags, and Spark captions max out at 4 lines. A Python lint to run before you submit.
TypeScript exhaustive switch on /v1/videos statuses fails the build
A never-typed default case makes a new video job status a compile error, and a runtime parser rejects strings the types do not know. 26 lines of TypeScript.
Verify a Sume agent.run.terminal webhook in Python
Python HMAC-SHA256 check for a Sume run webhook: sume-v1 signature over timestamp.raw_body, a five-minute window, and a verifier that refuses an empty secret.
Which request_id do you dedupe a Sume run webhook on?
Dedupe on the envelope request_id, which equals run_id and is stable across retries. The nested payload.request_id is a different id. A code check.
Build IMAGE_REF tags in Python for up to 10 Omni references
A Python helper turns a list of up to 10 image URLs into an Omni Flash prompt with matching IMAGE_REF tags, 0-based, in list order. Runs as written.
Four music variants in parallel: Python asyncio, one key per take
Submit four Music Router jobs at once from Python with one Idempotency-Key each, poll status concurrently, and pay 4 x $0.125 = $0.50. Code that runs.
GET /v1/jobs returns 404 for a job another key created: Sume's rules
A Sume API key reads only jobs its own member created. A reconciler on a different member's key gets 404 not_found for a real job. How to design for it.
Which Sume hosted MCP tools are read-only? 24 the docs label Read
The tools-and-gates page labels 24 hosted MCP tools as Read across five groups, plus meta and account tools. List and verify with tools_list.
One idempotency key per prompt row: re-run a 1,000-clip library safely
Derive the Idempotency-Key from every field you send, so a crashed batch can restart without paying twice and a changed row never collides. Python, 17 lines.
image_url or reference_image_urls: the Omni field for a photo
On Gemini Omni Flash 1.1, one image in image_url is a start frame; one image in reference_image_urls with no frame is reference-to-video. The price is the same.
Log requested vs stored model ids to find retired ids still in config
Sume runs a retired image id as its successor and stores the successor on the job. Compare the two ids after each submit to find stale config.
Music 1.0 to Music Router: what changes in your integration
Sume is retiring Music 1.0 gradually; every request already resolves through the Music Router. New code should call /v1/music-router/generate. What changes.