用途:通过 Telnyx Python SDK 控制通话中的语音媒体,包括播放音频、文本转语音和通话录音,适用于 IVR 系统、语音公告和对话录制场景。
安装与初始化:pip install telnyx;使用 client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY")) 初始化,后续示例均基于已初始化的 client。
主要能力:
- 播放音频:调用 client.calls.actions.start_playback(call_control_id=..., audio_url=...),支持 mp3/wav、loop、overlay、cache_audio 等可选参数;连续多条播放命令会排队。可用 stop_playback 停止播放。
- 文本转语音:调用 client.calls.actions.speak(call_control_id=..., payload="...", voice="female", language="en-US"),payload 必填,支持 text 或 ssml 类型、basic/premium 服务级别、voice_settings 和 target_legs。
- 通话录音:start_recording 需提供 format 与 channels(如 format="wav", channels="single"),可选 play_beep、max_length、transcription、transcription_engine、transcription_language 等;可 pause_recording、resume_recording、stop_recording。录音在挂断时自动停止。
Webhook 与验证:Telnyx 使用 Ed25519 签名,请求包含 telnyx-signature-ed25519 和 telnyx-timestamp 头。生产环境应验证签名,使用 client.webhooks.unwrap(payload, headers=headers) 处理原始请求体。相关事件包括 call.playback.started/ended、call.speak.started/ended、call.recording.saved、call.recording.transcription.saved、call.recording.error。
错误处理:需处理网络错误、429 限流、422 校验错误和 401 认证错误;限流应按 Retry-After 头进行指数退避重试。
限制:overlay 启用时 target_legs 仅限 self;录音格式和支持的转写语言、引擎以资料中列举的枚举为准;具体价格与平台限制暂未提供。