telnyx-stt-python

用途

Telnyx Speech-to-Text - Python 是一个用于将音频转写为文本的 Python 技能，基于 Telnyx 的 OpenAI 兼容转写端点。它适合需要在 Python 应用中集成语音转文本能力的开发者，例如处理录音、生成字幕或对音频内容做文本化处理。

安装与初始化

安装命令：

pip install telnyx

初始化方式：

import os
from telnyx import Telnyx

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

主要能力

语音转文本

调用 client.ai.audio.transcribe 将音频文件转写为文本。该端点与 OpenAI Transcription API 一致，因此也可以配合 OpenAI 的 JS 或 Python SDK 使用（将 base URL 设为 https://api.telnyx.com/v2/ai/openai）。

请求端点：POST /ai/audio/transcriptions

参数说明：

url（string，URL，必填）：要转写的音频文件 URL。
model（string，可选）：模型 ID，例如 openai/whisper-large-v3-turbo、distil-whisper/distil-large-v2。
language（string，可选）：语言代码，例如 en、es、fr。
prompt（string，可选）：用于引导转写风格的可选提示。
response_format（enum，可选）：json、text、srt、verbose_json、vtt，默认 json。
temperature（number，可选）：采样温度（0-1），默认 0。
keywords（array[string]，可选）：关键词偏置，用于提升领域特定术语的准确度。

基础转写示例：

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

指定模型与语言：

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

使用关键词偏置：

response = client.ai.audio.transcribe(
    url="https://example.com/audio.mp3",
    keywords=["Telnyx", "API", "WebRTC", "SIP"],
)
print(response.text)

使用 verbose_json 获取分段：

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}")

主要响应字段：

response.text：完整转写文本。
response.duration：音频时长（秒）。
response.segments：分段对象数组（包含 start、end、text），在使用 verbose_json 格式时返回。

列出可用的 STT 提供商

获取可用的语音转文本提供商及其服务类型。

请求端点：GET /ai/audio/transcriptions/providers

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

按提供商名称过滤：

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

按服务类型过滤：

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

主要响应字段：

response.providers：提供商对象数组，包含 name 和 service_type。

错误处理

所有 API 调用都可能因网络错误、速率限制（429）、验证错误（422）或认证错误（401）而失败。生产代码中应始终处理错误：

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}")

常见错误码：401 无效 API 密钥，403 权限不足，404 资源未找到，422 验证错误，429 速率受限。

CLI 用法

Telnyx Agent CLI 提供用于 STT 的复合命令：

# 转写音频
telnyx-agent stt --audio-url https://example.com/audio.mp3 --json

# 指定模型与语言
telnyx-agent stt --audio-url https://example.com/audio.mp3 --model openai/whisper-large-v3-turbo --language es --json

# 列出可用提供商
telnyx-agent stt-providers --json

# 按提供商或服务类型过滤
telnyx-agent stt-providers --provider telnyx --service-type transcription --json

适用场景

将录音或音频文件批量转写为文本。
为音频生成字幕文件（使用 srt 或 vtt 格式）。
需要时间戳与分段信息的场景（使用 verbose_json）。
对包含领域术语、产品名或缩写的音频提升识别准确度（使用 keywords）。
需要查询可用语音转文本提供商及其服务类型的场景。

限制与注意事项

音频 URL：音频文件必须可通过 URL 公开访问。支持的格式包括 mp3、mp4、mpeg、mpga、m4a、wav 和 webm。
OpenAI 兼容性：转写端点与 OpenAI 兼容，可将 base URL 设为 https://api.telnyx.com/v2/ai/openai 后使用 OpenAI Python 或 JS SDK。
关键词偏置：使用 keywords 可提升领域特定术语、产品名或缩写的转写准确度。
模型：可用模型包括 openai/whisper-large-v3-turbo（快速、准确）和 distil-whisper/distil-large-v2（轻量）。完整列表请查看 stt-providers。
语言：使用 ISO 639-1 代码（en、es、fr、de、ja 等）。省略则自动检测。
响应格式：使用 verbose_json 获取时间戳和分段；使用 srt 或 vtt 获取字幕文件。
收费、价格与平台支持等具体信息暂未提供。