# Start a cloud recording task (/en/api-reference/api-ref/cloud-recording/start)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

Starts a cloud recording task with an acquired resource ID.

- OpenAPI: /openapi/cloud-recording/cloud-recording.en.yaml
- Operation ID: start-cloud-recording
- Method: POST
- Path: /v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/mode/{mode}/start

## Servers

- https://api.sd-rtn.com

## Parameters

- `Content-Type` (header, optional) - `application/json`.
- `appid` (path, 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.
- `resourceid` (path, required) - The resource ID obtained from the `acquire` endpoint.
- `mode` (path, required) - The recording mode:
- `individual`: Individual recording mode.
- `mix`: Composite recording mode.
- `web`: Web page recording mode.

## Request body

- `cname` (string, required) - The name of the channel to record. Must match the `cname` used in the `acquire` request.
No schema.
- `uid` (string, required) - The UID used by the cloud recording service in the channel. Must match the `uid` used in the `acquire` request.
No schema.
- `clientRequest` (object, required) - Set this field to improve availability and optimize load balancing.
  - `clientRequest.token` (string) - 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.
No schema.
  - `clientRequest.storageConfig` (object, required) - Configuration for third-party cloud storage.
    - `clientRequest.storageConfig.vendor` (integer, 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`.
No schema.
    - `clientRequest.storageConfig.region` (integer, required) - The region of the third-party cloud storage.
No schema.
    - `clientRequest.storageConfig.bucket` (string, required) - The cloud storage bucket name. Must comply with the naming rules of the corresponding cloud storage service.
No schema.
    - `clientRequest.storageConfig.accessKey` (string, required) - The access key for the third-party cloud storage.
No schema.
    - `clientRequest.storageConfig.secretKey` (string, required) - The secret key for the third-party cloud storage.
No schema.
    - `clientRequest.storageConfig.stsToken` (string) - 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`).
No schema.
    - `clientRequest.storageConfig.stsExpiration` (integer) - 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`.
No schema.
    - `clientRequest.storageConfig.fileNamePrefix` (array) - 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`.
      - `clientRequest.storageConfig.fileNamePrefix.items` (string)
No schema.
    - `clientRequest.storageConfig.extensionParams` (object) - Encryption and tagging settings applied to uploaded recording files by the cloud storage service.
      - `clientRequest.storageConfig.extensionParams.sse` (string, required) - The encryption mode for uploaded files. Applicable to Amazon S3 only. See the Amazon S3 documentation.
- `kms`: KMS encryption.
- `aes256`: AES256 encryption.
No schema.
      - `clientRequest.storageConfig.extensionParams.tag` (string, required) - Tag content applied to uploaded files. Applicable to Alibaba Cloud and Amazon S3 only.
No schema.
      - `clientRequest.storageConfig.extensionParams.endpoint` (string) - The domain name for S3 protocol cloud storage. This field is required when you set `vendor` to `11`.
No schema.
  - `clientRequest.recordingConfig` (object) - Configuration for recorded audio and video streams. Set this object in individual and composite recording modes.
    - `clientRequest.recordingConfig.channelType` (integer, required) - The channel profile:
- `0`: Communication.
- `1`: Live streaming.

 Must match the channel profile set in the Agora RTC SDK.
No schema.
    - `clientRequest.recordingConfig.decryptionMode` (integer) - 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`.
No schema.
    - `clientRequest.recordingConfig.secret` (string) - The encryption key. Required when `decryptionMode` is not `0`.
No schema.
    - `clientRequest.recordingConfig.salt` (string) - The encryption salt. Base64-encoded, 32 bytes. Required when `decryptionMode` is `7` or `8`.
No schema.
    - `clientRequest.recordingConfig.maxIdleTime` (integer) - Maximum channel idle time, in seconds. The recording service exits after the channel is idle for longer than this value.
No schema.
    - `clientRequest.recordingConfig.streamTypes` (integer) - The type of media stream to subscribe to:
- `0`: Audio only.
- `1`: Video only.
- `2`: Audio and video.
No schema.
    - `clientRequest.recordingConfig.videoStreamType` (integer) - 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).
No schema.
    - `clientRequest.recordingConfig.subscribeAudioUids` (array) - 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.
      - `clientRequest.recordingConfig.subscribeAudioUids.items` (string)
No schema.
    - `clientRequest.recordingConfig.unsubscribeAudioUids` (array) - 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.
      - `clientRequest.recordingConfig.unsubscribeAudioUids.items` (string)
No schema.
    - `clientRequest.recordingConfig.subscribeVideoUids` (array) - 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.
      - `clientRequest.recordingConfig.subscribeVideoUids.items` (string)
No schema.
    - `clientRequest.recordingConfig.unsubscribeVideoUids` (array) - 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.
      - `clientRequest.recordingConfig.unsubscribeVideoUids.items` (string)
No schema.
    - `clientRequest.recordingConfig.subscribeUidGroup` (integer) - 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.
No schema.
    - `clientRequest.recordingConfig.streamMode` (string) - 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.
No schema.
    - `clientRequest.recordingConfig.audioProfile` (integer) - 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.
No schema.
    - `clientRequest.recordingConfig.transcodingConfig` (object) - Transcoded video output settings. Only applicable in composite recording mode. See Set the video profile.
      - `clientRequest.recordingConfig.transcodingConfig.width` (integer) - Video width in pixels. `width` × `height` cannot exceed 1920 × 1080.
No schema.
      - `clientRequest.recordingConfig.transcodingConfig.height` (integer) - Video height in pixels. `width` × `height` cannot exceed 1920 × 1080.
No schema.
      - `clientRequest.recordingConfig.transcodingConfig.fps` (integer) - Video frame rate in fps.
No schema.
      - `clientRequest.recordingConfig.transcodingConfig.bitrate` (integer) - Video bitrate in Kbps.
No schema.
      - `clientRequest.recordingConfig.transcodingConfig.maxResolutionUid` (string) - 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.
No schema.
      - `clientRequest.recordingConfig.transcodingConfig.mixedVideoLayout` (integer) - 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`.
No schema.
      - `clientRequest.recordingConfig.transcodingConfig.backgroundColor` (string) - Canvas background color as an RGB hex string (e.g., `"#FF0000"` for red).
No schema.
      - `clientRequest.recordingConfig.transcodingConfig.backgroundImage` (string) - 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.
No schema.
      - `clientRequest.recordingConfig.transcodingConfig.defaultUserBackgroundImage` (string) - 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`.
No schema.
      - `clientRequest.recordingConfig.transcodingConfig.layoutConfig` (array) - Per-user screen layout settings for custom layout. Supports up to 17 users. Only applicable when `mixedVideoLayout` is `3`.
        - `clientRequest.recordingConfig.transcodingConfig.layoutConfig.items` (object)
          - `clientRequest.recordingConfig.transcodingConfig.layoutConfig.items.uid` (string) - The UID of the user assigned to this layout region. If not specified, layout regions are assigned in the order users join the channel.
No schema.
          - `clientRequest.recordingConfig.transcodingConfig.layoutConfig.items.x_axis` (number, required) - 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.
No schema.
          - `clientRequest.recordingConfig.transcodingConfig.layoutConfig.items.y_axis` (number, required) - 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.
No schema.
          - `clientRequest.recordingConfig.transcodingConfig.layoutConfig.items.width` (number, required) - Relative width of the region (6 decimal places).
No schema.
          - `clientRequest.recordingConfig.transcodingConfig.layoutConfig.items.height` (number, required) - Relative height of the region (6 decimal places).
No schema.
          - `clientRequest.recordingConfig.transcodingConfig.layoutConfig.items.alpha` (number) - Transparency of the user's video window. `0.0` is fully transparent, `1.0` is fully opaque.
No schema.
          - `clientRequest.recordingConfig.transcodingConfig.layoutConfig.items.render_mode` (integer) - 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.
No schema.
      - `clientRequest.recordingConfig.transcodingConfig.backgroundConfig` (array) - Per-user background image settings.
        - `clientRequest.recordingConfig.transcodingConfig.backgroundConfig.items` (object)
          - `clientRequest.recordingConfig.transcodingConfig.backgroundConfig.items.uid` (string, required) - The UID of the user.
No schema.
          - `clientRequest.recordingConfig.transcodingConfig.backgroundConfig.items.image_url` (string, required) - 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.
No schema.
          - `clientRequest.recordingConfig.transcodingConfig.backgroundConfig.items.render_mode` (integer) - 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.
No schema.
  - `clientRequest.recordingFileConfig` (object) - Configuration for recorded files.
    - `clientRequest.recordingFileConfig.avFileType` (array) - 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`.
      - `clientRequest.recordingFileConfig.avFileType.items` (string)
No schema.
  - `clientRequest.snapshotConfig` (object) - 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.
    - `clientRequest.snapshotConfig.captureInterval` (integer) - Screenshot capture interval in seconds.
No schema.
    - `clientRequest.snapshotConfig.fileType` (array, required) - Screenshot file format. Currently only `jpg` is supported.
      - `clientRequest.snapshotConfig.fileType.items` (string)
No schema.
  - `clientRequest.extensionServiceConfig` (object) - Configuration for extended services. Only applicable in web page recording mode.
    - `clientRequest.extensionServiceConfig.errorHandlePolicy` (string) - 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.
No schema.
    - `clientRequest.extensionServiceConfig.extensionServices` (array, required)
      - `clientRequest.extensionServiceConfig.extensionServices.items` (object)
        - `clientRequest.extensionServiceConfig.extensionServices.items.serviceName` (string, required) - Name of the extension service:
- `"web_recorder_service"`: Web page recording.
- `"rtmp_publish_service"`: Push web page recording to CDN.
No schema.
        - `clientRequest.extensionServiceConfig.extensionServices.items.errorHandlePolicy` (string) - 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
No schema.
        - `clientRequest.extensionServiceConfig.extensionServices.items.serviceParam` (object, required) - Specific configuration for the extension service.
          - `clientRequest.extensionServiceConfig.extensionServices.items.serviceParam.url` (string, required) - The URL of the page to record.
No schema.
          - `clientRequest.extensionServiceConfig.extensionServices.items.serviceParam.audioProfile` (integer, 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.
No schema.
          - `clientRequest.extensionServiceConfig.extensionServices.items.serviceParam.videoWidth` (integer, required) - Output video width in pixels. `videoWidth` × `videoHeight` must not exceed 1920 × 1080.
No schema.
          - `clientRequest.extensionServiceConfig.extensionServices.items.serviceParam.videoHeight` (integer, required) - Output video height in pixels. `videoWidth` × `videoHeight` must not exceed 1920 × 1080.
No schema.
          - `clientRequest.extensionServiceConfig.extensionServices.items.serviceParam.maxRecordingHour` (integer, required) - Maximum web page recording duration, in hours.
No schema.
          - `clientRequest.extensionServiceConfig.extensionServices.items.serviceParam.videoBitrate` (integer) - Output video bitrate in Kbps.
No schema.
          - `clientRequest.extensionServiceConfig.extensionServices.items.serviceParam.videoFps` (integer) - Output video frame rate in fps.
No schema.
          - `clientRequest.extensionServiceConfig.extensionServices.items.serviceParam.mobile` (boolean) - Whether to enable mobile web mode.
No schema.
          - `clientRequest.extensionServiceConfig.extensionServices.items.serviceParam.maxVideoDuration` (integer) - Maximum MP4 file duration in minutes. A new MP4 file is created when the current file exceeds this duration.
No schema.
          - `clientRequest.extensionServiceConfig.extensionServices.items.serviceParam.onhold` (boolean) - 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.
No schema.
          - `clientRequest.extensionServiceConfig.extensionServices.items.serviceParam.readyTimeout` (integer) - Page load timeout in seconds.
No schema.
          - `clientRequest.extensionServiceConfig.extensionServices.items.serviceParam.outputs` (array) - CDN output settings for web page recording push.
            - `clientRequest.extensionServiceConfig.extensionServices.items.serviceParam.outputs.items` (object)
              - `clientRequest.extensionServiceConfig.extensionServices.items.serviceParam.outputs.items.rtmpUrl` (string) - CDN address to which the stream is pushed.
No schema.
          - `clientRequest.extensionServiceConfig.extensionServices.items.serviceParam.container` (object)
            - `clientRequest.extensionServiceConfig.extensionServices.items.serviceParam.container.format` (string) - Container format, such as `mp4`, `mp3`, `m4a`, or `aac`.
No schema.
            - `clientRequest.extensionServiceConfig.extensionServices.items.serviceParam.container.sampleRate` (string) - Audio sampling rate in Hz.
No schema.
            - `clientRequest.extensionServiceConfig.extensionServices.items.serviceParam.container.bitrate` (string) - Audio bitrate in Kbps.
No schema.
            - `clientRequest.extensionServiceConfig.extensionServices.items.serviceParam.container.channels` (string) - Number of audio channels.
No schema.

## Responses

### 200

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

- `resourceId` (string) - The cloud recording resource ID. Valid for five minutes; re-request from `acquire` if expired.

The resource ID used by cloud recording.
No schema.
- `sid` (string) - The recording ID. Uniquely identifies a recording session. Generated after the cloud recording service starts successfully.

The recording ID, identifying the current recording session.
No schema.
- `cname` (string) - The name of the channel to be recorded.

The name of the channel being recorded.
No schema.
- `uid` (string) - The UID used by the cloud recording service in the RTC channel.
No schema.
### default

The request failed. If the HTTP status code is not `200`, see the Cloud Recording response status codes for troubleshooting.

No schema.