telnyx-tts-python

Telnyx Text-to-Speech - Python 是一个用于在 Python 中调用 Telnyx 文本转语音（TTS）能力的技能。

用途 该技能面向需要将文本合成为语音的 Python 开发者，通过 Telnyx 客户端统一调用 Telnyx 自身及多家第三方 TTS 提供商，生成语音音频。

安装与初始化 安装命令为 pip install telnyx。初始化方式为导入 os 与 Telnyx，使用 client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY")) 创建客户端。文档中的示例均假设 client 已按此方式初始化。

主要能力

1. 从文本生成语音：调用 POST /text-to-speech/speech，将文本合成为音频。返回形式为 base64 编码的 JSON（base64_output）或二进制音频流（binary_output）。
2. 列出可用语音：调用 GET /text-to-speech/voices，可获取一个或全部 TTS 提供商的可用语音列表，并可按 provider 过滤。

生成语音参数

• text（string，必填）：要合成的文本。
• provider（enum，可选）：TTS 提供商，可选 telnyx、aws、azure、elevenlabs、minimax、resemble、rime，默认 telnyx。
• voice（string，可选）：使用的语音 ID，例如 AWS 的 en-US-Standard-A。
• output_type（enum，可选）：binary_output 或 base64_output，默认 binary_output。
• text_type（enum，可选）：text 或 ssml，默认 text。
• language（string，可选）：语言代码，例如 en-US。
• voice_settings（object，可选）：高级语音设置（速度、音调、音量）。
• telnyx / aws / azure / elevenlabs / minimax / resemble / rime（object，可选）：各提供商专属选项。
• disable_cache（boolean，可选）：禁用响应缓存。

响应字段 当 output_type 为 base64_output 时，response.base64_audio 为 Base64 编码的音频数据；当 output_type 为 binary_output 时，响应为二进制音频流。列出语音时，response.voices 为语音对象数组，包含 name、provider、language、voice_id。

使用方式示例 默认 Telnyx 提供商：client.text_to_speech.generate(text="Hello from Telnyx!")，打印 response.base64_audio。 指定 AWS 提供商与语音：provider="aws"、voice="en-US-Standard-A"、output_type="base64_output"。 SSML 输入：text 传入 SSML 标记，text_type="ssml"。 ElevenLabs 提供商：provider="elevenlabs"、voice="21m00Tcm4TlvDq8ikWAM"、output_type="base64_output"。 列出全部语音：client.text_to_speech.list_voices()，遍历 response.voices 打印名称、提供商与语言。 按提供商过滤：client.text_to_speech.list_voices(provider="aws")。

CLI 用法 Telnyx Agent CLI 提供 TTS 复合命令：

• 生成语音：telnyx-agent tts --text "Hello world" --json
• 指定提供商与语音：telnyx-agent tts --text "Hello world" --provider aws --voice en-US-Standard-A --json
• 列出语音：telnyx-agent tts-voices --json
• 按提供商过滤语音：telnyx-agent tts-voices --provider elevenlabs --json

错误处理 所有 API 调用都可能因网络错误、速率限制（429）、校验错误（422）或认证错误（401）而失败。生产代码应处理错误，示例包括捕获 telnyx.APIConnectionError、telnyx.RateLimitError（可 sleep 后重试）以及 telnyx.APIStatusError（打印状态码与消息）。常见错误码：401 无效 API 密钥，403 权限不足，404 资源未找到，422 校验错误，429 速率受限。

重要说明

• 音频格式：output_type 为 base64_output 时需解码 base64 字符串得到音频字节；为 binary_output 时响应为原始音频流。
• SSML：使用 text_type: "ssml" 可发送 SSML 标记，以精细控制发音、停顿与强调。
• 提供商专属选项：每个提供商（aws、azure、elevenlabs 等）都有各自的对象用于专属配置（如 AWS 引擎类型、ElevenLabs 稳定性）。
• 缓存：响应默认缓存，可用 disable_cache: true 绕过。
• xAI：xAI 提供商可通过 CLI（--provider xai）使用，并支持语音列表。

适用场景 适用于需要在 Python 应用中集成文本转语音、并希望统一接入多家 TTS 提供商或通过 CLI 快速生成语音与查询语音列表的开发者。

限制 具体收费、价格、平台支持范围、音频格式细节及效果等资料暂未提供。