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

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

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

接口行为

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

在一个房间内，你最多只能将 17 路流合为一路流。若超出最大合流数限制，会返回 InvalidParameter 错误。

前置条件

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

调用接口

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

接口限制

QPS 不得超过 150。

请求方式

使用 Post 方式发起请求。

请求参数

以下是接口特有的请求参数。关于其他公共请求参数，参看请求参数。

Query

参数名	类型	必填	示例值	描述
Action	String	是	`StartPushMixedStreamToCDN`
Version	String	是	`2020-12-01`	OpenAPI 版本

Body

参数名	类型	必填	示例值	描述
AppId	String	是	`Your_AppId`	你的音视频应用的唯一标志
BusinessId	string	否	`Your_BusinessId`	业务标识
RoomId	String	是	`Your_RoomId`	房间的 ID，是房间的唯一标志
TaskId	String	是	`Your_TaskId`	合流转推任务 ID。你必须对每个合流转推任务设定 TaskId，且在后续进行任务更新和结束时也须使用该 TaskId。关于 TaskId 的详细说明，参看TaskId说明。关于 TaskId 及以上 Id 字段的命名规则，参看 ID。
TargetStreams	Streams	否	/	你可以通过本参数设定需要转推的音视频流。如果参数为空，默认对房间内所有人进行转推。最多17路音视频流。此参数中的 `stream` 不得和 `ExcludeStreams` 中重复。
ExcludeStreams	Streams	否		你可以通过本参数设定不需要转推的音视频流，即转推流的黑名单。参数默认为空。黑名单中的流不得超过 17 路。不支持将屏幕流添加到黑名单中。此参数中的 `stream` 不得和 `TargetStreams` 中重复。
PushURL	String	是	`rtmp://xxx/xxx`	推流 CDN 地址。仅支持 RTMP 协议。
Encode	Encode	否	/	音视频编码参数
Layout	Layout	否	/	房间内多路流合为一路时的布局参数
Control	Control	否	/	配置选项。

TaskId 说明：

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

请求示例代码

Query

https://rtc.volcengineapi.com?Action=StartPushMixedStreamToCDN&Version=2020-12-01

Body

使用自动布局进行合流转推时：

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

使用自定义布局进行合流转推时：

{
    "AppId": "Your_AppId",
    "BusinessId" : "Your_BusinessId",
    "RoomId": "Your_RoomId",
    "TaskId": "Your_TaskId",
    "TargetStreams": {
        "StreamList": [
            {
                "Index": 0,
                "UserId": "Your_UserId_3"
            },
            {
                "Index": 1,
                "UserId": "Your_UserId_4",
                "StreamType": 1
            }
        ]
    },
   "PushURL": "rtmp://xxx/xxx",
   "Layout": {
        "LayoutMode": 2,
        "CustomLayout": {
            "Canvas": {
                "Width": 860,
                "Height": 340,
                "Background": "#303342"
            },
            "Regions": [
                {
                    "StreamIndex": 0,
                    "LocationX": 0,
                    "LocationY": 0,
                    "WidthProportion": 0.5,
                    "HeightProportion": 1,
                    "ZOrder": 0,
                    "Alpha": 1,
                    "RenderMode": 0
                },
                {
                    "StreamIndex": 1,
                    "LocationX": 0.5,
                    "LocationY": 0,
                    "WidthProportion": 0.5,
                    "HeightProportion": 1,
                    "ZOrder": 1,
                    "Alpha": 1,
                    "RenderMode": 1
                },
                
            ]
        }
    }
}
json

返回调用结果

返回值 Result 仅在请求成功时返回"ok",失败时为空。

正常返回示例

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