Start a cloud recording task

Updated 2026/07/03 04:07:10

Starts a cloud recording task with an acquired resource ID.

POST

https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/mode/{mode}/start

After receiving a resource ID from acquire, call this endpoint within five minutes to start cloud recording.

Note

After calling start, check that the recording service has started successfully. See Integration best practices.

Path Parameters

appidstring

Required

The App ID of your project.

For web page recording mode, enter the App ID for which the cloud recording service is enabled.
For individual and composite recording 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.

resourceidstring

Required

The resource ID obtained from the acquire endpoint.

modestring

Required

Allowed values:

individual, mix, web

The recording mode:

individual: Individual recording mode.
mix: Composite recording mode.
web: Web page recording mode.

Header Parameters

Content-Typestring

Default:

"application/json"

application/json.

Request Body

application/json

cnamestring

Required

The name of the channel to record. Must match the cname used in the acquire request.

uidstring

Required

The UID used by the cloud recording service in the channel. Must match the uid used in the acquire request.

clientRequestobject

Required

Set this field to improve availability and optimize load balancing.

Note

Values must be valid and consistent with the startParameter in the acquire request body; otherwise the start request returns an error.

tokenstring

A dynamic key used for authentication. Required if your project has enabled the App Certificate. See Token authentication for details.

Only required in individual recording and composite recording modes. Cloud recording does not support token updates, so ensure the token validity period is longer than your expected recording duration to prevent the task from exiting the channel prematurely.

storageConfigobject

Required

Configuration for third-party cloud storage.

vendorinteger

Required

Third-party cloud storage platform:

1: Amazon S3
2: Alibaba Cloud
3: Tencent Cloud
5: Microsoft Azure
6: Google Cloud
7: Huawei Cloud
8: Baidu IntelligentCloud
11: S3-compatible storage. Specify the domain name in extensionParams.endpoint.

regioninteger

Required

The region of the third-party cloud storage.

Note

To ensure upload success and real-time performance, the cloud storage region must match the region of the server where you initiate the request. See Third-party cloud storage regions.

bucketstring

Required

The cloud storage bucket name. Must comply with the naming rules of the corresponding cloud storage service.

accessKeystring

Required

The access key for the third-party cloud storage.

secretKeystring

Required

The secret key for the third-party cloud storage.

stsTokenstring

A temporary security token issued by the cloud provider's Security Token Service (STS), granting limited access to cloud storage resources.

Currently supported only for Amazon S3 (1), Alibaba Cloud (2), and Tencent Cloud (3).

stsExpirationinteger

The stsToken expiration time as a Unix timestamp in seconds.

Use Uint64 storage to avoid timestamp overflow.
Set the longest possible validity period when applying the token. The minimum validity period is 4 hours.
If the recording task runs longer than 1 hour, reapply a new stsToken every 60 minutes and call update again to refresh the storageConfig.

fileNamePrefixarray<string>

The storage path prefix for recorded files. For example, setting ["directory1","directory2"] results in a file name prefix of directory1/directory2/. The total prefix length, including slashes, cannot exceed 128 characters. Supported characters: lowercase letters a-z, uppercase letters A-Z, digits 0-9.

extensionParamsobject

Encryption and tagging settings applied to uploaded recording files by the cloud storage service.

recordingConfigobject

Configuration for recorded audio and video streams. Set this object in individual and composite recording modes.

channelTypeinteger

Required

Default:

The channel profile:

0: Communication.
1: Live streaming.

Must match the channel profile set in the Agora RTC SDK.

decryptionModeinteger

Default:

The decryption mode, required if channel encryption is enabled in the SDK client:

0: No encryption.
1: AES_128_XTS.
2: AES_128_ECB.
3: AES_256_XTS.
4: SM4_128_ECB.
5: AES_128_GCM.
6: AES_256_GCM.
7: AES_128_GCM2. Requires setting secret and salt.
8: AES_256_GCM2. Requires setting secret and salt.

secretstring

The encryption key. Required when decryptionMode is not 0.

saltstring

The encryption salt. Base64-encoded, 32 bytes. Required when decryptionMode is 7 or 8.

maxIdleTimeinteger

Default:

Range:

5 <= value <= 2592000

Maximum channel idle time, in seconds. The recording service exits after the channel is idle for longer than this value.

streamTypesinteger

Default:

The type of media stream to subscribe to:

0: Audio only.
1: Video only.
2: Audio and video.

videoStreamTypeinteger

Default:

The remote video stream type to subscribe to when dual-stream mode is enabled:

0: High-quality video stream (high resolution and high bitrate).
1: Low-quality video stream (low resolution and low bitrate).

subscribeAudioUidsarray<string>

Audio UIDs to subscribe to. Use ["#allstream#"] to subscribe to all audio streams. Do not set together with unsubscribeAudioUids.

