Public TTS API

Generate text-to-speech audio using live endpoints and API keys, with aggressive caching

Overview

The Public TTS API serves the audio of a live endpoint to external applications. It is designed for production use: responses are cached, stale audio is served instantly while fresh audio regenerates in the background, and callers never wait when any audio exists.

Configuration lives in the endpoint

All configuration — text, character, TTS settings, tone/SSML, TTL — is loaded from the live endpoint stored in the database. The API accepts no text or setting overrides; editors change the endpoint in the dashboard and consumers pick it up automatically.

Authentication

Requires an API key with the tts:generate scope (keys created before scopes existed have it implicitly). Provide it one of three ways:

# 1. Authorization header (recommended)
Authorization: Bearer YOUR_API_KEY

# 2. X-API-Key header
X-API-Key: YOUR_API_KEY

# 3. Query parameter
?api_key=YOUR_API_KEY

Endpoint

GET/api/public/ttstts:generate

Query param	Type	Description
`liveEndpointId`*	string	The live endpoint to fetch audio for

Example request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://agenticaudiostudio.com
/api/public/tts?liveEndpointId=YOUR_ENDPOINT_ID"

Response

{
  "success": true,
  "textToScreen": "string",        // the (possibly tone-enhanced) display text
  "textToSpeech": "string",
  "audioUrl": "string",            // CDN-backed URL - play this directly
  "audioKey": "string",
  "audioFileName": "string",
  "liveEndpointId": "string",
  "generationId": "string",
  "providerType": "string",
  "settings": { "changeTone": true, "useSSML": true, "ttsSettings": {} },
  "ttl": 60,
  "generatedAt": "ISO 8601",
  "cached": true
}

Cache headers

X-Cache	Meaning
`HIT`	Fresh cached audio
`STALE`	Expired audio served instantly; a background refresh is running
`STALE-GENERATING / WAIT`	A regeneration was already in progress
`MISS`	First fetch — generated synchronously

Rate-limit state is reported in X-RateLimit-Limit / -Remaining / -Reset (60 requests/minute per key).

Errors

Status	Meaning
`401`	Missing, invalid, or disabled API key
`403`	Key is missing the `tts:generate` scope
`404`	Live endpoint not found or belongs to another organization
`402`	Insufficient tokens and no cached audio exists. When cached audio exists, the API serves it with a `tokenError` field instead of failing.
`429`	Rate limit exceeded (`Retry-After` header included)
`500`	Generation failed

Best Practices

Recommendations

• Use the Authorization header for the API key.
• Fetch ahead of need so a first-fetch MISS never blocks users.
• Cache audioUrl on your side within the endpoint's TTL.
• Handle tokenError gracefully — audio still played, but the balance needs attention.
• Monitor spend in the Tokens dashboard.

For request-driven generation (text supplied per call), use POST /api/v1/tts from the REST API instead.