StartRtcCloudRecording - 启动Rtc云端录制任务_视频直播(LIVE)-阿里云帮助中心

启动rtc云端录制任务。

接口说明

重要云端录制属于收费功能，当前为公测阶段，您可以免费使用，公测结束后将正常收费，具体时间另行通知。

## 服务接入点本接口可用的服务接入点包括：

cn-shanghai：上海
ap-southeast-1: 新加坡

QPS 限制

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

调试

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

调试

授权信息

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

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

操作

访问级别

资源类型

条件关键字

关联操作

live:StartRtcCloudRecording

create

*全部资源

*

无

请求参数

名称	类型	必填	描述	示例值
AppId	string	是	待录制的频道所属 app 的 id。该 app 需要归属于当前调用接口账号所属的主账号。	******-7074--9ef5-85c19a4***
ChannelId	string	是	待录制的频道对应的 id。需要确保调用本接口时，该频道内有用户，否则会创建录制任务失败。	room1024
SubscribeParams	object	是	订阅相关参数。
SubscribeUserIdList	array	是	订阅的 UserId 信息列表，单流录制模式下，会对其中每个 UserId 分别进行录制；混流录制模式下，会将所有 UserId 的音视频混合到一组音视频中。说明数组不能为空，并且最多支持 17 个元素。
	object	否	订阅的 UserId 的信息。
UserId	string	是	订阅的 UserId。	userA
StreamType	integer	否	订阅的 UserId 的媒体类型。取值： 0：原始流，即包括音频和视频。（默认值） 1：仅音频流。 2：仅视频流（混流录制模式下有效）。	0
SourceType	integer	否	该 UserId 的视频输入流类型，仅订阅非纯音频流时（StreamType!=1）有效。取值： 0：摄像头。（默认值） 1：屏幕共享。	0
RecordParams	object	是	录制相关参数。
RecordMode	integer	是	录制模式。取值： 0：单流录制模式，对于订阅的每个 UserId，各自生成录制文件。 1：混流录制模式，对于订阅的 UserId，将这些用户的流进行混合转码后，仅生成一组录制文件。	0
StreamType	integer	否	录制的输出流的媒体类型。取值： 0：原始流，即包括音频和视频。（默认值） 1：仅音频流。 2：仅视频流。	0
MaxFileDuration	integer	否	录制文件最大时长（秒）。超过该时长的录制文件会被分割。取值范围须在[180,7200]内，即最大 2 小时。不指定时，则默认 2 小时。	7200
StorageParams	object	是	存储相关参数。
StorageType	integer	是	存储方式。取值： 0：VOD 1：OSS	1
FileInfo	array	否	文件存储信息，用于指定录制文件的格式、存储位置和命名，仅在 StorageType 为 OSS 时有效。说明对于数组中每个元素，会分别生成对应配置的录制文件。不设置时，默认包含 HLS 格式的配置；设置时，如果未包含 HLS 格式的配置，会自动生成 HLS 格式的默认配置。
	object	否	不同文件格式的存储配置。