Audio streams to subscribe to. The array length cannot exceed 32. Set to ["#allstream#"] to subscribe to all UIDs. Cannot be set together with unsubscribeAudioUids.

Only applicable when streamTypes is 0 or 2. If a subscription list is set for only one media type, the service will not subscribe to the other type.

unsubscribeAudioUidsarray<string>

Audio UIDs not to subscribe to. Do not set together with subscribeAudioUids.

Audio streams to exclude. The service subscribes to all other UIDs. The array length cannot exceed 32. Cannot be set together with subscribeAudioUids.

subscribeVideoUidsarray<string>

Video UIDs to subscribe to. Use ["#allstream#"] to subscribe to all video streams. Do not set together with unsubscribeVideoUids.

Video streams to subscribe to. The array length cannot exceed 32. Set to ["#allstream#"] to subscribe to all UIDs. Cannot be set together with unsubscribeVideoUids.

Only applicable when streamTypes is 1 or 2. If a subscription list is set for only one media type, the service will not subscribe to the other type.

unsubscribeVideoUidsarray<string>

Video UIDs not to subscribe to. Do not set together with subscribeVideoUids.

Video streams to exclude. The service subscribes to all other UIDs. The array length cannot exceed 32. Cannot be set together with subscribeVideoUids.

subscribeUidGroupinteger

Estimated peak number of subscribed UIDs. Required in individual recording mode.

0: 1–2 UIDs.
1: 3–7 UIDs.
2: 8–12 UIDs.
3: 13–17 UIDs.
4: 18–32 UIDs.
5: 33–49 UIDs.

For example, if subscribeVideoUids is ["100","101","102"] and subscribeAudioUids is ["101","102","103"], the subscriber count is 4.

streamModestring

Default:

"default"

Output mode of the media stream. Only applicable in individual recording mode. See Media streaming output modes.

"default": Audio transcoding generates separate M3U8 audio and video index files.
"standard": Generates separate M3U8 audio and video index files, plus a merged audio-and-video index file. If VP8 encoding is used on the Web client, a merged MPD file is generated instead.
"original": Original encoding mode for individual non-transcoding audio recording. Only takes effect when streamTypes is 0. No transcoding occurs; generates an M3U8 audio index file.

audioProfileinteger

Default:

Audio output sampling rate, bitrate, encoding mode, and channel count. Only applicable in composite recording mode.

0: 48 kHz, music encoding, mono, ~48 Kbps.
1: 48 kHz, music encoding, mono, ~128 Kbps.
2: 48 kHz, music encoding, stereo, ~192 Kbps.

transcodingConfigobject

Transcoded video output settings. Only applicable in composite recording mode. See Set the video profile.

widthinteger

Default:

360

Video width in pixels. width × height cannot exceed 1920 × 1080.

heightinteger

Default:

640

Video height in pixels. width × height cannot exceed 1920 × 1080.

fpsinteger

Default:

Video frame rate in fps.

bitrateinteger

Default:

500

Video bitrate in Kbps.

maxResolutionUidstring

The UID of the large video window in vertical layout. Must be an integer from 1 to (2³²−1), cannot be 0. Only required in vertical layout.

mixedVideoLayoutinteger

Default:

Composite video layout:

0: Floating layout. The first user to join fills the entire canvas; other users appear as small windows arranged horizontally from bottom to top, up to 4 rows of 4 windows (17 windows total).
1: Adaptive layout. All user windows are equal in size, automatically adjusted based on user count. Supports up to 17 windows.
2: Vertical layout. The maxResolutionUid user appears in a large window on the left; other users are arranged in up to two columns on the right, 8 windows per column (17 windows total).
3: Custom layout. Configure positions using layoutConfig.

backgroundColorstring

Default:

"#000000"

Canvas background color as an RGB hex string (e.g., "#FF0000" for red).

backgroundImagestring

URL of the canvas background image. Displayed in cropped mode: the image is scaled proportionally until the canvas is filled, and excess edges are cropped.

defaultUserBackgroundImagestring

URL of the default background image shown when a user stops sending video for more than 3.5 seconds. Overridden if a per-UID background image is set in backgroundConfig.

layoutConfigarray<object>

Items:

items <= 17

Per-user screen layout settings for custom layout. Supports up to 17 users. Only applicable when mixedVideoLayout is 3.

backgroundConfigarray<object>

Per-user background image settings.

recordingFileConfigobject

Configuration for recorded files.

Note

Cannot be set when taking screenshots only. Required in all other cases including individual recording (without transcoding, with transcoding, or simultaneous recording and screenshots), composite recording, and web page recording.

avFileTypearray<string>

Default:

[  "hls"]

The type of recorded video files:

"hls": M3U8 and TS files.
"mp4": MP4 files.

In individual recording mode (non-screenshot-only), use the default value. In composite recording and web page recording modes, set to ["hls","mp4"] to generate MP4 files. Setting to ["mp4"] alone causes an error. In composite recording mode, a new MP4 file is created when the current file exceeds ~2 hours or ~2 GB. In web page recording mode, a new MP4 file is created when the current file exceeds maxVideoDuration.

