Documentation
Cloud Recording
API Documents
Start Recording

Start recording

Last updated：2024-01-22 19:18

Description

Starts cloud recording.

After you successfully call the StartRecord method, the Cloud Recording will record the audio and video streams and whiteboards in the room based on the specified recording parameters.

Each recording task may last up to 24 hours. When the recording duration reaches the maximum, the recording task automatically ends.
ZEGOCLOUD recommends that each of your recording tasks call the Stop recording method to stop recording to avoid additional costs for continued recording.

Request method and endpoint

Request method: POST
Request endpoint: https://cloudrecord-api.zego.im/?Action=StartRecord
Transmission protocol: HTTPS
Rate limit: 50 requests/second (testing environment: 20 requests/second)

Request parameters

Listed below are the parameters specific to this request. For the list of public request parameters, see Accessing Server APIs - Public parameters.

Parameter	Type	Required	Description
RoomId	String	Yes	Room ID.
RecordInputParams	Object	Yes	Recording task input parameters. For details, see RecordInputParams member parameters.
RecordOutputParams	Object	No	Recording task output parameters. For details, see RecordOutputParams member parameters.
StorageParams	Object	Yes	Recording task storage parameters. For details, see StorageParams member parameters.

Listed below are RecordInputParams member parameters.

Parameter	Type	Required	Description
RecordMode	Int	Yes	Recording mode. 1: single-stream recording 2: mixed-stream recording
StreamType	Int	No	Recording type of a media stream. This parameter is valid only for audio or video streams. For whiteboards, only video files will be recorded. 1: only audio files 2: only video files 3 (default value): combined audio and video files 4: separate audio and video files
RecordStreamList	Array of Object	No	List of streams to be recorded. This parameter is valid only in single-stream recording mode. For details, see RecordStreamList member parameters. If the parameter is not specified or set to an empty list, all streams in the room will be recorded by default.
FillBlank	Bool	No	Whether to automatically perform supplementary recording of blank screens after the streaming of a user is interrupted. true: yes. Upon interruption, the video recording pauses at the last frame (by default) or the background image of the stream is displayed. When the user resumes the streaming with the same stream ID, the recording resumes and data will be written into the same recording files. false (default value): no. When the user resumes the streaming, a new recording file is generated. There are two possible occasions for supplementary recording of blank screens: Cloud recording automatically stops when the duration of no stream in the room reaches the maximum. For details, see `MaxIdleTime`. The user proactively stops cloud recording. For details about the background images of streams, see DefaultMixStreamBackgroundImage and BackgroundImage.
FillFrame	Object	No	Settings for filling in screens after the camera is turned off while the audio streaming continues. This parameter is valid only in mixed-stream recording mode. For details, see FillFrame member parameters.
RecordMuteAudio	Int	No	Whether to record audio frames in mute mode. This parameter is valid only in the following scenarios: a single stream is recorded; only audio files are recorded and they are stored in MP3 format. 1 (default value): yes 2: no
RecordMuteAudioSplitThreshold	Int	No	Mute time threshold for automatically split recording files, in seconds. When the mute duration of a stream reaches this threshold during the recording, a new recording file will be generated. This parameter is valid only in the following scenarios: a single stream is recorded; only audio files are recorded; the recording file is stored in MP3 mode and `RecordMuteAudio` is set to `2`. If this parameter is set to 0, a separate recording file is generated immediately when a stream is muted. If this parameter is set to 0 or a negative value, the recording file will not be split.
HasWhiteboard	Bool	No	Whether to record a whiteboard. true: yes false (default value): no If this parameter is set to `true`, the `Whiteboard` parameter is required.
Whiteboard	Array of Object	No	Whiteboard parameter, which is required when `HasWhiteboard` is set to `true`. For details, see Whiteboard member parameters.
MaxIdleTime	Int	No	Maximum duration with no stream or whiteboard after which cloud recording automatically stops, in seconds. The default value is `30`. The value must be greater or equal to 5, and less than or equal to 86400 (24 hours). Note: This parameter is valid only when there is no stream or whiteboard in the room.
MaxRecordTime	Int	No	Maximum duration of a recording task. Recording automatically stops when the duration reaches the maximum, in seconds. The default value is `86400`. The value must be greater or equal to 300 and less than or equal to 86400 (24 hours).
MixConfig	Object	No	Mixed-stream settings. This parameter is required when `RecordMode` is set to `2`. For details, see MixConfig member parameters.

