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

对于一个音视频通话，你可以将其中的多路音视频流合为一路，并将合并得到的音视频流通过 RTMP 协议推送到指定的推流地址（通常是 CDN 地址）。

你可以使用 StartPushMixedStreamToCDN 这个 OpenAPI 实现这一功能。

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

使用说明

接口行为

你可以调用 StartPushMixedStreamToCDN 接口，将指定音视频房间内的指定音视频流，按照指定的布局合为一路，并推送至指定的地址。

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

前置条件

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

调用接口

关于调用接口的服务地址、通信协议、字符编码和签名机制，参看调用 OpenAPI。

注意事项

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

请求说明

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

请求参数

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

Query

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

Body

参数	类型	是否必选	示例值	描述
AppId	String	是	`Your_AppId`	你的音视频应用的唯一标志
BusinessId	String	否	`Your_BusinessId`	业务标识
RoomId	String	是	`Your_RoomId`	房间的 ID，是房间的唯一标志
TaskId	String	是	`Your_TaskId`	合流转推任务 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 of Streams	否	`-`	你可以通过本参数设定需要转推的音视频流。如果参数为空，默认对房间内所有人进行转推。自定布局下最多 30 路音视频流，其他布局下最多 17 路音视频流。此参数中的 `stream` 不得和 `ExcludeStreams` 中重复。
ExcludeStreams	Object of Streams	否	`-`	你可以通过本参数设定不需要转推的音视频流，即转推流的黑名单。参数默认为空。黑名单中的流自定布局下最多 30 路音视频流，其他布局下最多 17 路音视频流。不支持将屏幕流添加到黑名单中。此参数中的 `stream` 不得和 `TargetStreams` 中重复。
PushURL	String	是	`rtmp://xxx/xxx`	推流 CDN 地址。仅支持 RTMP 协议。
Encode	Object of Encode	否	`-`	音视频编码参数
Layout	Object of Layout	否	`-`	房间内多路流合为一路时的布局参数
Control	Object of Control	否	`-`	配置选项。

Streams

参数	类型	是否必选	示例值	描述
StreamList	Array of Stream	否	`-`	由`Stream`组成的列表，可以为空。为空时，表示订阅房间内所有流。在一个 `StreamList` 中，`Stream.Index` 不能重复。

Encode

参数	类型	是否必选	示例值	描述
VideoWidth	Integer	否	`640`	输出画面的宽度。默认值为`640`，范围为 `[2, 1920]`，必须是偶数。自定义布局下此参数不生效，整体画面宽度以 `canvas` 中的 `Width` 为主。
VideoHeight	Integer	否	`480`	输出画面的高度，范围为`[2, 1920]`，必须是偶数，默认值为`480`。自定义布局下此参数不生效，整体画面高度以 `canvas` 中的 `Height` 为主。
VideoFps	Integer	否	`15`	输出视频帧率。默认为 `15`，取值范围为 `[1,60]`。
VideoBitrate	Integer	否	`/`	输出视频码率。取值范围 [0,10000]，单位为 Kbps，默认值为 `0`。 `0` 表示自适应码率，会自动根据 `VideoFps` , `VideoWidth` 以及`VideoHeight` 计算出合理的码率。自适应码率模式下，RTC 默认不会设置超高码率。如果订阅屏幕流，建议自行设置高码率。不同场景下设置码率等视频发布参数,请参考设置视频发布参数。
VideoCodec	Integer	否	`0`	视频编码协议。默认值为 `0`，可以取 `0` 或 `1`。取 `0` 时使用 `H.264`,取 `1` 时使用 `ByteVC1` 编码器。
VideoGop	Integer	否	`4`	输出视频 GOP。默认为 `4`，取值范围为 `[1,5]`，单位为秒。
AudioCodec	Integer	否	`0`	音频编码协议。默认值为 `0`，此时使用 aac 编码协议。目前只支持 aac。
AudioProfile	Integer	否	`0`	音频配置文件类型，在使用 aac 编码时生效。取值范围为 `{0, 1, 2}`。 `0` :采用 LC 规格； `1`: 采用 HE-AAC v1 规格； `2`: 采用 HE-AAC v2 规格。取 `2` 时，只支持输出流音频声道数为双声道。默认值为 `0`。
AudioBitrate	Integer	否	`/`	音频码率。取值范围为 `[32,192]`,单位为 Kbps，默认值为 `64`。当`AudioProfile`=`0`时：若输入参数取值范围为 `[32,192]`，编码码率等于输入码率。当`AudioProfile`=`1`时：若输入参数取值范围为 `[32,128]`，编码码率等于输入码率。若输入参数取值范围为 `[128,192]`，编码码率固定为`128`。当`AudioProfile`=`2`时：若输入参数取值范围为 `[32,64]`，编码码率等于输入码率。若输入参数取值范围为 `[64,192]`，编码码率固定为`64`。
AudioSampleRate	Integer	否	`48000`	音频采样率。默认值 `48000`，取值为 `[32000,44100,48000]`，单位是 Hz。
AudioChannels	Integer	否	`2`	音频声道数。 `1`：单声道 `2`：双声道。默认值为 `2`。

