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
Retry an avatar video submit without paying twice on Sume
Use one Idempotency-Key per paid avatar video submit and poll the job instead of resubmitting after a timeout. A Python example and the rules from Sume docs.
Does a rejected Sume video request cost anything? Free 400 probes
A malformed POST /v1/videos is checked before any estimate or reservation, so a 400 or 404 bills nothing. Three probes to test size, seed and model ids.
The 202 from POST /v1/videos has four fields: where the rest arrives
The Sume submit response returns only id, polling_url, status and model. Usage, unsigned_urls and error come on the poll. A parser that expects no more.
Timeline audio concat or audio.parts: which join for narration takes?
Use audio.parts when the narration only feeds one render; use Timeline audio concat when you need a reusable file. Concat is $0.01 per job, up to 1,800 s.
Transcribe a 90-second clip with video inspect: cost and reservation
Video inspect with transcribe true adds Sume STT at $0.01 per audio minute; send duration_seconds 90 so the hold fits, or it reserves one minute.
Sume video poll usage.cost: reserved while running, captured at end
The usage.cost number is the Sume billable amount: the reservation while a job runs and the captured amount once it settles. wan-3.0 at 720p, 10 s, as math.
Video frames caps at 24 stills: a 15 s hook needs fps 1.6, not 2
Video frames returns at most 24 stills and fps up to 2. At 2 fps only 12 s are covered, so a 15 s hook needs fps 1.6; the Python below checks any length.
Wait for an avatar video in one request? Sume sync stops at 30 s
Sume sync and subscribe modes are the same bounded wait of at most 30 seconds. For avatar videos use async with polling or a webhook, not a long HTTP hold.
Sume /v1/videos has id and generation_id: which one do you store?
Both fields hold the same job id on Sume, so store id. Why generation_id exists and where that id also works: /v1/jobs status and result, webhooks, redeliver.
Edit returns a square? A 1-cent test for aspect_ratio auto vs none
Omitting aspect_ratio on a Sume edit is not the same as auto. A 1-cent low-quality regression test that catches the dropped field before it ships.
API Gateway to Lambda: verify a Sume video webhook on the raw bytes
A Sume callback_url can point at a Lambda behind an HTTP API. Decode the body to bytes first, then verify sume-v1 with the SDK. Handler code is under 30 lines.
Proxy for a Sume video button: forward the click's Idempotency-Key
The docs proxy sample adds crypto.randomUUID() on every forwarded call, so a browser retry makes a second paid job. Take the key from the client for /v1/videos.
callback_url or webhook_url? Which Sume route takes which field name
POST /v1/videos takes callback_url; the model endpoints take mode webhook with webhook_url. Both must be public HTTPS and both deliver signed job events.
Celery task for a Sume video: task id as the Idempotency-Key
One Celery task submits POST /v1/videos with its own task id as the Idempotency-Key and re-queues itself every 30 seconds until the job ends. No double bills.
curl -d to Sume /v1/videos gives 415: add the JSON Content-Type
A POST /v1/videos with a body that is not application/json gets 415 unsupported_media_type, with the content type you sent in details. The curl fix.
Gate a Format run on TikTok limits: artifact size, length, pixels
Check a Sume Format run's artifacts[] for size, duration and dimensions against TikTok's non-Spark limits before upload. A Python gate under 30 lines.
Get a 30-second track from Music 1.0 when there is no duration field
Music 1.0 rejects duration and duration_seconds. Steer length in the prompt, for example 'a 30-second track' with timestamped sections; a generation is $0.125.
Image-to-image in Python: three references on GPT Image 2.5
A 22-line Python script that sends three reference images to POST /v1/images with GPT Image 2.5 and prints the URL and cost. References limits and pitfalls.
GPT Image 2.5 slow? OpenAI says jpeg is faster than png
OpenAI says jpeg is faster than png and complex prompts can take 2 minutes. How to set output_format on Sume and handle the 202 that follows.
mask_url edit on GPT Image 2.5: the mask is a guide, not a hard edge
OpenAI says GPT Image masking is prompt-based and may not follow the mask shape exactly. How that affects mask_url edits on Sume and a cheap way to test it.
Moving off Image 1.0: quality default flips from low to high
Image 1.0 defaults to quality low. On POST /v1/images with gpt-image-2.5 the default is high: 1 cent becomes 7. Field map and the one line to add to keep costs.
PowerShell 7: verify a Sume webhook with HMACSHA256, constant-time
A PowerShell function that refuses an empty secret, checks the 300-second window and accepts any entry in a rotated sume-v1 header. Under 30 lines.
Sent sume/video-1.0, the poll says sume/auto: the alias is rewritten
The model field on a /v1/videos poll echoes sume/auto, not what you sent, for the auto aliases. What that means for logs, price replays and your own checks.
sonic-latest or sonic-3-6: which Sume TTS id for repeatable narration
Pin sonic-3.6 when a series must sound the same; sonic-latest is an alias that tracks the current stable Sonic. Avoid sonic-preview with pro voice clones.
Sume /content?index=N: default 0, a 302, and a 404 past the last one
What the Sume content route answers for index 0, an index past the last output, a failed job and a running job, plus a Python loop that saves every output.
Self-test a Python Sume verifier: rotation, stale time, empty secret
Six asserts for a stdlib hmac verifier: new and old secret both pass, tampered body fails, 301 seconds old fails, empty secret raises. One file, no framework.
Timeline sizes for TikTok's three ad ratios: 540x960, 960x540, 640x640
TikTok's non-Spark minimums are 540x960 (9:16), 960x540 (16:9) and 640x640 (1:1). All three fit Timeline's even 256 to 2160 px output range at $0.10 a minute.
TypeScript union for a Sume /v1/videos poll with an exhaustive switch
Model the five poll statuses as a discriminated union so unsigned_urls only exists on completed and error only on failed. Compiles in strict mode, 30 lines.
Verify a Sume avatar video webhook signature in Python
A Python verifier for Sume job webhooks: HMAC SHA-256 over timestamp.raw_body, sume-v1 entries, a 5-minute window, and a refusal when the secret is empty.
Verify the Sume signature in the HTTP handler, not in the queue worker
A queue delay over 300 seconds makes a valid Sume signature look stale. Verify at receipt, enqueue the verified event, and use redeliver if a late check failed.
Sume ignores aspect_ratio when image_size is set: Flux, Seedream
On Sume's custom-pixel image rows, image_size wins and aspect_ratio is ignored. Nano Banana turns WxH into an enum ratio. What each model does with both fields.
Read /v1/balance: state, micros and the expiring-soon amount
What GET /v1/balance returns, why an empty state means a 402 is coming, and a Node check that compares available micros to a job's cost before you submit.
Caption files: YouTube UTF-8, LinkedIn text-only SRT, Sume burns in
YouTube takes SRT, SBV and more as UTF-8; LinkedIn wants text-only SRT. Sume burns captions in and exports no SRT, so build the file from segments.
Sume webhooks in a Cloudflare Worker: verify, queue, 204
A Worker that verifies a Sume delivery with verifyWebhook, hands the event to a queue with ctx.waitUntil, and replies 204 inside Sume's 10-second limit.
Platform specs ask for bitrate and GOP: what Sume lets you set
YouTube, TikTok and Meta list bitrate, GOP and audio rates. Sume rejects codec and crf fields. Here is what you can control instead: size, fps, audio.
Deterministic Sume Idempotency-Key: body hash plus a take counter
Hash customer, take number and canonical body into one key. A retry replays the job; a deliberate redo bumps the take. Python, stdlib only.
Gemini Omni reference-to-video: 3-second clips and IMAGE_REF tags
Omni on Sume takes up to 10 reference images and 3 reference videos of at most 3 s each, addressed as <IMAGE_REF_0> and <VIDEO_REF_0> in the prompt.
Gemini Omni video edit on Sume: how an unknown clip length is priced
Omni edit takes a video_url and a prompt; output follows the source length. Sume reserves 8 s ($1.00 at 720p) when unknown and accepts a hint up to 30 s.
Read a Sume job's events to time the wait before generation
Read GET /v1/jobs/:id/events, find generation.submitted, and compute how long a job sat between created, queued and started. A Python helper with tested math.
How many Sume jobs can one key poll at once? Reads per minute by plan
Polling every 2 seconds costs 30 reads per job per minute. Divide your plan's read budget by 30 to size the poller: 160 jobs on Free, 1600 on Scale.
Sume job returns 404 not_found? The key may not own that job
A valid job id can still return 404 not_found on the Sume API: API keys read only jobs their own member created. How to confirm it and what to change.
Largest square GPT Image 2.5 takes on Sume: 2880x2880
2880x2880 is exactly 8,294,400 pixels, the top of the GPT Image 2.5 custom-size box on Sume. 2896x2896 is over. 4K UHD lands on the same cap.
Longest AI video clip in one API call: max seconds per Sume model
In one Sume call, Seedance 2.5 and Wan 3.0 reach 30 seconds, Seedance 2.0, Kling v3 Pro and MiniMax reach 15, Gemini Omni Flash 1.1 stops at 10. Full table.
Pinterest video aspect ratio text, quoted, and a master check
Pinterest's video spec says 'shorter than 1:2, taller than 1.91:1'. Quote it, convert the recommended ratios to decimals, and check a master with Sume frames.
Save a Sume job's result artifacts in Python by content type
Fetch GET /v1/jobs/:id/result and save each artifact with an extension from content_type, not the URL. Standard library only, with a text-result guard.
quality on Flux or Seedream returns 400 on Sume: which rows take it
Only GPT Image 2.5, GPT Image 2 and Ideogram 4.5 list quality on POST /v1/images. Send it to Flux, Seedream or Qwen and you get 400 unsupported_parameter.
Which Sume key scope reads or rotates the webhook signing secret?
Reading the webhook signing secret needs account:read; rotating needs account:write. Scopes are fixed at key creation, so use a separate key.
Sume Auto video defaults: 8 seconds, 720p, 3 to 10 second range
sume/auto lets Sume pick the video family. Defaults are 720p and 8 s, with 3 to 10 s clips at 16:9 or 9:16. The legacy Video 1.0 URL rejects 4K.