服务端接口

本文说明 Room 对外服务端接口。业务服务端通过 Token 接口申请短效入房凭证，并把返回的 peer_id 和 token 安全下发给设备端。设备端建连请参考设备端集成。

鉴权方式（TGV1-HMAC-SHA256）

与探鸽云端 OpenAPI 服务端签名一致，详见服务端 API 接口签名算法 Demo。

签发入房 token

POST /v1/token/room

请求头

Header	必填	说明
Content-Type	是	固定为 application/json。
X-Tg-App-Id	是	应用 ID。
Authorization	是	TGV1 服务端签名，格式为 TGV1-HMAC-SHA256 Credential=..., SignedHeaders=..., Signature=...。

请求 Body

{
  "room_id": "order-20260611-001",
  "device_id": "device-001"
}

字段	类型	必填	说明
room_id	string	是	业务侧逻辑房间 ID。
device_id	string	是	设备 ID，默认参与者可映射为 device_{device_id}。

响应示例

{
  "peer_id": "room_peer_order_20260611_001_device_001",
  "token": "v1.{claimB64}.{sig}"
}

peer_id 是设备端连接目标标识，业务服务端不要解析或改写。设备端调用 TiRTC TiRtcWhipConnect 时，应同时传入这个 peer_id 和 token。

常见错误

HTTP 状态码	说明
400	请求参数错误，例如 room_id 或 device_id 为空。
401	App 鉴权失败，检查应用 ID、TGV1 签名时间、签名 Header 和 Body SHA-256。
403	当前应用或设备没有入房权限。
429	房间人数超限。
503	服务暂不可用，请稍后重试或联系技术支持。