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
Sume Send test vs Redeliver: which to use for avatar video jobs
Send test posts a dummy webhook.test payload to a URL you type; Redeliver re-sends a real job's terminal event with a fresh signature. When to use each.
Ruby verifier for Sume avatar job webhooks (HMAC SHA 256)
A Ruby method that verifies Sume's x-sume-webhook-signature: HMAC SHA 256 over timestamp.body, any sume-v1 entry, five-minute window, empty secret refused.
Video-trim says unsupported_media_source: which Sume routes take URLs
Trim, filter and compose need a media.sume.com clip; upscale, STT, RMBG and captions take public HTTPS URLs. Imports take TikTok and Instagram. Read 2026-10-10.
Pick the cheapest Sume image row for a ratio and 3 refs (Python)
A 24-line Python script reads GET /v1/images/models and the endpoints route, filters by aspect ratio and reference count, and sorts by billed price.
Sume image 400 'does not accept aspect_ratio': read supported (Python)
When a Sume image row rejects aspect_ratio with 400 invalid_request, the error carries a supported array. This Python snippet picks the nearest listed ratio.
ElevenLabs dubbing output: mono v1, stereo v2, and Sume channels
ElevenLabs dubbing v1 returns mono and v2 at most stereo. On Sume, detach keeps source channels or mono, and a concat of mixed layouts fails by design.
A for await loop over Sume job status: one async generator, 3 runtimes
Wrap Sume status polling in an async generator and read it with for await. One fetch-only file ran unchanged on Node, Bun and Deno and honors the poll hint.
Is there a Sume API test mode? No sandbox key, but two hosts
Sume has no sume_test key. Use the dev host with its own key, cap each run with generation_spend_cap_usd, and mock the rest. What each option costs and covers.
openapi-fetch with Sume's OpenAPI JSON: a typed client in 20 lines
Generate types from Sume's reference JSON with openapi-typescript, then call it with openapi-fetch and an x-api-key middleware. A type-checked sample.
Tailscale Funnel for Sume webhooks: a public HTTPS URL for localhost
Sume webhook URLs must be public HTTPS, so localhost is rejected. Tailscale Funnel gives your dev machine one, plus a receiver that refuses an empty secret.
Test a Sume poll loop with node:test mock.timers, no real sleeping
Use node:test mock.timers to prove your poll loop waits next_poll_after_seconds, falls back to 2 s, and never polls early. A runnable test, no network.
Python 3.14 uuid.uuid7() as a Sume Idempotency-Key: when it is safe
uuid.uuid7() is new in Python 3.14 and makes a tidy Idempotency-Key for Sume submits, if you generate it once per intent and store it. A runnable stdlib sample.
uv run a single-file Python script against the Sume API (PEP 723)
A one-file Sume script with inline PEP 723 dependencies runs with uv run and no virtualenv. Submit, poll next_poll_after_seconds, print the result.
A circuit breaker for paid video API calls: cap, poll, cancel
Guard paid video generation with three layers: a per-run spend cap, a loop breaker in your code, and cancel. Sume charges for work done before a cancel.
Write a Sume video URL back to a CMS record: what to store
Sume media URLs in a finished run are durable and public. Store them on your CMS record, and proxy or copy them if you need per-customer access control.
Grok Imagine Lite's 10 requests per second vs Sume plan concurrency
xAI lists a 10 requests per second limit and Batch API for Grok Imagine 1.5 Lite. On Sume, a clip batch is bounded by plan concurrency and queue capacity.
Sume API 401 on the dev host: keys only work on their own host
A Sume key works only on the host it was created for. A key from api.sume.com gets 401 on api.dev.sume.com and the reverse. Match key, host, and env var.
Move a Vidu Q4 job to Sume: six fields to check before you submit
Vidu Q4 Preview's image-to-video fields (duration, resolution, start image, audio) mapped to Sume's /v1/videos names, with a Python filter for rows that fit.
Fit an AI voiceover to a target length with Sume TTS speed 0.6 to 1.5
To hit a target duration, generate once, measure the audio, then set generation_config.speed to measured over target, clamped to Sume's 0.6 to 1.5 range.
Sume TTS 400 tts_language_script_mismatch: Korean encoding check
Sume TTS rejects language ko when the transcript has no Hangul syllable: 400 tts_language_script_mismatch, no charge. Usually the text was decoded wrongly.
ElevenLabs 8 kHz mu-law and A-law vs Sume TTS pcm_mulaw, pcm_alaw
For phone-line audio, ElevenLabs lists 8 kHz mu-law and A-law. Sume TTS 1.0 offers pcm_mulaw and pcm_alaw in a raw container at 8000 Hz.
Scribe accepts MP4 and MOV; Sume STT needs an audio URL: detach first
ElevenLabs Scribe takes video files such as MP4 and MOV directly. Sume STT wants a public HTTPS audio_url, so a video goes through audio detach first at $0.01.
Sume STT words[] cap: what words_truncated and words_total mean
Sume STT returns word timings capped at 20,000 entries and sets words_truncated and words_total when it hits the cap. A 600-second job stays far below it.
Silent reference clip: stt_skipped_silent, no-audio and caption errors
A silent clip does not fail a Sume reference ingest, and STT settles to zero. Video inspect and captions do raise errors on silence.
Veo 3.1 request on Sume: 720p, 4, 6 or 8 seconds, in Python
A working POST /v1/videos call for veo-3.1-lite with 6 seconds, 9:16 and no audio, the rates for the three Veo rows, and what Sume rejects.
How do I ask Sume for 2K? Only 5 of 19 image rows list resolution
Only Nano Banana 2.1, Nano Banana Pro, Imagen 4 Ultra, Ideogram 4.5 and Soul list a resolution field. Send it to FLUX, Seedream or GPT and you get a 400.
Sume webhook URL localhost returns 400: test with a tunnel
Sume refuses localhost, private ranges, and plain HTTP webhook URLs with a 400 at create. Use a public HTTPS tunnel and verify the signature.
A sensor for a Sume Format run: poll, back off, time out
Poll a Sume Format run with a doubling backoff up to 60 seconds and a hard deadline. Here is the loop, the terminal states, and a 45 minute limit.
Which language does Lyria 3.5 sing in? Spanish prompt on Sume Music
Google says Lyria generates music in the language of your prompt. On Sume, write the brief in the language you want sung; no language field exists on Music.
Prove a Sume retry makes one job: drop the response on purpose
A 28-line fake server creates the job, then hangs up before replying. A stable Idempotency-Key leaves one job; a fresh key per retry leaves two. Runs anywhere.
How many Format runs per minute can my Sume plan start?
Sume limits writes per minute by plan, from 120 on Free to 1200 on Scale, with reads at 40 times that. Read the rate-limit headers and back off on 429.
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.