Skip to main content

Agora Developer Center

Docs

REST quickstart

The command-line examples in this article are for demonstration only and should not be used in a production environment. In a production environment, you need to send RESTful API requests through your application server.

Understand the tech​

The complete process of implementing a cloud recording is as follows:

1. Get a resource ID Before starting a cloud recording, you must call the acquire method to obtain a cloud recording resource. After calling this method successfully, you can get a resource ID in the response body.

2. Start a cloud recording Call the start method to join the channel and start a cloud recording. After calling this method successfully, you can get a recording ID from the response body to mark the current recording process.

3. Query the recording status Call the query method to check the recording status during the recording.

4. Stop the cloud recording Call the stop method to stop the cloud recording.

5. Upload the recording file After the recording is over, the cloud recording service uploads the recording file to the third-party cloud storage you specify.

Prerequisites​

Project setup​

Enable the cloud recording service before using Agora Cloud Recording for the first time.

  1. Log in to Agora Console, and click the Project Management icon on the left navigation panel.

  2. On the Project Management page, find the project for which you want to enable the cloud recording service, and click the edit icon.

  3. On the Edit Project page, find Cloud Recording, and click Enable.

  4. Click Enable Cloud Recording.

  5. Click Apply.

Now, you can use Agora Cloud Recording and see the usage statistics in the Usage page.

Implement the cloud recording​

The following figure shows the API call sequence of a cloud recording: Querying the recording status (query), updating the subscription list (update), and updating the video layout (updateLayout) are optional and can be called multiple times, but they must be called during the recording process, that is, after the recording starts and before the recording ends.

Pass the basic HTTP authentication​

The RESTful APIs require basic HTTP authentication. You need to set the Authorization parameter in every HTTP request header. For how to get the value for Authorization, see basic HTTP authentication.

acquire: Get a resource ID​

Call the acquire method to request a resource ID for cloud recording.

After calling this method successfully, you can get a resource ID in the response body. The resource ID is valid for five minutes, so you need to start recording with this resource ID within five minutes. One resource ID can only be used for one recording session.

  • The recording service is equivalent to a non-streaming client in the channel. The uidparameter in the request body is used to identify the recording service and cannot be the same as any existing user ID in the channel. For example, if there are two users already in the channel and their user IDs are 123 and 456, the uid cannot be "123" or "456".
  • Agora Cloud Recording does not support user IDs in string format, that is, User Accounts. Ensure that every user in the channel has an integer user ID. The string content of theuid parameter must also be an integer.

Sample code​

You can use the command-line tool to send the following command to call the acquire method.


_13
# Replace <appid> with the App ID of your Agora project
_13
curl --location --request POST 'https://api.agora.io/v1/apps/<appid>/cloud_recording/acquire' \
_13
# Replace <Authorization> with the Base64-encoded credential in basic HTTP authentication
_13
--header 'Authorization: Basic <Authorization>' \
_13
--header 'Content-Type: application/json' \
_13
--data-raw '{
_13
# Replace <YourChannelName> with the name of the channel you need to record
_13
"cname": "<YourChannelName>",
_13
# Replace <YourRecordingUID> with your user ID
_13
"uid": "<YourRecordingUID>",
_13
"clientRequest":{
_13
}
_13
}'

Start recording​

Call the start method within five minutes after getting the resource ID to join a channel and start the recording. You can choose either individual recording or composite recording as the recording mode.

If this method call succeeds, you get a recording ID (sid) from the HTTP response body. This ID is the unique identification of the current recording.

Sample code​

You can use the command-line tool to send the following commands to call the start method.


_30
# Replace <appid> with the App ID of your Agora project
_30
# Replace <resourceid> with the resource ID obtained through the acquire method
_30
# Replace "<mode>" with "individual" for individual recording or "composite" for composite recording
_30
curl --location --request POST 'https://api.agora.io/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/mode/<mode>/start' \
_30
# Replace <Authorization> with the Base64-encoded credential in basic HTTP authentication
_30
--header 'Authorization: Basic <Authorization>' \
_30
--header 'Content-Type: application/json' \
_30
--data-raw '{
_30
# Replace <YourChannelName> with the name of the channel you need to record.
_30
"cname": "<YourChannelName>",
_30
# Replace <YourRecordingUID> with your user ID that identifies the recording service.
_30
"uid": "<YourRecordingUID>",
_30
"clientRequest": {
_30
# Replace <YourToken> with the temporary token you obtain from the console.
_30
"token": "<YourToken>",
_30
# Set the storageConfig related parameters.
_30
"storageConfig": {
_30
"secretKey": "<YourSecretKey>",
_30
"vendor": 0,
_30
"region": 0,
_30
"bucket": "<YourBucketName>",
_30
"accessKey": "<YourAccessKey>"
_30
},
_30
# Set the recordingConfig related parameters.
_30
"recordingConfig": {
_30
# Which is consistent with the "channelType" of the Agora RTC SDK.
_30
"channelType": 0
_30
}
_30
}
_30
}'

