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
A Sume webhook receiver in plain Python WSGI, no framework
A 28-line wsgiref app that reads the raw body, verifies sume-v1 with a rotation-safe check, refuses an empty secret, and answers 204. Tested with curl.
One Sume webhook route for job and run events, 204 on the rest
Route job.* and *.run.terminal events from one verified webhook handler and answer 204 for any unknown event, so a new type cannot trigger retries.
urllib3 Retry on POST: retry a Sume submit only with a key
A urllib3 Retry config that retries 429, 502, 503 and 504 on a Sume submit, and a wrapper that refuses to send a POST without an Idempotency-Key.
Validate a Gemini Omni Flash 1.1 request in Python before sending
A 28-line Python check for Sume's gemini-omni-flash-1.1 rules: 3-10 s, 10 reference images, 3 reference videos, no audio off, and edit mode exclusions.
Verify a Sume Format webhook in Python: empty secret, stale timestamp
A Python check for the Sume format.run.terminal webhook: HMAC-SHA256 over timestamp.raw_body, a 5-minute window, and a refusal to run with an empty secret.
Sume video models by aspect ratio: who takes 9:16, 21:9 and 1:1
Seedance takes 21:9 through 9:16, Kling only 16:9, 9:16 and 1:1, Gemini Omni only 16:9 and 9:16. Full matrix of Sume video models as of 2026-10-08.
AI video API with audio reference input: which Sume models accept it
Seedance (all four), Wan 3.0, MiniMax H3 and H3 Max accept audio references on Sume. Kling, Gemini Omni, Grok Imagine and the motion models do not.
Vidu Q4 or LTX on Sume? Check the video model list first
Sume does not list Vidu or LTX in its video catalog as of 2026-10-08. Query GET /v1/videos/models and filter by id; a short script and the 12 ids it returns.
Wan 3.0 reference limits on Sume: 10 images, 5 videos, 5 audio clips
Wan 3.0 on Sume takes up to 10 reference images, 5 reference videos (15 s total, 16 fps or more) and 5 audio clips (15 s total). Here is the full envelope.
How many Sume image rows list mask, background, quality, resolution
mask_url and background list on GPT Image 2.5 only, quality on three row types, resolution on a handful. A count of catalog rows by parameter, with a script.
Cancel every queued Sume job without cancelling a running one
A Python script that lists queued jobs, checks the cancelable flag, posts the cancel, and handles 409 job_generation_already_started when the race is lost.
Check a webhook URL before you give it to Sume: https and public
Sume rejects localhost, private-network and non-HTTPS webhook URLs. A Python preflight that catches all three, and the 2048-character limit, before you submit.
Group failed Sume jobs by error category with curl and jq
One curl and jq command that lists the last 100 failed jobs, groups them by error.category, code and retryable, and prints a sample job id for each group.
Hy Image 3.5 Preview returns base64 PNG; Sume returns a URL
Moving image code from a base64 PNG response (Hy Image 3.5 Preview on OpenRouter) to Sume means downloading data[].url. A 12-line Python version.
Image 1.0 defaults to low quality; GPT Image 2.5 defaults to high
Same prompt, two Sume routes, two defaults: Image 1.0 omits quality as low, POST /v1/images with GPT Image 2.5 omits it as high. Set quality in both.
Image 1.0 to POST /v1/images: image_urls becomes input_references
Move a Sume Image 1.0 request to POST /v1/images: image_urls to input_references, mask_image_url to mask_url, num_images to n, plus new defaults.
List Sume jobs for one run_id and count them by status (curl and jq)
GET /v1/jobs filters by run_id, scope and status and returns up to 100 rows. A short curl and jq script gives a count per status for one run.
Pick the cheapest Video Router model from the live catalog
Read GET /v1/video-router/models, filter by resolution, duration and capability, and rank by list x 1.25 in integer micros. Node code with an offline test.
Poll a Sume image job in Python: obey next_poll_after_seconds
When POST /v1/images returns 202, keep polling the status_url and sleep for next_poll_after_seconds. A short Python loop that stops on a terminal status.
Smallest square GPT Image 2.5 accepts on Sume: 816x816
A small icon request fails at 800x800 on GPT Image 2.5: under 655,360 pixels. 810x810 fails the 16 rule. 816x816 is the smallest legal square.
Sume image n: docs say up to 10, every catalog row says 4 or less
The Image API docs say n is 1 to 10, but each catalog row publishes its own ceiling: 4 on most, 1 on Grok Imagine. Cost is cost_usd times n. Table with prices.
Sume submit: request_id is the job id you poll (curl, jq)
After an async submit, data.request_id is the id for GET /v1/jobs/:id. error.request_id is for support tickets. A curl and jq check.
Tall 1:3 strip on GPT Image 2.5: 1280x3840 passes, 1280x3856 fails
A tall scroll strip on Sume's GPT Image 2.5 can be 1:3 at most. 1280x3840 is exact and legal; one more row of 16 pixels breaks the 3:1 rule.
Verify a Sume image webhook in Python, then read artifacts[]
A 23-line Python verifier for Sume's x-sume-webhook-signature header on an image job: refuses an empty secret, checks a 5-minute window, reads the image URL.
verifyWebhook toleranceSeconds 0 turns off the Sume replay check
In @sume-com/sdk, toleranceSeconds defaults to 300 and 0 skips the timestamp check. A runnable test shows an hour-old signed delivery passing only at 0.
Check your Sume webhook secret at boot: 64 hex and a match
A Node startup check for a Sume webhook receiver: the secret must be 64 hex characters, non-empty, and equal to GET /v1/webhooks/signing-secret.
A 12-second webhook handler times out at 10 s: dedupe Sume deliveries
Sume gives each webhook attempt 10 seconds and retries up to 10 times. A 12 s handler gets repeats. Verify, store job_id once, and return 2xx early.
A/B a Format run on Haiku 5.5 and Astra: use different keys
Same Idempotency-Key with a different body is a 409 on Sume. When the model field changes, derive the key from the body. A Python sketch that does.
Find the six removed Sora identifiers in your repo, then move to Sume
OpenAI's removal list names the Videos API and five model ids, all dated 2026-09-24. A runnable repo scan finds them, and what changes on Sume's /v1/videos.
Kling motion control: send image_url or avatar_handle, not both
Sume's Kling 3.0 Motion Control takes exactly one visual source: image_url or an avatar_id/avatar_handle. A short Python check before the $0.1575/s submit.
Kling motion control on Sume: keep_original_sound and orientation
Two optional Kling motion control fields on Sume: keep_original_sound defaults to true and character_orientation defaults to video, or image.
Omni Flash references: 10 images, 3 clips of 3 s, 9 s of footage
Gemini Omni Flash 1.1 on Sume takes up to 10 reference images and 3 reference clips of 3 s each (9 s of footage), with no audio reference. Cost: $1.00 for 8 s.
A Preview video model in production: pin a Sume id or use sume/auto?
Vidu calls Q4 a Preview. On Sume, pin a model id for a repeatable look, or use sume/auto, which hides the family and defaults to 720p and 8 seconds.
Python: chain generate, cutout and upscale with one polling helper
One Python helper submits any Sume job with mode async, polls status until terminal, and returns the artifact URL. Three calls chain image, RMBG and upscale.
Reconcile a mixed project with GET /v1/usage: debited, held, refunded
How to read what one job or run really cost: debited, held and refunded fields, with the arithmetic for a project where one of six shots fails and is refunded.
Replace line 7 of 12 voiceover lines: one TTS job and a concat
Fixing one 180-character line of a 12-line voiceover costs $0.02 (one TTS job at the 1-cent floor plus a $0.01 concat) vs $0.12 to redo all 12. Read 2026-10-08.
Silent 11-second b-roll: Omni rejects generate_audio false
Gemini Omni Flash 1.1 on Sume always has audio and rejects generate_audio false, and stops at 10 s anyway. For 11 s of b-roll, Wan 3.0 at 720p is $1.375.
RMBG, image upscale and video upscale request fields side by side
The three Sume media tools take different bodies: image_url, upscale_factor 1-4, video_url, duration_seconds 1-30, enhancement_tier. One table, prices included.
Sume run webhook: 10 s timeout, so queue before you call a slow model
Sume gives your webhook 10 seconds per attempt, up to 10 attempts. Verify the signature, store the event, return 2xx, then call any slow model. Python verifier.
MAI-Voice-2.1 audio in a Sume Timeline: 9 clips, 261 s
Sume does not list MAI-Voice. To use its audio in a Timeline, import the files, concat at $0.01, render 261 s as 5 minutes ($0.50). Read 2026-10-08.
Write the Lyria brief from your shot list: a Python timestamp builder
Lyria responds to [m:ss-m:ss] section markers. A short Python script turns a 6-shot, 59-second shot list into a brief under the 5000-character limit.
Count TTS characters first: Sume counts spaces and punctuation
Sume TTS bills every character including spaces and punctuation, up to 20,000 per request. A runnable Python counter prices a script on Sume and MAI.
Eight market beds in parallel: asyncio, one idempotency key each
Eight Music Router jobs with one Idempotency-Key per market and a metadata tag cost $1.00 and survive a retry without a second charge. A runnable Python script.
Mistral Large 4 preview as your orchestrator, Sume as the renderer
Sume does not list Mistral Large 4. Let it plan in your own code and hand each video task to a Sume Agent Completion; Python sample with the required cap.
H3 Max Recast prompt: 2,000 characters, and the fields Sume rejects
The optional Recast prompt is capped at 2,000 characters, and aspect_ratio, generate_audio and frame fields are refused. A checker to run before a paid submit.
Retry cost of a mixed project: what a failed shot, 402 and replay bill
Six failure cases for an image, voice, music, video and render project, with the cost of the retry for each and the one mistake that pays for everything twice.
RMBG or upscale fails: image_not_fetchable and the HTTPS fix list
Sume cutout and upscale jobs need a public HTTPS image_url of at most 2,048 characters. Fix list for image_not_fetchable, 400 on model, 402 and 429 errors.
Same image as first and last frame: a 6-second loop on three models
A 6 s loop with one image as both first and last frame costs $2.27 on Seedance 2.0 at 720p, $0.60 on H3 Max at 768p and $0.75 on Omni at 720p.