Layout

参数类型是否必选示例值描述

参数	类型	是否必选	示例值	描述
LayoutMode	Integer	否	`0`	布局模式。默认值为 `0`，值的范围为 `{0, 1, 2, 3}`。 `0` 为自适应布局模式。参看自适应布局。 `1` 为垂直布局模式。参看垂直布局。 `2` 为自定义布局模式。 `3` 为并排布局模式。参看并排布局
MainVideoStream	Object of Stream	否		在垂直布局模式下生效，指定主画面流的属性。如果此参数为空，则主画面为随机的一路流。
CustomLayout	Object of CustomLayout	否		使用自定义布局模式时，使用此参数进行具体设置。

LayoutMode

Integer

否

0

布局模式。默认值为 0，值的范围为 {0, 1, 2, 3}。

0 为自适应布局模式。参看自适应布局。
1 为垂直布局模式。参看垂直布局。
2 为自定义布局模式。
3 为并排布局模式。参看并排布局

MainVideoStream Object of Stream 否在垂直布局模式下生效，指定主画面流的属性。如果此参数为空，则主画面为随机的一路流。

CustomLayout Object of CustomLayout 否使用自定义布局模式时，使用此参数进行具体设置。

Control

参数	类型	是否必选	示例值	描述
MediaType	Integer	否	`0`	流的类型，用于全局控制订阅的流的类型。默认值为`0`，可以取`0`和`1`。`0`表示音视频，`1`表示纯音频，暂不支持纯视频。
FrameInterpolationMode	Integer	否	`0`	选择补帧模式。默认值为`0`，可以取`0`和`1`。`0`为补最后一帧，`1`为补黑帧。自动布局模式下，没有补帧的逻辑。补帧是指在音视频录制或合流转推时，视频的帧率通常是固定的。但是，因为网络波动或其他原因，实际帧率可能无法达到预设的帧率。此时，需要补帧以保持视频流畅。补最后一帧意味着补充的视频帧和中断前的最后一帧相同，此时看到的画面可能会有短暂静止；补黑帧意味着补充的视频帧是全黑的。使用占位图、补帧和上一帧的关系: 你可以在 `Region` 中传入 `Alternateimage` 字段设置占位图,在 `Control` 中传入`FrameInterpolationMode` 字段设置补帧模式,但占位图优先级高于补帧模式。在 `Region.StreamIndex` 对应的视频流停止发布时, `Region` 对应的画布空间会根据设置填充占位图或补帧。但当视频流为屏幕流时，补帧模式不生效。当 `Region.StreamIndex` 对应的视频流发布后停止采集或推送时, `Region` 对应的画布空间会填充上一帧。当 `Region.StreamIndex` 对应的视频流发布时,设置的占位图或补顿模式不造成任何影响。
MaxIdleTime	Integer	否	`180`	任务的空闲超时时间，超过此时间后，任务自动终止。单位为秒。取值范围为 `[10, 86400]`, 默认值为 `180`。
MaxRecordTime	Integer	否	`0`	（仅对录制有效）最大录制时长，单位为秒。默认值为 `0`。`0` 表示不限制录制时长。
SpatialConfig	Object of SpatialConfig	否		空间音频配置。若合流转推的音频参数设置为单声道，空间音频无效。
PushStreamMode	Integer	否	`0`	转推直播推流模式，用于控制触发推流的时机。取值为`0`或`1`。默认值为`0`。 `0`：房间内有用户推 RTC 流时即触发 CDN 推流。 `1`：调用接口发起推流任务后，无论房间内是否有用户推 RTC 流,均可触发 CDN 推流。任务超时逻辑不变，依然是无用户推流即判定为超时。
SEIConfig	Object of SEIConfig	否		（仅对转推直播有效）SEI 相关配置。

