Before starting a cloud recording, you need to call the acquire method get a resource ID. Each resource ID can only be used for one recording session.
- Method:POST
- Endpoint: /v1/apps/<appid>/cloud_recording/acquire
The request frequency limit is 10 requests per second for each Agora account. Contact Agora technical support if you want to raise the limit.
If this method call succeeds, you get a resource ID (`resourceId`) from the HTTP response body. The resource ID is valid for five minutes, so you need to
start recording with this resource ID with it before it expires.
HTTP request
The following parameter is required in the URL.
| Parameter |
Type |
Description |
appid |
String |
Your App ID。- In web page recording mode: Use the App ID for which the cloud recording service has been enabled.
- In other modes: Use the same App ID as the channel to be recorded. Ensure that the cloud recording service has been enabled for this App ID.
|
The following parameters are required in the request body.
| Parameter |
Type |
Description |
cname |
String |
- In web page recording mode, use
cname to distinguish between recording sessions. cname should not exceed 128 bytes. You can use a set of appid, cname, and uid to identify one session. As a best practice, if you want to record a web page in more than one session, you can use different user IDs to identify each session while using the same cname to relate to all sessions for that web page. - In other recording modes, use
cname to set the name of the channel to be recorded.
|
uid |
String |
A string that contains the user ID of the recording client, for example "527841". The user ID needs to meet the following requirements: It is a 32-bit unsigned integer within the range between 1 and (232-1).It is unique and does not duplicate any existing user ID in the channel. It is an integer; Cloud Recording does not support user account (which is a string), so all user IDs in the channel must be integers. |
clientRequest |
JSON |
A specific client request that includes the following parameters: region: (Optional) String, which is used to specify the region for connection. If you specify a region, the cloud recording server connects only to the Agora servers within that region. The following region settings are supported: "CN" (Mainland China), "AP" (Asia, excluding Mainland China), "EU" (Europe), or "NA" (North America).
-
resourceExpiredHour: (Optional) Number. Sets the time limit (in hours) for Cloud Recording RESTful API calls. Time starts counting when you successfully start a cloud recording and get an sid (the recording ID).- If you exceed the time limit, you can no longer call
query, update, updateLayout, or stop. - The recording will not stop after exceeding the time limit. The maximum recording length is the value you set through the
maxRecordingHour parameter of the start method. - The value range of
resourceExpiredHour is [1, 720], and the default value is 72.
scene: (Optional) Number. Sets the recording options. 0：Audio and video recording (Default) or Postpone Audio Mixing:- Audio and video recording: The recording service uploads the recording files to the third-party cloud storage you specify in real time after the recording ends.
- Postpone Audio Mixing: The recording service merges and transcodes the recording files of all user IDs in the specified channel within 24 hours after the recording ends to generate an MP3/M4A/AAC file, and then uploads the file to the third-party cloud storage you specify. This scene is only applicable to the individual audio non-transcoding recording mode.
1: Web page recording.
|
Request example
- The request URL is
https://api.agora.io/v1/apps/<yourappid>/cloud_recording/acquire.
Content-type is application/json;charset=utf-8.Authorization is the basic authentication, see RESTful API authentication for details.- The request body:
{
"cname": "httpClient463224",
"uid": "527841",
"clientRequest": {
"region": "CN",
"resourceExpiredHour": 24
}
}
HTTP response
If the returned HTTP status code is 200, it means the request was successful, and the response body contains the following fields:
code: Number. Status code.resourceId: String. The resource ID for cloud recording. The resource ID is valid for five minutes.
Response example
"Code": 200,
"Body":
{
"resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG"
}
