本文档 API 接口为最新版本接口，后续相关功能的新增都会在此更新，推荐使用最新版本接口。旧版接口文档请参考历史版本。
对于一个音视频通话，你可以使用云端录制功能，录制音视频文件。

你可以使用 StartRecord 这个 OpenAPI 实现这一功能。

使用说明

接口行为

你可以调用 StartRecord 接口，指示 RTC 按照你设定的配置进行录制。设置包括：单流/合流，布局模板，音视频文件参数等。
录制分为单流录制和合流录制:

单流录制时：你可以将每一路指定录制的流单独录制成一个音视频文件。此时，你不可以设置布局；整体画面分辨率为原始视频分辨率，并不支持修改。
合流录制时：你可以将指定录制的流混合录制成一个音视频文件。录制时，你可以设置视频布局，分辨率，帧率，码率等。
无论你使用单流录制还是合流录制，你最多只能录制 17 路流。
你需要在接口调用中配置存储空间，选择将录制结果存储在存储平台中。目前支持的存储平台包括：火山引擎视频点播 VOD、火山引擎对象存储 TOS、Amazon S3、阿里云对象存储 OSS、华为云 OBS、腾讯云 COS 和七牛云 Kodo。
你也可以在控制台配置存储空间和文件格式，效果与调用 OpenAPI 一致。

如果你已开通录制开始的消息通知功能，在开始云端录制时，你能够收到相关回调通知。关于消息通知服务，参看开通消息通知服务。

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

前置条件

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

调用接口

关于调用接口的服务地址、通信协议、字符编码和签名机制，参看调用 OpenAPI。

注意事项

请求频率：QPS 不得超过 60。

请求说明

请求方式：POST
请求地址：https://rtc.volcengineapi.com?Action=StartRecord&Version=2023-11-01

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`StartRecord`	接口名称。当前 API 的名称为 `StartRecord`。
Version	String	是	`2023-11-01`	接口版本。当前 API 的版本为 `2023-11-01`。

Body

