Skip to main content
Conversational AI Engine: Create advanced voice apps by combining Agora's real-time audio with powerful conversational AI.

Update layout

POST
https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/updateLayout

After starting a composite recording, call this endpoint to update the video mixing layout.

  • Each call to this endpoint overwrites all previous layout settings. For example, if you set backgroundColor to "#FF0000" when starting a recording and call updateLayout without setting backgroundColor again, the background color reverts to the default value "#000000".
  • This endpoint is only valid within an active recording session. If the recording was not started successfully or has already ended, the request returns 404.
  • If you need to call updateLayout multiple times in succession, wait for the previous response before sending the next request to avoid unexpected results.

Request​

Path parameters​

appid stringrequired

The App ID of your project. Use the same App ID as the channel being recorded. Ensure that the cloud recording service has been enabled for this App ID.

resourceid stringrequired

The resource ID obtained from the acquire endpoint.

sid stringrequired

The recording ID obtained from the start endpoint.

mode stringrequired

Must be mix. This endpoint only supports composite recording mode.

Request body​

APPLICATION/JSON
BODYrequired
  • cname stringrequired

    The name of the channel being recorded. Must match the cname used in the acquire request.

  • uid stringrequired

    The UID used by the cloud recording service in the channel. Must match the uid used in the acquire request.

  • clientRequest objectrequired
    Show propertiesHide properties
    • mixedVideoLayout numbernullable

      Default: 0

      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.
    • maxResolutionUid stringnullable

      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.

    • backgroundColor stringnullable

      Default: "#000000"

      Canvas background color as an RGB hex string (e.g., "#FF0000" for red).

    • backgroundImage stringnullable

      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.

    • defaultUserBackgroundImage stringnullable

      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.

    • layoutConfig array[object]nullable

      Per-user screen layout settings. Supports up to 17 users. Only applicable when mixedVideoLayout is 3.

      Show propertiesHide properties
      • uid stringnullable

        The UID of the user assigned to this layout region. If not specified, layout regions are assigned in the order users join the channel.

      • x_axis number (float)required

        Range: [0, 1]

        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.

      • y_axis number (float)required

        Range: [0, 1]

        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.

      • width number (float)required

        Range: [0, 1]

        Relative width of the region (6 decimal places).

      • height number (float)required

        Range: [0, 1]

        Relative height of the region (6 decimal places).

      • alpha number (float)nullable

        Default: 1

        Range: [0, 1]

        Transparency of the user's video window. 0.0 is fully transparent, 1.0 is fully opaque.

      • render_mode numbernullable

        Default: 0

        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.
    • backgroundConfig array[object]nullable

      Per-user background image settings.

      Show propertiesHide properties
      • uid stringrequired

        The UID of the user.

      • image_url stringrequired

        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.

      • render_mode numbernullable

        Default: 0

        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.

Response​

Response body​

  • If the returned status code is 200, the request was successful.

    OK
    • cname string

      The name of the channel being recorded.

    • uid string

      The UID used by the cloud recording service in the RTC channel.

    • resourceId string

      The resource ID used by cloud recording.

    • sid string

      The recording ID, identifying the current recording session.

  • If the returned status code is not 200, the request failed. See Response status codes for troubleshooting.

Authorization

This endpoint requires Basic Auth.

Request example


_32
curl --request POST \
_32
--url https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/mix/updateLayout \
_32
--header 'Authorization: Basic <credentials>' \
_32
--header 'Content-Type: application/json' \
_32
--data '{
_32
"cname": "httpClient463224",
_32
"uid": "527841",
_32
"clientRequest": {
_32
"mixedVideoLayout": 3,
_32
"backgroundColor": "#FF0000",
_32
"layoutConfig": [
_32
{
_32
"uid": "1",
_32
"x_axis": 0.1,
_32
"y_axis": 0.1,
_32
"width": 0.1,
_32
"height": 0.1,
_32
"alpha": 1,
_32
"render_mode": 1
_32
},
_32
{
_32
"uid": "2",
_32
"x_axis": 0.2,
_32
"y_axis": 0.2,
_32
"width": 0.1,
_32
"height": 0.1,
_32
"alpha": 1,
_32
"render_mode": 1
_32
}
_32
]
_32
}
_32
}'

Response example


_6
{
_6
"cname": "httpClient463224",
_6
"uid": "527841",
_6
"resourceId": "JyvK8nXHuV1BE.....",
_6
"sid": "38f8e3c......"
_6
}