query: Query recording status​

During the recording, you can call the query method to query the recording status multiple times.

After calling this method successfully, you can get the current recording status and related information about the recording file from the response body. See Best Practices in Integrating Cloud Recording for details about how to Monitor service status during a recording and Obtain the M3U8 file name.

Sample code​

You can use the command-line tool to send the following commands to call the query method.


_8
# Replace <appid> with the App ID of your Agora project
_8
# Replace <resourceid> with the resource ID obtained through the acquire method
_8
# Replace <sid> with the sid obtained through the start method
_8
# Replace "<mode>" with "individual" for individual recording or "composite" for composite recording
_8
curl --location --request GET 'https://api.agora.io/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/query' \
_8
# Replace <Authorization> with the Base64-encoded credential in basic HTTP authentication
_8
--header 'Authorization: Basic <Authorization>' \
_8
--header 'Content-Type: application/json' \

stop: Stop recording​

Call the stop the recording.

After calling this method successfully, you can get the status of the recording file upload and information about the recording file from the response body.

Sample code​

You can use the command-line tool to send the following command to call the stop method.


_17
# Replace <appid> with the App ID of your Agora project
_17
# Replace <resourceid> with the resource ID obtained through the acquire method
_17
# Replace <sid> with the sid obtained through the start method
_17
# Replace "<mode>" with "individual" for individual recording or "composite" for composite recording
_17
curl --location --request POST
_17
'https://api.agora.io/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/stop' \
_17
--header 'Content-Type: application/json;charset=utf-8' \
_17
# Replace <Authorization> with the Base64-encoded credential in basic HTTP authentication
_17
--header 'Authorization: Basic <Authorization>' \
_17
--data-raw '{
_17
# Replace <YourRecordingUID> with your user ID that identifies the recording service.
_17
"uid": "<YourRecordingUID>",
_17
# Replace <YourChannelName> with the name of the channel you are recording.
_17
"cname": "<YourChannelName>",
_17
"clientRequest":{
_17
}
_17
}'

Considerations​

Parameter settings​

  • If the uid parameter in the request body is the same as the user ID in the channel, or if a non-integer user ID is used, the recording fails. For details, see the notes on the uid parameter in the section Get a cloud recording resource.
  • When the start request returns 200, it means only that the RESTful API request is successful. To ensure that the recording starts successfully and goes on normally, you also need to call query to query the recording status. Errors such as uUnreasonable transcodingConfig parameter settings, incorrect third-party cloud storage information, or incorrect token information cause the query method to return 404. See Why do I get a 404 error when I call query after successfully starting a cloud recording? .
  • Set maxIdleTime reasonably according to your actual business needs. Within the time range set by maxIdleTime, even if the channel is idle, the recording continues and billing is generated.

API call​

  • After obtaining the resource ID, you must call the startmethod within 5 minutes to start a recording. After the timeout, you need to request a resource ID again.
  • After obtaining the sid (recording ID), after the time set by resourceExpiredHour has passed, you are not able to call the query, updateLayout, and stop methods.

Next steps​

Manage recorded files​

After the recording starts, the Agora server splits the recorded content into multiple TS/WebM files and keeps uploading them to the third-party cloud storage until the recording stops. You can refer to Manage Recorded Files to learn about the naming rules, file sizes, and slicing rules of recording files.

Token authentication​

To ensure communication security, in a formal production environment, you need to generate tokens on your app server. See Authenticate Your Users with Token.

See also​

Update subscription lists​

During the recording, you can call update to update the subscription lists multiple times. See Set up subscription lists for details.

Update video layout​

During the recording, you can call the updateLayout method to set or update the video layout. See Set Video Layout for details.

Sample project​

Agora provides a Postman collection, which contains sample requests of RESTful API for a cloud recording. You can use the collection to quickly grasp the basic functionalities of the Cloud Recording RESTful APIs. You only need to import the collection to Postman and set your environment variables.

You can also use Postman to generate code snippets written in various programming languages. To do so, select a request, click Code, and select the desired language in GENERATE CODE SNIPPETS.

img

Reference documents​

Page Content