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/auto or a pinned video id after a vendor retires a model?
After the Sora removal, choose between model: sume/auto and a pinned catalog id. What each guarantees on Sume, with the 3-10 s, 720p, 8 s Auto defaults.
OpenAI gave six months' notice on Sora: dates and a checklist
OpenAI told developers on 2026-03-24 that the Videos API and Sora 2 ids go on 2026-09-24, with no replacement listed. Six ids and a checklist.
4:5 still to video: no Sume video model lists 4:5, so pick another
No video model in Sume's catalog lists 4:5. Make the still 3:4 or 1:1, animate it, then crop to 4:5 with a $0.02 video-filter pass.
HappyHorse result links expire in 24 hours: save the file the same day
Alibaba's HappyHorse API says video URLs and task ids last 24 hours. Download on completion, in Python, from Sume's content endpoint or any vendor's.
QA 1,000 voice-agent calls with speech-to-text on Sume
Transcribe call recordings to review a voice agent. Sume STT is $0.01 per audio minute with a 10-minute reservation limit: the math for 1,000 calls.
1920x1088 works on GPT Image 2.5 where 1920x1080 fails: the 16 rule
1080 is not a multiple of 16, so a custom 1920x1080 size is rejected on ChatGPT Image 2.5. Use 1920x1088 or 1536x864, then trim. Prices included.
21:9 banner still to video: only Seedance and MiniMax H3 list 21:9
A 21:9 still can only become a 21:9 clip on Seedance or MiniMax H3 in Sume's catalog. GPT Image 2.5 reaches 21:9 with a 2352x1008 custom size.
Voice agent narrates a long task: poll a Sume video job meanwhile
Decagon Voice 3 narrates progress during long tasks. The same pattern for a voice agent that starts a Sume job: submit, speak, poll jobs_wait.
MAI-Voice-2.1-Flash: Voice Live or the Speech SDK with SSML?
Microsoft's docs show two ways to call MAI-Voice-2.1-Flash: the Azure Speech SDK with SSML, and Voice Live. Which fits an agent, which fits a batch.
Keep a series voice consistent: pin model, voice, speed and volume
A series sounds the same only if every episode sends the same TTS settings. Keep one profile in code, pin a model id, and send it with each Sume request.
Label speakers without diarization: transcribe each mic track, merge
Sume STT has no speaker labels. If you record each speaker on a separate track, transcribe both tracks and merge the segments by start time. Python script.
Sume STT to an SRT file: build subtitles from sentence segments
Sume returns timed sentence segments, not an SRT. Turn them into a valid .srt file in Python for YouTube, Vimeo or a player, with the timestamp format.
Never set toleranceSeconds to 0 on a Sume webhook verifier
toleranceSeconds 0 skips the timestamp check, so a captured delivery verifies forever. See the replay and a WebCrypto verifier that rejects stale ones.
Refuse an empty Sume API key or webhook secret: a fail-fast loader
An empty SUME_API_KEY or webhook secret fails late and confusingly. Load both at boot, reject empty or whitespace values, and never print them. Python, tested.
A Node CLI to submit a Sume video job: util.parseArgs and --dry-run
A Node script with util.parseArgs that validates duration, builds the /v1/videos request, and prints it with --dry-run before anything bills. Tested offline.
Record the Idempotency-Key before you POST a Sume video job
A worker that dies after submitting a video job loses the job id. Write the key to a ledger first, then POST; a retry returns the same job. Tested SQLite code.
A/B test two AI video models by API with a stable hash bucket
Split production video jobs between two Sume model ids by hashing a job key, so retries keep the same arm. Python code, a duration table and a 1,000-key check.
asyncio TaskGroup cancels siblings: poll many Sume jobs safely
A TaskGroup cancels every other poller when one raises. For a batch of Sume video jobs that abandons waits, not jobs. Catch inside the task and return results.
Check a Shorts timeline body offline: a Python mirror of the rules
Catch Timeline 1.0 refusals you can see in the body (start at 0, 0.5 s coverage, transitions, even sizes) in 28 lines of Python before the plan call.
Check an image request against the Sume catalog before you send it
Fetch GET /v1/images/models once, then reject a bad ratio, quality or reference count in Python before it reaches POST /v1/images and returns a 400.
TTS then H3 Max lip sync: check the 5 to 14.8 s audio window
H3 Max lip sync takes 5 to 14.8 seconds of Sume-hosted audio and clips the rest. Measure a TTS line from its word timings and price it before you submit.
Claude Code PreToolUse hook: block paid Sume calls without a spend cap
A PreToolUse hook that denies Sume generate and TTS tools when max_spend_usd or idempotency_key is missing. Python hook with the settings.json matcher, tested.
Clicks or gaps when joining TTS MP3 clips: render WAV, join once
Joined MP3 voiceover clips can gap or click. Sume's Timeline audio docs explain why: MP3 adds priming padding at each edge. Keep WAV until the last step.
AGENTS.md rules for a coding agent that calls Sume over hosted MCP
Six AGENTS.md lines that stop a coding agent double-billing Sume video jobs: idempotency_key, jobs_wait slices, dry_run, plus a CI lint script.
Cursor mcp.json for the hosted Sume server: env interpolation or OAuth
Cursor reads .cursor/mcp.json with url and headers and supports ${env:NAME}. Pass the Sume key from the environment, or omit headers and use OAuth. Validated.
Express receiver for Sume TTS job webhooks: raw body and HMAC
A Node Express route that verifies Sume job webhooks over the raw body, accepts rotated secrets, rejects an empty secret and answers 204 before any work.
Gemini CLI and the hosted Sume server: do not rely on env in headers
Add the hosted Sume server to Gemini CLI with httpUrl and a bearer header. Gemini expands env vars only in the env block; set a timeout above jobs_wait.
Get the video URL from a Sume webhook: pick the artifact by type
A Sume job.completed payload lists artifacts with id, url, type and content_type. Select the video by content_type, not array index. TypeScript for Node.
Same volume every Shorts episode: gain_db, duck_db, one music bed
Sume does not measure loudness. To keep a series consistent, pin audio.gain_db, soundtrack gain_db and duck_db in one function with one bed. Python plan loop.
Live webinar captions: Sume has no streaming STT, so use chunks
MAI-Transcribe-2-Streaming is $0.54 an hour. Sume STT is $0.60, async and capped at 10 minutes a job. How to caption a webinar recording in chunks.
Make an AI voiceover louder: generation_config volume and a peak check
Sume TTS takes generation_config.volume from 0.5 to 2. Raise it, then check the WAV peak in Python so you never ship a clipped voiceover.
Nearest supported aspect ratio per Sume image model, in Python
A model rejects an aspect ratio it does not list. Read the catalog, pick the closest ratio it accepts, generate, then crop to the exact shape you need.
One API key for Seedance 2.5, Wan 3.0, Kling 3 and MiniMax H3
Do you need a ByteDance, Alibaba, Kuaishou and MiniMax account to call their video models? On Sume one key and one wallet cover all four. How it works.
One 6-minute b-roll, twelve Shorts episodes: source_in offsets
Slice one imported b-roll into twelve non-repeating 30-second episode backgrounds with Timeline 1.0 source_in, and plan the whole season unbilled in Python.
opencode remote MCP entry for Sume: env syntax and a longer timeout
The hosted Sume server in opencode.json: type remote, a bearer header from an env variable, a timeout above jobs_wait's 55 s cap. Checked by a script.
Python exceptions for Sume errors: retry on the class, not the status
Map the Sume error envelope code to two exception classes, Retryable and Fatal, so one except clause drives retries. Covers 409, 429, 402 and 503.
Python: run one prompt on four AI video models and save the clips
A Python script that sends one prompt to Wan 3.0, Seedance 2.5, Kling 3 and MiniMax H3 on Sume, polls all four jobs and saves each MP4, with costs.
Read Sume TTS raw PCM in Python: f32le samples at 24 kHz
Ask the TTS Router for container raw, 24000 Hz and pcm_f32le, then load the samples with the standard library for DSP or a custom player.
Save a Sume artifact atomically: write a .part file, then rename
A half-written MP4 that looks finished is worse than none. Download a Sume artifact to a .part file, check the length, rename once. Tested in Python.
Seedance 2.5 job failed: refund, new idempotency key, and rerun cost
A failed Seedance 2.5 job is refunded on Sume. Retry with a new Idempotency-Key; the old one replays the failed job. A Python handler and the rerun cost.
Low-latency TTS without streaming: one job per sentence
Sume TTS has no streaming. To start playback early, split the script by sentence, submit the jobs in parallel and play each file as it finishes, in order.
Shortest and longest values Sume accepts for a Short: one table
Minimum clip, slot, spine and fade values and the maximums for trim, transitions and soundtrack on Sume, in one table with an offline slot checker in Python.
Shorts season webhooks: a Python receiver that counts episodes
Receive Sume job webhooks for a season of Shorts renders: verify sume-v1, reject an empty secret, de-dupe by job_id, and know when every episode is terminal.
Sora API gone: 9:16 portrait video on Sume, model by model
Which Sume video models return 9:16 after the Sora API ended on 2026-09-24, how to ask for it, and a script that reads the catalog instead of trusting a table.
Parse a Sume video poll response with a dataclass, no network
A stdlib Python dataclass for the /v1/videos poll response (status, unsigned_urls, usage.cost, error), tested on sample JSON so a ported client fails early.
Export old video prompts to JSONL, then re-render on Sume resumably
A prompt manifest for a Sora back catalog: one JSON line per clip with a stable idempotency key and status, and a runnable script that skips what is done.
Photo to video on Sume: frame_images or input_references?
Which Sume video field starts from your photo and which only guides style. If you send both, frame_images wins. Two request bodies and a check you can run.
Score a Sora replacement: five numbers to log for every clip
Before you cut over from Sora to a Sume video model, log five numbers per clip: status, wall time, usage.cost, duration asked and failures. Script included.