本文档 API 接口为最新版本接口,后续相关功能的新增都会在此更新,推荐使用最新版本接口。旧版接口文档请参考历史版本。
注意
在开始录制前,你必须已经在控制台上开启录制功能,参看在控制台开启/关闭云端录制功能。
在实时音视频通话场景中,你可以通过调用此接口实现云端录制功能,支持单流或合流录制模式。
你可以根据需求配置指定任务 ID、选择录制模式、自定义音视频流目标列表、设置编码参数、安排视频布局以及指定存储配置等,以满足多样化的录制需求。调用后,接口返回任务启动状态,确保录制流程顺利进行。
如果录制任务状态发生变化,你在控制台上设置的回调地址会收到每个状态变化的回调。
录制分为单流录制和合流录制:
你需要在接口调用中配置存储空间,选择将录制结果存储在存储平台中。目前支持的存储平台包括:火山引擎视频点播 VOD、火山引擎对象存储 TOS、Amazon S3、阿里云对象存储 OSS、华为云 OBS、腾讯云 COS 和七牛云 Kodo。
录制文件生成后,不推荐调用 GetRecordTask
接口获取录制生成的文件,强烈建议接入录制结束回调事件。
请求频率:QPS 不得超过 60。
如果你需要获取云端录制状态回调,请开通消息通知服务。
下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。
参数 | 类型 | 是否必选 | 示例值 | 描述 |
---|---|---|---|---|
Action | String | 是 | StartRecord | 接口名称。当前 API 的名称为 StartRecord 。 |
Version | String | 是 | 2023-11-01 | 接口版本。当前 API 的版本为 2023-11-01 。 |
参数 | 类型 | 是否必选 | 示例值 | 描述 |
---|---|---|---|---|
AppId | String | 是 | 661e****543cf | 你的音视频应用的唯一标志,参看获取 AppId。 |
BusinessId | String | 否 | B****23 | 业务标识 |
RoomId | String | 是 | Room1 | 房间的 ID,是房间的唯一标志 |
TaskId | String | 是 | Task1 | 云端录制任务 ID。你必须对每个云端录制任务设定 TaskId,且在后续进行任务更新和结束时也须使用该 TaskId。
关于 TaskId 及以上 Id 字段的命名规则符合正则表达式: TaskId 重复调用开始接口不会导致请求失败,BaseResponse.Result 会提示 The task has been started. Please do not call the startup task interface repeatedly 。 |
RecordMode | Integer | 否 | 0 | 录制模式。支持取值及含义如下:
0 。 |
TargetStreams | Object | 否 | - | 需要录制的音视频流。如果参数为空,默认录制房间内所有发布的音视频流,最多 17 路流。 此参数中的 stream 不得和 ExcludeStreams 中重复,若重复会报错InvalidParameter 。 |
StreamList | Object[] | 否 | - | 音视频流列表,由 Stream 组成,可以为空。为空时,表示订阅房间内所有流。在一个 StreamList 中,Stream.Index 不能重复。 |
Index | Integer | 否 | 0 | 在自定义布局中,使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中,你需要使用 Index 指定对应流的布局设置。 |
UserId | String | 是 | user1 | 用户 ID,表示这个流所属的用户。 |
StreamType | Integer | 否 | 0 | 流的类型。支持取值及含义如下:
0 。 |
ExcludeStreams | Object | 否 | - | 音视频流录制黑名单,即不需要录制的音视频流。 黑名单仅支持配置普通音视频流,且最多可配置 17 路。此参数中的 stream 不得和 TargetStreams 中重复。默认值为空。 |
StreamList | Object[] | 否 | - | 音视频流列表,由 Stream 组成,可以为空。为空时,表示订阅房间内所有流。在一个 StreamList 中,Stream.Index 不能重复。 |
Index | Integer | 否 | 0 | 在自定义布局中,使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中,你需要使用 Index 指定对应流的布局设置。 |
UserId | String | 是 | user1 | 用户 ID,表示这个流所属的用户。 |
StreamType | Integer | 否 | 0 | 流的类型。支持取值及含义如下:
0 。 |
Encode | Object | 否 | - | 音视频编码参数。
|
VideoWidth | Integer | 否 | 640 | 画面宽度。取值范围为 [2, 1920] ,必须是偶数,单位为像素,默认值为 640 。该参数在垂直布局和并排布局下生效,自定义布局下请使用 canvas.Width 设置画面宽度。 |
VideoHeight | Integer | 否 | 480 | 画面高度,取值范围为 [2, 1920] ,必须是偶数,单位为像素,默认值为 480 。该参数在垂直布局和并排布局下生效,自定义布局下请使用 canvas.Height 设置画面宽度。 |
VideoFps | Integer | 否 | 15 | 视频帧率。取值范围为 [1,60] ,单位为 FPS ,默认值为 15 。 |
VideoBitrate | Integer | 否 | 0 | 视频码率。取值范围为 [0,10000] ,单位为 Kbps,默认值为 0 。0 表示自适应码率,会自动根据 VideoFps , VideoWidth 以及VideoHeight 计算出合理的码率。自适应码率模式下,RTC 默认不会设置超高码率。如果订阅屏幕流,建议自行设置高码率。不同场景下设置码率等视频发布参数,请参考设置视频发布参数。 |
VideoCodec | Integer | 否 | 0 | 视频编码协议。支持取值及含义如下:
0 。 |
VideoGop | Integer | 否 | 4 | 输出视频 GOP。取值范围为 [1,5] ,单位为秒,默认值为 4 。 |
AudioCodec | Integer | 否 | 0 | 音频编码协议。仅支持取 0 ,表示 AAC 编码协议。 |
AudioProfile | Integer | 否 | 0 | 音频配置文件类型。支持取值及含义如下:
0 。 |
AudioBitrate | Integer | 否 | 64 | 音频码率。取值范围为 当 当
当
|
AudioSampleRate | Integer | 否 | 48000 | 音频采样率。可取值为: 32000 ,44100 ,48000 ,单位为 Hz,默认值为 48000 。 |
AudioChannels | Integer | 否 | 2 | 音频声道数。支持取值及含义如下:
2 。 |
Layout | Object | 否 | - | 布局参数。仅在合流模式(即 RecordMode =0 )时下支持设置布局参数。 |
LayoutMode | Integer | 否 | 0 | |
MainVideoStream | Object | 否 | - | 在垂直布局模式下生效,指定主画面流的属性。垂直布局时,此参数必填。 |
Index | Integer | 否 | 0 | 在自定义布局中,使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中,你需要使用 Index 指定对应流的布局设置。 |
UserId | String | 是 | user1 | 用户 ID,表示这个流所属的用户。 |
StreamType | Integer | 否 | 0 | 流的类型。支持取值及含义如下:
0 。 |
CustomLayout | Object | 否 | - | 使用自定义布局模式时,使用此参数进行具体设置。 |
Canvas | Object | 否 | - | 整体屏幕(画布)的宽高以及背景色。 |
Width | Integer | 否 | 640 | 整体屏幕(画布)的宽度,取值范围为 [2, 1920] ,必须是偶数,单位为像素,默认值为 640 。 |
Height | Integer | 否 | 480 | 整体屏幕(画布)的高度,取值范围为 [2, 1920] ,必须是偶数,单位为像素,默认值为 480 。 |
Background | String | 否 | #000000 | 整体屏幕(画布)的背景色, 范围为 #000000 ~ #ffffff (大小写均可),格式为 #RGB(16进制),默认值为 #000000 (黑色)。 |
BackgroundImage | String | 否 | - | 背景图片的 URL。长度最大为 1024 byte。可以传入的图片的格式包括: JPG , JPEG , PNG 。如果背景图片的宽高和整体屏幕的宽高不一致,背景图片会缩放到铺满屏幕。 如果你设置了背景图片,背景图片会覆盖背景色。 |
Regions | Object[] | 否 | - | 在自定义布局模式下,你可以使用 自定义布局模式下,对于
|
StreamIndex | Integer | 是 | 0 | 流的标识。这个标志应和 TargetStreams.StreamList.Stream.Index 对应。 |
LocationX | Integer | 否 | 0 | 视频流对应区域左上角的横坐标相对整体画面左上角原点的横向位移,取值的范围为 1920 , 视频流对应区域左上角的横坐标相对整体画面的比例为 0.33 ,那么该画布左上角的横坐标为 634 (1920*0.33=633.6,四舍五入取整)。 |
LocationY | Integer | 否 | 0 | 视频流对应区域左上角的横坐标相对整体画面左上角原点的纵向位移,取值的范围为 [0.0, Canvas.Height) 。默认值为 0 。若传入该参数,服务端会对该参数进行校验,若不合法会返回错误码 InvalidParameter 。 |
Width | Integer | 是 | 640 | 视频流对应区域宽度的像素绝对值,取值的范围为 (0.0, Canvas.Width] 。 |
Height | Integer | 是 | 480 | 视频流对应区域高度的像素绝对值,取值的范围为 (0.0, Canvas.Height] 。 |
ZOrder | Integer | 否 | 0 | 当多个流的画面有重叠时,使用此参数设置指定画面的图层顺序。取值范围为 [0, 100] ,默认值为 0 。0 表示该区域图像位于最下层,100 表示该区域图像位于最上层。 |
Alpha | Float | 否 | 1 | 画面的透明度,取值范围为 (0.0, 1.0] ,默认值为 1.0 。0.0 表示完全透明,1.0 表示完全不透明。 |
RenderMode | Integer | 否 | 0 | 画面的渲染模式。支持取值及含义如下:
0 。目前 0 和 3 均为按照指定的宽高直接缩放,但我们推荐你使用 3 以便与客户端实现相同逻辑。 |
SourceCrop | Object | 否 | - | 源流剪切功能,可以在源视频帧渲染之前进行裁剪,即预处理一次再渲染。 |
LocationX | Float | 否 | 0 | 裁剪后得到的视频帧左上角的横坐标相对裁剪前整体画面的比例,取值的范围为 [0.0, 1.0) 。默认值为 0.0 。 |
LocationY | Float | 否 | 0 | 裁剪后得到的视频帧左上角的纵坐标相对裁剪前整体画面的比例,取值的范围为 [0.0, 1.0) 。默认值为 0.0 。 |
WidthProportion | Float | 否 | 0.5 | 裁剪后得到的视频帧宽度相对裁剪前整体画面宽度的比例,取值范围为 (0.0, 1.0] 。默认值为 1.0 。 |
HeightProportion | Float | 否 | 0.5 | 裁剪后得到的视频帧高度相对裁剪前整体画面宽度的比例,取值范围为 (0.0, 1.0] 。默认值为 1.0 。 |
AlternateImage | String | 否 | - | 补位图片的 url。长度不超过 1024 个字符串。
|
CornerRadius | Float | 否 | 0.1 | 转推直播下边框圆角半径与画布宽度的比例值,取值范围为 [0,1] 。默认值为 0 ,表示没有圆角效果。圆角半径的像素位不能超过 Region 宽高最小值的一半,否则不会出现圆角效果。 |
MediaType | Integer | 否 | 0 | 该路流参与混流的媒体类型。支持取值及含义如下:
0 。例如该路流为音视频流, MediaType 设为1 ,则只混入音频内容。 |
AlternateImageFillMode | Integer | 否 | 0 | 画面的渲染模式。支持取值及含义如下:
0 。 |
Control | Object | 否 | - | 高级配置选项 |
MediaType | Integer | 否 | 0 | 订阅流类型。支持取值及含义如下:
0 。 |
FrameInterpolationMode | Integer | 否 | 0 | 补帧模式。支持取值及含义如下:
默认值为 如果同时配置
|
MaxSilenceSeconds | Integer | 否 | 3600 | 任务最大中断时间,仅对单流录制生效。取值范围为
|
MaxIdleTime | Integer | 否 | 180 | 任务的空闲超时时间,超过此时间后,任务自动终止。取值范围为 [10, 86400] ,单位为秒,默认值为 180 。 |
MaxRecordTime | Integer | 否 | 0 | 最大录制时长,取值为正整数,单位为秒。默认值为 0 。0 表示不限制录制时长。 |
EnableSyncUpload | Boolean | 否 | false | 是否开启边录制边上传功能。
默认值为 注意 该功能仅对 |
FileFormatConfig | Object | 否 | - | 录制文件的格式设置 |
FileFormat | String[] | 否 | ["HLS"] | 存储文件格式。支持取值包括: MP4 、HLS 、FLV 、MP3 、 AAC 、M4A 。可同时选择多个存储文件格式,最终生成所选存储格式对应的多个文件。MP3 、AAC 和M4A 仅在编码纯音频时有效。 |
FileNameConfig | Object | 否 | - | 录制文件的命名设置。 录制文件的名称由
|
Prefix | String[] | 否 | ["directory1","directory2"] | 指定录制文件名的前缀,对 TosConfig 和CustomConfig 生效。在 TOS 以及支持 S3 的第三方存储平台上,可以实现指定文件夹的功能。如: Prefix = ["directory1","directory2"] ,将在录制文件名前加上前缀 "directory1/directory2/ "。前缀长度最大值为 128 个字符。仅支持大小写字母、数字。 |
Pattern | String | 否 | {TaskId}{RoomId}{UserId}{Type}{StartTime}{Duration}{Random} | 自定义录制文件名模式,具体参看自定义录制文件名。 如果你设置了 Pattern ,需自行保证最终文件名的唯一性,否则在 TOS 或第三方存储平台上同名文件将被覆盖; 你也可以给对应 bucket 开启版本控制,允许文件名重复,防止被覆盖的情况发生。 |
StorageConfig | Object | 是 | - | 录制文件的存储平台配置。 支持:
|
Type | Integer | 否 | 0 | 存储平台类型
0 。 |
TosConfig | Object | 否 | - | Tos 平台设置。当 Type = 0 时,需正确设置 TosConfig 的值,否则请求会报错 |
AccountId | String | 是 | 210****990 | 火山引擎平台账号 ID,例如:
|
Region | Integer | 否 | 0 | 不同存储平台支持的 Region 不同,具体参看 Region对照表 默认值为0 。 |
Bucket | String | 是 | tos-vod-c****16fd9e8343 | 存储桶的名称。 |
VodConfig | Object | 否 | - | 点播平台设置。当 Type = 1 时,需正确设置 VodConfig 的值,否则请求会报错 |
AccountId | String | 是 | 210****933 | 火山引擎平台账号 ID,例如:
|
Region | Integer | 否 | 0 | 不同存储平台支持的 Region 不同,具体参看 Region对照表 默认值为0 。 |
Space | String | 是 | Storagespace | 点播空间名称。 |
StorageClass | Integer | 否 | 1 | 上传到视频点播平台时, 文件的存储类型。支持取值及含义如下::
1 。关于存储类型的详细说明,参看媒资存储存储类型 |
AutoSetFileExtension | Boolean | 否 | false | 上传到视频点播平台时, 是否需要根据文件后缀自动设置
false 。 |
CustomConfig | Object | 否 | - | 第三方存储平台设置。当 Type = 2 时,需正确设置 CustomConfig 的值,否则请求会报错 |
Vendor | Integer | 否 | 0 | 第三方云存储平台。支持取值及含义如下:
0 。 |
Region | Integer | 否 | 0 | 不同存储平台支持的 Region 不同,具体参看 Region对照表 默认值为0 。 |
Bucket | String | 是 | tos-vod-c****16fd9e8343 | 存储桶的名称。 |
AccessKey | String | 是 | AKLTMzV****NDcyNjU | 第三方存储平台账号的密钥。需确保此账号对存储桶有写权限。不建议开启读权限 |
SecretKey | String | 是 | TVRjMl****aadf== | 第三方存储平台账号的密钥 |
本接口无特有的返回参数。公共返回参数请见返回结构。
其中返回值 Result
仅在请求成功时返回 ok
,失败时为空。
POST https://rtc.volcengineapi.com?Action=StartRecord&Version=2023-11-01 { "AppId": "661e****543cf", "BusinessId": "12312312****2131djad", "RoomId": "Room1", "TaskId": "Task1", "RecordMode": 0, "FileFormatConfig": { "FileFormat": ["HLS", "FLV"] }, "FileNameConfig": { "Prefix": ["directory1", "directory2"], "Pattern": "" }, "StorageConfig": { "Type": 0, "TosConfig": { "UserAccountId": "21****89", "Region": "0", "Bucket": "tos-vod-cn-v****d9e8343******" } } }
{ "Result": "ok", "ResponseMetadata": { "RequestId": "20230****10420", "Action": "StartRecord", "Version": "2023-11-01", "Service": "rtc", "Region": "cn-north-1" } }
您可访问公共错误码,获取更多错误码信息。