# 更新云端录制合流布局 (/zh-CN/api-reference/api-ref/cloud-recording/update-layout) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 更新进行中的合流录制任务布局。 - OpenAPI: /openapi/cloud-recording/cloud-recording.zh-CN.yaml - Operation ID: update-cloud-recording-layout - Method: POST - Path: /v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/updateLayout - Endpoint: https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/updateLayout ## Servers - https://api.sd-rtn.com `updateLayout` 方法用于更新云端录制合流布局。 开始合流录制后，你可以调用该方法（`updateLayout`）更新合流布局。 每次调用该方法都会覆盖原来的布局设置。例如，在开始录制时设置了 `backgroundColor` 为 `"#FF0000"`（红色），如果调用 `updateLayout` 方法更新合流布局时如果不再设置 `backgroundColor` 字段，背景色就会变为黑色（默认值）。 :::warning[注意] - `updateLayout` 请求仅在会话内有效。如果录制启动错误，或录制已结束，调用 `updateLayout` 将返回 `404`。 - 如果需要连续调用 `updateLayout` 方法更新合流布局，请在收到上一次 `updateLayout` 响应后再进行调用，否则可能导致请求结果与预期不一致。 ::: ## Authorization This endpoint requires authentication. - `Basic Auth` ## Parameters - `Authorization` (header, required, string) - 声网云端录制 RESTful API 仅支持 HTTPS 协议。发送请求时，你需要使用声网提供的客户 ID 和客户密钥生成 Base64 编码凭证，并填入请求头部的 `Authorization` 字段中。详见[实现 HTTP 基本认证](/zh-CN/realtime-media/cloud-recording/build/setup-and-access/http-basic-auth)。 - Example: `Basic ` - `Content-Type` (header, optional, string) - `application/json`。 - `appid` (path, required, string) - 你的项目使用的 [App ID](/zh-CN/realtime-media/cloud-recording/build/setup-and-access/enable-service#获取-app-id)。 - 对于页面录制模式，只需输入开通了云端录制服务的 App ID。 - 对于单流和合流录制模式，必须使用和待录制的频道相同的 App ID，且该 App ID 需要开通云端录制服务。 - `resourceid` (path, required, string) - 通过 [`acquire`](./acquire) 请求获取到的 Resource ID。 - `sid` (path, required, string) - 通过 [`start`](./start) 获取的录制 ID。 - `mode` (path, required, string) - 录制模式。只支持 `mix`，代表[合流录制模式](/zh-CN/realtime-media/cloud-recording/build/recording-modes/mix-mode/set-composite)。 ## Request body - `cname` (string, required) - 录制服务所在频道的名称。需要和你在 [`acquire`](./acquire) 请求中输入的 `cname` 相同。 - `uid` (string, required) - 字符串内容为录制服务在 RTC 频道内使用的 UID，用于标识该录制服务，需要和你在 [`acquire`](./acquire) 请求中输入的 `uid` 相同。 - `clientRequest` (object, required) - `clientRequest.maxResolutionUid` (string) - 仅需在**垂直布局**下设置。指定显示大视窗画面的用户 UID。字符串内容的整型取值范围 1 到 (232-1)，且不可设置为 0。 - `clientRequest.mixedVideoLayout` (number) - 视频合流布局： - `0`：悬浮布局。第一个加入频道的用户在屏幕上会显示为大视窗，铺满整个画布，其他用户的视频画面会显示为小视窗，从下到上水平排列，最多 4 行，每行 4 个画面，最多支持共 17 个画面。 - `1`：自适应布局。根据用户的数量自动调整每个画面的大小，每个用户的画面大小一致，最多支持 17 个画面。 - `2`：垂直布局。指定 `maxResolutionUid` 在屏幕左侧显示大视窗画面，其他用户的小视窗画面在右侧垂直排列，最多两列，一列 8 个画面，最多支持共 17 个画面。 - `3`：自定义布局。由你在 `layoutConfig` 字段中自定义合流布局。 - Default: `0` - `clientRequest.backgroundColor` (string) - 视频画布的背景颜色。支持 RGB 颜色表，字符串格式为 # 号和 6 个十六进制数。默认值 `"#000000"`，代表黑色。 - Default: `#000000` - `clientRequest.backgroundImage` (string) - 视频画布的背景图的 URL。背景图的显示模式为裁剪模式。

裁剪模式：优先保证画面被填满。背景图尺寸等比缩放，直至整个画面被背景图填满。如果背景图长宽与显示窗口不同，则背景图会按照画面设置的比例进行周边裁剪后填满画面。

- `clientRequest.defaultUserBackgroundImage` (string) - 默认的用户画面背景图的 URL。

配置该字段后，当任一⽤户停止发送视频流超过 3.5 秒，画⾯将切换为该背景图；如果针对某 UID 单独设置了背景图，则该设置会被覆盖。

- `clientRequest.layoutConfig` (array) - 用户的合流画面布局。由每个用户对应的布局画面设置组成的数组，支持最多 17 个用户。

注意：仅需在自定义布局下设置。

