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
Check a reference image URL before sending it to Sume Images
Sume rejects localhost, private-network and non-HTTPS reference URLs before submission. A short Python pre-flight check that catches them first.
Does MiniMax H3 have an API? Three endpoints, or one route on Sume
Yes. MiniMax lists three Open Platform endpoints for H3: create, h3-context-ir and regeneration. Sume wraps H3 in one async video route, minimax-h3.
/v1/videos size returns 400: send resolution and aspect_ratio
Every v1 Sume video model reports supported_sizes null, so a size field gets 400 unsupported_parameter. Send resolution and aspect_ratio; where to read values.
SQLite: add a sume_job_id column to rows that used sora-2 snapshots
OpenAI removed the Videos API and every sora-2 snapshot on Sept 24, 2026. A migration that tags old rows, then re-renders each once through Sume.
Wan 3.0 API rate limit: 300 RPM on Model Studio vs Sume jobs
Alibaba lists 300 requests per minute for Wan 3.0 on Model Studio. Here is what that means for a batch, and how Sume submits Wan 3.0 as async jobs.
GPT Image 2.5 banner: 3840x1280 passes the 3:1 rule
3840x1280 is exactly 3:1, both edges are multiples of 16 and it is 4,915,200 pixels, so Sume accepts it on GPT Image 2.5. The four checks shown.
Nano Banana 2.1 on Sume in Python: handle the 200 and 202 replies
Call google/nano-banana-2.1 on Sume's /v1/images in Python and handle both the 200 image reply and the 202 job envelope, with polling to the result URL.
curl and jq: count Sume jobs by status in one command
GET /v1/jobs with limit=100 piped into jq group_by prints how many jobs are queued, processing, failed and so on, and warns when next_cursor says more.
Go httptest: a four-case table test for a Sume webhook handler
Sign a fixture body with sume-v1 HMAC, then assert 204 for a valid call and 401 for a stale timestamp, an empty server secret and a wrong secret.
Claude Code allowedMcpServers: the serverUrl rule for mcp.sume.com
Allow only Sume's hosted MCP endpoint in Claude Code managed settings with an allowedMcpServers serverUrl entry, and what the rule does not control.
Image API n: 10 per call in the schema, lower for each model
The Sume Image API schema allows n from 1 to 10, but each model lists its own n range. How to read the ceiling and what you pay for n images.
Python asyncio.Semaphore sized to a Sume plan's job capacity
Free holds 6 paid jobs at once, Pro 24, Startup 48, Scale 120. A Semaphore of that size keeps a 60-job batch from hitting 429 queue_full.
Node: flip a video backend to Sume a day before the Veo 3.1 shutdown
Google ends three Veo 3.1 preview ids on Oct 22 and its page gives a date, not an hour. A 19-line Node switch moves traffic to Sume early, with an override.
Image API 200 or 202: branch on the status code, not the body
POST /v1/images returns images with 200 or a job envelope with 202. A small Python handler that branches on the code and prints the URLs to poll.
Image 1.0 is retiring and its URLs point at Auto: what to change
Sume says Image 1.0 retires soon and its public URLs are compatibility aliases for the Auto pipe. The three edits for a client that still calls /v1/image-1.0.
TypeScript SDK: createVideoGeneration, then poll for 'cancelled'
The @sume-com/sdk video functions return {data, error, response} and never throw. An 18-line loop passes an Idempotency-Key and handles the British spelling.
Gemini 3.8 Flash TTS takes 8,192 input tokens: splitting a long script
Gemini 3.8 Flash TTS lists 8,192 input tokens and 16,384 output tokens. Sume TTS takes 20,000 characters per job. Here is how to split a long script.
MCP outputSchema vs Sume output_schema: who sets the contract
In MCP the server declares a tool's outputSchema. In a Sume Agent Completion you send output_schema per run, and the result can still come back degraded.
claude mcp add --header Bearer: a Sume API key for CI runs
For unattended Claude Code runs, pass a Sume API key as a Bearer header. That session sees every tool, so cap spend and send idempotency keys.
Codex 0.160.1 remote stdio MCP fix: does it affect Sume?
Codex 0.160.1 preserves SYSTEMROOT, TEMP and TMP for remote stdio MCP launches on Windows hosts. Sume's hosted MCP is HTTP, so no process is launched.
Go: a context timeout stops waiting on a Sume job, not the job
context.WithTimeout cancels your status read, never the generation. A 29-line Go loop shows the DeadlineExceeded branch, and why the job id must be stored.
Claude Code MCP scope: local, project or user for the Sume server
Use project scope for a shared .mcp.json with the Sume URL only, user scope for your own machine, and keep API keys out of shared files.
Sume run webhook: two request_ids, which one to dedupe on
Dedupe a Sume run webhook on the envelope request_id, which equals run_id and is stable across retries. Ignore payload.request_id, a correlation id.
Python: check Omni Flash 1.1 limits against /v1/videos/models first
Google's Omni runs a sync call and extends in 10-second steps up to 40 seconds. Sume's gemini-omni-flash-1.1 takes 3 to 10 seconds per job. A preflight check.
After imagen-4.0-generate-001: read n from endpoints, use webhook mode
Do not assume your old image count carries over. Read supported_parameters.n from the Sume endpoints route, then submit in webhook mode and wait for.
Go: poll a Sume job and stop on any terminal state, even a new one
A Go status loop that names completed, failed and canceled, stops on terminal=true for anything else, and never sleeps less than next_poll_after_seconds.
HappyHorse 1.1 takes a seed on Cloudflare; Sume video models do not
Cloudflare's HappyHorse 1.1 accepts a seed up to 2,147,483,647 and an optional watermark. No Sume v1 video model accepts a seed; here is the workaround.
sume/auto is missing from GET /v1/images/models: hardcode it
Sume Image Router Auto never appears in the model list. Discovery code that only reads GET /v1/images/models will never offer sume/auto. How to handle it.
TTS output formats: Gemini 24 kHz WAV vs Sume 44.1 kHz MP3 default
Gemini 3.8 TTS returns 24 kHz mono 16-bit WAV, or headerless L16 when streaming. Sume TTS defaults to 44.1 kHz 128 kbps MP3 and offers WAV and raw options.
Ruby Net::HTTP: POST /v1/videos with callback_url, for a Sora port
A 15-line Net::HTTP submit for /v1/videos that sends an HTTPS callback_url and an Idempotency-Key, checks for 202, and stores the id before any callback.
A lost response on a 30 s Kling motion control submit: reuse the key
If a network timeout hides the reply to a 30-second Kling motion control submit, a new Idempotency-Key reserves $4.725 again. Reuse the key. Python retry loop.
How long do 100 AI video clips take? Concurrency slots by plan
100 jobs take ceil(100 / slots) waves: 100 on Free, 25 on Pro, 13 on Startup, 5 on Scale. Multiply by one job's time. Math and a runnable snippet.
frame_images and input_references together: frame_images wins
Send both and Sume runs image-to-video, not reference-to-video. How to pick one field per request and check the model's catalog entry first.
Gemini TTS streams raw PCM; Sume returns a finished wav or raw file
Gemini 3.8 Flash TTS streams headerless audio/l16 at 24 kHz. Sume returns a hosted file from an async job. Wrap the PCM in WAV and match the formats.
Image burst after a model launch: 429 queue_full vs 503 retry plan
Launch week means batches. On Sume, 429 rate_limited, 429 queue_full and 503 provider_capacity_exceeded each need a different retry, plus idempotency keys.
image_size, aspect_ratio or size: which field wins on Sume
Sume's image API has three size fields. image_size beats aspect_ratio, size takes only a tier, and 4:5 is 1080x1350 portrait. Examples for GPT and Nano Banana.
List Sume image models that take references or masks with jq
New image models land weekly. One curl and one jq filter on GET /v1/images/models show which ids accept input_references, mask_url or background, and how many.
Music 1.0 is retiring: keep old calls, move new code to the router
Sume Music 1.0 routes still work and keep job.model sume/music-1.0, but every request now resolves through the Music Router. What to change and when.
Next.js route handler: submit a Seedance 2.5 job, keep the key private
Keep your Sume API key on the server: a Next.js route handler that submits a seedance-2.5 job and returns the job id, plus a second route that polls it.
No-code HTTP step: submit a Wan 3.0 job and get a callback_url
Any automation tool with an HTTP request step and a webhook trigger can run wan-3.0 on Sume. The request body, the HTTPS callback_url, and what to store.
Port a Kling 3 request to Sume motion control: three fields to remove
Sume Kling 3.0 Motion Control has a strict body. Moving from a Video Router kling-3 request means dropping model and reference urls and adding two fields.
Can I submit 100 AI video jobs at once? Queue limits by plan
Accepted capacity is slots plus queue: 6 on Free, 24 on Pro, 48 on Startup, 120 on Scale. Submit 100 at once and 94, 76, 52 or 0 get 429 queue_full.
Ruby Net::HTTP: submit a Wan 3.0 video job and poll until it finishes
A standard-library Ruby script that posts to /v1/videos with wan-3.0, polls the polling_url every 30 seconds and stops on completed, failed or cancelled.
Retry or fix? A status-code policy for Sume API clients in Python
Retry 429 and 503 with the same idempotency key; never retry 400, 401, 402 or 404. A small Python policy function, tested, with the Sume docs rules behind it.
Sume job webhooks: 10 attempts, 30 seconds apart, at least 270 s
Ten attempts with a fixed 30-second gap cover at least 270 seconds. What that means for your deploys, cold starts and when to fall back to polling a Sume job.
Voice note to SRT in Python with Sume STT sentence segments
Submit a voice note to Sume STT with sentence segmentation, poll the job, and write an SRT file from segments[]. Runnable Python with asyncio.run.
Validate clip length against supported_durations before a Sume submit
Durations differ by model: some start at 2 seconds, some stop at 10, some reach 30. Read supported_durations from the catalog and snap a request in Python.
waitForJob polls every 2 s: 600 reads in a 20-minute Sume video job
The SDK's waitForJob floor is a 2-second poll and a 20-minute timeout: at most 600 reads per job. The read budget by plan and why next_poll_after_seconds wins.