Custom recording configuration

Custom recording enables you to use third-party cloud storage services, while standard recording does not.

Set custom recording configuration

Sets the custom recording configuration for all live streams under the specified entry point.

HTTP request

PATCH https://api.agora.io/v1/projects/{appid}/fls/entry_points/{entry_point}/settings/record/custom/regions/{region}

Path parameter

Parameter	Type	Description
`appid`	String	Required. The App ID corresponding to the entry point.
`entry_point`	String	Required. The entry point name.
`region`	String	Required. The configured region when adding the domain.

Request body

The request body is in the JSON Object type, and contains the following fields:

Field	Type	Description
`mp4Config`	JSON Object	Optional. For the configuration of the MP4 recording files, see mp4Config.
`hlsConfig`	JSON Object	Optional. For the configuration of the HLS recording files, see HlsConfig.
`storageConfig`	JSON Object	Optional (required when setting recording options for the first time). For the storage configuration of the recording files, see StorageConfig.

HTTP response

If the returned HTTP status code is 200, the request is successful.

If the returned HTTP status code is not 200, the request fails. You can refer to the HTTP status code for possible reasons.

Example

Request line

PATCH https://api.agora.io/v1/projects/{your_appid}/fls/entry_points/live/settings/record/custom/regions/cn HTTP/1.1

Request body

{
    "hlsConfig": {
        "enabled": true
    },
    "mp4Config": {
        "enabled": true
    },
    "storageConfig": {
        "accessKey": "{your access key}",
        "bucket": "{your bucket}",
        "region": 3,
        "secretKey": "{your secret key}",
        "vendor": 2
    }
}

Response line

HTTP/1.1 200 OK

Get custom recording configuration

Gets the custom recording configuration for the specified entry point.

HTTP request

GET https://api.agora.io/v1/projects/{appid}/fls/entry_points/{entry_point}/settings/record/custom/regions/{region}

Path parameter

Parameter	Type	Description
`appid`	String	Required. The App ID corresponding to the entry point.
`entry_point`	String	Required. The entry point name.
`region`	String	Required. The configured region when adding the domain.

HTTP response

If the returned HTTP status code is 200, the request is successful, and the response body contains the following fields:

Field	Type	Description
`mp4Config`	JSON Object	For the configuration of the MP4 recording files, see mp4Config.
`hlsConfig`	JSON Object	For the configuration of the HLS recording files, see HlsConfig.
`storageConfig`	JSON Object	For the storage configuration of the recording files, see StorageConfig.

If the returned HTTP status code is not 200, the request fails. You can refer to the HTTP status code for possible reasons.

Example

Request line

GET https://api.agora.io/v1/projects/{your_appid}/fls/entry_points/live/settings/record/custom/regions/cn HTTP/1.1

Response line

HTTP/1.1 200 OK

Request body

{
    "hlsConfig": {
        "enabled": true
    },
    "mp4Config": {
        "enabled": true
    },
    "storageConfig": {
        "accessKey": "{your accesskey}",
        "region": 3,
        "secretKey": "{your secretkey}",
        "vendor": 2
    }
}

Parameter type

mp4Config

The configuration of the MP4 recording files, including the following fields:

enabled: Bool type, optional. Whether to enable recording in the MP4 format.

HlsConfig

The configuration of the HLS recording files, including the following fields:

enabled: Bool type, optional. Whether to enable recording in the HLS format.

StorageConfig

The storage configuration of the recording files, including the following fields:

vendor: Number. The third-party cloud storage vendor.
- 0: Qiniu Cloud
- 1: Amazon S3
- 2: Alibaba Cloud
- 3: Tencent Cloud
- 4: Kingsoft Cloud
- 5: Microsoft Azure
- 6: Google Cloud
- 7: Huawei Cloud
- 8: Baidu AI Cloud
region: Number. The region information specified for the third-party cloud storage. The recording service only supports regions in the following lists:
In order to improve the success rate and real-time performance when uploading recording files, if you set the region of the cloud recording service in the acquire method, make sure that the region of the third-party cloud storage corresponds to the same geographical region. For example, if the region of the cloud recording service is set to NA (North America), the third-party cloud storage needs to be set to a location within North America.

When the third-party cloud storage is Qiniu Cloud (vendor = 0):

0: East China
1: North China
2: South China
3: North America
4: Southeast Asia

