StartRecord

2026-09-23

POST

https://cloudrecord-api.zego.im/

调用本接口开始云端录制。

当开发者成功调用 StartRecord 接口后，云端录制服务会根据设置的录制参数录制房间内的音视频流和白板。

注意

每个录制任务时间最长为 24 小时。超过 24 小时，录制任务将自动停止录制。
ZEGO 建议您的每个录制任务都调用 StopRecord 方法停止录制，以免持续录制产生额外的费用。

说明

调用频率限制：50 次/秒

Request

Query Parameters

Action string必填

可选值: [StartRecord]

接口原型参数

https://cloudrecord-api.zego.im?Action=StartRecord

AppId uint32必填

💡公共参数。应用 Id，由 ZEGO 分配的用户唯一凭证。可从 ZEGO 控制台获取。

SignatureNonce string必填

💡公共参数。16 位 16 进制随机字符串（8 字节随机数的 hex 编码）。生成算法可参考签名示例。

Timestamp int64必填

💡公共参数。当前 Unix 时间戳，单位为秒。生成算法可参考签名示例，最多允许 10 分钟的误差。

SignatureVersion string必填

可选值: [2.0]

默认值: 2.0

💡公共参数。签名版本号。

Signature string必填

💡公共参数。签名，用于验证请求的合法性。请参考签名机制生成。

application/json

Body

required

RoomId string必填

待录制的房间 ID。

RecordInputParams objectrequired

注意
FillBlank 和 MaxIdleTime 作用对象不同：
FillBlank：作用于流本身，只要录制任务还在进行，FillBlank 设置为 true 后，若流处于中断状态，则会继续以补白的方式录制，此时该流仍然为中断状态，不影响房间内有无流的判断。
MaxIdleTime：作用于整个录制任务状态，当房间内无流时长超过 MaxIdleTime 时，则会中止整个录制任务。
混流录制模式下，若 StreamType 为 1，表示仅录制音频，此时无法录制白板。

RecordMode integer必填

可选值: [1, 2]

录制模式。

1：单流录制
2：混流录制

StreamType integer

可选值: [1, 2, 3, 4]

默认值: 3

录制媒体流类型，仅适用于音视频流，白板只会录制视频。

1：仅录制音频
2：仅录制视频
3：录制音视频（音视频文件合并）（默认值）
4：录制音视频（音频视频文件分离）

ClientTaskId string

用户发起录制请求的任务 ID。
如果该录制任务 ID 已存在对应的服务端录制任务，响应参数 TaskId 则返回已存在的服务端录制任务 ID；否则服务端将创建一个新的录制任务，响应参数 TaskId 则返回新创建的服务端录制任务 ID。

RecordStreamList object[]

仅适用于单流录制模式，指定要录制的流信息列表。若未指定该字段或该列表为空，默认录制房间中所有流。

Array[

StreamId string必填

待录制的流 ID。

]

FillBlank boolean

默认值: false

流中断时是否自动补白，默认为 false，即不补白。

true：用户推流中断时会自动补白，根据录制模式不同，自动补白的效果不同。
- 单流录制：只对音频进行补白。
  
  说明
  
  若推流端仅推视频流，或录制媒体流类型为仅录制视频，则无法补白。
  
  中断过程中，服务端将为音频补充静音帧，直到使用同样的流 ID 重新在房间内推流。最终，同一份录制文件会保留正常推流内容和静音帧。
- 混流录制：中断过程中，视频将停留在最后一帧（默认）或显示流画面背景图。此外，若混流中没有音频内容了，服务端将补充静音帧，直到使用同样的流 ID 重新在房间内推流。最终，同一份录制文件会保留正常推流内容、补白画面和静音帧（如有）。如果需要使用流画面背景图作为补白，请参考 DefaultMixStreamBackgroundImage 和 BackgroundImage 参数说明。仅当进行混流录制时（即 RecordMode 取值为 2），设置流画面背景图才会生效。
false：用户推流中断时不会补白。单流录制模式下，用户下次重推会生成新的录制文件。混流录制模式下，只有一个录制文件并且用户下次重推不会生成新的录制文件。

中断补白的时机有两种可能：

房间无流时长超时导致自动停止云录制，见 MaxIdleTime 的定义。
主动停止云录制。

FillFrame object

关闭摄像头后（音频持续在推）填充画面的方式，仅适用于混流录制。

FrameFillMode integer

可选值: [1, 2, 3]

默认值: 1

画面填充模式。

1：填充最后一帧（默认值）
2：填充指定颜色
3：不填充帧

注意

FrameFillMode 相关：

