Start Recording

Start recording while configuring parameters for the recording service.

Enable Service

Cloud Recording is a paid value-added service. Before using the Cloud Recording API, ensure you've enabled the service in Console and completed relevant configurations. See Configure Cloud Recording Service.

Note: The recording trigger method must be set to Manual to use API-controlled recording.

Request Method

POST: https://Data Center Domain/rtc/record/start.json

Signature Rule: All requests to RC server APIs require signature validation. See API Request Signature.

Request Body Parameters

The HTTP request body contains a JSON object with the following structure:

Parameter	Type	Required	Description
sessionId	String	Yes	Current call session ID. Obtain this sessionId through RC server callbacks. See Room Status Callback.
extra	String	Yes	Extended field for business tagging. The recording callback service will include this field when notifying your application server.
config	Object	Yes	Specifies cloud recording configurations, supporting split-stream recording or MCU mixed-stream recording.
config.recordType	Number	No	Specifies recording type (default: 1). Recording modes are categorized by stream type: 1: Split-stream recording—Records each user's stream separately or merges all user streams with customizable layouts. 2: MCU mixed-stream recording—Directly records server-side mixed live streams. Output matches viewer experience with predefined layouts. Only available after enabling RTC Live Streaming.
config.mode	Number	No	Specifies split-stream recording mode (valid only when config.recordType=1): 0: Single mode—Full recording 1: Single mode—Video-only 2: Single mode—Audio-only 3: Mix mode—Full recording 4: Mix mode—Video-only 5: Mix mode—Audio-only 6: Single Mix mode—Video Single mode generates separate audio/video files. Mix mode produces merged recordings. See Recording Mode Details in Configure Cloud Recording Service.
config.videoResolution	String	No	Specifies split-stream recording resolution (valid only when config.recordType=1). 12 options: 256x144 / 144x256 320x240 / 240x320 480x320 / 320x480 640x480 / 480x640 1280x720 / 720x1280 1920x1080 / 1080x1920 Defaults: For single modes (0/1/2): Matches first client stream resolution. For mix modes (3/4/5/6): 640x480
config.videoFormat	String	Yes	Output video format: mkv, mp4, flv, hls. Note: Some audio/video format combinations may cause player compatibility issues (e.g., silent video). Try alternative players before finalizing formats.
config.audioFormat	String	Yes	Output audio format: aac, mp3. Note: See video format note above.
config.mixLayout	Number	Yes	Sub-stream layout for split-stream recording (valid only when config.recordType=1 and mix modes 3/4/5/6). Options: 1: Custom layout 2: Floating layout 3: Adaptive layout
config.sliceMin	Number	Yes	Recording slice duration (minutes). Options: 30, 60, 90, 120.
config.renderMode	Number	Yes	Video scaling method: 1: Crop to fill (may clip source) 2: Letterbox (may show black bars)
config.hostUserId	String	No	Primary view user ID (valid only when config.recordType=1): Custom layout (1): Omit (use config.input instead). Floating layout (2): Required for background. Adaptive layout (3): Required for top-left view. Do not use with MCU recording (config.recordType=2).
config.hostStreamId	String	No	Primary view stream ID (valid only when config.recordType=1): Custom layout (1): Omit (use config.input). Floating layout (2): Required for background rendering. Adaptive layout (3): Required for top-left rendering. Do not use with MCU recording (config.recordType=2).
config.input	Object	No	Custom layout parameters for merged recordings (valid only when config.recordType=1). Required when config.mixLayout=1. Contains sub-view stream arrays with positioning data. See config.input Object Details below.
config.mcuConfig	Object	No	MCU recording configurations (valid only when config.recordType=2).
config.mcuConfig.mode	Number	No	MCU recording mode (valid only when config.recordType=2): 1: Video-only 2: Audio-only 6: Full recording
config.mcuConfig.videoResolution	String	Yes	MCU recording resolution (valid only when config.recordType=2). Same 12 options as config.videoResolution.

• config.input Object Details: Specifies custom layout parameters for sub-stream views in merged recordings:

  Parameter	Type	Required	Description
  video	Array	Yes	Array defining sub-window positions/sizes.
  video[i].userId	String	Yes	Sub-window user ID
  video[i].streamId	String	Yes	Sub-window stream ID
  video[i].x	Number	Yes	Float. Sub-window X-axis position (relative to videoResolution width).
  video[i].y	Number	Yes	Float. Sub-window Y-axis position (relative to videoResolution height).
  video[i].width	Number	Yes	Float. Sub-window width (relative to videoResolution width).
  video[i].height	Number	Yes	Float. Sub-window height (relative to videoResolution height).

Request Example

POST /rtc/record/start.json HTTP/1.1
Host: api.rong-api.com
App-Key: uwd1c0sxdlx2
Timestamp: 1585127132438
Nonce: 14314
Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
Room-Id: room1
Content-Type: application/json

{
    "sessionId":"aaa",
    "config":{
        "recordType": 1,
        "mode":3,
        "videoResolution":"640x480",
        "videoFormat":"mkv",
        "audioFormat":"aac",
        "mixLayout":1,
        "sliceMin":60,
        "renderMode":1,
        "hostUserId":"abc",
        "hostStreamId":"111_RongCloudRTC",
        "input":{
            "video":[
                {
                    "userId":"111",
                    "streamId":"111_RongCloudRTC",
                    "x":0,
                    "y":0,
                    "width":0.5,
                    "height":0.5
                },
                {
                    "userId":"2222",
                    "streamId":"2222_RongCloudRTC",
                    "x":0.5,
                    "y":0.5,
                    "width":0.5,
                    "height":0.5
                }
            ]
        },
        "mcuConfig":{
            "mode": 6
            "videoResolution":"640x480"
        }
    }
}

Response

Field	Type	Description
code	Number	Status code (200 = success).
errorMessage	String	Error details.
recordId	String	Unique recording ID for callback/file slice correlation.

Response Example

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "code":200,
    "errorMessage":"Success",
    "recordId":"b8bed381888091ff4e6a42d6f3b8782a"
}