Make a vertical Short clip with curl and jq: submit, poll, download
A 20-line shell script that asks Sume for an 8-second 9:16 clip at 1080p, polls the job, and saves short.mp4, matched to YouTube's Shorts page.
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
Node script for a 9:16 TikTok video: check the model, then submit
A Node 20 fetch script that confirms a Sume model lists 9:16 and your duration, submits one 12-second 720p job, and saves an MP4 that fits TikTok's API limits.
Revoked a Sume API key and it still works? Up to 15 seconds
After you revoke a Sume API key, the API can keep accepting it for up to 15 seconds by default, because the key lookup is cached. What that means for a leak.
Sume public_reason: generation_rejected vs temporary error
How Sume picks generation_rejected, temporary_generation_error or generation_failed on a failed job from the provider HTTP status and the retryable flag.
Sume "Generation could not start": rejected request or outage
Generation could not start is the fallback when a provider rejects a submit. A 4xx gives generation_rejected_request; anything else gives submit_failed.
Sume job error details.input_field: the parameter that failed
When a provider rejects one request field, Sume publishes its name as details.input_field beside provider_error_message. Map it back to your body and fix it.
Sume job failed artifact_too_large: shrink the output
A finished file that storage refuses with HTTP 413 fails as artifact_too_large and is not retryable. Shorten the cut, lower the resolution or the bitrate.
Sume content_policy_rejected: image, music and video messages
Sume scans a provider's rejection text for six phrases and answers with one of three fixed content-policy messages and next_action fix_input.
Sume job failed: generation_output_unavailable, retry or not
generation_output_unavailable means Sume could not copy a finished output into its storage. Retryable true gives retry_later; false gives contact_support.
Sume job failed: image_content_rejected, what to change
image_content_rejected marks a non-retryable failure at an image-input stage such as first_frame. Sume sets next_action to fix_input: swap the picture.
Sume command line tool on Linux arm64: Graviton, Docker on a Mac
The Sume command line tool ships Linux arm64 and x64 binaries plus macOS arm64 and x64. Windows is x64 only. Pick the right asset for Graviton or Docker.
The agent field in Sume MCP results: next_step and poll_after
Sume's hosted MCP adds an agent object to tool results with next_step, poll_after_seconds, adjustments and recovery. What each field means and when it is null.
Upgraded your Sume plan but ratelimit-limit is still the old number?
A plan change can take up to 60 seconds to reach the per-key rate limit, because the tier is cached. Why ratelimit-limit lags, and what changes at once.
Generate a Go client from the Sume OpenAPI with oapi-codegen
The full Sume spec trips oapi-codegen on a [number, null] type, but filtering to the operations you use works. Config, generated names and a short caller.
What to log from a Sume API error: request_id, code, no secrets
Log the status, error.code, error.request_id, retry-after and the path without its query. Keep keys, signed URLs and media URLs out. A 25-line Python logger.
Retry or not: a decision table for failed Sume submit calls
Which Sume errors deserve a retry with the same Idempotency-Key, which mean poll the job, and which mean fix the request. One table and a 15-line classifier.
Clear a full Sume queue: cancel queued jobs after 429 queue_full
When submits fail with 429 queue_full, list queued jobs with GET /v1/jobs?status=queued and cancel the ones you no longer need. Safe on a 409, with a script.
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.