服务端接口

本文档说明业务服务端如何对接 AI 对讲相关接口。角色管理、设备与角色绑定等 OpenAPI 以 Apifox 文档为准；本文只展开 AI 对讲连接凭证申请接口。

鉴权方式 (TGV1-HMAC-SHA256)

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

角色与设备绑定 OpenAPI

获取角色、设备绑定角色、查询设备绑定角色等 OpenAPI 的详细接口定义与在线调试，请参阅 探鸽 OpenAPI 文档 (Apifox)。

申请连接凭证

向探鸽平台申请供设备建立 TiRTC 连接的短效凭证 peer_id 和 token。凭证有效期较短（通常为分钟级），设备端应在获取后尽快使用。

• 请求地址：POST https://api-tirtc.tange365.com/v1/token/aichat

请求头

Header	说明
Content-Type	application/json
Authorization	TGV1 签名授权行
X-Tg-Algorithm	签名算法名称，固定为 TGV1-HMAC-SHA256
X-Tg-Date	请求时间（UTC 格式）
X-Tg-App-Id	应用 ID，需与凭证中的 app_id 一致
X-Tg-Content-Sha256	请求 Body 的 SHA-256 哈希值（小写十六进制）
X-Tg-Signed-Headers	参与签名的 Header 名称列表

以上 TGV1 相关 Header 的格式与签名步骤，详见 TGV1-HMAC-SHA256 签名算法。

请求 Body

{
  "device_id": "DEMO_DEVICE_01",
  "role_id": "role_xxx"
}

字段	类型	必填	说明
device_id	string	是	设备 ID，需已在探鸽平台注册并绑定应用。
role_id	string	是	角色 ID，来自控制台角色配置或设备角色绑定查询。

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "peer_id": "whips://aichat?device_id=DEMO_DEVICE_01&role_id=role_xxx",
    "token": "v1.{payload}.{signature}"
  }
}

• code 非 0 时不要把响应下发给设备。
• peer_id 和 token 应由业务服务端通过安全通道下发给设备，作为设备端 TiRtcWhipConnect 的入参。
• 凭证为短效凭证，获取后应尽快使用，避免因过期导致建连失败。

错误码

/v1/token/aichat 常见错误

错误码	HTTP 状态码	说明
AuthFailure.SignatureFailure	401	签名校验失败。检查 CanonicalURI、X-Tg-Date 时间偏差和 Body SHA-256 是否正确。
AuthFailure.TokenExpired	401	请求签名中的时间戳过期。确保 X-Tg-Date 与服务端时间偏差不超过允许范围。
InvalidParameter	400	请求参数错误，例如 device_id 或 role_id 为空。
ResourceNotFound.Device	404	设备未注册或未绑定到当前应用。
ResourceNotFound.Role	404	角色不存在或未发布。
LimitExceeded	429	请求频率超出限制。请降低调用频率后重试。
InternalError	500	平台内部错误。请携带 request_id 联系技术支持。

角色与设备绑定相关错误码请查阅 探鸽 OpenAPI 文档 (Apifox)。