实时音视频
实时音视频
文档指南
请输入
- 文档首页
实时音视频实时音视频服务端 API 参考转推直播查询合流转推任务状态 GetPushMixedStreamToCDNTask
复制全文
下载 pdf查询合流转推任务状态 GetPushMixedStreamToCDNTask
文档反馈
问问助手调用 GetPushMixedStreamToCDNTask 接口，查询由客户端或服务端发起的合流转推任务的状态和配置详情，包括任务起止时间、推流状态、流信息、布局及编码参数等。此接口适用于查询 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 可选 示例值：user1@@task123
要查询的转推直播任务 ID。
- 通过服务端发起时，该值为调用 StartPushMixedStreamToCDN 时传入的 TaskId。
- 通过客户端 SDK 发起时，TaskId 是按照 userId@@taskId 格式拼接而成的字符串；当传入的 taskId 为空时，这里的 TaskId 为 userId。
UserId String 可选 示例值：Your_UserId
客户端发起转推任务的用户 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[] 示例值：-
目标视频流列表。
Index Integer 示例值：0
视频流的唯一索引，用于在自定义布局中标识该视频流。在 Layout.regions.StreamIndex 中会引用此 Index 来配置对应视频流的布局。
在一个 StreamList 中，Stream.Index 不能重复。
UserId String 示例值：user1
目标视频流所属的用户 ID。
StreamType Integer 示例值：0
流的类型：
- 0：普通音视频流。
- 1：屏幕共享流。
ExcludeStreams Object 示例值：-
转推任务排除的音视频流。
StreamList Object[] 示例值：-
目标视频流列表。
Index Integer 示例值：0
视频流的唯一索引，用于在自定义布局中标识该视频流。在 Layout.regions.StreamIndex 中会引用此 Index 来配置对应视频流的布局。
在一个 StreamList 中，Stream.Index 不能重复。
UserId String 示例值：user1
目标视频流所属的用户 ID。
StreamType Integer 示例值：0
流的类型：
- 0：普通音视频流。
- 1：屏幕共享流。
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 计算出合理的码率。
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 示例值：-
合流布局配置。
MainVideoStream Object 示例值：-
垂直布局配置。
Index Integer 示例值：0
视频流的唯一索引，用于在自定义布局中标识该视频流。在 Layout.regions.StreamIndex 中会引用此 Index 来配置对应视频流的布局。
在一个 StreamList 中，Stream.Index 不能重复。
UserId String 示例值：user1
目标视频流所属的用户 ID。
StreamType Integer 示例值：0
流的类型：
- 0：普通音视频流。
- 1：屏幕共享流。
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, Canvas.Width)。默认值为 0。若传入该参数，服务端会对该参数进行校验，若不合法会返回错误码 InvalidParameter。
视频流对应区域左上角的实际坐标是通过画面尺寸和相对位置比例相乘，并四舍五入取整得到的。假如，画布尺寸为 1920, 视频流对应区域左上角的横坐标相对整体画面的比例为 0.33，那么该画布左上角的横坐标为 634（1920*0.33=633.6，四舍五入取整）。
LocationY Integer 示例值：0
视频流对应区域左上角的横坐标相对整体画面左上角原点的纵向位移，取值的范围为 [0, Canvas.Height)。默认值为 0。若传入该参数，服务端会对该参数进行校验，若不合法会返回错误码 InvalidParameter。
Width Integer 示例值：640
视频流对应区域宽度的像素绝对值，取值的范围为 (0, Canvas.Width]。
Height Integer 示例值：480
视频流对应区域高度的像素绝对值，取值的范围为 (0, Canvas.Height]。
ZOrder Integer 示例值：0
当多个流的画面有重叠时，使用此参数设置指定画面的图层顺序。
- 取值范围为 [0, 100]。0 表示该区域图像位于最下层，100 表示该区域图像位于最上层。
- 默认值为 0。
Alpha Float 示例值：0.5
画面的透明度。
- 取值范围为 (0.0, 1.0]。0.0 表示完全透明，1.0 表示完全不透明。
- 默认值为 1.0。
RenderMode Integer 示例值：0
画面的渲染模式。支持取值及含义如下：
- 0 ：按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形
- 1 ：按照显示区域的长宽比裁减视频，然后等比拉伸或缩小视频，占满显示区域。
- 2 ：按照原始画面的宽高比缩放视频，在显示区域居中显示。如果原始画面宽高比与指定的宽高比不同，就会导致画面有空缺，空缺区域为填充的背景色值。
- 3 ：按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形。
默认值为 0。
目前 0 和 3 均为按照指定的宽高直接缩放，但我们推荐你使用 3 以便与客户端实现相同逻辑。
SourceCrop Object 示例值：-
源流剪切功能，可以在源视频帧渲染之前进行裁剪，即预处理一次再渲染。
LocationX Float 示例值：0.1
裁剪后得到的视频帧左上角的横坐标相对裁剪前整体画面的比例，取值的范围为 [0.0, 1.0)。默认值为 0.0。
LocationY Float 示例值：0.1
裁剪后得到的视频帧左上角的纵坐标相对裁剪前整体画面的比例，取值的范围为 [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 示例值：-
PassthroughRTCSEIMessage Boolean 示例值：true
是否透传 RTC 流里的 SEI 信息。
- true：是。
- false：否。
默认值为 true。
VolumeIndicationInterval Float 示例值：3.0
设置用户音量回调的最小触发间隔。例如，设置为 3.0 时，即使音量在 3.0 秒内持续变化，SDK 也最多每 3 秒触发一次音量回调。如果音量在此间隔内无变化，则不触发回调。
仅当用户说话音量发生变化时此回调才会被触发。
- 取值范围为 [0.3, ∞]，单位为秒。
- 默认值为 2.0。
VolumeIndicationMode Boolean 示例值：false
是否开启音量指示模式。
- true：是。此时非关键帧中也可能携带 SEI 信息。
- false：否。此时只会在关键帧中携带 SEI 信息。
默认值为 false。
TalkVolume Integer 示例值：30
有效说话音量大小。取值范围为 [0, 255]，默认值为 0。
AddVolumeValue Boolean 示例值：false
SEI 中是否包含用户说话音量值。
- false：否。
- true：是。
默认值为 false。
SEIContentMode Integer 示例值：0
开启音量指示模式后，非关键帧携带 SEI 包含的信息类型。支持取值及含义如下：
- 0：全量信息。
- 1：只有音量信息和时间戳。
默认值为 0。
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=661e7ae5543cf&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,
"Width": 640,
"Height": 288,
"ZOrder": 0,
"Alpha": 1,
"CornerRadius": 0,
"RenderMode": 0,
"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_RequestId",
"Action": "GetPushMixedStreamToCDNTask",
"Version": "2023-11-01",
"Service": "rtc",
"Region": "cn-north-1"
}
}
错误码
最近更新时间：2026.07.18 23:50:57
这个页面对您有帮助吗？
有用
有用
无用
无用