实时音视频
实时音视频
文档指南
请输入
- 文档首页
实时音视频实时音视频服务端 API 参考云端录制开始云端录制 StartRecord
复制全文
下载 pdf开始云端录制 StartRecord
文档反馈
问问助手开启云端录制任务。支持将房间内的音视频流进行单流录制或合流录制，并配置视频布局、编码参数及存储至指定的云存储平台。
- 单流录制：将每一路指定录制的流单独录制成一个音视频文件。此时，你不可以设置布局；整体画面分辨率为原始视频分辨率，并不支持修改。
- 合流录制：将指定录制的流混合录制成一个音视频文件。录制时，你可以设置视频布局，分辨率，帧率，码率等。
使用说明
前提条件
获取录制文件
注意事项
请求频率：QPS 不得超过 60。
请求说明
- 请求方式：POST
- 请求地址：https://rtc.volcengineapi.com?Action=StartRecord&Version=2023-11-01
调试
API Explorer
您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。
请求参数
Query
Action String 必选 示例值：StartRecord
接口名称。当前 API 的名称为 StartRecord。
Version String 必选 示例值：2023-11-01
接口版本。当前 API 的版本为 2023-11-01。
Body
AppId String 必选 示例值：661e****543cf
BusinessId String 可选 示例值：B****23
RoomId String 必选 示例值：Room1
需要录制的房间的 ID。
TaskId String 必选 示例值：Task1
云端录制任务 ID。由您自定义，用于标识和管理（更新、停止）录制任务。
- 命名规范：符合正则表达式 [a-zA-Z0-9_@-.]{1,128}。
- 唯一性规则：在同一个 AppId 和 RoomId 组合下，TaskId 必须唯一。
任务运行中，使用相同 TaskId 重复调用该接口，系统将返回提示而非报错。
RecordMode Integer 可选 示例值：0
录制模式。支持取值及含义如下：
- 0（默认值）：合流录制。
- 1 ：单流录制。
TargetStreams Object 可选 示例值：-
指定需要录制的音视频流。若为空，默认录制房间内所有发布流（最多 17 路流）。
StreamList Object[] 可选 示例值：-
目标视频流列表。
Index Integer 可选 示例值：0
视频流的唯一索引，用于在自定义布局中标识该视频流。在 Layout.regions.StreamIndex 中会引用此 Index 来配置对应视频流的布局。
在一个 StreamList 中，Stream.Index 不能重复。
UserId String 必选 示例值：user1
目标视频流所属的用户 ID。
StreamType Integer 可选 示例值：0
流的类型：
- 0（默认值）：普通音视频流。
- 1：屏幕共享流。
ExcludeStreams Object 可选 示例值：-
指定不需要录制的音视频流（即黑名单），默认为空。最多可配置 17 路。
StreamList Object[] 可选 示例值：-
目标视频流列表。
Index Integer 可选 示例值：0
视频流的唯一索引，用于在自定义布局中标识该视频流。在 Layout.regions.StreamIndex 中会引用此 Index 来配置对应视频流的布局。
在一个 StreamList 中，Stream.Index 不能重复。
UserId String 必选 示例值：user1
目标视频流所属的用户 ID。
StreamType Integer 可选 示例值：0
流的类型：
- 0：普通音视频流。
- 1：屏幕共享流。
Encode Object 可选 示例值：-
音视频编码参数。
- 单流录制时，你仅可以设置 VideoFps 和 VideoBitrate。
- 合流录制时，你仅可以设置 VideoWidth、VideoHeight、VideoFps 和 VideoBitrate。
VideoFps Integer 可选 示例值：15
视频帧率。取值范围为 [1,60]，单位为 FPS，默认值为 15。
VideoBitrate Integer 可选 示例值：0
视频码率。取值范围为 [0,10000]，单位为 Kbps，默认值为 0。
0 表示自适应码率，会自动根据 VideoFps , VideoWidth 以及VideoHeight 计算出合理的码率。
VideoWidth Integer 可选 示例值：640
画面宽度。取值范围为 [2, 4096]，必须是偶数，单位为像素，默认值为 640。该参数在垂直布局和并排布局下生效，自定义布局下请使用 canvas.Width 设置画面宽度。
VideoHeight Integer 可选 示例值：480
画面高度，取值范围为 [2, 2160]，必须是偶数，单位为像素，默认值为 480。该参数在垂直布局和并排布局下生效，自定义布局下请使用 canvas.Height 设置画面宽度。
VideoCodec Integer 可选 示例值：0
视频编码协议。支持取值及含义如下：
- 0：H.264
- 1：ByteVC1
默认值为 0。
VideoGop Integer 可选 示例值：4
输出视频 GOP。取值范围为 [1,5]，单位为秒，默认值为 4。
AudioCodec Integer 可选 示例值：0
音频编码协议。仅支持取 0，表示 AAC 编码协议。
AudioProfile Integer 可选 示例值：0
音频配置文件类型。支持取值及含义如下：
- 0 :采用 LC 规格；
- 1: 采用 HE-AAC v1 规格；
- 2: 采用 HE-AAC v2 规格。此时，只支持输出流音频声道数为双声道。
默认值为 0。
AudioBitrate Integer 可选 示例值：64
音频码率。取值范围为 [32,192]，单位为 Kbps。若不传，默认值为 64。
当AudioProfile=0时：
若输入参数取值范围为 [32,192]，编码码率等于输入码率。
当AudioProfile=1时：
- 若输入参数取值范围为 [32,128]，编码码率等于输入码率。
- 若输入参数取值范围为 [128,192]，编码码率固定为128。
当AudioProfile=2时：
- 若输入参数取值范围为 [32,64]，编码码率等于输入码率。
- 若输入参数取值范围为 [64,192]，编码码率固定为64。
AudioSampleRate Integer 可选 示例值：48000
音频采样率。可取值为：16000、32000、44100、48000，单位为 Hz，默认值为 48000。
AudioChannels Integer 可选 示例值：2
音频声道数。支持取值及含义如下：
- 1：单声道。
- 2：双声道。
默认值为 2。
Layout Object 可选 示例值：-
布局参数。
MainVideoStream Object 可选 示例值：-
垂直布局配置。
Index Integer 可选 示例值：0
视频流的唯一索引，用于在自定义布局中标识该视频流。在 Layout.regions.StreamIndex 中会引用此 Index 来配置对应视频流的布局。
在一个 StreamList 中，Stream.Index 不能重复。
UserId String 必选 示例值：user1
目标视频流所属的用户 ID。
StreamType Integer 可选 示例值：0
流的类型：
- 0：普通音视频流。
- 1：屏幕共享流。
CustomLayout Object 可选 示例值：-
自定义布局配置。
Canvas Object 可选 示例值：-
整体屏幕（画布）的宽高以及背景色。
Width Integer 可选 示例值：640
整体屏幕（画布）的宽度，取值范围为 [2, 4096]，必须是偶数，单位为像素，默认值为 640。
Height Integer 可选 示例值：480
整体屏幕（画布）的高度，取值范围为 [2, 2160]，必须是偶数，单位为像素，默认值为 480。
Background String 可选 示例值：#000000
整体屏幕（画布）的背景色, 范围为 #000000 ~ #ffffff (大小写均可)，格式为 #RGB(16进制)，默认值为 #000000（黑色）。
BackgroundImage String 可选 示例值：-
背景图片的 URL。长度最大为 1024 byte。可以传入的图片的格式包括：JPG、JPEG、PNG。
如果背景图片的宽高和整体屏幕的宽高不一致，背景图片会缩放到铺满屏幕。
如果你设置了背景图片，背景图片会覆盖背景色。
Regions Object[] 可选 示例值：-
在自定义布局模式下，你可以使用 Regions 对每一路视频流进行画面布局设置。其中，每个 Region 对一路视频流进行画面布局设置。
自定义布局模式下，对于 StreamList 中的每个 Stream，Regions 中都需要给出对应的布局信息，否则会返回请求不合法的错误。即 Regions.Region.StreamIndex 要与 TargetStreams.StreamList.Stream.Index 的值一一对应，否则自定义布局设置失败，返回 InvalidParameter 错误码。
当传入的必填参数值不合法时，返回错误码 InvalidParameter 。
StreamIndex Integer 必选 示例值：0
流的标识。这个标志应和 TargetStreams.StreamList.Stream.Index 对应。
LocationX Integer 可选 示例值：0
视频流对应区域左上角的横坐标相对整体画面左上角原点的横向位移，取值的范围为 [0, Canvas.Width)。默认值为 0。若传入该参数，服务端会对该参数进行校验，若不合法会返回错误码 InvalidParameter。
视频流对应区域左上角的实际坐标是通过画面尺寸和相对位置比例相乘，并四舍五入取整得到的。假如，画布尺寸为 1920, 视频流对应区域左上角的横坐标相对整体画面的比例为 0.33，那么该画布左上角的横坐标为 634（1920*0.33=633.6，四舍五入取整）。
LocationY Integer 可选 示例值：0
视频流对应区域左上角的纵坐标相对整体画面左上角原点的纵向位移，取值的范围为 [0, Canvas.Height)。默认值为 0。若传入该参数，服务端会对该参数进行校验，若不合法会返回错误码 InvalidParameter。
Width Integer 必选 示例值：640
视频流对应区域宽度的像素绝对值，取值的范围为 (0, Canvas.Width]。
Height Integer 必选 示例值：480
视频流对应区域高度的像素绝对值，取值的范围为 (0, Canvas.Height]。
ZOrder Integer 可选 示例值：0
当多个流的画面有重叠时，使用此参数设置指定画面的图层顺序。
- 取值范围为 [0, 100]。0 表示该区域图像位于最下层，100 表示该区域图像位于最上层。
- 默认值为 0。
Alpha Float 可选 示例值：0.5
画面的透明度。
- 取值范围为 (0.0, 1.0]。0.0 表示完全透明，1.0 表示完全不透明。
- 默认值为 1.0。
RenderMode Integer 可选 示例值：0
画面的渲染模式。支持取值及含义如下：
- 0 ：按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形
- 1 ：按照显示区域的长宽比裁减视频，然后等比拉伸或缩小视频，占满显示区域。
- 2 ：按照原始画面的宽高比缩放视频，在显示区域居中显示。如果原始画面宽高比与指定的宽高比不同，就会导致画面有空缺，空缺区域为填充的背景色值。
- 3 ：按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形。
默认值为 0。
目前 0 和 3 均为按照指定的宽高直接缩放，但我们推荐你使用 3 以便与客户端实现相同逻辑。
SourceCrop Object 可选 示例值：-
源流剪切功能，可以在源视频帧渲染之前进行裁剪，即预处理一次再渲染。
LocationX Float 可选 示例值：0.1
裁剪后得到的视频帧左上角的横坐标相对裁剪前整体画面的比例，取值的范围为 [0.0, 1.0)。默认值为 0.0。
LocationY Float 可选 示例值：0.1
裁剪后得到的视频帧左上角的纵坐标相对裁剪前整体画面的比例，取值的范围为 [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 个字符串。
- 在 Region.StreamIndex 对应的视频流没有发布，或被暂停采集时，AlternateImage 对应的图片会填充 Region 对应的画布空间。当视频流被采集并发布时，AlternateImage 不造成任何影响。
- 可以传入的图片的格式包括：JPG、JPEG、PNG。
- 当图片和画布尺寸不一致时，图片根据 RenderMode 的设置，在画布中进行渲染。
CornerRadius Float 可选 示例值：0.1
转推直播下边框圆角半径与画布宽度的比例值，取值范围为 [0,1]。默认值为 0，表示没有圆角效果。
圆角半径的像素位不能超过 Region 宽高最小值的一半，否则不会出现圆角效果。
MediaType Integer 可选 示例值：0
该路流参与混流的媒体类型。支持取值及含义如下：
- 0：音视频
- 1：纯音频
- 2：纯视频
默认值为 0。
例如该路流为音视频流，MediaType设为 1，则只混入音频内容。
AlternateImageFillMode Integer 可选 示例值：0
画面的渲染模式。支持取值及含义如下：
- 0：按照用户原始视频帧比例进行缩放
- 1：保持图片原有比例
默认值为 0。
Control Object 可选 示例值：-
高级配置选项。
MediaType Integer 可选 示例值：0
订阅流类型。支持取值及含义如下：
- 0：音视频。
- 1：纯音频。
默认值为 0。
FrameInterpolationMode Integer 可选 示例值：0
补帧模式。支持取值及含义如下：
- 0：补最后一帧，
- 1：补黑帧。
默认值为0。自动布局模式下，该参数不生效。
补帧是指在音视频录制时，视频的帧率通常是固定的。但是，因为网络波动或其他原因，实际帧率可能无法达到预设的帧率。此时，需要补帧以保持视频流畅。补最后一帧意味着补充的视频帧和中断前的最后一帧相同，此时看到的画面可能会有短暂静止；补黑帧意味着补充的视频帧是全黑的。
如果同时配置Alternateimage 和FrameInterpolationMode ，优先使用 Alternateimage参数。
- 在 Region.StreamIndex 对应的视频流停止发布时, Region 对应的画布空间会根据设置填充占位图或补帧。但当视频流为屏幕流时，补帧模式不生效。
- 当 Region.StreamIndex 对应的视频流发布后停止采集或推送时, Region 对应的画布空间会填充上一帧。
- 当 Region.StreamIndex 对应的视频流发布时,设置的占位图或补帧模式不造成任何影响。
MaxSilenceSeconds Integer 可选 示例值：3600
任务最大中断时间，仅对单流录制生效。取值范围为 [60, 3600],单位为秒，默认值为 3600。
- 若任务中断时间小于该参数值，则根据设置的补帧模式进行补帧。
- 若任务中断时间大于该参数值但小于空闲超时时间，任务恢复时会生成一个新文件。
建议该参数取值小于 MaxIdleTime 取值。
MaxIdleTime Integer 可选 示例值：180
任务的空闲超时时间，单位为秒。
任务启动后，系统会自动分配一个后端机器人订阅目标流。如果机器人在房间内始终没有订阅到目标流（例如目标用户不在房间或指定的流停止发布），任务就会处于“空闲状态”。空闲时间超过设定值，任务就会自动结束。
- 取值范围为 [10, 86400]。
- 默认值为 180。
MaxRecordTime Integer 可选 示例值：0
最大录制时长，取值为正整数，单位为秒。默认值为 0。0 表示不限制录制时长。
EnableSyncUpload Boolean 可选 示例值：false
是否开启边录制边上传功能。
- false：关闭
- true：开启
默认值为 false。
注意
该功能仅对HLS格式存储文件生效，即：FileFormatConfig.FileFormat取值必须包含 HLS。若 HLS 格式文件名中包含填充变量，开通该功能的值始终为 0。
FileFormatConfig Object 可选 示例值：-
录制文件的格式设置。
FileFormat String[] 可选 示例值：["HLS"]
存储文件格式。支持取值包括：MP4、HLS、FLV、MP3、 AAC、M4A。可同时选择多个存储文件格式，最终生成所选存储格式对应的多个文件。
MP3、AAC和M4A仅在编码纯音频时有效。
FileNameConfig Object 可选 示例值：-
录制文件的命名设置。
录制文件的名称由 StorageConfig.Type 和 FileNameConfig 共同决定。
- 当StorageConfig.Type配置为 0 ，即存储在 TOS 平台时，录制文件名称由FilenameConfig.Prefix + FilenameConfig.Pattern +随机数组成
- 当StorageConfig.Type配置为 1 ，即存储在 火山引擎视频点播平台 平台时，录制文件名称由FilenameConfig.Pattern + 随机数组成
- 当StorageConfig.Type配置为 2 ，即存储在指定第三方S3 对象存储平台时，录制文件名称由FilenameConfig.Prefix + FilenameConfig.Pattern +随机数组成。
例如：当 StorageConfig.Type 配置为 0 ，FilenameConfig.Prefix配置为directory1/directory2/，FilenameConfig.Pattern 配置为 {TaskId}_{RoomId}_{StartTime}_{Duration}，
若此时该文件的 TaskId = mytask123456789, RoomId = myroom99991234，StartTime =1645769481126，Duration = 30s 且生成的随机八位字符为 c4694fa1，则生成录制文件的文件名为：directory1/directory2/mytask123456789_myroom99991234_1645769481126_000030_c4694fa1.mp4。
Prefix String[] 可选 示例值：["dir1","dir2"]
路径前缀，用于定义目录层级。例如，取值 ["dir1", "dir2"]，则会生成路径 dir1/dir2/。
总长度上限 128 字符，仅支持大小写字母和数字。
Pattern String 可选 示例值：{TaskId}_{RoomId}_{UserId}_{Type}_{StartTime}_{Duration}_{Random}
自定义文件名模版，支持通过变量定义。
- 支持的变量：
- 对单流切片：{TaskId}、{RoomId}、{UserId}、{Type}、{StartTime}、{Duration}。
- 对多流切片：{TaskId}、{RoomId}、{StartTime}、{Duration}。
- 限制：128 个字符；请勿在 Pattern 中包含文件后缀名（如 .mp4 或 .jpg）。
注意
如果设置了 Pattern，需自行保证最终文件名的唯一性，否则在 TOS 或第三方存储平台上同名文件将被覆盖；你也可以给对应 bucket 开启版本控制，允许文件名重复，防止被覆盖的情况发生。
StorageConfig Object 必选
录制文件的存储平台配置。
TosConfig Object 可选 示例值：-
Tos 平台设置。当 Type = 0 时，需正确设置 TosConfig 的值，否则请求会报错
AccountId String 必选 示例值：21****90
TOS 所属的火山引擎主账号 ID。
Bucket String 必选 示例值：tos-vod-****-16***43
存储桶（Bucket）的名称。
Region Integer 可选 示例值：0
ObjectMetadata Object 可选 示例值：-
设置上传到 TOS 的对象的元信息，如 HTTP 头、自定义元数据等，以实现如在线预览文件、缓存控制等功能。
注意
TOS 支持携带指定请求头来修改对象元数据，在下载对象或者 HEAD 对象时，这些值会设置到 HTTP 头域中，并返回给客户端。
AutoSetContentType Boolean 可选 示例值：true
默认值为 false（不开启）。
ContentDisposition String 可选 示例值：inline
- inline：在浏览器内直接在线显示（如预览图片、播放音频）。
- attachment：作为附件下载。
如果留空，则使用 TOS 的默认行为。
CacheControl String 可选 示例值：public, max-age=3600
设置 HTTP Cache-Control 头，用于控制 CDN 和浏览器的缓存行为。
- 传入格式和取值，参见 Cache-Control。
- 服务端会去除输入值首尾的空格。
Expires String 可选 示例值：2026-10-21T07:28:00Z
- 格式：RFC3339 格式的 UTC 时间字符串。
- 服务端会校验该时间必须晚于当前服务器时间，否则请求会失败。
- 若同时设置了 CacheControl，客户端通常会优先采用 CacheControl 的策略。
ContentEncoding String 可选 示例值：gzip
ContentLanguage String 可选 示例值：zh-CN
设置 HTTP Content-Language 头，用于指定内容的语言。
- 支持的取值，参见 Content-Language。
- 服务端会去除输入值首尾的空格。
Metadata JSONMap 可选 示例值：{"user-id": "12345"}
自定义元数据，映射到对象存储的自定义 header（如 x-amz-meta-* / x-tos-meta-*）。
- Key 规范：
- 不能为空，且长度不能超过 256 字节。
- 服务端会自动去除首尾空格并转换为小写。建议使用小写字母和 - 分隔符（例如 user-id）。
- Value 规范：服务端会按原始内容存储，不会做任何修改（包括不会去除空格）。
VodConfig Object 可选 示例值：-
点播平台设置。当 Type = 1 时，需正确设置 VodConfig 的值，否则请求会报错
AccountId String 必选 示例值：210****933
火山引擎平台账号 ID，例如：200000000。
- 火山引擎平台账号 ID 查看路径参看查看和管理账号信息。
- 此账号 ID 为火山引擎主账号 ID。
- 若你调用 OpenAPI 鉴权过程中使用的 AK、SK 为子用户 AK、SK，账号 ID 也必须为火山引擎主账号 ID，不能使用子用户账号 ID。
Region Integer 可选 示例值：0
Space String 必选 示例值：Storagespace
点播空间名称。
StorageClass Integer 可选 示例值：1
上传到视频点播平台时文件的存储类型：
- 1（默认值）：标准存储。
- 2：归档存储。
- 3：低频存储。
AutoSetFileExtension Boolean 可选 示例值：false
- true：需要
- false（默认值）：不需要
CustomConfig Object 可选
第三方存储平台设置。当 Type = 2时，需正确设置 CustomConfig 的值，否则请求会报错
Vendor Integer 可选 示例值：0
第三方云存储平台。支持取值及含义如下：
- 0：Amazon S3
- 1：阿里云 OSS
- 2：华为云 OBS
- 3：腾讯云 COS
- 4：七牛云 Kodo。
默认值为 0。
Bucket String 必选 示例值：tos-vod-c****16fd9e8343
存储桶的名称。
AccessKey String 必选 示例值：AKLTMzV****NDcyNjU
第三方存储平台账号的密钥。需确保此账号对存储桶有写权限。不建议开启读权限
SecretKey String 必选 示例值：TVRjMl****aadf==
第三方存储平台账号的密钥。
SecurityToken String 可选 示例值：security token
第三方云存储的临时访问凭证。该凭证由云服务商的安全令牌服务 (Security Token Service, STS) 临时颁发，具有有效期，超过有效期凭证将失效，减少因凭证泄露带来的安全风险。
- 有效时长要求：SecurityToken 的有效时长需要大于录制时长，并预留至少1小时的失败重试时间，否则可能存在丢失部分数据的风险。
- 不支持的云服务商：七牛云 Kodo 暂不支持。
返回参数
其中返回值 Result 仅在请求成功时返回 ok,失败时为空。
请求示例
POST https://rtc.volcengineapi.com?Action=StartRecord&Version=2023-11-01
{
"AppId": "661e7ae5543cf",
"BusinessId": "1231231232132131djad",
"RoomId": "Room1",
"TaskId": "Task1",
"RecordMode": 0,
"FileFormatConfig": {
"FileFormat": ["HLS", "FLV"]
},
"FileNameConfig": {
"Prefix": ["directory1", "directory2"],
"Pattern": ""
},
"StorageConfig": {
"Type": 0,
"TosConfig": {
"AccountId": "21000689",
"Region": 0,
"Bucket": "tos-vod-cn-v-16fd9e8343******"
}
}
}
返回示例
{
"Result": "ok",
"ResponseMetadata": {
"RequestId": "20230604110420",
"Action": "StartRecord",
"Version": "2023-11-01",
"Service": "rtc",
"Region": "cn-north-1"
}
}
错误码
最近更新时间：2026.08.21 13:49:44
这个页面对您有帮助吗？
有用
有用
无用
无用