Sume TTS: webhook_url, sync wait or polling? The four modes
Sume TTS jobs take mode async, sync, subscribe or webhook. A webhook needs a public HTTPS webhook_url, and sync waits at most 30 seconds.
A Sume TTS request can set mode to async, sync, subscribe or webhook. If you pick webhook you must also send webhook_url, which has to be a public HTTPS URL; sync waits at most 30 seconds for the job. Without any of these, a request with no webhook_url runs in async mode and you poll the job.
What the schema accepts
The shared communication options in the request schema are mode, webhook_url and wait_timeout_seconds. wait_timeout_seconds is an integer from 0 to 30. If you send only a webhook_url, the mode defaults to webhook; if you send neither, it defaults to async. Asking for mode webhook without a URL returns an invalid-options error.
| You send | Resulting mode | Notes |
|---|---|---|
| Nothing | async | Poll the job |
| webhook_url only | webhook | URL must be public HTTPS, max 2,048 characters |
| mode: webhook, no URL | Error | Invalid communication options |
| mode: sync, wait_timeout_seconds: 30 | sync | Wait capped at 30 seconds |
| callback_url on a TTS body | Rejected | TTS body is strict and lists webhook_url only |
Which to choose
For a short line, sync is the simplest: one call, and you get the result if it finishes inside the wait. For a long script near the 20,000-character limit, do not count on 30 seconds. Use a webhook if you have a public endpoint, or poll the shared job status route if you do not. Polling and results use GET /v1/jobs/:id/status and /result, the same surface as other Sume jobs.
- Short line, interactive: sync with a wait up to 30 seconds.
- Long script, server to server: webhook_url.
- No public endpoint: async and poll the job.
Choosing by workload
A narration pipeline that submits fifty scripts overnight does not want fifty open connections. Submit them in async mode with idempotency keys, or give each a webhook_url and let the completions come to you. A chat product that speaks one reply to a person is different: there, a synchronous wait of a few seconds is acceptable, and the 30-second ceiling tells you where to switch to polling.
Remember that TTS on Sume is an asynchronous file job, not a live audio stream. If you need audio to start while text is still arriving, this is the wrong surface, and the live-voice comparison post linked below explains where it fits.
A caveat on callback_url
Some Sume routes accept callback_url as an alias of webhook_url, and they must match if both are sent. The TTS body schema only lists webhook_url, so use that name for TTS and verify against the request reference. Also verify webhook signatures on your receiver; never accept an empty secret.
Sources
Related posts
More in Developers
- Sume TypeScript SDK createImage: a retired model id fails tsc
Sume's @sume-com/sdk lists accepted image model ids as a string union, so gpt-image-1 fails to compile. Use tsc as the migration checklist.
- TypeScript types for a Sume job status: narrow on sume_status
Type the Sume job envelope as a discriminated union on sume_status, so a switch covers queued to canceled and the compiler flags a missed case. Runs on Node 22.
- Unit test a transcription retry loop with a fake 429 in Python
Test your Sume STT retry code without calling the API: inject the POST and sleep, return a 429 with retry-after, and assert the same key is sent twice.
- Unity editor tool: generate an AI video clip with UnityWebRequest
A Unity coroutine posts a Wan 3.0 job to Sume, polls /v1/jobs/{id}/status with next_poll_after_seconds and downloads the MP4 with DownloadHandlerFile.
Written by Sume