查询合流转推任务状态 GetPushMixedStreamToCDNTask--实时音视频-火山引擎

文档中心

立即注册

导航

查询合流转推任务状态 GetPushMixedStreamToCDNTask

最近更新时间：2024.10.30 14:22:23首次发布时间：2024.01.03 20:25:17

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

在实时音视频通话场景中，若需查询特定房间下合流转推任务的详细信息，你可以通过调用此接口实现。

通过指定应用标识、房间 ID 及任务 ID，你能够获取任务的当前状态和配置详情，任务的开始与结束时间、状态、停止原因、推流状态等详细信息，以及音视频流的具体配置。此接口适用于查询 72 小时内启动的合流转推任务。

你可以查询由客户端或服务端发起的合流转推任务，但返回的参数结构均为服务端的参数结构。

使用说明

前置条件

在查询前，你必须已经在控制台上开通转推直播服务。

注意事项

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

请求说明

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

调试

API Explorer

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

去调试

请求参数

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

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`GetPushMixedStreamToCDNTask`	接口名称。当前 API 的名称为 `GetPushMixedStreamToCDNTask`。
Version	String	是	`2023-11-01`	接口版本。当前 API 的版本为 `2023-11-01`。
AppId	String	是	`661e****543cf`	你的音视频应用的唯一标志
RoomId	String	是	`Room1`	房间的 ID，是房间的唯一标志
TaskId	String	否	`Task1`	要查询的转推直播任务 ID。通过服务端发起时，该值为调用 OpenAPI 时传入的 TaskId。通过客户端 SDK 发起时，TaskId 是按照 `userId`@@`taskId` 格式拼接而成的字符串；当传入的 taskId 为空时，这里的 TaskId 为 `userId`。 `TaskId` 和 `UserId` 均为非必填参数，但是你需要至少填一个参数以保证可以正常发起请求。
UserId	String	否	`user1`	客户端发起转推任务的用户 ID。你在客户端发起多个任务，当使用该接口进行查询时：查询第一个任务时，`UserId` 可以传入发起转推任务的用户 `UserId`，`TaskId` 传入空字符串；或直接将该用户的 `UserId` 传入 `TaskId`。查询第二个以上任务时，`UserId` 和 `TaskId` 为发起转推任务的用户 `UserId` 和 `TaskId`。

返回参数

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

