Start a cloud recording task

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.

info

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

appid stringrequired

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.

resourceid stringrequired

The resource ID obtained from the acquire endpoint.

mode stringrequired

Possible values: individual, mix, web

The recording mode:

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

APPLICATION/JSON

BODYrequired

stringrequired

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

stringrequired

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

objectrequired
Set this field to improve availability and optimize load balancing.
info
Values must be valid and consistent with the startParameter in the acquire request body; otherwise the start request returns an error.
Show propertiesHide properties
stringnullable

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.

objectrequired

Configuration for third-party cloud storage.

Show propertiesHide properties

numberrequired
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.
numberrequired

The region of the third-party cloud storage.

info

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.

stringrequired

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

stringrequired

The access key for the third-party cloud storage.

stringrequired

The secret key for the third-party cloud storage.

stringnullable

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).

numbernullable
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 to refresh the storageConfig.
array[string]nullable

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.

objectnullable

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

Show propertiesHide properties

stringrequired
The encryption mode for uploaded files. Applicable to Amazon S3 only. See the Amazon S3 documentation.
• kms: KMS encryption.
• aes256: AES256 encryption.
stringrequired

Tag content applied to uploaded files. Applicable to Alibaba Cloud and Amazon S3 only.

objectnullable
Configuration for recorded audio and video streams. Only required in individual recording and composite recording modes.
Show propertiesHide properties
numberrequired

Default: 0

The channel profile:

• 0: Communication.
• 1: Live streaming.

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

numbernullable
Default: 0
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.
stringnullable

The encryption key. Required when decryptionMode is not 0.

stringnullable

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

numbernullable

Default: 30

Range: [5, 2592000]

Maximum channel idle time in seconds. Cannot exceed 30 days. The recording service exits automatically when this duration is exceeded. Starting a new recording after exit generates a new recording file.

A channel is considered idle when there are no hosts in a live channel, or no users in a communication channel.

numbernullable
Default: 2
The type of media stream to subscribe to:
• 0: Audio only.
• 1: Video only.
• 2: Audio and video.
numbernullable
Default: 0
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).
array[string]nullable

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.

array[string]nullable

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

array[string]nullable

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.

array[string]nullable

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

numbernullable

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.

stringnullable
Default: "default"
Possible values: default, standard, original
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.
numbernullable
Default: 0
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.
objectnullable
Transcoded video output settings. Only applicable in composite recording mode. See Set the video profile.
Show propertiesHide properties
numbernullable

Default: 360

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

numbernullable

Default: 640

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

numbernullable

Default: 15

Video frame rate in fps.

numbernullable

Default: 500

Video bitrate in Kbps.

stringnullable

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.

numbernullable
Default: 0
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.
stringnullable

Default: "#000000"

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

stringnullable

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.

stringnullable

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.

array[object]nullable
Per-user screen layout settings for custom layout. Supports up to 17 users. Only applicable when mixedVideoLayout is 3.
Show propertiesHide properties
stringnullable

The UID of the user assigned to this layout region. If not specified, layout regions are assigned in the order users join the channel.

number (float)required

Range: [0, 1]

Horizontal coordinate of the region's upper-left corner as a relative value (6 decimal places). 0.0 is the far left, 1.0 is the far right.

number (float)required

Range: [0, 1]

Vertical coordinate of the region's upper-left corner as a relative value (6 decimal places). 0.0 is the top, 1.0 is the bottom.

number (float)required

Range: [0, 1]

Relative width of the region (6 decimal places).

number (float)required

Range: [0, 1]

Relative height of the region (6 decimal places).

number (float)nullable

Default: 1

Range: [0, 1]

Transparency of the user's video window. 0.0 is fully transparent, 1.0 is fully opaque.

numbernullable
Default: 0
Display mode for the user's video window:
• 0: Cropped mode. The window is filled; video is scaled proportionally and cropped at the edges if the aspect ratio differs.
• 1: Fit mode. All video content is visible; the video is scaled proportionally and black borders may appear.
array[object]nullable
Per-user background image settings.
Show propertiesHide properties
stringrequired