- `clientRequest.layoutConfig.items` (object) - `clientRequest.layoutConfig.items.uid` (string) - 字符串内容为待显示在该区域的用户的 UID，32 位无符号整数。

如果不指定 UID，会按照用户加入频道的顺序自动匹配 layoutConfig 中的画面设置。

- `clientRequest.layoutConfig.items.x_axis` (number, required) - 屏幕里该画面左上角的横坐标的相对值，精确到小数点后六位。从左到右布局，`0.0` 在最左端，`1.0` 在最右端。该字段也可以设置为整数 0 或 1。 - Format: `float` - Range: `[0, 1]` - `clientRequest.layoutConfig.items.y_axis` (number, required) - 屏幕里该画面左上角的纵坐标的相对值，精确到小数点后六位。从上到下布局，`0.0` 在最上端，`1.0` 在最下端。该字段也可以设置为整数 0 或 1。 - Format: `float` - Range: `[0, 1]` - `clientRequest.layoutConfig.items.width` (number, required) - 该画面宽度的相对值，精确到小数点后六位。该字段也可以设置为整数 0 或 1。 - Format: `float` - Range: `[0, 1]` - `clientRequest.layoutConfig.items.height` (number, required) - 该画面高度的相对值，精确到小数点后六位。该字段也可以设置为整数 0 或 1。 - Format: `float` - Range: `[0, 1]` - `clientRequest.layoutConfig.items.alpha` (number) - 图像的透明度。精确到小数点后六位。`0.0` 表示图像为透明的，`1.0` 表示图像为完全不透明的。 - Default: `1` - Format: `float` - Range: `[0, 1]` - `clientRequest.layoutConfig.items.render_mode` (number) - 画面显示模式： - `0`：裁剪模式。优先保证画面被填满。视频尺寸等比缩放，直至整个画面被视频填满。如果视频长宽与显示窗口不同，则视频流会按照画面设置的比例进行周边裁剪后填满画面。 - `1`：缩放模式。优先保证视频内容全部显示。视频尺寸等比缩放，直至视频窗口的一边与画面边框对齐。如果视频尺寸与画面尺寸不一致，在保持长宽比的前提下，将视频进行缩放后填满画面，缩放后的视频四周会有一圈黑边。 - Default: `0` - `clientRequest.backgroundConfig` (array) - 用户的背景图设置。 - `clientRequest.backgroundConfig.items` (object) - `clientRequest.backgroundConfig.items.uid` (string, required) - 字符串内容为用户 UID。 - `clientRequest.backgroundConfig.items.image_url` (string, required) - 该用户的背景图 URL。配置背景图后，当该⽤户停止发送视频流超过 3.5 秒，画⾯将切换为该背景图。 URL 支持 HTTP 和 HTTPS 协议，图片格式支持 JPG 和 BMP。图片大小不得超过 6 MB。录制服务成功下载图片后，设置才会生效；如果下载失败，则设置不⽣效。不同字段设置可能会互相覆盖，具体规则详见[设置背景色或背景图](/zh-CN/realtime-media/cloud-recording/build/recording-modes/mix-mode/set-composite-layout#进阶设置背景色或背景图)。 - `clientRequest.backgroundConfig.items.render_mode` (number) - 画面显示模式： - `0`：裁剪模式。优先保证画面被填满。视频尺寸等比缩放，直至整个画面被视频填满。如果视频长宽与显示窗口不同，则视频流会按照画面设置的比例进行周边裁剪后填满画面。 - `1`：缩放模式。优先保证视频内容全部显示。视频尺寸等比缩放，直至视频窗口的一边与画面边框对齐。如果视频尺寸与画面尺寸不一致，在保持长宽比的前提下，将视频进行缩放后填满画面，缩放后的视频四周会有一圈黑边。 - Default: `0` ### Request body example ```json { "cname": "", "uid": "", "clientRequest": { "mixedVideoLayout": 3, "backgroundColor": "#FF0000", "layoutConfig": [ { "uid": "", "x_axis": 0.1, "y_axis": 0.1, "width": 0.1, "height": 0.1, "alpha": 1, "render_mode": 1 }, { "uid": "", "x_axis": 0.2, "y_axis": 0.2, "width": 0.1, "height": 0.1, "alpha": 1, "render_mode": 1 } ] } } ``` ## Responses ### 200 如果返回的 HTTP 状态码为 `200`，表示请求成功。 - `cname` (string) - 录制的频道名。 - `uid` (string) - 字符串内容为云端录制服务在 RTC 频道内使用的 UID，用于标识频道内的录制服务。 - `resourceId` (string) - 云端录制使用的 Resource ID。 - `sid` (string) - 录制 ID。标识一次录制周期。 ### 非 200 如果 HTTP 状态码不为 `200`，请参考[响应状态码](/zh-CN/realtime-media/cloud-recording/reference/response-code)排查问题。 No schema. ## Response examples ### 200 ```json { "cname": "录制的频道名。", "uid": "字符串内容为云端录制服务在 RTC 频道内使用的 UID，用于标识频道内的录制服务。", "resourceId": "云端录制使用的 Resource ID。", "sid": "录制 ID。标识一次录制周期。" } ```