参数	类型	示例值	描述
PushMixedStreamToCDNTask	Object	`-`	合流转推任务信息
StartTime	Long	`1677237518000`	任务开始时间戳，Unix 时间，单位为毫秒
EndTime	Long	`1677239022000`	任务结束时间戳，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`。
TargetStreams	Object	`-`	转推任务包含的音视频流
StreamList	Object[]	`-`	音视频流列表，由`Stream`组成，可以为空。为空时，表示订阅房间内所有流。在一个 `StreamList` 中，`Stream.Index` 不能重复。
Index	Integer	`0`	在自定义布局中，使用 `Index` 对流进行标志。后续在 `Layout.regions.StreamIndex` 中，你需要使用 `Index` 指定对应流的布局设置。
UserId	String	`user1`	用户 ID，表示这个流所属的用户。
StreamType	Integer	`0`	流的类型。支持取值及含义如下： `0`：普通音视频流， `1`：屏幕流。默认值为`0`。
ExcludeStreams	Object	`-`	转推任务排除的音视频流
StreamList	Object[]	`-`	音视频流列表，由`Stream`组成，可以为空。为空时，表示订阅房间内所有流。在一个 `StreamList` 中，`Stream.Index` 不能重复。
Index	Integer	`0`	在自定义布局中，使用 `Index` 对流进行标志。后续在 `Layout.regions.StreamIndex` 中，你需要使用 `Index` 指定对应流的布局设置。
UserId	String	`user1`	用户 ID，表示这个流所属的用户。
StreamType	Integer	`0`	流的类型。支持取值及含义如下： `0`：普通音视频流， `1`：屏幕流。默认值为`0`。
PushURL	String	`rtmp://xxxxxx`	推流 CDN 地址。仅支持 RTMP 协议。
Encode	Object	`-`	输出的音视频编码参数。
VideoWidth	Integer	`640`	画面宽度。取值范围为 `[2, 1920]`，必须是偶数，单位为像素，默认值为 `640`。该参数在垂直布局和并排布局下生效，自定义布局下请使用 `canvas.Width` 设置画面宽度。
VideoHeight	Integer	`480`	画面高度，取值范围为 `[2, 1920]`，必须是偶数，单位为像素，默认值为 `480`。该参数在垂直布局和并排布局下生效，自定义布局下请使用 `canvas.Height` 设置画面宽度。
VideoFps	Integer	`15`	视频帧率。取值范围为 `[1,60]`，单位为 `FPS`，默认值为 `15`。
VideoBitrate	Integer	`0`	视频码率。取值范围为 `[0,10000]`，单位为 Kbps，默认值为 `0`。 `0` 表示自适应码率，会自动根据 `VideoFps` , `VideoWidth` 以及`VideoHeight` 计算出合理的码率。自适应码率模式下，RTC 默认不会设置超高码率。如果订阅屏幕流，建议自行设置高码率。不同场景下设置码率等视频发布参数,请参考设置视频发布参数。
VideoCodec	Integer	`0`	视频编码协议。支持取值及含义如下： `0`：`H.264` `1`：`ByteVC1` 默认值为 `0`。
VideoGop	Integer	`4`	输出视频 GOP。取值范围为 `[1,5]`，单位为秒，默认值为 `4`。
AudioCodec	Integer	`0`	音频编码协议。仅支持取 `0`，表示 AAC 编码协议。
AudioProfile	Integer	`0`	音频配置文件类型。支持取值及含义如下： `0` :采用 LC 规格； `1`: 采用 HE-AAC v1 规格； `2`: 采用 HE-AAC v2 规格。此时，只支持输出流音频声道数为双声道。默认值为 `0`。
AudioBitrate	Integer	`64`	音频码率。取值范围为 `[32,192]`,单位为 `Kbps`。该参数若不填，RTC 会根据音频配置文件类型、采样率、声道数的配置生成音频码率取值。该参数若填写，实际生效的码率也会随着音频配置文件类型、采样率、声道数的配置而变化。若你发现生效的码率值没有达到你设定的值，可能是该值已经超过该场景下的极限码率。
AudioSampleRate	Integer	`48000`	音频采样率。可取值为：`{32000,44100，48000}`，单位为 Hz，默认值为 `48000`。
AudioChannels	Integer	`2`	音频声道数。支持取值及含义如下： `1`：单声道。 `2`：双声道。默认值为 `2`。
Layout	Object	`-`	房间内多路流合为一路时的布局参数
LayoutMode	Integer	`0`	布局模式。支持取值及含义如下： `0`：自适应布局。 `1`：垂直布局 `2` ：自定义布局。 `3` ：并排布局默认值为`0`
MainVideoStream	Object	`-`	在垂直布局模式下生效，指定主画面流的属性。垂直布局时，此参数必填。
Index	Integer	`0`	在自定义布局中，使用 `Index` 对流进行标志。后续在 `Layout.regions.StreamIndex` 中，你需要使用 `Index` 指定对应流的布局设置。
UserId	String	`user1`	用户 ID，表示这个流所属的用户。
StreamType	Integer	`0`	流的类型。支持取值及含义如下： `0`：普通音视频流， `1`：屏幕流。默认值为`0`。
CustomLayout	Object	`-`	使用自定义布局模式时，使用此参数进行具体设置。
Canvas	Object	`-`	整体屏幕（画布）的宽高以及背景色。
Width	Integer	`640`	整体屏幕（画布）的宽度，取值范围为 `[2, 1920]`，必须是偶数，单位为像素，默认值为 `640`。
Height	Integer	`480`	整体屏幕（画布）的高度，取值范围为 `[2, 1920]`，必须是偶数，单位为像素，默认值为 `480`。
Background	String	`#000000`	整体屏幕（画布）的背景色, 范围为 `#000000 ~ #ffffff` (大小写均可)，格式为 #RGB(16进制)，默认值为 `#000000`（黑色）。
BackgroundImage	String	`-`	背景图片的 URL。长度最大为 1024 byte。可以传入的图片的格式包括：`JPG`, `JPEG`, `PNG`。如果背景图片的宽高和整体屏幕的宽高不一致，背景图片会缩放到铺满屏幕。如果你设置了背景图片，背景图片会覆盖背景色。
Regions	Object[]	`-`	在自定义布局模式下，你可以使用 `Regions` 对每一路视频流进行画面布局设置。其中，每个 `Region` 对一路视频流进行画面布局设置。自定义布局模式下，对于 `StreamList` 中的每个 `Stream`，`Regions` 中都需要给出对应的布局信息，否则会返回请求不合法的错误。即 `Regions.Region.StreamIndex` 要与 `TargetStreams.StreamList.Stream.Index` 的值一一对应，否则自定义布局设置失败，返回 `InvalidParameter` 错误码。当传入的必填参数值不合法时，返回错误码 `InvalidParameter` 。
StreamIndex	Integer	`0`	流的标识。这个标志应和 `TargetStreams.StreamList.Stream.Index` 对应。
LocationX	Integer	`0`	视频流对应区域左上角的横坐标相对整体画面左上角原点的横向位移，取值的范围为 `[0.0, Canvas.Width)`。默认值为 `0`。若传入该参数，服务端会对该参数进行校验，若不合法会返回错误码 `InvalidParameter`。视频流对应区域左上角的实际坐标是通过画面尺寸和相对位置比例相乘，并四舍五入取整得到的。假如，画布尺寸为`1920`, 视频流对应区域左上角的横坐标相对整体画面的比例为 `0.33`，那么该画布左上角的横坐标为 `634`（1920*0.33=633.6，四舍五入取整）。
LocationY	Integer	`0`	视频流对应区域左上角的横坐标相对整体画面左上角原点的纵向位移，取值的范围为 `[0.0, Canvas.Height)`。默认值为 `0`。若传入该参数，服务端会对该参数进行校验，若不合法会返回错误码 `InvalidParameter`。
Width	Integer	`640`	视频流对应区域宽度的像素绝对值，取值的范围为 `(0.0, Canvas.Width]`。
Height	Integer	`480`	视频流对应区域高度的像素绝对值，取值的范围为 `(0.0, Canvas.Height]`。
ZOrder	Integer	`0`	当多个流的画面有重叠时，使用此参数设置指定画面的图层顺序。取值范围为 `[0, 100]`，默认值为 `0`。`0` 表示该区域图像位于最下层，`100` 表示该区域图像位于最上层。
Alpha	Float	`1`	画面的透明度，取值范围为 `(0.0, 1.0]`，默认值为 `1.0`。`0.0` 表示完全透明，`1.0` 表示完全不透明。
RenderMode	Integer	`0`	画面的渲染模式。支持取值及含义如下： `0` ：按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形 `1` ：按照显示区域的长宽比裁减视频，然后等比拉伸或缩小视频，占满显示区域。 `2` ：按照原始画面的宽高比缩放视频，在显示区域居中显示。如果原始画面宽高比与指定的宽高比不同，就会导致画面有空缺，空缺区域为填充的背景色值。 `3` ：按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形。默认值为 `0`。目前 `0` 和 `3` 均为按照指定的宽高直接缩放，但我们推荐你使用 `3` 以便与客户端实现相同逻辑。
SourceCrop	Object	`-`	源流剪切功能，可以在源视频帧渲染之前进行裁剪，即预处理一次再渲染。
LocationX	Float	`0`	裁剪后得到的视频帧左上角的横坐标相对裁剪前整体画面的比例，取值的范围为 `[0.0, 1.0)`。默认值为 `0.0`。
LocationY	Float	`0`	裁剪后得到的视频帧左上角的纵坐标相对裁剪前整体画面的比例，取值的范围为 `[0.0, 1.0)`。默认值为 `0.0`。
WidthProportion	Float	`0.5`	裁剪后得到的视频帧宽度相对裁剪前整体画面宽度的比例，取值范围为 `(0.0, 1.0]`。默认值为 `1.0`。
HeightProportion	Float	`0.5`	裁剪后得到的视频帧高度相对裁剪前整体画面宽度的比例，取值范围为 `(0.0, 1.0]`。默认值为 `1.0`。
AlternateImage	String	`-`	补位图片的 url。长度不超过 1024 个字符串。在 `Region.StreamIndex` 对应的视频流没有发布，或被暂停采集时，`AlternateImage` 对应的图片会填充 `Region` 对应的画布空间。当视频流被采集并发布时，`AlternateImage` 不造成任何影响。可以传入的图片的格式包括：JPG, JPEG, PNG。当图片和画布尺寸不一致时，图片根据 `RenderMode` 的设置，在画布中进行渲染。
ApplySpatialAudio	Boolean	`-`	该路流对应的用户是否开启空间音频效果。 `true`：开启空间音频效果。 `false`：关闭空间音频效果。默认值为 `true`
SpatialPosition	Integer[]	`[0,0,0]`	空间音频下，房间内指定用户所在位置的三维坐标，默认值为`[0,0,0]`。数组长度为`3`，三个值依次对应`X`,`Y`,`Z`，每个值的取值范围为 `[-100,100]`。
CornerRadius	Float	`0.1`	转推直播下边框圆角半径与画布宽度的比例值，取值范围为 `[0,1]`。默认值为 `0`，表示没有圆角效果。圆角半径的像素位不能超过 Region 宽高最小值的一半，否则不会出现圆角效果。
MediaType	Integer	`0`	该路流参与混流的媒体类型。支持取值及含义如下： `0`：音视频 `1`：纯音频 `2`：纯视频默认值为 `0`。例如该路流为音视频流，`MediaType`设为`1`，则只混入音频内容。
AlternateImageFillMode	Integer	`0`	画面的渲染模式。支持取值及含义如下： `0`：按照用户原始视频帧比例进行缩放 `1`：保持图片原有比例默认值为 `0`。
Control	Object	`-`
MediaType	Integer	`0`	流的类型，用于全局控制订阅的流的类型。支持取值及含义如下： `0` ：音视频； `1` ：纯音频。默认值为 `0`。
FrameInterpolationMode	Integer	`0`	选择补帧模式。支持取值及含义如下： `0`：补最后一帧。 `1`：补黑帧默认值为`0`。自动布局模式下，没有补帧的逻辑。补帧是指在音视频录制或合流转推时，视频的帧率通常是固定的。但是，因为网络波动或其他原因，实际帧率可能无法达到预设的帧率。此时，需要补帧以保持视频流畅。补最后一帧意味着补充的视频帧和中断前的最后一帧相同，此时看到的画面可能会有短暂静止；补黑帧意味着补充的视频帧是全黑的。使用占位图、补帧和上一帧的关系: 你可以在 `Region` 中传入 `Alternateimage` 字段设置占位图,在 `Control` 中传入`FrameInterpolationMode` 字段设置补帧模式,但占位图优先级高于补帧模式。在 `Region.StreamIndex` 对应的视频流停止发布时, `Region` 对应的画布空间会根据设置填充占位图或补帧。但当视频流为屏幕流时，补帧模式不生效。当 `Region.StreamIndex` 对应的视频流发布后停止采集或推送时, `Region` 对应的画布空间会填充上一帧。当 `Region.StreamIndex` 对应的视频流发布时,设置的占位图或补顿模式不造成任何影响。
MaxIdleTime	Integer	`180`	任务的空闲超时时间，超过此时间后，任务自动终止。取值范围为 `[10, 86400]`,单位为秒，默认值为 `180`。
SpatialConfig	Object	`-`	空间音频配置。若合流转推的音频参数设置为单声道，空间音频无效。
EnableSpatialRender	Boolean	`false`	是否开启空间音频处理功能。 `false`：关闭。 `true`：开启默认值为 `false`。
AudienceSpatialPosition	Integer[]	`[0,0,0]`	观众所在位置的三维坐标，默认值为`[0,0,0]`。数组长度为`3`，三个值依次对应`X`,`Y`,`Z`，每个值的取值范围为 `[-100,100]`。
AudienceSpatialOrientation	Object	`-`	设置观众朝向。各个向量两两垂直，如果传入的值没有保证两两垂直，自动赋予默认值。默认值为：`forward` = `[1, 0, 0]`, `right` = `[0, 1, 0]`, `up` = `[0, 0, 1]`。
Up	Float[]	`[0, 0, 1]`	头顶朝向
Right	Float[]	`[0, -1, 0]`	右边朝向
Forward	Float[]	`[1, 0, 0]`	前方朝向
PushStreamMode	Integer	`0`	转推直播推流模式，用于控制触发推流的时机。支持取值及含义如下： `0`：房间内有用户推 RTC 流时即触发 CDN 推流。 `1`：调用接口发起推流任务后，无论房间内是否有用户推 RTC 流,均可触发 CDN 推流。默认值为 `0`。任务超时逻辑不变，依然是无用户推流即判定为超时。
SEIConfig	Object	`-`	SEI 相关配置。
UserConfigExtraInfo	String	`-`	设置SEI数据结构中 `app_data` 参数的值，最大长度为 `4096`。此参数支持动态更新。
PassthroughRTCSEIMessage	Boolean	`true`	是否透传 RTC 流里的 SEI 信息。 `true`：是。 `false`：否。默认值为 `true`。
VolumeIndicationInterval	Float	`2`	用户说话音量的回调间隔。取值范围为 `[0.3,∞]`，单位为秒，默认值为 `2`。仅当用户说话音量发生变化时此回调才会被触发。
VolumeIndicationMode	Boolean	`false`	是否开启音量指示模式。 `true`：是。此时非关键帧中也可能携带 SEI 信息。 `false`：否。此时只会在关键帧中携带 SEI 信息。默认值为 `false`。若 `VolumeIndicationMode` = `true` 的同时设置 `MediaType` = `1`，该流推向 CDN 地址时，服务端会补黑帧。关于音量指示模式的用法，参看音量指示模式。
TalkVolume	Integer	`30`	有效说话音量大小。取值范围为`[0,255]`，默认值为`0`。
AddVolumeValue	Boolean	`false`	SEI 中是否包含用户说话音量值。 `false`：否。 `true`：是。默认值为 `false`。
SEIContentMode	Integer	`0`	开启音量指示模式后，非关键帧携带 SEI 包含的信息类型。支持取值及含义如下： `0`：全量信息。 `1`：只有音量信息和时间戳。默认值为 `0`。关于 SEI 结构，参看服务端合流转推 SEI 结构
SEIPayLoadType	Integer	`100`	设置 SEI 的 `Payload Type`，对服务端合流转推 SEI 和 RTC 透传SEI 均生效。支持取值为 `5` 或 `100`，默认为 `100`。
SEIPayloadUUID	String	`566f6c63656e67696e65525443534549`	该字段为长度为 32 位的 16 进制字符，每个字符的范围为 `a-f，A-F，0-9`，不可包含 `-`。如果校验失败，会返回错误码 `InvalidParameter`。仅当 `SEIPayLoadType`=`5`时，该字段需要填写，`SEIPayLoadType`=`100`时，该字段内容会被忽略。此参数仅对 RTC 透传SEI 生效。当用户设置 `SEIPayloadType` = `5` 时，服务端合流转推SEI 的 `SEIPayloadUUID` 为固定值：`566f6c63656e67696e65525443534549`，对应16位字符串 `VolcengineRTCSEI`。

