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
Python urllib gets 403 'error code: 1010' from api.sume.com: set a UA
Python's default urllib User-Agent got a plain-text HTTP 403 from api.sume.com in my test while other clients passed. Add a User-Agent and parse errors safely.
Idempotency keys for Sume batches: item index plus payload hash
A deterministic Idempotency-Key makes a rerun return the original jobs, and a changed payload gets a new key, avoiding 409 idempotency_conflict.
Crash-safe Sume submit: write the key first, reconcile on boot
If a worker dies between POST and saving the job id, list queued and processing jobs, match idempotency_key, and resubmit only keys still unknown.
Map Sume API error codes to messages your app's users can act on
A translation table from Sume HTTP codes such as 402, 409, 413, 415 and 429 to user-facing copy, plus which errors the user cannot fix and should never see raw.
Detect Sume OpenAPI drift in CI: hash the operations you call
Fetch api.sume.com/reference/json, hash only the operations you use, and fail CI when one changes. A 23-line script, plus the User-Agent a stdlib fetch needs.
Go errgroup SetLimit: submit Sume jobs within your concurrency budget
Cap in-flight Sume submissions in Go with errgroup.SetLimit, size the width from your concurrency limit, and keep one Idempotency-Key per item. 30 lines.
Sume GET /v1/balance expiration fields: warn before credits lapse
GET /v1/balance reports when your next credit lot expires and how much expires soon. Read the fields, convert micros to dollars, and alert from a cron job.
Verify a canceled Sume job was refunded: read the usage ledger by job
After you cancel a queued job, check GET /v1/usage with job_id and read the row status: reserved, captured or refunded. A Python script prints the answer.
Preview a HyperFrames composition as PNG stills with the Sume API
POST /v1/hyperframes-previews returns 1-6 PNG stills of a composition without rendering an MP4. Request shape, polling, and what the frames are not.
HyperFrames check via the Sume API: caption collisions pre-render
Send check with caption_zone to POST /v1/hyperframes-previews and get findings, contrast and overlap reports. A failing check is still a completed job.
Slow down a TTS voiceover: speed 0.6 to 1.5, volume, emotion
Sume TTS accepts generation_config with speed 0.6 to 1.5, volume 0.5 to 2 and a free-text emotion guide. How to retime a voiceover to a video.
Lip-sync a 2-minute monologue: split one TTS wav into H3 Max clips
MiniMax H3 Max lip-sync takes audio of 5 to 14.8 seconds. For a longer speech, render one TTS wav and cut it at sentence ends; the cost is worked below.
Unit-test a Sume job poll loop with a fake clock and no network
Inject the status reader and the sleep function to test a Sume poll loop in milliseconds: next_poll_after_seconds, backoff fallback and the client deadline.
Launch-week 503 provider_capacity_exceeded: safe video submit retries
New video models cause capacity spikes. Retry 429 and 503 on Sume with the same Idempotency-Key, honor retry-after, never retry 402. Python sample included.
Exact 1080x1350 from Sume: ask for 4:5, then resize
Sume image models take an aspect ratio, not a pixel size. Ask for 4:5, check the returned size, then resize to 1080x1350 with Pillow. Which models list 4:5.
Music prompt rejected by policy: rewrite only the flagged part
If Sume Music rejects a prompt on policy, change the flagged content but keep the musical brief. The docs say not to flatten it to a generic bed; here is how.
Let a browser poll your backend, not the Sume API: a proxy pattern
Keep SUME_API_KEY on the server: submit async, return the job id, and give the browser a read-only status route. A 27-line TypeScript route with the checks.
POST /v1/trending-research: Reels and TikTok niche search over REST
One call returns up to 24 ranked public short videos for a niche from Instagram and TikTok at $0.10 per accepted search. Fields, limits and a Python example.
ElevenLabs made eleven_v4_turbo a default: pin your TTS engine
ElevenLabs set eleven_v4_turbo as a default on Oct 5. Sume carries Sonic engines, not Eleven; here is how to pin an engine id so audio does not drift.
Edit an AI image in rounds: feed each result URL back as a reference
Sume image calls are stateless. To refine an image over rounds, send the last result URL as input_references, keep the original too, and track cost.
Can you cancel an image generation on Sume? Only before it starts
Cancelling a Sume image job works only before generation work starts. After that the API returns 409 job_generation_already_started and the job runs and bills.
Image API returned 202, not an image: one Python handler for both
POST /v1/images waits 30 seconds, then returns a 202 job envelope. A Python handler that reads the status code, polls the job and returns image URLs either way.
Store the Sume artifact, not a provider link: what to persist per job
A completed Sume job returns artifacts with id, url, type and content_type. Persist those plus the job id and idempotency key, not provider links.
image_not_fetchable on a Sume image edit: reference URL checklist
A Sume image edit failed with image_not_fetchable or input_media_unreachable. What the docs say the error means and a checklist for the reference URL.
sume login opens the wrong host: SUME_APP_BASE_URL and its defaults
sume login picks its approval host from SUME_APP_BASE_URL, else from the API base URL. The defaults, and how to fix a wrong host.
Move a Grok Imagine polling loop to Sume's /v1/videos in Python
Port an xAI Grok Imagine video poll loop to Sume: submit, idempotent retry, poll states, download and read usage.cost. A runnable Python script under 30 lines.
n=10 on the Sume Image API: docs say 10, catalog says 4 (Grok 1)
The Image API docs say n goes up to 10, but every catalog model caps lower: 4 for most, 1 for Grok Image, 1 or 4 for Soul. The 400 you get and how to batch.
stream: true on the Sume Image API returns 400. What to show instead
Sume image models have no SSE streaming: stream true returns 400 streaming_not_supported. Use async mode and job events for stages, or a webhook for the end.
Port an ElevenLabs text-to-speech call to Sume TTS 1.0, field by field
ElevenLabs puts the voice in the URL; Sume TTS 1.0 takes it in the body and rejects model_id. A field map and a tested mapper function.
Image API docs example vs live catalog: Seedream 4.5 shows 5 ratios
The docs example for Seedream 4.5 lists 5 ratios and 0.033 USD. The catalog lists 9 ratios and 0.05 USD. Why you read the endpoint, not the example.
Sume waitForJob in TypeScript: ms timeout, failed jobs resolve
waitForJob in @sume-com/sdk takes milliseconds, resolves for failed and canceled jobs, and throws only on timeout or a failed read. 25-line sample.
Which Sume timeout is which: sync, jobs_wait, waitForJob, webhooks
Sume's waits differ: 30 s sync cap, 50 s jobs_wait, a 20-minute SDK default in ms, 10 s per webhook attempt. A table of each unit and what expiry does.
sume models list is a deprecated alias: use sume catalog list
The Sume CLI keeps sume models list as a deprecated alias of sume catalog list. What the catalog command shows, what it cannot do, and how to migrate scripts.
Sume SDK function name for an endpoint: the camelCase operationId
GET /v1/catalog is listPublicApiCapabilities in @sume-com/sdk. Map any Sume route to its generated function from the OpenAPI operationId, with a table.
Lint a Format package in CI before you PUT it
A short Python check for a Sume Format package: SKILL.md name equals the slug, allowed folders and extensions, file names, 100 MiB limits. Run it before PUT.
Edit several Format files in one commit with a change set
One PUT to the Sume Format contents root commits many files at once. Learn what a change set keeps, why it cannot delete, and how If-Match guards the package.
Suno v6-wild is less predictable: how to keep a track on Sume
Suno describes v6-wild as less predictable. Sume Music has no seed, so you cannot rerun a track; keep the job result and its URL as the only master.
sume/auto hides which image model ran: pin an id for brand assets
model sume/auto never discloses the family, and job.model stays sume/auto. Why a brand asset set needs a pinned image model id, and how to pin one on Sume.
OpenRouter's video expired event has no Sume twin: one normalizer
OpenRouter sends completed, failed, cancelled and expired video events; Sume sends three job events. A Python normalizer and verifier for both.
One length gate for six ad platforms: caps table and Sume plan
Reels 15 min, Stories 60 min, TikTok 10 min, LinkedIn 30 min, Pinterest 5 min, Snap 180 s. Check one Sume Timeline length against all six with the plan call.
Twenty image jobs, one webhook: mode webhook plus a Python verifier
Submit 20 image requests with mode webhook, receive signed job.completed callbacks, and verify them in Python. Retries, replay window and the poll fallback.
Know the day Sume lists a new video model: a catalog check script
Vendors launch video models weekly. A short Python script reads GET /v1/videos/models and flags when an id or name appears, with exit codes for cron or CI.
List Sume's music and TTS router engines in Python before deploy
A short Python script reads the music and TTS router model lists so a deploy check can confirm your pinned engine ids and fixed prices still exist.
Grok Imagine ignores aspect_ratio on image-to-video; Sume rejects it
xAI says image-to-video output matches the input image and ignores aspect_ratio. Sume's Grok row goes further and rejects the field. Crop the still first.
TTS output_format: choose wav or mp3 for joins, captions and clips
Sume TTS returns mp3 by default. Choose wav when you will join, slice per sentence or feed lip-sync; mp3 is smaller but adds padding at every edge.
Port a fal queue submit and poll loop to Sume /v1/videos in Python
A fal queue client posts to queue.fal.run, polls a status URL and fetches a result. The Sume version is 21 lines of Python on /v1/videos. Field map, traps.
Grok Image on Sume: one image per call, so fan out four in Python
x-ai/grok-image lists n as 1 to 1 in the Sume catalog. How to get four variants with four parallel calls, what it costs, and how to stay under queue limits.
OpenRouter: poll video every 30 s. Sume: obey next_poll_after_seconds
OpenRouter recommends a 30 second poll on video. Sume's jobs API returns next_poll_after_seconds, else backoff. A Python poller that does both.