文档中心
云端录制旧版文档
API 文档
开始录制

开始录制

更新时间：2022-03-14 18:27

1 描述

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

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

每个录制任务时间最长为 24 小时。超过 24 小时，录制任务将自动停止录制。

2 接口原型

请求方式：POST/JSON

请求地址：

服务环境	调用频率限制	请求地址
国内正式环境	50 次/秒	https://cloudrecord-sh.zego.im/start
国内测试环境	50 次/秒	https://cloudrecord-test.zego.im/start
海外正式环境	50 次/秒	https://cloudrecord-hk.zegocloud.com/start
海外测试环境	50 次/秒	https://cloudrecord-test.zegocloud.com/start

传输协议：HTTPS

3 请求参数

参数	类型	是否必选	描述
app_id	Int64	是	ZEGO 给开发者分配的 AppID，唯一标识一个应用。
access_token	String	是	接口鉴权凭证，通过获取 AccessToken 接口获取。
room_id	String	是	待录制的房间 ID。
record_input_params	Object	是	录制任务输入参数。详见 record_input_params 成员列表。
record_output_params	Object	否	录制任务输出参数。详见 record_output_params 成员列表。
storage_params	Object	是	录制任务的存储配置。详见 storage_params 成员列表。若未指定该项配置，则使用开启云端录制服务时设置的存储配置。

record_input_params 成员如下：

参数	类型	是否必选	描述
record_mode	Int	是	录制模式。 1：单流录制 2：混流录制
stream_type	Int	否	录制媒体流类型，仅适用于音视频流，白板只会录制视频。 1：仅录制音频 2：仅录制视频 3：录制音视频（音视频文件合并）（默认值） 4：录制音视频（音频视频文件分离）
record_stream_list	Array of Object	否	仅适用于单流录制模式，指定要录制的流信息列表。详见 record_stream_list 成员列表。若未指定该字段或该列表为空，默认录制房间中所有流。
fill_blank	Bool	否	流中断时是否自动补白，默认为 false，即不补白。 true：用户推流中断时会自动补白，中断过程中视频停留在最后一帧（默认）或显示流画面背景图，用同样的流 ID 重推，录制将恢复正常，写入同一个录制文件中。 false：用户推流中断时不会补白，该用户下次重推生成新的录制文件。中断补白的时机有两种可能：房间无流时长超时导致自动停止云录制，见 max_idle_time 的定义。主动停止云录制。流画面背景图的说明请参见 default_mix_stream_background_image 和 background_image。
fill_frame	Object	否	关闭摄像头后（音频持续在推）填充画面的方式，仅适用于混流录制。详见 fill_frame 成员列表。
record_mute_audio	Int	否	指定是否录制静音状态下的音频帧数据，仅当单流录制、只录制音频且输出文件格式为 mp3。 1：录制静音状态下的音频帧（默认值） 2：不录制静音状态下的音频帧
record_mute_audio_split_threshold	Int	否	录制文件自动分片的静音时长阈值，单位：秒。录制过程中如果静音状态时长大于等于该阈值，则该段静音前后会生成为不同的录制文件。仅当单流录制、只录制音频、输出文件格式为 mp3 且 record_mute_audio 为 2 时生效。指定为 0 时遇静音即分片，不指定或者指定为负数时表示不分片。
has_whiteboard	Bool	否	是否录制白板。 true：录制白板 false：不录制白板（默认值）本参数为 true 时`whiteboard` 参数必选。
whiteboard	Array of Object	否	白板参数，`has_whiteboard` 为 true 时必选。详见 whiteboard 成员列表。
max_idle_time	Int	否	房间内没有任何流、白板之后多长时间自动停止云录制，单位：秒。默认值为 30 秒，该值需大于等于 5，且小于等于 4294967295。注意：该参数仅当房间内无流、无白板时生效。
max_record_time	Int	否	录制任务最大时长，录制持续时间达到该值自动结束。单位：秒。默认值 86400 秒（24 小时），该值需大于等于 300，且小于等于 86400（24 小时）。
mix_config	Object	否	混流参数，`record_mode` 为 2 时必选。详见 mix_config 成员列表。

fill_blank 和 max_idle_time 作用对象不同：

