DocsICP FilingConsole
Documentation

StartCloudRecord

Updated at:
Copy as MD
Product
My Favorites

Start a cloud recording task.

Operation description

Usage notes

Start cloud recording for an online channel.

QPS limit

The maximum queries per second (QPS) for this operation is 10 per user. Requests that exceed this limit are throttled, which may affect your business. Call this operation at a reasonable rate.

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

rtc:StartCloudRecord

create

*App

acs:rtc:*:{#accountId}:app/{#AppId}

 None None

Request parameters

Parameter

Type

Required

Description

Example
AppId

string

Yes

The application ID. You can create and view the application ID in the console. Only one application ID is supported.

eo85****
ChannelId

string

Yes

The existing channel ID. Only one channel ID is supported.

testid
TemplateId

string

Yes

The template ID.

567
TaskId

string

No

The task ID of this cloud recording task. Only one task ID is supported. The task ID can contain letters, digits, underscores (_), and hyphens (-). Maximum length: 55 bytes.

123
CropMode

integer

No

The cropping mode. Valid values:

  • 1: Crop while maintaining the aspect ratio.

  • 2: Pad while maintaining the aspect ratio. Default value.

  • 3: Stretch to fill the area.

2
ReservePaneForNoCameraUser

boolean

No

A placeholder for user panes when no camera stream is pushed. The default value is true, which reserves a pane for users who do not push a camera stream. If you set this parameter to false, no pane is reserved for users without a camera stream.

ShowDefaultBackgroundOnMute

boolean

No

Show the default background image for muted users.

  • true: Show the default background image. Default value.

  • false: Do not show the default background image. Custom background images still display.

SubHighResolutionStream

boolean

No

Subscribe to high-resolution streams.

  • false: Subscribe to streams of different resolutions based on the pane area. Default value.

  • true: Use the highest resolution stream published by the client.

StartWithoutChannel

boolean

No

Start the recording task even if the channel does not exist.

  • true: Yes.

  • false: No. Default value.

StartWithoutChannelWaitTime

integer

No

The wait time before starting the recording task if the channel does not exist. This parameter takes effect only when StartWithoutChannel is set to true. Unit: seconds. Valid values: 30 to 120.

30
Annotation

string

No

Enable or disable annotation.

disable
StorageConfig

object

Yes

Storage configuration.

testid
Vendor

integer

Yes

The storage platform. Valid values:

vendorObject Storage ServiceRemarks
1AliYun OSSAlibaba Cloud
2AliYun Apsara Stack OSSApsara Stack

1
Region

integer

Yes

The storage region.

RegionAliYun OSS
0CN_Hangzhou
1CN_Shanghai
2CN_Qingdao
3CN_Beijing
4CN_Zhangjiakou
5CN_Huhehaote
6CN_Shenzhen
7CN_Hongkong
8US_West_1
9US_East_1
10AP_Southeast_1
11AP_Southeast_2 (decommissioned. Do not use.)
12AP_Southeast_3
13AP_Southeast_5
14AP_Northeast_1
15AP_South_1 (decommissioned. Do not use.)
16EU_Central_1
17EU_West_1
18EU_East_1(ME_East_1)
19AP_Southeast_6
20CN_Heyuan
21CN_Guangzhou
22CN_Chengdu
23CN_Nanjing
24CN_Fuzhou
25CN_Wulanchabu
26CN_Northeast_2
27CN_Southeast_7
28CN_Wuhan_LR
100oss-cn-hzjbp
101oss-cn-shanghai-finance-1
102oss-cn-shenzhen-finance-1
103oss-cn-beijing-finance-1
104oss-cn-hzfinance
105oss-cn-shanghai-finance-1-pub
106oss-cn-szfinance
107oss-cn-beijing-finance-1-pub
RegionAliYun Apsara Stack OSS
0default

0
Bucket

string

Yes

The bucket name.

test-bucket-for-recording
AccessKey

string

Yes

The AccessKey. Grant the RAM user associated with this AccessKey the write permission on the Object Storage Service product of the corresponding cloud provider. Otherwise, the recording files cannot be written to the bucket.

LTAX***
SecretKey

string

Yes

The SecretKey.

APb6qWYEzKtYxE***
Endpoint

string

No

The private endpoint for Apsara Stack.

https://aliyuns.dalian.oss.com
Panes

array<object>

No

Cell configuration settings.

eo85****

array<object>

No

VideoOrder

string

No

The order in which video sources are filled when SourceType is set to video.

  • screenFirst: Prioritize screen sharing. Default value.

  • cameraFirst: Prioritize camera streams.

cameraFirst
SourceType

string

No

The media type of the pane. Valid values:

  • video: Camera or screen-sharing stream. Default value.

  • camera: Camera stream.

  • screen: Screen-sharing stream.

  • whiteboard: Whiteboard.

video
Images

array<object>

No

Local image watermarks for panes.

object

No

PaneImageCropMode

integer

No

The cropping mode. Valid values:

  • 1: Crop while maintaining the aspect ratio.

  • 2: Pad while maintaining the aspect ratio.

  • 3: Stretch to fill the area.

2
Alpha

number

No

The transparency level.

0.9
X

number

Yes

The x-coordinate.

0.2
Y

number

Yes

The y-coordinate.

0.2
Height

number

Yes

The height.

0.2
Width

number

Yes

The width.

0.2
Layer

integer

No

The z-axis layer.

0
Url

string

Yes

The image content cannot be updated during streaming.

https://aliyun.com/123xx.jpg
Display

string

No

When to display the watermark.

  • streamOnly: Display only when the current user has a video stream. Default value.

  • backup: Display only when the current user does not have a video stream.

  • always: Always display.

backup
Texts

array<object>

No

Local text watermarks for panes.

array<object>

No

BoxBorderw

integer

No

The border width of the bounding box.

5
FontColor

object

No

The font color.

R

integer

No

The red component.

255
B

integer

No

The blue component.

255
G

integer

No

The green component.

255
Texture

string

Yes

The watermark content.

文字水印
Layer

integer

No

The z-axis layer.

0
Font

integer

No

The font. Valid values:

  • 0: Alibaba PuHuiTi Regular

  • 1: Alibaba PuHuiTi Light

  • 2: Alibaba PuHuiTi Medium

  • 3: Alibaba PuHuiTi Bold

  • 4: Alibaba PuHuiTi Heavy

  • 5: Alimama Shuhei Ti

  • 6: DingTalk Jinbu Ti

  • 7: Alimama Dao Li Ti

  • 8: Alimama Dongfang Dakaishu

  • 9: Alimama Fangyuan Ti

0
BoxColor

object

No

The bounding box color.

R

integer

No

The red component.

255
B

integer

No

The blue component.

255
G

integer

No

The green component.

255
FontSize

integer

No

The font size.

36
Alpha

number

No

The watermark transparency.

0.9
X

number

Yes

The x-coordinate.

0.2
HasBox

boolean

No

Whether to draw a bounding box.

Y

number

Yes

The y-coordinate.

0.2
BoxAlpha

number

No

The bounding box transparency.

0.6
Display

string

No

When to display the watermark.

  • streamOnly: Display only when the current user has a video stream. Default value.

  • backup: Display only when the current user does not have a video stream.

  • always: Always display.

backup
PaneCropMode

integer

No

The cropping mode. Valid values:

  • 1: Crop while maintaining the aspect ratio.

  • 2: Pad while maintaining the aspect ratio.

  • 3: Stretch to fill the area.

3
PaneId

integer

Yes

The layout ID. Starts from 0.

0
Source

string

No

The media source for the pane. You can specify a user ID. To specify a particular user type, use wildcards. Supported wildcards:

  • $ActiveSpeaker: The current active speaker in the channel.

  • $ScreenShare: The screen-sharing user. If multiple users share their screens, they are filled in order.

22
Backgrounds

array<object>

No

Background images.

object

No

Alpha

number

No

The transparency level.

0.9
X

number

Yes

The x-coordinate.

0.2
Y

number

Yes

The y-coordinate.

0.2
PaneBackgroundCropMode

integer

No

The cropping mode. Valid values:

  • 1: Crop while maintaining the aspect ratio.

  • 2: Pad while maintaining the aspect ratio.

  • 3: Stretch to fill the area.

2
Height

number

Yes

The height.

0.2
Width

number

Yes

The width.

0.3
Layer

integer

No

The z-axis layer.

0
Url

string

Yes

The image URL.

https://aliyun.com/123xx.jpg
Display

string

No

When to display the background image.

  • streamOnly: Display only when the current user has a video stream. Default value.

  • backup: Display only when the current user does not have a video stream.

  • always: Always display.

backup
Whiteboard

object

No

Whiteboard configuration.

WhiteboardId

string

No

The whiteboard ID. Default value: default.

default
ReservePaneForOfflineUser

boolean

No

If set to true, reserve a pane when the specified user or wildcard user goes offline. Default value: true.

If set to false, display video streams in auto-fill order when the specified user or wildcard user goes offline.

Images

array<object>

No

Global image watermarks.

disable

object

No

Alpha

number

No

The transparency level.

0.9
X

number

Yes

The x-coordinate.

0.2
Y

number

Yes

The y-coordinate.

0.3
Height

number

Yes

The height.

0.2
ImageCropMode

integer

No

The cropping mode. Valid values:

  • 1: Crop while maintaining the aspect ratio.

  • 2: Pad while maintaining the aspect ratio.

  • 3: Stretch to fill the area.

2
Width

number

Yes

The width.

0.2
Layer

integer

No

The z-axis layer.

0
Url

string

Yes

The image URL. The image content cannot be updated during stream ingest.

https://aliyun.com/123xxx.jpg
Backgrounds

array<object>

No

Background images.

object

No

BackgroundCropMode

integer

No

The cropping mode. Valid values:

  • 1: Crop while maintaining the aspect ratio.

  • 2: Pad while maintaining the aspect ratio.

  • 3: Stretch to fill the area.

2
Alpha

number

No

The transparency level.

0.9
X

number

Yes

The x-coordinate.

0.2
Y

number

Yes

The y-coordinate.

0.2
Height

number

Yes

The height.

0.2
Width

number

Yes

The width.

0.2
Layer

integer

No

The z-axis layer.

0
Url

string

Yes

The image URL.

https://aliyun.com/123.jpg
Texts

array<object>

No

Global text watermarks.

array<object>

No

BoxBorderw

integer

No

The border width of the bounding box.

5
BoxColor

object

No

The bounding box color.

R

integer

No

The red component.

255
B

integer

No

The blue component.

255
G

integer

No

The green component.

255
FontSize

integer

No

The font size.

36
Alpha

number

No

The watermark transparency.

0.1
FontColor

object

No

The font color.

R

integer

No

The red component.

255
B

integer

No

The blue component.

255
G

integer

No

The green component.

255
X

number

Yes

The x-coordinate.

0.2
HasBox

boolean

No

Whether to draw a bounding box.

Y

number

Yes

The y-coordinate.

0.2
Texture

string

Yes

The watermark content.

文字水印
Layer

integer

No

The z-axis layer.

0
Font

integer

No

The font. Valid values:

  • 0: Alibaba PuHuiTi Regular

  • 1: Alibaba PuHuiTi Light

  • 2: Alibaba PuHuiTi Medium

  • 3: Alibaba PuHuiTi Bold

  • 4: Alibaba PuHuiTi Heavy

  • 5: Alimama Shuhei Ti

  • 6: DingTalk Jinbu Ti

  • 7: Alimama Dao Li Ti

  • 8: Alimama Dongfang Dakaishu

  • 9: Alimama Fangyuan Ti

0
BoxAlpha

number

No

The bounding box transparency.

0.6
ClockWidgets

array<object>

No

Global clock watermarks.

array<object>

No

BoxBorderw

integer

No

The border width of the bounding box.

5
BoxColor

object

No

The bounding box color.

R

integer

No

The red component.

255
B

integer

No

The blue component.

255
G

integer

No

The green component.

255
FontSize

integer

No

The clock font size.

30
Zone

integer

No

The time zone.

8
Alpha

number

No

The transparency level.

0.9
FontColor

object

No

The font color.

R

integer

No

The red component.

255
B

integer

No

The blue component.

255
G

integer

No

The green component.

255
X

number

Yes

The x-coordinate.

0.2
HasBox

boolean

No

Whether to draw a bounding box.

Y

number

Yes

The y-coordinate.

0.2
Layer

integer

No

The z-axis layer.

0
Font

integer

No

The font. Valid values:

  • 0: Alibaba PuHuiTi Regular

  • 1: Alibaba PuHuiTi Light

  • 2: Alibaba PuHuiTi Medium

  • 3: Alibaba PuHuiTi Bold

  • 4: Alibaba PuHuiTi Heavy

  • 5: Alimama Shuhei Ti

  • 6: DingTalk Jinbu Ti

  • 7: Alimama Dao Li Ti

  • 8: Alimama Dongfang Dakaishu

  • 9: Alimama Fangyuan Ti

0
BoxAlpha

number

No

The bounding box transparency.

0.6
RegionColor

object

No

The global pane background color.

R

integer

No

R.

255
G

integer

No

G.

255
B

integer

No

B

255
BgColor

object

No

The global background color.

R

integer

No

R.

255
G

integer

No

G.

255
B

integer

No

B

255
LayoutSpecifiedUsers

object

No

The list of specified users for layout generation. This includes blacklists and whitelists.

Whitelist: Subscribes to the video streams of specified users in the channel.

  • If a whitelist is set, panes are filled sequentially based on the list.

  • When switching between multiple template layouts, only users in the whitelist are considered.

Blacklist: Does not subscribe to the video streams of specified users in the channel.

  • When switching between multiple template layouts, only users not in the blacklist are considered.

Type

string

Yes

The type of user list. `black` for blacklist, `white` for whitelist.

white
Ids

array

Yes

A list of specified user IDs.

string

Yes

A specific user ID.

123
RecordMode

integer

No

0: Composite recording. Default value. 1: Individual recording. Individual recording does not support updates.

SingleStreamingRecord

object

No

Parameters for individual recording.

AvMerge

boolean

No

Merge audio files into the video file. Default value: false.

SpecifiedStreams

array<object>

Yes

The stream to record in single-stream recording mode.

object

No

StreamType

string

Yes

The stream type. Valid values:

  • mic: Audio stream.

Type

string

No

The type of blacklist or whitelist for individual stream recording.

  • white: Whitelist. Records this stream.

white
Ids

array

Yes

A list of user IDs.

string

Yes

A user ID.

TranscodingParameters

object

No

By default, individual recordings are saved in MP3 format. Specify this parameter if transcoding is needed.

Audio

object

No

Audio encoding.

Bitrate

integer

No

The bitrate in kbps.

Codec

string

No

The audio codec format. Optional:

  • mp3

  • aac

SampleRate

integer

No

The sample rate. Optional:

  • 8000

  • 16000

  • 32000

  • 44100

  • 48000

Container

string

No

The recording file container.

  • mp3

  • aac

  • mp4

  • ts

aac
Important Related Notes

The total number of local image watermarks, local background image watermarks, global image watermarks, or global background images must not exceed 16.

Advanced Watermark Layering

The RTC media server generates frames in the following steps:

Draw video -> Draw images -> Draw text

Video, images, and text are distinct elements. The overall priority order is text, then images, then video.

  1. Layout video frames according to the customer-defined layout.

    a. Images in the grid and global images are arranged in a unified layer.

    b. Layer 0 is at the bottom. A larger layer value places the element higher. The layer value ranges from 0 to 100.

  2. Images include user-defined PNG or JPG images.

    a. Draw images based on user configurations, such as width, height, position, and transparency.

    b. Layer 0 is at the bottom. A larger layer value places the element higher. The layer value ranges from 0 to 100.

  3. Text is divided into three types: regional text, global text, and timestamp text.

    a. Draw text of the same type according to layer order. Layer 0 is at the bottom. A larger layer value places the element higher. The layer value ranges from 0 to 100.

    b. For different text types, the priority order is timestamp text, then global text, then regional text. When elements overlap, lower-priority elements are overwritten.

Overlapping Display:

  1. For overlapping parts, if no specific configuration is set, higher-priority elements overwrite lower-priority elements.

  2. To prevent lower-priority content from being overwritten by higher-priority content, set the transparency property of the higher-priority content to 0.

Single-Stream Recording Container and Audio Encoding Format Validation Rules

Single-stream recording allows users to specify the encoding format and container format for recording files. Different container formats support different stream types and encoding formats. The single-stream recording API validates relevant parameters. Unsupported combinations are rejected.

Rule 1: Stream Types and Supported Container Formats

Stream TypeContainer Format
Pure audio stream (stream type is mic only)aac, mp3, mp4, ts
Pure video stream or audio/video stream (stream type includes camera or screen-cast)mp4, ts

Rule 2: Container Formats and Supported Audio Encoding Formats

Container FormatAudio Encoding Format
mp3mp3
aacaac
tsmp3, aac
mp4aac

Response elements

Element

Type

Description

Example

object

result

TaskId

string

The task ID for this cloud recording.

123
RequestId

string

The request ID.

16A96B9A-F203-4EC5-8E43-CB92E68F4CF8

Examples

Success response

JSON format

{
  "TaskId": "123",
  "RequestId": "16A96B9A-F203-4EC5-8E43-CB92E68F4CF8"
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.