telnyx-video-go

用途

Telnyx Video - Go 是一个面向 Go 开发者的技能资料，用于在应用程序中创建和管理实时视频通信与会议的房间。文档以 Go SDK 示例的形式给出，配合 Telnyx 视频 API 使用。

安装与初始化

安装命令：

go get github.com/team-telnyx/telnyx-go

初始化客户端示例：

import ( "context" "fmt" "os"

"github.com/team-telnyx/telnyx-go" "github.com/team-telnyx/telnyx-go/option" )

client := telnyx.NewClient( option.WithAPIKey(os.Getenv("TELNYX_API_KEY")), )

文档中所有示例均假设 client 已按上述方式初始化。

主要能力

错误处理

文档说明所有 API 调用都可能因网络错误、速率限制（429）、校验错误（422）或认证错误（401）而失败，建议在生产代码中始终处理错误。示例展示了通过类型断言识别 *telnyx.Error 并区分 422 校验错误、429 速率限制（建议使用指数退避重试）等情况。常见错误码包括：401 API 密钥无效、403 权限不足、404 资源未找到、422 校验错误（检查字段格式）、429 速率限制（使用指数退避重试）。

房间合成（Room Compositions）

查看房间合成列表：GET /room_compositions
创建房间合成（异步）：POST /room_compositions，可选参数包括 format、resolution、session_id、video_layout、webhook_event_failover_url、webhook_event_url、webhook_timeout_secs
查看单个房间合成：GET /room_compositions/{room_composition_id}
删除房间合成（同步）：DELETE /room_compositions/{room_composition_id}

返回字段包含 completed_at、created_at、download_url、duration_secs、ended_at、format（mp4）、id、record_type、resolution、room_id、session_id、size_mb、started_at、status（completed/enqueued/processing）、updated_at、user_id、video_layout、webhook 相关字段等。

房间参与者（Room Participants）

查看参与者列表：GET /room_participants
查看单个参与者：GET /room_participants/{room_participant_id}

返回字段包含 context、id、joined_at、left_at、record_type、session_id、updated_at。

房间录制（Room Recordings）

查看录制列表：GET /room_recordings
批量删除录制：DELETE /room_recordings
查看单个录制：GET /room_recordings/{room_recording_id}
删除单个录制（同步）：DELETE /room_recordings/{room_recording_id}

返回字段包含 codec、completed_at、created_at、download_url、duration_secs、ended_at、id、participant_id、record_type、room_id、session_id、size_mb、started_at、status（completed/processing）、type（audio/video）、updated_at。

房间会话（Room Sessions）

查看会话列表：GET /room_sessions
查看单个会话：GET /room_sessions/{room_session_id}
结束会话：POST /room_sessions/{room_session_id}/actions/end（会踢出房间内当前所有参与者）
踢出参与者：POST /room_sessions/{room_session_id}/actions/kick，可选参数 exclude、participants
静音参与者：POST /room_sessions/{room_session_id}/actions/mute，可选参数 exclude、participants
取消静音参与者：POST /room_sessions/{room_session_id}/actions/unmute，可选参数 exclude、participants
查看会话参与者：GET /room_sessions/{room_session_id}/participants

会话返回字段包含 active、created_at、ended_at、id、participants、record_type、room_id、updated_at。

房间（Rooms）

查看房间列表：GET /rooms
创建房间（同步）：POST /rooms，可选参数 enable_recording、max_participants、unique_name、webhook_event_failover_url、webhook_event_url、webhook_timeout_secs
查看房间：GET /rooms/{room_id}
更新房间（同步）：PATCH /rooms/{room_id}
删除房间（同步）：DELETE /rooms/{room_id}（删除后参与者将被踢出，无法再加入该房间，也不再对该房间计费）
生成加入房间的客户端令牌：POST /rooms/{room_id}/actions/generate_join_client_token，可选参数 refresh_token_ttl_secs、token_ttl_secs，返回 refresh_token、refresh_token_expires_at、token、token_expires_at
刷新客户端令牌：POST /rooms/{room_id}/actions/refresh_client_token，必填 refresh_token，可选 token_ttl_secs，返回 token、token_expires_at
查看房间会话列表：GET /rooms/{room_id}/sessions

房间返回字段包含 active_session_id、created_at、enable_recording、id、max_participants、record_type、sessions、unique_name、updated_at、webhook 相关字段等。

使用方式

文档以 Go 代码示例逐步演示每个接口的调用方法，包括参数构造、使用 context.Background() 发起请求、通过 log.Fatal 或 fmt.Printf 处理返回值，以及错误处理模式。开发者可参照示例将对应调用集成到自己的 Go 程序中。加入房间需要先通过 generate_join_client_token 生成客户端令牌，令牌在 token_ttl_secs 后过期，并可通过提供的刷新令牌在 refresh_token_ttl_secs 内刷新。

适用场景

适用于需要在 Go 应用中集成 Telnyx 实时视频通信与会议功能的场景，例如管理视频房间、控制会话中的参与者、录制与合成房间音视频、以及为客户端签发加入房间的令牌。

限制

资料未提供价格、计费标准、平台支持范围、并发或性能上限、可用区域等具体信息，暂未提供。使用前需自行配置 TELNYX_API_KEY 环境变量。