fill_blank：作用于流本身，只要录制任务还在进行，fill_blank设置为 true 后，若流处于中断状态，则会继续以补白的方式录制，此时该流仍然为中断状态，不影响房间内有无流的判断。
max_idle_time：作用于整个录制任务状态，当房间内无流时长超过 max_idle_time 时，则会中止整个录制任务。

混流录制模式下，若 stream_type 为 1，表示仅录制音频，此时无法录制白板。

record_stream_list 成员如下：

参数	类型	是否必选	描述
stream_id	String	是	待录制的流 ID。

fill_frame 成员如下：

参数	类型	是否必选	描述
frame_fill_mode	Int	否	画面填充模式。 1：填充最后一帧（默认值） 2：填充指定颜色 3：不填充帧
frame_fill_color	Int	否	`frame_fill_mode` 设置为 2 时有效，用于指定填充颜色，默认为黑色。前三个字节为 RGB 颜色值，第四个字节固定为 0，即 0xRRGGBB00。

frame_fill_mode 相关：

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

whiteboard 成员如下：

参数	类型	是否必选	描述
horizontal_ratio	Int	是	原始白板的宽高比（宽）。
vertical_ratio	Int	是	原始白板的宽高比（高）。
width	Int	否	单流录制白板输出视频的分辨率宽，默认值为 1280。
height	Int	否	单流录制白板输出视频的分辨率高，默认值为 720。
whiteboard_id	String	否	录制白板的 ID。如果希望开始录制后立刻录制白板，必须指定白板 ID。如果希望开始录制后先不录制白板，可不携带该参数，待需要录制白板时调用更新白板接口指定白板 ID。
is_ppt_animation	Bool	否	是否录制动态 PPT，默认为 false。 true：录制动态 PPT，支持录制 PPT 中的动画效果、视频。 false：不录制动态 PPT，PPT 中的动画效果、视频不会被录制下来。
ppt_animation_fps	Int	否	录制动态 PPT 的帧率，默认值为 15，有效范围 [1,30]。

录制动态 PPT 功能需单独收费，需开通请先联系 ZEGO 商务人员。若未开通，直接设置 is_ppt_animation 和 ppt_animation_fps 参数属于无效设置。

mix_config 成员如下：

参数	类型	是否必选	描述
mix_mode	Int	否	布局方式。 1：自定义布局，必须指定 mix_input_list 2：（默认）平分布局 3：水平布局 4：垂直布局 5：悬浮布局
mix_input_list	Array of Object	否	自定义布局参数。详见 mix_input_list 成员列表。
mix_output_stream_id	String	是	指定混流输出的流 ID，将作为 output_file_rule 中的一部分。
mix_output_video_config	Object	是	输出视频参数。详见 mix_output_video_config 成员列表。
mix_output_audio_config	Object	否	输出音频参数。详见 mix_output_audio_config 成员列表。
mix_output_background_color	Int	否	录制背景颜色，默认为黑色。前三个字节为 RGB 颜色值，第四个字节固定为 0，即 0xRRGGBB00。
mix_output_background_image	String	否	视频画布背景图的 URL 地址。建议背景图的分辨率与输出视频分辨率一致，如两者分辨率不一致，背景图会被拉伸或压缩以填满整个画面。背景图格式支持 JPG 和 PNG，大小不能超过 5MB，如背景图下载失败，则设置不生效。 URL 支持 HTTP 和 HTTPS 协议。
mix_max_resolution_stream_id	String	否	`mix_mode` 设为 3、4、5 时，用于指定显示大画面的流 ID。
mix_output_watermark_image	String	否	水印图片的 URL 地址。建议水印图的分辨率与输出视频分辨率一致，如两者分辨率不一致，水印图片会被拉伸或压缩以填满整个画面。水印图格式支持 PNG，背景必须透明，否则会遮挡录制画面；大小不能超过 5MB，如水印图下载失败，则设置不生效。 URL 支持 HTTP 和 HTTPS 协议。
default_mix_stream_background_image	String	否	流画面默认背景图的 URL 地址，当 fill_blank 为 true 时，指定流不存在或者流中断时会显示该背景图。若对指定流 ID 设置了 background_image，则优先显示 background_image。如背景图的分辨率和流画面的分辨率不一致，背景图会被拉伸或压缩以填满整个画面。背景图格式支持 JPG 和 PNG，大小不能超过 5MB，如背景图下载失败，则设置不生效。 URL 支持 HTTP 和 HTTPS 协议。

