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
Transcribe the first 60 seconds of 500 support recordings
500 screen-recorded support sessions: detach seconds 0 to 60 ($5.00), then STT 60 s each ($5.00). Total $10.00 at $0.01 per job and per minute.
Stream a Sume video download in Python: .part file, then rename
Download /v1/videos/{id}/content with requests stream=True, write a .part file and rename on success. A lost 30 s clip costs $1.875 to $17.334 to re-buy.
Seven pre-flight checks before an Omni, H3 or Recast job
Duration, resolution, ratio, edit conflicts, reference counts, refused fields and URLs: seven per-model checks that catch a refused Sume video request.
curl -w http_code: branch a Sume video submit in bash on 202, 402, 429
A bash submit that saves the body, reads the HTTP code with curl -w and branches on 202, 402, 429 and 5xx. Three Wan 3.0 payloads cost $1.875, $3.75 and $7.50.
Duration dropdown from supported_durations: 27, 29 and 8 choices
Seedance 2.5 offers 27 lengths, Wan 3.0 29, Omni Flash 1.1 8. Map supported_durations to options in TypeScript, with the price of the longest option.
POST /v1/videos status codes: which of 10 are safe to retry
OpenAPI lists 202 plus ten error codes for POST /v1/videos. Which to retry with the same key, which to fix or stop on, a Python classifier and a backoff plan.
Poll every 2 s or 30 s? Reads per 20-minute video job on Free and Pro
Polling a Sume video job every 2 s is 600 reads in 20 minutes; every 30 s is 40. Share of the read budget on Free and Pro, with a Python check.
Node: stream a Sume video to disk with pipeline and a short-file check
Download a finished Sume video from /v1/videos/{id}/content in Node without loading it into memory, and fail if the file is shorter than content-length.
Resume polling Sume video jobs after a restart with a sqlite ledger
Write the job id and Idempotency-Key to sqlite before anything else can crash, then resume polling open jobs on start. Python standard library only.
Edit an existing clip with Gemini Omni Flash 1.1: video_url on Sume
Sume exposes Omni video edit mode through the Video Router video_url field: the prompt is the instruction, resolution defaults to 720p, no duration.
OpenRouter video payload on Sume: drop seed, size, provider.options
Sume /v1/videos follows the OpenRouter shape but rejects seed, size and provider.options with a 400. A Node function that strips them and checks the model id.
ffprobe check for Gemini Omni reference videos: 3 files, 3 s each
Before sending reference videos to Sume's gemini-omni-flash-1.1, check with ffprobe that you have one to three files and each is 3.0 s or shorter. Bash script.
Video Router body to /v1/videos: frame_images, input_references
Map Video Router image_url, end_image_url and reference_image_urls to /v1/videos frame_images and input_references, with a Node converter.
List Sume video model limits with curl, jq and column in one table
curl GET /v1/videos/models into jq and column to see each model's duration range, resolutions and audio flag in one table. Documented limits for six models.
FLUX.3 not on Sume yet: detect it via /v1/images/models, fall back
Sume does not list FLUX.3. A Python script reads /v1/images/models, uses FLUX.3 if it appears, else Nano Banana 2.1 at 2K for $0.15. BFL 2k is $0.100.
Hosted Sume MCP token hygiene: 5 rules for agent credentials
Five Sume credential rules: an OAuth token is not an API key, stays out of CLI config and prompts, never goes to other providers; rotate exposed keys.
Remote MCP with an API key: x-api-key or Bearer on Sume?
Sume's hosted MCP accepts a key as Authorization: Bearer or as x-api-key. Both see the full tool set; writes and paid calls still need an idempotency_key.
MCP authorization spec: 6 requirements vs what Sume documents
The MCP authorization spec asks for resource metadata, PKCE and a resource parameter. Here is what hosted Sume MCP documents for each, and what stays open.
Still on /v1/image-router/generate? It works but gets no new params
Sume's legacy image-router generate and models routes still work but are deprecated and get no new parameters. What to change to move to POST /v1/images.
A fresh UUID per retry is not an idempotency key (Node, Sume)
Create the Idempotency-Key once outside the retry loop, retry only 429, 502, 503 and 504, and stop on 4xx. A Node submit helper for Sume /v1/videos.
Replay a sume/auto video submit with one key, assert one job
Submit model sume/auto twice with the same Idempotency-Key and assert the same job id and the same route. Why a replay is safe and why Sume hides the family.
Idempotency-Key from a body hash plus a take number (Node, Sume)
Build an Idempotency-Key for Sume /v1/videos from a SHA-256 of the body plus a take counter, so a retry replays and a re-roll pays. Node code.
Total usage.cost for Sume video job ids with curl, jq and awk
One shell pipeline: read job ids from a file, GET /v1/videos/{id} for each, keep completed jobs, and sum usage.cost with awk. No Python or Node needed.
Check your image cost table against Sume /v1/images/models cost_usd
Read pricing lines from GET /v1/images/models/{id}/endpoints and compare cost_usd with your own table before a batch. Sume lines already include its margin.
Deno.serve webhook receiver for Sume jobs: Web Crypto HMAC, rotation
Verify Sume job webhooks in Deno with Web Crypto: refuse an empty secret, accept any rotation entry, 300 s tolerance, return 204. Retry window is 370 s.
Face swap webhook receiver in Python that refuses an empty secret
Verify a Sume face swap job.completed webhook in Python: HMAC SHA-256 over timestamp.body, sume-v1 entries, a 5-minute window, and an empty secret refused.
Agent Completion webhook retries: 10 attempts over about 3 hours
Sume tries an agent.run.terminal webhook up to 10 times. By the documented formula the nine waits add up to about 3 h 3 min, before jitter and Retry-After.
OpenRouter video client on Sume: cancelled is terminal, callback_url
Moving an OpenRouter video client to Sume: add cancelled to your terminal statuses, send callback_url on each request, and keep unknown statuses non-terminal.
Scheduled run input: 64 properties and 2 MiB, how to pack a brief
A Sume scheduled run takes an input object of at most 64 properties and 2,097,152 bytes. Here is how to pack a brief for an agent without hitting either limit.
AI voiceover too loud: three Sume gain knobs and what each one costs
TTS generation_config.volume (0.5-2), Timeline audio.gain_db (-60 to 12) and soundtrack.duck_db (0-20). Which to change, and which means paying for new audio.
Which AI video models on Sume make their own audio track
Gemini Omni Flash 1.1 always generates audio and rejects generate_audio false; MiniMax H3 Max has native stereo audio; Seedance 2.0 reports generate_audio true.
Transcribe a 15-second voice note in one request: STT sync mode
Sume STT can answer in the same HTTP call: mode sync with wait_timeout_seconds up to 30 returns 200, otherwise 202 and a poll. A $0.01 minimum, with curl.
Sume MCP OAuth in six steps: from the first challenge to a call
Hosted Sume MCP OAuth takes six steps: challenge, authorize redirect, consent page, Write toggle, PKCE code exchange, then a bearer call to the MCP endpoint.
One webhook route for OpenRouter video and Sume job events
Normalize OpenRouter video.generation.* and Sume job.* webhook bodies to one outcome type, and answer 204 to events you do not know. Runnable Bun/Node code.
Failed AI video jobs: Google bills successes, Sume refunds the hold
Google says Veo videos are charged only when generated. Sume holds the price at submit, captures it on success and refunds it on failure or early cancel.
createSumeClient sends x-api-key only: an extra header gives 401
The Sume API accepts Bearer or x-api-key but rejects both at once with 401. A fetch wrapper for createSumeClient that drops the extra header, tested offline.
generation_limits missing from a Sume submit: send one, then re-read
The docs say the snapshot is included when Sume can compute it. A Python rule for waves when it is absent, full, or open, tested on three inputs.
List Sume video models: /v1/videos/models for limits, /v1/catalog
Two discovery routes, two jobs. /v1/videos/models returns durations, resolutions, aspect ratios and audio flags; the public /v1/catalog lists the wider catalog.
sume/auto on a retried submit: same job, model still sume/auto
A retry of a sume/auto video with the same Idempotency-Key returns the original job, price and route. A Python check, plus why the family is never disclosed.
Sume TTS language field: set ja or ko, or the voice reads in English
Omit language on Sume TTS and the provider defaults to English; Sume infers ko or ja only from a Hangul- or kana-only script. Set it on non-English scripts.
Sume webhook_url without a mode field: it runs in webhook mode
Send webhook_url and omit mode, and Sume treats the submit as mode webhook: 202, job id in the first response, signed terminal callback, poll as backup.
Sume TTS speed 0.6 to 1.5: a 14-minute script and the 1,200 s cap
generation_config.speed runs 0.6 to 1.5. A 14-minute read slowed to 0.6 would need about 23 minutes and hit the 1,200-second cap; the price stays per character.
Sume TTS sentence segments: boundary_lead_ms 0 vs 500, 12 lines
Ask Sume TTS for words and sentence segmentation and you get gapless wav slices. boundary_lead_ms (default 70) moves each cut 0 to 500 ms after the last word.
wave_size_hint on an empty workspace: Free 4, Pro 18, Startup 36
What generation_limits.wave_size_hint returns before any job is queued, by Sume plan, with the arithmetic and a Python check you can run.
Eight Wan 3.0 clips on Free: six queue, two get queue_full
Free plan accepted capacity is 6 paid jobs. Submit eight 10-second Wan 3.0 720p jobs and two return 429 queue_full; the six accepted hold $7.50 of the $10.00.
Sume job webhook retries: 370 s worst case, then poll or redeliver
Sume retries a job webhook 10 times, 30 s apart, with a 10 s timeout each: 270 s of gaps and up to 370 s in total. What to do when the window closes.
Store the Sume job webhook, then answer 204: SQLite insert-or-ignore
Commit the event keyed on job_id before you return 2xx, so a retry or a redeliver is harmless and a crash never loses it. Runnable Python and sqlite3 example.
Avatar video image URLs: product_image, scene photo and backgrounds
Sume avatar video takes three kinds of image URL: product_image, scene.image_url and scene-background images. All must be public HTTPS. Checks to run first.