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
Fade in and out on a Timeline render: output fade seconds 0 to 5
Set output.fade_in_seconds and fade_out_seconds (0 to 5 s, sum within the render length). The music bed has its own fade_out_seconds, up to 10.
Fast-cut Shorts in Timeline: eight chained fades, then a hard cut
Timeline refuses more than 8 adjacent fades with too_many_chained_transitions. Transitions must be 1 s or less and half the shorter neighbour. How to plan cuts.
Get transcript text from a captioned video: caption jobs return none
A Sume caption job returns the burned video, not the transcript. For text and word times run STT or video inspect with transcribe. Prices and a recipe.
A 3-minute Timeline render: poll job status, don't sleep a fixed time
Timeline renders are async by default. Submit with an Idempotency-Key, poll /v1/jobs/:id/status until terminal, then read /result. Cost: 3 minutes is $0.30.
How do I add a listen-to-this-page audio version with TTS?
Turn each article into an audio file with one async TTS job per page: a 9,000-character article costs 43 cents on Sume. What it does not replace.
Model an AI generation job as a state machine in your database
A schema and update rule for tracking Sume jobs: five statuses, sticky terminal states, a separate webhook delivery column, and the idempotency key on the row.
Poll hundreds of AI jobs without a thundering herd: jitter and budgets
Poll many Sume jobs without synchronized bursts: jitter, next_poll_after_seconds, per-plan read budgets, and the math on how much polling a plan can absorb.
Portuguese speech to text API: Sume STT language_code pt or pt-BR
Transcribe Portuguese audio with Sume STT using language_code pt or pt-BR, then check the reported language and word times. $0.01 per audio minute.
Probe a finished video before upload: duration, size and aspect
Run video inspect with frames false to read a render's duration, size and frame rate before posting. Check it against the 3-minute Shorts limit.
Reconcile Sume jobs after a deploy or outage: poll what is open
After downtime, read status for every job your own table still shows as open, honor terminal and result_ready, and never resubmit. Python with sqlite.
Redact faces and license plates: Pillow first, AI edit only to replace
For redaction use Pillow boxes you control; use an AI mask edit on openai/gpt-image-2.5 only to replace a plate or face, from $0.0094 per image on Sume.
Speech to text API in Go: transcribe audio with net/http
Transcribe audio in Go using only the standard library: submit to Sume STT, poll the job and print the text. A 30-line program at one cent per audio minute.
Spot-check burned-in captions with video frames at STT word times
Check captions on a rendered video by pulling stills at word midpoints from a Sume STT result with POST /v1/video-frames, then compare text to speech.
Start a Sume render from a serverless function: submit, save, 202
A function must not wait for a video. Submit with mode webhook and a stable Idempotency-Key, save the status URL, return 202, and let the signed webhook finish.
Sume timeouts in one table: 30 s, 55 s, 10 s, 90 minutes
Every wait in the Sume API has its own number: sync 30 s, jobs_wait 55 s, webhook attempts 10 s, SDK helpers 10 and 20 minutes, Format runs 90 minutes.
Can a Sume webhook arrive twice? Build an idempotent receiver
Sume retries failed webhook deliveries up to 10 times and Redeliver replays a real event, so one terminal event can reach you twice. Dedupe on job_id or run_id.
Test a Sume webhook receiver with signed fixtures, no paid job needed
Generate sume-v1 signatures yourself and test six cases: good, rotated, reserialized, stale, empty-secret and unknown event. Python code that runs as is.
Thai, Vietnamese, Indonesian speech to text: Sume STT language hints
Send th, vi or id as language_code to Sume STT, or omit it to auto-detect, then check language_probability. $0.01 per audio minute; test a sample first.
Timeline output.fps: why a 24 fps clip judders when you force 30
Leave output.fps unset and Timeline renders at the source rate. Force 30 on a 24 fps clip and frames repeat; the job reports output_fps_resamples_sources.
GPT Image 1 to GPT Image 2.5 on Sume: what changes in the output
Moving from GPT Image 1 to ChatGPT Image 2.5 on Sume changes the response (URL, not base64), default quality, size grid and failures.
Which Sume API calls are safe to retry blindly, and which need a key?
Reads, cancels and redelivers retry safely; paid submits retry only under the same Idempotency-Key. A call-by-call table, plus the codes that mean wait or stop.
Check duration, resolution, ratio against /v1/videos/models in Node
A Sora-era request will not fit every Sume model. A Node script reads GET /v1/videos/models and lists what the model rejects before you pay for a job.
The duration window all fallback video models share: 5 to 10 s on Sume
Pair Omni, Seedance, Wan and MiniMax H3 as fallbacks and the only duration every one accepts is 5 to 10 seconds. Overlap table for each pair on Sume.
Nightly video batch after Sora: 6, 24, 48 or 120 jobs by Sume plan
A cron that submitted 30 Sora renders at once needs a new ceiling. Sume accepts 6 jobs on Free, 24 on Pro, 48 on Startup, 120 on Scale before queue_full.
Edit one region of a large photo: crop, edit, stitch back in Pillow
Crop the part you want changed, edit it with Ideogram 4.5 on Sume, then resize and feather it back into the full-resolution photo with Pillow. Code included.
Measure softening and colour creep across AI edit passes in Pillow
Test the no-drift claim on your own photos: edge sharpness and a white-patch colour reading for each pass of an edit chain, in short Python with Pillow.
A ten-photo edit regression suite to re-run when a model launches
Ten photos, five edits each, one scoring sheet: a cheap test to re-run whenever a new image edit model launches. 50 edits cost $1.875 at the low tier on Sume.
Which Sume image models take references and masks: a Python check
Read GET /v1/images/models and list each model max input_references and whether it exposes mask_url, instead of trusting a blog table. Runnable Python.
Which Sume calls are unbilled previews, and which reserve money
Four documented Sume checks create no job and reserve no credits: timeline plan, video filter check, MCP dry_run and the admission preview. Submits reserve.
Avatar job tracking table: which Sume ids to store and why
Avatar work produces a handle, a job id, a preview id and a video id. A small SQL table that keeps them straight, plus the status fields to poll.
Move captions on an avatar video: design.placement and anchor_ratio
Inline avatar captions take no design overrides. To lift the caption line off the platform buttons, re-burn with the standalone job. Fields, price, example.
Restyle avatar clip captions with source_caption_id, no re-transcribe
To try a second caption look on an avatar video, send source_caption_id instead of the video URL. Sume reuses the word timings. Cost, errors and a worked flow.
queue_full 429 on a Sume submit: the reservation is released
A 429 queue_full releases or refunds the failed admission's reservation. Check refunded_usd_micros in /v1/usage, then retry with the same Idempotency-Key.
Sume /v1/usage summary.final is false: a hold is open, not spent
Read GET /v1/usage?job_id= and book cost only when summary.final is true. held_usd_micros and refunded_usd_micros are not spend. Code to poll it.
Redeliver a missed video webhook after a bad deploy: one Sume call
Receiver down when the video finished? POST /v1/jobs/{job_id}/webhook/redeliver re-sends job.completed with a fresh signature. Scope, statuses, pitfalls.
Sume webhooks: 10 attempts 30 seconds apart for a video receiver
A Sume job webhook is tried up to 10 times, 30 seconds apart by default, with a 10 s timeout each. What that means for a video receiver, plus a Python verifier.
Bash progress line for a Sume bulk queue from counts with jq
Poll a Sume bulk queue and print 'running: 60/100 done, 4 running, 2 failed' with curl and jq; back off, ride out 429 and 503, and exit 1 if any item failed.
sume login --no-browser on a remote server: approve the user_code URL
On an SSH box, sume login --no-browser prints the approval URL instead of opening a browser. After you approve the user_code, the CLI stores a CLI-scoped key.
Music job metadata: stored on the Sume job, not sent to Lyria
The metadata object on a Sume music request is stored on the job and never sent to the provider. Tag takes by scene and brief with it.
Show the product name the moment the voice says it: STT word times
Find when a voiceover says a word with Sume STT words[], then use that second as the next timeline video[].start. Offline Python script included.
Pandas DataFrame to a Sume bulk queue in 100-row chunks
Turn a product DataFrame into Sume Format bulk queues: one item per row, 100 rows per queue, a stable key per chunk, and SKU order saved beside each queue id.
GET /v1/jobs/:id returns 404 for a job your teammate's key created
A Sume job id can answer 404 not_found to your key though it exists: an API key reads only jobs its own member created, and only that member can cancel.
Speaking rate in words per minute from Sume STT word times (Python)
Compute words per minute for a recording from the words[] start and end times Sume STT returns, plus a per-minute pacing table. Offline Python, no API call.
Retry a failed Format create with the same Idempotency-Key
After a 402 or 503 on a Format create, Sume releases the Idempotency-Key. Fix the cause, then retry with the same key instead of minting a new one.
Stream a product feed NDJSON into 100-row Sume bulk bodies
Read an NDJSON product feed lazily with itertools.islice and write one bulk-run body per 100 rows, so a large file never has to fit in memory. Python stdlib.
SUME_API_AUTH_MODE: make the Sume CLI send Bearer instead of x-api-key
The Sume CLI sends x-api-key by default. Set SUME_API_AUTH_MODE=bearer when your client or network layer expects Authorization: Bearer. Never send both.
Ruby Net::HTTP: create a Sume bulk queue and poll to an exit code
A 30-line Ruby script with only the standard library: create a Sume bulk queue from items.json, back off the poll, skip 429 and 503, and exit 1 on failed items.
SQLite ledger for Sume bulk queues: SKU to run id and what to retry
Record each bulk queue item by index in SQLite, keep the SKU you sent, and query the SKUs that failed or were canceled and never completed in a later queue.