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 rejects localhost webhook URLs: test locally with a poll fallback
Sume only accepts public HTTPS webhook URLs and rejects localhost and private networks. For local work, poll the job and keep webhooks for a deployed endpoint.
TTS language en-US vs en-GB on Sume: regional tags compare by language
For the voice-language check, Sume compares regional tags by primary language, so en-GB on an en-US voice does not trigger the 409, and fil matches tl.
Live commerce TTS rejects literal text: use transcript_source
Sume's live-commerce TTS takes only transcript_source (a script revision plus sentence IDs) and rejects literal transcript text, even if correct.
Video editing API or AI prompt edit: which Sume endpoint to call
Trim, frames, captions and filter are deterministic jobs; Omni edit changes content from a prompt. Pick the cheapest route that does the change you need.
video_url on /v1/videos fails: edits go to /v1/video-router/generate
Sume's /v1/videos has frame_images and input_references but no edit field. Send video_url to /v1/video-router/generate with gemini-omni-flash-1.1.
What balance do 100 video ads need? Sume reserves at submit
Sume reserves the credits of every accepted job at submit, so a 100-ad batch needs the whole total in the balance. 402 insufficient_credits otherwise.
Why a video model is missing from your Sume model list
A documented video id can be absent from the model list: Veo needs Google Cloud, Tencent rows need the Tencent switch. Absent ids 404. Read 2026-10-13.
Astro 7.3.8 actions: call the Sume video API, key stays on the server
Astro actions give a browser form a typed way to start a Sume video job and poll it, without the API key in client code. Zod 4 validation, 402 handling.
Effect 4.0.4 retryTransient honors Retry-After: key your Sume submit
Effect 4.0.4 makes HttpClient.retryTransient honor Retry-After, so a Sume 429 waits as told. It also retries POST on 5xx, so send an Idempotency-Key.
Go 1.27.2 synctest: test a 30-second Sume poll loop in milliseconds
Test a Go poll loop for Sume video jobs with testing/synctest: 90 seconds of fake sleeps and a 20-minute deadline pass in under a second, no sockets.
k6 2.3 --once and --scenario: smoke-test the Sume API without spend
Use k6 --once and --scenario for a Sume API smoke test that costs nothing: models, a deliberate 400, and a paced balance read that counts 429s.
Playwright 1.64 lock and --shuffle for a Sume API test suite
Playwright 1.64 adds a describe lock and --shuffle. Use them to test Sume video calls: free 400 checks run in parallel, one paid test holds a credits lock.
Tokio JoinSet and Semaphore: eight Sume clips, abort on a 402
Run Sume video jobs from Rust with reqwest, a Tokio Semaphore, and a JoinSet that collects clips as they finish and calls abort_all on a 402.
Bun 1.4.3 EAI_AGAIN vs ETIMEOUT: retry a Sume submit safely
Bun 1.4.3 reports a temporary DNS failure as EAI_AGAIN, not ETIMEOUT. Update your retry check, and keep one Idempotency-Key across every Sume submit retry.
Bun 1.4.3 fetch stream errors: catch a cut-off Sume video download
Bun 1.4.3 fixes response streams that ended cleanly after a transfer failure. Still check the byte count when you save a finished Sume video to disk.
Where is the transcript for my caption job? Use video_inspect
A Sume caption job returns a captioned video, not raw text. For words and sentence segments, run video_inspect with transcribe true at $0.01 per audio minute.
provider.sort and allow_fallbacks on Sume images: accepted, no effect
Porting OpenRouter-style image code to Sume: provider ignore, sort and allow_fallbacks are accepted but change nothing. only and order take "sume" alone.
Timeline audio 400: concat takes no url, split takes no parts
Sume's timeline audio endpoint rejects concat with a top-level url and split with parts. Stable error codes and the right shape for each operation.
Validate an image request against supported_parameters first
Sume rejects a parameter a model does not list with 400 unsupported_parameter. Read the catalog descriptors and check a request body before you POST /v1/images.
Lambda Powertools idempotency and Sume's Idempotency-Key: use both
Powertools idempotency guards your Lambda handler; Sume's Idempotency-Key guards the paid submit. How they differ, and how to derive one key from an order id.
LangGraph replay re-fires API calls: key Sume submits per fork
LangGraph time travel re-runs every node after the checkpoint, API calls too. Derive the Sume Idempotency-Key from the body so replays dedupe and forks run.
Usage hold_counts: open, browser_session, billing_pending
A scoped Sume usage summary can show final false with money held. hold_counts says whether a turn runs, a Browser session is open, or work is being priced.
What one script_run call cost: the usage script_runs array
Sume's usage summary lists each script_run call with its rows, debited, held and refunded micros, so a fan-out of TTS or image jobs has one price.
WireMock scenarios: fake a Sume job going queued to completed
Use one WireMock scenario per job so GET /v1/jobs/{id}/status answers queued, processing, then completed, and test the poll loop without spending.
xAI video API polling: pending, done, failed vs Sume job states
xAI's video API returns a request_id and three states. Here is how they map onto Sume's five /v1/videos statuses, with a runnable Python polling loop.
Eleven v4 seed and voice settings: what each Sume router id accepts
Which of stability, similarity_boost, style, speed and seed work on eleven-v4, v4-turbo, v3, multilingual-v2 and turbo-v2.5 in the Sume TTS Router, with ranges.
ElevenLabs voice ids in the Sume TTS Router: list them, avoid 400s
Eleven v4 and other eleven-* ids run through the Sume TTS Router. How to list voices with family=eleven, which id shape each family takes, and what gets a 400.
Image-to-video with sound by API: Sume ids that take a first frame
Kandinsky 6.0 has an image-to-audio-video mode. On Sume these ids take a first_frame image and return sound, and these do not. Request code included.
MCPJam auth debugger on Sume's MCP host: what each step returns
Point MCPJam's auth debugger at mcp.sume.com and read the results: S256-only PKCE, public clients, authorization_code only, a one-hour token, a resource check.
What did one script_run cost? Sume script_runs and its children
Sume /v1/usage lists script_runs with rows and money per call, and counts script_run_children in includes. Read the cost of one script_run to the cent.
pending_usd_micros vs held: what Sume's settle sweeper still owns
Sume /v1/usage splits open holds into held and pending_usd_micros. Read the two fields and settle_state to tell parked rows from spend, and when final flips.
unpriced_usd_micros: legacy rows still inside Sume's debited total
unpriced_usd_micros in Sume /v1/usage is captured spend from legacy rows with no price-book stamp. It is inside debited, so never subtract or add it twice.
TanStack Start webhook route for Sume jobs: verify the raw body
Receive a signed Sume job webhook in a TanStack Start server route: read request.text(), verify with the SDK, answer 204, and dedupe on job_id.
Word timestamps for an Eleven v4 voice: the router says 400, use STT
The Sume TTS Router rejects timestamps on eleven-* ids. Get word timings by running the finished narration through Sume STT for one cent a minute.
Grok Imagine Video 1.5 Lite batch API: what xAI documents
xAI's Lite page lists a $0.02 per second price, 10 requests per second, batch support and two regions. Sume jobs are async instead; here is how they differ.
Nova 2.5 Sonic async tool calls: start a Sume job, return the job id
With asynchronous tool calling, a Nova 2.5 Sonic agent can start a Sume music or caption job, answer at once with the job id, and poll status later.
pplx-embed-v2-late for storyboard frames: Sume has no embeddings route
Perplexity's pplx-embed-v2-late embeds images and pages. Sume lists no embeddings route; use video_frames_create for stills and index them on your side.
Sume 400 invalid_request: read details.errors[].path to find the field
A Sume 400 invalid_request lists each bad field in details.errors with path, loc, message and type. Read them in Python instead of guessing from the message.
A Sume 400 that returns a job id: input rejected at provider submit
Most Sume 400s create nothing, but a provider input rejected at submit leaves a failed job, a request_id and a refund. How to read it and what key to use.
Sume 404 resource_not_found: job_not_found and model_not_found overlap
Every Sume 404 reports public_reason resource_not_found, whatever the code. Branch on error.code to tell a missing job from a bad model id or a missing asset.
Sume 409 job_not_queued: the job left the queue before it started
What the Sume 409 job_not_queued means: a submit found its job no longer queued, sent nothing to the provider, and the error is not retryable by resending.
Sume generation_capacity_exhausted: the 503, job reason and flag
Sume reports provider capacity three ways: HTTP 503 provider_capacity_exceeded, a job reason generation_capacity_exhausted, and a sync flag. All three retry.
Sume job failed artifact_too_large: shrink the output, don't rerun
A Sume job failing with artifact_too_large or artifact_upload_rejected made its file but could not store it. Make the file smaller; rerunning changes nothing.
EmbeddingGemma 2's 5.5-minute audio limit: cut a long track
EmbeddingGemma 2 fits 5.5 minutes of audio. A 28-minute video needs six 300-second audio detach ranges at $0.01 per job, $0.06 in total.
EmbeddingGemma 2 takes 58 video frames: sample them with Sume
EmbeddingGemma 2 fits 58 video frames in its 8K window. Sume's video inspect returns 24 stills per call, so three calls with explicit times cover it.
Actix Web: verify a Sume webhook from the web::Bytes extractor
Take the Sume webhook body as web::Bytes in Actix Web, verify HMAC SHA-256 with the hmac and subtle crates, and return 204 or 401.
Falcon ASGI: verify a Sume webhook with req.bounded_stream.read()
Read the raw Sume webhook body in Falcon ASGI with req.bounded_stream.read(), verify HMAC SHA-256, and set HTTP_204 or raise HTTPUnauthorized.
Go Fiber v3: BodyRaw for Sume webhooks, and copy it before you queue
Sign-check a Sume webhook in Go Fiber with c.BodyRaw() and hmac.Equal, then copy the bytes before handing them to a goroutine, since Fiber reuses them.