snapshotConfigobject

Screenshot capture settings. Only applicable in individual recording mode.

Screenshots can be taken separately or simultaneously with recording. See Capture screenshots.
If the recording service or the recording upload service malfunctions, the screenshot may fail. Recording is not affected if the screenshot malfunctions.
streamTypes must be 1 or 2. If subscribeAudioUids is set, subscribeVideoUids must also be set.

extensionServiceConfigobject

Configuration for extended services. Only applicable in web page recording mode.

errorHandlePolicystring

Default:

"error_abort"

Error handling policy. Currently only "error_abort" is supported: when an error occurs in an extension service, all other non-extension services (such as stream subscription) also stop.

extensionServicesarray<object>

Required

serviceNamestring

Required

Name of the extension service:

"web_recorder_service": Web page recording.
"rtmp_publish_service": Push web page recording to CDN.

errorHandlePolicystring

Error handling policy within the extension service:

"error_abort": Default for web page recording. Stops other extension services when this service encounters an error.
"error_ignore": Default for CDN push. Other extension services are unaffected when this service encounters an error.

Errors in the page recording service will cause CDN push to fail, but errors in the CDN push service do not affect page recording

serviceParamobject

Required

Specific configuration for the extension service.

urlstring

Required

The URL of the page to record.

audioProfileinteger

Required

Audio output sampling rate, bitrate, encoding mode, and channel count:

0: 48 kHz, music encoding, mono, ~48 Kbps.
1: 48 kHz, music encoding, mono, ~128 Kbps.
2: 48 kHz, music encoding, stereo, ~192 Kbps.

videoWidthinteger

Required

Output video width in pixels. videoWidth × videoHeight must not exceed 1920 × 1080.

videoHeightinteger

Required

Output video height in pixels. videoWidth × videoHeight must not exceed 1920 × 1080.

maxRecordingHourinteger

Required

Range:

1 <= value <= 720

Maximum web page recording duration, in hours.

videoBitrateinteger

Output video bitrate in Kbps.

videoFpsinteger

Default:

Range:

5 <= value <= 60

Output video frame rate in fps.

mobileboolean

Default:

false

Whether to enable mobile web mode.

maxVideoDurationinteger

Default:

120

Range:

30 <= value <= 240

Maximum MP4 file duration in minutes. A new MP4 file is created when the current file exceeds this duration.

onholdboolean

Default:

false

Whether to start the recording in a paused state:

true: The service opens and renders the page but does not generate slice files. Call update with onhold: false to resume.
false: Recording starts immediately.

To pause and resume reliably, wait for each update response before sending the next one.

readyTimeoutinteger

Default:

Range:

0 <= value <= 60

Page load timeout in seconds.

outputsarray<object>

CDN output settings for web page recording push.

containerobject

Response

If the returned status code is 200, the request was successful.
If the returned status code is not 200, the request failed. See Response status codes for troubleshooting.

Response Body

The request succeeded. To confirm that the recording service started successfully, follow the integration best practices.

cnamestring

The name of the channel to be recorded.

The name of the channel being recorded.

uidstring

The UID used by the cloud recording service in the RTC channel.

resourceIdstring

The cloud recording resource ID. Valid for five minutes; re-request from acquire if expired.

The resource ID used by cloud recording.

sidstring

The recording ID. Uniquely identifies a recording session. Generated after the cloud recording service starts successfully.

The recording ID, identifying the current recording session.

Response

See Page load timeout detection.

Response example

{
    "code": 7,
    "reason": "already started"
  }

Authorization

This endpoint requires authentication.

basicAuth

Request examples

curl --request POST \    --url https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/mode/{mode}/start \    --header 'Authorization: Basic <credentials>' \    --header 'Content-Type: application/json' \    --data '{    "cname": "<your_channel_name>",    "uid": "527841",    "clientRequest": {      "recordingConfig": {        "channelType": 1,        "streamTypes": 2,        "streamMode": "default",        "videoStreamType": 0,        "maxIdleTime": 30,        "subscribeAudioUids": ["123", "456"],        "subscribeVideoUids": ["123", "456"],        "subscribeUidGroup": 0      },      "recordingFileConfig": {        "avFileType": ["hls"]      },      "storageConfig": {        "vendor": 2,        "region": 3,        "bucket": "xxxxx",        "accessKey": "xxxxx",        "secretKey": "xxxxx",        "fileNamePrefix": ["directory1", "directory2"]      }    }  }'

Response example

{  "cname": "string",  "uid": "string",  "resourceId": "string",  "sid": "string"}

Start a cloud recording task

Path Parameters

Header Parameters

Request Body

Response

Response Body

Response

Response example

Authorization

Request examples

Response example

Contact Us

Contact Us