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
Arazzo 1.1 workflow for Sume: submit, poll, retry until terminal
Arazzo 1.1.0 can describe Sume's submit then poll sequence over its operationIds, with a 2 s retry action. The YAML, and what I could and could not check.
Failed Format runs: a dead-letter table you can retry from
Keep a dead-letter table for failed Sume Format runs: run id, thread id, failure code, retry flag, and a new idempotency key, so retries stay safe.
AsyncAPI 3.1 for your Sume webhook receiver: a 29-line spec
Describe the receiver Sume calls in AsyncAPI 3.1.0: one receive operation, two signature headers, three job events. Parsed with the AsyncAPI parser.
Veo 3.1 image_url rejected on Sume: text-only error and what to use
Sume's Veo rows refuse image, frame, reference and video inputs as 'text-to-video only here'. The refused fields, other messages, and rows that take an image.
Assert the Sume usage ledger in CI: canceled job debits zero
After canceling a queued Sume job, read GET /v1/usage?job_id= and assert summary.final is true and debited_usd_micros is 0. A short Python CI check.
ElevenLabs dubbing 180-minute app limit vs 3 GB API and Sume detach
ElevenLabs dubs up to 180 minutes in the app or 3 GB via API. Sume detach takes 1,800 s of source and 900 s of output per job, so long videos need ranges.
ky retry on POST for Sume: Idempotency-Key, 40 s timeout, v2 baseUrl
ky does not retry POST by default and times out at 10 s, but Sume sync can hold 30 s. A tested ky v2 config with a stable Idempotency-Key and no 429 retries.
Lyria 3.5 is single-turn: what that means for Sume Music retries
Google says Lyria music is single-turn, with no iterative editing and varying results per call. On Sume that means a new take per prompt: no seed, no duration.
GitHub Actions concurrency for a Sume render job: the cancel trap
cancel-in-progress stops your workflow, not the Sume job it submitted. Group by branch, cancel via POST /v1/jobs/{id}/cancel in a final step, and cap the run.
A video model row missing from Sume's list: why, and how to check
Veo and Genjutsu list in the Sume catalog only where their provider route is configured. How listing works, plus a Python check that fails on a missing id.
Recover Sume jobs after a crash: match your key to GET /v1/jobs
Your worker died after submit and lost the job ids. Page GET /v1/jobs, match idempotency_key to your own keys, stop at the last page. A 29-line sample.
aiohttp 3.14.4 fixes truncated retried file bodies: Sume submits
aiohttp 3.14.4 fixed an internal retry that sent a cut-off body from a file object. Send a Sume JSON submit from bytes and keep one Idempotency-Key.
Express 5.3 logs Error.cause: keep the Sume request_id
Express 5.3.0 prints the full error object, nested cause included. Wrap a failed Sume call so its code and request_id land in the log line you grep.
FastAPI 0.143 makes OTel exporter setup opt-in: Sume webhook spans
FastAPI 0.143.0 stops auto-configuring OpenTelemetry exporters. If your Sume webhook route traces went quiet after the upgrade, here is the one-line opt-in.
Go 1.27.2 and 1.26.9 patch net/http: update your Sume webhook receiver
Go 1.27.2 and 1.26.9 (2026-10-08) list security fixes in net/http and crypto/tls. A stdlib receiver for Sume webhooks that verifies the signature, in two files.
Node 26.11 --process-timeout exits 124: the Sume job keeps running
Node 26.11.0 adds --process-timeout, which kills a script with exit code 124. A Sume job it was waiting on keeps running and billing, so save the polling URL.
Vercel skipMiddlewareRequestBody and a Sume webhook route
Vercel's Oct 8 skipMiddlewareRequestBody stops sending request bodies to Routing Middleware. What it means for a Sume webhook route that signs the raw body.
Does Sume accept lowercase 4k as a video resolution? Yes
Since fab7d59af, lowercase 4k is an alias on every Sume video row that lists 4K, on both /v1/video-router/generate and /v1/videos.
Pick the highest resolution a Sume video model lists (Python)
Sume's catalog row is now the one resolution list for both video endpoints. A short Python helper reads supported_resolutions and steps down instead of failing.
Bun 1.4.3 ERR_PROXY_TUNNEL: is it a Sume error or your proxy?
Bun 1.4.3 rejects fetch with ERR_PROXY_TUNNEL on a failed CONNECT. A Sume error always carries error.request_id; use it to tell the two apart.
Bun 1.4.3 fake timers: test a Sume poll loop with request timeouts
Bun 1.4.3 fixes advanceTimersByTime spinning with AbortSignal.timeout. Test a Sume job poll loop that honors next_poll_after_seconds without real waits.
Bun 1.4.3 fetch Content-Length check: send a Sume JSON body as bytes
Bun 1.4.3 rejects fetch when a declared Content-Length mismatches a stream body. For a Sume submit, skip the header and pass the encoded JSON.
Claude Code 2.1.296: headless runs skip a switched-off MCP server
Claude Code 2.1.296 fixed claude -p starting a .mcp.json or plugin MCP server that was switched off. What that means for Sume's paid tools in CI.
Claude Code 2.1.296 raises the MCP instructions cap to 4,096
Claude Code 2.1.296 doubled the default MCP instructions cap to 4,096 characters. Sume's server instructions are about 10,900, so the cap still applies.
bun run --check: type errors stop before a Sume job submits
Bun 1.4.3 adds bun check and a --check flag on bun run. Use it so a type error in your Sume script fails before a paid generation request is sent.
Next.js Oct 14 security update: redeploy, then test your Sume webhook
Next.js will ship an out-of-band security update on Oct 14. Prepare your Sume webhook receiver now, then prove it still verifies after you redeploy.
Fly Machines --schedule is fuzzy: key a Sume job by period
Fly's --schedule starts a Machine on an approximate hourly, daily, weekly or monthly cycle, not at a set time. Key the Sume submit by period, not by start time.
Heroku Scheduler can skip or double-run: protect a Sume job
Heroku says Scheduler may miss a run or run twice. Use a slot Idempotency-Key plus a catch-up check so Sume bills once per slot.
Render cron job that submits a Sume job: one key per slot
Render delays a cron run while one is active, and a manual trigger cancels it. Use a UTC slot Idempotency-Key so a re-run never bills a Sume job twice.
Claude Code hook: swap Sume's download URL for a saved file
A PostToolUse hook with updatedToolOutput can fetch the signed link from assets_download_url, save the file, and show Claude only the local path.
nginx proxy_read_timeout is 60s, but Sume gives up at 10s
nginx waits up to 60 seconds for your app by default, yet a Sume webhook attempt times out at 10. Why raising proxy timeouts does not help and what to do.
Page on-call when a Sume webhook is exhausted: PagerDuty dedup_key
Send a PagerDuty Events API v2 trigger when Sume gives up on a webhook, using the job id as dedup_key so retries and redelivers never page twice.
Terraform and secrets: keep the Sume API key out of state
Terraform's sensitive flag hides a value from logs but still writes it to state. How to handle a Sume API key and webhook signing secret without that leak.
Compose 400: stack and overlay layout keys cannot be mixed
Fix compose_stack_takes_no_overlay_layout and its mirror: pick stack or overlay as operation, then send only the layout keys that belong to it.
Timeline 400: first slot must start at 0 and take no transition
Fix timeline_must_start_at_zero and transition_on_first_segment: start video[0] at 0, use source_in to skip, put fades on slot two, then plan for free.
video_inspect 400: frames program and transcribe flag errors
Fix video_inspect_frames_program_conflict, _required and video_inspect_transcribe_required: send at or fps, and transcribe true with its language options.
Game NPC barks: 150 short lines in one TTS job (43 cents) vs 150 jobs
Short lines cost 1 cent each as separate Sume TTS jobs. One job with sentence slices returns the same 150 lines as separate WAV files for 43 cents.
IVR phone menu prompts with TTS: 8 kHz mu-law WAV and cost per prompt
Make phone-menu prompts as 8 kHz mu-law or A-law WAV with Sume TTS. A 20-prompt menu bills 20 cents because each short job hits the 1-cent minimum.
7:5 and 5:7 images: crop from 3:2, 4:3, 3:4 or 2:3 on Sume
No Sume image row lists 7:5 or 5:7, but BFL's FLUX 3 Image does. How many pixels you lose cropping from 3:2, 4:3, 3:4 and 2:3, with the exact numbers.
FLUX 3 Image has no negative prompt: what to write, and Sume's rows
BFL's FLUX 3 Image has no negative_prompt field; it wants the positive version. The replacement table, a runnable rewriter, and Sume's image rows' fields.
Vidu Q4 image-to-video request, field by field, as a Sume body
Vidu Q4 Preview is not in Sume's video catalog (read 2026-10-09). Map its img2video fields to POST /v1/videos on seedance-2.5 or wan-3.0.
Vidu, Wan 3.0 and Sume job states in one poller
Vidu says created/queueing/processing/success/failed, Wan says PENDING/RUNNING/SUCCEEDED/FAILED, Sume says pending/in_progress/completed. One mapping table.
Wan 3.0 X-DashScope-Async header and polling vs Sume
Alibaba needs an X-DashScope-Async: enable header and suggests polling about every 15 seconds. Sume is async by default and hands you a polling_url.
Egress firewall for a Claude agent in CI: Sume hosts to allow
Claude Agent SDK v0.2.164 hardens CI egress firewalls. Which Sume hosts a render job needs: api.sume.com, mcp.sume.com and media.sume.com, and what each is for.
Wan 3.0 reference file limits: pixels, ratio, MB and fps preflight
Alibaba lists per-file limits for Wan 3.0 reference images, videos and audio. A runnable Python check to run before you submit them to Sume.
Wan 3.0 reference video needs 16 fps: probe clips before Sume
Alibaba lists 16 fps or more, 1 to 15 s and 100 MB for each Wan 3.0 reference clip. An ffprobe script that checks your real files before you send URLs to Sume.
Quantized H3 vs lossless H3 vs a hosted clip: compare fairly
MiniMax's guide says not to mix ComfyUI quantized and SGLang lossless outputs. How to set up a fair comparison with a hosted clip, including the seed catch.
Alibaba Wan 3.0 Model Studio request to a Sume /v1/videos body
Map a Model Studio wan3.0-video call (input.media, parameters, X-DashScope-Async) to POST /v1/videos with model wan-3.0. Field by field.