调用StartCloudRecord接口开始云端录制任务-音视频通信-阿里云

本接口用于开始云端录制任务。

接口说明

使用说明

本接口用于开始在线频道的云端录制任务。

QPS 限制

本接口的单用户 QPS 限制为 10 次/秒。超过限制，API 调用会被限流，这可能会影响您的业务，请合理调用。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作	访问级别	资源类型	条件关键字	关联操作
rtc:StartCloudRecord	create	App `acs:rtc::{#accountId}:app/{#AppId}`	无	无

请求参数

名称

类型

必填

描述

示例值

AppId

string

是

应用 ID，通过控制台创建和查询，仅支持传单个 ID。

eo85****

ChannelId

string

是

已存在的频道 ID，仅支持传单个 ID。

testid

TemplateId

string

是

模版 ID。

567

TaskId

string

否

本次云端录制的任务 ID，仅支持传单个 ID。由大小写字母、数字、下划线、短划线（-）组成，最大 55 字节。

123

CropMode

integer

否

裁剪方式。取值：

1：保持比例裁剪。
2：保持比例留边（默认值）。
3：拉伸铺满。

ReservePaneForNoCameraUser

boolean

否

未推摄像头流用户窗格占位。默认为 true，表示用户未推摄像头流时保留一个窗格。为 false 时，表示用户未推摄像头流时不保留窗格。

ShowDefaultBackgroundOnMute

boolean

否

mute 时是否显示窗格默认底图。

true: 显示（默认值）
false: 不显示（设置的局部窗格底图依然显示）

SubHighResolutionStream

boolean

否

订阅高分辨率流。

false：根据窗格面积订阅不同分辨率的流。（默认值）
true：默认用客户端推的最高分辨率的流进行填充。

StartWithoutChannel

boolean

否

是否允许频道不存在时开启任务。

true: 是
false: 否（默认值）

StartWithoutChannelWaitTime

integer

否

当 StartWithoutChannel 参数为 true 的时候，设置该值才有意义，表示房间未开启时，任务等待时长，单位为秒，区间限制为[30,120]。

Annotation

string

否

标注开关。

disable

StorageConfig

object

是

存储配置

Vendor

integer

是

存储平台。取值：

vendor	对象存储产品	备注
1	AliYun OSS	阿里云
2	AliYun 专有云 OSS	阿里云专有云

Region

integer

是

存储地域。

Region	AliYun OSS
0	CN_Hangzhou
1	CN_Shanghai
2	CN_Qingdao
3	CN_Beijing
4	CN_Zhangjiakou
5	CN_Huhehaote
6	CN_Shenzhen
7	CN_Hongkong
8	US_West_1
9	US_East_1
10	AP_Southeast_1
11	AP_Southeast_2 （已下线，请勿使用）
12	AP_Southeast_3
13	AP_Southeast_5
14	AP_Northeast_1
15	AP_South_1 （已下线，请勿使用）
16	EU_Central_1
17	EU_West_1
18	EU_East_1(ME_East_1)
19	AP_Southeast_6
20	CN_Heyuan
21	CN_Guangzhou
22	CN_Chengdu
23	CN_Nanjing
24	CN_Fuzhou
25	CN_Wulanchabu
26	CN_Northeast_2
27	CN_Southeast_7
28	CN_Wuhan_LR
100	oss-cn-hzjbp
101	oss-cn-shanghai-finance-1
102	oss-cn-shenzhen-finance-1
103	oss-cn-beijing-finance-1
104	oss-cn-hzfinance
105	oss-cn-shanghai-finance-1-pub
106	oss-cn-szfinance
107	oss-cn-beijing-finance-1-pub

Region	AliYun 专有云 OSS
0	default

Bucket

string

是

存储桶名称

test-bucket-for-recording

AccessKey

string

是

accessKey。该密钥对应的子账号，请添加对应云厂商对象存储产品写权限，否则会导致结果文件写入失败。

LTAX***

SecretKey

string

是

secretKey

APb6qWYEzKtYxE***

Endpoint