FillBlank and MaxIdleTime have different application scopes.

FillBlank: applies to the stream. Assume that FillBlank is set to true. When the streaming is interrupted, the system supplements blank screens as long as the recording task is still ongoing. In this case, the interrupted streaming status will not affect the judgment of whether there is a stream in the room.
MaxIdleTime: applies to the recording task. When the duration with no stream in a room exceeds the maximum specified by MaxIdleTime, the recording task ends.

In mixed-stream recording mode, when StreamType is 1, only audio files are recorded and the whiteboards are not.

Listed below are RecordStreamList member parameters.

Parameter	Type	Required	Description
StreamId	String	Yes	ID of a stream to be recorded.

Listed below are FillFrame member parameters.

Parameter	Type	Required	Description
FrameFillMode	Int	No	Screen filling mode. 1 (default value): Fill in the last frame. 2: Fill in a frame of the specified color. 3: Do not fill in any frame.
FrameFillColor	Int	No	Color of the frame to be filled in. This parameter is valid only when `FrameFillMode` is set to `2`. The default color is black. The first three bytes specify the RGB color code and the fourth byte is fixed at 0, that is, 0xRRGGBB00.

Pay attention to the following information about FrameFillMode:

For the mini program client, this parameter can only be set to 1.
For the web client, this parameter can only be set to 2 and the color of the frame to be filled in can only be black.

Listed below are Whiteboard member parameters.

Parameter	Type	Required	Description
HorizontalRatio	Int	Yes	Width of the original whiteboard.
VerticalRatio	Int	Yes	Height of the original whiteboard.
Width	Int	No	Resolution width of the output whiteboard video in single-recording mode. The default value is `1280`.
Height	Int	No	Resolution height of the output whiteboard video in single-recording mode. The default value is `720`.
WhiteboardId	String	No	Whiteboard ID. If a whiteboard must be recorded immediately after the start of recording, this parameter is required. If no whiteboard needs to be recorded immediately after the start of recording, this parameter is not required and the whiteboard ID can be specified later when necessary by calling the Update the whiteboard method.
BackgroundColor	Int	No	Whiteboard background color, default is white. The first three bytes represent the RGB color value, and the fourth byte is fixed as 0, i.e. 0xRRGGBB00.
IsPPTAnimation	Bool	No	Whether to record dynamic PowerPoint presentations, default is false. true：Recording of dynamic PowerPoint presentations, supports recording of animation effects and videos in PPT. false：Do not record dynamic PowerPoint presentations, animation effects and videos in PPT will not be recorded.
PPTAnimationFps	Int	No	The frame rate for recording dynamic PowerPoint presentations, default is 15, valid range is [1,30].

Listed below are MixConfig member parameters.

