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.
Which Sume API routes work without an API key?
Only health, catalog, openapi.json and the three bgm routes work without a key. Every other /v1 route needs a Bearer or x-api-key credential, never both.
fal retries failed requests up to 10 times; on Sume the retry is yours
fal's queue retries transient errors up to 10 times unless you send X-Fal-No-Retry. On Sume the retry is yours: reuse the Idempotency-Key, never resubmit blind.
fal never drops queued requests; Sume can answer 429 queue_full
fal's queue docs say queued requests are never dropped. Sume caps accepted jobs per plan and returns 429 queue_full when full. Plan for the gap.
OpenRouter puts an idempotency key on video webhooks; Sume uses job_id
OpenRouter's video guide adds an idempotency key header to each delivery. Sume dedupes on job_id and takes Idempotency-Key on submit. Which key goes where.
Size a batch from generation_limits so no clip hits queue_full
Read accepted_generation_jobs_limit from a Sume submit response and slice your clips. A 50-clip batch leaves 2 for a later wave on Startup and 26 on Pro.
Webhook events arrive out of order: Sume sends one event per job
Stripe does not guarantee event order. Sume job webhooks send terminal events only, so key on job_id, dedupe, and poll status when a callback never arrives.
Griffin 10 ms audio packets vs Sume TTS: async jobs, no streaming
Tavus Griffin emits speech in packets as small as 10 ms. Sume's TTS Router lists streaming TTS as a non-goal, so audio arrives as a finished file for lip sync.
How long does AI lip sync take? fal says about a minute at 1080p
fal says a 1080p H3 Max lip-sync clip takes about a minute. On Sume the call is an async job, so poll with backoff. This Python example submits and polls.
LiveKit avatar join latency and playback latency: what to measure
LiveKit avatar plugins emit join latency and playback latency. Learn what each means before you pick a live avatar, and what a rendered clip has instead.
LiveKit avatar providers with Node.js support vs a Sume Node job
LiveKit lists eight avatar providers with Node.js plugins and eight Python-only ones. For a clip rather than a live room, Sume works from Node with fetch.
Timeline refuses a 180-second Short: clips end more than 0.5 s early
Timeline 1.0 allows video coverage to stop at most 0.5 seconds before the end of the audio spine. Check slot ends in Python before you plan a 180-second Short.
Nova 2 Sonic cut hallucinations 88%: run a read-back check on Sume
AWS says its May Nova 2 Sonic refresh cut hallucinations 88% on an internal set. Test any voice on your own text: Sume TTS, then STT, then a diff.
Entity error 14.41%? Score your own call audio with Sume STT in Python
AssemblyAI reports 14.41% entity error on voice-agent audio and 3.44% English WER. Neither is yours. Compute entity recall on 20 of your clips with Sume STT.
AssemblyAI word boost cuts name errors 61%: a term map for Sume STT
AssemblyAI reports word boost cut entity errors 60.9% on names and 72.8% on technical terms. Sume STT has no boost field; here is a post-correction map.
Does the previous agent turn help transcription? AssemblyAI says 4.3%
AssemblyAI reports agent context cut entity error from 16.04% to 15.35%, a 4.3% relative drop. Sume STT has no context field; here is a fair test.
Fallback chain for a 30-second AI video: first catalog row that fits
Kling 4.0 is rolling out in stages. Pick the first Sume video id whose catalog row lists 30 seconds, and stop with an error if none does.
Route a Kling video job in Python: scene, motion clip or 30 seconds
A small Python router for Sume: performance copies go to Kling motion control, 4-15 s scenes to kling-3, and longer jobs to a catalog id that lists 30 s.
Retry a Kling motion control submit without paying twice
All four Sume motion-control routes take an Idempotency-Key. Resend the same body and key after a timeout and you get the original job, not a second reserve.
video_inspect: fps 2 and a 24-still cap cover only 12 seconds
At fps 2 video_inspect's 24-still cap covers 12 seconds. Pick fps or explicit at[] times by clip length; a table of coverage from 12 s to 96 s per call.
video_inspect seek fast vs precise: a quick look with keyframe stills
seek: fast moves each still to the keyframe at or before its instant and skips the decode. Use it for a quick look; precise when timing matters.
Agent Completion result: read output.videos, images, audio and files
A completed Agent Completion puts its last text in output.text and generated media in output.images, videos, audio and files, as durable media.sume.com URLs.
catalog_list vs tools_list: finding HTTP-only Sume features
tools_list shows what this MCP session can call. catalog_list shows API capabilities, some with no MCP tool. Read both before telling a user it can't be done.
Agent run webhook: created_at orders deliveries, request_id dedupes
An agent.run.terminal delivery has two ids that look alike. request_id dedupes retries; created_at orders deliveries. Includes a Python receiver.
Run webhook payload is null: payload_too_large means fetch result_url
Sume cannot send a receipt over 1 MiB inline. The webhook arrives with payload null and error.code payload_too_large. The run did not fail. Fetch result_url.
Build an AI image progress UI: gate on supports_streaming false
Sume's image catalog reports supports_streaming false on every row. Build the progress UI from job states and gate a live preview on that field.
Claude Agent SDK init message: check the Sume server status first
Read the init message's mcp_servers statuses before a paid Sume call. failed and needs-auth mean the tools are not usable. pending is not a failure on its own.
Claude Agent SDK allowedTools mcp__sume__* also allows paid Sume tools
A wildcard in allowedTools approves every tool the Sume server exposes. With an API key that includes paid ones. Name the read tools instead.
Sonnet 5.5 token bill vs Sume spend cap: two meters on one agent run
Sonnet 5.5 tokens bill at the model vendor. Sume generation bills in the Sume wallet. A worked example shows why one cap cannot cover both.
Two model fields: deepseek-flash for your planner, sume-agent for Sume
Your planner config says deepseek-flash. The Sume Agent Completion model field takes only sume-agent. Keep them in separate settings.
ElevenLabs Music can sign MP3s with C2PA; what to log for a Sume track
The ElevenLabs Music API has sign_with_c2pa for MP3 output only. Sume's Music docs name no audio credential, so keep a record of job, prompt and routed model.
Porting to Sume images: 400 unsupported_parameter checklist
Porting an image client to Sume: seed, stream, output_compression and size WxH return 400, and background works only on GPT Image 2.5. A fix for each.
image-generations_create is now generate_image: fix old MCP prompts
The Sume MCP tool image-generations_create was retired for generate_image. Update agent prompts and allow-lists, and check with tools_list. Dated facts.
MCP: read image-models_get, then dry-run generate_image first
An agent checklist for hosted Sume MCP: read the model with image-models_get, dry-run generate_image with a spend cap, then submit with a new idempotency key.
Kling motion control webhook_url: a Python receiver that verifies
Send mode async plus webhook_url on a Kling motion control submit, then verify x-sume-webhook-signature (HMAC SHA-256 over timestamp.body) in Python.
mode subscribe on Sume images is a 30-second wait: poll instead
On Sume, mode subscribe is an alias of sync with one wait of at most 30 seconds and no events. For a longer wait, submit async and poll status in your client.
Model calls image-generations_create? Use generate_image
New LLMs may emit old Sume tool names. The hosted server maps dots to underscores and documents two retired aliases that now point at new names.
Agents SDK blocked_tool_names: hide Sume paid tools from a model
create_static_tool_filter takes allowed and blocked tool names. Use it so an agent on Sume's hosted MCP can read, but never sees a paid generate tool.
reference_ingest OCR: needs_verification crops under 0.85 confidence
reference_ingest never corrects OCR text. Lines under 0.85 confidence come back as needs_verification with a native-resolution crop to check.
Reference-to-video with 3 images, 6 seconds: cost by Sume model
A 6-second reference-to-video clip with three images costs $0.45 on H3 at 768p up to $3.47 on Seedance 2.5 at 720p on Sume. Eight rows priced.
Rolling a webhook secret: Stripe's 24-hour overlap vs Sume's header
Stripe can keep an old signing secret live for up to 24 hours. Sume sends one sume-v1 entry per live secret; verify any match. Python verifier included.
language_code or auto-detect on Sume STT? A two-arm test on your clips
AssemblyAI reports 8.4% mean WER over 18 FLEURS languages. For your audio, run each clip twice on Sume STT, with and without language_code, and compare.
Shorts series episodes number by publish date: a Python order check
YouTube numbers Shorts series episodes by publish date, so upload order is episode order. Check durations and publish times in Python before you schedule.
Shorts series: one Idempotency-Key per season and episode
Timeline renders require an Idempotency-Key. Name it from season and episode, so a retried upload script for episode 4 does not queue a second render.
Voice model updated in place with no API change: how to detect it
Nova 2 Sonic was refreshed in place in May with no API change. If a vendor can change your voice silently, log the model id and a canary clip. Sume code inside.
Split a 10-minute TikTok into parts for 3 and 5-minute accounts
TikTok's API allows up to 10 minutes, but an account may be limited to 3 or 5. Split a 600-second video into 4 or 2 parts with Sume trim at $0.02 a job.
Stripe retries webhooks for 3 days, Sume job webhooks for 4.5 minutes
Compare retry windows: Stripe live mode retries up to three days; Sume job webhooks use 10 attempts at 30s spacing. Size your poll fallback to the shorter one.
Transparent AI image: PNG or WebP, not JPEG, on GPT Image 2.5
For a transparent AI image, request png or webp with background transparent on GPT Image 2.5. JPEG has no alpha. Code to request and verify the alpha channel.
OpenRouter video lists 4-8 second clips; Sume model ranges run 2-30s
OpenRouter's video guide shows typical 4-8 second durations. Sume validates duration per model, from 2-30s on Wan 3.0 to 3-10s on Omni 1.1. See the table.