参数	类型	是否必选	示例值	描述
AppId	String	是	`Your_AppId`	你的音视频应用的唯一标志
BusinessId	String	否	`Your_BusinessId`	业务标识
RoomId	String	是	`Your_RoomId`	房间的 ID，是房间的唯一标志
TaskId	String	是	`Your_TaskId`	云端录制任务 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 of Streams	否	`-`	你可以通过本参数设定需要录制的音视频流。如果参数为空，默认录制对房间内所有发布的音视频流进行录制。无论合流还是单流录制，最多 17 路流。此参数中的 `stream` 不得和 `ExcludeStreams` 中重复。
ExcludeStreams	Object of Streams	否	`-`	你可以通过本参数设定不需要录制的音视频流，即录制流的黑名单。参数默认为空。黑名单中的流不得超过 17 路。不支持将屏幕流添加到黑名单中。此参数中的 `stream` 不得和 `TargetStreams` 中重复。
Encode	Object of Encode	否	`-`	音视频编码参数。单流录制时，你仅可以设置 `VideoFps` 和 `VideoBitrate`。合流录制时，你仅可以设置 `VideoWidth`，`VideoHeight`，`VideoFps`，和 `VideoBitrate`。
Layout	Object of Layout	否	`-`	布局参数。仅在合流模式下支持设置布局参数。
Control	Object of Control	否	`-`	配置选项
FileFormatConfig	Object of FileFormatConfig	否	`-`	录制文件的格式设置
FileNameConfig	Object of FileNameConfig	否	`-`	录制文件的命名设置。录制文件的名称由 `[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 或第三方存储平台上默认不可以重复。如果你设置了 `Pattern`，需自行保证最终文件名的唯一性，否则在 TOS 或第三方存储平台上同名文件将被覆盖; 你也可以给对应 bucket 开启版本控制，允许文件名重复，防止被覆盖的情况发生。
StorageConfig	Object of StorageConfig	是	`-`	录制文件的存储平台。目前支持：火山引擎视频点播 VOD 、火山引擎对象存储 TOS、Amazon S3、阿里云对象存储 OSS、华为云 OBS、腾讯云 COS 和七牛云 Kodo。

Streams

参数	类型	是否必选	示例值	描述
StreamList	Array of Stream	否	`-`	由`Stream`组成的列表，可以为空。为空时，表示订阅房间内所有流。在一个 `StreamList` 中，`Stream.Index` 不能重复。

Encode

参数	类型	是否必选	示例值	描述
VideoWidth	Integer	否	`640`	输出画面的宽度。默认值为`640`，范围为 `[2, 1920]`，必须是偶数。自定义布局下此参数不生效，整体画面宽度以 `canvas` 中的 `Width` 为主。
VideoHeight	Integer	否	`480`	输出画面的高度，范围为`[2, 1920]`，必须是偶数，默认值为`480`。自定义布局下此参数不生效，整体画面高度以 `canvas` 中的 `Height` 为主。
VideoFps	Integer	否	`15`	输出视频帧率。默认为 `15`，取值范围为 `[1,60]`。
VideoBitrate	Integer	否	`/`	输出视频码率。取值范围 [0,10000]，单位为 Kbps，默认值为 `0`。 `0` 表示自适应码率，会自动根据 `VideoFps` , `VideoWidth` 以及`VideoHeight` 计算出合理的码率。自适应码率模式下，RTC 默认不会设置超高码率。如果订阅屏幕流，建议自行设置高码率。不同场景下设置码率等视频发布参数,请参考设置视频发布参数。
VideoCodec	Integer	否	`0`	视频编码协议。默认值为 `0`，可以取 `0` 或 `1`。取 `0` 时使用 `H.264`,取 `1` 时使用 `ByteVC1` 编码器。
VideoGop	Integer	否	`4`	输出视频 GOP。默认为 `4`，取值范围为 `[1,5]`，单位为秒。
AudioCodec	Integer	否	`0`	音频编码协议。默认值为 `0`，此时使用 aac 编码协议。目前只支持 aac。
AudioProfile	Integer	否	`0`	音频配置文件类型，在使用 aac 编码时生效。取值范围为 `{0, 1, 2}`。 `0` :采用 LC 规格； `1`: 采用 HE-AAC v1 规格； `2`: 采用 HE-AAC v2 规格。取 `2` 时，只支持输出流音频声道数为双声道。默认值为 `0`。
AudioBitrate	Integer	否	`/`	音频码率。取值范围为 `[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`	音频采样率。默认值 `48000`，取值为 `[32000,44100,48000]`，单位是 Hz。
AudioChannels	Integer	否	`2`	音频声道数。 `1`：单声道 `2`：双声道。默认值为 `2`。

Layout

参数类型是否必选示例值描述

参数	类型	是否必选	示例值	描述
LayoutMode	Integer	否	`0`	布局模式。默认值为 `0`，值的范围为 `{0, 1, 2, 3}`。 `0` 为自适应布局模式。参看自适应布局。 `1` 为垂直布局模式。参看垂直布局。 `2` 为自定义布局模式。 `3` 为并排布局模式。参看并排布局
MainVideoStream	Object of Stream	否		在垂直布局模式下生效，指定主画面流的属性。如果此参数为空，则主画面为随机的一路流。
CustomLayout	Object of CustomLayout	否		使用自定义布局模式时，使用此参数进行具体设置。

LayoutMode

Integer

否

0

布局模式。默认值为 0，值的范围为 {0, 1, 2, 3}。

0 为自适应布局模式。参看自适应布局。
1 为垂直布局模式。参看垂直布局。
2 为自定义布局模式。
3 为并排布局模式。参看并排布局

MainVideoStream Object of Stream 否在垂直布局模式下生效，指定主画面流的属性。如果此参数为空，则主画面为随机的一路流。

CustomLayout Object of CustomLayout 否使用自定义布局模式时，使用此参数进行具体设置。

Control

参数	类型	是否必选	示例值	描述
MediaType	Integer	否	`0`	流的类型，用于全局控制订阅的流的类型。默认值为`0`，可以取`0`和`1`。`0`表示音视频，`1`表示纯音频，暂不支持纯视频。
FrameInterpolationMode	Integer	否	`0`	选择补帧模式。默认值为`0`，可以取`0`和`1`。`0`为补最后一帧，`1`为补黑帧。自动布局模式下，没有补帧的逻辑。补帧是指在音视频录制或合流转推时，视频的帧率通常是固定的。但是，因为网络波动或其他原因，实际帧率可能无法达到预设的帧率。此时，需要补帧以保持视频流畅。补最后一帧意味着补充的视频帧和中断前的最后一帧相同，此时看到的画面可能会有短暂静止；补黑帧意味着补充的视频帧是全黑的。使用占位图、补帧和上一帧的关系: 你可以在 `Region` 中传入 `Alternateimage` 字段设置占位图,在 `Control` 中传入`FrameInterpolationMode` 字段设置补帧模式,但占位图优先级高于补帧模式。在 `Region.StreamIndex` 对应的视频流停止发布时, `Region` 对应的画布空间会根据设置填充占位图或补帧。但当视频流为屏幕流时，补帧模式不生效。当 `Region.StreamIndex` 对应的视频流发布后停止采集或推送时, `Region` 对应的画布空间会填充上一帧。当 `Region.StreamIndex` 对应的视频流发布时,设置的占位图或补顿模式不造成任何影响。
MaxIdleTime	Integer	否	`180`	任务的空闲超时时间，超过此时间后，任务自动终止。单位为秒。取值范围为 `[10, 86400]`, 默认值为 `180`。
MaxRecordTime	Integer	否	`0`	（仅对录制有效）最大录制时长，单位为秒。默认值为 `0`。`0` 表示不限制录制时长。
SpatialConfig	Object of SpatialConfig	否		空间音频配置。若合流转推的音频参数设置为单声道，空间音频无效。
PushStreamMode	Integer	否	`0`	转推直播推流模式，用于控制触发推流的时机。取值为`0`或`1`。默认值为`0`。 `0`：房间内有用户推 RTC 流时即触发 CDN 推流。 `1`：调用接口发起推流任务后，无论房间内是否有用户推 RTC 流,均可触发 CDN 推流。任务超时逻辑不变，依然是无用户推流即判定为超时。
SEIConfig	Object of SEIConfig	否		（仅对转推直播有效）SEI 相关配置。

FileFormatConfig

参数	类型	是否必选	示例值	描述
FileFormat	Array of String	否	`["HLS"]`	存储文件格式。可取值为：`MP4`、`HLS`、`FLV`、`MP3`、 `AAC`、`M4A`。可同时选择多个存储文件格式，最终生成所选存储格式对应的多个文件。 `MP3`、`AAC`和`M4A`仅在编码纯音频时有效。

FileNameConfig

参数类型是否必选示例值描述

参数	类型	是否必选	示例值	描述
Prefix	Array of String	否		制定录制文件名的前缀，对`TosConfig`和`CustomConfig`生效。 `Prefix` 为指定录制文件名的前缀，是一个由多个字符串组成的数组，在 TOS 以及支持 S3 的第三方存储平台上，可以实现指定文件夹的功能。如：`Prefix` = `["directory1","directory2"]`，将在录制文件名前加上前缀 "`directory1/directory2/`"。前缀长度（包括斜杠）不得超过 128 个字符。`Prefix`中不得出现斜杠、下划线、括号等符号字符。仅支持以下字符： 26 个小写英文字母 a-z 26 个大写英文字母 A-Z 10 个数字 0-9
Pattern	String	否	`/`	自定义录制文件名模式，具体参看自定义录制文件名。

Prefix

Array of String

否

制定录制文件名的前缀，对TosConfig和CustomConfig生效。
Prefix 为指定录制文件名的前缀，是一个由多个字符串组成的数组，在 TOS 以及支持 S3 的第三方存储平台上，可以实现指定文件夹的功能。如：Prefix = ["directory1","directory2"]，将在录制文件名前加上前缀 "directory1/directory2/"。
前缀长度（包括斜杠）不得超过 128 个字符。Prefix中不得出现斜杠、下划线、括号等符号字符。
仅支持以下字符：

26 个小写英文字母 a-z
26 个大写英文字母 A-Z
10 个数字 0-9

Pattern String 否 / 自定义录制文件名模式，具体参看自定义录制文件名。

StorageConfig

参数	类型	是否必选	示例值	描述
Type	Integer	否	`0`	存储平台类型 0：火山引擎对象存储 TOS 1: 火山引擎视频点播 VOD 2: 第三方存储平台(需支持 S3 协议) 3: VeImageX (当前仅支持抽帧截图功能) 默认值为 `0`。
TosConfig	Object of TosConfig	否	`-`	当 Type = `0` 时，需正确设置 `TosConfig` 的值，否则请求会报错
VodConfig	Object of VodConfig	否	`-`	当 Type = `1` 时，需正确设置 `VodConfig` 的值，否则请求会报错
CustomConfig	Object of CustomConfig	否	`-`	当 Type = `2`时，需正确设置 `CustomConfig` 的值，否则请求会报错
VeImageXConfig	Object of VeImageXConfig	否	`-`	当 Type = `3`时，需正确设置 `VeImageXConfig` 的值，否则请求会报错

Stream

参数	类型	是否必选	示例值	描述
Index	Integer	否	`0`	在自定义布局中，使用 `Index` 对流进行标志。后续在 `Layout.regions.StreamIndex` 中，你需要使用 `Index` 指定对应流的布局设置。
UserId	String	是	`Your_UserId`	用户Id，表示这个流所属的用户。
StreamType	Integer	否	`0`	流的类型，值可以取`0`或`1`，默认值为`0`。`0`表示普通音视频流，`1`表示屏幕流。

CustomLayout

参数类型是否必选示例值描述

Canvas Object of Canvas 否整体屏幕（画布）的宽高以及背景色。

参数	类型	是否必选	示例值	描述
Canvas	Object of Canvas	否		整体屏幕（画布）的宽高以及背景色。
Regions	Array of Region	否		在自定义布局模式下，你可以使用 `Regions` 对每一路视频流进行画面布局设置。其中，每个 `Region` 对一路视频流进行画面布局设置。自定义布局模式下，对于 `StreamList` 中的每个 `Stream`，`Regions` 中都需要给出对应的布局信息，否则会返回请求不合法的错误。即 `Regions.Region.StreamIndex` 要与 `TargetStreams.StreamList.Stream.Index` 的值一一对应，否则自定义布局设置失败，返回 `InvalidParameter` 错误码。当传入的必填参数值不合法时，返回错误码 `InvalidParameter` 。

Regions

Array of Region

否

在自定义布局模式下，你可以使用 Regions 对每一路视频流进行画面布局设置。其中，每个 Region 对一路视频流进行画面布局设置。
自定义布局模式下，对于 StreamList 中的每个 Stream，Regions 中都需要给出对应的布局信息，否则会返回请求不合法的错误。即 Regions.Region.StreamIndex 要与 TargetStreams.StreamList.Stream.Index 的值一一对应，否则自定义布局设置失败，返回 InvalidParameter 错误码。

当传入的必填参数值不合法时，返回错误码 InvalidParameter 。

SpatialConfig

参数	类型	是否必选	示例值	描述
EnableSpatialRender	Boolean	否	`false`	是否开启空间音频处理功能。 `false`：关闭。 `true`：开启
AudienceSpatialPosition	Array of Integer	否	`[0,0,0]`	观众所在位置的三维坐标，默认值为`[0,0,0]`。数组长度为`3`，三个值依次对应`X`,`Y`,`Z`，每个值的取值范围为`[-100,100]`。
AudienceSpatialOrientation	Object of AudienceSpatialOrientation	否		设置观众朝向。各个向量两两垂直，如果传入的值没有保证两两垂直，自动赋予默认值。默认值为：`forward` = `[1, 0, 0]`, `right` = `[0, 1, 0]`, `up` = `[0, 0, 1]`。

SEIConfig

参数	类型	是否必选	示例值	描述
UserConfigExtraInfo	String	否	`/`	设置SEI数据结构中 `app_data` 参数的值，最大长度为 `4096`。此参数支持动态更新。
PassthroughRTCSEIMessage	Boolean	否	`true`	是否透传 RTC 流里的 SEI 信息。 `true`：是。 `false`：否。默认值为 `true`。
VolumeIndicationInterval	Float	否	`2`	用户说话音量的回调间隔，单位为秒，取值范围为`[0.3,∞]`，默认值为 `2`。仅当用户说话音量发生变化时此回调才会被触发。
VolumeIndicationMode	Boolean	否	`false`	(仅对转推直播有效）是否开启音量指示模式。 `true`：是。此时非关键帧中也可能携带 SEI 信息。 `false`：否。此时只会在关键帧中携带 SEI 信息。默认值为 `false`。若 `VolumeIndicationMode` = `true` 的同时设置 `MediaType` = `1`，该流推向 CDN 地址时，服务端会补黑帧。关于音量指示模式的用法，参看音量指示模式。
AddVolumeValue	Boolean	否	`false`	SEI 中是否包含用户说话音量值。 `false`：否。 `true`：是。默认值为 `false`。
SEIContentMode	Integer	否	`0`	开启音量指示模式后，非关键帧携带 SEI 包含的信息类型。 `0`：全量信息。 `1`：只有音量信息和时间戳。关于 SEI 结构，参看服务端合流转推 SEI 结构
SEIPayLoadType	Integer	否	`100`	设置 SEI 的 `Payload Type`，对服务端合流转推 SEI 和 RTC 透传SEI 均生效。取值为 `5` 或 `100`，默认为 `100`。
SEIPayloadUUID	String	否	`566f6c63656e67696e65525443534549`	该字段为长度为 32 位的 16 进制字符，每个字符的范围为 `a-f，A-F，0-9`，不可包含 `-`。如果校验失败，会返回错误码 `InvalidParameter`。仅当 `SEIPayLoadType`=`5`时，该字段需要填写，`SEIPayLoadType`=`100`时，该字段内容会被忽略。此参数仅对 RTC 透传SEI 生效。当用户设置 `SEIPayloadType` = `5` 时，服务端合流转推SEI 的 `SEIPayloadUUID` 为固定值：`566f6c63656e67696e65525443534549`，对应16位字符串 `VolcengineRTCSEI`。

TosConfig

参数类型是否必选示例值描述

参数	类型	是否必选	示例值	描述
AccountId	String	是	`Your_AccountId`	火山引擎平台账号 ID，例如：`200000000`。火山引擎平台账号 ID 查看路径：控制台->账号管理->账号信息此账号 ID 为火山引擎主账号 ID。若你调用 OpenAPI 鉴权过程中使用的 AK、SK 为子用户 AK、SK，账号 ID 也必须为火山引擎主账号 ID，不能使用子用户账号 ID。
Region	Integer	否	`0`	不同存储平台支持的 Region 不同，具体参看 Region对照表默认值为`0`。
Bucket	String	是	`Your_Bucket`	存储桶的名称。

AccountId

String

是

Your_AccountId

火山引擎平台账号 ID，例如：200000000。

火山引擎平台账号 ID 查看路径：控制台->账号管理->账号信息
此账号 ID 为火山引擎主账号 ID。
若你调用 OpenAPI 鉴权过程中使用的 AK、SK 为子用户 AK、SK，账号 ID 也必须为火山引擎主账号 ID，不能使用子用户账号 ID。

Region

Integer

否

0

不同存储平台支持的 Region 不同，具体参看 Region对照表
默认值为0。

Bucket String 是 Your_Bucket 存储桶的名称。

VodConfig

参数类型是否必选示例值描述

参数	类型	是否必选	示例值	描述
AccountId	String	是	`Your_AccountId`	火山引擎平台账号 ID，例如：`200000000`。火山引擎平台账号 ID 查看路径：控制台->账号管理->账号信息此账号 ID 为火山引擎主账号 ID。若你调用 OpenAPI 鉴权过程中使用的 AK、SK 为子用户 AK、SK，账号 ID 也必须为火山引擎主账号 ID，不能使用子用户账号 ID。
Region	Integer	否	`0`	不同存储平台支持的 Region 不同，具体参看 Region对照表默认值为`0`。
Space	String	是	`Your_Space`	点播空间名称。

AccountId

String

是

Your_AccountId

火山引擎平台账号 ID，例如：200000000。

火山引擎平台账号 ID 查看路径：控制台->账号管理->账号信息
此账号 ID 为火山引擎主账号 ID。
若你调用 OpenAPI 鉴权过程中使用的 AK、SK 为子用户 AK、SK，账号 ID 也必须为火山引擎主账号 ID，不能使用子用户账号 ID。

Region

Integer

否

0

不同存储平台支持的 Region 不同，具体参看 Region对照表
默认值为0。

Space String 是 Your_Space 点播空间名称。

CustomConfig

参数	类型	是否必选	示例值	描述
Vendor	Integer	否	`0`	第三方云存储平台。 `0`： Amazon S3 `1`：阿里云 OSS `2`：华为云 OBS `3`：腾讯云 COS `4`：七牛云 Kodo。默认值为 `0`。
Region	Integer	否	`0`	不同存储平台支持的 Region 不同，具体参看 Region对照表默认值为`0`。
Bucket	String	是	`Your_Bucket`	存储桶的名称。
AccessKey	String	是	`Your_AccessKey`	第三方存储平台账号的密钥。需确保此账号对存储桶有写权限。不建议开启读权限
SecretKey	String	是	`Your_SecretKey`	第三方存储平台账号的密钥

VeImageXConfig

参数类型是否必选示例值描述

参数	类型	是否必选	示例值	描述
AccountId	String	是	`Your_AccountId`	火山引擎平台账号 ID，例如：`200000000`。火山引擎平台账号 ID 查看路径：控制台->账号管理->账号信息此账号 ID 为火山引擎主账号 ID。若你调用 OpenAPI 鉴权过程中使用的 AK、SK 为子用户 AK、SK，账号 ID 也必须为火山引擎主账号 ID，不能使用子用户账号 ID。
Region	Integer	否	`/`	不同存储平台支持的 Region 不同，具体参看 Region对照表默认值为`0`。
ServiceId	String	是	`Your_ServiceId`	服务 ID。你可以在 veImageX 控制台服务管理页面，通过创建好的图片服务中获取服务 ID。你也可以通过 OpenAPI 的方式获取服务 ID，具体请参考获取所有服务信息。

AccountId

String

是

Your_AccountId

火山引擎平台账号 ID，例如：200000000。

火山引擎平台账号 ID 查看路径：控制台->账号管理->账号信息
此账号 ID 为火山引擎主账号 ID。
若你调用 OpenAPI 鉴权过程中使用的 AK、SK 为子用户 AK、SK，账号 ID 也必须为火山引擎主账号 ID，不能使用子用户账号 ID。

Region

Integer

否

/

不同存储平台支持的 Region 不同，具体参看 Region对照表
默认值为0。

ServiceId

String

是

Your_ServiceId

服务 ID。

你可以在 veImageX 控制台服务管理页面，通过创建好的图片服务中获取服务 ID。
你也可以通过 OpenAPI 的方式获取服务 ID，具体请参考获取所有服务信息。

Canvas

参数	类型	是否必选	示例值	描述
Width	Integer	否	`640`	整体屏幕（画布）的宽度，单位为像素，范围为 `[2, 1920]`，必须是偶数。默认值为 `640`。
Height	Integer	否	`480`	整体屏幕（画布）的高度，单位为像素，范围为 `[2, 1920]`，必须是偶数。默认值为 `480`。
Background	String	否	`#000000`	整体屏幕（画布）的背景色，格式为 #RGB(16进制)，默认值为 `#000000`（黑色）, 范围为 `#000000 ~ #ffffff` (大小写均可)。
BackgroundImage	String	否	`/`	背景图片的 URL。长度最大为 1024 byte。可以传入的图片的格式包括：JPG, JPEG, PNG。如果背景图片的宽高和整体屏幕的宽高不一致，背景图片会缩放到铺满屏幕。如果你设置了背景图片，背景图片会覆盖背景色。

Region

参数	类型	是否必选	示例值	描述
StreamIndex	Integer	是	`0`	流的标识。这个标志应和 `TargetStreams.StreamList.Stream.Index` 对应。
LocationX	Integer	否	`0`	视频流对应区域左上角的横坐标相对整体画面左上角原点的横向位移，取值的范围为 `[0.0, Canvas.Width)`。默认值为 `0`。若传入该参数，服务端会对该参数进行校验，若不合法会返回错误码 `InvalidParameter`。视频流对应区域左上角的实际坐标是通过画面尺寸和相对位置比例相乘，并四舍五入取整得到的。假如，画布尺寸为`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` 表示该区域图像位于最下层，`100` 表示该区域图像位于最上层, 默认值为 `0`。
Alpha	Float	否	`1`	画面的透明度，取值范围为 `(0.0, 1.0]`。`0.0` 表示完全透明，`1.0` 表示完全不透明，默认值为 `1.0`。
RenderMode	Integer	否	`0`	画面的渲染模式，值的范围为 `{0, 1, 2，3}`, 默认值为 `0`： `0` 表示按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形 `1` 表示按照显示区域的长宽比裁减视频，然后等比拉伸或缩小视频，占满显示区域。 `2` 表示按照原始画面的宽高比缩放视频，在显示区域居中显示。如果原始画面宽高比与指定的宽高比不同，就会导致画面有空缺，空缺区域为填充的背景色值。 `3` 表示按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形。目前 `0` 和 `3` 均为按照指定的宽高直接缩放，但我们推荐你使用 `3` 以便与客户端实现相同逻辑。不同渲染模式下，效果如下：
SourceCrop	Object of SourceCrop	否		源流剪切功能，可以在源视频帧渲染之前进行裁剪，即预处理一次再渲染。
AlternateImage	String	否	`rtmp://xxx.xxx`	补位图片的 url。长度不超过 1024 个字符串。在 `Region.StreamIndex` 对应的视频流没有发布，或被暂停采集时，`AlternateImage` 对应的图片会填充 `Region` 对应的画布空间。当视频流被采集并发布时，`AlternateImage` 不造成任何影响。可以传入的图片的格式包括：JPG, JPEG, PNG。当图片和画布尺寸不一致时，图片根据 `RenderMode` 的设置，在画布中进行渲染。
ApplySpatialAudio	Boolean	否	`/`	该路流对应的用户是否开启空间音频效果。 `true`：开启空间音频效果。 `false`：关闭空间音频效果。默认值为 `true`
SpatialPosition	Array of Integer	否	`[0,0,0]`	空间音频下，房间内指定用户所在位置的三维坐标，默认值为`[0,0,0]`。数组长度为`3`，三个值依次对应`X`,`Y`,`Z`，每个值的取值范围为`[-100,100]`。
CornerRadius	Float	否	`0.1`	转推直播下边框圆角半径与画布宽度的比例值，取值范围为 `[0,1]`。圆角半径的像素位不能超过 Region 宽高最小值的一半，否则不会出现圆角效果。
MediaType	Integer	否	`0`	该路流参与混流的媒体类型。 `0`：音视频 `1`：纯音频 `2`：纯视频默认值为 `0`。假如该路流为音视频流，`MediaType`设为`1`，则只混入音频内容。
AlternateImageFillMode	Integer	否	`0`	画面的渲染模式。 `0`：按照用户原始视频帧比例进行缩放 `1`：保持图片原有比例默认值为 `0`。

AudienceSpatialOrientation

参数	类型	是否必选	示例值	描述
Up	Array of Float	否	`[0, 0, 1]`	头顶朝向
Right	Array of Float	否	`[0, -1, 0]`	右边朝向
Forward	Array of Float	否	`[1, 0, 0]`	前方朝向

SourceCrop

参数	类型	是否必选	示例值	描述
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`。

返回参数

本接口无特有的返回参数。公共返回参数请见返回结构。
其中返回值 Result 仅在请求成功时返回 ok,失败时为空。

请求示例

POST https://rtc.volcengineapi.com?Action=StartRecord&Version=2023-11-01

{
  "AppId": "Your_AppId",
  "BusinessId": "Your_BusinessId",
  "RoomId": "Your_RoomId",
  "TaskId": "Your_TaskId",
  "RecordMode": 0,
  "FileFormatConfig": {
    "FileFormat": ["HLS", "FLV"]
  },
  "FileNameConfig": {
    "Prefix": ["directory1", "directory2"],
    "Pattern": ""
  },
  "StorageConfig": {
    "Type": 0,
    "TosConfig": {
      "UserAccountId": "Your_UserAccountId",
      "Region": "Your_Region",
      "Bucket": "Your_Bucket"
    }
  }
}
json

返回示例

{
  "Result": "ok",
  "ResponseMetadata": {
    "RequestId": "Your_RequestId",
    "Action": "StartRecord",
    "Version": "2023-11-01",
    "Service": "rtc",
    "Region": "cn-north-1"
  }
}
json

错误码

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