All Products
Search

This Product

    ApsaraVideo Live:UpdateRtcCloudRecording

    Document Center

    ApsaraVideo Live:UpdateRtcCloudRecording

    Last Updated:Aug 19, 2025

    Updates an RTC cloud recording task.

    Operation description

    QPS limit

    The queries per second (QPS) limit for this API is 50 for each user. If you exceed this limit, API calls are throttled, which can affect your business. Ensure that you call this API within this limit.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    live:UpdateRtcCloudRecording

    update

    *All Resource

    *

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    TaskId

    string

    Yes

    The task ID returned when you start an RTC cloud recording.

    ******73-8501-****-8ac1-72295a******

    SubscribeParams

    object

    Yes

    The updated subscription parameters.

    SubscribeUserIdList

    array

    Yes

    A list of user IDs to subscribe to. In individual recording mode, a separate recording is created for each user ID. In stream mixing mode, the audio and video streams of all user IDs are mixed into a single stream.

    Note

    • The array can contain a maximum of 17 elements.

    object

    No

    Information about the user ID to subscribe to.

    UserId

    string

    Yes

    The user ID to subscribe to.

    userA
    StreamType

    integer

    No

    The media type of the user ID to subscribe to. Valid values:

    • 0: The original stream, which includes both audio and video. (Default)

    • 1: Audio-only stream.

    • 2: Video-only stream.

    0
    SourceType

    integer

    No

    The video input stream type for the user ID. This parameter is valid only when you subscribe to a video stream (StreamType=2). Valid values:

    • 0: Camera. (Default)

    • 1: Screen sharing.

    0
    MixLayoutParams

    object

    No

    The updated layout parameters. Do not specify this parameter in individual recording mode. This parameter is required in stream mixing mode when transcoding non-audio-only streams.

    MixBackground

    object

    No

    The global background image for the mixed stream.

    RenderMode

    integer

    No

    The display mode for the output video. Valid values:

    • 0: Crop. (Default)

    • 1: Scale and fill with a black background.

    0
    Url

    string

    No

    The URL of the background image. The URL can be up to 2,048 characters long.

    https://xxxx.com/photos/my-test-picture.png

    UserPanes

    array

    No

    The window layout information for the subscribed users. Only users with specified layout information are included in the video. This parameter is required in stream mixing mode when recording non-audio-only files.

    array<object>

    No

    The window configuration in the video.

    UserId

    string

    No

    The user ID corresponding to this window.

    • If you do not specify a user ID, the windows are filled in the order that users join the channel.

    • The combination of the user ID and SourceType specified here must be included in SubscribeUserIdList.

    • Audio-only streams cannot be added to the layout.

    userA
    SourceType

    integer

    No

    The video input stream type for the user ID. This parameter is invalid if you do not specify a user ID. Valid values:

    • 0: Camera. (Default)

    • 1: Screen sharing. The combination of the user ID and SourceType specified here must be included in SubscribeUserIdList.

    0
    Height

    string

    No

    The height of the pane as a normalized percentage. The value must be between 0 and 1. (Default: 0)

    0.5
    Width

    string

    No

    The width of the pane as a normalized percentage. The value must be between 0 and 1. (Default: 0)

    0.5
    X

    string

    No

    The X-coordinate as a normalized percentage. The value must be between 0 and 1. (Default: 0)

    0
    Y

    string

    No

    The Y-coordinate as a normalized percentage. The value must be between 0 and 1. (Default: 0)

    0
    ZOrder

    integer

    No

    The stacking order. A value of 0 indicates the bottom layer. A value of 1 is layered on top of 0, and so on. (Default: 0)

    0
    SubBackground

    object

    No

    The background image for the sub-window. This image is displayed in the layout position when a user turns off their camera, does not push a stream after joining, or leaves the session.

    RenderMode

    integer

    No

    The display mode for the sub-window output. Valid values:

    • 0: Crop. (Default)

    • 1: Scale and fill with a black background.

    0
    Url

    string

    No

    The URL of the background image. The URL can be up to 2,048 characters long.

    https://xxxx.com/photos/my-test-pane-picture.png

    • You can subscribe to both the camera and screen sharing streams for the same user ID simultaneously. In individual recording mode, if you subscribe to both streams for the same user ID, the FileNamePattern and SliceNamePattern parameters must include the SourceType variable to prevent recording files from being overwritten.

    • In individual recording mode, you cannot subscribe to only the video-only stream of a user ID. This means that in this mode, you cannot set UserInfo.StreamType to 2.

    • To record a user's screen stream without audio, you can subscribe to their original stream and push only the screen video with the audio muted. To record a user's screen stream with audio, you can subscribe to their original stream and push both the screen video and audio. Alternatively, you can subscribe to their video-only stream with SourceType set to 1 and also subscribe to their audio-only stream to record with audio. Note that subscribing to a video-only stream is not supported in individual recording mode.

    • In individual recording mode, if RecordParams.StreamType is set to 1 (audio-only), you cannot subscribe to a video-only stream (StreamType=2) in SubscribeParams. Similarly, if RecordParams.StreamType is set to 2 (video-only), you cannot subscribe to an audio-only stream (StreamType=1) in SubscribeParams.

    • In stream mixing mode, if RecordParams.StreamType is set to 1 (audio-only), you cannot subscribe to all user IDs in SubscribeParams as video-only (StreamType=2). Similarly, if RecordParams.StreamType is set to 2 (video-only), you cannot subscribe to all user IDs in SubscribeParams as audio-only (StreamType=1).

    Response parameters

    Parameter

    Type

    Description

    Example

    object

    Schema of Response

    RequestId

    string

    The request ID.

    ******58-5876-****-83CA-B56278******

    TaskId

    string

    The task ID.

    ******73-8501-****-8ac1-72295a******

    Examples

    Success response

    JSON format

    {
  "RequestId": "******58-5876-****-83CA-B56278******\n",
  "TaskId": "******73-8501-****-8ac1-72295a******\n"
}

    Error codes

    HTTP status code

    Error code

    Error message

    Description
    400 NotFound.Task %s, please check the TaskId. The parameter TaskId does not exist.
    400 InvalidParameter.TaskId %s, please check the TaskId. The specified task must be in the running or recovering state.
    400 InvalidParameter.SubscribeParams.SubscribeUserIdList %s, please check the subscribeUserIdList of subscribeParams. The parameter SubscribeUserIdList is invalid, please check.
    400 InvalidParameter.MixLayoutParams.UserPanes %s, please check the userPanes of mixLayoutParams. The parameter UserPanes has invalid fields, please check.
    400 InvalidParameter.MixTranscodeParams %s, please check the transcodeParams. The parameter MixTranscodeParams has invalid fields, please check.
    400 MissingParameter %s. Missing parameter
    403 InvalidParameter.UserId %s, please check the UserId. UserId is invalid, please check.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.