小程序端仅支持填充最后一帧，不支持填充指定颜色或不填充帧。

web 端仅支持填充黑色，不支持填充最后一帧或填充其它颜色或不填充帧。

FrameFillColor int32

FrameFillMode 设置为 2 时有效，用于指定填充颜色，默认为黑色。前三个字节为 RGB 颜色值，第四个字节固定为 0，即 0xRRGGBB00。

RecordMuteAudio integer

可选值: [1, 2]

默认值: 1

指定是否录制静音状态下的音频帧数据，仅当单流录制、只录制音频且输出文件格式为 mp3 时生效。

1：录制静音状态下的音频帧（默认值）
2：不录制静音状态下的音频帧

RecordMuteAudioSplitThreshold integer

录制文件自动分片的静音时长阈值，单位：秒。

录制过程中如果静音状态时长大于等于该阈值，则该段静音前后会生成为不同的录制文件。

仅当单流录制、只录制音频、输出文件格式为 mp3 且 RecordMuteAudio 为 2 时生效。

指定为 0 时遇静音即分片，不指定或者指定为负数时表示不分片。

HasWhiteboard boolean

默认值: false

是否录制白板。

true：录制白板
false：不录制白板（默认值）

本参数为 true 时 Whiteboard 参数必选。

Whiteboard object[]

白板参数，HasWhiteboard 为 true 时必选。

Array[

HorizontalRatio integer必填

原始白板的宽高比（宽）。

VerticalRatio integer必填

原始白板的宽高比（高）。

Width integer

默认值: 1280

单流录制白板输出视频的分辨率宽，默认值为 1280。

Height integer

默认值: 720

单流录制白板输出视频的分辨率高，默认值为 720。

WhiteboardId string

录制白板的 ID。

如果希望开始录制后立刻录制白板，必须指定白板 ID。
如果希望开始录制后先不录制白板，可不携带该参数，待需要录制白板时调用更新白板接口指定白板 ID。

BackgroundColor int32

白板背景颜色，默认为白色。前三个字节为 RGB 颜色值，第四个字节固定为 0，即 0xRRGGBB00。

IsPPTAnimation boolean

默认值: false

是否录制动态 PPT，默认为 false。

true：录制动态 PPT，支持录制 PPT 中的动画效果、视频。
false：不录制动态 PPT，PPT 中的动画效果、视频不会被录制下来。

注意

使用录制动态 PPT 功能前，请联系 ZEGO 商务人员付费开通。否则，设置 IsPPTAnimation 和 PPTAnimationFps 参数无效。

PPTAnimationFps integer

可选值: >= 1 and <= 30

默认值: 15

录制动态 PPT 的帧率，默认值为 15，有效范围 [1,30]。

]

MaxIdleTime integer

可选值: >= 5 and <= 86400

默认值: 30

房间内没有任何流、白板之后多长时间自动停止云录制，单位：秒。默认值为 30 秒，该值需大于等于 5，且小于等于 86400（24 小时）。

注意

该参数仅当房间内无流、无白板时生效。

MaxRecordTime integer

可选值: >= 300 and <= 86400

默认值: 86400

录制任务最大时长，录制持续时间达到该值自动结束。单位：秒。默认值 86400 秒（24 小时），该值需大于等于 300，且小于等于 86400（24 小时）。

说明

最大录制时长限制支持上调为 48 小时。如需调整最大录制时长，请联系 ZEGO 技术支持。

ResumeWithoutInterruption boolean

默认值: false

单流录制在推流端中断时，是否进行断点续录，默认值为 false。

该参数只针对单流录制有效。

设置为 true 时，用户推流中断恢复后，会在同一份录制文件中继续录制，且不包含中断的时长。

最终，一个流 ID 只有同一份录制文件。

RecordAudioWithSideInfo boolean

默认值: false

单流录制时，是否包含 SEI 信息。

该参数只针对单流录制生效。纯音频推流 SEI 场景，录制音视频文件时，设置为 true，生成的音视频文件中会包含 SEI 信息。

MixConfig object

混流参数，RecordMode 为 2 时必选。

MixMode integer

可选值: [1, 2, 3, 4, 5]

默认值: 2

布局方式。

1：自定义布局，必须指定 MixInputList
2：（默认）平分布局
3：水平布局
4：垂直布局
5：悬浮布局

MixInputList object[]

自定义布局参数。

