All Products
Search

This Product

    ApsaraVideo Live:StartRtcCloudRecording

    Document Center

    ApsaraVideo Live:StartRtcCloudRecording

    Last Updated:Jul 14, 2026

    Starts an RTC cloud recording task.

    Operation description

    Cloud recording is a paid feature. For billing details, see Cloud recording fees.

    Endpoints

    The following endpoints are active for this operation:

    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

    Rate limit

    The individual user QPS limit for this operation is 50 calls per second. If this limit is exceeded, API calls are throttled, which may affect your business. Invoke this operation as needed.

    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 primary account of the current API caller.

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

    string

    Yes

    The ID of the channel to be recorded. Ensure that the channel has active users when this operation is called. Otherwise, the recording task fails to be created.

    room1024
    SubscribeParams

    object

    Yes

    The subscription parameters.

    SubscribeUserIdList

    array<object>

    Yes

    The list of subscribed UserId information. In single-stream recording mode, each UserId is recorded separately. In stream mixing recording mode, the audio and video of all UserIds are mixed into one set of audio and video.

    Note

    • The array cannot be empty and supports a maximum of 17 elements.

    object

    No

    The information of a subscribed UserId.

    UserId

    string

    Yes

    The subscribed UserId.

    userA
    StreamType

    integer

    No

    The media type of the subscribed UserId. Valid values:

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

    • 1: audio-only stream.

    • 2: video-only stream (valid only in stream mixing recording mode).

    Valid values:

    • 0 :

      original stream, which includes both audio and video.

    • 1 :

      audio-only stream.

    • 2 :

      video-only stream.

    0
    SourceType

    integer

    No

    The video input stream type of the UserId. This parameter is valid only when subscribing to a non-audio-only stream (StreamType != 1). Valid values:

    • 0: camera. (Default)

    • 1: screen sharing.

    Valid values:

    • 0 :

      camera.

    • 1 :

      screen sharing.

    0
    RecordParams

    object

    Yes

    The recording parameters.

    RecordMode

    integer

    Yes

    The recording mode. Valid values:

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

    • 1: stream mixing recording mode. The streams of all subscribed UserIds are mixed and transcoded, and only one set of recording files is generated.

    Valid values:

    • 0 :

      single-stream recording mode. A separate recording file is generated for each subscribed UserId.

    • 1 :

      stream mixing recording mode. The streams of all subscribed UserIds are mixed and transcoded, and only one set of recording files is generated.

    0
    StreamType

    integer

    No

    The media type of the recorded output stream. Valid values:

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

    • 1: audio-only stream.

    • 2: video-only stream.

    Valid values:

    • 0 :

      original stream, which includes both audio and video.

    • 1 :

      audio-only stream.

    • 2 :

      video-only stream.

    0
    MaxFileDuration

    integer

    No

    The maximum duration of a recording file, in seconds. Recording files that exceed this duration are split. The value must be within the range of [180, 7200], which is a maximum of 2 hours. If not specified, the default value is 2 hours.

    7200
    StorageParams

    object

    Yes

    The storage parameters.

    StorageType

    integer

    Yes

    The storage method. Valid values:

    • 0: VOD

    • 1: OSS

    Valid values:

    • 0 :

      VOD

    • 1 :

      OSS

    1
    FileInfo

    array<object>

    No

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

    Note

    A recording file is generated for each element in the array based on the corresponding configuration. If no format is specified, the HLS format is used by default.

    object

    No

    The storage configuration for different file formats.

    Format

    string

    Yes

    The file storage format. Valid values:

    • HLS

    • MP4

    • MP3

    Valid values:

    • MP4 :

      MP4 format.

    • MP3 :

      MP3 format.

    • HLS :

      HLS format.

    HLS
    FileNamePattern

    string

    No

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

    • AppId

    • ChannelId

    • UserId (required in single-stream mode; invalid in stream mixing mode, where it is retained as the {UserId} string if selected)

    • RecordMode

      • When the value is 0, it corresponds to Single

      • When the value is 1, it corresponds to Mix

    • SourceType

      • In single-stream mode, when the stream type is video-only, this parameter takes effect. SourceType can be configured as:

        • When the value is 0, it corresponds to C (Camera) for camera video stream.

        • When the value is 1, it corresponds to S (Screen) for screen sharing video stream.

      • In single-stream mode, when the stream type is audio-only, SourceType is automatically configured as A (Audio) to identify the recorded content as an audio-only stream.

      • In single-stream mode, when the stream type is original stream, this parameter takes effect. SourceType can be configured as:

        • When the value is 0, it corresponds to OC (Original Camera) for camera original stream.

        • When the value is 1, it corresponds to OS (Original Screen) for screen sharing original 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)

      • When the value is 0, it corresponds to AV (Audio Video) for audio and video streams.

      • When the value is 1, it corresponds to A (Audio) for audio stream.

      • When the value is 2, it corresponds to V (Video) for video stream.

    • StartTime: the time when recording starts, in UTC+8 time zone, in a format similar to 2025-03-25-11:27:28. (Required when not using the default value)

    Default values:

    • Single-stream recording mode

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

      • If different StreamType or SourceType values are subscribed for the same UserId, the default value is {AppId}_{ChannelId}_{UserId}_{SourceType}_{StartTime}

    • Stream mixing recording mode

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

    Note

    • The string can only consist of the above variables. Variable names must be wrapped in {}. Variable names are separated by a single underscore (_). Each variable can appear at most once in the string.

    • After naming as xxx, the file is saved in a format similar to TaskId/xxx.m3u8, where TaskId is the task ID generated when the cloud recording task is started and is automatically added to the storage path.

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

    string

    No

    The segment naming format. This parameter is valid only in HLS format. Similar to FileNamePattern, except that the Sequence variable is additionally available:

    • AppId

    • ChannelId

    • UserId (required in single-stream mode; invalid in stream mixing mode, where it is retained as the {UserId} string if selected)

    • RecordMode

      • When the value is 0, it corresponds to Single

      • When the value is 1, it corresponds to Mix

    • SourceType

      • In single-stream mode, when the stream type is video-only, this parameter takes effect. SourceType can be configured as:

        • When the value is 0, it corresponds to C (Camera) for camera video stream.

        • When the value is 1, it corresponds to S (Screen) for screen sharing stream.

      • In single-stream mode, when the stream type is audio-only, SourceType is automatically configured as A (Audio) to identify the recorded content as an audio-only stream.

      • In single-stream mode, when the stream type is original stream, this parameter takes effect. SourceType can be configured as:

        • When the value is 0, it corresponds to OC (Original Camera) for camera original stream.

        • When the value is 1, it corresponds to OS (Original Screen) for screen sharing original 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)

      • When the value is 0, it corresponds to AV (Audio Video) for audio and video streams.

      • When the value is 1, it corresponds to A (Audio) for audio stream.

      • When the value is 2, it corresponds to V (Video) for video stream.

    • StartTime: the time when recording starts, in UTC+8 time zone, in a format similar to 2025-03-25-11:27:28. (Required when not using the default value)

    • Sequence: in HLS format, the ts file name contains Sequence. This variable is invalid for other formats. (Required when not using the default value)

    Default values:

    • Single-stream recording mode

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

      • If different StreamType or SourceType values are subscribed for the same UserId, the default value is {AppId}_{ChannelId}_{UserId}_{SourceType}_{StartTime}_{Sequence}

    • Stream mixing recording mode

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

    Note

    • The string can only consist of the above variables. Variable names must be wrapped in {}. Variable names are separated by a single underscore (_). Each variable can appear at most once in the string.

    • After naming as xxx, the segment file is saved in a format similar to TaskId/xxx.ts, where TaskId is the task ID generated when the cloud recording task is started and is automatically added to the storage path.

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

    array

    No

    The file storage path. Each element in the array corresponds to a directory level. 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 directly 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 together.

    • If FilePathPrefix is set, each element in the array can only consist of letters (a-zA-Z), digits (0-9), hyphens (-), and underscores (_), and cannot be an empty string.

    • The total length of all path levels concatenated together cannot exceed 128 characters (including the connecting '/' characters, but excluding the automatically appended TaskId). For example, if the parameter value is ["dir1","dir2"], the concatenated path is "dir1/dir2/", meaning the total character count of all elements plus the array length (corresponding to the "/" after each path level) cannot exceed 128.

    • The number of elements in the array cannot exceed 5, meaning a maximum of 5 custom path levels.

    string

    No

    The name of each directory level.

    dir1
    SliceDuration

    integer

    No

    The segment length in seconds. This parameter is valid only in HLS format. The value must be within the range of [10, 30]. (Default value: 30)

    If you do not have special requirements, use the default value.

    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 endpoint of the OSS storage. The corresponding region ID must be consistent with the selected endpoint.

    oss-cn-shanghai.aliyuncs.com
    OSSBucket

    string

    Yes

    The bucket name of the OSS storage. The bucket must belong to the primary account of the current API caller.

    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 currently support recording to VOD.

    StorageLocation

    string

    No

    The storage address configured in the video-on-demand console under Media Asset Management > Storage Management. Recording files are first saved to this location and then uploaded to VOD.

    Note

    • Ensure that the region of the storage address is consistent with the selected endpoint.

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

    string

    No

    The video-on-demand transcoding template group ID.

    Note

    • Ensure that the area of the transcoding template group ID is consistent with the selected endpoint.

    ****8a914d3989e9825eb90530b2****
    AutoCompose

    integer

    No

    Specifies whether to enable automatic merging. Valid values:

    • 0: Disabled. (Default)

    • 1: Enabled. When enabled, the ComposeVodTranscodeGroupId parameter must be set.

    Valid values:

    • 0 :

      disabled.

    • 1 :

      enabled. When enabled, the ComposeVodTranscodeGroupId parameter must be set.

    0
    ComposeVodTranscodeGroupId

    string

    No

    The VOD transcoding template group ID used to transcode the new video generated by automatic merging in the video-on-demand service.

    Note

    • This parameter is required only when AutoCompose (whether to enable automatic merging) is set to 1.

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

    • For common issues about automatic merging and transcoding, see Live-to-VOD FAQ.

    • For VOD transcoding billing details, see Media transcoding billing.

    ****4c34112cfe68248f2f77759c****
    MixTranscodeParams

    object

    No

    The transcoding parameters. This parameter is not required in single-stream recording mode and is required in stream mixing recording mode.

    FrameFillType

    integer

    No

    The frame fill type when a stream is interrupted. Valid values:

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

    Valid values:

    • 0 :

      fill with the last frame.

    0
    AudioBitrate

    integer

    Yes

    The audio bitrate in kbps. The value must be within the range of [8, 500]. Required in stream mixing mode.

    300
    AudioChannels

    integer

    Yes

    The number of audio channels. Valid values:

    • 1: mono.

    • 2: stereo.

    Required in stream mixing mode.

    Valid values:

    • 1 :

      mono.

    • 2 :

      stereo.

    2
    AudioSampleRate

    integer

    Yes

    The audio sample rate in Hz. Valid values:

    • 8000

    • 16000

    • 32000

    • 44100

    • 48000

    Required in stream mixing mode.

    Valid values:

    • 8000 :

      8000HZ

    • 16000 :

      16000HZ

    • 32000 :

      32000HZ

    • 44100 :

      44100HZ

    • 48000 :

      48000HZ

    32000
    VideoCodec

    string

    No

    The video encoding format. Valid values:

    • H.264 (Default)

    • H.265

    Valid values:

    • H.264 :

      H.264 encoding.

    • H.265 :

      H.265 encoding.

    H.264
    VideoBitrate

    integer

    No

    The video bitrate in kbps. The value must be within the range of [1, 10000]. Required in stream mixing mode when the recording output is expected to contain video. Invalid in other cases.

    5000
    VideoFramerate

    integer

    No

    The video frame rate in fps. The value must be within the range of [1, 60]. Required in stream mixing mode when the recording output is expected to contain video. Invalid in other cases.

    30
    VideoGop

    integer

    No

    The video GOP. One I-frame exists for every VideoGop frames. The value must be within the range of [1, 60]. Required in stream mixing mode when the recording output is expected to contain video. Invalid in other cases.

    30
    VideoHeight

    integer

    No

    The video height in pixels. The value must be within the range of [0, 1920]. (Default value: 0)

    480
    VideoWidth

    integer

    No

    The video width in pixels. The value must be within the range of [0, 1920]. (Default value: 0)

    640
    MixLayoutParams

    object

    No

    The layout parameters. This parameter is not required in single-stream recording mode. In stream mixing recording mode, this parameter is required when the recording output is expected to contain video.

    MixBackground

    object

    No

    The global background image for stream mixing.

    RenderMode

    integer

    No

    The display mode for the output. Valid values:

    • 0: Crop. (Default)

    • 1: Scale and display with black borders.

    Valid values:

    • 0 :

      crop.

    • 1 :

      scale and display with black borders.

    0
    Url

    string

    No

    The URL of the background image. The maximum length is 2048 characters.

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

    array<object>

    No

    The window layout information for subscribed users. Only UserIds with layout information configured are placed in the video. Required in stream mixing mode when recording non-audio-only files.

    array<object>

    No

    The window configuration in the video.

    UserId

    string

    No

    The UserId corresponding to this window.

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

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

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

    userA
    SourceType

    integer

    No

    The video input stream type of the UserId. Setting SourceType is invalid when UserId is not specified. Valid values:

    • 0: camera. (Default)

    • 1: screen sharing.

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

    Valid values:

    • 0 :

      camera.

    • 1 :

      screen sharing.

    0
    Height

    string

    No

    The pane height as a normalized percentage. The value must be within the range of [0, 1]. (Default value: 0)

    0.5
    Width

    string

    No

    The pane width as a normalized percentage. The value must be within the range of [0, 1]. (Default value: 0)

    0.5
    X

    string

    No

    The X coordinate as a normalized percentage. The value must be within the range of [0, 1]. (Default value: 0)

    0
    Y

    string

    No

    The Y coordinate as a normalized percentage. The value must be within the range of [0, 1]. (Default value: 0)

    0
    ZOrder

    integer

    No

    The stacking order. 0 is the bottom layer, layer 1 is above layer 0, and so on. (Default value: 0)

    0
    SubBackground

    object

    No

    The sub-pane background image. When a user turns off the camera, has not started stream ingest after joining, or leaves the channel midway, the corresponding image is filled in the layout position.

    RenderMode

    integer

    No

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

    • 0: Crop. (Default)

    • 1: Scale and display with black borders.

    Valid values:

    • 0 :

      crop.

    • 1 :

      scale and display with black borders.

    0
    Url

    string

    No

    The URL of the background image. The maximum length is 2048 characters.

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

    string

    No

    The URL for receiving callback messages. Task status messages are pushed to this URL in JSON format via POST. The maximum length is 2048 characters.

    For callback message details, see documentation.

    http://xxxx/test/mycallback
    NotifyAuthKey

    string

    No

    The authentication key for callback messages. If not specified, no authentication is performed. If specified, the length must be within [16, 64] characters and consist of only uppercase and lowercase letters and digits.

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

    • When a valid NotifyAuthKey is set, authentication content is included in the callback message.

    mytestkeymytestkey
    NotifyFileUploadedFormat

    array

    No

    The specified formats for which a callback message is sent when the recording file generation event (RecordFileUploaded) is triggered.

    string

    No

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

    • SLICE

    • HLS

    • MP4

    • MP3

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

    MP4
    MaxIdleTime

    integer

    No

    The idle timeout period. When the task remains idle for longer than MaxIdleTime, the task is automatically stopped. Unit: seconds. The value must be within the range of [10, 14400], which is a maximum of 4 hours. (Default value: 300 seconds)

    • In stream mixing recording mode, the task is considered idle when all subscribed user streams stop stream ingest.

    • In single-stream recording mode, subscribed streams are independent of each other. When any stream stops stream ingest, it is considered idle. After MaxIdleTime is reached, recording for that stream is stopped. When all subscribed streams have been idle beyond the timeout, the entire cloud recording task is stopped.

    600

    • In single-stream recording mode:

      • You can subscribe to both the camera and screen sharing streams of the same UserId simultaneously, but the FileNamePattern and SliceNamePattern parameters must include the SourceType variable (to avoid recording files overwriting each other).

      • Subscribing to only the video-only stream of a UserId is not currently supported. In single-stream mode, UserInfo.StreamType cannot be set to 2.

    • In single-stream recording mode:

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

      • If RecordParams.StreamType is video-only (value 2), SubscribeParams cannot contain an audio-only subscription (SubscribeParams value 1).

    • In stream mixing recording mode:

      • If RecordParams.StreamType is audio-only (value 1), not all UserIds in SubscribeParams can subscribe to video-only streams (all SubscribeParams values set to 2).

      • If RecordParams.StreamType is video-only (value 2), not all UserIds in SubscribeParams can subscribe to audio-only streams (all SubscribeParams values set to 1).

    • During recording, if the channel is closed midway, users must rejoin and resume stream ingest within the idle timeout period. Otherwise, the task is automatically stopped.

    Response elements

    Element

    Type

    Description

    Example

    object

    The response parameters.

    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.
    403 QuotaExceed.RunningTask The number of active cloud recording tasks has reached the limit. The number of active cloud recording tasks has reached the limit.
    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.