Format	string	是	文件存储格式。取值： HLS MP4 MP3	HLS
FileNamePattern	string	否	文件命名格式。可以由以下变量按任意顺序选择并组合： AppId ChannelId UserId（单流模式下必选；混流模式下无效，选择的话会保留为{UserId}字符串） RecordMode 值为 0 时对应 Single 值为 1 时对应 Mix SourceType 单流模式下，当流类型为纯视频流时，配置生效，SourceType 可配置为：当值为 0 时，对应 C（Camera）摄像头视频流。当值为 1 时，对应 S（Screen）屏幕共享视频流。单流模式下，当流类型为纯音频流时，SourceType 自动配置为 A（Audio），用于标识该录制内容为纯音频流。单流模式下，当流类型为原始流时，配置生效，SourceType 可配置为：当值为 0 时，对应 OC（Original Camera）摄像头原始流。当值为 1 时，对应 OS（Original Screen）屏幕共享原始流。其他场景下，SourceType 配置无效，若用户手动配置了 SourceType，系统将会保留{SourceType}占位符字符串。 StreamType（使用 RecordParams 参数下的 StreamType 参数）当值为 0 时对应 AV（Audio Video）音频流与视频流。当值为 1 时对应 A（Audio）音频流。当值为 2 时对应 V（Video）视频流。 StartTime：开始录制的 UTC 时间，格式类似 2025-03-25-11:27:28。（不使用默认值时必选）默认值如下：单流录制模式 {AppId}_{ChannelId}_{UserId}_{StartTime} 如果同时订阅了同一个 UserId 的不同 StreamType 或不同 SourceType，则默认值为{AppId}_{ChannelId}_{UserId}_{SourceType}_{StartTime} 混流录制模式 {AppId}_{ChannelId}_{StartTime} 说明字符串只能由以上变量组成，变量名需要用{}包裹，变量名之间用一个下划线（_）分隔，每个变量至多在字符串内出现一次。当命名为 xxx 后，文件最终会保存为类似 TaskId/xxx.m3u8 的形式，其中 TaskId 是在启动云端录制任务时生成的任务 id，会自动添加到存储路径中。	{AppId}_{ChannelId}_{StartTime}_{UserId}
SliceNamePattern	string	否	切片命名格式，仅在 HLS 格式下有效。与 FileNamePattern 类似，只是可选变量多出了 Sequence： AppId ChannelId UserId（单流模式下必选；混流模式下无效，选择的话会保留为{UserId}字符串） RecordMode 值为 0 时对应 Single 值为 1 时对应 Mix SourceType 单流模式下，当流类型为纯视频流时此参数生效，SourceType 可配置为：取值为 0，对应 C（Camera）摄像头视频流。取值为 1，对应 S（Screen）屏幕共享流。单流模式下，当流类型为纯音频流时，SourceType 自动配置为 A（Audio），用于标识该录制内容为纯音频流。单流模式下，当流类型为原始流时，配置生效，SourceType 可配置为：当值为 0 时，对应 OC（Original Camera）摄像头原始流。当值为 1 时，对应 OS（Original Screen）屏幕共享原始流。其他场景下，SourceType 配置无效，若用户手动配置该参数，系统将保留`{SourceType}`占位符字符串。 StreamType（使用 RecordParams 参数下的 StreamType 参数）当值为 0 时对应 AV（Audio Video）包含音频流与视频流。当值为 1 时对应 A（Audio ）音频流。当值为 2 时对应 V（Video）视频流。 StartTime：开始录制的 UTC 时间，格式类似 2025-03-25-11:27:28。（不使用默认值时必选）。 Sequence：HLS 格式下，ts 文件名中包含 Sequence，其他格式下无效。（不使用默认值时必选）。默认值如下：单流录制模式 {AppId}_{ChannelId}_{UserId}_{StartTime}_{Sequence} 如果同时订阅了同一个 UserId 的不同 StreamType 或不同 SourceType，则默认值为{AppId}_{ChannelId}_{UserId}_{SourceType}_{StartTime}_{Sequence} 混流录制模式 {AppId}_{ChannelId}_{StartTime}_{Sequence} 说明字符串只能由以上变量组成，变量名需要用{}包裹，变量名之间用一个下划线（_）分隔，每个变量至多在字符串内出现一次。当命名为 xxx 后，切片文件最终会保存为类似 TaskId/xxx.ts 的形式，其中 TaskId 是在启动云端录制任务时生成的任务 id，会自动添加到存储路径中。	{AppId}_{ChannelId}_{StartTime}_{Sequence}
FilePathPrefix	array	否	文件存储路径。数组中的元素对应每一级目录，例如参数值为["dir1","dir2"]时，xxx.m3u8 文件将被保存为 dir1/dir2/TaskId/xxx.m3u8。该参数为空时，上述例子将直接保存为 TaskId/xxx.m3u8。路径结尾会自动补充任务的 TaskId，以避免不同任务的录制文件混在一起。如果设置了 FilePathPrefix，那么数组中每个元素，只能由英文字母（a-zA-Z）、数字（0-9）、短横线（-）、下划线（_）组成，并且不能为空字符串。数组中各层路径拼接好后，总长度不能超过 128 个字符（包括连接的'/'，不包括自动填入的 TaskId）。例如参数值为["dir1","dir2"]，那么拼接好的路径就是"dir1/dir2/"，也即数组中所有元素的总字符数与数组长度之和（对应每层路径后的"/"），不得超过 128。数组中元素个数不得超过 5，即最多自定义 5 层路径。
	string	否	每一级目录名。	dir1