Array[

StreamId string

指定在该画面中录制的流的 ID。

如果未指定，会按照流加入房间的时间顺序进行录制。

ViewType integer

可选值: [1, 2]

默认值: 1

该画面显示内容的类型。

1：音视频（默认值）
2：白板

类型 2 仅在开启白板录制时有效，仅支持将一个画面设置为白板，超过两个及以上会返回错误。

Top integer必填

可选值: >= 0 and <= 1920

画布上该画面左上角的 y 轴坐标，取值范围 [0, 1920]。

Left integer必填

可选值: >= 0 and <= 1920

画布上该画面左上角的 x 轴坐标，取值范围 [0, 1920]。

Bottom integer必填

可选值: >= 0 and <= 1920

画布上该画面右下角的 y 轴坐标，取值范围 [0, 1920]。

Right integer必填

可选值: >= 0 and <= 1920

画布上该画面右下角的 x 轴坐标，取值范围 [0, 1920]。

Layer integer必填

该画面的图层优先级，当两个画面发生重叠时，数值大的显示在上方。

FillMode integer

可选值: [1, 2]

默认值: 1

实际视频流宽高比与画面不一致时的处理方式。

1：裁剪模式，该模式下优先保证画面被填满，原视频等比缩放填满画面后，四周超出画面的内容会被裁剪。（默认值）
2：缩放模式，该模式下优先保证原视频的完整性，原视频等比缩放填满画面后，四周会补一圈黑边。

BackgroundImage string

流画面背景图的 URL 地址，仅当指定了 StreamId 参数时生效。自定义布局指定的流不存在或者流中断时会显示该背景图。

建议背景图的大小和设置的流的画面大小一致，若两者不一致，背景图会被拉伸或压缩以填满整个画面。
背景图格式支持 JPG 和 PNG，大小不能超过 5MB，如背景图下载失败，则设置不生效。
URL 支持 HTTP 和 HTTPS 协议。

]

FillMode integer

可选值: [1, 2]

默认值: 1

(适用于 MixConfig 中的 MixMode 不为 1，即不是自定义布局时)

实际视频流宽高比与画面不一致时的处理方式。

1：裁剪模式，该模式下优先保证画面被填满，原视频等比缩放填满画面后，四周超出画面的内容会被裁剪。（默认值）
2：缩放模式，该模式下优先保证原视频的完整性，原视频等比缩放填满画面后，四周会补一圈黑边。

说明

如需了解适用于自定义布局的 FillMode，请参考 mixinputlist.FillMode。

MixOutputStreamId string必填

指定混流输出的流 ID，将作为 OutputFileRule 中的一部分。

MixOutputVideoConfig object

输出视频参数；StreamType 为 2、3、4 时，此参数必选。

Width integer必填

可选值: <= 1920

输出视频的分辨率宽，单位为像素。

Width 取值小于或等于 1920，且 Width 和 Height 的乘积不能超过 1920 * 1080，否则会报错。

Height integer必填

可选值: <= 1920

输出视频的分辨率高，单位为像素。

Height 取值小于或等于 1920，且 Width 和 Height 的乘积不能超过 1920 * 1080，否则会报错。

Fps integer必填

可选值: >= 5 and <= 30

默认值: 15

输出视频的帧率，默认 15，有效范围 [5,30]。

Bitrate integer必填

输出视频的码率，单位：bps。例如要设置码率为 1.5 Mbps 时，需要设置此参数为 1500*1000，也就是 1500000。

MixOutputAudioConfig object

Bitrate integer

默认值: 48000

音频码率，默认值为 48000 bps。

MixOutputBackgroundColor int32

录制背景颜色，默认为黑色。前三个字节为 RGB 颜色值，第四个字节固定为 0，即 0xRRGGBB00。

MixOutputBackgroundImage string

视频画布背景图的 URL 地址。

建议背景图的分辨率与输出视频分辨率一致，如两者分辨率不一致，背景图会被拉伸或压缩以填满整个画面。
背景图格式支持 JPG 和 PNG，大小不能超过 5MB，如背景图下载失败，则设置不生效。
URL 支持 HTTP 和 HTTPS 协议。

MixMaxResolutionStreamId string

MixMode 设为 3、4、5 时，用于指定显示大画面的流 ID。

MixOutputWatermarkImage string

水印图片的 URL 地址。

建议水印图片的大小和设置的水印布局大小一致，若两者不一致，水印图片会被拉伸以填满水印布局的位置。
水印图片格式支持 JPG 和 PNG，大小不能超过 5MB，如水印图片下载失败，则设置不生效。
URL 支持 HTTP 和 HTTPS 协议。

MixOutputWatermarkImageConfig object

水印布局配置。

Left integer必填

可选值: >= 0 and <= 1920

画布上该水印左上角的 x 轴坐标，取值范围 [0, 1920]，不能超过 Right 的值和画布的宽。