Stream

参数	类型	是否必选	示例值	描述
Index	Integer	否	`0`	在自定义布局中，使用 `Index` 对流进行标志。后续在 `Layout.regions.StreamIndex` 中，你需要使用 `Index` 指定对应流的布局设置。
UserId	String	是	`Your_UserId`	用户Id，表示这个流所属的用户。
StreamType	Integer	否	`0`	流的类型，值可以取`0`或`1`，默认值为`0`。`0`表示普通音视频流，`1`表示屏幕流。

CustomLayout

参数类型是否必选示例值描述

Canvas Object of Canvas 否整体屏幕（画布）的宽高以及背景色。

参数	类型	是否必选	示例值	描述
Canvas	Object of Canvas	否		整体屏幕（画布）的宽高以及背景色。
Regions	Array of Region	否		在自定义布局模式下，你可以使用 `Regions` 对每一路视频流进行画面布局设置。其中，每个 `Region` 对一路视频流进行画面布局设置。自定义布局模式下，对于 `StreamList` 中的每个 `Stream`，`Regions` 中都需要给出对应的布局信息，否则会返回请求不合法的错误。即 `Regions.Region.StreamIndex` 要与 `TargetStreams.StreamList.Stream.Index` 的值一一对应，否则自定义布局设置失败，返回 `InvalidParameter` 错误码。当传入的必填参数值不合法时，返回错误码 `InvalidParameter` 。

Regions

Array of Region

否

在自定义布局模式下，你可以使用 Regions 对每一路视频流进行画面布局设置。其中，每个 Region 对一路视频流进行画面布局设置。
自定义布局模式下，对于 StreamList 中的每个 Stream，Regions 中都需要给出对应的布局信息，否则会返回请求不合法的错误。即 Regions.Region.StreamIndex 要与 TargetStreams.StreamList.Stream.Index 的值一一对应，否则自定义布局设置失败，返回 InvalidParameter 错误码。

当传入的必填参数值不合法时，返回错误码 InvalidParameter 。

SpatialConfig

参数	类型	是否必选	示例值	描述
EnableSpatialRender	Boolean	否	`false`	是否开启空间音频处理功能。 `false`：关闭。 `true`：开启
AudienceSpatialPosition	Array of Integer	否	`[0,0,0]`	观众所在位置的三维坐标，默认值为`[0,0,0]`。数组长度为`3`，三个值依次对应`X`,`Y`,`Z`，每个值的取值范围为`[-100,100]`。
AudienceSpatialOrientation	Object of AudienceSpatialOrientation	否		设置观众朝向。各个向量两两垂直，如果传入的值没有保证两两垂直，自动赋予默认值。默认值为：`forward` = `[1, 0, 0]`, `right` = `[0, 1, 0]`, `up` = `[0, 0, 1]`。

SEIConfig

参数	类型	是否必选	示例值	描述
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 地址时，服务端会补黑帧。关于音量指示模式的用法，参看音量指示模式。
AddVolumeValue	Boolean	否	`false`	SEI 中是否包含用户说话音量值。 `false`：否。 `true`：是。默认值为 `false`。
SEIContentMode	Integer	否	`0`	开启音量指示模式后，非关键帧携带 SEI 包含的信息类型。 `0`：全量信息。 `1`：只有音量信息和时间戳。关于 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`。

Canvas

参数	类型	是否必选	示例值	描述
Width	Integer	否	`640`	整体屏幕（画布）的宽度，单位为像素，范围为 `[2, 1920]`，必须是偶数。默认值为 `640`。
Height	Integer	否	`480`	整体屏幕（画布）的高度，单位为像素，范围为 `[2, 1920]`，必须是偶数。默认值为 `480`。
Background	String	否	`#000000`	整体屏幕（画布）的背景色，格式为 #RGB(16进制)，默认值为 `#000000`（黑色）, 范围为 `#000000 ~ #ffffff` (大小写均可)。
BackgroundImage	String	否	`/`	背景图片的 URL。长度最大为 1024 byte。可以传入的图片的格式包括：JPG, JPEG, PNG。如果背景图片的宽高和整体屏幕的宽高不一致，背景图片会缩放到铺满屏幕。如果你设置了背景图片，背景图片会覆盖背景色。