string

否

专有云时，私网连接地址。

https://aliyuns.dalian.oss.com

Panes

array<object>

否

单元格设置。

eo85****

object

否

VideoOrder

string

否

SourceType 为 video 时，填充顺序。

screenFirst，屏幕共享优先（默认值）
cameraFirst，摄像头优先

cameraFirst

SourceType

string

否

单元格媒体类型。取值：

video：用户摄像头或者屏幕共享流（默认值）。
camera：摄像头流。
screen：共享屏幕流。
whiteboard：白板。

video

Images

array<object>

否

窗格局部图片水印。

object

否

PaneImageCropMode

integer

否

裁剪方式。取值：

1：保持比例裁剪。
2：保持比例留边。
3：拉伸铺满。

Alpha

double

否

透明度。

0.9

double

是

横坐标。

0.2

double

是

纵坐标。

0.2

Height

double

是

高。

0.2

Width

double

是

宽。

0.2

Layer

integer

否

z 轴层级。

Url

string

是

对应的图片内容在推流期间不支持更新

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

Display

string

否

水印显示时机。

streamOnly：当前用户有视频流时显示（默认值）。
backup：当前用户无视频流时显示。
always：总是显示。

backup

Texts

array<object>

否

窗格局部文字水印。

object

否

BoxBorderw

integer

否

矩形框线宽。

FontColor

object

否

字体颜色。

integer

否

R。

255

integer

否

B。

255

integer

否

G。

255

Texture

string

是

水印内容。

文字水印

Layer

integer

否

z 轴层级。

Font

integer

否

字体。

0：阿里巴巴普惠体 Regular
1：阿里巴巴普惠体 Light
2：阿里巴巴普惠体 Medium
3：阿里巴巴普惠体 Bold
4：阿里巴巴普惠体 Heavy
5：阿里妈妈数黑体
6：钉钉进步体
7：阿里妈妈刀隶体
8：阿里妈妈东方大楷
9：阿里妈妈方圆体

BoxColor

object

否

矩形框颜色。

integer

否

R。

255

integer

否

B。

255

integer

否

G。

255

FontSize

integer

否

字体大小。

Alpha

double

否

水印透明度。

0.9

double

是

横坐标。

0.2

HasBox

boolean

否

是否需要矩形框。

double

是

纵坐标。

0.2

BoxAlpha

double

否

矩形框透明度。

0.6

Display

string

否

水印显示时机。

streamOnly：当前用户有视频流时显示（默认值）。
backup：当前用户无视频流时显示。
always：总是显示。

backup

PaneCropMode

integer

否

裁剪方式。取值：

1：保持比例裁剪。
2：保持比例留边。
3：拉伸铺满。

PaneId

integer

是

布局 ID，从 0 开始。

Source

string

否

单元格媒体源。可指定 userId，如需指定特定用户类型。可使用通配符配置，支持以下类型。

$ActiveSpeaker：当前频道发言人
$ScreenShare：屏幕共享用户，当频道中有多个屏幕共享时，将按照先后顺序依次填充

Backgrounds

array<object>

否

背景图片。

object

否

Alpha

double

否

透明度。

0.9

double

是

横坐标。

0.2

double

是

纵坐标。

0.2

PaneBackgroundCropMode

integer

否

裁剪方式。取值：

1：保持比例裁剪。
2：保持比例留边。
3：拉伸铺满。

Height

double

是

高。

0.2

Width

double

是

宽。

0.3

Layer

integer

否

z 轴层级。

Url

string

是

图片地址。

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

Display

string

否

显示时机。

streamOnly：当前用户有视频流时显示（默认值）。
backup：当前用户无视频流时显示。
always：总是显示。

backup

Whiteboard

object

否

白板配置。

WhiteboardId

string

否

白板 ID，默认为 default。

default

ReservePaneForOfflineUser

boolean

否

未入会用户窗格占位。

默认为 true，表示宫格指定的具体用户或通配符用户离线时，窗格强制占位。为 false 时，表示宫格指定的具体用户或通配符用户离线时，将按自动填充顺序显示视频流。

