All Products
Search

This Product

    ApsaraVideo Live:StartRtcCloudRecording

    Document Center

    ApsaraVideo Live:StartRtcCloudRecording

    Last Updated:Mar 20, 2026

    Starts an RTC cloud recording task.

    Operation description

    Cloud recording is a paid feature. For more information, see Cloud recording fees.

    Endpoints

    This API operation is available at the following endpoints:

    RegionRegion IDPublic endpoint
    Shanghaicn-shanghailive.aliyuncs.com
    Singaporeap-southeast-1live.ap-southeast-1.aliyuncs.com
    US (Virginia)us-east-1live.us-east-1.aliyuncs.com

    QPS limits

    This API supports up to 50 calls per second for a single user. Calls that exceed this limit are throttled. This may affect your business. Plan your calls accordingly.

    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 that owns the channel to record. The app must belong to the Alibaba Cloud account you use to call this API operation.

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

    string

    Yes

    The ID of the channel to record. Make sure users are in the channel when you call this API operation. 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 individual recording mode, a separate recording file is generated for each user ID. In mixed-stream recording mode, the audio and video streams of all user IDs are mixed into one stream.

    Note

    • The array cannot be empty and can contain up to 17 elements.

    object

    No

    The 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 stream for the user ID. Valid values:

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

    • 1: Audio-only stream.

    • 2: Video-only stream. This value is valid only in mixed-stream recording mode.

    0
    SourceType

    integer

    No

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

    • 0: Camera. (Default)

    • 1: Screen sharing.

    0
    RecordParams

    object

    Yes

    The recording parameters.

    RecordMode

    integer

    Yes

    The recording mode. Valid values:

    • 0: Individual recording mode. A separate recording file is generated for each subscribed user ID.

    • 1: Mixed-stream recording mode. 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, which includes both audio and video. (Default)

    • 1: Audio-only stream.

    • 2: Video-only stream.

    0
    MaxFileDuration

    integer

    No

    The maximum duration of a recording file in seconds. Files that exceed this duration are split. The value must be between 180 and 7200 seconds (up to 2 hours). If you do not specify this parameter, the default is 7200 seconds.

    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 file storage information. This parameter specifies the format, storage location, and naming convention for recording files. It is valid only when StorageType is set to OSS.

    Note

    For each element in the array, a recording file with the corresponding configuration is generated. If you do not set this parameter, the default configuration for the HLS format is used. If you set this parameter but do not include a configuration for the HLS format, a default configuration for the HLS format is automatically generated.

    object

    No

    The storage configurations for different file formats.

    Format

    string

    Yes

    The file storage format. Valid values:

    • HLS

    • MP4

    • MP3

    HLS
    FileNamePattern

    string

    No

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

    • AppId

    • ChannelId

    • UserId (Required in individual recording mode. Invalid in mixed-stream recording mode. If selected, it is retained as the string {UserId}.)

    • RecordMode

      • A value of 0 corresponds to Single.

      • A value of 1 corresponds to Mix.

    • SourceType

      • In individual recording mode, this configuration takes effect when the stream is a video-only stream. SourceType can be set to:

        • A value of 0 corresponds to C (Camera) for a camera video stream.

        • A value of 1 corresponds to S (Screen) for a screen sharing video stream.

      • In individual recording mode, if the stream is an audio-only stream, SourceType is automatically set to A (Audio) to indicate that the recording is an audio-only stream.

      • In individual recording mode, this configuration takes effect when the stream is an original stream. SourceType can be set to:

        • A value of 0 corresponds to OC (Original Camera) for an original camera stream.

        • A value of 1 corresponds to OS (Original Screen) for an original screen sharing stream.

      • In other scenarios, the SourceType configuration is invalid. If you manually configure SourceType, the system retains the {SourceType} placeholder string.

    • StreamType (Uses the StreamType parameter under RecordParams)

      • A value of 0 corresponds to AV (Audio Video) for a stream containing both audio and video.

      • A value of 1 corresponds to A (Audio) for an audio stream.

      • A value of 2 corresponds to V (Video) for a video stream.

    • StartTime: The time when the recording starts. The time is in the UTC+8 time zone, and the format is similar to 2025-03-25-11:27:28. (Required if you do not use the default value.)

    The default values are as follows:

    • Individual recording mode

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

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

    • Mixed-stream recording mode

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

    Note

    • The string can only consist of the preceding variables. Variable names must be enclosed in curly brackets ({}) and separated by an underscore (_). Each variable can appear at most once in the string.

    • If the file is named xxx, it is saved in a format similar to TaskId/xxx.m3u8. TaskId is the ID of the task generated when the cloud recording task starts. It is automatically added to the storage path.

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

    string

    No

    The naming format for segments. This parameter is valid only for the HLS format. It is similar to FileNamePattern, but with the addition of the Sequence variable:

    • AppId

    • ChannelId

    • UserId (Required in individual recording mode. Invalid in mixed-stream recording mode. If selected, it is retained as the string {UserId}.)

    • RecordMode

      • A value of 0 corresponds to Single.

      • A value of 1 corresponds to Mix.

    • SourceType

      • In individual recording mode, this parameter takes effect when the stream is a video-only stream. SourceType can be set to:

        • A value of 0 corresponds to C (Camera) for a camera video stream.

        • A value of 1 corresponds to S (Screen) for a screen sharing stream.

      • In individual recording mode, if the stream is an audio-only stream, SourceType is automatically set to A (Audio) to indicate that the recording is an audio-only stream.

      • In individual recording mode, this configuration takes effect when the stream is an original stream. SourceType can be set to:

        • A value of 0 corresponds to OC (Original Camera) for an original camera stream.

        • A value of 1 corresponds to OS (Original Screen) for an original screen sharing stream.

      • In other scenarios, the SourceType configuration is invalid. If you manually configure this parameter, the system retains the {SourceType} placeholder string.

    • StreamType (Uses the StreamType parameter under RecordParams)

      • A value of 0 corresponds to AV (Audio Video) for a stream containing both audio and video.

      • A value of 1 corresponds to A (Audio) for an audio stream.

      • A value of 2 corresponds to V (Video) for a video stream.

    • StartTime: The time when the recording starts. The time is in the UTC+8 time zone, and the format is similar to 2025-03-25-11:27:28. (Required if you do not use the default value.)

    • Sequence: For the HLS format, the .ts file name includes Sequence. This is invalid for other formats. (Required if you do not use the default value.)

    The default values are as follows:

    • Individual recording mode

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

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

    • Mixed-stream recording mode

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

    Note

    • The string can only consist of the preceding variables. Variable names must be enclosed in curly brackets ({}) and separated by an underscore (_). Each variable can appear at most once in the string.

    • If the segment is named xxx, it is saved in a format similar to TaskId/xxx.ts. TaskId is the ID of the task generated when the cloud recording task starts. It 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 each level of the directory. For example, if the parameter value is ["dir1","dir2"], the xxx.m3u8 file is saved as dir1/dir2/TaskId/xxx.m3u8. If this parameter is empty, the file is saved as TaskId/xxx.m3u8.

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

    • If you set FilePathPrefix, each element in the array can only contain letters (a-z, A-Z), digits (0-9), hyphens (-), and underscores (_). It cannot be an empty string.

    • The total length of the concatenated path from all levels in the array cannot exceed 128 characters. This includes the connecting slashes (/) but not the automatically added TaskId. For example, if the parameter value is ["dir1","dir2"], the concatenated path is "dir1/dir2/". The total number of characters of all elements in the array plus the length of the array (for the slashes) must not exceed 128.

    • The array can contain up to 5 elements, which means you can customize up to 5 levels of directories.

    string

    No

    The name of each directory level.

    dir1
    SliceDuration

    integer

    No

    The segment length in seconds. This parameter is valid only for the HLS format. The value must be between 10 and 30 seconds. 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 the storage method is OSS and is invalid when the storage method is VOD.

    OSSEndpoint

    string

    Yes

    The name of the OSS storage endpoint. The corresponding region ID must match the selected endpoint.

    oss-cn-shanghai.aliyuncs.com
    OSSBucket

    string

    Yes

    The name of the OSS storage bucket. The bucket must belong to the Alibaba Cloud account you use to call this API operation.

    mytest-bucket
    VodParams

    object

    No

    The VOD storage configuration. This parameter is required when the storage method is VOD and is invalid when the storage method is OSS.

    Note

    • The US (Virginia) region does not support recording to VOD.

    StorageLocation

    string

    No

    The storage address. You can find this address in the VOD console by choosing Media Asset Management Configuration > Storage. Recording files are first saved to this address and then uploaded to VOD.

    Note

    • Make sure that the region of the storage address matches the selected endpoint.

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

    string

    No

    The ID of the VOD transcoding template group.

    Note

    • Make sure that the region of the transcoding template group matches the selected endpoint.

    ****8a914d3989e9825eb90530b2****
    AutoCompose

    integer

    No

    Automatic merge. Valid values:

    • 0: Disable automatic merge. (Default)

    • 1: Enable automatic merge. If you enable this feature, you must set the ComposeVodTranscodeGroupId parameter.

    0
    ComposeVodTranscodeGroupId

    string

    No

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

    Note

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

    • If only one media asset file exists when the recording ends, automatic merging is not triggered, even if it is enabled.

    • For answers to common questions about automatic composition and transcoding, see FAQ about converting live streams to VOD.

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

    ****4c34112cfe68248f2f77759c****
    MixTranscodeParams

    object

    No

    The transcoding parameters. Do not set this parameter in individual recording mode. This parameter is required in mixed-stream recording mode.

    FrameFillType

    integer

    No

    The method to use for frame supplementation when a stream is interrupted. Valid values:

    • 0: Supplement with the last frame. (Default)

    0
    AudioBitrate

    integer

    Yes

    The audio bitrate in kbps. The value must be between 8 and 500. This parameter is required in mixed-stream recording mode.

    300
    AudioChannels

    integer

    Yes

    The number of audio channels. Valid values:

    • 1: Mono.

    • 2: Stereo.

    This parameter is required in mixed-stream recording mode.

    2
    AudioSampleRate

    integer

    Yes

    The audio sampling rate in Hz. Valid values:

    • 8000

    • 16000

    • 32000

    • 44100

    • 48000

    This parameter is required in mixed-stream recording 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 kbps. The value must be between 1 and 10000. This parameter is required in mixed-stream recording mode when the output is expected to include video. It is invalid in other cases.

    5000
    VideoFramerate

    integer

    No

    The video frame rate in fps. The value must be between 1 and 60. This parameter is required in mixed-stream recording mode when the output is expected to include video. It is invalid in other cases.

    30
    VideoGop

    integer

    No

    The video group of pictures (GOP). An I-frame exists for every VideoGop frames. The value must be between 1 and 60. This parameter is required in mixed-stream recording mode when the output is expected to include video. It is invalid in other cases.

    30
    VideoHeight

    integer

    No

    The video height in pixels. The value must be between 0 and 1920. (The default value is 0.)

    480
    VideoWidth

    integer

    No

    The video width in pixels. The value must be between 0 and 1920. (The default value is 0.)

    640
    MixLayoutParams

    object

    No

    The layout parameters. Do not set this parameter in individual recording mode. This parameter is required in mixed-stream recording mode when the recording is not an audio-only file.

    MixBackground

    object

    No

    The global background image for the mixed stream.

    RenderMode

    integer

    No

    The display mode for the video output. Valid values:

    • 0: Crop. (Default)

    • 1: Scale and display 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<object>

    No

    Specifies the window layout information for subscribed users. Only user IDs with layout information are included in the video. This parameter is required in mixed-stream recording mode when the recording is not an audio-only file.

    array<object>

    No

    The window configuration in the video.

    UserId

    string

    No

    The user ID corresponding to this window.

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

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

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

    userA
    SourceType

    integer

    No

    The type of video input stream for the user ID. If you do not specify a user ID, this SourceType setting is invalid. Valid values:

    • 0: Camera. (Default)

    • 1: Screen sharing.

    The combination of the user ID and SourceType set 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. (The default value is 0.)

    0.5
    Width

    string

    No

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

    0.5
    X

    string

    No

    The X coordinate as a normalized percentage. The value must be between 0 and 1. (The default value is 0.)

    0
    Y

    string

    No

    The Y coordinate as a normalized percentage. The value must be between 0 and 1. (The default value is 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. (The default value is 0.)

    0
    SubBackground

    object

    No

    The background image for the sub-window. When a user turns off their camera, does not push a stream after joining, or leaves mid-session, the corresponding image fills their layout position.

    RenderMode

    integer

    No

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

    • 0: Crop. (Default)

    • 1: Scale and display 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
    NotifyUrl

    string

    No

    The address to receive callback messages. The address can be up to 2,048 characters long. Task status messages are sent to this address as JSON-formatted POST requests.

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

    http://xxxx/test/mycallback
    NotifyAuthKey

    string

    No

    The authentication key for callback messages. By default, this is empty, which means no authentication is performed. If you specify a key, it must be 16 to 64 characters long and contain only uppercase letters, lowercase letters, and digits.

    • If NotifyUrl is not specified, NotifyAuthKey is also invalid.

    • If a valid NotifyAuthKey is set, the callback message includes authentication content.

    mytestkeymytestkey
    NotifyFileUploadedFormat

    array

    No

    When the RecordFileUploaded event is triggered, a callback message is sent in the specified format.

    string

    No

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

    • 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 of StorageParams.FileInfo.

    MP4
    MaxIdleTime

    integer

    No

    The idle timeout period. If a task remains idle for longer than MaxIdleTime, it stops automatically. Unit: seconds. The value must be between 10 and 14400 seconds (up to 4 hours). The default value is 300 seconds.

    • For mixed-stream recording mode, the task is considered idle when all subscribed user streams stop.

    • For individual recording mode, subscribed streams are independent. If any stream stops, it is considered idle. After MaxIdleTime is reached, the recording for that stream stops. When all subscribed streams time out due to inactivity, the entire cloud recording task stops.

    600

    • In individual recording mode:

      • You can simultaneously 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. This means that in individual recording mode, UserInfo.StreamType cannot be set to 2.

    • In individual recording mode:

      • If RecordParams.StreamType is set to audio-only (value 1), SubscribeParams cannot include a subscription to a video-only stream (value 2).

      • If RecordParams.StreamType is set to video-only (value 2), SubscribeParams cannot include a subscription to an audio-only stream (value 1).

    • In mixed-stream recording mode:

      • If RecordParams.StreamType is set to audio-only (value 1), not all user IDs in SubscribeParams can be subscribed to as video-only streams (value 2).

      • If RecordParams.StreamType is set to video-only (value 2), not all user IDs in SubscribeParams can be subscribed to as audio-only streams (value 1).

    • If a channel closes during recording, rejoin the channel and start stream ingest within the idle duration. Otherwise, the task stops automatically.

    Response elements

    Element

    Type

    Description

    Example

    object

    The 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******",
  "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.