All Products
Search

This Product

    ApsaraVideo Live:StartRtcCloudRecording

    Document Center

    ApsaraVideo Live:StartRtcCloudRecording

    Last Updated:Jan 27, 2026

    Starts an RTC cloud recording task.

    Operation description

    Cloud recording is a billable feature. For more information, see Cloud recording pricing.

    Endpoints

    Call this operation from the following endpoints:

    RegionRegion IDEndpoint
    China (Shanghai)cn-shanghailive.aliyuncs.com
    Singaporeap-southeast-1live.ap-southeast-1.aliyuncs.com
    US (Virginia)us-east-1live.us-east-1.aliyuncs.com

    QPS limit

    The queries per second (QPS) limit for this operation is 50 per user. If you exceed this limit, your API calls are throttled, which may affect your business. Use this API responsibly.

    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:StartRtcCloudRecording

    create

    *All Resource

    *

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    AppId

    string

    Yes

    The ID of the app to which the channel to be recorded belongs. The app must belong to the Alibaba Cloud account that is used to call the API.

    ********-7074-****-9ef5-85c19a4*****
    ChannelId

    string

    Yes

    The ID of the channel to record. Ensure that users are in the channel when you call this API. Otherwise, the recording task fails to start.

    room1024
    SubscribeParams

    object

    Yes

    The subscription parameters.

    SubscribeUserIdList

    array<object>

    Yes

    A list of user IDs to subscribe to. In single-stream recording mode, a separate recording is generated 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 cannot be empty and can contain a maximum of 17 elements.

    object

    No

    The information about the subscribed user ID.

    UserId

    string

    Yes

    The user ID to subscribe to.

    userA
    StreamType

    integer

    No

    The media type of the stream for the user ID. Valid values:

    • 0: original stream (audio and video). This is the default value.

    • 1: audio-only stream.

    • 2: video-only stream. This value is valid only in stream mixing mode.

    0
    SourceType

    integer

    No

    The type of the video input stream for the user ID. This parameter is valid only when you subscribe to a stream that is not audio-only (StreamType is not 1). Valid values:

    • 0: camera stream. This is the default value.

    • 1: screen sharing stream.

    0
    RecordParams

    object

    Yes

    The recording parameters.

    RecordMode

    integer

    Yes

    The recording mode. Valid values:

    • 0: single-stream recording. A separate recording file is generated for each subscribed user ID.

    • 1: stream mixing. The streams of the subscribed user IDs are mixed and transcoded into a single set of recording files.

    0
    StreamType

    integer

    No

    The media type of the output stream. Valid values:

    • 0: original stream (audio and video). This is the default value.

    • 1: audio-only stream.

    • 2: video-only stream.

    0
    MaxFileDuration

    integer

    No

    The maximum duration of a recording file, in seconds. A recording file that exceeds the maximum duration is split. The value must be within the range of [180, 7200]. The maximum duration is 2 hours. If you do not specify this parameter, the default value of 2 hours is used.

    7200
    StorageParams

    object

    Yes

    The storage parameters.

    StorageType

    integer

    Yes

    The storage method. Valid values:

    • 0: VOD

    • 1: OSS

    1
    FileInfo

    array<object>

    No

    The information about file storage. This parameter is used to specify the format, storage location, and naming rules of recording files. This parameter is valid only when StorageType is set to OSS.

    Note

    For each element in the array, a recording file is generated based on the specified configuration. If this parameter is not set, the configuration for the HLS format is used by default. If you set this parameter but do not include the configuration for the HLS format, the system automatically adds the default configuration for the HLS format.

    object

    No

    The storage configuration for different file formats.

    Format

    string

    Yes

    The file format for storage. Valid values:

    • HLS

    • MP4

    • MP3

    HLS
    FileNamePattern

    string

    No

    The file naming pattern. You can combine the following variables in any order:

    • AppId

    • ChannelId

    • UserId (Required in single-stream mode. Invalid in stream mixing mode. If you include this variable in stream mixing mode, the literal string {UserId} is retained.)

    • RecordMode

      • If the value is 0, the recording mode is Single.

      • If the value is 1, the recording mode is Mix.

    • SourceType

      • In single-stream mode, if the stream is video-only, this parameter is valid. Set SourceType to one of the following values:

        • If the value is 0, the video stream is from a camera (C).

        • If the value is 1, the video stream is from screen sharing (S).

      • In single-stream mode, if the stream is audio-only, SourceType is automatically set to A (Audio) to identify the recording as an audio-only recording.

      • In single-stream mode, if the stream is an original stream, this parameter is valid. Set SourceType to one of the following values:

        • If the value is 0, the stream is an original camera stream (OC).

        • If the value is 1, the stream is an original screen sharing stream (OS).

      • In other scenarios, this parameter is invalid. If you configure this parameter manually, the {SourceType} placeholder is retained.

    • StreamType (This refers to the StreamType parameter under RecordParams.)

      • If the value is 0, the stream is an audio and video stream (AV).

      • If the value is 1, the stream is an audio stream (A).

      • If the value is 2, the stream is a video stream (V).

    • StartTime: The time when the recording starts. The time is in the UTC+8 time zone and in a format such as 2025-03-25-11:27:28. This variable is required if you do not use the default value.

    The default values are as follows:

    • Single-stream recording mode

      • {AppId}_{ChannelId}_{UserId}_{StartTime}

      • If you subscribe to different stream types or source types for the same user ID, the default value is {AppId}_{ChannelId}_{UserId}_{SourceType}_{StartTime}.

    • Stream mixing mode

      • {AppId}_{ChannelId}_{StartTime}

    Note

    • The string can only consist of the preceding variables. Enclose each variable in braces {}. Separate variables with an underscore (_). Each variable can appear only once in the string.

    • If the file is named xxx, the file is saved in a path such as TaskId/xxx.m3u8. TaskId is the ID of the task that is generated when you start the cloud recording task. The task ID is automatically added to the storage path.

    {AppId}_{ChannelId}_{StartTime}_{UserId}
    SliceNamePattern

    string

    No

    The slice naming pattern. This parameter is valid only for the HLS format. This parameter is similar to FileNamePattern, but includes the Sequence variable.

    • AppId

    • ChannelId

    • UserId (Required in single-stream mode. Invalid in stream mixing mode. If you include this variable in stream mixing mode, the literal string {UserId} is retained.)

    • RecordMode

      • If the value is 0, the recording mode is Single.

      • If the value is 1, the recording mode is Mix.

    • SourceType

      • In single-stream mode, if the stream is video-only, this parameter is valid. Set SourceType to one of the following values:

        • If the value is 0, the video stream is from a camera (C).

        • If the value is 1, the video stream is from screen sharing (S).

      • In single-stream mode, if the stream is audio-only, SourceType is automatically set to A (Audio) to identify the recording as an audio-only recording.

      • In single-stream mode, if the stream is an original stream, this parameter is valid. Set SourceType to one of the following values:

        • If the value is 0, the stream is an original camera stream (OC).

        • If the value is 1, the stream is an original screen sharing stream (OS).

      • In other scenarios, this parameter is invalid. If you configure this parameter manually, the {SourceType} placeholder is retained.

    • StreamType (This refers to the StreamType parameter under RecordParams.)

      • If the value is 0, the stream is an audio and video stream (AV).

      • If the value is 1, the stream is an audio stream (A).

      • If the value is 2, the stream is a video stream (V).

    • StartTime: The time when the recording starts. The time is in the UTC+8 time zone and in a format such as 2025-03-25-11:27:28. This variable is required if you do not use the default value.

    • Sequence: The sequence number is included in the names of TS files in HLS format. This variable is invalid for other formats. This variable is required if you do not use the default value.

    The default values are as follows:

    • Single-stream recording mode

      • {AppId}_{ChannelId}_{UserId}_{StartTime}_{Sequence}

      • If you subscribe to different stream types or source types for the same user ID, the default value is {AppId}_{ChannelId}_{UserId}_{SourceType}_{StartTime}_{Sequence}.

    • Stream mixing mode

      • {AppId}_{ChannelId}_{StartTime}_{Sequence}

    Note

    • The string can only consist of the preceding variables. Enclose each variable in braces {}. Separate variables with an underscore (_). Each variable can appear only once in the string.

    • If the slice is named xxx, the slice file is saved in a path such as TaskId/xxx.ts. TaskId is the ID of the task that is generated when you start the cloud recording task. The task ID is automatically added to the storage path.

    {AppId}_{ChannelId}_{StartTime}_{Sequence}
    FilePathPrefix

    array

    No

    The file storage path. The elements in the array correspond to directory levels. For example, if you set the value to ["dir1","dir2"], the xxx.m3u8 file is saved to dir1/dir2/TaskId/xxx.m3u8. If this parameter is empty, the file is saved to TaskId/xxx.m3u8.

    • The task ID is automatically appended to the end of the path to prevent files from different tasks from being mixed.

    • If you set FilePathPrefix, each element can contain only letters (a-z and A-Z), digits (0-9), hyphens (-), and underscores (_). The elements cannot be empty strings.

    • The total length of the concatenated path cannot exceed 128 characters. This includes the forward slashes (/) but excludes the automatically added task ID. For example, if the value is ["dir1","dir2"], the concatenated path is "dir1/dir2/". The total number of characters of all elements plus the number of elements (for the forward slashes) cannot exceed 128.

    • The array can contain a maximum of 5 elements. This means you can customize up to 5 directory levels.

    string

    No

    The name of each directory level.

    dir1
    SliceDuration

    integer

    No

    The duration of a slice in seconds. This parameter is valid only for the HLS format. The value must be within the range of [10, 30]. The default value is 30.

    Use the default value unless you have specific requirements.

    30
    OSSParams

    object

    No

    The OSS storage configuration. This parameter is required when StorageType is set to OSS and is invalid when StorageType is set to VOD.

    OSSEndpoint

    string

    Yes

    The name of the OSS endpoint. The region ID of the endpoint must be the same as the region of the selected endpoint.

    oss-cn-shanghai.aliyuncs.com
    OSSBucket

    string

    Yes

    The name of the OSS bucket. The bucket must belong to the Alibaba Cloud account that is used to call the API.

    mytest-bucket
    VodParams

    object

    No

    The VOD storage configuration. This parameter is required when StorageType is set to VOD and is invalid when StorageType is set to OSS.

    StorageLocation

    string

    No

    The storage address that is included in the VOD console under Media Asset Management > Storage Management. Recording files are first saved to this address and then uploaded to VOD.

    mytest.oss-cn-shenzhen.aliyuncs.com
    VodTranscodeGroupId

    string

    No

    The ID of the VOD transcoding template group.

    ****8a914d3989e9825eb90530b2****
    AutoCompose

    integer

    No

    Specifies whether to enable automatic composition. Valid values:

    • 0: disables automatic composition. This is the default value.

    • 1: enables automatic composition. If you enable automatic composition, you must set the ComposeVodTranscodeGroupId parameter.

    0
    ComposeVodTranscodeGroupId

    string

    No

    The ID of the VOD transcoding template group that is used to transcode the new video composed in the VOD service.

    Note

    • This parameter is required only when AutoCompose is set to 1.

    • For more information about common issues with automatic composition and transcoding, see Live-to-VOD FAQ.

    • For more information about VOD transcoding billing, see Media asset transcoding billing.

    ****4c34112cfe68248f2f77759c****
    MixTranscodeParams

    object

    No

    The transcoding parameters. Do not specify this parameter for single-stream recording. This parameter is required for stream mixing.

    FrameFillType

    integer

    No

    The frame filling type during a stream interruption. Valid values:

    • 0: Fill with the last frame. This is the default value.

    0
    AudioBitrate

    integer

    Yes

    The audio bitrate in kbit/s. The value must be within the range of [8, 500]. This parameter is required in stream mixing mode.

    300
    AudioChannels

    integer

    Yes

    The number of audio channels. Valid values:

    • 1: mono.

    • 2: stereo.

    This parameter is required in stream mixing mode.

    2
    AudioSampleRate

    integer

    Yes

    The audio sampling rate in Hz. Valid values:

    • 8000

    • 16000

    • 32000

    • 44100

    • 48000

    This parameter is required in stream mixing mode.

    32000
    VideoCodec

    string

    No

    The video encoding format. Valid values:

    • H.264 (default)

    • H.265

    H.264
    VideoBitrate

    integer

    No

    The video bitrate in kbit/s. The value must be within the range of [1, 10000]. In stream mixing mode, this parameter is required if the output recording includes video. In other cases, this parameter is invalid.

    5000
    VideoFramerate

    integer

    No

    The video frame rate in fps. The value must be within the range of [1, 60]. In stream mixing mode, this parameter is required if the output recording includes video. In other cases, this parameter is invalid.

    30
    VideoGop

    integer

    No

    The video GOP. An I-frame appears every VideoGop frames. The value must be within the range of [1, 60]. In stream mixing mode, this parameter is required if the output recording includes video. In other cases, this parameter is invalid.

    30
    VideoHeight

    integer

    No

    The video height in pixels. The value must be within the range of [0, 1920]. The default value is 0.

    480
    VideoWidth

    integer

    No

    The video width in pixels. The value must be within the range of [0, 1920]. The default value is 0.

    640
    MixLayoutParams

    object

    No

    The layout parameters. Do not specify this parameter for single-stream recording. This parameter is required in stream mixing mode if the output recording is not audio-only.

    MixBackground

    object

    No

    The global background image for stream mixing.

    RenderMode

    integer

    No

    The display mode for the output video. Valid values:

    • 0: crop. This is the default value.

    • 1: scale and pad with black.

    0
    Url

    string

    No

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

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

    array<object>

    No

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

    array<object>

    No

    The window configuration in the output video.

    UserId

    string

    No

    The user ID that corresponds to this window.

    • If UserId is not set, the windows are filled in the order that users join the channel.

    • The combination of UserId and SourceType specified here must be included in SubscribeUserIdList.

    • Users who are subscribed to audio-only streams cannot be added to the layout.

    userA
    SourceType

    integer

    No

    The type of the video input stream for this user ID. This parameter is invalid if UserId is not specified. Valid values:

    • 0: camera stream. This is the default value.

    • 1: screen sharing stream.

    The combination of UserId and SourceType specified here must be included in SubscribeUserIdList.

    0
    Height

    string

    No

    The height of the pane. This value is a normalized percentage. The value must be within the range of [0, 1]. The default value is 0.

    0.5
    Width

    string

    No

    The width of the pane. This value is a normalized percentage. The value must be within the range of [0, 1]. The default value is 0.

    0.5
    X

    string

    No

    The X coordinate. This value is a normalized percentage. The value must be within the range of [0, 1]. The default value is 0.

    0
    Y

    string

    No

    The Y coordinate. This value is a normalized percentage. The value must be within the range of [0, 1]. The default value is 0.

    0
    ZOrder

    integer

    No

    The stacking order. Layer 0 is the bottom layer. Layer 1 is stacked on top of layer 0, and so on. The default value is 0.

    0
    SubBackground

    object

    No

    The background image of the sub-pane. This image is used when a user turns off their camera, does not publish a stream after joining the channel, or leaves the channel. The image fills the layout position.

    RenderMode

    integer

    No

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

    • 0: crop. This is the default value.

    • 1: scale and pad with black.

    0
    Url

    string

    No

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

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

    string

    No

    The callback URL to receive task status messages. Messages are sent using POST requests in the JSON format. The URL can be up to 2,048 characters in length.

    For more information about callback messages, see On-cloud recording callback message.

    http://xxxx/test/mycallback
    NotifyAuthKey

    string

    No

    The authentication key for callback messages. If this parameter is not specified, authentication is disabled. If this parameter is specified, the key must be 16 to 64 characters in length and can contain only letters and digits.

    • If NotifyUrl is not specified, NotifyAuthKey is invalid.

    • If a valid NotifyAuthKey is specified, authentication content is included in the callback message.

    mytestkeymytestkey
    NotifyFileUploadedFormat

    array

    No

    The formats for which callback messages are sent when the RecordFileUploaded event is triggered.

    string

    No

    The specific file formats for which to receive callbacks. Valid values (case-insensitive):

    • SLICE

    • HLS

    • MP4

    • MP3

    The VOD storage mode is not supported. For the OSS storage mode, the selected formats must be included in the file formats specified in StorageParams.FileInfo.

    MP4
    MaxIdleTime

    integer

    No

    The idle timeout period in seconds. If a task is idle for a period longer than the value of MaxIdleTime, the task automatically stops. The value must be within the range of [10, 14400]. The maximum period is 4 hours. The default value is 300 seconds.

    • In stream mixing mode, the task is considered idle when all subscribed users stop publishing streams.

    • In single-stream recording mode, the streams are independent of each other. If any subscribed stream stops being published, the stream is considered idle. After the idle timeout period specified by MaxIdleTime, the recording for that stream stops. When all subscribed streams become idle and time out, the entire cloud recording task stops.

    600

    • For single-stream recording:

      • You can subscribe to both the camera and screen sharing streams of the same user ID. However, the FileNamePattern and SliceNamePattern parameters must include the SourceType variable to prevent recording files from being overwritten.

      • You cannot subscribe to only the video-only stream of a user ID. In single-stream mode, the value of UserInfo.StreamType cannot be 2.

    • In single-stream recording mode:

      • If RecordParams.StreamType is set to 1 (audio-only), you cannot subscribe to video-only streams in SubscribeParams (where StreamType is 2).

      • If RecordParams.StreamType is set to 2 (video-only), you cannot subscribe to audio-only streams in SubscribeParams (where StreamType is 1).

    • In stream mixing mode:

      • If RecordParams.StreamType is set to 1 (audio-only), the streams that you subscribe to in SubscribeParams cannot all be video-only streams (where StreamType is 2).

      • If RecordParams.StreamType is set to 2 (video-only), the streams that you subscribe to in SubscribeParams cannot all be audio-only streams (where StreamType is 1).

    • During recording, if the channel is closed, users must rejoin the channel and publish streams within the idle timeout period. Otherwise, the task stops automatically.

    Response elements

    Element

    Type

    Description

    Example

    object

    The response content.

    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******",
  "TaskId": "******73-8501-****-8ac1-72295a******"
}

    Error codes

    HTTP status code

    Error code

    Error message

    Description
    400 InvalidParameter.NotifyUrl %s, please check the notifyUrl. The parameter NotifyUrl format is invalid, please check.
    400 InvalidParameter.StorageParams.FileInfo %s, please check the fileInfo of storageParams. The parameter FileInfo has invalid fields, please check.
    400 InvalidParameter.StorageParams.OSSParams %s, please check the ossParams of storageParams. The parameter OSSParams has invalid fields, please check.
    400 NotFound.OSSBucket %s, please check the ossBucket of storageParams. The parameter OSSBucket does not exist.
    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.
    404 InvalidParameter.ChannelId %s, please check the channelId.
    404 InvalidParameter.AppId %s, please check the appId. The parameter AppId is invalid. Check it.
    405 InvalidParameter.StorageParams.VodParams %s, please check the vodParams of storageParams.
    405 InvalidParameter.NotifyAuthKey %s, please check the notifyAuthKey.
    405 InvalidParameter.MaxIdleTime %s, please check the maxIdleTime.
    405 InvalidParameter.RecordParams %s, please check the recordParams.
    405 InvalidParameter.StorageParams.StorageType %s, please check the storageType of storageParams. The parameter StorageType is invalid, please check.
    405 InvalidParameter.NotifyFileUploadedFormat %s, please check the notifyFileUploadedFormat. The parameter NotifyFileUploadedFormat is invalid, please check.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.