Ceres拉流接口

Ceres 云端流拉取 API 文档（GraphQL） | TUTK SDK 开发手册

一、概述

本文档涵盖Ceres云端流拉取相关GraphQL接口，用于通知ceres服务从设备拉流并获取拉流URL，或终止已建立的流连接。支持三种流拉取初始化接口（适配不同认证场景）和一种流终止接口。

核心说明：

1、所有接口统一通过 POST 方法请求，请求路径为 /ceres；
2、支持 RTSP (over TLS) 和 HLS 两种流格式；
3、接口支持实时流拉取和回放流拉取，回放需指定相关回放参数；
4、需提前向TUTK申请 realm 信息，用于接口身份校验；
5、响应数据统一包含在 data 字段中，核心返回值为状态码（code）、拉流URL（url）和错误信息（msg）。

二、GraphQL 接口

所有接口请求地址：https://domain:port/ceres（实际部署时替换为真实域名和端口），请求方式均为 POST，Content-Type 默认为 application/json。

（一）init_streaming

通知ceres从设备拉流并获取拉流URL，适配P2P场景下基于 account/password 的认证方式，支持实时流拉取。

请求说明

项	说明
HTTP请求方式	POST（固定URL：https://domain:port/ceres）
请求头（Header）	Content-Type: `application/json`

输入参数

参数名	类型	必选	说明	备注
`device`	string	是	设备的UID，长度为20位或40位	核心标识参数
`account`	string	是	[P2P] 连线 avClientStart 中的 account（AVAPI）	P2P场景必填
`password`	string	是	[P2P] 连线 avClientStart 中的 password（AVAPI）	P2P场景必填
`protocol`	string	是	流格式，可选值：`rtsp`（rtsp over TLS）、`hls`	仅支持指定的两种格式
`realm`	string	是	realm，客户向TUTK申请	身份校验核心参数
`state`	string	是	客户自定义信息，用于第三方验证	自定义校验字段
`authkey`	string	否	[P2P] 设备 loginEx 的连线密码，使用 login 方式则无需填写	可选参数
`authToken`	string	否	第三方 auth 的 token	可选参数
`authType`	string	否	authToken 的类型，如：`Bearer` 或 `JWT`	与 authToken 配套使用
`channel`	int	否	设备的通道	默认使用默认通道

返回值

参数名	类型	说明
`code`	string	小于0失败，0为成功
`url`	string	拉流的地址（成功时返回有效地址，失败时为空字符串）
`msg`	string	失败的错误信息（成功时为空字符串）

响应状态码

状态码	徽章	说明
`200`	成功	请求成功，返回拉流信息
`400`	参数错误	必填参数缺失或格式错误
`401`	认证失败	realm无效、account/password错误或第三方验证失败

请求示例（curl）

init_streaming 请求示例（curl命令）

curl -XPOST -d '{ "query": "query { init_streaming( authToken:\"dm verify token\", authType:\"Bearer\", device:\"device UID\", account:\"user\", password:\"secret\", protocol:\"rtsp\", realm:\"rd\", state:\"state\", authkey:\"auth auth\", channel:0 ){ code, url, msg } }" }' https://domain:port/ceres

响应示例（成功）

init_streaming 成功响应示例

{ "data": { "init_streaming": { "code": 0, "url": "rtsp://192.168.55.10:8554/de89bbd28252c7bde7e09223f078529f85279e86", "msg": "" } } }

（二）init_streaming_v3

通知ceres从设备拉流并获取拉流URL，适配P2P场景下基于 avtoken/identity 的认证方式，支持实时流和回放流拉取。

请求说明

项	说明
HTTP请求方式	POST（固定URL：https://domain:port/ceres）
请求头（Header）	Content-Type: `application/json`

输入参数