请求示例

GET https://rtc.volcengineapi.com?Action=GetPushMixedStreamToCDNTask&Version=2023-11-01&AppId=661e****543cf&RoomId=Room1&TaskId=Task1&UserId=user1

返回示例

{
    "Result": {
        "PushMixedStreamToCDNTask": {
            "StartTime": 1677237518000,
            "EndTime": 1677239022000,
            "Status": 3,
            "StopReason": "StopByAPI",
            "PushStreamState": "6",
            "TargetStreams": {
                "StreamList": [
                    {
                        "Index": 1,
                        "UserId": "user1",
                        "StreamType": 0
                    }
                ]
            },
            "ExcludeStreams": {
                "StreamList": [
                    {
                        "Index": 3,
                        "UserId": "user3",
                        "StreamType": 1
                    }
                ]
            },
            "PushURL": "rtmp://xxxxxx",
            "Layout": {
                "LayoutMode": 2,
                "CustomLayout": {
                    "Canvas": {
                        "Width": 1280,
                        "Height": 720,
                        "Background": "#303342",
                        "BackgroundImage": "http://xxxxxx"
                    },
                    "Regions": [
                        {
                            "StreamIndex": 1,
                            "LocationX": 0,
                            "LocationY": 144,
                            "WidthProportion": 640,
                            "HeightProportion": 288,
                            "ZOrder": 0,
                            "Alpha": 1,
                            "CornerRadius": 0,
                            "RenderMode": 0,
                            "SourceCrop": {
                                "LocationX": 430,
                                "LocationY": 340,
                                "WidthProportion": 430,
                                "HeightProportion": 340
                            },
                            "AlternateImage": "http://xxxxx",
                            "SpatialPosition": [
                                1,
                                1,
                                1
                            ]
                        }
                    ]
                }
            },
            "Encode": {
                "VideoCodec": 0,
                "VideoBitrate": 1600,
                "VideoWidth": 1280,
                "VideoHeight": 720,
                "VideoFps": 15,
                "VideoGop": 4,
                "AudioCodec": 0,
                "AudioProfile": 0,
                "AudioBitrate": 128,
                "AudioSampleRate": 48000,
                "AudioChannels": 2
            },
            "Control": {
                "MediaType": 0,
                "FrameInterpolationMode": 0,
                "MaxIdleTime": 180,
                "VolumeIndicationInterval": 2,
                "VolumeIndicationMode": false,
                "TalkVolume": 0,
                "SpatialConfig": {
                    "AudienceSpatialPosition": [
                        0,
                        0,
                        0
                    ]
                },
                "PushStreamMode": 0
            }
        }
    },
    "ResponseMetadata": {
        "RequestId": "Your_****estId",
        "Action": "GetPushMixedStreamToCDNTask",
        "Version": "2023-11-01",
        "Service": "rtc",
        "Region": "cn-north-1"
    }
}

错误码

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