# Update layout (/en/api-reference/api-ref/cloud-recording/update-layout)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

Updates the video mixing layout of an active composite recording.

- OpenAPI: /openapi/cloud-recording/cloud-recording.en.yaml
- Operation ID: update-cloud-recording-layout
- Method: POST
- Path: /v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/updateLayout

## Servers

- https://api.sd-rtn.com

## Parameters

- `Content-Type` (header, optional) - `application/json`.
- `appid` (path, required) - The App ID of your project.
- For web page recording mode, enter the App ID for which the cloud recording service is enabled.
- For individual and composite recording modes, use the same App ID as the channel to be recorded. Ensure that the cloud recording service has been enabled for this App ID.
- `resourceid` (path, required) - The resource ID obtained from the `acquire` endpoint.
- `sid` (path, required) - The recording ID obtained from the `start` endpoint.
- `mode` (path, required) - Must be `mix`. This endpoint only supports composite recording mode.

## Request body

- `cname` (string, required) - The name of the channel to record. Must match the `cname` used in the `acquire` request.
The name of the channel being recorded.
No schema.
- `uid` (string, required) - The UID used by the cloud recording service in the channel. Must match the `uid` used in the `acquire` request.
The UID used by the cloud recording service in the RTC channel.
No schema.
- `clientRequest` (object, required)
  - `clientRequest.maxResolutionUid` (string) - The UID of the large video window in vertical layout. Must be an integer from 1 to (2³²−1), cannot be `0`. Only required when `mixedVideoLayout` is `2`.
No schema.
  - `clientRequest.mixedVideoLayout` (integer) - Composite video layout:

- `0`: Floating layout. The first user to join fills the entire canvas; other users appear as small windows arranged horizontally from bottom to top, up to 4 rows of 4 windows (17 windows total).
- `1`: Adaptive layout. All user windows are equal in size, automatically adjusted based on user count. Supports up to 17 windows.
- `2`: Vertical layout. The `maxResolutionUid` user appears in a large window on the left; other users are arranged in up to two columns on the right, 8 windows per column (17 windows total).
- `3`: Custom layout. Configure positions using `layoutConfig`.
No schema.
  - `clientRequest.backgroundColor` (string) - Canvas background color as an RGB hex string (e.g., `"#FF0000"` for red).
No schema.
  - `clientRequest.backgroundImage` (string) - URL of the canvas background image. Displayed in cropped mode: the image is scaled proportionally until the canvas is filled, and excess edges are cropped.
No schema.
  - `clientRequest.defaultUserBackgroundImage` (string) - URL of the default background image shown when a user stops sending video for more than 3.5 seconds. Overridden if a per-UID background image is set in `backgroundConfig`.
No schema.
  - `clientRequest.layoutConfig` (array) - Per-user screen layout settings for custom layout. Supports up to 17 users. Only applicable when `mixedVideoLayout` is `3`.
    - `clientRequest.layoutConfig.items` (object)
      - `clientRequest.layoutConfig.items.uid` (string) - The UID of the user assigned to this layout region. If not specified, layout regions are assigned in the order users join the channel.
No schema.
      - `clientRequest.layoutConfig.items.x_axis` (number, required) - Horizontal coordinate of the region's upper-left corner as a relative value (6 decimal places). `0.0` is the far left, `1.0` is the far right.
No schema.
      - `clientRequest.layoutConfig.items.y_axis` (number, required) - Vertical coordinate of the region's upper-left corner as a relative value (6 decimal places). `0.0` is the top, `1.0` is the bottom.
No schema.
      - `clientRequest.layoutConfig.items.width` (number, required) - Relative width of the region (6 decimal places).
No schema.
      - `clientRequest.layoutConfig.items.height` (number, required) - Relative height of the region (6 decimal places).
No schema.
      - `clientRequest.layoutConfig.items.alpha` (number) - Transparency of the user's video window. `0.0` is fully transparent, `1.0` is fully opaque.
No schema.
      - `clientRequest.layoutConfig.items.render_mode` (integer) - Display mode for the user's video window:

- `0`: Cropped mode. The window is filled; video is scaled proportionally and cropped at the edges if the aspect ratio differs.
- `1`: Fit mode. All video content is visible; the video is scaled proportionally and black borders may appear.
No schema.
  - `clientRequest.backgroundConfig` (array) - Per-user background image settings.
    - `clientRequest.backgroundConfig.items` (object)
      - `clientRequest.backgroundConfig.items.uid` (string, required) - The UID of the user.
No schema.
      - `clientRequest.backgroundConfig.items.image_url` (string, required) - The URL of the user's background image, shown when the user stops sending video for more than 3.5 seconds. Supports HTTPS, JPG and BMP formats, maximum 6 MB. Settings take effect only after the image is successfully downloaded.
No schema.
      - `clientRequest.backgroundConfig.items.render_mode` (integer) - Display mode for the background image:

- `0`: Cropped mode. The window is filled; image is scaled proportionally and cropped at the edges if the aspect ratio differs.
- `1`: Fit mode. All image content is visible; the image is scaled proportionally and black borders may appear.
No schema.

## Responses

### 200

The request succeeded.

- `resourceId` (string) - The cloud recording resource ID. Valid for five minutes; re-request from `acquire` if expired.

The resource ID used by cloud recording.
No schema.
- `sid` (string) - The recording ID. Uniquely identifies a recording session. Generated after the cloud recording service starts successfully.

The recording ID, identifying the current recording session.
No schema.
- `cname` (string) - The name of the channel to be recorded.

The name of the channel being recorded.
No schema.
- `uid` (string) - The UID used by the cloud recording service in the RTC channel.
No schema.
### default

The request failed. If the HTTP status code is not `200`, see the Cloud Recording response status codes for troubleshooting.

No schema.