Parameter	Type	Required	Description
MixMode	Int	No	Layout. 1: customized layout. In this layout, `MixInputList` is required. 2 (default value): grid layout 3: horizontal layout 4: vertical layout 5: floating layout
MixInputList	Array of Object	No	Customized layout parameters. For details, see MixInputList member parameters.
MixOutputStreamId	String	Yes	Stream ID in mixed-stream recording mode, which will be used as a part of `OutputFileRule`.
MixOutputVideoConfig	Object	No	Output video parameters. When `StreamType` is `2`, `3`, or `4`, this parameter is required. For details, see MixOutputVideoConfig member parameters.
MixOutputAudioConfig	Object	No	Output audio parameters. For details, see MixOutputAudioConfig member parameters.
MixOutputBackgroundColor	Int	No	Recording background color, which is black by default. The first three bytes specify the RGB color code and the fourth byte is fixed at `0`, that is, 0xRRGGBB00.
MixOutputBackgroundImage	String	No	URL of the background image of a video canvas. We recommend that the resolution of the background image be the same as the output video resolution. If the resolutions are different, the background image will be stretched or compressed to fully fill in the screen. The background image can be in JPG or PNG format. The maximum image size is 5 MB. If the background image download fails, the setting will be invalid. HTTP and HTTPS URLs are supported.
MixMaxResolutionStreamId	String	No	Stream ID of the large screen when `MixMode` is set to `3`, `4`, or `5`.
MixOutputWatermarkImage	String	No	URL of the watermark image. We recommend that the resolution of the watermark image be the same as the output video resolution. If the resolutions are different, the watermark image will be stretched or compressed to fully fill in the screen. The watermark image can be in PNG format and the background must be transparent. Otherwise, the screens to be recorded will be blocked. The maximum image size is 5 MB. If the background image download fails, the setting will be invalid. HTTP and HTTPS URLs are supported.
MixOutputWatermarkImageConfig	Object	No	Watermark layout configuration. See MixOutputWatermarkImageConfig member list.
DefaultMixStreamBackgroundImage	String	No	URL of the default background image of a stream. Assume that FillBlank is `true`. When the specified stream does not exist or the streaming is interrupted, the background image specified by this parameter is displayed. For a customized layout, if BackgroundImage is specified for a stream ID, the specified background image is displayed preferentially. If the resolution of the background image is different from that of the stream images, the background image will be stretched or compressed to fill in the screen. The background image can be in JPG or PNG format. The maximum image size is 5 MB. If the background image download fails, the setting will be invalid. HTTP and HTTPS URLs are supported.
IsAlwaysMix	Bool	No	Whether to start recording immediately after the start of the recording task. The default value is false, which means that recording starts after the stream publishing in the room has started. true：Start recording immediately after the start of the recording task. false：Start recording after stream publishing in the room has started.

Listed below are MixInputList member parameters.

Parameter	Type	Required	Description
StreamId	String	No	ID of the stream to be displayed on a screen. If this parameter is not set, the stream will be matched based on its order to enter the room.
ViewType	Int	No	Type of content to be displayed on a screen. 1 (default value): audio and video 2: whiteboard The value `2` is valid only when whiteboard recording is enabled. This parameter can be set to `2` for only one screen. Otherwise, an error will be returned.
Top	Int	Yes	Y-axis coordinate of the upper left corner of a screen on the canvas. The value ranges from 0 to 1920 and can't exceed the value of `Bottom` or the canvas height.
Left	Int	Yes	X-axis coordinate of the upper left corner of a screen on the canvas. The value ranges from 0 to 1920 and can't exceed the value of `Right` or the canvas width.
Bottom	Int	Yes	Y-axis coordinate of the lower right corner of a screen on the canvas. The value ranges from 0 to 1920 and can't exceed the canvas height.
Right	Int	Yes	X-axis coordinate of the lower right corner of a screen on the canvas. The value ranges from 0 to 1920 and can't exceed the canvas width.
Layer	Int	Yes	Layer priority of a screen. When an overlap occurs between two screens, the one with a larger value of `Layer` will be displayed on top.
FillMode	Int	No	Filling mode when the aspect ratio of a video stream is different from that of the screen. 1 (default value): cropping. In this mode, the video stream is scaled equally to fully fill in the screen and the content outside the screen will be cropped. 2: scaling. In this mode, the video screen is scaled equally to fill in the screen and black borders will be filled in along all sides.
BackgroundImage	String	No	URL of the background image of a stream. This parameter is valid only when StreamId is set. When the specified stream specified for a customized layout does not exist or the streaming is interrupted, the background image specified by this parameter is displayed. We recommend that the resolution of the background image be the same as the output video resolution. If the resolutions are different, the background image will be stretched or compressed to fully fill in the screen. The background image can be in JPG or PNG format. The maximum image size is 5 MB. If the background image download fails, the setting will be invalid. HTTP and HTTPS URLs are supported.

Listed below are MixOutputVideoConfig member parameters.

Parameter	Type	Required	Description
Width	Int	Yes	Resolution width of the output video, in pixels. The value must be less than or equal to 1920 and the product of the values of `Width` and `Height` can't exceed 1920 x 1080. Otherwise, an error message will be returned.
Height	Int	Yes	Resolution height of the output video, in pixels. The value must be less than or equal to 1920 and the product of the values of `Width` and `Height` can't exceed 1920 x 1080. Otherwise, an error message will be returned.
Fps	Int	Yes	Frame rate of the output video. The value ranges from 5 to 30 and the default value is `15`.
Bitrate	Int	Yes	Bit rate of the output video, in bps. If you want to set the bit rate to 1.5 Mbps, this parameter must be set to `1500000`, that is, 1500 x 1000.