OSSParams	object	否	OSS 存储配置。当存储方式为 OSS 时必须配置，当存储方式为 VOD 时无效。
OSSEndpoint	string	是	OSS 存储的 Endpoint 名称。所对应的 regionId 需要与选择的服务接入点一致。	oss-cn-shanghai.aliyuncs.com
OSSBucket	string	是	OSS 存储的 Bucket 名称。该 Bucket 需要归属于当前调用接口账号所属的主账号。	mytest-bucket
VodParams	object	否	VOD 存储配置。当存储方式为 VOD 时必须配置，当存储方式为 OSS 时无效。
StorageLocation	string	否	点播控制台->媒资管理配置->存储管理中包含的存储地址，录制文件会先保存到这里，再上传到 Vod。	mytest.oss-cn-shenzhen.aliyuncs.com
VodTranscodeGroupId	string	否	点播转码模板组 ID。	**8a914d3989e9825eb90530b2**
AutoCompose	integer	否	自动合并。取值： 0：关闭自动合并。（默认值） 1：开启自动合并。开启时必须设置参数 ComposeVodTranscodeGroupId。	ON
ComposeVodTranscodeGroupId	string	否	对自动合成出来的新视频在点播服务中进行一次转码，所使用的点播转码模板组 ID。说明当 AutoCompose（是否开启自动合并）设为 1 时，本参数才必填。自动合成和转码常见问题，请参见直播转点播常见问题 FAQ。点播转码计费详情，请参见媒资转码计费。	**4c34112cfe68248f2f77759c**
MixTranscodeParams	object	否	转码相关参数，单流录制模式下不填，混流录制模式下必填。
FrameFillType	integer	否	断流补帧类型。取值： 0：补最后一帧。（默认值）	0
AudioBitrate	integer	是	音频码率（kbps），取值范围须在[8, 500]内。混流模式下必填。	300
AudioChannels	integer	是	音频声道数。取值： 1：单通道。 2：双通道。混流模式下必填。	2
AudioSampleRate	integer	是	音频采样率（Hz）。取值： 8000 16000 32000 44100 48000 混流模式下必填。	32000
VideoCodec	string	否	视频编码格式。取值： H.264（默认值） H.265	H.264
VideoBitrate	integer	否	视频码率（kbps），取值范围须在[1,10000]内。混流模式下，期望录制输出包含画面时必填，其他情况下无效。	5000
VideoFramerate	integer	否	视频帧率（fps），取值范围须在[1,60]内。混流模式下，期望录制输出包含画面时必填，其他情况下无效。	30
VideoGop	integer	否	视频 GOP，每 VideoGop 帧存在一个 I 帧，取值范围须在[1,60]内。混流模式下，期望录制输出包含画面时必填，其他情况下无效。	30
VideoHeight	integer	否	视频高度（px），取值范围须在[0,1920]内。（默认值为 0）	480
VideoWidth	integer	否	视频宽度（px），取值范围须在[0,1920]内。（默认值为 0）	640
MixLayoutParams	object	否	布局相关参数，单流录制模式下不填，混流录制模式下期望录制出非纯音频文件时必填。
MixBackground	object	否	混流全局背景图。
RenderMode	integer	否	画面输出时的显示模式。取值： 0：裁剪。（默认值） 1：缩放并显示黑底。	0
Url	string	否	背景图 URL，最大长度不超过 2048 个字符。	https://xxxx.com/photos/my-test-picture.png
UserPanes	array	否	用于指定订阅的用户的窗口布局信息，只有设置了布局信息的 UserId，才会被放到画面中。混流模式且录制非纯音频文件时必填。
	array<object>	否	画面中窗口配置。
