文档中心

实时音视频

转推直播

查询单流转推任务状态 GetPushSingleStreamToCDNTask

本文档 API 接口为最新版本接口，后续相关功能的新增都会在此更新，推荐使用最新版本接口。旧版接口文档请参考历史版本。

调用 GetPushSingleStreamToCDNTask 接口，查询由客户端或服务端发起的单流转推任务的状态和配置详情，包括任务起止时间、推流状态、流信息及推流地址等。

注意事项

请求频率：QPS 不得超过 60。

请求说明

请求方式：GET

请求地址：https://rtc.volcengineapi.com?Action=GetPushSingleStreamToCDNTask&Version=2023-11-01

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Query

Action String 必选示例值：GetPushSingleStreamToCDNTask

接口名称。当前 API 的名称为 GetPushSingleStreamToCDNTask。

Version String 必选示例值：2023-11-01

接口版本。当前 API 的版本为 2023-11-01。

AppId String 必选示例值：66****3cf

实时音视频应用的 AppId。可在控制台获取。

RoomId String 必选示例值：Your_RoomId

目标房间 ID。

TaskId String 可选示例值：Your_TaskId

要查询的转推直播任务 ID。

若为通过服务端的任务：该值为调用 StartPushSingleStreamToCDN 时传入的 TaskId。

若为通过客户端的任务：TaskId 为按照 userId@@taskId 格式拼接而成的字符串；当传入的 taskId 为空时，这里的 TaskId 为 userId。

注意

TaskId 和 UserId至少填一个。

UserId String 可选示例值：Your_UserId

客户端发起转推任务的用户 ID。若在客户端发起了多个任务：

查询第一个任务时，UserId 可以传入发起转推任务的用户 UserId，TaskId 传入空字符串；或直接将该用户的 UserId 传入 TaskId。

查询第二个以上任务时，UserId 和 TaskId 为发起转推任务的用户 UserId 和 TaskId。

返回参数

下表仅列出本接口特有的返回参数，公共返回参数请参见返回结构。

PushSingleStreamToCDNTask Object 示例值：-

单流转推任务信息。

StartTime Long 示例值：1677205841000

任务开始时间戳，Unix 时间，单位为毫秒

EndTime Long 示例值：1677205914000

任务结束时间戳，Unix 时间，单位为毫秒。0 表示任务未结束

Status Long 示例值：3

任务状态。

0：未知异常状态

1：未开始

2：运行中

3：已结束

4：任务运行失败

StopReason String 示例值：StopByAPI

任务停止的原因

返回为空：表示任务未结束

UnknownStopReason：未知停止原因

StopByAPI：用户主动调用服务端 OpenAPI 停止

StartTaskFailed：任务启动失败

IdleTimeOut：任务超过最大空闲时间

UserDisconnect：客户端用户主动退房/调用停止转推接口

PushStreamState Integer 示例值：6

推流状态

0：未获取到任务状态。建议稍后重新查询

1：未开始推流

2：首次连接 CDN 服务

3：正在重连 CDN 服务

4：连接 CDN 服务成功，正在尝试推流。

5：连接 CDN 服务成功，推流成功

6：已停止推流。

仅当Status=2 时，PushStreamState 有实际意义；当Status=3 时，PushStreamState=6; status 为其他值时，PushStreamState 均为0。

Stream Object 示例值：-

房间内转推的流。

UserId String 示例值：user1

流所属用户 ID。

StreamType Integer 示例值：0

流的类型。支持取值及含义如下：

0：普通音视频流。

1：屏幕流。

默认值为 0。

PushURL String 示例值：rtmp://xxxxx

推流地址。目前仅支持 rtmp 协议

Control Object

高级配置。

MediaType Integer 示例值：0

全局控制订阅的流的类型，支持的取值如下：

0：音视频。

1：纯音频。

默认值为 0。

MaxIdleTime Integer 示例值：180

任务的空闲超时时间，单位为秒。

任务启动后，系统会自动分配一个后端机器人订阅目标流。如果机器人在房间内始终没有订阅到目标流（例如目标用户不在房间或指定的流停止发布），任务就会处于“空闲状态”。空闲时间超过设定值，任务就会自动结束。

取值范围为 [10, 86400]。

默认值为 180。

请求示例

返回示例

错误码

您可访问公共错误码，获取更多错误码信息。

最近更新时间：2026.07.18 23:50:57

这个页面对您有帮助吗？

有用

无用