参数名	类型	必选	说明	备注
`device`	string	是	设备的UID，长度为20位或40位	核心标识参数
`avtoken`	string	是	[P2P] 连线 avClientStart 中的 avtoken/av password（AVAPI）	P2P场景必填
`identity`	string	是	[P2P] 连线 avClientStart 中的 account 或 identity（AVAPI）	P2P场景必填
`protocol`	string	是	流格式，可选值：`rtsp`（rtsp over TLS）、`hls`	仅支持指定的两种格式
`realm`	string	是	realm，客户向TUTK申请	身份校验核心参数
`state`	string	是	客户自定义信息，用于第三方验证	自定义校验字段
`authkey`	string	否	[P2P] 设备 loginEx 的连线密码，使用 login 方式则无需填写	可选参数
`avType`	string	否	[P2P] av通道创建验证的密码类型，可选值：`authToken`、`authPass`	可选参数
`authToken`	string	否	第三方 auth 的 token	可选参数
`authType`	string	否	authToken 的类型，如：`Bearer` 或 `JWT`	与 authToken 配套使用
`channel`	int	否	设备的通道	默认使用默认通道
`playbackFile`	string	否	回放的文件名	回放场景必填
`playbackChannel`	int	否	回放的通道	回放场景必填
`playbackTimestamp`	int	否	回放的时间戳，最早不超过1年	回放场景必填

返回值

参数名	类型	说明
`code`	string	小于0失败，0为成功
`url`	string	拉流的地址（成功时返回有效地址，失败时为空字符串）
`msg`	string	失败的错误信息（成功时为空字符串）

响应状态码

状态码	徽章	说明
`200`	成功	请求成功，返回拉流信息
`400`	参数错误	必填参数缺失、格式错误或回放场景参数不完整
`401`	认证失败	realm无效、avtoken/identity错误或第三方验证失败

请求示例（curl）

init_streaming_v3 请求示例（curl命令）

curl -XPOST -d '{ "query": "query { init_streaming_v3( device:\"device UID\", authToken:\"dm verify token\", authType:\"Bearer\", avtoken:\"user\", authkey:\"secret\", avType:\"authToken\", protocol:\"rtsp\", identity:\"admin\", realm:\"rd\", state:\"state\", channel:0 ){ code, url, msg } }" }' https://domain:port/ceres

响应示例（成功）

init_streaming_v3 成功响应示例

{ "data": { "init_streaming_v3": { "code": 0, "url": "rtsp://192.168.55.10:8554/de89bbd28252c7bde7e09223f078529f85279e86", "msg": "" } } }

（三）init_streaming_v4

通知ceres从设备拉流并获取拉流URL，适配基于设备 credential 的认证方式，支持实时流和回放流拉取，配置更简洁。

请求说明

项	说明
HTTP请求方式	POST（固定URL：https://domain:port/ceres）
请求头（Header）	Content-Type: `application/json`

输入参数

参数名	类型	必选	说明	备注
`device`	string	是	设备的UDID	核心标识参数
`credential`	string	是	设备的连线凭证/秘钥：credential	认证核心参数
`protocol`	string	是	流格式，可选值：`rtsp`（rtsp over TLS）、`hls`	仅支持指定的两种格式
`realm`	string	是	realm，客户向TUTK申请	身份校验核心参数
`state`	string	是	客户自定义信息，用于第三方验证	自定义校验字段
`authToken`	string	否	第三方 auth 的 token	可选参数
`authType`	string	否	authToken 的类型，如：`Bearer` 或 `JWT`	与 authToken 配套使用
`channel`	int	否	设备的通道	默认使用默认通道
`playbackFile`	string	否	回放的文件名	回放场景必填
`playbackChannel`	int	否	回放的通道	回放场景必填
`playbackTimestamp`	int	否	回放的时间戳，最早不超过1年	回放场景必填

返回值

参数名	类型	说明
`code`	string	小于0失败，0为成功
`url`	string	拉流的地址（成功时返回有效地址，失败时为空字符串）
`msg`	string	失败的错误信息（成功时为空字符串）

响应状态码

状态码	徽章	说明
`200`	成功	请求成功，返回拉流信息
`400`	参数错误	必填参数缺失、格式错误或回放场景参数不完整
`401`	认证失败	realm无效、credential错误或第三方验证失败

请求示例（curl）

init_streaming_v4 请求示例（curl命令）

