Skip to main content
POST
/
api
/
v1
/
audio
/
tts
Text to Speech
curl --request POST \
  --url https://api.example.com/api/v1/audio/tts \
  --header 'Content-Type: application/json' \
  --data '
{
  "text": "<string>",
  "voice": "<string>",
  "speed": 123
}
'
Convert text to speech. Returns raw audio bytes (audio/mpeg) — not JSON.
The response is a binary MP3 file, not a JSON object. The Content-Type header is audio/mpeg.

​
Authentication

Requires a Bearer token. See Authentication.

​
Request Body

​
text
string
required
Text to convert to speech. Maximum 4,096 characters.
​
voice
string
default:"theo-voice-classic"
Optional Theo voice identifier. Omit to use the default voice. Unknown values fall back to theo-voice-classic.
VoiceCharacter
theo-voice-classicNeutral, versatile — default
theo-voice-brightBright, clear, upbeat
theo-voice-storytellerNarrative, expressive
theo-voice-deepDeep, authoritative
theo-voice-warmWarm, professional
theo-voice-softSoft, thoughtful
​
speed
number
default:"1.0"
Playback speed multiplier (0.25–4.0).

​
Request Examples

curl -X POST https://www.hitheo.ai/api/v1/audio/tts \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Welcome to Theo. How can I help you today?",
    "voice": "theo-voice-warm",
    "speed": 1.0
  }' \
  --output speech.mp3

​
Response

The response body is raw MP3 audio bytes.
HeaderValue
Content-Typeaudio/mpeg
Content-LengthFile size in bytes
X-Request-IdUnique request ID (prefixed tts_)

​
Errors

StatusCodeDescription
400missing_texttext is required
401invalid_api_keyMissing or invalid API key
502tts_provider_errorTheo voice engine returned an error — retry
503tts_unavailableTTS is not configured on this instance