Top integer必填

可选值: >= 0 and <= 1920

画布上该水印左上角的 y 轴坐标，取值范围 [0, 1920]，不能超过 Bottom 的值和画布的高。

Right integer必填

可选值: >= 0 and <= 1920

画布上该水印右下角的 x 轴坐标，取值范围 [0, 1920]，不能超过画布的宽。

Bottom integer必填

可选值: >= 0 and <= 1920

画布上该水印右下角的 y 轴坐标，取值范围 [0, 1920]，不能超过画布的高。

DefaultMixStreamBackgroundImage string

流画面默认背景图的 URL 地址，当 FillBlank 参数为 true 且 FrameFillMode = 3 时，指定流不存在或者流中断，且录制模式为混流录制时，会显示该背景图。

自定义布局时，若对指定流 ID 设置了 BackgroundImage 参数，则优先显示 BackgroundImage。
建议背景图的大小和设置的流的画面大小一致，若两者不一致，背景图会被拉伸或压缩以填满整个画面。
背景图格式支持 JPG 和 PNG，大小不能超过 5MB，如背景图下载失败，则设置不生效。
URL 支持 HTTP 和 HTTPS 协议。

IsAlwaysMix boolean

默认值: false

录制任务启动后，是否立即开始录制。默认为 false，表示房间内进行推流后，开始录制。

true：录制任务启动后，立即开始录制。
false：录制任务启动后，等房间内进行推流后，开始录制。

MixOutputWatermarkTimestampConfig object

时间水印配置。配置后，时间水印显示在视频右上角，格式为 yyyy-MM-dd HH

。

FontSize integer必填

可选值: >= 12 and <= 100

字体大小，取值范围 [12, 100]，单位 px。

RecordSoundWave boolean

默认值: false

录制任务启动后，是否记录音浪信息。默认为 false。

true：录制任务启动后，每间隔 1 秒记录当前所有流的音浪信息。
false：录制任务启动后，不记录音浪信息。

音浪信息会以 JSON 格式写入到一个独立的文件中，文件名称与录制文件名称一致，后缀为.sw，在录制任务结束后，和录制文件一起上传到指定的云存储位置。

SoundWaveType integer

可选值: [0, 1]

默认值: 0

音浪信息类型。仅当 RecordSoundWave 为 true 时，此参数生效。

0：记录流 ID 信息（默认值）。示例：{"time":10, "sound_wave":[{"stream_id":"s1", "volume":0}]}
1：记录用户 ID 信息。示例：{"time":10, "sound_wave":[{"user_id":"u1", "volume":0}]}

StreamConfigList object[]

自定义流参数。

Array[

StreamId string

流 ID。如果 StreamId 为空，表示设置参数的默认值，其他没有在 StreamConfigList 中出现的流会使用参数默认值。

StreamType integer

可选值: [0, 1, 2, 3]

流录制类型，仅在 RecordInputParams 中的 StreamType 等于 3 或 4 生效。

0：默认类型
1：音频
2：视频
3：音视频

]

ClearInputStreamTimeout integer

等待输入流的超时时间，单位为毫秒。在此期间，ZEGO 服务端等待获取输入流后才开始混流。若超时仍未收到输入流，混流将自动开始。

RecordOutputParams object

录制任务输出参数。

OutputFileFormat string

可选值: [mp4, flv, hls, jpg, aac, mp3, ogg]

默认值: mp4

指定录制生成文件的格式，默认为 "mp4"。目前支持 "mp4"、"flv"、"hls"、"jpg"、"aac"、"mp3" 和 "ogg"。

说明

如果录制 "mp4" 或 "flv"，且 StreamType 设为 4，则录制生成的音频文件格式为 "aac"。

如果单流录制时，原音频流为 "opus" 格式且输出参数选定为 "ogg"，将会按照输入音频流的码率、采样率进行录制。

当推流为 VP8 编码且录制生成文件选择 "mp4" 格式时，需要联系 ZEGO 技术支持进行配置。

OutputFolder string

录制文件在第三方云存储的输出目录，默认为根目录。

OutputFileRule integer

可选值: [1]

默认值: 1

录制文件命名规则。

说明

目前仅支持 "1" 作为唯一命名格式，暂不支持自定义的命名格式。

默认值为 1，表示命名格式为：

TaskId_RoomId_UserId_StreamId_Type_UTC（单流录制）
Taskid_RoomId_MixOutputStreamId_Type_UTC（混流录制）
Taskid_Roomid_whiteboard_Type_UTC（单流录制带白板）