When the third-party cloud storage is Amazon S3 (vendor = 1):

0：US_EAST_1
1：US_EAST_2
2：US_WEST_1
3：US_WEST_2
4：EU_WEST_1
5：EU_WEST_2
6：EU_WEST_3
7：EU_CENTRAL_1
8：AP_SOUTHEAST_1
9：AP_SOUTHEAST_2
10：AP_NORTHEAST_1
11：AP_NORTHEAST_2
12：SA_EAST_1
13：CA_CENTRAL_1
14：AP_SOUTH_1
15：CN_NORTH_1
16：CN_NORTHWEST_1
18：AF_SOUTH_1
19：AP_EAST_1
20：AP_NORTHEAST_3
21：EU_NORTH_1
22：ME_SOUTH_1
24：AP_SOUTHEAST_3
25：EU_SOUTH_1
26：AWS_REGION_NUM

When the third-party cloud storage is Alibaba Cloud (vendor = 2):

0: CN_Hangzhou
1: CN_Shanghai
2: CN_Qingdao
3: CN_Beijing
4: CN_Zhangjiakou
5: CN_Huhehaote
6: CN_Shenzhen
7: CN_Hongkong
8: US_West_1
9: US_East_1
10: AP_Southeast_1
11: AP_Southeast_2
12: AP_Southeast_3
13: AP_Southeast_5
14: AP_Northeast_1
15: AP_South_1
16: EU_Central_1
17: EU_West_1
18: EU_East_1
19：AP_Southeast_6
20：CN_Heyuan
21：CN_Guangzhou
22：CN_Chengdu

For details, see Alibaba Cloud Documentation.

When the third-party cloud storage is Tencent Cloud (vendor = 3):

0：AP_Beijing_1
1：AP_Beijing
2：AP_Shanghai
3：AP_Guangzhou
4：AP_Chengdu
5：AP_Chongqing
6：AP_Shenzhen_FSI
7：AP_Shanghai_FSI
8：AP_Beijing_FSI
9：AP_Hongkong
10：AP_Singapore
11：AP_Mumbai
12：AP_Seoul
13：AP_Bangkok
14：AP_Tokyo
15：NA_Siliconvalley
16：NA_Ashburn
17：NA_Toronto
18：EU_Frankfurt
19：EU_Moscow

When the third-party cloud storage is Kingsoft Cloud (vendor = 4):

0：CN_Hangzhou
1：CN_Shanghai
2：CN_Qingdao
3：CN_Beijing
4：CN_Guangzhou
5：CN_Hongkong
6：JR_Beijing
7：JR_Shanghai
8：NA_Russia_1
9：NA_Singapore_1

When the third-party cloud storage is Microsoft Azure (vendor = 5):

The region parameter has no effect, whether or not it is set.

When the third-party cloud storage is Google Cloud (vendor = 6):

The region parameter has no effect, whether or not it is set.

When the third-party cloud storage is Huawei Cloud (vendor = 7):

0：CN_North_1
1：CN_North_4
2：CN_East_2
3：CN_East_3
4：CN_South_1
5：CN_Southwest_2
6：AP_Southeast_1
7：AP_Southeast_2
8：AP_Southeast_3
9：AF_South_1
10：SA_Argentina_1
11：SA_Peru_1
12：NA_Mexico_1
13：SA_Brazil_1
14：LA_South_2
15：SA_Chile_1

When the third-party cloud storage is Baidu AI Cloud (vendor = 8):

0：Beijing
1：Baoding
2：Suzhou
3：Guangzhou
4：Hongkong
5：Singapore
6：Wuhan
7：Shanghai

bucket: String. The bucket name of the third-party cloud storage.
accessKey: String. The access key of the third-party cloud storage. Agora suggests that you use a write-only access key.
secretKey: String. The secret key of the third-party cloud storage.

HTTP status code

Status code	Description
200	The request succeeds.
400	The parameter is invalid, for example the `appid` or the `entry_point` is empty, or the `region` parameter value is invalid.
401	Unauthorized (the customer ID and the customer secret do not match).
404	The server cannot find the resource according to the request, which means the requested entry point does not exist or the requested URI path is invalid.
500	An internal error occurs in the server, so the server is not able to complete the request.
504	An internal error occurs in the server. The gateway or the proxy server did not receive a timely request from the remote server.