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
Captions misspell your brand name: fix it with authored cues
Sume video captions have no custom dictionary field. Pass cues with your own spelling and speech-to-text is skipped, so the brand name prints as written.
AI music exactly 30 seconds: no duration field, use Timeline
Music Router rejects duration and duration_seconds. Ask for the length in the prompt, then fix the exact output length with Timeline 1.0 audio.duration_seconds.
Avatar video captions error over 60 seconds: split the script
Inline captions on an avatar video are rejected when the estimated duration is over 60 seconds, the same cap as the job. Split long scripts into jobs.
Green screen removal by API: chromakey in a video filter graph
Sume's video filter allowlists chromakey and colorkey, but an MP4 holds no alpha, so a key must be composited inside the graph. Not AI background removal.
Claude mcp_tool_listing pin: what a Sume tool list depends on
A pinned mcp_tool_listing holds the Sume tool list fetched for one session scope. Sume's list depends on mcp:read vs mcp:write and never pushes list changes.
Claude Code MCP 403 insufficient_scope: re-auth Sume with Write
Claude Code 2.1.274 names the missing permission on a 403 insufficient_scope. For Sume, a read-only grant lacks mcp:write: re-authenticate and turn Write on.
Claude Code alwaysLoad meta false: deferred Sume tools
Claude Code 2.1.285: a tool with _meta anthropic/alwaysLoad false stays deferred under a server alwaysLoad. What that means for Sume's tool set.
Claude Code API 400 after a tool returned an object: Sume results
Claude Code 2.1.286 fixed API 400s when a tool returned an object, number or boolean. Sume tools return text content blocks, errors too.
Claude Code background Bash 30-minute limit and Sume jobs
Claude Code 2.1.285 stops background Bash after 30 minutes by default (2 h max). A Sume render is a job id, so poll it with jobs_wait slices, never resubmit.
Claude Code Bedrock/Vertex MCP 2026-07-28 default vs Sume
Claude Code on Bedrock, Vertex and Foundry now negotiates MCP 2026-07-28 by default. The opt-out env vars, and the versions the Sume server accepts.
Claude Code headless MCP auth reminder: Sume key vs OAuth expiry
Claude Code 2.1.286 fixed a repeated MCP auth reminder in headless runs. Sume OAuth tokens last one hour with no refresh, so unattended runs should use a key.
Claude Code MCP OAuth token lost, keychain locked: Sume tokens
Claude Code 2.1.281 stops a locked macOS keychain from dropping stored MCP OAuth tokens. A Sume token lasts one hour with no refresh grant.
CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH and Sume server instructions
Claude Code 2.1.280 lets CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH change the 2,048-character cap. Sume's instructions are long; use tools_schema.
claude mcp add refused: managed settings, plugins only, Sume
Claude Code 2.1.284 refuses claude mcp add when managed settings limit MCP servers to plugins. What the Sume remote URL needs from your admin.
Claude Code MCP connector lists no tools: Sume handshake versions
Claude Code 2.1.286 fixed connectors showing no tools after a server dropped an older handshake. Sume answers 2025-03-26, 2025-06-18 and 2025-11-25.
Claude Code MCP images saved to file: Sume returns a media URL
Claude Code 2.1.283 saves images from MCP tools to a file. Sume tool results are text with a media.sume.com URL, so keep the URL as the durable reference.
Claude Code /usage MCP server credit: reading Sume spend
Claude Code 2.1.286 credits an MCP server for calls made while it was still connecting. Sume spend is a separate number: read it with usage_get.
Claude Managed Agents auto permission and Sume paid MCP calls
The auto policy evaluates each MCP tool call server-side. Sume has no paid scope, so pair auto with dry_run, max_spend_usd and a scope-limited session.
Claude Opus 5.5 tool_choice any 400: steer Sume tools instead
Opus 5.5 returns 400 for tool_choice any or tool. Use auto, then steer to generate_image with instructions and tools_schema, and keep dry_run before paid calls.
Codex MCP input schema budget: how many Sume tools you load
Codex 0.158.0 makes MCP and Code Mode input schema budgets configurable. Sume keeps tool descriptions short and shows fewer tools to a read-only session.
Apply a LUT to video by API: no .cube file, use lutrgb curves
Sume's video filter cannot load a .cube LUT because lut3d is not allowlisted. Per-channel curves with lutrgb or lutyuv are the supported way to grade.
Deepgram Flux numerals toggle vs Sume STT digits
Deepgram Flux can switch numerals on mid-stream for PINs and phone numbers. Sume STT is a batch job with fixed provider settings and no numerals flag.
Deepgram Flux TTS speed 0.5 to 1.5 vs Sume's 0.6 to 1.5
Deepgram widened Flux TTS speed to 0.5-1.5 in 0.05 steps on 2026-08-31. Sume TTS accepts generation_config.speed from 0.6 to 1.5, plus a deprecated enum.
Devin Desktop ACP session/new mcp_servers with Sume's remote URL
Devin Desktop 3.10.35 uses MCP servers an ACP client passes in session/new. Pass Sume's streamable HTTP URL and an API-key header, not editor config.
ElevenLabs API timeout: cascade_timeout_seconds vs Sume waits
ElevenLabs added cascade_timeout_seconds (2-15 s) for Speech Engine retries. Sume's wait_timeout_seconds is a different knob: a 0-30 s HTTP wait on a job.
ElevenLabs API cursor pagination, and how Sume pages lists
ElevenLabs added a cursor-paginated phone number endpoint. Sume list routes use keyset pages: pass next_cursor back as cursor until has_more is false.
ElevenLabs Flows webhook: what changed, and Sume's per-job webhook
ElevenLabs Flows template runs can send a terminal result to a webhook, and webhook targets now need type all or ids. Sume sets the callback per job.
is_final_audio_for_turn vs Sume TTS sentence boundaries: wav or mp3
ElevenLabs now emits is_final_audio_for_turn after every byte, even for MP3. Sume marks boundaries differently: sentence segments, sliced only for wav or raw.
eleven_turbo_v2_5 deprecated: use Flash; Sume TTS Router ids
ElevenLabs lists eleven_turbo_v2_5 as deprecated and suggests eleven_flash_v2_5. Sume's TTS Router pins an explicit catalog id, so list the ids first.
ElevenLabs Voice Design 409: wait and retry, or new key on Sume?
Voice Design now returns 409 while a preview generation is in progress; ElevenLabs says retry. On Sume, reuse an Idempotency-Key only for the same payload.
Facebook Page story API: media from an earlier post is rejected
Meta's Stories API says a story's photo or video cannot have been used in a published post. Make the story variant a new file with a Sume job, not the old URL.
edge_fades_exceed_output: fade in and out too long for the video
Timeline 1.0 refuses fades that are too long: each edge fade is 0 to 5 seconds and fade in plus fade out must not exceed the output length.
x-fal-billable-units header: WebSocket billing vs Sume receipts
fal bills WebSocket sessions via x-fal-billable-units headers. Sume has no such header: cost is a per-job ledger row you read back by job or run.
Fix lens distortion in video by API with lenscorrection
Sume's video filter allowlists ffmpeg's lenscorrection, so barrel distortion from a wide action-cam clip can be corrected by coefficients you choose and test.
FLUX.2 JSON prompt: on Sume it is text in the prompt field
BFL says FLUX.2 accepts JSON-structured prompts. On Sume, prompt is a plain string, so JSON goes in as text; other fields are typed.
FLUX.2 LoRA API: finetune_id on BFL, not on Sume
BFL serves klein LoRAs through -finetuned endpoints with finetune_id. Sume rejects provider-specific parameters, so use reference images instead.
FLUX Request Moderated vs Content Moderated, and Sume's reason
BFL separates input moderation from output moderation and adds a Moderation Reasons array. Sume groups refusals under content_policy_rejected.
FLUX safety_tolerance 0 to 5, and what Sume does instead
BFL's safety_tolerance runs 0 (strictest) to 5 on FLUX.2, default 2. Sume has no such dial: it returns 400 unsupported_parameter.
Upload 30 reference images to a Sume Format run (images only)
A Format run takes up to 30 images in attachments[], type input_image, by public HTTPS URL or asset_id. Video and audio attachments are not supported today.
Gemini 2.5 not available in a new project: what to do
Google's September 18 changelog limits Gemini 2.5 models to users who already used them. New projects are pointed to 3.5 Flash-Lite or 3.8 Flash.
gemini-3.1-flash-tts-preview replacement: 3.8 Flash-Lite TTS
Google names gemini-3.8-flash-lite-tts as the replacement for the 3.1 preview TTS model. What that changes for you, and what stays fixed on Sume TTS.
Gemini TTS API polling: the Sume audio job pattern
Gemini 3.8 Flash TTS went GA on Sep 22. On Sume, speech is a job: submit async, store the job id, poll the status URL, and never resubmit while it runs.
Gemini 3.8 TTS returns WAV by default; Sume TTS returns MP3
Gemini 3.8 TTS unary requests return WAV with a RIFF header. Sume TTS 1.0 defaults to mp3 at 44100 Hz, so ask for wav when your pipeline needs it.
Gemini TTS reads stage directions aloud: Sume emotion field
Gemini 3.8 TTS speaks its text field verbatim, so style goes in speech_metadata. On Sume, keep the transcript clean and put delivery in generation_config.
Gemini API file size limit: 2GB per file, 20GB storage
Gemini's rate-limits page lists a 2GB input file limit and 20GB file storage under Batch API limits. Sume takes public HTTPS URLs instead of uploaded files.
Gemini Batch API rate limits vs Sume's 100-run bulk queue
Gemini Batch API allows 100 concurrent batch requests and a 2GB input file. Sume bulk runs queue up to 100 Format runs with concurrency 1 to 16.
Gemini image_size 1k rejected: use 1K, and Sume resolution tiers
Gemini rejects a lowercase image_size such as 1k; use an uppercase K. Sume's images API takes a resolution tier, and only values the model lists.
Omni 1.1 Flash start and end frame API on Sume
Omni 1.1 Flash can render between two keyframes, including looping clips. On Sume, Omni takes image_url plus end_image_url; frame_images covers other models.