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.
Lower background music under narration: Timeline duck_db and gain_db
Keep a music bed from covering the voiceover in a Sume Timeline render: soundtrack gain_db, duck_db from 0 to 20, loop, and a fade-out up to 10 seconds.
Make an AI voice read numbers, prices and years correctly: a test list
Test how a Sume TTS voice reads prices, years, percentages and phone numbers: eight lines in one job, sentence slices to audition, and a respell fallback.
Agent Builder structured outputs into a capped Sume Agent Completion
OpenAI advises structured outputs between nodes. Map that JSON into a Sume Agent Completion, with the spend cap set by your code, not the model.
Recast photo URL rejected: public HTTPS, no login in the URL
A Recast request is refused when a reference photo URL is private, signed or carries a username and password. What Sume accepts and how to fix each case.
Recast in TypeScript: upload your own files, submit, poll (SDK)
Upload a source MP4 and a host photo with uploadFile, submit h3-max-recast with generateVideoRouter and poll getApiJobStatus. Uses the published @sume-com/sdk.
waitForJob resolves for failed jobs: read job.status, not catch (TS)
In the Sume SDK on main, waitForJob returns the job for completed, failed and canceled alike. Branch on job.status and job.error, and keep catch for timeouts.
Strip Markdown, HTML and URLs before text to speech: Python and cost
Sume TTS bills every character you send, spaces included. Strip Markdown, HTML tags and link URLs in Python first, then see the characters and cents saved.
Transcribe a 45-minute recording: split first, offset the timestamps
A 45-minute file exceeds Sume STT's 10-minute request cap and audio detach's 1,800 s source cap. Split locally, transcribe each chunk, and stitch word times.
Transcribe an iPhone voice memo (m4a) with an API: audio_url, limits
Sume STT takes a public HTTPS audio_url up to 10 minutes. What is verified for m4a, why media-imports cannot host a memo, and a Python example.
Trim silence from a TTS file: word timestamps and Timeline audio
Cut the lead-in and tail of a Sume TTS file by reading words[] start and end, then slice it with Timeline audio split for $0.01 or use source_in in a render.
video_url or reference_video_urls? Which Sume models edit a clip
Sume has two ways to pass a video: video_url is a source to edit or recast, reference_video_urls only conditions a new clip. Which models take which.
Voiceover longer than the video: speed up, trim or lengthen picture
A Sume TTS voiceover runs 35 seconds over a 30-second video. Compare speed up to 1.5x, a shorter script or a longer Timeline slot, with cost and a Python check.
WAV or MP3 for AI narration you will trim or join: Sume defaults
Sume TTS defaults to mp3 at 44.1 kHz and 128 kbps, but Timeline audio says mp3 re-adds priming padding at every edge. Use wav for narration you cut or join.
YouTube takes 15 Shorts per upload: batch-render 30 episodes
YouTube's help says you can upload up to 15 Shorts at a time. Render a 30-episode series in two groups of 15 with Sume Timeline, idempotent, for $3.00.
AI image API 429s: queue_full vs rate_limited, and how to retry each
Sume returns 429 for two different reasons. rate_limited means back off; queue_full means wait for jobs to finish. A Python retry that treats them differently.
AI image model fallback in Python: try the next model on a 502
Image models launch and fail on different days. A Python loop that tries the next Sume model id on 502 or 503, stops on 400, and keeps the 202 job path intact.
Avatar video mode: sync waits 30 seconds, so use async or webhook
Sume's sync and subscribe modes wait at most 30 seconds. Avatar video usually takes longer. How to read the timed-out response and what to do next.
Can polling Sume job status hit the rate limit? Read budget math
Reads and writes have separate Sume budgets. Worked numbers for polling every accepted job per plan, plus a delay function that reads ratelimit headers.
Compare AI image models on the same prompt: a 20-line API script
MAI-Image-2.6 and Muse Image both claim No. 2 on Arena. Skip the leaderboard: run one prompt through several Sume image models and compare the URLs and cost.
Fix one sentence in an AI avatar video without a full re-render
ElevenLabs can regenerate only edited dubbing regions. A Sume avatar video is one job, so the fix is to keep clips short and join them: the cost math.
Gemini API video upload limits vs how Sume takes media inputs
Gemini accepts video inline under 100 MB or through the File API up to 20 GB paid and 2 GB free. How Sume's video routes take URLs, and where they refuse.
GPT Image 2.5 image_size rules: validate in Python before you send
Custom image_size on GPT Image 2.5 needs edges in multiples of 16, max edge 3840, aspect 3:1 or less, and 655,360 to 8,294,400 pixels. A Python checker for it.
MAI-Image-2.6 allows 6 requests a minute at tier 1; Sume queues
Foundry rates MAI-Image-2.6 at 6 RPM on tier 1 and 429s past it. Sume accepts valid image jobs as queued until a plan slot opens. Compare the two behaviours.
MAI-Image-2.6 returns base64 PNG; Sume returns a hosted image URL
Foundry returns MAI-Image-2.6 as b64_json PNG only. Sume returns a signed media URL in data[].url, in png, jpeg or webp per model. How to handle each in code.
Migrate Veo 3.1 API calls to Gemini Omni Flash 1.1: parameter map
Veo 3.1 previews shut down October 22, 2026. A parameter-by-parameter map from the Veo guide to Gemini Omni Flash 1.1 requests on Sume, with a working curl.
Poll a Sume job with AbortSignal.any in Node 26.10
Node 26.10.0 fixes AbortSignal.any() propagation. Here is a Sume job poll loop with a hard deadline and a caller cancel, using next_poll_after_seconds.
Open Graph image 1200x630 with an AI API: generate 16:9, then crop
Meta recommends og:image at 1200 x 630 and a 1.91:1 ratio. Sume has no 1.91:1 option, so generate 16:9 and crop with 12 lines of Pillow. Steps and limits.
OpenRouter video is ZDR-ineligible: what Sume says about retention
OpenRouter says video generation cannot use Zero Data Retention because output is held for retrieval. Sume has no ZDR toggle; what to tell your security team.
Pace bulk Sume submits with generation_limits, not wave_size_hint
Size in-flight work as concurrency minus active minus queued, capped by queue capacity. A short Node pacer that reads generation_limits from each submit.
Python 3.15 TaskGroup.cancel: stop at the first Sume job done
Python 3.15 adds TaskGroup.cancel. Watch several Sume jobs and stop the other watchers when the first one completes, without cancelling the paid jobs.
Python asyncio.timeout around a Sume job poll: a hard budget
Wrap a Sume status loop in asyncio.timeout so it stops at a fixed budget and returns still_running, leaving the job alone. A short version, run against a mock.
Python Sume webhook handler: stdlib verify and SQLite dedupe
A stdlib Python handler for Sume webhooks: verify that accepts rotation, then INSERT OR IGNORE on job_id so a retry runs once. Tested on 3.14 and 3.15.
Why did my Sume webhook not arrive? Read the job events
One GET on a job lists a webhook.delivery event with status, attempts, last HTTP code and host. A 19-line Python function turns it into a one-line verdict.
Retry an avatar video request without paying twice
A timed-out avatar video submit can be retried safely with the same Idempotency-Key. What Sume returns, what causes a 409, and how to build the key.
Sume API errors: a 13-line function that says retry or fix
Map a failed Sume response to out-of-credit, wait, back off, fix the key, retry with the same key, or fix the request, using the documented error envelope.
Sume Idempotency-Key design: one key per order and revision
Build Idempotency-Key from your own order id plus a revision number, so retries return the same Sume job and a changed prompt is a deliberate new key.
verifyWebhook returns false during a Sume secret rotation
The npm build of @sume-com/sdk 0.2.0 compares the signature header for equality, so rotation deliveries with two signatures fail. A 21-line fix.
@sume-com/sdk waitForJob is not exported: a 26-line replacement
The docs show waitForJob, but the npm build of @sume-com/sdk 0.2.0 does not export it. Here is a fetch version with 429 tolerance and a deadline.
Sume webhook signature fails: compare the secret fingerprint
When a sume-v1 signature does not verify, one header tells you if the wrong secret signed it. A 24-line Node check reads the fingerprint and names the cause.
Sume webhook never arrived: a sweeper that settles pending jobs
Run a small timer job that reads status for jobs still pending after ten minutes and settles them with the same guarded update your webhook route uses.
Test a Sume webhook receiver with node:test and signed fixtures
Three node:test cases that sign their own Sume webhook bodies: fresh, rotation header, and the three rejections. Runs with node --test.
TTS word timestamps to Timeline slide starts in Python
Call the Sume TTS Router with word timestamps, find the word that opens each slide, and build the Timeline video array of start times in a short Python script.
TypeScript 7: an exhaustive switch over Sume job statuses
Turn a Sume job record into done, failed, canceled or running with a never check, so a new status breaks the build. Compiled with tsc 7.0.2 in strict mode.
Verify a Sume avatar video webhook in Python (HMAC SHA-256)
A Python verifier for avatar video webhooks: timestamp tolerance, rotation-safe comparison, and a hard refusal when the signing secret is empty.
Is there an asset library API for AI images and videos?
Sume has no folders or tags. Your library is completed jobs plus durable media.sume.com artifacts, which you list, label by Idempotency-Key, and download.
Face swap source clip: 4-15 seconds with usable audio on Sume
Sume's Avatar Face Swap Beta targets source videos of about 4-15 seconds with usable audio. What the docs say on length, silent clips, and unsupported fields.
Check a transparent GPT Image 2.5 PNG for real alpha in Python
A transparent GPT Image 2.5 result can still look opaque. Ask for background transparent as PNG, then check the alpha channel in Python: a 20-line script.
Why concurrency_limit differs from the Sume plan table
In Sume generation_limits, concurrency_limit is the effective cap and limit_source says plan or admin_override. Size work from it, not plan_concurrency_limit.