Region

参数	类型	是否必选	示例值	描述
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` 表示该区域图像位于最下层，`100` 表示该区域图像位于最上层, 默认值为 `0`。
Alpha	Float	否	`1`	画面的透明度，取值范围为 `(0.0, 1.0]`。`0.0` 表示完全透明，`1.0` 表示完全不透明，默认值为 `1.0`。
RenderMode	Integer	否	`0`	画面的渲染模式，值的范围为 `{0, 1, 2，3}`, 默认值为 `0`： `0` 表示按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形 `1` 表示按照显示区域的长宽比裁减视频，然后等比拉伸或缩小视频，占满显示区域。 `2` 表示按照原始画面的宽高比缩放视频，在显示区域居中显示。如果原始画面宽高比与指定的宽高比不同，就会导致画面有空缺，空缺区域为填充的背景色值。 `3` 表示按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形。目前 `0` 和 `3` 均为按照指定的宽高直接缩放，但我们推荐你使用 `3` 以便与客户端实现相同逻辑。不同渲染模式下，效果如下：
SourceCrop	Object of SourceCrop	否		源流剪切功能，可以在源视频帧渲染之前进行裁剪，即预处理一次再渲染。
AlternateImage	String	否	`rtmp://xxx.xxx`	补位图片的 url。长度不超过 1024 个字符串。在 `Region.StreamIndex` 对应的视频流没有发布，或被暂停采集时，`AlternateImage` 对应的图片会填充 `Region` 对应的画布空间。当视频流被采集并发布时，`AlternateImage` 不造成任何影响。可以传入的图片的格式包括：JPG, JPEG, PNG。当图片和画布尺寸不一致时，图片根据 `RenderMode` 的设置，在画布中进行渲染。
ApplySpatialAudio	Boolean	否	`/`	该路流对应的用户是否开启空间音频效果。 `true`：开启空间音频效果。 `false`：关闭空间音频效果。默认值为 `true`
SpatialPosition	Array of Integer	否	`[0,0,0]`	空间音频下，房间内指定用户所在位置的三维坐标，默认值为`[0,0,0]`。数组长度为`3`，三个值依次对应`X`,`Y`,`Z`，每个值的取值范围为`[-100,100]`。
CornerRadius	Float	否	`0.1`	转推直播下边框圆角半径与画布宽度的比例值，取值范围为 `[0,1]`。圆角半径的像素位不能超过 Region 宽高最小值的一半，否则不会出现圆角效果。
MediaType	Integer	否	`0`	该路流参与混流的媒体类型。 `0`：音视频 `1`：纯音频 `2`：纯视频默认值为 `0`。假如该路流为音视频流，`MediaType`设为`1`，则只混入音频内容。
AlternateImageFillMode	Integer	否	`0`	画面的渲染模式。 `0`：按照用户原始视频帧比例进行缩放 `1`：保持图片原有比例默认值为 `0`。

AudienceSpatialOrientation

参数	类型	是否必选	示例值	描述
Up	Array of Float	否	`[0, 0, 1]`	头顶朝向
Right	Array of Float	否	`[0, -1, 0]`	右边朝向
Forward	Array of Float	否	`[1, 0, 0]`	前方朝向

SourceCrop

参数	类型	是否必选	示例值	描述
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`。

返回参数

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

请求示例

POST https://rtc.volcengineapi.com?Action=StartPushMixedStreamToCDN&Version=2023-11-01

{
    "AppId" : "Your_AppId",
    "BusinessId" : "Your_BusinessId",
    "RoomId" : "Your_RoomId",   
    "TaskId": "Your_TaskId",
    "PushURL": "rtmp://xxx/xxx"
}
json

返回示例

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

错误码

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