Listed below are MixOutputAudioConfig member parameters.

Parameter	Type	Required	Description
Bitrate	Int	No	Audio bit rate, which is 48000 bps by default.

Listed below are MixOutputWatermarkImageConfig member parameters.

Parameter	Type	Required	Description
Left	Int	Yes	The x-axis coordinate of the upper left corner of the screen on the canvas, the value range is [0, 1920], which cannot exceed the value of Right and the width of the canvas.
Top	Int	Yes	The y-axis coordinate of the upper left corner of the screen on the canvas, the value range is [0, 1920], which cannot exceed the value of Bottom and the height of the canvas.
Right	Int	Yes	The x-axis coordinate of the lower right corner of the screen on the canvas, the value range is [0, 1920], which cannot exceed the width of the canvas.
Bottom	Int	Yes	The y-axis coordinate of the lower right corner of the screen on the canvas, the value range is [0, 1920], and cannot exceed the height of the canvas.

Listed below are RecordOutputParams member parameters.

Parameter	Type	Required	Description
OutputFileFormat	String	No	Format of an output recording file. The options are `mp4`, `flv`, `hls`, `jpg`, and `mp3`, and the default value is `mp4`. If this parameter is set to `mp4` or `flv` and `StreamType` is set as `4`, an audio file in AAC format will be generated.
OutputFolder	String	No	Output directory of a recording file stored on a third-party cloud storage platform. The root directory is used by default.
OutputFileRule	Int	No	Naming rule of a recording file. The default value and the only value that is supported currently is `1`. That is, the naming rules for different recording modes are as follows: Single-stream recording mode: TaskId_RoomId_UserId_StreamId_Type_UTC Mixed-stream recording mode: Taskid_RoomId_MixOutputStreamId_Type_UTC Single-stream recording with whiteboard: Taskid_Roomid_whiteboard_Type_UTC The meanings of file name fields are as follows: Type: file type, which can be `V` (video), `A` (audio), and `VA` (video and audio). UTC: UTC time when recording starts for the file. The time zone is UTC+0 and the time is composed of year, month, day, hour, minute, second, and millisecond. MixOutputStreamId: same as that specified in `MixConfig`. whiteboard: fixed part in the file name
SnapshotInterval	Int	No	Screen capture interval, in seconds. This parameter is valid when the recording file is generated in JPG format. The value ranges from 5 to 3600 and the default value is `10`.
CallbackUrl	String	No	Customized callback URL. The callback URL configured when the service is enabled will be used if this parameter is not set. HTTP and HTTPS URLs are supported.

Listed below are StorageParams member parameters.

Parameter	Type	Required	Description
Vendor	Int	Yes	Recording file storage service provider. Currently, the following service providers are supported: 1: Amazon S3 2: Alibaba Cloud OSS 3: Tencent Cloud COS 4: Qiniu Cloud KODO 5: Alibaba Cloud VOD 6: Tencent Cloud VOD 7: Huawei Cloud OBS 8: Google Cloud Storage 9: China Mobile Cloud EOS
Region	String	No	Region.
Bucket	String	No	Bucket.
AccessKeyId	String	No	Access key. We recommend that you provide an access key with the write-only permission.
AccessKeySecret	String	No	Secret key.
AlibabaCloudVodParams	Object	No	Storage information when Alibaba Cloud VOD is used. For details, see AlibabaCloudVodParams member parameters.
TencentCloudVodParams	Object	No	Storage information when Tencent Cloud VOD is used. For details, see TencentCloudVodParams member parameters.

