You need to enable JavaScript to run this app.
实时音视频

实时音视频

请输入
  • 文档首页
    • 实时音视频实时音视频服务端 API 参考云端录制开始云端录制 StartRecord
复制全文
我的收藏
云端录制
开始云端录制 StartRecord
复制全文
我的收藏
开始云端录制 StartRecord

本文档 API 接口为最新版本接口，后续相关功能的新增都会在此更新，推荐使用最新版本接口。旧版接口文档请参考历史版本。

注意

在开始录制前，你必须已经在控制台上开启录制功能，参看在控制台开启/关闭云端录制功能。

在实时音视频通话场景中，你可以通过调用此接口实现云端录制功能，支持单流或合流录制模式。

你可以根据需求配置指定任务 ID、选择录制模式、自定义音视频流目标列表、设置编码参数、安排视频布局以及指定存储配置等，以满足多样化的录制需求。调用后，接口返回任务启动状态，确保录制流程顺利进行。

如果录制任务状态发生变化，你在控制台上设置的回调地址会收到每个状态变化的回调。

使用说明

接口行为

录制分为单流录制和合流录制：

  • 单流录制时：你可以将每一路指定录制的流单独录制成一个音视频文件。此时，你不可以设置布局；整体画面分辨率为原始视频分辨率，并不支持修改。
  • 合流录制时：你可以将指定录制的流混合录制成一个音视频文件。录制时，你可以设置视频布局，分辨率，帧率，码率等。
    无论你使用单流录制还是合流录制，一个任务下你最多只能录制 17 路流。

你需要在接口调用中配置存储空间，选择将录制结果存储在存储平台中。目前支持的存储平台包括：火山引擎视频点播 VOD、火山引擎对象存储 TOS、Amazon S3、阿里云对象存储 OSS、华为云 OBS、腾讯云 COS 和七牛云 Kodo。

录制文件生成后，不推荐调用 GetRecordTask接口获取录制生成的文件，强烈建议接入录制结束回调事件。

注意事项

请求频率：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
你的音视频应用的唯一标志，参看获取 AppId。
BusinessId
String
否
B****23
业务标识
RoomId
String
是
Room1
房间的 ID，是房间的唯一标志
TaskId
String
是
Task1

云端录制任务 ID。你必须对每个云端录制任务设定 TaskId，且在后续进行任务更新和结束时也须使用该 TaskId。

TaskId 是任务的标识，在一个 AppId 的 RoomId 下 taskId 是唯一的，不同 AppId 或者不同 RoomId 下 TaskId 可以重复，因此 AppId + RoomId + TaskId 是任务的唯一标识，可以用来标识指定 AppId 下某个房间内正在运行的任务，从而能在此任务运行中进行更新或者停止此任务。

关于 TaskId 及以上 Id 字段的命名规则符合正则表达式：[a-zA-Z0-9_@\-\.]{1,128}

若任务运行中，使用相同的 TaskId 重复调用开始接口不会导致请求失败，BaseResponse.Result 会提示 The task has been started. Please do not call the startup task interface repeatedly。
RecordMode
Integer
否
0

录制模式。支持取值及含义如下：

  • 0 ：合流录制，
  • 1 ：单流录制。
默认值为 0。
TargetStreams
Object
否
-
需要录制的音视频流。如果参数为空，默认录制房间内所有发布的音视频流，最多 17 路流。
此参数中的 stream 不得和 ExcludeStreams 中重复，若重复会报错InvalidParameter。
StreamList
Object[]
否
-
音视频流列表，由Stream组成，可以为空。为空时，表示订阅房间内所有流。在一个 StreamList 中，Stream.Index 不能重复。
ExcludeStreams
Object
否
-
音视频流录制黑名单，即不需要录制的音视频流。
黑名单仅支持配置普通音视频流，且最多可配置 17 路。此参数中的 stream 不得和 TargetStreams 中重复。
默认值为空。
StreamList
Object[]
否
-
音视频流列表，由Stream组成，可以为空。为空时，表示订阅房间内所有流。在一个 StreamList 中，Stream.Index 不能重复。
Encode
Object
否
-

音视频编码参数。

  • 单流录制时，你仅可以设置 VideoFps 和 VideoBitrate。
  • 合流录制时，你仅可以设置 VideoWidth，VideoHeight，VideoFps，和 VideoBitrate。
VideoWidth
Integer
否
640
画面宽度。取值范围为 [2, 4096]，必须是偶数，单位为像素，默认值为 640。该参数在垂直布局和并排布局下生效，自定义布局下请使用 canvas.Width 设置画面宽度。
VideoHeight
Integer
否
480
画面高度，取值范围为 [2, 2160]，必须是偶数，单位为像素，默认值为 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：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
音频采样率。可取值为：32000,44100，48000，单位为 Hz，默认值为 48000。
AudioChannels
Integer
否
2

音频声道数。支持取值及含义如下：

  • 1：单声道。
  • 2：双声道。
默认值为 2。
Layout
Object
否
-
布局参数。仅在合流模式（即 RecordMode=0）时下支持设置布局参数。
LayoutMode
Integer
否
0

布局模式。支持取值及含义如下：

默认值为 0。
MainVideoStream
Object
否
-
在垂直布局模式下生效，指定主画面流的属性。垂直布局时，此参数必填。
CustomLayout
Object
否
-
使用自定义布局模式时，使用此参数进行具体设置。
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 格式文件名中包含Duration填充变量，开通该功能Duration的值始终为 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。

文件名在 视频点播平台 上可以重复，但在 TOS 或第三方存储平台上默认不可以重复。

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 的值，否则请求会报错
VodConfig
Object
否
-
点播平台设置。当 Type = 1 时，需正确设置 VodConfig 的值，否则请求会报错
CustomConfig
Object
否
第三方存储平台设置。当 Type = 2时，需正确设置 CustomConfig 的值，否则请求会报错
VeImageXConfig
Object
否
-
VeImageX 平台设置。当 Type = 3时，需正确设置 VeImageXConfig 的值，否则请求会报错

返回参数

本接口无特有的返回参数。公共返回参数请见返回结构。
其中返回值 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"
    }
}

错误码

您可访问公共错误码，获取更多错误码信息。

最近更新时间：2025.09.09 11:48:30
这个页面对您有帮助吗？
有用
有用
无用
无用