mix_input_list 成员如下：

参数	类型	是否必选	描述
stream_id	String	否	指定在该画面显示的 streamID，如果未指定，会按照流加入房间的时间顺序进行匹配。
view_type	Int	否	该画面显示内容的类型。 1：音视频（默认值） 2：白板类型 2 仅在开启白板录制时有效，仅支持将一个画面设置为白板，超过两个及以上会返回错误。
top	Int	是	画布上该画面左上角的 y 轴坐标，取值范围 [0, 1920]，不能超过 bottom 的值和画布的高。
left	Int	是	画布上该画面左上角的 x 轴坐标，取值范围 [0, 1920]，不能超过 right 的值和画布的宽。
bottom	Int	是	画布上该画面右下角的 y 轴坐标，取值范围 [0, 1920]，不能超过画布的高。
right	Int	是	画布上该画面右下角的 x 轴坐标，取值范围 [0, 1920]，不能超过画布的宽。
layer	Int	是	该画面的图层优先级，当两个画面发生重叠时，数值大的显示在上方。
fill_mode	Int	否	实际视频流宽高比与画面不一致时的处理方式。 1：裁剪模式，该模式下优先保证画面被填满，原视频等比缩放填满画面后，四周超出画面的内容会被裁剪。（默认值） 2：缩放模式，该模式下优先保证原视频的完整性，原视频等比缩放填满画面后，四周会补一圈黑边。
background_image	String	否	流画面背景图的 URL 地址，仅当指定了 stream_id 时生效。自定义布局指定的流不存在或者流中断时会显示该背景图。建议背景图的分辨率与流画面分辨率一致，如两者分辨率不一致，背景图会被拉伸或压缩以填满整个画面。背景图格式支持 JPG 和 PNG，大小不能超过 5MB，如背景图下载失败，则设置不生效。 URL 支持 HTTP 和 HTTPS 协议。

mix_output_video_config 成员如下：

参数	类型	是否必选	描述
width	Int	是	输出视频的分辨率宽，单位为像素。 width 取值小于或等于 1920，且 width 和 height 的乘积不能超过 1920 * 1080，否则会报错。
height	Int	是	输出视频的分辨率高，单位为像素。 height 取值小于或等于 1920，且 width 和 height 的乘积不能超过 1920 * 1080，否则会报错。
fps	Int	是	输出视频的帧率，默认 15，有效范围 [5,30]。
bitrate	Int	是	输出视频的码率，单位：bps。例如要设置码率为 1.5 Mbps 时，需要设置设置此参数为 1500*1000，也就是 1500000。

mix_output_audio_config 成员如下：

参数	类型	是否必选	描述
bitrate	Int	否	音频码率，默认值为 48000 bps。

record_output_params 成员如下：

参数	类型	是否必选	描述
output_file_format	String	否	指定录制生成文件的格式，默认为 “mp4”。目前支持 “mp4”、“flv”、“hls”、“jpg” 和 “mp3”。如果录制 “mp4” 或 “flv”，且 `stream_type` 设为 4，则录制生成的音频文件格式为 aac。
output_folder	String	否	录制文件在第三方云存储的输出目录，默认为根目录。
output_file_rule	Int	否	录制文件命名规则，默认值为 1，表示命名格式为： taskid_roomid_userid_streamid_type_utc（单流录制） taskid_roomid_mix_output_stream_id_type_utc（混流录制） taskid_roomid_whiteboard_type_utc（单流录制带白板）文件名中的字段含义如下： type：文件类型，V 表示视频文件，A 表示音频文件，VA 表示音视频文件。 utc：该文件开始录制时的 UTC 时间，时区为 UTC+0，由年、月、日、小时、分钟、秒和毫秒组成。 mix_output_stream_id：在 mix_config 中指定。 whiteboard：固定，不可修改。
snapshot_interval	Int	否	截图周期，单位：秒。录制文件格式为 “jpg” 时有效，取值范围是 [5, 3600]，默认值 10。
callback_url	String	否	自定义回调地址的 URL，不填写此参数时会使用服务开通时配置的回调地址。URL 支持 HTTP 和 HTTPS 协议。

storage_params 成员如下：