UserId	string	否	该窗口对应的 UserId。不设置 UserId 时，会按照订阅的用户进入频道的顺序依次填入窗口。这里设置的 UserId 与 SourceType 的组合必须包含在 SubscribeUserIdList 中。订阅纯音频流是不能加入到布局中的	userA
SourceType	integer	否	该 UserId 的视频输入流类型。不填写 UserId 时，此处设置 SourceType 无效。取值： 0：摄像头。（默认值） 1：屏幕共享。这里设置的 UserId 与 SourceType 的组合必须包含在 SubscribeUserIdList 中。	0
Height	string	否	窗格高度，归一化百分比。取值范围须在[0,1]内。(默认为 0)	0.5
Width	string	否	窗格宽度，归一化百分比。取值范围须在[0,1]内。(默认为 0)	0.5
X	string	否	坐标 X，归一化百分比。取值范围须在[0,1]内。(默认为 0)	0
Y	string	否	坐标 Y，归一化百分比。取值范围须在[0,1]内。(默认为 0)	0
ZOrder	integer	否	叠放顺序，0 为最底层，1 层在 0 层之上，以此类推。(默认为 0)	0
SubBackground	object	否	子画面背景图，当用户关闭摄像头、或入会后未推流、或入会后中途离会时，会在布局位置填充为对应的图片。
RenderMode	integer	否	子画面输出时的显示模式。取值： 0：裁剪。（默认值） 1：缩放并显示黑底。	0
Url	string	否	背景图 URL，最大长度不超过 2048 个字符。	https://xxxx.com/photos/my-test-pane-picture.png
NotifyUrl	string	否	接受回调消息地址。任务状态消息会通过 POST 方式，以 Json 格式推送到该地址。	http://xxxx/test/mycallback
NotifyAuthKey	string	否	回调消息鉴权 key，默认不填，即不做鉴权。如果填写，长度需要在[16,64]个字符内，且只由大小写英文字母和数字组成。当 NotifyUrl 未填写时，NotifyAuthKey 也无效。当设置有效的 NotifyAuthKey 时，会在回调消息内携带鉴权内容。	mytestkey
MaxIdleTime	integer	否	空闲超时时间，当任务处于空闲状态的时长超过 MaxIdleTime 时，自动停止任务。单位为秒，范围须在[10,14400]内，即最大 4 小时。（默认为 300 秒）对于混流录制模式，当所有订阅的用户流都停止推流时算作空闲对于单流录制模式，订阅的流之间彼此独立，任意一路流停止推流都算作空闲，达到 MaxIdleTime 后会停止该路流的录制，当所有订阅流都空闲超时后，会停止整个云端录制任务。	600

对于单流录制模式：
- 支持同时订阅同一个 UserId 的摄像头和屏幕共享，但 FileNamePattern 和 SliceNamePattern 参数中必须包含 SourceType 变量（避免出现录制文件互相覆盖的情况）。
- 目前不支持只订阅某个 UserId 的纯视频流。即在单流模式下，UserInfo.StreamType 的值不能设置为 2。
在单流录制模式下：
- 如果 RecordParams.StreamType 是纯音频流（取值为 1），那么 SubscribeParams 中不能存在订阅纯视频的情况（即 SubscribeParams 取值为 2）。
- 如果 RecordParams.StreamType 是纯视频流（值为 2），那么 SubscribeParams 中不能存在订阅纯音频的情况（即 SubscribeParams 取值为 1）。
在混流录制模式下：
- 如果 RecordParams.StreamType 是纯音频流（值为 1），那么 SubscribeParams 中不能所有 UserId 都只订阅纯视频（即所有 SubscribeParams 取值为 2）。
- 如果 RecordParams.StreamType 是纯视频流（值为 2），那么 SubscribeParams 中不能所有 UserId 都只订阅纯音频（即所有 SubscribeParams 取值为 1）。
录制过程中，如果中途 channel 关闭，需要在空闲时长内重新入会推流，否则任务将自动停止。

返回参数

名称	类型	描述	示例值
	object	返回内容。
RequestId	string	请求 id。	****58-5876--83CA-B56278****
TaskId	string	任务 id。	****73-8501--8ac1-72295a****

示例

正常返回示例

JSON格式

{
  "RequestId": "******58-5876-****-83CA-B56278******",
  "TaskId": "******73-8501-****-8ac1-72295a******"
}

错误码

HTTP status code	错误码	错误信息	描述
400	InvalidParameter.NotifyUrl	%s, please check the notifyUrl.	参数NotifyUrl格式无效，请检查。
400	InvalidParameter.StorageParams.FileInfo	%s, please check the fileInfo of storageParams.	参数FileInfo存在无效字段，请检查。
400	InvalidParameter.StorageParams.OSSParams	%s, please check the ossParams of storageParams.	参数OSSParams存在无效字段，请检查。
400	NotFound.OSSBucket	%s, please check the ossBucket of storageParams.	参数OSSBucket不存在。
400	InvalidParameter.SubscribeParams.SubscribeUserIdList	%s, please check the subscribeUserIdList of subscribeParams.	参数SubscribeUserIdList无效，请检查。
400	InvalidParameter.MixLayoutParams.UserPanes	%s, please check the userPanes of mixLayoutParams.	参数UserPanes存在无效字段，请检查。
400	InvalidParameter.MixTranscodeParams	%s, please check the transcodeParams.	参数MixTranscodeParams存在无效字段，请检查。
400	MissingParameter	%s.	参数缺失
403	InvalidParameter.UserId	%s, please check the UserId.	UserId无效，请检查。
404	InvalidParameter.ChannelId	%s, please check the channelId.
404	InvalidParameter.AppId	%s, please check the appId.	参数AppId无效，请检查。
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.

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

变更历史

更多信息，参考变更详情。