The UID of the user.

stringrequired

The URL of the user's background image, shown when the user stops sending video for more than 3.5 seconds. Supports HTTPS, JPG and BMP formats, maximum 6 MB. Settings take effect only after the image is successfully downloaded.

numbernullable
Default: 0
Display mode for the background image:
• 0: Cropped mode. The window is filled; image is scaled proportionally and cropped at the edges if the aspect ratio differs.
• 1: Fit mode. All image content is visible; the image is scaled proportionally and black borders may appear.
objectnullable

Configuration for recorded files.

info

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.

Show propertiesHide properties

array[string]nullable

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.

objectnullable

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.

Show propertiesHide properties

numbernullable

Default: 10

Range: [5, 3600]

Screenshot capture interval in seconds.

array[string]required

Screenshot file format. Currently only ["jpg"] is supported.

objectnullable
Configuration for extended services. Only applicable in web page recording mode.
Show propertiesHide properties
stringnullable

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.

array[object]required
Show propertiesHide properties
stringrequired
Name of the extension service:
• "web_recorder_service": Web page recording.
• "rtmp_publish_service": Push web page recording to CDN.
stringnullable

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.

objectrequired
Specific configuration for the extension service.
Show propertiesHide properties
stringrequired

The URL of the page to record.

numberrequired
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.
numberrequired

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

numberrequired

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

numberrequired

Range: [1, 720]

Maximum web page recording duration in hours. Recording stops automatically when this limit is exceeded. The recommended value should not exceed the resourceExpiredHour set in the acquire request. Charges continue until recording stops, so set this value according to your business needs or stop recording manually.

numbernullable
Output video bitrate in Kbps. Default values by resolution:
• Resolution ≥ 1280 × 720: 2000
• Resolution < 1280 × 720: 1500
numbernullable

Default: 15

Range: [5, 60]

Output video frame rate in fps.

booleannullable
Default: false
Whether to enable mobile web mode:
• true: The recording service uses mobile web rendering mode.
• false: Uses standard rendering mode.
numbernullable

Default: 120

Range: [30, 240]

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

booleannullable

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.

numbernullable
Default: 0
Range: [0, 60]
Page load timeout in seconds. See Page load timeout detection.
• 0: Page loading status is not detected.
• 1–60: Recording stops if the page does not load within this duration.

• If the returned status code is 200, the request was successful.

  OK

  string

  The name of the channel being recorded.

  string

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

  string

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

  string

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

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

Authorization

This endpoint requires Basic Auth.

Request example

• curl
• Python
• Node.js

_31

curl --request POST \

_31

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

_31

--header 'Authorization: Basic <credentials>' \

_31

--header 'Content-Type: application/json' \

_31

--data '{

_31

"cname": "<your_channel_name>",

_31

"uid": "527841",

_31

"clientRequest": {

_31

"recordingConfig": {

_31

"channelType": 1,

_31

"streamTypes": 2,

_31

"streamMode": "default",

_31

"videoStreamType": 0,

_31

"maxIdleTime": 30,

_31

"subscribeAudioUids": ["123", "456"],

_31

"subscribeVideoUids": ["123", "456"],

_31

"subscribeUidGroup": 0

_31

},

_31

"recordingFileConfig": {

_31

"avFileType": ["hls"]

_31

},

_31

"storageConfig": {

_31

"vendor": 2,

_31

"region": 3,

_31

"bucket": "xxxxx",

_31

"accessKey": "xxxxx",

_31

"secretKey": "xxxxx",

_31

"fileNamePrefix": ["directory1", "directory2"]

_31

}

_31

}

_31

}'

Response example

• 200
• Non-200

_6

{

_6

"cname": "<your_channel_name>",

_6

"uid": "527841",

_6

"resourceId": "JyvK8nXHuV1BE.....",

_6

"sid": "38f8e3cfdc474cd56fc1ceba380d7e1a"

_6

}