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
Dart: submit a 30-second Wan 3.0 clip with package:http
Server-side Dart with package:http: POST wan-3.0 for 30 seconds, poll until completed and write the MP4. Keep the key out of the Flutter app.
Face swap request in Python: validate the video URL before you send
A Python snippet that rejects non-HTTPS, localhost and private-IP video URLs locally, then submits a Sume face-swap beta run with a quality and idempotency key.
Music API 400s: duration and negative_prompt, and the fix
Sume's Music Router returns 400 if you send duration, duration_seconds or a non-empty negative_prompt. The fix for each, and a request that passes validation.
rate_limited or queue_full? One Python submit handler for both 429s
Two different 429s need two different waits. A Python handler reads error.code, sleeps on retry-after for rate_limited, and waits for capacity on queue_full.
Port an OpenRouter video client to Sume: base URL, key, model ids
Sume's /v1/videos follows the OpenRouter video wire. Three edits move a client: base URL, API key, bare model id. The six differences that still bite.
Balance needed to submit 10 or 50 video jobs: reserve per model
Sume reserves each job's estimate at submit. A table of the balance 10 and 50 ten-second clips need on six video models, and where a 402 lands in a batch.
Which Sume API errors to retry and which to stop on: Node wrapper
A retry policy by error.code for Sume submits: retry rate_limited, queue_full, provider_capacity_exceeded; stop on 400, 401, 402, 409. Node wrapper with jitter.
Why input_references fails on Imagen, Recraft, Soul and Qwen Max
Five Sume image rows list zero input_references: imagen-4 fast and ultra, recraft-v4, Soul and qwen-image-max. Check the catalog in Python first.
Switch video models by changing one string: what can still break
On Sume's /v1/videos you swap the model id and keep the body. Duration range, resolution and aspect ratio are the three fields that may need adjusting.
Reserve, capture, refund: a 20-clip batch with 3 failures, 2 cancels
Worked example of how a Sume balance moves across a 20-job batch when 3 jobs fail and 2 are canceled while queued: what is held, captured and released.
Sume webhook retries: 10 attempts, 30 s apart, 10 s timeout each
The delivery schedule for Sume job webhooks: 10 attempts, fixed 30 s spacing, 10 s timeout, about 4.5 minutes of retries, then redeliver and the status poll.
Retry a timed-out Omni Flash submit without paying twice (Node)
Node 18+ code that retries a Gemini Omni Flash 1.1 POST to Sume's /v1/videos on timeout or 429 with one Idempotency-Key, so a retry returns the same job.
model sume/auto on /v1/videos vs pinning Seedance 2.5: what differs
sume/auto lets Sume pick the video family and never says which. Its documented limits are 3 to 10 s, so a 15 or 30 second Seedance clip must be pinned.
Music prompt limits: 1-5000 characters and no duration field
Sume's Music Router takes a 1 to 5000 character prompt and rejects duration. How to set length and sections in the prompt text, with a request.
Deno: a 30-second Wan 3.0 video with fetch and top-level await
A short Deno script that submits a 30-second wan-3.0 job, polls to completion and writes clip.mp4, using only fetch and no npm packages.
Verify x-sume-webhook-signature in Node: sume-v1 HMAC, raw body
A node:crypto verifier for Sume's sume-v1 signature that refuses an empty secret, checks the 5-minute window, and accepts either entry during a rotation.
Draft on Grok Imagine, finish on Seedance 2.5: two calls, one prompt
A Python flow that renders a prompt on grok-imagine-video-1.5 for $0.125, then re-sends the approved text to seedance-2.5 at 1080p for $14.22.
Does Seedance audio cost extra on Sume? generate_audio and the price
Seedance prices on Sume are per video token and carry no separate audio line. What generate_audio does, what it defaults to, and the 10 s price either way.
Check Sume webhook signatures in Python with hmac.compare_digest
A Python verifier for the sume-v1 header: raw bytes, constant-time compare, 300 s replay window, empty-secret refusal, and a Flask route that dedupes on job_id.
Cancel queued Sume jobs after queue_full; handle 409 already started
How to free capacity after a 429 queue_full: cancel queued jobs, read job_generation_already_started on running ones, and why a cancel releases the reserve.
Generate then cut out: an image-model result into RMBG, in Python
Two Sume calls: generate a product shot, then POST its URL to /v1/rmbg-1.0/remove. Runnable Python, the polling loop, and the $0.1225 total per cutout.
Can't choose a video model? Send sume/auto and let Sume pick
model: sume/auto lets Sume select the video family for you: 3 to 10 seconds, 16:9 or 9:16, default 720p and 8 seconds. What it does and does not tell you.
Is Higgsfield Genjutsu in your Sume catalog? Check, then price it
higgsfield-genjutsu appears in the catalog only when its provider is configured. List your models, then price a 4 to 30 second source at 480p or 720p.
sync, subscribe, async or webhook: which Sume mode for a video job
Sume's sync and subscribe modes wait at most 30 seconds, then return a job id. Use async or webhook for video; Python that survives a timed-out wait.
model sume/auto on /v1/videos: defaults, limits, replay-stable price
sume/auto lets Sume pick the video family. Defaults are 720p and 8 s, clips run 3 to 10 s at 16:9 or 9:16, and a replay gets the same route and price.
List your Sume Formats in Python and keep the video ones
Page through GET /v1/formats with next_cursor, keep io.output_kind video, and print each vanity_invoke_url. A runnable snippet with field caveats.
Prompting Omni Flash with sound: write the audio as its own line
Gemini Omni Flash 1.1 always generates audio. A prompt layout that separates picture from sound, three example prompts, and the request on Sume.
Omni job status names: pending vs queued, cancelled vs canceled
Sume's /v1/videos poll uses pending, in_progress, completed, failed and cancelled; /v1/jobs uses queued, processing and canceled. Mapping table for Omni code.
callback_url on /v1/videos: the Sume job envelope that arrives
A /v1/videos callback_url delivers Sume's job.completed, job.failed or job.canceled envelope, not video.generation.* events. Payload, signature, checks.
Retry a timed-out POST /v1/videos with one Idempotency-Key, pay once
A Python submit wrapper that retries network errors, 429 and 5xx with a stable Idempotency-Key, so a replay returns the original job instead of a second charge.
Wan 3.0 draft and final need different Idempotency-Keys (409)
Reusing one Idempotency-Key for a 480p draft and a 1080p final of the same prompt returns 409 idempotency_conflict. A Python key builder that avoids it.
PHP: submit a 30-second Wan 3.0 clip, poll it, save the MP4
Plain PHP 8 with curl and no SDK: send a 30-second wan-3.0 request, poll the job, and write the MP4 to disk. The 720p run is reserved at $3.75.
Edit a photo with Nano Banana: aspect_ratio auto and the cost of 100
Send a product photo as input_references to Nano Banana 2.1 or Pro and set aspect_ratio auto to keep its shape. Python request and cost of 100 edits.
Omni Flash API errors: which to retry and which to fix
A retry policy for Gemini Omni Flash 1.1 calls on Sume: 400, 401, 402, 409, 429 rate_limited, 429 queue_full and 503 each mapped to retry, wait or fix.
Seedance reference inputs on Sume: images, video, audio per docs
Which reference types the Seedance ids accept on /v1/videos (images, video, audio, first and last frame), how references are priced, and a working request.
Swift: URLSession async/await for one 30-second Wan 3.0 job
A 28-line main.swift that submits wan-3.0 for 30 seconds, polls with Task.sleep and saves the MP4. Runs on macOS or Linux with swiftc.
Kubernetes CronJob that submits a nightly 30-second Wan 3.0 clip
A CronJob manifest using curlimages/curl and a Secret: one dated Idempotency-Key per night, concurrency forbidden, and a month of reserves at each resolution.
Rotate the Sume webhook secret without dropping events
After POST /v1/webhooks/signing-secret/rotate, Sume signs with both secrets for 24 hours. How verifyWebhook handles the two-entry header, and the deploy order.
Review a 30-second Wan 3.0 clip: video inspect caps at 24 stills
Video inspect returns at most 24 stills per call, so a 30-second clip needs a sample rate of 0.8 fps or an explicit list of 24 times. Python builds the request.
PowerShell: Invoke-RestMethod for a 30-second Wan 3.0 clip
Windows PowerShell script that posts a 30-second wan-3.0 job, loops until it completes and saves the MP4 with Invoke-WebRequest. $3.75 at 720p.
Free, Pro, Startup, Scale: processing seats, queue slots, full hold
Sume's concurrency by plan, queue capacity max(3, 5 x concurrency), accepted job capacity, and the balance reserved if every slot holds a 10 s clip.
Sume TypeScript SDK waitForJob: 20-minute timeout, job keeps billing
How @sume-com/sdk waitForJob polls a generation job, what SumeJobTimeoutError means, and why a client timeout does not cancel or refund the job.
Seedance output pixel sizes: 480p, 720p and 1080p for every ratio
The frame size Seedance renders at 480p, 720p and 1080p for 21:9, 16:9, 4:3, 1:1, 3:4 and 9:16 on Sume, as used for pricing.
Python: submit, poll and download one Omni Flash clip (v1/videos)
A short Python script that submits a Gemini Omni Flash 1.1 request to Sume's /v1/videos, polls the job until it completes and saves the MP4.
detach_source_has_no_audio: check probe.has_audio first
Audio detach fails with detach_source_has_no_audio on silent video. Probe has_audio with a free frames-false video inspect first. Refusal codes listed.
Poll /v1/jobs/{id}/status, then /result, in Node with backoff
A 25-line Node function that polls a Sume job on its own next_poll_after_seconds, reads /result only when the job completed, and keeps the id on timeout.
First-frame image for /v1/videos: public HTTPS only, no signed URLs
Image and video inputs to Sume generation must be fetchable public HTTPS URLs. Localhost, private IPs, signed URLs and wrong content types are rejected.
Hook matcher rules: when mcp__sume__ names are exact, not regex
Claude Code reads a matcher of letters, digits, underscores and pipes as exact names, and other characters as regex. How to write it for Sume tools.