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
Nine 20 s voice files, one 180 s spine: Timeline audio.parts
Join nine 20-second voice files into a 180 s Short spine with Timeline 1.0 audio.parts (up to 20 slices, gapless, no re-TTS) for $0.30 inside one render.
Pin Gemini Omni Flash 1.1 or send sume/auto: six checks
sume/auto picks the model for video and defaults to 720p and 8 s. Pin gemini-omni-flash-1.1 when you need edit mode, 4K or fixed references. A decision table.
Python check: is this MP4 over TikTok's 516 kbps? Size and duration
A short Python function turns file bytes and duration_seconds into average kbps and tests TikTok's 516 kbps floor, 500 MB cap and 10-minute limit.
Rotate the Sume webhook secret twice in one 24-hour window: what dies
Sume signs with both secrets for 24 hours after a rotation. Rotate a second time inside that window and the secret from two rotations back stops at once.
sume/auto defaults to 720p and 8s: 250 old prompts, pinned vs Auto
With model sume/auto a request defaults to 720p and 8 seconds. Pinned, 250 such clips cost $150 to $605 on Sume. Auto does not disclose the family.
Sume CLI: --confirm-submit vs --confirm-paid, which one when
The Sume CLI gates non-paid writes with --confirm-submit and avatar creates with --confirm-paid. Reads need neither. Here is the split, with defaults to know.
job.canceled: the third Sume terminal event your handler forgets
Sume sends job.completed, job.failed and job.canceled and nothing else. A handler that covers only two leaves canceled jobs open. Route all three, 204 the rest.
Sume MCP first call: mcp_health must say mcp_oauth, then tools_list
After adding the Sume connector, call mcp_health and check authenticated.auth_source is mcp_oauth. Then call tools_list to see which tools your grant exposes.
Sume webhook status is OK or ERROR; job status is completed or failed
A Sume job webhook body says status OK or ERROR, while the job endpoints say completed, failed or canceled. Branch on the event name and map both vocabularies.
Ten Sume job error categories and which ones are worth a retry
Sume failed jobs carry a category such as validation, quota or worker_timeout. Map all ten to retry, fix, top up or support in one small Python table.
Timeline plan call: price a narrated render before you spend
POST /v1/timeline-1.0/plan is unbilled and returns billable_minutes and estimated_cost_usd_micros. How to price a narration plus music render first.
Clip-type route table in Python: Sora use cases to Sume models
A 30-line Python route table maps ads, demos and teasers to a Sume model, size and length, refuses a length the model cannot make, and prints the dollar cost.
Video trim end past the clip: trim_clamped_to_source and a short ad
If end is beyond the source, Sume video-trim clamps it and warns trim_clamped_to_source. Ask for 0-20 s of a 15 s clip and you get 15 s, which can break a spot.
wave_size_hint 450 is not concurrency: sizing Sume submit waves
With concurrency 100 and a 500-job queue, Sume shows wave_size_hint 450 but your in-flight budget is 100. How to compute both from generation_limits.
Which key scope each Sume webhook endpoint needs
Reading the signing secret needs account:read, rotating and Send test need account:write, and redelivering a job needs jobs:write. A least-privilege map.
Which Sume MCP URL? mcp.sume.com/mcp, not the dev host or Studio
Add https://mcp.sume.com/mcp as the connector. The dev host is internal, and Studio Agent is a separate product, not the hosted MCP connector.
Re-render 100 Sora prompts at 8s 720p 9:16: six Sume models priced
A 100-prompt library of 8-second 720p vertical clips costs $60.00 to $242.00 on Sume depending on the model. Exact per-clip cents and the arithmetic.
Lost video callback? Sweep pending jobs after the 10-attempt window
Sume retries a job webhook 10 times, 30 seconds apart. If none gets through, the job is still done. A 30-line sweeper that polls pending jobs recovers it.
Continue a 30 s shot: Video frames still as the next first frame
Extract a last-second still from a 30 s Sume clip with Video frames and send it as first_frame for the next shot. Price of the chain at 720p.
Derive the Idempotency-Key from a SHA-256 of the request in Python
A key built from the path and a canonical body hash makes a retry return the original Sume job and a changed prompt a new one, with no 409 to handle.
detach_source_has_no_audio: the free probe that prevents it on Sume
Sume audio detach fails with detach_source_has_no_audio on a video with no sound track. A frames-off video inspect reads probe.has_audio first. Codes inside.
Does a replayed sume/auto video submit get the same model and price?
Yes. The Sume docs say Auto resolves from the normalized request and catalog version, so an idempotent replay returns the same route and price.
Draft 100 prompts at 480p, finish 15 at 1080p: the two-pass cost
Rendering 100 prompts at 480p on seedance-2-mini and 15 keepers at 1080p on seedance-2-fast costs $152.75 on Sume, against $545.00 for all 100 at 1080p.
Edit or regenerate an Omni clip? The per-second price is the same
On Sume, Gemini Omni Flash 1.1 edit mode and a fresh generation bill the same per output second. Compare three tries of each at 720p and pick by continuity.
Recast 400 "exactly one source video and 1-4 images": five causes
The Videos API refuses an h3-max-recast request that is not one video plus 1-4 images in input_references. Five causes of that 400 and what to send instead.
Can hosted MCP run a Sume Format? Call it over REST with an API key
The hosted MCP tools-and-gates inventory lists no Format-run tool. Run Formats with POST /v1/formats/{handle}/{slug}/runs and an API key that has formats:write.
A 10-minute render needs 11 to 12 jobs_wait calls, not one long one
On hosted MCP, jobs_wait holds at most 55 seconds, default 50. A ten-minute render is 11 or 12 waits on the same job id. Never resubmit the paid create.
MiniMax H3 duration errors: at most 15 s, at least 5 s, Recast 30 s
Video Router refuses a MiniMax H3 job over 15 s or under 5 s with a named message, and Recast has its own 5-30 s rule. Messages, limits and a pre-check.
Nano Banana 2 is retired on Sume: the old id still works, as 2.1
google/nano-banana-2 and nano-banana-2 still work on Sume and run as Nano Banana 2.1. The job stores the 2.1 id, and the catalog lists only 2.1.
Omni Flash on /v1/videos vs /v1/video-router: the field map
The same Gemini Omni Flash 1.1 runs on /v1/videos and /v1/video-router/generate with different fields. Field map for frame_images, input_references, video_url.
Omni resolution values: 4K, lowercase 4k, and what is rejected
Gemini Omni Flash 1.1 on Sume takes 360p, 720p, 1080p and 4K. The catalog also accepts lowercase 4k as an alias. Which strings fail, and the price of each.
Omni video references: three clips of 3 s, so 9 s of footage at most
Gemini Omni Flash 1.1 takes up to 3 reference videos of 3 s each and 10 reference images. The tags are VIDEO_REF_0 to 2; the price is unchanged.
Poll or callback for 1,000 video jobs: request counts at 30 seconds
At a 30-second poll, 1,000 video jobs make 4,000 to 20,000 status requests by job time. A callback_url cuts that to 1,000 deliveries plus a sweep.
Polling a 5-minute video job: 150 GETs at 2 s, or 10 at 30 s
A five-minute Sume video job costs 150 status reads at a 2 s interval and 10 at 30 s. Poll /v1/videos with a loop that handles every status.
Python asyncio price check: one Omni Flash clip at four resolutions
A runnable Python script submits a 3-second Omni Flash clip at 360p, 720p, 1080p and 4K together and prints usage.cost. Expect $2.20 in total.
Recast prompt limit is 2,000 characters: what to write, what it costs
The H3 Max Recast prompt is optional and capped at 2,000 characters. See what to put in it for a person swap and why the length never changes the price on Sume.
Sume webhook retries: 10 attempts, 30 s apart, a 4.5 minute window
Sume retries a job webhook up to 10 times, 30 s apart by default. That is 270 s between first and last attempt, 370 s at worst. What to do after.
Timeline plan needs no Idempotency-Key; render does: a wrapper
POST /v1/timeline-1.0/plan is free and takes no Idempotency-Key. Render is paid and requires one. A wrapper plans first, then renders with a derived key.
Transcript from a video on Sume: inspect transcribe or detach first?
Sume can transcribe a video through video inspect (1,800 s limit, compute plus $0.01 per minute) or from a detached 16 kHz mono wav. How to choose.
verifyWebhook toleranceSeconds: 300 by default, and 0 turns replay off
In the Sume SDK, verifyWebhook rejects deliveries older than 300 seconds by default. toleranceSeconds 0 skips that check. When each setting is right.
How many minutes of speech fit in one 20,000-character TTS request?
Sume TTS caps a request at 20,000 characters. At 800 to 1,200 characters per minute that is roughly 17 to 25 minutes of audio and costs 95 cents.
Image API returned 202 after 30 seconds: a Python poll that finishes
POST /v1/images waits 30 seconds, then returns 202 with a job envelope for slow high-quality runs. A 25-line Python script that handles both 200 and 202.
Log the Sume request_id in Python JSON logs, no keys or URLs
A small logging helper for failed /v1/videos calls: keep error.code, request_id and job id, and leave out the API key and signed media URLs.
Music 1.0 or Music Router: which route for new Sume code?
Use POST /v1/music-router/generate for new code. Music 1.0 still works but resolves through the router; every router model bills the same fixed $0.125.
No progress percent on the Sume video poll: status plus elapsed time
The poll has status, not a percentage. How to build an honest progress label from pending, in_progress and elapsed seconds, with a 30-second interval.
PowerShell 7: submit, poll and save a Sume video, no SDK
A Windows-friendly script for POST /v1/videos: Idempotency-Key, a 30-second poll on polling_url, and a download from unsigned_urls[0]. Fits in 14 lines.
Python match on a Sume /v1/videos poll: five statuses, one handler
Python 3.10 structural matching on the poll dict: wait on pending and in_progress, return on completed, raise on failed or cancelled. Runs under asyncio.run.
Read back a Sume TTS job to keep the next line in the same voice
A completed Sume text_to_speech job records model_id, voice, language, output_format, generation_config and speed. Reuse them so line two matches line one.