Skip to main content

​
Endpoint

POST https://api.telnyx.com/v2/text-to-speech/speech

​
Authentication

Authorization: Bearer YOUR_API_KEY

​
Request

{
  "text": "Hello from Telnyx text-to-speech.",
  "voice": "Telnyx.Ultra.aura"
}

​
Response Modes

The output_type parameter controls how audio is returned:
ValueResponse
binary_output (default)Raw audio bytes. Content-Type header indicates format (e.g., audio/mpeg).
base64_outputJSON body with base64-encoded audio.
audio_idReturns an audio_id for deferred retrieval via GET /v2/text-to-speech/speech/:audio_id.

​
Binary (default)

curl -X POST https://api.telnyx.com/v2/text-to-speech/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello.", "voice": "Telnyx.NaturalHD.astra"}' \
  --output output.mp3

​
Base64

curl -X POST https://api.telnyx.com/v2/text-to-speech/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello.", "voice": "Telnyx.NaturalHD.astra", "output_type": "base64_output"}'
Response: 
{
  "base64_audio": "<base64-encoded-audio>"
}

​
Text Preprocessing

Before synthesis, text is automatically preprocessed:
  • Markdown stripping — headers, bold, italics, code blocks, links, lists, emoji → plain text
  • Pronunciation dictionary — custom word replacements applied if pronunciation_dict_id is set

​
Ultra

The Ultra model is REST-only — it is not available over WebSocket. Ultra offers sub-100ms latency, 44 languages, and emotion/speed/volume controls. See Models for details.

​
Streaming Response

The REST endpoint supports HTTP chunked transfer encoding for streaming. Audio chunks are sent as they are synthesized, with a 30-second timeout between chunks.

​
OpenAI SDK Compatibility

Telnyx TTS is compatible with the OpenAI Audio API: 
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_TELNYX_API_KEY",
    base_url="https://api.telnyx.com/v2"
)

response = client.audio.speech.create(
    model="tts-1-hd",
    voice="astra",
    input="Hello from Telnyx."
)

response.stream_to_file("output.mp3")
See Request Body for all options.