/telnyx-tts-python

name: telnyx-tts-python
description: >-
  Generate speech from text using Telnyx and third-party TTS providers (AWS,
  Azure, ElevenLabs, MiniMax, Resemble, Rime, xAI). Returns base64-encoded
  audio or a binary stream. Also lists available voices per provider.
metadata:
  author: telnyx
  product: tts
  language: python

Telnyx Text-to-Speech - Python

Installation

pip install telnyx

Setup

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),
)

All examples below assume `client` is already initialized as shown above.

Error Handling

All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:

import telnyx

try:
    response = client.text_to_speech.generate(text="Hello world")
except telnyx.APIConnectionError:
    print("Network error — check connectivity and retry")
except telnyx.RateLimitError:
    import time
    time.sleep(1)
except telnyx.APIStatusError as e:
    print(f"API error {e.status_code}: {e.message}")

Common error codes: `401` invalid API key, `403` insufficient permissions, `404` resource not found, `422` validation error, `429` rate limited.

Core Tasks

Generate speech from text

Generate synthesized speech audio from text input. Returns audio as base64-encoded JSON (`base64_output`) or a binary audio stream (`binary_output`).

`POST /text-to-speech/speech`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `text` | string | Yes | The text to synthesize. | | `provider` | enum | No | TTS provider: `telnyx`, `aws`, `azure`, `elevenlabs`, `minimax`, `resemble`, `rime`. Default: `telnyx`. | | `voice` | string | No | Voice ID to use (e.g., `en-US-Standard-A` for AWS). | | `output_type` | enum | No | `binary_output` or `base64_output`. Default: `binary_output`. | | `text_type` | enum | No | `text` or `ssml`. Default: `text`. | | `language` | string | No | Language code (e.g., `en-US`). | | `voice_settings` | object | No | Advanced voice settings (speed, pitch, volume). | | `telnyx` | object | No | Telnyx-specific provider options. | | `aws` | object | No | AWS-specific provider options. | | `azure` | object | No | Azure-specific provider options. | | `elevenlabs` | object | No | ElevenLabs-specific provider options. | | `minimax` | object | No | MiniMax-specific provider options. | | `resemble` | object | No | Resemble-specific provider options. | | `rime` | object | No | Rime-specific provider options. | | `disable_cache` | boolean | No | Disable response caching. |

# Default Telnyx provider
response = client.text_to_speech.generate(
    text="Hello from Telnyx!",
)
print(response.base64_audio)

# AWS provider with specific voice
response = client.text_to_speech.generate(
    text="Hello from Telnyx!",
    provider="aws",
    voice="en-US-Standard-A",
    output_type="base64_output",
)
print(response.base64_audio)

# SSML input
response = client.text_to_speech.generate(
    text="<speak>Hello <break time='1s'/> world</speak>",
    text_type="ssml",
)
print(response.base64_audio)

# ElevenLabs provider
response = client.text_to_speech.generate(
    text="Hello from Telnyx!",
    provider="elevenlabs",
    voice="21m00Tcm4TlvDq8ikWAM",
    output_type="base64_output",
)
print(response.base64_audio)

Primary response fields:

• `response.base64_audio` — Base64-encoded audio data (when `output_type` is `base64_output`)
• Binary stream (when `output_type` is `binary_output`)

List available voices

Retrieve a list of available voices from one or all TTS providers.

`GET /text-to-speech/voices`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `provider` | enum | No | Filter by provider: `telnyx`, `aws`, `azure`, `elevenlabs`, `minimax`, `resemble`, `rime`. |

# List all voices across all providers
response = client.text_to_speech.list_voices()
for voice in response.voices:
    print(f"{voice['name']} — {voice['provider']} ({voice['language']})")

# List only AWS voices
response = client.text_to_speech.list_voices(provider="aws")
for voice in response.voices:
    print(f"{voice['name']} — {voice['language']}")

Primary response fields:

• `response.voices` — Array of voice objects with `name`, `provider`, `language`, `voice_id`

CLI Usage

The Telnyx Agent CLI provides composite commands for TTS:

# Generate speech
telnyx-agent tts --text "Hello world" --json

# Generate with specific provider and voice
telnyx-agent tts --text "Hello world" --provider aws --voice en-US-Standard-A --json

# List available voices
telnyx-agent tts-voices --json

# Filter voices by provider
telnyx-agent tts-voices --provider elevenlabs --json

Important Notes

• **Audio format**: When `output_type` is `base64_output`, decode the base64 string to get the audio bytes. When `binary_output`, the response is a raw audio stream.
• **SSML**: Use `text_type: "ssml"` to send SSML markup for fine-grained control over pronunciation, pauses, and emphasis.
• **Provider-specific options**: Each provider (`aws`, `azure`, `elevenlabs`, etc.) has its own object for provider-specific configuration (e.g., AWS engine type, ElevenLabs stability).
• **Caching**: Responses are cached by default. Use `disable_cache: true` to bypass.
• **xAI**: The xAI provider is available via the CLI (`--provider xai`) and supports voice listing.