/telnyx-stt-python

name: telnyx-stt-python
description: >-
  Transcribe audio to text via the OpenAI-compatible transcription endpoint.
  Supports multiple models, languages, and keyword biasing. Also lists
  available speech-to-text providers and service types.
metadata:
  author: telnyx
  product: stt
  language: 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](https://platform.openai.com/docs/api-reference/audio/createTranscription) 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.