tencent cloud

实时音视频

动态与公告
产品动态
产品近期公告
关于 TRTC Live 正式上线的公告
关于TRTC Conference 正式版上线的公告
Conference 商业化版本即将推出
关于多人音视频 Conference 开启内测公告
关于音视频通话 Call 正式版上线的公告
关于腾讯云音视频终端 SDK 播放升级及新增授权校验的公告
关于 TRTC 应用订阅套餐服务上线的相关说明
产品简介
产品概述
基本概念
产品功能
产品优势
应用场景
性能数据
购买指南
计费概述
免费时长说明
月订阅
现收现付
TRTC 逾期与暂停政策
常见问题解答
退款说明
新手指引
Demo 体验
视频通话 SDK
组件介绍
开通服务
跑通 Demo
快速接入
离线唤醒
会话聊天
云端录制
AI 降噪
界面定制
Chat 集成通话能力
更多特性
无 UI 集成
服务端 API
客户端 API
解决方案
错误码表
发布日志
常见问题
视频会议 SDK
组件介绍(TUIRoomKit)
开通服务(TUIRoomKit)
跑通 Demo(TUIRoomKit)
快速接入(TUIRoomKit)
屏幕共享(TUIRoomKit)
预定会议(TUIRoomKit)
会中呼叫(TUIRoomKit)
界面定制(TUIRoomKit)
虚拟背景(TUIRoomKit)
会议控制(TUIRoomKit)
云端录制(TUIRoomKit)
AI 降噪(TUIRoomKit)
会中聊天(TUIRoomKit)
机器人推流(TUIRoomKit)
更多特性(TUIRoomKit)
客户端 API(TUIRoomKit)
服务端 API(TUIRoomKit)
常见问题(TUIRoomKit)
错误码 (TUIRoomKit)
SDK更新日志(TUIRoomKit)
直播与语聊 SDK
Live 视频直播计费说明
组件介绍
开通服务(TUILiveKit)
跑通 Demo
无 UI 集成
UI 自定义
直播监播
视频直播
语聊房
高级功能
客户端 API
服务端 API
错误码
发布日志
常见问题
RTC Engine
开通服务
SDK 下载
API-Example
接入指引
API-参考手册
高级功能
AI 集成
概述
MCP 配置
Skills 配置
集成指南
常见问题
RTC RESTFUL API
History
Introduction
API Category
Room Management APIs
Stream mixing and relay APIs
On-cloud recording APIs
Data Monitoring APIs
Pull stream Relay Related interface
Web Record APIs
AI Service APIs
Cloud Slicing APIs
Cloud Moderation APIs
Making API Requests
Call Quality Monitoring APIs
Usage Statistics APIs
Data Types
Appendix
Error Codes
控制台指南
应用管理
套餐包管理
用量统计
监控仪表盘
开发辅助
解决方案
实时合唱
常见问题
迁移指南
计费相关
功能相关
UserSig 相关
应对防火墙限制相关
缩减安装包体积相关
Andriod 与 iOS 相关
Web 端相关
Flutter 相关
Electron 相关
TRTCCalling Web 相关
音视频质量相关
其他问题
旧版文档
RTC RoomEngine SDK(旧)
集成 TUIRoom (Web)
集成 TUIRoom (Android)
集成 TUIRoom (iOS)
集成 TUIRoom (Flutter)
集成 TUIRoom (Electron)
TUIRoom API 查询
实现云端录制与回放(旧)
监控仪表盘计费(旧)
协议与策略
安全合规认证
安全白皮书
信息安全说明
服务等级协议
苹果隐私策略:PrivacyInfo.xcprivacy
TRTC 政策
隐私协议
数据处理和安全协议
词汇表

REST API 简介

PDF
聚焦模式
字号
最后更新时间: 2025-04-17 16:28:40
REST API 是 CallKit SDK 的后台 HTTP 管理接口,其主要目的在于为开发者提供一套简单的管理入口。
为了安全性,REST API 仅提供 HTTPS 接口。

前提条件

要调用 REST API,您必须购买或领取 CallKit Sdk 所需的套餐包。
警告:
我们如果您使用的是 TUICallKit.call()或者TUICallKit.groupCall()接口发起通话的,请查看:Deprecated Document 目录,如果您还有任何疑问,您可以联系:info_rtc@tencent.com 。

调用方法

请求 URL

REST API 的 URL 格式如下:
https://xxxxxx/$ver/$servicename/$command?sdkappid=$SDKAppID&identifier=$identifier&usersig=$usersig&random=99999999&contenttype=json
其中各个参数的含义以及取值如下(参数名称及其取值均区分大小写):
参数
含义
取值
https
请求协议
请求协议为 HTTPS,请求方式为 POST
xxxxxx
请求域名
SDKAppID 所在国家/地区对应的专属域名:
中国:console.tim.qq.com
新加坡:adminapisgp.im.qcloud.com
ver
协议版本号
固定为v4
servicename
内部服务名,不同的 servicename 对应不同的服务类型
示例:v4/call_engine_http_srv/get_call_info,其中call_engine_http_srvservicename更多详情请参见 REST API 列表
command
命令字,与 servicename 组合用来标识具体的业务功能
示例:v4/call_engine_http_srv/get_call_info,其中get_call_infocommand更多详情请参见 REST API 列表
sdkappid
App 在即时通信 IM 控制台获取的应用标识
在申请接入时获得
identifier
用户名,调用 REST API 时必须为 App 管理员账号
参见 App 管理员
usersig
用户名对应的密码
参见 生成 UserSig
random
标识当前请求的随机数参数
32位无符号整数随机数,取值范围0 - 4294967295
contenttype
请求格式
固定值为json
注意:
App 服务端在调用 REST API 时,identifier 必须为 App 管理员账号。
App 可以在每次调用 REST API 时都生成管理员账号的 UserSig,亦可生成一个固定的 UserSig 重复使用,但请特别注意 UserSig 的有效期。

