Implement RTC Cloud Recording via StartRtcCloudRecording API - ApsaraVideo Live - Alibaba Cloud - ApsaraVideo Live

Starts an RTC cloud recording task.

Operation description

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

Service registration

QPS limit.

Try it now

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

Test

RAM authorization

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

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

live:StartRtcCloudRecording

create

*All Resource

*

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 associated with the current API caller's account.	******-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 UserId entries. 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.
	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: 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 takes effect only when the subscription is not audio-only (StreamType != 1). Valid values: Valid values: 0 : camera. 1 : screen sharing.	0
RecordParams	object	Yes	The recording parameters.
RecordMode	integer	Yes	The recording mode. Valid values: Valid values: 0 : single-stream recording mode, in which a separate recording file is generated for each subscribed UserId. 1 : stream mixing recording mode, in which the streams of all subscribed UserIds are mixed and transcoded to generate a single set of recording files.	0
StreamType	integer	No	The media type of the output recording stream. Valid values: 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. A recording file that exceeds this duration is split. The value must be in the range of [180, 7200], which means a maximum of 2 hours. If this parameter is not specified, the default value is 7200 (2 hours).	7200
StorageParams	object	Yes	The storage parameters.
StorageType	integer	Yes	The storage method. Valid values: 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 takes effect only when StorageType is set to OSS.
	object	No	The storage configuration for different file formats.
Format	string	Yes	The file storage format. Valid values: 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}_{StartTime}_{UserId}
SliceNamePattern	string	No	The segment naming format. This parameter takes effect only in HLS format. Similar to FileNamePattern, but with an additional variable Sequence:	{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 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.
	string	No	The name of each directory level.	dir1
SliceDuration	integer	No	The segment length in seconds. This parameter takes effect only in HLS format. The value must be in the range of [10, 30]. Default value: 30.	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 service registration endpoint.	oss-cn-shanghai.aliyuncs.com
OSSBucket	string	Yes	The name of the OSS bucket. The bucket must belong to the primary account associated with the current API caller's account.	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.
StorageLocation	string	No	The storage address configured in the ApsaraVideo VOD console under Media Asset Management > Storage Management. Recording files are first saved to this location 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: Valid values: 0 : Disable automatic composition. 1 : Enable automatic composition. When enabled, the ComposeVodTranscodeGroupId parameter must be specified.	0
ComposeVodTranscodeGroupId	string	No	The ID of the VOD transcoding template group used to transcode the automatically composed video in the VOD service.	**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: Valid values: 0 : Fill with the last frame.	0
AudioBitrate	integer	Yes	The audio bitrate in kbps. 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: Valid values: 1 : mono. 2 : stereo.	2
AudioSampleRate	integer	Yes	The audio sample rate in Hz. Valid values: Valid values: 8000 : 8000HZ 16000 : 16000HZ 32000 : 32000HZ 44100 : 44100HZ 48000 : 48000HZ	32000
VideoCodec	string	No	The video encoding format. Valid values: 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 in the range of [1, 10000].	5000
VideoFramerate	integer	No	The video frame rate in fps. The value must be in the range of [1, 60].	30
VideoGop	integer	No	The video GOP. An I-frame is inserted every VideoGop frames. The value must be in the range of [1, 60].	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. This parameter is not required in single-stream recording mode and is required in stream mixing recording mode when the output is not audio-only.
MixBackground	object	No	The global background image for stream mixing.
RenderMode	integer	No	The display mode for the output. Valid values: 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	Specifies the window layout information for subscribed users. Only users whose UserId has layout information configured are included in the video. This parameter is required in stream mixing mode when recording non-audio-only files.
	array<object>	No	The window configuration in the video.
UserId	string	No	The UserId corresponding to this window.	userA
SourceType	integer	No	The video input stream type for this UserId. If UserId is not specified, this SourceType setting has no effect. Valid values: Valid values: 0 : camera. 1 : screen sharing.	0
Height	string	No	The pane height as a normalized percentage. The value must be within [0,1]. Default value: 0.	0.5
Width	string	No	The pane width as a normalized percentage. The value must be within [0,1]. Default value: 0.	0.5
X	string	No	The X coordinate as a normalized percentage. The value must be within [0,1]. Default value: 0.	0
Y	string	No	The Y coordinate as a normalized percentage. The value must be within [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 background image for the sub-pane. When a user turns off the camera, has not published a stream after joining, or leaves the channel midway, the corresponding image fills 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 by using the POST method. The maximum length is 2048 characters.	http://xxxx/test/mycallback
NotifyAuthKey	string	No	The authentication key for callback messages. Leave this parameter empty to skip authentication. If specified, the key must be 16 to 64 characters in length and consist of only uppercase and lowercase letters and digits.	mytestkeymytestkey
NotifyFileUploadedFormat	array	No	The specified formats for which a callback message is sent when the recording file upload event (RecordFileUploaded) is triggered.
	string	No	The specific file formats for which callbacks are received. Valid values (case-insensitive):	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 [10,14400], which is a maximum of 4 hours. Default value: 300.	600

For single-stream recording mode:
In single-stream recording mode:
In stream mixing recording mode:
During recording, if the channel is closed midway, you must rejoin and publish the stream within the idle timeout period. Otherwise, the task is automatically stopped.

Response elements

Element	Type	Description	Example
	object	The response body.
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.