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
Claude Code http hook: send paid Sume call records to an audit log
An http hook POSTs hook input to a URL, with headers from allowed environment variables only. Log Sume tool names and idempotency keys with a tiny receiver.
Claude Code hook: exit 2 or a JSON deny for a paid Sume call?
Exit code 2 blocks and cannot be overridden by JSON; exit 0 with permissionDecision deny carries a reason. A runnable Python guard for Sume's paid tools.
Dry-run 200 holiday renders free with the Sume Timeline plan call
POST /v1/timeline-1.0/plan is unbilled and returns billable_minutes and a cost estimate. A short Python loop totals the bill before you submit a batch.
Split a 15-reference storyboard into two Wan 3.0 jobs on Sume
A 15-image brief does not fit one Sume Wan 3.0 job, which takes 10 references. Split it into two jobs in Python; two 8 s 720p jobs cost $2.00.
bun test for a Sume webhook verifier: five cases to run on Bun 1.4.2
Five bun:test cases for a Sume webhook verifier: fresh, tampered, stale, rotation and an empty secret, plus a pin to Bun 1.4.2 or later. Run on Bun 1.4.0.
Node 26.11 ships Undici 8.11.2: tell a Sume poll timeout from an abort
Catch TimeoutError separately from AbortError when a Sume status poll in Node fetch times out, and know which Sume calls are safe to repeat after that timeout.
Check probe.has_audio before captions to avoid caption_no_speech
A silent clip fails Sume speech captions with caption_no_speech. Run video_inspect with frames false, read probe.has_audio, then pick STT captions or text cues.
Deno 2.9.7: scope permissions to a Sume key check on GET /v1/me
Run a Sume API key check in Deno 2.9.7 with allow-net limited to api.sume.com and allow-env limited to the key, and see what the permission error looks like.
node:test mock.method on fetch: test a Sume status poll offline
Node 26 goes LTS this month. Test a Sume job status poll with node:test and mock.method on fetch: four cases, no network, no key, no third-party test library.
Is Vidu Q4 Preview on Sume? Check the live video catalog in Python
Sume's documented video catalog lists no Vidu model. A short Python check against GET /v1/videos/models confirms it before you build, plus the closest rows.
Threads API video rules: H.264, AAC, edit lists, and what Sume covers
Meta's Threads page lists MP4 or MOV, H.264 or HEVC, AAC, no edit lists and a front moov atom. Which of these Sume documents, and which you must check.
Vercel's 300 s default: does a 30 s Sume image sync call fit?
Yes: with fluid compute the default is 300 seconds, far above the 30-second Sume image wait. Branch on 200, 202 and 502, and poll video jobs instead.
Promise.allSettled for many Sume job statuses: isolate one failure
Check many Sume job statuses at once with Promise.allSettled so one 429 or network error is reported on its own row and does not hide the other results.
Sume webhook receiver: return 204 for an unknown event, not a 500
Route Sume webhook events through a handler table, answer 204 for any event you do not know, and keep the webhook.test event out of your job table. Node sample.
Cloudflare Workers CPU time vs wall clock for a Sume webhook
A Sume webhook verifier on Workers spends CPU only on the HMAC and body read, not on waiting. See the limits and a WebCrypto verifier.
Threads video aspect ratio runs 0.01:1 to 10:1: Sume Timeline sizes
Meta's Threads page allows ratios from 0.01:1 to 10:1 with 9:16 recommended and 1920 px max width. Sizes that Sume Timeline can output inside those bounds.
claude plugin validate --strict in CI: what it checks in a Sume entry
Run claude plugin validate with --strict so warnings fail the build. The MCP checks that hit a Sume entry: undeclared keys, bad URLs, literal credentials.
Where a Claude Code plugin keeps Sume state: CLAUDE_PLUGIN_DATA
A plugin's data directory survives updates, while its root changes. Where to put a Sume call log or cache, and when uninstalling deletes it.
Plugin headersHelper cannot read user_config: where the Sume key goes
Claude Code rejects ${user_config.*} inside an MCP headersHelper. Use the headers field for a Sume API key, or fetch the key inside the helper script yourself.
Name your Sume plugin right: claude- and anthropic- prefixes fail
claude plugin validate errors on plugin names that pass as Anthropic's own. Pick a name for a Sume hosted MCP plugin that validates, and see what still loads.
Plugin lists Sume twice? In Claude Code the later declaration wins
Claude Code loads a plugin's .mcp.json first, then mcpServers from plugin.json; a name declared later replaces an earlier one. Keep one Sume entry.
Ship a Sume Claude Code plugin off by default: defaultEnabled false
A manifest can set defaultEnabled to false, so a Sume plugin with paid tools starts disabled until someone turns it on. What persists after updates.
Hook matcher for a plugin-bundled Sume server: mcp__plugin_ names
A Sume server shipped inside a Claude Code plugin gets a longer tool prefix than one added by hand. Write the PreToolUse matcher for it and test it first.
GPT Image 2.5 inpainting with mask_url on Sume: steps and cost
Edit part of an image with mask_url and up to 16 references on openai/gpt-image-2.5. Billed about $0.066 an image on Sume. Steps and the limits.
Sume image_size vs aspect_ratio: 1080x1350 and GPT size limits
image_size wins over aspect_ratio on Sume's image API. On Nano Banana 1080x1350 becomes 4:5 plus target pixels; GPT needs multiples of 16. Rules and checks.
Python: find Sume image models that list a ratio like 8:1 or 4:5
A 15-line Python script reads GET /v1/images/models and prints every Sume image model that lists a given aspect ratio, so you stop guessing before a 400.
Phonon-2 is CC-BY-4.0: what attribution means for shipped transcripts
Phonon-2 allows commercial use under CC-BY-4.0 with attribution. What that asks of an app that ships transcripts, and where hosted Sume STT differs.
Cartesia sonic-3-latest and sonic-3-preview aliases: fix model strings
Cartesia lists sonic-3-latest and sonic-3-preview as deprecated aliases. What each maps to, which ids Sume's TTS Router accepts, and a safe migration.
TypeScript 7.0.2 with @sume-com/sdk 0.2.0: the tsconfig that compiles
We compiled a Sume SDK 0.2.0 job-status call with TypeScript 7.0.2. It needs nodenext resolution, types set to node and a module-type package.json.
npm audit signatures on @sume-com/sdk 0.2.0: what it proves, what not
Run npm audit signatures on @sume-com/sdk 0.2.0 before deploy. It checks the registry signature; the registry lists no provenance attestation for this version.
MCP C# SDK 2.0 for a .NET client: check the protocol header with Sume
The C# MCP SDK 2.0 targets the 2026-07-28 spec and keeps 1.x APIs compiling. What to test before pointing a .NET client at Sume, which lists 2025 versions.
Lambda get_remaining_time_in_millis: stop polling a Sume job in time
A Lambda that polls a Sume job should check get_remaining_time_in_millis before each sleep and return the job id so a later invocation can resume. Python.
AWS Lambda's 3 s default vs POST /v1/images' 30 s sync wait
POST /v1/images waits up to 30 seconds by default, but a Lambda defaults to 3. Send mode async with an Idempotency-Key and return the job id instead.
Bun 1.4.2 fixes an AsyncLocalStorage leak: per-request Sume keys
Bun 1.4.2 fixes an AsyncLocalStorage leak from 1.4.1. Carry a per-request Sume Idempotency-Key in the store, and check your Bun version first.
Next.js 16.4 Cache Components: keep Sume job polls out of use cache
Next.js 16.4 enables Cache Components in new apps. We built a Sume status route both ways: a plain GET handler stayed live, a use cache helper froze one answer.
Sume 429: retry-after header first, then the body field, then backoff
How long to wait after a Sume 429? Use the retry-after header, then error.retry_after_seconds, then jittered backoff. A Python stdlib function with checks.
Vidu Q4 Preview result URLs last 24 hours: save the file the same day
Vidu says Q4 Preview output URLs stay valid for 24 hours. Copy the file the day you render it, and see what Sume documents about its job result URL.
Clock changes vs clock drift: what breaks Sume webhook checks
Sume webhook timestamps are Unix seconds, so time zone changes cannot break the 5-minute replay check; a drifting server clock can. A check to tell them apart.
Vidu @subject tags vs Sume Omni <IMAGE_REF_0> reference tokens
Vidu Q4 reference prompts use @[subject_name]. On Sume only Gemini Omni Flash 1.1 documents prompt tokens: <IMAGE_REF_0>, <VIDEO_REF_0>.
Node 26.11 isValidHeaderValue: check a Sume Idempotency-Key first
Node 26.11 adds http.isValidHeaderValue. Use it to reject a bad Idempotency-Key before POST /v1/images, with a fallback for older Node, and see its limits.
AbortSignal.any: stop a Sume request on SIGTERM or after 5 seconds
Combine a shutdown signal and AbortSignal.timeout with AbortSignal.any, then tell a timeout from a SIGTERM stop on a Sume GET /v1/me call in Node.
Vidu Q4 Preview has a seed field; Sume video models reject seed
Vidu Q4 Preview image-to-video takes a custom seed. Sume video models report seed false and return 400 unsupported_parameter if you send one.
Threads API video max is 300 s: split a 21-minute talk into parts
The Threads API page lists video up to 300 seconds and 1 GB. Split a 21-minute recording into five trim requests with a small Python script. $0.02 per trim.
4K 3840x2160 for YouTube: Sume Timeline output stops at 2160 per edge
YouTube lists 35-45 Mbps for 4K. Sume Timeline allows even width and height from 256 to 2160, so 3840x2160 is refused. What you can render instead.
720x1280 vs 1080x1920 for a 60 s Short: 40 MB vs 63 MB
YouTube lists 5 Mbps for 720p and 8 Mbps for 1080p. A 60 second Short is 40.38 MB vs 62.88 MB with audio. Set output.width and height in Sume Timeline.
A 12-minute video job costs 24 status reads at 30 s and 360 at 2 s
Poll cadence arithmetic for Sume video jobs: 30-second polls, the 2-second SDK floor, and the 20-minute client deadline, with a runnable calculation.
Bash script to submit, poll, and download a Sume video
A 22-line bash and jq script for POST /v1/videos: idempotency key, 30-second polls, a 20-minute cap, and exit codes 0 to 3 that a scheduler can read.
Budget 250 product shots: read each Sume model's price in code
A short Python script reads the pricing line from Sume's per-model endpoints route and prints the cost of 250 product shots. Reference rules and a worked table.