Documentation
Home Page ApsaraVideo Live Developer Reference API Reference API catalog ApsaraVideo Real-time Communication Cloud recording StartRtcCloudRecording

StartRtcCloudRecording

Updated at:
Copy as MD
Product

Starts an RTC cloud recording task.

Operation description

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

Service registration

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

QPS limit

The single-user QPS limit for this operation is 50 calls per second. If this limit is exceeded, the API call is 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 Alibaba Cloud account that calls this operation.

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

string

Yes

The ID of the channel to be recorded. Make sure that the channel has active users when you call this operation. Otherwise, the recording task fails to be created.

room1024
SubscribeParams

object

Yes

The subscription parameters.

SubscribeUserIdList

array<object>

Yes

The list of subscribed UserIds. 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 a single set of audio and video.

Note

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

object

No

The information about 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 the subscribed stream is not audio-only (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 recording 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 in the range of [180, 7200], which is a maximum of 2 hours. Default value: 7200.

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 convention 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 each file format.

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. If selected, the {UserId} string is retained.)

  • 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 set to:

      • 0: corresponds to C (Camera) for camera video stream.

      • 1: corresponds to S (Screen) for screen sharing video stream.

    • In single-stream mode, when the stream type is audio-only, SourceType is automatically set to A (Audio) to indicate that the recording content is an audio-only stream.

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

      • 0: corresponds to OC (Original Camera) for camera original stream.

      • 1: 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 the default value is not used.)

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 variables listed above. Variable names must be enclosed in {}. Variables are separated by a single underscore (_). Each variable can appear at most once in the string.

  • After the file is named 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 for the HLS format. Similar to FileNamePattern, but with an additional variable Sequence:

  • AppId

  • ChannelId

  • UserId (required in single-stream mode. Invalid in stream mixing mode. If selected, the {UserId} string is retained.)

  • 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 set to:

      • 0: corresponds to C (Camera) for camera video stream.

      • 1: corresponds to S (Screen) for screen sharing stream.

    • In single-stream mode, when the stream type is audio-only, SourceType is automatically set to A (Audio) to indicate that the recording content is an audio-only stream.

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

      • 0: corresponds to OC (Original Camera) for camera original stream.

      • 1: 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 the default value is not used.)

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

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 variables listed above. Variable names must be enclosed in {}. Variables are separated by a single underscore (_). Each variable can appear at most once in the string.

  • After the segment is named 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 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 contain letters (a-zA-Z), digits (0-9), hyphens (-), and underscores (_), and cannot be an empty string.

  • The total length of all directory 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 number of characters in all elements plus the array length (corresponding to the "/" after each directory level) cannot exceed 128.

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

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 in 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 match the selected service registration 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 calls this 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 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

  • Make sure that the area of this storage address matches the selected service registration endpoint.

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

string

No

The ID of the video-on-demand transcoding template group.

Note

  • Make sure that the area of this transcoding template group ID matches the selected service registration 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 ID of the VOD transcoding template group used to transcode the automatically composed new video in ApsaraVideo VOD.

Note

  • This parameter is required only when AutoCompose 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 composition and transcoding, see Live-to-VOD FAQ.

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

****4c34112cfe68248f2f77759c****
MixTranscodeParams

object

No

The transcoding parameters. Do not set this parameter in single-stream recording mode. This parameter 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 Kbit/s. The value must be in 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.

Valid values:

  • 1 :

    mono.

  • 2 :

    stereo.

2
AudioSampleRate

integer

Yes

The audio sample rate in Hz. Valid values:

  • 8000

  • 16000

  • 32000

  • 44100

  • 48000

This parameter is 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 Kbit/s. The value must be in the range of [1, 10000]. This parameter is required in stream mixing mode when the recording output is expected to contain video. Otherwise, this parameter is invalid.

5000
VideoFramerate

integer

No

The video frame rate in fps. The value must be in the range of [1, 60]. This parameter is required in stream mixing mode when the recording output is expected to contain video. Otherwise, this parameter is invalid.

30
VideoGop

integer

No

The video GOP. An I-frame exists every VideoGop frames. The value must be in the range of [1, 60]. This parameter is required in stream mixing mode when the recording output is expected to contain video. Otherwise, this parameter is invalid.

30
VideoHeight

integer

No

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

480
VideoWidth

integer

No

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

640
MixLayoutParams

object

No

The layout parameters. Do not set this parameter in single-stream recording mode. This parameter is required in stream mixing recording mode 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. 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 UserId corresponding to this window.

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

  • The combination of UserId 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 of the UserId. Setting SourceType without specifying UserId has no effect. Valid values:

  • 0: camera. (Default)

  • 1: screen sharing.

The combination of UserId and SourceType specified 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 in the range of [0, 1]. Default value: 0.

0.5
Width

string

No

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

0.5
X

string

No

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

0
Y

string

No

The Y coordinate as a normalized percentage. The value must be in 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 displayed at 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 sent to this URL via POST in JSON format. 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 in the range of [16, 64] characters and can only contain uppercase and lowercase letters and digits.

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

  • If 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 formats for which callbacks are received. Valid values (case-insensitive):

  • SLICE

  • HLS

  • MP4

  • MP3

VOD storage mode is not supported. For 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. When the task remains idle for longer than MaxIdleTime, the task is automatically stopped. The value must be in the range of [10, 14400], which is a maximum of 4 hours. Default value: 300.

  • 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 stops. When all subscribed streams have been idle beyond the timeout, the entire cloud recording task stops.

600

  • For 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 prevent recording files from overwriting each other.

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

  • In single-stream recording mode:

    • If RecordParams.StreamType is set to audio-only (value 1), SubscribeParams cannot contain any video-only subscriptions (SubscribeParams value 2).

    • If RecordParams.StreamType is set to video-only (value 2), SubscribeParams cannot contain any audio-only subscriptions (SubscribeParams value 1).

  • In stream mixing recording mode:

    • If RecordParams.StreamType is set to 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 set to 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.
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.

Previous：Cloud recordingNext：UpdateRtcCloudRecording