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.
Find every Sora call left in your codebase: a retired-id scan
OpenAI's Videos API shut down 2026-09-24. A 20-line Python scan lists every file still naming a retired sora-2 model id so you can swap them.
Flask webhook receiver for Sume: verify sume-v1, refuse empty secret
A Flask route that verifies the Sume signature on the raw body, takes either rotation entry, checks the replay window, and will not boot without a secret.
Gemini Omni edit 400: aspect_ratio is not supported, framing is kept
Sending aspect_ratio with a video_url edit on gemini-omni-flash-1.1 returns a 400 on Sume. Why the output keeps the source framing and what to send.
Omni edit came back 720p: how to ask for 1080p on Sume
A gemini-omni-flash-1.1 edit defaults to 720p when you leave resolution out. Set resolution on the request; here is what the edit mode accepts.
Omni edit plus a reference image returns 400: send one or the other
Sume rejects video_url together with image or reference fields. Choose edit or reference-to-video on gemini-omni-flash-1.1, and see each field list.
Image-to-image strength or denoise: no field on Sume, do this
No strength, denoise or seed field exists on Sume's Image API; it returns 400 unsupported_parameter. How to control how far an edit moves from the reference.
A kill switch for paid Sume submits: stop new jobs, cancel queued
Add an off switch to code that spends on the Sume API: check a flag before each submit, then cancel queued jobs; a 409 job_generation_already_started will bill.
Calling the Sume API from Kotlin: no SDK, so write the poll loop
Sume publishes a TypeScript SDK and no Kotlin package. The documented submit, poll, fetch loop works from OkHttp or Ktor; the deadline lives in your client.
Per-customer spend caps on Sume: what Sume caps, what you log
A Sume key belongs to a workspace, not your end customer. Cap each run with generation_spend_cap_usd and keep a per-customer ledger yourself.
Mixed-language script: one Sume TTS request per language, then concat
A script that switches language mid-way needs one TTS request per language on Sume. Join up to 20 parts with timeline audio at $0.01.
reference_video_urls or video_url? Reference footage vs edit source
On Sume, reference_video_urls guide a new clip; video_url is a source you edit or swap. They cannot be combined on Gemini Omni Flash. Which model takes which.
Sora video ids in your database after the shutdown: what to keep
OpenAI's Videos API shut down 2026-09-24. Old video_ids no longer resolve, so store your own file URL and the model used. Schema fields included.
Speech-to-text audio too large? Sume STT takes up to 10 MB, hosted
Sume's stt_create needs a public HTTPS audio URL on the Sume media host, 10 MB at most. What fits: 16 kHz mono wav versus mp3, and how to cut a long file.
SSML in text to speech: Sume takes a plain transcript, no ssml field
Does Sume's text to speech accept SSML? The tts_create body has a plain transcript and rejects unknown keys. What to use for speed, volume, emotion and pauses.
Sume API rate limits by plan: requests per minute for writes and reads
Sume gives every API key a per-minute budget set by plan: 120 writes on Free up to 1200 on Scale, with reads at forty times the write number. Table and headers.
Client timeouts for Sume jobs: SDK defaults and the 30-second cap
Sume's sync wait caps at 30 seconds, waitForRun defaults to 10 minutes, subscribeFormatRun and waitForJob to 20. Pick a deadline per job type, keep the job id.
Choosing a Sume Idempotency-Key: business key plus a payload version
A good Idempotency-Key is stable across retries and changes with the request. Build it from your order id and a payload hash, or hit 409 idempotency_conflict.
Retry Sume 429s in TypeScript: a fetch wrapper that obeys retry-after
A small fetch wrapper for the Sume API: retry 429 only when the request is a GET or carries an Idempotency-Key, wait retry-after, and never loop on queue_full.
Sume reserve, capture, refund: what your cost ledger should mirror
Sume reserves the estimate at submit, captures it on success and releases it on failure or cancel. Mirror the three states or cost reports will double count.
Sume SDK returns {data, error}, not exceptions: an unwrap helper
Generated @sume-com/sdk operations resolve with data, error and response instead of throwing. Wrap them in an unwrap helper that throws a typed error.
Where the Sume TypeScript SDK runs: Node 18+, Bun, Deno and Workers
@sume-com/sdk has no runtime dependencies and needs only fetch and WebCrypto. Install it, create a client, and know which options and helpers it adds.
Sume video job failed: retry, new key, or switch the model?
A failed video job is final, and an Idempotency-Key replay returns the same failed job. Read the error, then retry with a new key or change models.
Sume webhooks plus a sweeper: recover jobs whose callback never came
Webhook delivery can fail after 10 attempts while the Sume job still finishes. Run a sweeper that polls jobs stuck non-terminal in your own table.
TTS word timings to burned-in captions: send them as words on Sume
Sume's TTS can return word start and end times; the caption job accepts words with text, start and end and skips transcription. How to wire them together.
Caption inputs on Sume: script_text, words, cues or segments?
Four caption inputs and only one may be sent. When to use script_text with transcription, word timings, or phrase cues for a silent clip. Plus the errors.
A video provider interface after the Sora shutdown, Sume behind it
OpenAI lists the Sora API shutdown as 2026-09-24 with no replacement. Put video generation behind one interface so the next vendor exit is a config change.
video_url 400 on Sume: edit is supported only by Omni Flash 1.1
A video_url on any other model returns 400 on the Sume Video Router. Which models take a source video, and how to pick one for your edit.
Unit-test a Sume submit-and-poll loop in Vitest with fake replies
Test a Sume polling loop without spending credits: inject the sleep, replay queued then completed replies, and assert next_poll_after_seconds is honored.
What to measure for Sume API jobs: metrics, labels and alerts
A metrics plan for code that calls the Sume API: submit outcome, queue wait, time to terminal, error code and webhook gap, with low-cardinality labels.
Which Sume API errors should page an engineer: route by category
Route Sume API failures by category: fix-the-input errors go to the caller, quota to finance, queue to a retry, and only internal or unexpected 5xx to on-call.
Crash-safe Sume submit: write the intent row and key first
If your process dies after a Sume submit but before storing the job id, a pre-written intent row and Idempotency-Key let the retry return the original job.
Teammate continues a thread: why webhook_delivery.url reads null
A Sume Agent turn reading a teammate's job sees delivery state, but webhook_delivery.url and last_error are null. Who reads which jobs, explained.
Is my avatar ready? GET /avatars with status=ready and a handle filter
Check whether one Sume avatar handle is ready before an avatar video render, using the list route's status=ready and handle query parameters in Python.
Sonnet 5.5 thinking disabled is a 400 at effort high: Sume
On Sonnet 5.5, thinking disabled is a 400 at effort high or below; use between_tools. Sume's Claude rows expose no thinking or effort fields.
Format 404 format_not_found: five causes, including a pending grant
A Sume 404 format_not_found can mean a typo, an archived Format, the wrong workspace, a team handle you are not in, or a shared Format whose grant is pending.
studio_agent_upstream_unavailable 503: retry, the run keeps going
A Sume 503 studio_agent_upstream_unavailable is a Sume-side outage: retry create with the same Idempotency-Key, and keep polling a run you already hold.
Gemini Live Translate transcripts as subtitles: you supply timing
Google's Live Translate can return input and output transcripts, but the page lists no word times. To burn subtitles, time each line, then send cues to Sume.
Image API provider.only returns 400 provider_not_available on Sume
Sume's Image API accepts provider routing fields but publishes one sume endpoint per model, so any other provider slug returns 400 provider_not_available.
Kling 3 input_references 400 unsupported_capability: fix
Sending input_references to kling-3 on Sume returns 400 unsupported_capability. Move the image to frame_images or pick a model that takes references.
last_frame without first_frame returns 400: kling-3 and Seedance fix
A frame_images list with only a last_frame is rejected with 400 unsupported_capability. Send a first_frame too; Kling 3.0 uses start and end frames only.
Luma Agents API polling: 20 s wait, 10-minute video timeout, and Sume
Luma's quickstart says wait 20 seconds, then poll, with a hard 2-minute image and 10-minute video timeout, not backoff. A matching Sume loop that actually runs.
OpenAI transcription 25 MB limit: how many minutes of wav fit?
OpenAI caps transcription uploads at 25 MB. A 16 kHz mono wav fills that in about 13 minutes, so detach long videos to mp3 or ranges first.
Prompt cache diagnostics are GA: why did my video agent miss?
Anthropic took cache diagnostics out of beta on Sep 23 and OpenAI made them GA on Sep 8. What each reports, and where Sume's run receipt fits in.
Does a queue_full 429 charge me? Sume's reservation rules
A Sume 429 queue_full means the workspace has no accepted-job capacity left. The failed admission releases its reservation; retry with the same Idempotency-Key.
subscribeFormatRun onCreated: save the run id, set your own key
subscribeFormatRun makes a new Idempotency-Key per call unless you pass one. Save the run id in onCreated and pass a stable key so a restart cannot double-run.
TikTok Display API video query: read is_aigc on 20 posts per call
TikTok's Query Videos endpoint returns is_aigc and counts for up to 20 video ids per call. Short Python audit, and where Sume fits.
TikTok oEmbed: embed a posted clip, or host the MP4 yourself?
TikTok's oEmbed endpoint turns a video URL into an embed blockquote. When that beats hosting the file, and what a Sume-made MP4 changes about the choice.
Edited a script? Reuse unchanged TTS takes with verify-spine
After a script edit, Sume's read-only verify-spine route checks which TTS takes still cover the accepted sentences, so you regenerate only what changed.