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
MiniMax H3 text-to-video rejects adaptive: send an explicit ratio
On Sume the H3 text-to-video builder accepts 21:9, 16:9, 4:3, 1:1, 3:4 or 9:16 and rejects adaptive. Only reference-to-video allows it. Preflight in Python.
Cut a 10-minute recording into 3-minute Reels with video trim
A 600 s recording becomes four trims: 180, 180, 180 and 60 s, $0.08 in total. Python loop with a safe Idempotency-Key per segment; run it with an imported file.
Date.now() is milliseconds: the Sume webhook timestamp is seconds
A Node webhook verifier that compares Date.now() to x-sume-webhook-timestamp rejects every delivery. The one-line fix and a four-case test around 300 s.
bash wait -n fails on macOS bash 3.2: cap curl jobs at four
On macOS /bin/bash 3.2 'wait -n' is an invalid option, so a throttled curl loop spins. A portable version that caps Sume video submits at four in flight.
make -j4 as a resumable Wan 3.0 batch runner with an Idempotency-Key
Twelve Wan 3.0 shots as twelve make targets. Re-run after a crash and only missing outputs submit, with an Idempotency-Key per shot. Tested on a stub server.
Seedance 2.5 estimate vs usage.cost: reconcile a job in Node
Compute the Seedance 2.5 price from width, height and seconds, submit one job to Sume, and compare it with usage.cost on the poll. A runnable Node 18 script.
Node --env-file for SUME_API_KEY: fail fast, not the string undefined
Node 22 loads .env with --env-file. A missing SUME_API_KEY then becomes the string 'undefined' in a header. Guard it in two lines and keep .env out of git.
One Sume webhook signature, three languages: a shared test vector
A fixed secret, timestamp and body that must sign to the same sume-v1 value in Python, Node and Go. Use it to test a verifier in any language you add.
Go: cancel the rest of a batch after the first 402 on Sume
A Go fan-out that stops launching Wan 3.0 submits the moment one returns 402 insufficient_credits, using context.WithCancel and a 2-slot semaphore.
Sora to Sume in Python: a 10% rollout flag with a spend guard
Move video traffic off a dead Sora call one slice at a time. A stable per-user percentage flag, one Sume call, and a cost guard that stops at your daily cap.
jq -n --arg: build a Sume video body when the prompt has quotes
Hand-quoted curl -d bodies break on a quote or backslash in the prompt. jq -n --arg escapes it right. Tested with a Wan 3.0 submit on curl 8.7.1 and jq.
curl -K config file: keep your Sume API key out of ps output
A key passed with -H shows in ps args and shell history. curl -K reads headers from a chmod 600 file instead. Tested on curl 8.7.1 against a stub.
Cut a YouTube Short on the beat: BPM to cut times in Python
Turn a music bed's BPM into cut start times for a 30-second Short. Runnable Python, plus the $0.10 Timeline render and $0.125 bed.
Shorts voiceover: how many characters fill 15, 30, 45 and 60 s
Planning table from script length to seconds and TTS cost, with the 15 characters per second assumption labeled and a way to measure the real value.
STT 1.0 or video inspect transcribe: two ways to transcribe on Sume
Both bill about $0.01 per audio minute on Sume, but STT takes an audio URL and video inspect takes a Sume clip. Limits of 10 minutes and 1,800 seconds.
Keep an AI-use ledger for every Short you upload (Python)
A small CSV ledger that records which Sume steps each Short used and what they cost, so a label decision never relies on memory. Code runs as is.
Submit 40 image jobs with mode webhook in Python on Sume
Send 40 POST /v1/images calls with mode webhook and a webhook_url: each returns a 202 job envelope at once and the result follows. Python, cost, status codes.
POST /v1/images status codes on Sume: 200, 202, 400, 404, 502
What each HTTP status from Sume's image route means and what to do: 200 images, 202 job envelope, 400 unsupported_parameter, 404 model_not_found, 502 failed.
Which Sume video model is fastest? The catalog's latency labels
Each Sume video model card carries a typical-latency label. Which rows are fast, medium or medium-slow, and what you pay for the faster ones.
Add captions to a silent clip: cues instead of speech recognition
A clip with no speech fails caption_no_speech. Send cues with your own text and times to burn on-screen lines on silent or music-only video for $0.20.
Korean captions: language ko does not choose the style
Setting language to ko on a caption job does not switch the style. The default is black-outline; a Latin style rejects Hangul with a 400. What to send instead.
Go MaxBytesReader: cap a Sume webhook body at 1 MiB, 413 before HMAC
A webhook endpoint that reads an unbounded body invites memory abuse. A Go handler with http.MaxBytesReader, an HMAC check and a refusal of empty secrets.
Swift withTaskGroup: four Sume video submits in flight
A sliding window in Swift 6: withTaskGroup keeps four POST /v1/videos requests in flight, re-arming as each finishes. One file, URLSession, no packages.
Ruby Thread and Queue: four workers submit Wan 3.0 clips
Ruby worker pool for POST /v1/videos: a Queue of shots, four Threads, Net::HTTP and one Idempotency-Key per shot. Tested on Ruby with a stub server.
Python ThreadPoolExecutor: submit 12 Wan 3.0 clips, four at a time
Stdlib-only Python: ThreadPoolExecutor with 4 workers posts Wan 3.0 jobs to /v1/videos, one Idempotency-Key per shot, results printed in completion order.
curl -d @file strips newlines: a Sume webhook test that fails 401
Signing a fixture file and sending it with curl -d changes the bytes. Use --data-binary to test a Sume webhook receiver. Both signatures shown.
AI music generator API key: a Python script that polls and downloads
Use your SUME_API_KEY to generate a track with the Music Router, poll the job and read the audio URL. A 28-line Python script with the $0.125 price.
Poll a Sume job from a Node script: deadline, backoff and exit code
A short Node script polls a Sume job with getApiJobStatus, honors next_poll_after_seconds, and gives up at a deadline without cancelling the job.
Read the Sume TTS Router catalog in one request: Sonic ids, prices
GET /v1/tts-router/models lists the Sonic ids, the per-character list price, the margin and the 20,000-character cap. A small Node script prints them.
How many new Sume jobs can I submit now? Read generation_limits
Open slots are concurrency_limit minus active and queued jobs, capped by queue_capacity_remaining. A short Python function computes it from a submit response.
Submit 12 thumbnail jobs with mode async and Idempotency-Key on Sume
Queue a dozen 16:9 thumbnails on POST /v1/images with mode async and one Idempotency-Key each. Re-run the script safely, then poll the status URLs. Python code.
Image 1.0 to POST /v1/images: image_urls, num_images, mask mapped
Moving from /v1/image-1.0/generate to /v1/images on Sume: image_urls becomes input_references, num_images becomes n, and the default mode becomes sync.
Claude Code 529 retry delay setting is not a Sume 429/503 retry
Claude Code 2.1.290 added a base delay setting for 529 retries. It does not govern Sume calls; follow retry-after and keep the Idempotency-Key.
MiniMax H3 Max API in Python: reference-to-video with three images
Use MiniMax H3 Max on Sume from Python: send three product photos in input_references, ask for 768p, poll and save. Reference limits and 10-second price.
Kling 3 API in Node: a silent clip with generate_audio false
Call Kling 3 on Sume from Node: send generate_audio false for the cheaper silent rate, add a last frame, poll and save. A 10-second silent clip costs $1.40.
Which Sume image models accept quality, and which reject it with a 400
Only four Sume image families list a quality value: ChatGPT Image 2.5, ChatGPT Image 2, Ideogram V3 and Ideogram 4.5. On any other row quality is a 400.
Wan 3.0 API in Node: vertical image-to-video from a first frame
Call Wan 3.0 on Sume from Node with fetch: pin a first frame, ask for 9:16 at 720p, poll the job and save the MP4. Includes limits and the 8-second price.
A zod schema for the Sume /v1/videos poll response, ported from Sora
Replace Sora's four-status type with a zod schema for Sume's five statuses. It rejects a completed job without unsigned_urls and a failed one without an error.
Sume SDK 0.2.0 exported constants: webhook headers and wait defaults
@sume-com/sdk 0.2.0 exports the webhook header names, the 300 s tolerance and the wait defaults as constants. List them so your code does not repeat strings.
Grok Imagine Video 1.5 API in Python: animate a still on Sume
Animate one image with Grok Imagine Video 1.5 on Sume: Python, a first frame, 720p, 4 to 15 seconds, $0.15 for 12 seconds. Text-only calls fail.
Sora's GET /videos and DELETE /videos/{id}: what Sume offers instead
Sora had list and delete routes. Sume lists your key's own jobs with GET /v1/jobs and documents no public delete, so plan retention in your own storage.
Save a sidecar JSON with every Sume mp4: job id, model, cost, prompt
Export finished video jobs with a Python script that downloads each mp4 and writes a sidecar JSON with job id, model, cost and the prompt you saved.
Re-render a prompts.txt of old Sora prompts with curl, jq and xargs
Turn a file of saved Sora prompts into Sume video jobs with four parallel curl calls, an idempotency key per prompt, then poll jobs.tsv and download each mp4.
Sign a test job.completed webhook and replay it at your receiver
Build a Sume-style job.completed delivery in Python: HMAC over timestamp.body, a verifier that refuses an empty secret, plus tamper, stale and rotation checks.
Sume TTS tts_duration_exceeded: splitting a script over 1,200 seconds
Sume TTS fails audio longer than 1,200 seconds with tts_duration_exceeded, and caps a request at 20,000 characters. Split at paragraph breaks and rejoin.
Sume TTS 409 tts_voice_language_mismatch: confirm and retry safely
A Sume TTS 409 means the voice's language differs from your request. Nothing was charged. Ask the user, then retry with confirm_language_mismatch true.
Read the Sume Music Router catalog: auto, Lyria 3.5 and Lyria 3 Pro
GET /v1/music-router/models returns three ids, their prompt limits and prices in micro-dollars. A Node script prints the table so you do not hard-code it.
Gemini Omni Flash 1.1 API: a vertical 4K clip with curl on Sume
Request a 9:16 4K clip from Gemini Omni Flash 1.1 on Sume: model id, resolution 4K, 3 to 10 seconds, audio always on, and the $3.00 price for 8 seconds.