文件名中的字段含义如下：

Type：文件类型，V 表示视频文件，A 表示音频文件，VA 表示音视频文件。
UTC：该文件开始录制时的 UTC 时间，时区为 UTC+0，由年、月、日、小时、分钟、秒和毫秒组成。
MixOutputStreamId：在 MixConfig 中指定。
whiteboard：固定，不可修改。

SnapshotInterval integer

可选值: >= 5 and <= 3600

默认值: 10

截图周期，单位：秒。录制文件格式为 "jpg" 时有效，取值范围是 [5, 3600]，默认值 10。

CallbackUrl string

自定义回调地址的 URL，不填写此参数时会使用服务开通时配置的回调地址。URL 支持 HTTP 和 HTTPS 协议。

FragmentSeconds integer

可选值: >= 2 and <= 60

默认值: 15

分片时长，单位：秒，取值范围是 [2, 60]，默认值 15。

注意：仅当 OutputFileFormat 为 "hls" 时，此参数生效。

RealtimeUploadFragment boolean

是否在录制时实时上传分片。

注意：仅当 OutputFileFormat 为 "hls" 时，此参数生效。

ShortFragmentPath boolean

M3U8 文件是否只保存视频分片文件（如 .ts 文件）的文件名，而非视频分片的路径。

注意：仅当 RealtimeUploadFragment 为 "true" 时生效。

StorageParams objectrequired

说明
各个属性参数的填写方法请参考 StorageParams 中的各个云存储相关的参数如何填写？

Vendor integer必填

可选值: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

录制文件存储服务提供商，目前支持的存储服务提供商如下：

1：亚马逊 S3
2：阿里云 OSS
3：腾讯云 COS
4：七牛云 Kodo
5：阿里云 Vod
6：腾讯云 Vod
7：华为云 OBS
8：谷歌云 Cloud Storage
9：移动云 EOS
10：使用 S3 协议的存储服务提供商，需要填写 StorageParams 属性参数 EndPoint。

注意

Vendor 设置为 1、2、3、4、7、9 时，Region，Bucket，AccessKeyId，AccessKeySecret 必选。

Vendor 设置为 5 时，AlibabaCloudVodParams 必选。目前仅支持上传 MP4、FLV 格式文件。

Vendor 设置为 6 时，TencentCloudVodParams 必选。目前仅支持上传 MP4、FLV、JPG、MP3 格式文件。

Vendor 设置为 8 时，Bucket，AccessKeyId，AccessKeySecret 必选。

Vendor 设置为 10 时，Region，Bucket，AccessKeyId，AccessKeySecret，EndPoint 必选。

Region string

云存储指定的地区信息。

Bucket string

云存储 bucket。

AccessKeyId string

云存储的 access key，建议提供只写权限的访问密钥。

AccessKeySecret string

云存储的 secret key。

AlibabaCloudVodParams object

Region string必填

阿里云 Vod 指定的地区信息。

AccessKeyId string必填

阿里云 Vod 的 access key。

AccessKeySecret string必填

阿里云 Vod 的 secret key，建议提供只写权限的访问密钥。

Title string必填

阿里云 Vod 视频名称。

StorageLocation string必填

阿里云 Vod 提供的固定参数。

TencentCloudVodParams object

SecretId string必填

腾讯云 Vod 的 access key。

SecretKey string必填

腾讯云 Vod 的 secret key，建议提供只写权限的访问密钥。

Region string必填

腾讯云 Vod 指定的地区信息。

SubAppId int64

腾讯云 Vod 的子应用 ID。

EndPoint string

Vendor 为 10 时，填写使用 S3 协议的存储服务的地址。

S3ForcePathStyle boolean

Vendor 为 10 时，使用 S3 协议上传是否强制使用路径样式定位存储桶。默认为 false。

Responses

application/json

数据结构
按数据结构生成的示例

Schema

Code int64

错误码。

Message string

错误描述。

RequestId string

请求 ID。

Data object

TaskId string

云录制服务分配的任务 ID，长度固定为 16 个字节的字符串。任务 ID 是对一次录制生命周期过程的唯一标识，结束录制时会失去意义。

{
  "Code": 0,
  "Message": "succeed",
  "RequestId": "abcd123",
  "Data": {
    "TaskId": "XXXXXXXXXXXX"
  }
}

{
  "Code": 0,
  "Message": "succeed",
  "RequestId": "abcd123",
  "Data": {
    "TaskId": "XXXXXXXXXXXX"
  }
}

StartRecord

https://cloudrecord-api.zego.im/

Request

Query Parameters

Body

Responses​

Responses