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
Seedance 2.5 API in Python: a 30-second clip with an audio reference
Submit a 30-second Seedance 2.5 job on Sume with requests: an image and an audio reference in input_references, polling, download, and limits to check.
Print a Sume job timeline from the events endpoint in Python
Fetch GET /v1/jobs/{id}/events and print one line per event with the standard library. A pull snapshot, not a stream, so run it again to see more.
Estimate a Gemini TTS bill from seconds of audio (Python, 25 tok/s)
A 20-line Python estimator for Gemini 3.8 Flash and Flash-Lite TTS audio output cost from seconds, at 25 tokens per second and Google's 2026 and 2027 rates.
Sume Images API has no b64_json: turn data[].url into base64
POST /v1/images returns a Sume-hosted data[].url, not b64_json. Fetch the URL and encode it yourself; 202 means poll the job. Python example inside.
Video API callback_url and Idempotency-Key: a sume/auto job in curl
Submit a video job on Sume with callback_url instead of polling, add an Idempotency-Key so retries are safe, and let sume/auto pick the model. Curl and errors.
image_size or aspect_ratio on Sume: which wins and who accepts it
On Sume's Images API image_size takes priority over aspect_ratio. Custom pixels work on GPT, Seedream, Flux, Qwen and Recraft; size rejects WxH.
Node test contract test for a Sume video wrapper, no mock library
Test a Sora-replacement wrapper with node:test and a local http server that answers 202, in_progress, then completed. No network and no key needed.
Sign and verify a Sume webhook offline: a Python test vector
Build a sume-v1 test signature with Python's hmac and check your verifier against it, including an empty secret, an old timestamp and a rotation header.
stream: true on Sume's Images API returns 400: use async and events
Sume's image catalog rows report supports_streaming false, so stream: true is a 400 streaming_not_supported. Submit async and read /v1/jobs/:id/events instead.
Map a Sume API HTTP status to the next step: one Python function
One Python function turns a Sume status, error code and headers into the next action: wait, retry with the same key, fix the request, or stop. Tested.
Sume queue_full 429 on a Shorts batch: how do I retry it?
queue_full means your accepted-job capacity is full: 6 on Free, 24 on Pro. Wait for jobs to finish, then resubmit with the same Idempotency-Key.
Can Sume import my existing YouTube Shorts to reuse in a new episode?
No. Sume's media import takes TikTok and Instagram links at $0.15 and rejects YouTube links. For your own Shorts, work from the original master.
Will polling video jobs trigger a 429? Reads and writes differ
Each Sume API key has a write budget and a read budget 40 times larger, so a status-poll loop cannot 429 your submits. Poll math, headers and a 429 backoff.
Retry a timed-out video submit without paying twice: Idempotency-Key
Your client timed out after submitting a 30-second video job? Retry with the same Idempotency-Key and Sume returns the original job, not a second bill.
Seedance 2.5 reference limits: 30 images on the vendor page, 9 on Sume
ByteDance lists up to 30 images, 10 video and 10 audio references for Seedance 2.5. Sume's Video Router validates fewer: 9, 3, 3, and 12 in total. Read both.
Verify a Sume webhook in Python when the secret is rotating
A Sume webhook can carry two sume-v1 signatures for 24 hours after rotation. A FastAPI verifier that accepts either, rejects an empty secret, checks the clock.
Wan 3.0 reference-to-video body: images, videos and audio in one job
A Wan 3.0 reference job on Sume takes up to 10 images, 5 videos and 5 audio files. Request body, the audio rule, and the frame-versus-reference conflict.
Poll or webhook for a 30-second AI video job? Use both
A 30-second Seedance 2.5 or Wan 3.0 clip runs for minutes. Submit async, take the signed webhook, and keep one status poll as the backup. Code included.
Move an OpenRouter video client to Sume: base URL, key, model ids
Sume POST /v1/videos matches the OpenRouter video API. Change the base URL, key and model id, then check size, seed, provider.options and webhooks.
Check video model limits before you submit: GET /v1/videos/models
Models differ on length, resolution and references. Read GET /v1/videos/models and validate a request before a paid submit, with a Python preflight.
Sync mode returned queued on a 30-second video: the 30 s cap
mode sync waits at most 30 seconds on the HTTP call, not on the job. A 30-second clip returns a job id with sync.timed_out true; keep polling, never resubmit.
v1/videos job statuses and a failed-job error handler
Map /v1/videos statuses (pending, in_progress, completed, failed, cancelled) to actions, and decide which failed-video errors deserve a retry. Python handler.
Sora API is gone: replace the calls with POST /v1/videos on Sume
OpenAI removed the Videos API and sora-2 on 2026-09-24. Point video code at Sume POST /v1/videos: new model ids, duration, resolution, polling, download.
Sume webhook failed 10 times? Redeliver the job event, don't resubmit
After 10 refused attempts a Sume job webhook stops, but the job is done. Read the job, then POST /v1/jobs/{job_id}/webhook/redeliver for a fresh signed event.
How many 30-second jobs can you submit at once? Read generation_limits
Submit responses carry generation_limits. Use concurrency_limit minus active and queued jobs as your in-flight budget, and treat wave_size_hint as a hint only.
Verify Sume job webhooks in Express: raw body, sume-v1, replay window
Verify a Sume job.completed webhook in Express with @sume-com/sdk verifyWebhook: raw body, empty secret refused, dedupe on job_id, answer 2xx fast.
Save a finished Seedance clip to your own storage, not the result URL
When a Seedance 2.5 or Wan 3.0 job completes, read /v1/jobs/{id}/result, take the artifact url and content_type, and copy the file into your own storage.
waitForJob for a 30-second Seedance clip: TypeScript SDK example
With @sume-com/sdk, submit a seedance-2.5 job through generateVideoRouter and let waitForJob poll it for up to 20 minutes. Idempotency key, onStatus, errors.
Seedance 2.5 30-second job: set a 20-minute client deadline in Python
A 30-second Seedance 2.5 job outlives any HTTP timeout. Submit async to Sume, poll with next_poll_after_seconds, and set the deadline in your client.
Lost a 30-second video job after SSH died? Sume CLI recovery
There is no sume video subcommand, but the Sume CLI recovers any job you made through the API: jobs status, watch, result and download. Never resubmit.
Does sume/auto pick a different video model on a retry? No: same route
With model sume/auto, an idempotent replay gets the same price and the same route, because resolution depends only on the request and the catalog version.
Caption job failed: caption_no_speech on a music-only AI video
Sume's caption job fails with caption_no_speech when a clip has no audible speech. Send cues with text, start and end instead; it is the same $0.20.
Sume auto never names the model: what to log for TikTok AI disclosure
With sume/auto the response does not name the model family. TikTok asks if content is AI-generated, not which model made it. Log job id and date.
Get a transcript of an AI video before TikTok Shop review
Run Sume video inspect with transcribe: true to read what an AI video says, at $0.01 per audio minute plus compute, before you post a TikTok Shop clip.
Chain TikTok mini-drama episodes: last frame in, first frame out
Pull the final still of episode one with Sume video frames, then send it as first_frame for episode two so the next shot starts where the last ended.
sume/auto or a pinned model for 30-second video on Sume
sume/auto defaults to 8 s clips of 3 to 10 s, so a 30-second job needs a pinned id: seedance-2.5 or wan-3.0. How the two paths differ.
Move a Seedance 2.5 call from video-router/generate to /v1/videos
Same jobs, same ids: map reference_image_urls to input_references and image_url to frame_images when you move a seedance-2.5 call to POST /v1/videos.
Read Seedance 2.5 and Wan 3.0 limits from GET /v1/videos/models
Call GET /v1/videos/models on Sume to read supported_durations, resolutions, references and generate_audio for seedance-2.5 and wan-3.0 before you submit.
Check MiniMax H3 reference limits before you submit: a Python guard
Sume's minimax-h3 rows take up to 9 images, 3 videos and 3 audios, 12 in all, and audio cannot be the only reference. A 20-line Python guard catches it.
Pause threshold test: 0.4 s versus 1 s silence splits on one clip
Before First Draft or your own trim removes pauses, test what a pause is: run video inspect with silence_split_seconds at 0.4, 0.7 and 1.0 on one clip.
Is there an API for Instagram First Draft? Sume job for each step
The pages we read describe First Draft as an in-app feature, not an API. Each action maps to a Sume job and price, plus the one step that stays manual.
Seedance 2.5 30-second clip via API: the request, poll and price
Send model seedance-2.5 with duration 30 to POST /v1/videos on Sume, poll the job, and expect about $17 at 720p 16:9. Request and Python poll loop.
callback_url for 30-second Seedance 2.5 and Wan 3.0 jobs
Add callback_url (HTTPS) to a 30-second seedance-2.5 or wan-3.0 job and Sume POSTs a signed webhook when it finishes. Headers and what to verify.
Retry a failed 30-second video job on Sume without paying twice
Reuse the same Idempotency-Key when you retry a seedance-2.5 or wan-3.0 submit on Sume; a replay returns the original job. Failed status and error field.
Image API stream:true returns 400: use async mode and events
Sume's Image API does not stream yet: stream:true returns 400 streaming_not_supported. Use mode async and read /events for progress, or a webhook.
Three 'auto' settings on GPT Image 2.5: aspect ratio, size and quality
auto means three different things on ChatGPT Image 2.5 through Sume: it matches an edit's shape, reserves an upper-bound size price, and reserves max quality.
GPT Image 2.5 4K returns 202: a Python poll loop that works
Slow ChatGPT Image 2.5 calls on Sume return 202 and a job envelope after 30 seconds. Python that handles 200 and 202 without paying twice.
Testing four new video models at once: how many jobs can Sume hold?
A model bake-off submits many jobs at once. Sume accepts 6 on Free, 24 on Pro, 48 on Startup, 120 on Scale, and queues the rest; past that is 429 queue_full.