Live Endpoints
Stored TTS configurations with caching and TTL — the backbone of the Public TTS API
Overview
A live endpoint is a saved TTS configuration with a stable ID: the text to speak, the character to speak it, the TTS settings, and a cache lifetime. External applications fetch it with a single authenticated GET — no text or settings in the request — and ToneBoard serves cached audio whenever it can, regenerating in the background when the cache ages out.
Use live endpoints when the same line is requested repeatedly and you want it served fast and cheap:
- •In-game announcements, kiosk prompts, IVR menus, smart-home responses.
- •Content that editors update in the dashboard without redeploying the consuming app — change the text, and the endpoint regenerates on the next fetch.
Anatomy of a Live Endpoint
| Field | Meaning |
|---|---|
name | Label shown in the dashboard |
text | The line to speak — the single source of truth; callers cannot override it |
characterId | The character that speaks (determines internal vs external voice) |
changeTone | Rewrite the text in the character's tone before speaking |
useSSML | Add expressive markup (SSML or internal expression cues) |
ttsSettings | Provider settings: stability, similarity boost, speed, pitch, model, ... |
ttlMinutes | How long a generation stays fresh before a refresh is triggered (default 60) |
Creating One
- 1Go to Live Endpoints → New Endpoint.
- 2Pick the project and character, write the text, and set tone/SSML and TTS settings.
- 3Choose a TTL that matches how often the content should be re-rendered (shorter TTL = fresher takes, more token spend).
- 4Use Preview on the endpoint to hear it before wiring an app to it — good takes can be saved to Saved Content right from the preview.
The Cache Lifecycle
Every fetch resolves against the endpoint's generation cache. The goal: never make the caller wait if any audio exists.
| Situation | What the API does | X-Cache header |
|---|---|---|
| Fresh generation exists | Serves it immediately | HIT |
| Generation exists but TTL expired | Serves the old audio immediately and regenerates in the background; the next fetch gets the new take | STALE |
| A regeneration is already running | Serves the previous take if there is one, otherwise waits briefly for the running generation | STALE-GENERATING / WAIT |
| No audio at all (first fetch) | Generates synchronously, then serves it | MISS |
Out of tokens?
If the balance can't cover a regeneration, the API keeps serving the newest cached audio and attaches a tokenError object to the response instead of failing. Only a first-ever fetch with no cache and no tokens returns 402.
Generation costs 5 tokens (external voice) or 10 (internal) — charged only when audio is actually generated, never for cache hits.
Consuming from Your App
Fetches go through the Public TTS API with an API key holding the tts:generate scope:
curl -s "https://<host>/api/public/tts?liveEndpointId=<endpointId>" \
-H "Authorization: Bearer $API_KEY"The JSON response includes audioUrl (a CDN-backed URL your app can play directly), the on-screen text, and cache metadata. Responses are rate-limited to 60/minute per key.
Tips
- •Fetch ahead of need (e.g. at scene load) so a
MISSnever blocks the user. - •Set the TTL to the slowest cadence your content changes — a static announcement can be hours; a rotating promo shorter.
- •Deleting a character that endpoints depend on is blocked; retire the endpoints first.