You need to enable JavaScript to run this app.
导航
实时音视频
  • 文档首页
    • /实时音视频/实时音视频/服务端 API 参考/转推直播/开始合流转推 StartPushMixedStreamToCDN
开始合流转推 StartPushMixedStreamToCDN
最近更新时间：2025.09.09 11:48:30首次发布时间：2024.01.03 20:25:17
复制全文
我的收藏
有用
有用
无用
无用

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

注意

在使用合流转推功能前，你必须已经在控制台上开启转推直播服务。

在实时音视频通话场景中，若需将房间内的多路音视频流合并为一路并推送至指定的 CDN 地址，你可通过调用此接口实现。

你可以根据需要设定应用标识、房间 ID、任务ID 以及推流地址等信息，同时可选配置音视频编码参数和布局模式。调用后，接口将返回任务启动状态，确保音视频流顺利推送至CDN。

如果转推直播任务状态发生变化，你在控制台上设置的回调地址会接收任务状态相关回调。

使用说明

接口行为

在一个房间内，自定义布局下你最多只能将 30 路流合为一路流，其他布局下你最多只能将 17 路流合为一路流。若超出最大合流数限制，会返回 InvalidParameter 错误。

同一 TaskId 不能同时开启合流转推和单流转推任务。

注意事项

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

请求说明

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

调试

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

请求参数

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

Query

参数
类型
是否必选
示例值
描述
Action
String
是
StartPushMixedStreamToCDN
接口名称。当前 API 的名称为 StartPushMixedStreamToCDN。
Version
String
是
2023-11-01
接口版本。当前 API 的版本为 2023-11-01。

Body

参数
类型
是否必选
示例值
描述
AppId
String
是
661e****543cf
你的音视频应用的唯一标志，参看获取 AppId。
BusinessId
String
否
B****23
业务标识
RoomId
String
是
Room1
房间的 ID，是房间的唯一标志
TaskId
String
是
Task1

合流转推任务 ID。你必须对每个合流转推任务设定 TaskId，且在后续进行任务更新和结束时也须使用该 TaskId。

TaskId 是任务的标识，在一个 AppId 的 RoomId 下 taskId 是唯一的，不同 AppId 或者不同 RoomId 下 TaskId 可以重复，因此 AppId + RoomId + TaskId 是任务的唯一标识，可以用来标识指定 AppId 下某个房间内正在运行的任务，从而能在此任务运行中进行更新或者停止此任务。

关于 TaskId 及以上 Id 字段的命名规则符合正则表达式：[a-zA-Z0-9_@\-\.]{1,128}

若任务运行中，使用相同的 TaskId 重复调用开始接口不会导致请求失败，BaseResponse.Result 会提示 The task has been started. Please do not call the startup task interface repeatedly。
TargetStreams
Object
否
-
你可以通过本参数设定需要转推的音视频流。如果参数为空，默认对房间内所有人进行转推。自定布局下最多 30 路音视频流，其他布局下最多 17 路音视频流。此参数中的 stream 不得和 ExcludeStreams 中重复。
StreamList
Object[]
否
-
音视频流列表，由Stream组成，可以为空。为空时，表示订阅房间内所有流。在一个 StreamList 中，Stream.Index 不能重复。
ExcludeStreams
Object
否
-
你可以通过本参数设定不需要转推的音视频流，即转推流的黑名单。参数默认为空。黑名单中的流自定布局下最多 30 路音视频流，其他布局下最多 17 路音视频流。不支持将屏幕流添加到黑名单中。此参数中的 stream 不得和 TargetStreams 中重复。
StreamList
Object[]
否
-
音视频流列表，由Stream组成，可以为空。为空时，表示订阅房间内所有流。在一个 StreamList 中，Stream.Index 不能重复。
PushURL
String
是
rtmp://xxx/xxx
推流 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。
MainVideoStream
Object
否
-
在垂直布局模式下生效，指定主画面流的属性。垂直布局时，此参数必填。
CustomLayout
Object
否
-
使用自定义布局模式时，使用此参数进行具体设置。
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
否
-
空间音频配置。若合流转推的音频参数设置为单声道，空间音频无效。
PushStreamMode
Integer
否
0

转推直播推流模式，用于控制触发推流的时机。支持取值及含义如下：

  • 0：房间内有用户推 RTC 流时即触发 CDN 推流。
  • 1：调用接口发起推流任务后，无论房间内是否有用户推 RTC 流,均可触发 CDN 推流。
默认值为 0。
任务超时逻辑不变，依然是无用户推流即判定为超时。
SEIConfig
Object
否
-
SEI 相关配置。

返回参数

本接口无特有的返回参数。公共返回参数请见返回结构。
其中返回值 Result 仅在请求成功时返回 ok，失败时为空。

请求示例

POST https://rtc.volcengineapi.com?Action=StartPushMixedStreamToCDN&Version=2023-11-01
{
    "AppId": "661e****543cf",
    "BusinessId": "B****23",
    "RoomId": "Room1",
    "TaskId": "Task1",
    "PushURL": "rtmp://xxx/xxx"
}

返回示例

{
    "Result": "ok",
    "ResponseMetadata": {
        "RequestId": "20230****10420",
        "Action": "StartPushMixedStreamToCDN",
        "Version": "2023-11-01",
        "Service": "rtc",
        "Region": "cn-north-1"
    }
}

错误码

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