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
Convert MAI-Transcribe-2 word offsets to Sume video caption words
Turn word timings in milliseconds into the seconds-based words array Sume video-captions accepts. A short Python converter plus the 60 s and 1,200-word limits.
Deno 2.9.7 traceparent fix: tag a Sume job id in a Deno.serve log
Deno 2.9.7 extracts traceparent from Deno.serve regardless of header case. In a Sume webhook handler, log the job_id with the trace so a render is traceable.
Elixir Req: submit and poll a Sume video job after Sora
An Elixir script using Req: POST /v1/videos with an Idempotency-Key, poll every 30 seconds, stop on completed, failed or cancelled. Req never retries the POST.
FastAPI 0.142 native OpenTelemetry: tag spans with a Sume job id
FastAPI 0.142.0 added native OpenTelemetry. Put the Sume job_id on the current span in a webhook route so a failed render shows up next to the HTTP trace.
FastAPI background poll of a Sume job: use next_poll_after_seconds
Poll a Sume job from an asyncio task in a FastAPI 0.142 app, wait for the server-provided interval, stop at terminal, and never resubmit after a timeout.
Fastify: verify a Sume video webhook where Sora's video.completed was
Swap the Sora video.completed handler for Sume's job.completed in Fastify. Keep the raw string body, verify sume-v1 with the SDK, and refuse an empty secret.
Find the timestamp of a quote in a recording with Sume STT words
Sume's STT result returns every word with start and end seconds. A short Python function finds a quoted phrase and returns where to cut. About a cent a minute.
Typed Sume video client from the OpenAPI JSON, after Sora
Sume publishes OpenAPI 3.0.3 at api.sume.com/reference/json. List the four video operations, then use the SDK's generated calls instead of hand-typing the wire.
Hono 4.13.10 split adapters: update a Sume webhook receiver
Hono 4.13.10 moved adapters to @hono/bun, @hono/deno and @hono/cloudflare-workers. The Sume verifyWebhook call needs no change; only the entrypoint imports do.
Hono 4.13.13 deprecates app.mount(): mount a Sume webhook sub-app
Hono 4.13.13 deprecates app.mount() in favor of Mount Middleware. A Sume webhook receiver written as a Hono sub-app uses app.route() and keeps its raw body.
Jupyter: move Sora cells to Sume, where a cell rerun is a retry
Re-running a notebook cell resubmits the request. Hold one Idempotency-Key per take in a variable so Sume returns the first video job, and show the file inline.
Kotlin: submit and poll a Sume video job with java.net.http
A Kotlin port of a Sora videos call: POST /v1/videos with an Idempotency-Key, poll every 30 seconds until done, with the JDK client and kotlinx.serialization.
Modal 1.6.1 endpoint logs and stats: debug a Sume webhook receiver
Modal 1.6.1 adds modal endpoint info, stats and logs. Use them to see why a Sume job webhook got a 401 or a timeout, and check the 150 s web timeout first.
Nano Banana 2.1 PDF and video grounding: Sume takes image URLs
fal's Nano Banana 2.1 Edit page lists video and PDF grounding. Sume's Image API takes public HTTPS image URLs only, so render pages first.
Next.js 16.4 Cache Components: will a Sume webhook route break?
Next.js 16.4 turns on Cache Components in create-next-app. A POST route handler is never cached, so a Sume webhook route works if it reads the raw body.
Next.js 16.4 GET route handler: poll a Sume job at request time
With Cache Components, Next.js 16.4 runs GET handlers at request time. A Sume job status route stays live if it sends no-store and follows the poll hint.
Replace videos.create_and_poll with a requests helper on Sume
The OpenAI Python SDK's create_and_poll and download_content have no Sume twin. Here is a 25-line requests helper with the same call shape and a safe retry key.
OpenRouter video client on Sume: swap the base URL, change webhooks
A client written for OpenRouter /videos works on Sume after you change the base URL, key and model ids. The webhook body and signature are different.
Pointing the OpenAI SDK at api.sume.com: why Sora calls still fail
Changing only the base URL does not carry a Sora call to Sume. Five documented differences: model ids, body format, seconds and size, status words, download.
Polling Omni jobs can't 429 your submits on Sume
Sume gives each API key separate read and write budgets: 120 writes and 4,800 reads a minute on Free, 1,200 and 48,000 on Scale. The math for an Omni batch.
Railway closes idle HTTP at 5 minutes: why Sume sync waits 30 s
Railway keeps a request open up to 15 minutes only while data moves. Sume sync mode caps the wait at 30 seconds, so long video jobs need async or a webhook.
Worker crashed mid-poll: list Sume jobs and join on idempotency_key
After a restart, GET /v1/jobs?status=processing lists your in-flight video jobs. Each row carries the idempotency_key you sent, so match your records on it.
Sora download_content vs Sume /content: the 302 and two 409 errors
OpenAI's content endpoint took variant=video, thumbnail or spritesheet. Sume's /content redirects with a 302 and returns two different 409s. How to branch.
Sora input_reference image: upload with uploadFile, use frame_images
OpenAI took the first-frame image as multipart input_reference. Sume wants an HTTPS URL: upload with the SDK's uploadFile, then pass it as frame_images.
Sora jobs in flight at shutdown: reconcile, then resubmit to Sume
OpenAI's page gives the removal date but not in-flight jobs. Mark every unfinished Sora row, then resubmit its prompt to Sume with a key built from the old id.
Measure your own render time on Sume from job event timestamps
No published Sora timing carries over. Read GET /v1/jobs/{id}/events, diff created, started and completed, and keep your own queue and render split per model.
Sora to Sume pull request review: eight lines to check before merge
A reviewer's checklist for a Sora-to-Sume PR: duration and resolution types, status words, the 302 download, the webhook body, idempotency and removed fields.
Sora API gone: port to Sume with Python urllib, no extra packages
Replace the OpenAI videos calls with a stdlib-only Python script: submit to Sume /v1/videos, poll, then fetch the 302 artifact URL without sending your key.
Speech-to-text for short voice notes: one request, sync mode
Send a voice note's public URL to Sume STT with mode sync and a 30-second wait. A cent per minute, plus the poll fallback when the job outlasts the wait.
Streamlit Sora demo: switch to Sume and st.video, no double billing
Streamlit reruns your script on every click. Derive the Sume Idempotency-Key from the prompt so a rerun returns the first job, then show the clip with st.video.
sume/auto and idempotent retries: same price, same route on replay
New video models land weekly. With model sume/auto and an Idempotency-Key, a retry of a Sume video submit gets the original job, price and route.
Cancel a Sume bulk run: no queue endpoint, so cancel each child
Sume has no public cancel for a bulk queue. Poll the queue, then POST /v1/format-runs/{run_id}/cancel for each running child. fal cancels one request with PUT.
Resume a bulk run after a crash: replay the Idempotency-Key
If your client dies after POSTing a 100-item bulk run, replay the same key and same body: Sume returns 202 with the original queue. A new body gets 409.
Sume Image API 400 unsupported_parameter: which field fails where
Which Sume image models list quality, resolution, mask_url, background, output_format and references, and which never do (seed, stream). Plus a check script.
result_ready vs terminal vs completed: gate the Sume result fetch
Poll a Sume job until terminal, fetch the result only when result_ready is true. Failed and canceled jobs answer 409 job_not_completed on /result.
Sume TTS word timestamps to caption cues for a narrated 60-second clip
Ask Sume TTS for timestamps.words, group them into cues and send them to video-captions so no recognition runs. About 25 cents for a 60-second narration.
Webhook endpoint down: redeliver a Sume video job after the retries
Sume retries a job webhook 10 times, 30 seconds apart. If your receiver was down longer, POST /v1/jobs/{id}/webhook/redeliver re-sends the terminal payload.
waitForJob times out at 20 minutes: why it does not fit a Vercel route
Sume SDK waitForJob waits 20 minutes by default and the job keeps billing if it throws. Vercel functions default to 300 s, so wait in a worker.
Sume wave_size_hint and a Worker subrequest limit: submit in waves
A Worker fan-out of Sume jobs hits 50 subrequests on Free. Size each wave from generation_limits, not from the hint alone, and stop at queue_capacity_remaining.
Turn a roleplay debrief into an avatar feedback clip in Python
Take the written debrief from a roleplay or survey session and render it as a 16:9 Sume avatar clip with a retry-safe key, a 12 to 168 word check and polling.
Vercel 800 s max duration: do you still need a Sume webhook?
Vercel Pro allows 800 s functions and a 30-minute beta. A Sume video job can still outlast one request, so use async or webhook mode and return in seconds.
Webhook signature mismatch: Sume fingerprint vs OpenRouter t=,v1=
A video webhook that fails verification has three usual causes: parsed body, wrong secret, wrong header format. Sume adds a secret fingerprint header.
Test a video webhook receiver before the first job: Sume vs fal
Sume sends a signed dummy webhook.test with one API call. fal retries real results up to 31 times and treats 3xx as failure, so test your URL first.
Extract 16 kHz mono audio from a video for transcription
A Python script that detaches speech-ready 16 kHz mono wav from a Sume-hosted video, then polls the job. Costs $0.01 per detach before the STT minute.
Assemble a three-clip montage with fades through the Sume API
A working Timeline 1.0 request that joins three hosted clips over one audio spine with fade and dissolve transitions, plus the Python to poll it, for $0.10.
Go: net/http client for a 30-second Wan 3.0 clip, 30 lines
A 30-line Go program using only the standard library: submit wan-3.0 for 30 seconds, poll the job, write clip.mp4. Reserve and per-second rate included.
Pre-flight an Omni Flash request against the Sume model catalog
A short Python check that reads supported durations, resolutions and aspect ratios for gemini-omni-flash-1.1 via /v1/videos/models.
Video upscale hold: omit duration_seconds and Sume reserves 5 s
Sume video upscale reserves from duration_seconds, or 5 seconds when you omit it. Hold table for 5, 15 and 30 seconds at $0.009 per second and the 402 case.