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

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

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

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

接口行为

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

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

前置条件

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

调用接口

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

接口限制

QPS 不得超过 150。

请求方式

使用 Post 方式发起请求。

请求参数

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

Query
参数名类型必填示例值描述
ActionString是StartPushMixedStreamToCDN接口名称，本接口取值：StartPushMixedStreamToCDN
VersionString是2023-06-01接口版本，本接口取值：2023-06-01
Body
参数名类型必填示例值描述
AppIdString是Your_AppId你的音视频应用的唯一标志
BusinessIdstring否Your_BusinessId业务标识
RoomIdString是Your_RoomId房间的 ID，是房间的唯一标志
TaskIdString是Your_TaskId合流转推任务 ID。你必须对每个合流转推任务设定 TaskId，且在后续进行任务更新和结束时也须使用该 TaskId。关于 TaskId 的详细说明，参看TaskId说明 。 关于 TaskId 及以上 Id 字段的命名规则，参看 ID。
TargetStreamsStreams否/你可以通过本参数设定需要转推的音视频流。如果参数为空，默认对房间内所有人进行转推。自定布局下最多 30 路音视频流，其他布局下最多 17 路音视频流。此参数中的 stream 不得和 ExcludeStreams 中重复。
ExcludeStreamsStreams否你可以通过本参数设定不需要转推的音视频流，即转推流的黑名单。参数默认为空。黑名单中的流自定布局下最多 30 路音视频流，其他布局下最多 17 路音视频流。不支持将屏幕流添加到黑名单中。此参数中的 stream 不得和 TargetStreams 中重复。
PushURLString是rtmp://xxx/xxx推流 CDN 地址。仅支持 RTMP 协议。
EncodeEncode否/音视频编码参数
LayoutLayout否/房间内多路流合为一路时的布局参数
ControlControl否/配置选项。
TaskId 说明：

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

请求示例代码
Query
https://rtc.volcengineapi.com?Action=StartPushMixedStreamToCDN&Version=2023-06-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,
                    "Width": 430,
                    "Height": 340,
                    "ZOrder": 0,
                    "Alpha": 1,
                    "RenderMode": 0
                },
                {
                    "StreamIndex": 1,
                    "LocationX": 430,
                    "LocationY": 0,
                    "Width": 430,
                    "Height": 340,
                    "ZOrder": 1,
                    "Alpha": 1,
                    "RenderMode": 1
                },
                
            ]
        }
    }
}

json
返回调用结果

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

正常返回示例 
{
    "Result": "ok",
    "ResponseMetadata": {
        "RequestId": "Your_RequestId",
        "Action": "StartPushMixedStreamToCDN",
        "Version": "2023-06-01",
        "Service": "rtc",
        "Region": "cn-north-1"
	}
}

json