HTTP 请求包体格式

REST API 仅支持 POST 方法,其请求包体为 JSON 格式,具体的包体格式参见每个 API 的详细描述。
需要特别注意的是,POST 包体不能为空,即使某条协议包体中不需要携带任何信息,也需要携带一个空的 JSON 对象,即{}

HTTP 返回码

除非发生网络错误(例如502错误),否则 REST API 的调用结果均为200,真正的 API 调用错误码与错误信息在 HTTP 应答包体中返回。

HTTP 应答包体格式

REST API 的应答包体也是 JSON 格式,其格式符合如下特征:
{
"ActionStatus": "OK",
"ErrorInfo": "",
"ErrorCode": 0,
"RequestId": "Id-70e312f1de024af5a36714b7b71da224-O-Seq-63504"
// REST API 其他应答内容
}
应答包体中必然包含 ActionStatus、ErrorInfo、ErrorCode、RequestId 这三个属性,其含义如下:
字段
类型
说明
ActionStatus
String
请求处理的结果,OK 表示处理成功,FAIL 表示失败,如果为 FAIL,ErrorInfo 带上失败原因
ErrorInfo
String
失败原因
ErrorCode
Integer
错误码,0为成功,其他为失败,可查询 错误码表 得到具体的原因
RequestId
String
唯一请求 ID,每次请求都会返回,定位问题时需要提供该次请求的 RequestId

调用示例

以下为通过 REST API 来 获取 App 中所有群组 示例。
HTTPS 请求:
POST /v4/group_open_http_svc/get_appid_group_list?usersig=xxx&identifier=admin&sdkappid=88888888&random=99999999&contenttype=json HTTP/1.1
Host: console.tim.qq.com
Content-Length: 22
{
"Limit": 2
}
HTTPS 应答:
HTTP/1.1 200 OK
Server: nginx/1.7.10
Date: Fri, 09 Oct 2015 02:59:55 GMT
Content-Length: 156
Connection: keep-alive
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: X-Requested-With
Access-Control-Allow-Methods: POST

{
"ActionStatus": "OK",
"ErrorCode": 0,
"GroupIdList": [
{
"GroupId": "@TGS#1YTTZEAEG"
},
{
"GroupId": "@TGS#1KVTZEAEZ"
}
],
"TotalCount": 58530
}

REST API 公共错误码

错误码
含义说明
60002
HTTP 解析错误 ,请检查 HTTP 请求 URL 格式。
60003
HTTP 请求 JSON 解析错误,请检查 JSON 格式。
60004
请求 URL 或 JSON 包体中账号或签名错误。
60005
请求 URL 或 JSON 包体中账号或签名错误。
60006
SDKAppID 失效,请核对 SDKAppID 有效性。
60007
REST 接口调用频率超过限制,请降低请求频率。
60008
服务请求超时或 HTTP 请求格式错误,请检查并重试。
60009
请求资源错误,请检查请求 URL。
60010
请求需要 App 管理员权限。
60011
SDKAppID 请求频率超限,请降低请求频率。
60012
REST 接口需要带 SDKAppID,请检查请求 URL 中的 SDKAppID。
60013
HTTP 响应包 JSON 解析错误。
60014
置换账号超时。
60015
请求包体账号类型错误,请确认账号为字符串格式。
60016
SDKAppID 被禁用。
60017
请求被禁用。
60018
请求过于频繁,请稍后重试。
60019
请求过于频繁,请稍后重试。
60020
您的专业版套餐包已到期并停用,请登录 即时通信 IM 购买页面 重新购买套餐包。购买后,将在5分钟后生效。
60021
RestAPI 调用来源 IP 非法。

FAQ

REST API 请求有概率超时,收不到任何响应?

1. Room 后台 REST 接口设置的超时时间是3s,调用方设置的超时时间应该长于3s。
2. telnet console.tim.qq.com 443确认能否连接服务端口。
3. 使用curl -I https://console.tim.qq.com简单测试看状态码是否为200。
4. 确认机器的 dns server 配置是内网 dns server,还是公共 dns server。如果是内网 dns server,请确保 dns server 网络出口和本机器网络出口 IP 所在地域运营商一致。
5. 建议业务调用方使用“长连接+连接池”模式。
说明:
由于 HTTPS 短连接建连耗时比较大,每次请求都有 TCP + tls 握手开销,所以建议 REST API 长连接接入。
使用标准 HTTP 库的场景:HTTP1.0 需要指定请求头部 Connection: keep-alive,HTTP1.1 默认支持长连接;基于 TCP 封装 HTTPS 请求的场景,可以复用 TCP 连接来收发请求。

帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