curl -XPOST -d '{ "query": "query { init_streaming_v4( authToken:\"dm verify token\", authType:\"Bearer\", device:\"device UID\", credential:\"credential\", protocol:\"rtsp\", realm:\"rd\", state:\"state\", channel:0 ){ code, url, msg } }" }' https://domain:port/ceres

响应示例（成功）

init_streaming_v4 成功响应示例

{ "data": { "init_streaming_v4": { "code": 0, "url": "rtsp://192.168.55.10:8554/de89bbd28252c7bde7e09223f078529f85279e86", "msg": "" } } }

（四）terminate_streaming

通知ceres停止拉流，释放相关连接资源。

请求说明

项	说明
HTTP请求方式	POST（固定URL：https://domain:port/ceres）
请求头（Header）	Content-Type: `application/json`

输入参数

参数名	类型	必选	说明	备注
`device`	string	是	device UID	核心标识参数
`state`	string	是	客户自定义信息，用于第三方验证	自定义校验字段
`protocol`	string	否	流格式，可选值：`rtsp`（rtsp over TLS）、`hls`	可选参数，指定需终止的流格式
`authToken`	string	否	第三方验证token，用于身份校验	可选参数，用于验证
`authType`	string	否	token类型，如：`Bearer` 或 `JWT`	与 authToken 配套使用
`playbackFile`	string	否	回放的文件名	回放流终止时必填
`channel`	int	否	需终止的通道编号	多通道场景建议指定

返回值

参数名	类型	说明
`code`	string	小于0失败，0为成功
`msg`	string	失败的错误信息（成功时为空字符串）

响应状态码

状态码	徽章	说明
`200`	成功	请求成功，流连接已终止
`400`	参数错误	必填参数缺失或格式错误
`401`	认证失败	第三方验证失败或权限不足
`404`	未找到	指定设备或流连接不存在

请求示例（curl）

terminate_streaming 请求示例（curl命令）

curl -XPOST -d '{ "query": "query { terminate_streaming( authToken:\"dm verify token\", authType:\"Bearer\", device:\"device UID\", state:\"state\", channel:0 ){ code, msg } }" }' https://domain:port/ceres

响应示例（成功）

terminate_streaming 成功响应示例

{ "data": { "terminate_streaming": { "code": 0, "msg": "" } } }

三、错误码说明

HTTP错误码：400（请求错误），具体错误原因通过返回体中的 code 字段和 msg 字段说明。

错误码（code）	错误消息（msg）	说明	处理建议
`0`	""（空字符串）	Success（操作成功）	-
`-1`	设备连线失败	SDK返回报错，或者已经有在拉取其他格式的流	检查设备状态，确认无其他流连接占用，重试拉流
`-2`	协议不支持	目前只支持 `hls` 或者 `rtsp`（rtsp over TLS）	使用支持的流格式重新请求
`-3`	验证失败	第三方验证失败	检查 authToken 有效性和权限配置
`-4`	参数错误	部分参数错误	对照接口文档检查参数格式和必填项
`-5`	通道占用	指定通道已被其他流连接占用	终止该通道已有连接后重试，或更换通道编号

错误响应示例

接口错误响应示例

{ "data": { "init_streaming": { "code": -3, "msg": "verify error", "url": "" } } }

四、备注信息

（一）设备规格

图像编码：H.264
音频编码：AAC ADTS（支持 8k / 44.1k / 48k Hz 采样率）

（二）自动关闭情形

RTSP 流：1分钟内未被使用，将自动关闭连接；
HLS 流：30秒内未收到 m3u8 请求，将自动关闭连接；
每个设备当前播放只支持一种流格式，如果已经在播放 RTSP，那么另外一个客户的想要 HLS 流是不被允许；
同个客户端需重新连接设备拉流时，需调用 terminate_streaming 关闭上次连接，或等待1分钟超时；
服务器如果30秒内没有收到设备任何数据，将关闭连接。

（三）测试推荐格式

分辨率：1080p
帧率：25 fps
音频：AAC（8k Hz 采样率）

（四）RTSP 流测试方法

使用 stunnel 工具将加密的 RTSP 流代理为本地裸流；
播放器连接本地代理的裸流地址进行播放。