用途
Telnyx Voice Media（curl 版）用于在 Telnyx 通话中控制媒体播放与录音，适合构建 IVR 系统、播放语音公告、进行文本转语音播报以及录制通话内容。所有操作通过 Telnyx Call Control API 的 HTTP 接口完成，示例均使用 curl 命令。
主要能力
- 播放音频 URL：在通话中播放指定音频文件，支持 mp3、wav 等类型，可设置缓存、循环、叠加播放等参数。连续下发多个播放命令时，音频会排队等待播放。
- 停止音频播放：停止当前通话中正在播放的音频。
- 文本转语音（Speak）：将文本转换为语音并在通话中播放，支持指定语音、语言、SSML 负载类型、服务等级等。连续下发多个 speak 命令时同样会排队。
- 录音控制：支持开始录音、停止录音、暂停录音、恢复录音。开始录音时可指定格式、声道、是否转写、转写引擎、转写语言、说话人分离等参数。
- Webhook 事件：提供 callPlaybackStarted、callPlaybackEnded、callSpeakStarted、callSpeakEnded、callRecordingSaved、callRecordingTranscriptionSaved、callRecordingError 等事件，用于跟踪命令执行结果。
使用方式
- 安装：curl 在 macOS、Linux 和 Windows 10+ 上已预装，无需额外安装。
- 设置认证：通过环境变量设置 API Key：
export TELNYX_API_KEY="YOUR_API_KEY_HERE" - 调用接口：所有请求使用
Authorization: Bearer $TELNYX_API_KEY头进行认证。
主要接口示例：
- 播放音频：
POST /calls/{call_control_id}/actions/playback_start - 停止播放：
POST /calls/{call_control_id}/actions/playback_stop - 开始录音：
POST /calls/{call_control_id}/actions/record_start（必填 format、channels） - 停止录音：
POST /calls/{call_control_id}/actions/record_stop - 暂停录音：
POST /calls/{call_control_id}/actions/record_pause - 恢复录音：
POST /calls/{call_control_id}/actions/record_resume - 文本转语音：
POST /calls/{call_control_id}/actions/speak（必填 payload、voice）
错误处理
API 调用可能因网络错误、速率限制（429）、校验错误（422）或认证错误（401）而失败。生产代码中应始终处理错误。常见错误码：401 无效 API Key，403 权限不足，404 资源未找到，422 校验错误（检查字段格式），429 速率限制（使用指数退避重试）。
Webhook 验证
Telnyx 使用 Ed25519 对 Webhook 进行签名，每个请求包含 telnyx-signature-ed25519 和 telnyx-timestamp 头。生产环境应始终验证签名，建议使用对应语言的 Telnyx SDK 进行验证（client.webhooks.unwrap）。端点必须在 2 秒内返回 2xx，否则 Telnyx 会重试（最多 3 次）。可在 Telnyx Portal 配置故障转移 URL。
适用场景
- 构建 IVR 交互式语音应答系统
- 播放公告或提示音
- 文本转语音播报
- 录制通话并可选进行转写
限制
- 使用 overlay 模式时，target_legs 仅限 self。
- 录音会在通话挂断时停止，也可通过停止录音命令主动停止。
- 部分参数为可选，具体字段与枚举值以官方 API 文档为准。
- 关于收费、价格、平台支持范围等信息，资料中暂未提供。