Images

array<object>

否

全局图片水印。

disable

object

否

Alpha

double

否

透明度。

0.9

double

是

横坐标。

0.2

double

是

纵坐标。

0.3

Height

double

是

高。

0.2

ImageCropMode

integer

否

裁剪方式。取值：

1：保持比例裁剪。
2：保持比例留边。
3：拉伸铺满。

Width

double

是

宽。

0.2

Layer

integer

否

z 轴层级。

Url

string

是

图片地址。对应的图片内容在推流期间不支持更新。

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

Backgrounds

array<object>

否

背景图片。

object

否

BackgroundCropMode

integer

否

裁剪方式。取值：

1：保持比例裁剪。
2：保持比例留边。
3：拉伸铺满。

Alpha

double

否

透明度。

0.9

double

是

横坐标。

0.2

double

是

纵坐标。

0.2

Height

double

是

高。

0.2

Width

double

是

宽。

0.2

Layer

integer

否

z 轴层级。

Url

string

是

图片地址。

https://aliyun.com/123.jpg

Texts

array<object>

否

全局文字水印。

object

否

BoxBorderw

integer

否

矩形框线宽。

BoxColor

object

否

矩形框颜色。

integer

否

R。

255

integer

否

B。

255

integer

否

G。

255

FontSize

integer

否

字体大小。

Alpha

double

否

水印透明度。

0.1

FontColor

object

否

字体颜色。

integer

否

R。

255

integer

否

B。

255

integer

否

G。

255

double

是

横坐标。

0.2

HasBox

boolean

否

是否需要矩形框。

double

是

纵坐标。

0.2

Texture

string

是

水印内容。

文字水印

Layer

integer

否

z 轴层级。

Font

integer

否

字体。

0：阿里巴巴普惠体 Regular
1：阿里巴巴普惠体 Light
2：阿里巴巴普惠体 Medium
3：阿里巴巴普惠体 Bold
4：阿里巴巴普惠体 Heavy
5：阿里妈妈数黑体
6：钉钉进步体
7：阿里妈妈刀隶体
8：阿里妈妈东方大楷
9：阿里妈妈方圆体

BoxAlpha

double

否

矩形框透明度。

0.6

ClockWidgets

array<object>

否

全局时钟水印。

object

否

BoxBorderw

integer

否

矩形框线宽。

BoxColor

object

否

矩形框颜色。

integer

否

R。

255

integer

否

B。

255

integer

否

G。

255

FontSize

integer

否

时钟字体大小。

Zone

integer

否

时区。

Alpha

double

否

透明度。

0.9

FontColor

object

否

字体颜色。

integer

否

R。

255

integer

否

B。

255

integer

否

G。

255

double

是

横坐标。

0.2

HasBox

boolean

否

是否需要矩形框。

double

是

纵坐标。

0.2

Layer

integer

否

z 轴层级。

Font

integer

否

字体。

0：阿里巴巴普惠体 Regular
1：阿里巴巴普惠体 Light
2：阿里巴巴普惠体 Medium
3：阿里巴巴普惠体 Bold
4：阿里巴巴普惠体 Heavy
5：阿里妈妈数黑体
6：钉钉进步体
7：阿里妈妈刀隶体
8：阿里妈妈东方大楷
9：阿里妈妈方圆体

BoxAlpha

double

否

矩形框透明度。

0.6

RegionColor

object

否

全局框格底色

integer

否

R。

255

integer

否

G。

255

integer

否

B。

255

BgColor

object

否

全局背景色

integer

否

R。

255

integer

否

G。

255

integer

否

B。

255

LayoutSpecifiedUsers

object

否

布局生成用户指定列表，包括黑/白名单两种。

白名单，指定订阅房间里哪些用户视频流。

设置后自动填充根据该列表进行顺序填充
模版多布局切换时只计算白名单中的人

黑名单，指定不订阅房间里哪些用户视频流。

模版多布局切换时只计算非黑名单中的人

Type

string

是