参数	类型	是否必选	描述
storage_provider	Int	是	录制文件存储服务提供商，目前支持的存储服务提供商如下： 1：亚马逊 S3 2：阿里云 OSS 3：腾讯云 COS 4：七牛云 Kodo 5：阿里云 Vod 6：腾讯云 Vod 7：华为云 OBS
region	String	否	云存储指定的地区信息，详见如下文档。亚马逊 S3：参考文档内 “Code” 字段阿里云 OSS：参考文档内 “Region ID” 字段腾讯云 COS：参考文档内 “地域简称” 字段七牛云 Kodo：参考文档内 “区域 Region ID” 字段华为云 OBS：参考文档内 “区域” 字段
bucket_name	String	否	云存储 bucket。
access_key_id	String	否	云存储的 access key，建议提供只写权限的访问密钥。
access_key_secret	String	否	云存储的 secret key。
aliyun_vod_params	Object	否	阿里云 Vod 存储信息。详见 aliyun_vod_params 成员列表。
tencentyun_vod_params	Object	否	腾讯云 Vod 存储信息。详见 tencentyun_vod_params 成员列表。

storage_provider设置为 1～4 还有 7 时，region，bucket_name，access_key_id，access_key_secret 必选。
storage_provider设置为 5 时，aliyun_vod_params 必选。目前仅支持上传 MP4、FLV 格式文件。
storage_provider设置为 6 时，tencentyun_vod_params 必选。目前仅支持上传 MP4、FLV 格式文件。

aliyun_vod_params 成员如下：

参数	类型	是否必选	描述
region	String	是	阿里云 Vod 指定的地区信息，例如 cn-shanghai。
access_key	String	是	阿里云 Vod 的 access key。
secret_key	String	是	阿里云 Vod 的 secret key，建议提供只写权限的访问密钥。
title	String	是	阿里云 Vod 视频名称。
storage_location	String	是	阿里云 Vod 提供的固定参数。

tencentyun_vod_params 成员如下：

参数	类型	是否必选	描述
access_key_id	String	是	腾讯云 Vod 的 access key。
access_key_secret	String	是	腾讯云 Vod 的 secret key，建议提供只写权限的访问密钥。
region	String	是	腾讯云 Vod 指定的地区信息，例如 ap-shanghai。
sub_app_id	Int64	否	腾讯云 Vod 的子应用 ID。

4 请求示例

以下是使用亚马逊 S3、阿里云 OSS、腾讯云 COS、七牛云 Kodo、华为云 OBS 请求示例。

{
    "app_id": 0000,
    "access_token": "xxxx",
    "room_id": "xxxx",
    "record_input_params": {
        "record_mode": 1,
        "stream_type": 3,
        "max_idle_time": 60
    },
    "record_output_params": {
        "output_file_format": "mp4",
        "output_folder": "record/"
    },
    "storage_params": {
        "storage_provider": 2,
        "region": "oss-xxxx",
        "bucket_name": "xxxx",
        "access_key_id": "xxxx",
        "access_key_secret": "xxxx"
    }
}

以下是使用阿里云 Vod 请求示例。

{
    "app_id": 0000,
    "access_token": "xxxx",
    "room_id": "xxxx",
    "record_input_params": {
        "record_mode": 1,
        "stream_type": 3,
        "max_idle_time": 60
    },
    "record_output_params": {
        "output_file_format": "mp4",
        "output_folder": "record/"
    },
    "storage_params": {
        "storage_provider": 5,
        "region": "",
        "bucket_name": "",
        "access_key_id": "",
        "access_key_secret": "",
        "aliyun_vod_params":{
            "region": "cn-xxxxx",
            "access_key": "xxxx",
            "secret_key": "xxxx",
            "title": "xxxx",
            "storage_location": "xxxx.oss-cn-xxxx.aliyuncs.com",
            }
    }
}

5 响应参数

参数	类型	描述
code	Int	错误码。
message	String	错误描述。
task_id	String	云录制服务分配的任务 ID，长度固定为 16 个字节的字符串。任务 ID 是对一次录制生命周期过程的唯一标识，结束录制时会失去意义。

6 响应示例

以下是 start 接口的响应示例。

{
    "code": 0,
    "message": "succeed",
    "task_id": "XXXXXXXXXXXX"
}