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.
To avoid polling, add an HTTPS callback_url to the POST /v1/videos body and Sume will POST to it when the job reaches a terminal state. Add an Idempotency-Key header so a retry returns the original job instead of creating and charging a second one.
With model: "sume/auto", Sume chooses the model from the request. The default target is Gemini Omni Flash 1.1, with 3 to 10 second clips at 360p to 4K in 16:9 or 9:16.
The request
The prompt, duration and ratio below fit the Auto envelope. The default is 720p and 8 seconds when you omit them.
curl -X POST "https://api.sume.com/v1/videos" \
-H "Authorization: Bearer $SUME_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ad-spring-001" \
-d '{"model":"sume/auto","prompt":"A vertical UGC-style product clip on a desk, natural light","aspect_ratio":"9:16","duration":6,"callback_url":"https://example.com/hooks/sume-video"}'What to rely on
Sume signs the raw JSON body and sends x-sume-webhook-timestamp and x-sume-webhook-signature headers. The payload is Sume's standard job webhook envelope, not an OpenRouter video.generation.* event. Follow the verification steps in the API reference and refuse to run the check if your signing secret is empty.
A webhook can be delayed or lost, so treat it as a nudge and confirm with GET /v1/videos/{id} before you act on the result. The same job is also readable at GET /v1/jobs/{id}/status and /result.
| Control | Behavior on Sume |
|---|---|
| callback_url | HTTPS only; POST on terminal state |
| Idempotency-Key | Replay returns the original job; same key with a different body gives 409 |
| sume/auto | Echoed back as the model; the resolved family is not disclosed |
| Billing | Reserved at submit; usage.cost is the billable amount |
Auto's limits
Auto validates against the Omni 1.1 envelope and fails closed. A 2-second or 11-second duration, 480p, or generate_audio: false returns 400 unsupported_capability, and the error names sume/auto, not an underlying model. If you need a longer clip or silence, pin a catalog id instead.
Auto does not appear in GET /v1/videos/models, because it is a routing value, not a model.
- Longer than 10 seconds: pin
wan-3.0,seedance-2.5,kling-3or an H3 row. - Silent output: pin
kling-3and sendgenerate_audio: false. - Retry on 429 or 5xx with the same
Idempotency-Key.
Sources
Related posts
More in Developers
- 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.
- Voice agent narrates a long task: poll a Sume video job meanwhile
Decagon Voice 3 narrates progress during long tasks. The same pattern for a voice agent that starts a Sume job: submit, speak, poll jobs_wait.
- 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.
- waitForJob polls every 2 s: 600 reads in a 20-minute Sume video job
The SDK's waitForJob floor is a 2-second poll and a 20-minute timeout: at most 600 reads per job. The read budget by plan and why next_poll_after_seconds wins.
Written by Sume