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
Cancel 12 queued Sume jobs: 12 writes, and a 409 that is not an error
Cancel is a write, only works before generation starts, and returns 409 job_generation_already_started after. A Python sweep that treats 409 as fine.
Enterprise API key rate limit before a contract: the Scale row
Until Sume provisions a contracted number, an Enterprise key uses the Scale row: 1,200 writes and 48,000 reads per minute. The full plan table and the math.
Five status vocabularies on the Sume and OpenRouter video APIs
Sume job status, the queue-shaped field, /v1/videos status, webhook delivery status and OpenRouter status differ in spelling. One TypeScript map fixes it.
Org workspace concurrency floor of 10: the queue and wave that follow
Sume gives org workspaces a processing floor of 10. With the default queue formula that is 50 queued, 60 accepted, and a wave hint of 45. Read your own fields.
Polling a 5-minute video: 30 s is 10 reads, 2 s is 150 on Sume
How often to poll a Sume video job: read counts for a 300 s job at 30 s and 2 s, and an asyncio loop that obeys next_poll_after_seconds.
Sume SDK errors by status: which class for 401, 402, 403, 404, 409
The @sume-com/sdk error classes by HTTP status, which fields they carry, and how run helpers differ from generated operations that resolve instead of throwing.
A known-answer test for the Sume webhook signature: one body, one hex
A fixed secret, timestamp, and body give a fixed sume-v1 value. Use it to unit-test your verifier: valid, stale, empty secret, and rotation cases in Python.
Text to speech API voice id: list avatars where voice.status is ready
Sume TTS rejects voice names from other services before any credit is held. Use avatar_id or avatar_handle, or a UUID or voi_ id copied verbatim.
Sume TTS pace test: 1,000 characters a minute decides the cap
Sume TTS stops at 20,000 characters or 1,200 seconds. The break-even is 1,000 characters a minute; measure your voice before a long read. Max $0.95 a job.
Fabric request: image_url and avatar_handle together are not allowed
Sume's VEED Fabric 1.0 body needs exactly one visual source: image_url or avatar_id / avatar_handle, never two. Valid bodies and audio rules.
Verify a Sume video callback signature in Python, empty secret refused
A short stdlib Python check for x-sume-webhook-signature on a /v1/videos callback: HMAC SHA-256 over timestamp.raw_body, rotated sume-v1 entries accepted.
Video fields Sume rejects: size, seed, provider.options, audio off
Sume's /v1/videos refuses size, seed and non-empty provider.options on every model, and Omni refuses generate_audio false. What to send in their place.
Claude Dynamic Workflows events vs Sume's single terminal run event
Anthropic's Oct 9 Dynamic Workflows beta streams workflow_run.* events. Sume sends one terminal webhook per run, no stream. How to fan out and track progress.
frame_images or image_url? Image-to-video fields on Sume's two APIs
Sume's /v1/videos uses frame_images and input_references; /v1/video-router/generate uses image_url, end_image_url and reference_*_urls. A field-by-field map.
Gemini 3.7 Flash now routes to 3.8: where a media client pins ids
Google auto-routes gemini-3.7-flash to gemini-3.8-flash since Oct 8. Where Sume lets you pin a model, where it routes for you, and what the job records.
Gemini Omni Flash 1.1 prompt length on Sume: a 20,000-character check
The Sume catalog constraint for Gemini Omni Flash 1.1 is a prompt of at most 20,000 characters, 3 to 10 seconds. A short Python preflight check before you pay.
Sume hosted MCP from a CI runner: API key or OAuth?
A headless runner cannot finish the OAuth consent page. Hosted Sume MCP also takes an API key as Bearer or x-api-key. What that session can call, and the rules.
Status reads for a full Sume queue: 3,600 to 72,000
Poll every accepted job every 2 s for 20 minutes: Free makes 3,600 reads, Scale 72,000. The math, and how one field cuts it.
Python verifier for Sume webhooks: rotation header and empty secrets
A Python function that checks the sume-v1 HMAC over timestamp.raw_body, accepts either signature during rotation, and refuses an empty secret. Under 30 lines.
Make an SRT file from Sume STT word timings in Python (7 words a cue)
Sume STT always returns words[] with word, start and end in seconds. This Python function turns the list into an SRT file, seven words a cue.
VEED Fabric audio must be under 10 MB: stereo wav tops out near 56 s
Sume lists VEED Fabric 1.0 audio as Sume-hosted, under 10 MB, at most 300 seconds. A 44.1 kHz stereo wav hits 10 MB near 56 seconds; a 128 kbps mp3 never does.
Wan 3.0 reference clips: four 4-second videos break the 15 s cap
Wan 3.0 accepts up to 5 reference videos totalling 15 seconds at 16 fps or more. Four 4-second clips total 16 seconds and fail; three 5-second clips pass.
Which Sume wait mode fits which job: image, video, avatar, swap
Sume's async, sync, subscribe and webhook modes differ only in how you learn the outcome. A table by job length, and why 30 seconds is a request budget.
A 1,300-second narration fails tts_duration_exceeded: split the script
Sume TTS fails a request whose audio runs past 1,200 seconds with tts_duration_exceeded and captures no credit. Split the script at sentence ends.
Before a 20-clip MCP burst: dry_run, admission preview, max_spend_usd
A single Sume MCP create needs none of these. A 20-job burst should use dry_run or generation_admission_preview, set max_spend_usd, and wait in one jobs_wait.
Run an Agent Completion nightly from CI with curl and a spend cap
A 25-line bash job that starts a Sume Agent Completion with a cap and an idempotency key, polls the receipt, and fails the build unless the run completed.
Four status vocabularies in the Sume API: job, resource, run, delivery
Jobs say queued and processing, resources say ready, deliveries say exhausted, queue-shaped fields say IN_QUEUE. A table so a client branches on the right one.
gemini-3.1-flash-image deprecated: Nano Banana 2.1 on Sume
Google deprecated gemini-3.1-flash-image on Oct 6 when Nano Banana 2.1 went GA. Which ids Sume accepts, what it bills per image, and what Google lists.
Gemini Omni edit mode on Sume: video_url only, 720p, no aspect_ratio
Omni edit mode takes a prompt and one video_url. Resolution defaults to 720p, aspect_ratio is rejected, and no image or reference field may be added.
Idempotency key from the order id, not a fresh UUID per attempt
A random UUID generated inside the retry loop gives every attempt a new key and a new paid job. Derive the Sume Idempotency-Key from the order instead.
Lint a video against TikTok, Reels, Feed and Shorts limits in Python
A 24-line Python check for duration, file size and average bitrate against the limits TikTok, Meta and YouTube publish, plus where Sume jobs fit before it.
MCP read-only OAuth session: which Sume tools you do and do not see
With OAuth mcp:read, hosted Sume MCP hides write and paid tools and returns insufficient_scope if you call them. What tools_list shows with Write off and on.
OpenAI's three tiers vs Sume plan concurrency of 1, 4, 8 and 20
OpenAI cut API usage tiers from five to three on Oct 6. Sume sets concurrency by plan, not spend. The plan numbers and the queue math, side by side.
Porting chat history to Agent Completions: assistant turns fail
Sume Agent Completions take OpenAI-style messages but return 400 on any assistant turn and start each call in a new thread. What to send instead.
Python asyncio loop for a Sume job: next_poll_after_seconds
A runnable httpx and asyncio loop for GET /v1/jobs/{id}/status that honors next_poll_after_seconds, backs off otherwise, and leaves the job running on timeout.
Sume error retry matrix: retry with the same key, or fix the request
Which Sume API errors to retry with the same Idempotency-Key, which to fix first, and which to leave alone. A table and a small Python function that decides.
Sume TTS default is mp3: sentence slices need wav and emit_audio
Sume TTS defaults to mp3 at 44.1 kHz and 128 kbps. Per-sentence audio slices need wav (pcm_s16le) plus segmentation emit_audio, as in the Python request below.
Which id to send Sume support: req_, job_, arun_ or agrun_
Error bodies carry req_ ids; jobs have job_; Format and Action runs arun_; Agent Completions agrun_. Which to share with support, and what never to paste.
Cheapest Sume image model for a 21:9 banner from a reference photo
Qwen Image at $0.025 is the cheapest row listing 21:9 with reference input. Flux 2 Pro is next at $0.0375. A short script finds it live.
Claude tool search limits: 200-char regex, 500-char BM25, 5 results
Claude's tool search tool has fixed limits on pattern length, results and deferred tools. What they mean for a Sume hosted MCP tool list.
Deploy check: does your video model id and duration exist on Sume?
A Python preflight that reads GET /v1/videos/models and fails the deploy when VIDEO_MODEL is not a catalog id or the duration is outside supported_durations.
Env and secrets diff for removing Sora: SUME_API_KEY, one auth header
Which environment variables to delete, add and rotate when a service leaves the OpenAI Videos API for Sume, plus a startup check that fails on a missing secret.
Failed Sume video job: resubmit or stop? Read retryable, next_action
Sora said failed and little else. A failed Sume job carries an error with category, retryable, retry_after_seconds and next_action. A small decision function.
Sora content rules vs Sume generation_rejected: read the job events
A prompt Sora refused may behave differently on Sume. How a rejection shows up as generation_rejected, which events to read, and why you must not assume parity.
Agent Completions model field is sume-agent only: no Haiku or GLM
You cannot choose Claude Haiku 5.5 or GLM 5.3 in the Agent Completions model field. Sume accepts sume-agent and returns 400 for anything else.
Check ad video length for Pinterest, LinkedIn and Google in Python
A short Python check of a video-inspect probe against Pinterest, LinkedIn and Google Video action length limits read on 2026-10-08, before you upload an ad.
Claude per-message effort: drop to low while a Sume job runs
Claude's per-message effort beta keeps the prompt cache when you change effort mid-conversation. How to use it around Sume jobs, and its Haiku 5.5 limit.
Cloudflare Queue consumer 15 min wall time: poll a Sume job
A Queue consumer on Cloudflare can run 15 minutes of wall time, but a Sume job can wait longer. Re-enqueue with a delay and honor next_poll_after_seconds.