文档中心
云端录制旧版文档
API 文档
更新混流布局

更新混流布局

更新时间：2022-03-01 19:45

1 描述

在录制过程中，可以随时调用本接口更改混流布局的设置。

2 接口原型

请求方式：POST/JSON

请求地址：

服务环境	调用频率限制	请求地址
国内正式环境	10 次/秒	https://cloudrecord-sh.zego.im/update_layout
国内测试环境	10 次/秒	https://cloudrecord-test.zego.im/update_layout
海外正式环境	10 次/秒	https://cloudrecord-hk.zegocloud.com/update_layout
海外测试环境	10 次/秒	https://cloudrecord-test.zegocloud.com/update_layout

传输协议：HTTPS

3 请求参数

参数	类型	是否必选	描述
app_id	Int64	是	ZEGO 给开发者分配的 AppID，唯一标识一个应用。
access_token	String	是	接口鉴权凭证，通过获取 AccessToken 接口获取。
task_id	String	是	录制任务 ID，长度固定为 16 个字节的字符串。
mix_mode	Int	否	布局方式。 1：自定义布局，必须指定 mix_input_list 2：平分布局（默认值） 3：水平布局 4：垂直布局 5：悬浮布局
mix_input_list	Array of Object	否	自定义布局参数。详见 mix_input_list 成员列表。
mix_max_resolution_stream_id	String	否	`mix_mode` 设为 3、4、5 时，用于指定显示大画面的流 ID。

mix_input_list 成员如下：

参数	类型	是否必选	描述
stream_id	String	否	指定在该画面显示的 streamID，如果未指定，会按照流加入房间的时间顺序进行匹配。
view_type	Int	否	该画面显示内容的类型。 1：音视频（默认值） 2：白板类型 2 仅在开启白板录制时有效，仅支持将一个画面设置为白板，超过两个及以上会返回错误。
top	Int	是	画布上该画面左上角的 y 轴坐标，取值范围 [0, 1920]，不能超过 bottom 的值和画布的高。
left	Int	是	画布上该画面左上角的 x 轴坐标，取值范围 [0, 1920]，不能超过 right 的值和画布的宽。
bottom	Int	是	画布上该画面右下角的 y 轴坐标，取值范围 [0, 1920]，不能超过画布的高。
right	Int	是	画布上该画面右下角的 x 轴坐标，取值范围 [0, 1920]，不能超过画布的宽。
layer	Int	是	该画面的图层优先级，当两个画面发生重叠时，数值大的显示在上方。
fill_mode	Int	否	实际视频流宽高比与画面不一致时的处理方式。 1：裁剪模式，该模式下优先保证画面被填满，原视频等比缩放填满画面后，四周超出画面的内容会被裁剪。（默认值） 2：缩放模式，该模式下优先保证原视频的完整性，原视频等比缩放填满画面后，四周会补一圈黑边。
background_image	String	否	流画面背景图的 URL 地址，仅当指定了 stream_id 时生效。自定义布局指定的流不存在或者流中断时会显示该背景图。建议背景图的分辨率与流画面分辨率一致，如两者分辨率不一致，背景图会被拉伸或压缩以填满整个画面。背景图格式支持 JPG 和 PNG，大小不能超过 5MB，如背景图下载失败，则设置不生效。 URL 支持 HTTP 和 HTTPS 协议。

4 请求示例

以下是使用 update_layout 接口更新自定义布局的请求示例。

{
    "app_id": 0000,
    "access_token": "xxxx",
    "task_id": "xxxx",
    "mix_mode": 1,
    "mix_input_list": [
        {
            "stream_id": "xxxx", 
            "view_type": 1, 
            "top": 0, 
            "left": 0, 
            "bottom": 720, 
            "right": 540, 
            "layer": 1
        },
        {
            "stream_id": "", 
            "view_type": 1, 
            "top": 0, 
            "left": 540, 
            "bottom": 360, 
            "right": 1080, 
            "layer": 1
        },
        {
            "stream_id": "", 
            "view_type": 1, 
            "top": 360, 
            "left": 540, 
            "bottom": 720, 
            "right": 1080, 
            "layer": 1
        }
    ]
}

5 响应参数

参数	类型	描述
code	Int	错误码。
message	String	错误描述。

6 响应示例

以下是 update_layout 接口的响应示例。

{
    "code": 0,
    "message": "succeed"
}