用户名单类型，黑名单：black，白名单：white。

white

Ids

array

是

指定用户 ID 列表。

string

是

具体用户 ID。

123

RecordMode

integer

否

0: 合流录制（默认值） 1: 单流录制（单流录制不支持更新）

SingleStreamingRecord

object

否

单流录制参数。

AvMerge

boolean

否

音频文件是否合并到视频文件，默认 false。

SpecifiedStreams

array<object>

是

单流录制指定的流。

object

否

StreamType

string

是

流类型，取值：

mic: 音频流

Type

string

否

单流录制流黑白名单类型

white: 白名单，表示录制该流

white

Ids

array

是

用户 ID 列表。

string

是

用户 ID。

TranscodingParameters

object

否

单流录制默认写入为 mp3 格式，如需转码需指定该参数。

Audio

object

否

音频编码。

Bitrate

integer

否

码率，单位 kbps。

Codec

string

否

音频编解码格式，可选:

SampleRate

integer

否

采样率，可选：

8000
16000
32000
44100
48000

Container

string

否

录制文件容器。

aac

注意相关补充

局部图片水印数量、局部背景图片水印、全局图片水印数量和全局背景图数量的总和不能超过 16。

高级水印层次说明

RTC 媒体服务器生成的画面会分成以下几个步骤：

绘制视频 -> 绘制图片 -> 绘制文字

视频、图片、文字是完全分开的，从整个画面来看文字优先级 > 图片 > 视频

绘制视频：根据客户定义的布局对视频画面进行布局

a. 宫格中的图片和全局图片的 layer 统一排列。

b. layer 0 位于最底层，layer 越大越位于上方，layer 的取值范围为[0,100] 。
绘制图片图片包括用户自定义的 png/jpg 图片。

a. 根据用户配置宽高、位置、透明度等信息进行绘制。

b. layer 0 位于最底层，layer 越大越位于上方，layer 的取值范围为[0,100] 。
绘制文字文字分为 3 个类型：区域文字全局文字和时间戳文字。

a. 同一类型文字根据 layer 顺序绘制，layer 0 位于最底层，layer 越大越位于上方，layer 的取值范围为[0,100] 。

b. 不同类型文字优先级为：时间戳文字 > 全局文字 > 区域文字。处于重叠位置时，优先级较低的将被覆盖。

重叠部分的显示：

重叠部分，如果没有特别配置，高优先级将覆盖低优先级。
低优先级内容如果不想被高优先级内容覆盖，可以设置高优先级内容的透明度属性为 0。

单流录制容器及音频编码格式校验规则

单流录制允许用户指定录制文件的编码格式及容器格式，不同容器格式支持的流类型、编码格式并不一致。单流录制接口会校验相关参数，不支持的组合会被拒绝。

规则一：流类型及支持的容器格式

流类型	容器格式
纯音频流（流类型只有 mic）	aac、mp3、mp4、ts
纯视频流 or 音视频流（流类型出现 camera 或 screen-cast）	mp4、ts

规则二：容器格式及支持的音频编码格式

容器格式	音频编码格式
mp3	mp3
aac	aac
ts	mp3、aac
mp4	aac

返回参数

名称	类型	描述	示例值
	object	result
TaskId	string	本次云端录制的任务 ID。	123
RequestId	string	请求 ID。	16A96B9A-F203-4EC5-8E43-CB92E68F4CF8

示例

正常返回示例

JSON格式

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

错误码

访问错误中心查看更多错误码。

变更历史

变更时间	变更内容概要	操作
2025-10-17	API 内部配置变更，不影响调用	查看变更详情
2025-04-15	OpenAPI 入参发生变更	查看变更详情
2025-02-21	OpenAPI 入参发生变更	查看变更详情
2025-02-12	API 内部配置变更，不影响调用	查看变更详情
2024-12-16	OpenAPI 入参发生变更	查看变更详情
2024-11-06	OpenAPI 入参发生变更	查看变更详情
2024-03-07	API 内部配置变更，不影响调用	查看变更详情