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.
Claude Code AGENTS.md without CLAUDE.md: Sume skills install
Claude Code reads AGENTS.md when no CLAUDE.md exists. sume skills install writes to .agents/skills or .claude/skills, so check which one you got.
CLAUDE_CODE_DISABLE_WEB_FETCH: what Sume crawl tools do
CLAUDE_CODE_DISABLE_WEB_FETCH turns off Claude Code's WebFetch tool. Sume's crawl_* tools come from an MCP server, so they are a separate path.
OpenAI Agents SDK MCP tool_input_guardrails for Sume spend
tool_input_guardrails on an Agents SDK MCP server can reject a call before it runs. For Sume paid tools, check idempotency_key and max_spend_usd.
OpenAI Agents SDK MCP require_approval for Sume write tools
Use require_approval with a tool_names list to gate Sume write tools by name, or connect with OAuth mcp:read so those tools are never visible.
AI SDK SSE heartbeat vs Sume jobs_wait 55s slices
AI SDK 7.0.123 adds optional SSE heartbeats for idle UI streams. Sume's jobs_wait is capped at 55s per call, so you still repeat it with the same ids.
AI SDK addToolOutput clears approval: Sume idempotency_key
AI SDK 7.0.126 clears tool approvals when addToolOutput runs. If a paid Sume call replays, a stable idempotency_key is what guards the create.
Gemini CLI keeps the OAuth refresh token: what Sume's MCP does
Gemini CLI 0.62 retains the OAuth refresh token on refresh. Sume's MCP token endpoint accepts only authorization_code, so expect a fresh sign-in, not a refresh.
Codex instant_interrupt mid jobs_wait: Sume jobs keep running
Codex's opt-in instant_interrupt lets new input steer a running turn. A Sume job submitted earlier keeps running and billing; re-read it with jobs_wait.
OpenAI 429 slow_down vs 503 server_is_overloaded, and Sume
OpenAI now splits 429 slow_down (traffic ramping too fast) from 503 server_is_overloaded. Here is how each maps to Sume's 429 scope and 503 retry rules.
Ramp up API traffic gradually: pace Sume submits to the write budget
OpenAI now returns a slow_down 429 when traffic grows too fast. On Sume, pace paid submits to your plan's write budget and read ratelimit-remaining.
Retry a 503 overload on a paid generation without a double charge
A 503 overload is safe to retry on Sume if you reuse the same idempotency key. Credit is reserved at submit and released if the job fails.
ElevenLabs per-key concurrency caps vs Sume's plan limit
ElevenLabs lets enterprise service account keys carry TTS, music and dubbing concurrency limits. Sume has one plan-based limit and no per-key setting.
Agent loops on Sume: tool calls spend writes, polls spend reads
An MCP tool call spends the write budget once for the run it creates; a jobs_status poll spends none. Reads have their own, much larger budget.
curl 8.22 RFC 9421 signatures vs the Sume webhook signature
curl 8.22.0 adds experimental RFC 9421 HTTP Message Signatures. A Sume webhook is not one: it is an HMAC over timestamp.body in a sume-v1 header.
Standard Webhooks headers vs Sume sume-v1: a header map
Sume does not send webhook-id, webhook-timestamp or webhook-signature. It sends x-sume-webhook-* headers with a sume-v1 hex signature. Use verifyWebhook.
SNS 1 MiB messages and Sume run webhook fan-out
Sume run webhook bodies are capped at 1 MiB, and SNS now allows 1 MiB messages with MaximumMessageSize. Ack the webhook first, then publish.
Durable Object waitUntil keep-alive and a Sume job poll
Pending I/O now keeps a Durable Object alive without a client, but a Sume video job is better tracked by job id, status_url polling or a webhook.
Cloudflare Worker 64 MiB limit and the Sume SDK bundle
Cloudflare now checks only a 64 MiB uncompressed Worker bundle. @sume-com/sdk has no runtime dependencies and runs on Workers; measure with a dry run.
Python Workers ASGI: a FastAPI Sume webhook receiver
Python Workers now accept ASGI frameworks. A FastAPI Sume receiver keeps the same rules there: raw body, constant-time HMAC compare, replay window, fast 2xx.
webcrypto_modern_algorithms flag: verifying a Sume webhook
Sume's verifyWebhook runs on plain WebCrypto in Workers. The docs list no compatibility flag for it, so webcrypto_modern_algorithms is not a step to add.
Supabase middleware pipeline: verify a Sume webhook first
Put Sume's verifyWebhook in the first step of a Supabase middleware pipeline: return 401 on a bad signature and handlers only see verified events.
GitHub Actions dropped Node 20: calling Sume needs no Node
Node 20 is gone from GitHub Actions runners. Sume's CLI is a native binary and the API is plain HTTPS, so a workflow step can call it with no Node version.
Cloudflare Workflow schedules: one Sume Idempotency-Key per tick
A scheduled Cloudflare Workflow that submits a Sume job should derive the Idempotency-Key from the tick, so a replayed step returns the same job.
x402 vs Sume's 402: a prepaid-balance error, not a payment prompt
Sume returns HTTP 402 with the code insufficient_credits when the balance is too low. The fix is adding funds, not sending a payment header.
Hookdeck 15-minute timeout and Sume's 10-second webhook attempt
Hookdeck's longer destination timeout does not change Sume's fixed 10-second attempt. Ack fast at the relay URL and give your handler its own time budget.
Webhook 410 Gone and 3xx: what Sume does with each
Sume has no special 410 handling and does not follow redirects. Any non-2xx, including 410 or 301, burns one of ten attempts. Here is the fix for each case.
How long does Sume retry a webhook before giving up?
Sume job webhooks give up after about 4.5 minutes of gaps, run webhooks after about 3 hours. Cumulative timings per attempt, then redeliver or poll.
Rotating a webhook secret during a gradual deployment
Sume signs with both the new and old secret for 24 hours after rotation, so two receiver versions can run side by side. Upgrade the verifier first, then rotate.
Can an AI agent debug a failed webhook on Sume over MCP?
Over MCP an agent can read job status, events and delivery status to see why a webhook did not arrive. Redeliver is a REST call that needs jobs:write.
Webhook signature mismatch: compare the secret fingerprint
Before filing a ticket for a Sume signature mismatch, compare the secret fingerprint header with the dashboard value. It is safe to paste into a ticket.
HeyGen Video Agent edit_plan vs Sume preview regenerate
HeyGen's edit_plan revises named scenes in one turn, up to 50 items. Sume has no in-place scene edit: regenerate preview stills, then render.
HeyGen avatar voice id: default_voice_id vs Sume avatar_handle
HeyGen's PATCH /v3/avatars/{group_id} stores a default_voice_id. On Sume, TTS can take an avatar_handle and resolve that avatar's ready voice.
HeyGen API idempotency key vs Sume: two different 409s
HeyGen returns 409 request_in_progress for an in-flight retry. Sume returns 409 idempotency_conflict only when a key is reused for a different payload.
HeyGen video scenes API vs Sume job result previews
HeyGen's GET /v3/videos/{video_id}/scenes returns each scene's visuals and script. Sume job results return media.sume.com artifacts and scene previews.
Change caption style without transcribing again: source_caption_id
Pass source_caption_id instead of video_url to re-burn a clip under a new style. Sume reuses the stored word timings, so speech-to-text runs only once.
caption_hangul_text_latin_style: the 400 and the fix
Sume returns 400 caption_hangul_text_latin_style when Korean copy is sent to slam, punch or tiktok-green. Name a Hangul style such as black-outline instead.
caption_font_requires_hangul_style: why font returns 400
Sume's font field on video captions is Hangul-only: sending it with slam, punch or tiktok-green returns 400 caption_font_requires_hangul_style.
Customize caption colors via API: not on punch or tiktok-green
Sume's design overrides change caption colours, weight, placement and motion per request, but punch and tiktok-green ignore them. Which styles accept design.
caption_no_speech: caption a silent clip with cues
caption_no_speech means the clip has no audible speech. Sume's fix is next_action use_overlay_captions: send cues with text, start and end and skip ASR.
WAV 16-bit PCM vs 32-bit float: what audio detach returns
Sume audio detach writes wav as 16-bit PCM (pcm_s16le) by default. If your camera records 32-bit float, here is what that means and which options you get.
Text to speech streaming API: what Sume returns instead
Sume's text to speech API doesn't stream audio chunks. It returns a finished file per job; split long scripts into sentence jobs to start playback sooner.
Real time speech to text API: what a file-based API can do
Sume's speech to text API isn't real time: it transcribes recordings of up to 10 minutes at a URL. Chunked recordings give near-live transcripts.
C# text to speech: call a TTS API with HttpClient
Text to speech in C#: POST the text and a voice with HttpClient, poll the job until it finishes, then stream the MP3 from its audio_url to a file.
C# speech to text: transcribe audio files with HttpClient
Speech to text in C#: POST the audio file's URL with HttpClient, poll the job, then read the transcript and word timestamps from the JSON result.
Talking avatar in JS: make one from Node, play it in React
A talking avatar in JavaScript: create it and send it a script from Node with the Sume SDK, wait for the job, then play the returned MP4 in React.
Python API rate limiting: stay under a per-minute limit
Pace Python API calls with an asyncio limiter set under the API's per-minute budget, keep polling on its own budget, and back off on 429 retry-after.
Promise.allSettled vs Promise.all for a batch of API jobs
Promise.allSettled waits for every promise and reports each outcome; Promise.all rejects on the first failure. For paid API jobs, use allSettled.
API throttling vs rate limiting: what's the difference?
Rate limiting refuses requests over a quota with a 429; throttling slows or queues the excess instead. What each one means for your client.