team-telnyx/telnyx-stt-python

Telnyx Speech-to-Text - 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.ai.audio.transcribe(
        model="openai/whisper-large-v3-turbo",
        url="https://example.com/audio.mp3",
    )
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

Transcribe speech to text

Transcribe an audio file to text. This endpoint is consistent with the OpenAI Transcription API and may be used with the OpenAI JS or Python SDK.

POST /ai/audio/transcriptions

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | url | string (URL) | Yes | URL of the audio file to transcribe. | | model | string | No | Model ID (e.g., openai/whisper-large-v3-turbo, distil-whisper/distil-large-v2). | | language | string | No | Language code (e.g., en, es, fr). | | prompt | string | No | Optional prompt to guide transcription style. | | response_format | enum | No | json, text, srt, verbose_json, vtt. Default: json. | | temperature | number | No | Sampling temperature (0-1). Default: 0. | | keywords | array[string] | No | Keyword biasing — improve accuracy for domain-specific terms. |

# Basic transcription
response = client.ai.audio.transcribe(
    url="https://example.com/audio.mp3",
)
print(response.text)

# With specific model and language
response = client.ai.audio.transcribe(
    url="https://example.com/audio.mp3",
    model="openai/whisper-large-v3-turbo",
    language="es",
)
print(response.text)

# With keyword biasing for domain-specific terms
response = client.ai.audio.transcribe(
    url="https://example.com/audio.mp3",
    keywords=["Telnyx", "API", "WebRTC", "SIP"],
)
print(response.text)

# Verbose JSON with segments
response = client.ai.audio.transcribe(
    url="https://example.com/audio.mp3",
    response_format="verbose_json",
)
for segment in response.segments:
    print(f"[{segment.start:.1f}s - {segment.end:.1f}s] {segment.text}")

Primary response fields:

• response.text — Full transcription text
• response.duration — Audio duration in seconds
• response.segments — Array of segment objects (with start, end, text) when using verbose_json format

List available STT providers

Retrieve a list of available speech-to-text providers and their service types.

GET /ai/audio/transcriptions/providers

response = client.ai.audio.list_providers()
for provider in response.providers:
    print(f"{provider['name']} — {provider['service_type']}")

# Filter by provider name
response = client.ai.audio.list_providers(provider="telnyx")
for provider in response.providers:
    print(f"{provider['name']} — {provider['service_type']}")

# Filter by service type
response = client.ai.audio.list_providers(service_type="transcription")
for provider in response.providers:
    print(f"{provider['name']} — {provider['service_type']}")

Primary response fields:

• response.providers — Array of provider objects with name and service_type

CLI Usage

The Telnyx Agent CLI provides composite commands for STT:

# Transcribe audio
telnyx-agent stt --audio-url https://example.com/audio.mp3 --json

# With specific model and language
telnyx-agent stt --audio-url https://example.com/audio.mp3 --model openai/whisper-large-v3-turbo --language es --json

# List available providers
telnyx-agent stt-providers --json

# Filter by provider or service type
telnyx-agent stt-providers --provider telnyx --service-type transcription --json

Important Notes

• Audio URL: The audio file must be publicly accessible via a URL. Supported formats include mp3, mp4, mpeg, mpga, m4a, wav, and webm.
• OpenAI compatibility: The transcription endpoint is OpenAI-compatible — you can use the OpenAI Python or JS SDK by setting the base URL to https://api.telnyx.com/v2/ai/openai.
• Keyword biasing: Use keywords to improve transcription accuracy for domain-specific terms, product names, or acronyms that generic models may mishear.
• Models: Available models include openai/whisper-large-v3-turbo (fast, accurate) and distil-whisper/distil-large-v2 (lightweight). Check stt-providers for the full list.
• Languages: Use ISO 639-1 codes (en, es, fr, de, ja, etc.). Omit to auto-detect.
• Response formats: Use verbose_json to get timestamps and segments. Use srt or vtt for subtitle files.