首页 > 文档中心 > 云端服务 > 智能音箱 > Ceres

CERES请求拉流接口

Ceres 云端流拉取 API 文档（GraphQL）

一、概述

本文档涵盖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 的认证方式，支持实时流拉取。

输入参数

参数名	类型	必选	说明	备注
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	失败的错误信息（成功时为空字符串）

请求示例（curl）

curl -XPOST -d '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"
    ){
        code,
        url,
        msg
    }
}' https://domain:port/ceres

响应示例（成功）

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

（二）init_streaming_v3

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

输入参数

参数名	类型	必选	说明	备注
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	失败的错误信息（成功时为空字符串）

请求示例（curl）

curl -XPOST -d '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"
    ){
        code,
        url,
        msg
    }
}' https://domain:port/ceres

响应示例（成功）

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

（三）init_streaming_v4

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

输入参数

参数名	类型	必选	说明	备注
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	失败的错误信息（成功时为空字符串）

请求示例（curl）

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

响应示例（成功）

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

（四）terminate_streaming

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

输入参数

参数名	类型	必选	说明	备注
device	string	是	device UID	核心标识参数
state	string	是	state, user info	自定义校验字段
protocol	string	否	流格式，可选值：rtsp（rtsp over TLS）、hls	可选参数，指定需终止的流格式
authToken	string	否	authToken, use to validate	可选参数，用于验证
authType	string	否	the token type, ex Bearer or JWT	与 authToken 配套使用
playbackFile	string	否	the filename of the playback	回放流终止时必填

返回值

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

请求示例（curl）

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

响应示例（成功）

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

三、错误码说明

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

错误码（code）	错误消息（msg）	说明
0	""（空字符串）	Success（操作成功）
-1	设备连线失败	SDK返回报错，或者已经有在拉取其他格式的流
-2	协议不支持	目前只支持 hls 或者 rtsp（rtsp over TLS）
-3	验证失败	第三方验证失败
-4	参数错误	部分参数错误

错误响应示例

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

四、备注信息

（一）设备规格

图像编码：H.264

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

（二）自动关闭情形

1. RTSP 流：1分钟内未被使用，将自动关闭连接；

2. HLS 流：30秒内未收到 m3u8 请求，将自动关闭连接；

3. 每个设备当前播放只支持一种流格式，如果已经在播放 RTSP，那么另外一个客户的想要 HLS 流是不被允许；

4. 同个客户端需重新连接设备拉流时，需调用 terminate_streaming 关闭上次连接，或等待1分钟超时；

5. 服务器如果30秒内没有收到设备任何数据，将关闭连接。

（三）测试推荐格式

分辨率：1080p

帧率：25 fps

音频：AAC（8k Hz 采样率）

（四）RTSP 流测试方法

当前返回的 RTSP 流为 SSL 加密格式，无法用一般的播放器直接播放，需通过以下步骤测试：

1. 使用 stunnel 工具将加密的 RTSP 流代理为本地裸流；

2. 播放器连接本地代理的裸流地址进行播放。