When Vendor is set to 1, 2, 3, 4 ,7, and 9, Region, Bucket, AccessKeyId, and AccessKeySecret are required.
When Vendor is set to 5, AlibabaCloudVodParams is required. Currently, only MP4 and FLV files can be uploaded.
When Vendor is set to 6, TencentCloudVodParams is required. Currently, only MP4 and FLV files can be uploaded.
If Vendor is 8, recording files will be stored in Google Cloud Storage, and you need to configure the following parameters:
Bucket: the bucket name. You can create a bucket as instructed in Create buckets.
AccessKeyId: the ID of the hash-based message authentication code (HMAC) key of Google Cloud Storage.
AccessKeySecret: the secret of the HMAC key of Google Cloud Storage. Create and obtain your key as instructed in Manage HMAC keys for service accounts.

Listed below are AlibabaCloudVodParams member parameters.

Parameter	Type	Required	Description
Region	String	Yes	Region, such as cn-shanghai.
AccessKeyId	String	Yes	Access key.
AccessKeySecret	String	Yes	Secret key. We recommend that you provide an access key with the write-only permission.
Title	String	Yes	Video name.
StorageLocation	String	Yes	Fixed parameter.

Listed below are TencentCloudVodParams member parameters.

Parameter	Type	Required	Description
SecretId	String	Yes	Access key.
SecretKey	String	Yes	Secret key. We recommend that you provide an access key with the write-only permission.
Region	String	Yes	Region, such as ap-shanghai.
SubAppId	Int64	No	Sub-application ID.

Sample request

Request URL

https://cloudrecord-api.zego.im/?Action=StartRecord
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=7a2c0f11145fb760d607a07b54825013
&SignatureVersion=2.0
&IsTest=false

Request message body

The following is an example of the request message body when Amazon S3, Alibaba Cloud OSS, Tencent Cloud COS, Qiniu Cloud KODO, Huawei Cloud OBS, or China Mobile Cloud EOS is used:

{
    "RoomId": "xxxx",
    "RecordInputParams": {
        "RecordMode": 1,
        "StreamType": 3,
        "MaxIdleTime": 60
    },
    "RecordOutputParams": {
        "OutputFileFormat": "mp4",
        "OutputFolder": "record/"
    },
    "StorageParams": {
        "Vendor": 2,
        "Region": "oss-xxxx",
        "Bucket": "xxxx",
        "AccessKeyId": "xxxx",
        "AccessKeySecret": "xxxx"
    }
}

The following is an example of the request message body when Alibaba Cloud VOD is used:

{
    "RoomId": "xxxx",
    "RecordInputParams": {
        "RecordMode": 1,
        "StreamType": 3,
        "MaxIdleTime": 60
    },
    "RecordOutputParams": {
        "OutputFileFormat": "mp4",
        "OutputFolder": "record/"
    },
    "StorageParams": {
        "Vendor": 5,
        "Region": "",
        "Bucket": "",
        "AccessKeyId": "",
        "AccessKeySecret": "",
        "AlibabaCloudVodParams":{
            "Region": "cn-xxxxx",
            "AccessKeyId": "xxxx",
            "AccessKeySecret": "xxxx",
            "Title": "xxxx",
            "StorageLocation": "xxxx.oss-cn-xxxx.aliyuncs.com",
            }
    }
}

Response parameters

Parameter	Type	Description
Code	Int64	Return code.
Message	String	Description of the request execution result.
RequestId	String	Request ID.
Data	Object	Response object. For details, see the Data member parameter.

Listed below is the Data member parameter.

Parameter	Type	Description
TaskId	String	Task ID assigned by the cloud recording service. The value is a 16-byte character string. The task ID is the unique identifier of a recording lifecycle and becomes meaningless after the recording ends.

Sample response

The following is a response example of the StartRecord method:

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

ZEGO UIKits

Cloud Communications Products

Low-Code Products

AIGC

Supporting Services

Start recording

Description

Request method and endpoint

Request parameters

If `Vendor` is `8`, recording files will be stored in Google Cloud Storage, and you need to configure the following parameters:

Sample request

Response parameters

Sample response

ZEGO UIKits

Cloud Communications Products

Low-Code Products

AIGC

Supporting Services

Start recording

Description

Request method and endpoint

Request parameters

If Vendor is 8, recording files will be stored in Google Cloud Storage, and you need to configure the following parameters:

Sample request

Response parameters

Sample response

If `Vendor` is `8`, recording files will be stored in Google Cloud Storage, and you need to configure the following parameters: