Skip to main content

  • Core Products

  • Add-Ons

  • Extensions Marketplace

    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.

    ParameterTypeDescription
    appidStringYour 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.

    ParameterTypeDescription
    cnameString
    • 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.
    uidStringA 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.
    • clientRequestJSONA 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.
      • 2: Postpone transcoding. After setting this scene, the recording service transcodes the recording file to generate an MP4 file within 24 hours after recording, and uploads the MP4 file to the third-party cloud storage you specify. This scenario only applies to individual recording mode. Also set the appsCollection parameter in the start method.

    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:

    _8
    {
    _8
    "cname": "httpClient463224",
    _8
    "uid": "527841",
    _8
    "clientRequest": {
    _8
    "region": "CN",
    _8
    "resourceExpiredHour": 24
    _8
    }
    _8
    }

    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​


    _5
    "Code": 200,
    _5
    "Body":
    _5
    {
    _5
    "resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG"
    _5
    }