Overview
This API sets one or more existing rooms as relay sub-rooms of a specified main room. Once configured, sub-rooms automatically subscribe to and relay the main room's mixed stream, allowing viewers in sub-rooms to watch the main room's live content.
Use Cases
Cross-Room Broadcasting: A host starts streaming in the main room, and the content is simultaneously relayed to multiple sub-rooms — "stream once, watch everywhere."
Multi-Channel Distribution: The same event is broadcast across different rooms; viewers choose their preferred sub-room.
Large-Scale Event Relay: Main stage content is relayed to branch venue rooms.
Note:
Sub-room Restrictions: Once added as a relay sub-room, the room cannot initiate Connection, TakeSeat, or Battle — it serves solely as a relay carrier for the main room's stream.
Per-Request Limit: Up to 5 sub-rooms per request.
Total Sub-room Limit: A single main room can bind up to 50 sub-rooms.
Idempotency: Re-adding a sub-room already bound to the same main room will not cause an error; it returns success directly.
Mutual Exclusion: The sub-room must not be in a Connection or PK state, and must have streaming enabled (IsUnlimitedRoomEnabled = true).
Request URL
Example
https://xxxxxx/v4/live_engine_http_srv/add_relay_room?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json
Query Parameters
The table below lists only the parameters relevant to this API call and their descriptions. For more details, refer to the REST API Overview. |
xxxxxx | The reserved domain for the country/region where the SDKAppID is located: Others in China: console.tim.qq.com Singapore: adminapisgp.im.qcloud.com Silicon Valley: adminapiusa.im.qcloud.com Jakarta: adminapiidn.im.qcloud.com |
v4/live_engine_http_srv/add_relay_room | Add Relay Sub-room API. |
sdkappid | |
identifier | |
usersig | Signature generated for the application admin account. For instructions, see Generate UserSig. |
random | Random 32-bit unsigned integer, range 0 - 4294967295. |
contenttype | Request format, fixed value json. |
Rate Limits
Within the same SDKAppID, each main room allows at most 1 relay write operation per second (AddRelayRoom / DelRelayRoom share the same rate limit).
Request Parameters
The request body must be in JSON format.
Request Example
{
"RoomId": "main-room-001",
"RelayRoomIdList": ["child-room-001", "child-room-002", "child-room-003"]
}
Field Descriptions
|
RoomId | String | Yes | Main room ID. The main room is the content source; its mixed stream will be relayed to all sub-rooms. |
RelayRoomIdList | Array of String | Yes | List of relay sub-room IDs: Up to 5 sub-rooms per request; Each sub-room must already exist; A sub-room cannot be another main room; A sub-room cannot be bound to a different main room (binding to the same main room is treated as idempotent success). |
Sub-room Restrictions
Once a room is added as a relay sub-room, the following operations will be rejected by the server:
|
Connection | The sub-room cannot initiate or accept connection invitations. |
TakeSeat | Viewers in the sub-room cannot take a seat. |
Battle (PK) | The sub-room cannot participate in PK battles. |
The sub-room serves solely as a relay carrier for the main room's stream. All content viewed by audience members in the sub-room comes entirely from the main room's mixed stream.
Template Mapping Between Main Room and Sub-rooms
The sub-room's mix stream layout is automatically determined by the main room's SeatTemplate — no manual configuration required:
|
Portrait Video | VideoPortrait10Seats | Portrait dynamic 1v9 floating layout |
Landscape Video | VideoLandscapeAudioMix10Seats | Landscape dynamic 1v9 layout |
Audio (Voice Chat/KTV) | Karaoke | KTV voice mix stream |
Note:
The sub-room's own SeatTemplate has no effect during relaying — the relay template from the table above is enforced.
When the main room switches templates across categories (e.g., from portrait to landscape), all sub-rooms' mix stream tasks are automatically updated to the new category's relay template.
After the relay relationship is removed, the sub-room reverts to its original template.
Return Parameters
When the API returns HTTP 200, check the ErrorCode in the response body to determine business logic success.
Success Response Example
{
"ActionStatus": "OK",
"ErrorInfo": "",
"ErrorCode": 0,
"RequestId": "Id-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"Response": {
"ResultList": [
{
"RoomId": "child-room-001",
"ErrorCode": 0,
"ErrorInfo": ""
},
{
"RoomId": "child-room-002",
"ErrorCode": 0,
"ErrorInfo": ""
},
{
"RoomId": "child-room-003",
"ErrorCode": 0,
"ErrorInfo": ""
}
]
}
}
Partial Failure Response Example
{
"ActionStatus": "OK",
"ErrorInfo": "",
"ErrorCode": 0,
"RequestId": "Id-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"Response": {
"ResultList": [
{
"RoomId": "child-room-001",
"ErrorCode": 0,
"ErrorInfo": ""
},
{
"RoomId": "child-room-004",
"ErrorCode": 100002,
"ErrorInfo": "sub-room not exist"
}
]
}
}
Field Descriptions
|
ActionStatus | String | Request processing result: OK: processed successfully; FAIL: failed. |
ErrorCode | Integer | Error code: 0: success; Non-zero: overall request failed. |
ErrorInfo | String | Error information. |
RequestId | String | Unique request ID, returned with every request. Provide this when troubleshooting issues. |
Response.ResultList | Array | Operation result list for each sub-room, in the same order as RelayRoomIdList in the request. |
Response.ResultList[i].RoomId | String | sub-room ID. |
Response.ResultList[i].ErrorCode | Integer | Operation result for this sub-room. 0 indicates success; non-zero indicates failure. |
Response.ResultList[i].ErrorInfo | String | Error information for this sub-room. |
Error Codes
For common error codes (60000 to 79999), refer to the Error Codes documentation. The following are the private error codes specific to this API: |
100001 | Internal server error. Please retry. |
100002 | Invalid request parameters. Check the request based on the error description. Common causes: sub-room does not exist, RelayRoomIdList is empty. |
100006 | Permission denied. Common causes: not a REST API call (client SDK not allowed), caller is neither the room owner nor an admin. |
100012 | Rate limit exceeded. Each main room allows at most 1 relay write operation per second. |
100027 | Operation in progress. Another relay write operation is being executed for the same main room. Please retry later. |
Complete Workflow
The relay feature involves three steps: create rooms, start streaming, and establish the relay relationship.
Step 1: Create Main Room and sub-rooms
Use the Create Room API to create the main room and sub-rooms separately. Main Room Example:
{
"RoomInfo": {
"RoomId": "main_room_001",
"RoomType": "Live",
"Owner_Account": "anchor_001",
"TakeSeatMode": "ApplyToTake",
"SeatTemplate": "VideoDynamicGrid9Seats",
"RoomName": "Main Stage"
}
}
Sub-room Example:
{
"RoomInfo": {
"RoomId": "child_room_001",
"RoomType": "Live",
"Owner_Account": "admin_001",
"SeatTemplate": "VideoDynamicGrid9Seats",
"RoomName": "Branch Venue A"
}
}
Note:
The sub-room's SeatTemplate has no effect during relaying; it is overridden by the relay template mapped from the main room's template. A single main room can bind up to 50 sub-rooms.
Step 2: Host Starts Streaming in Main Room
The host joins the main room via the client SDK → takes a seat (TakeSeat) → starts publishing audio/video streams. The server automatically triggers MCU mix stream generation. The relay content comes from this mixed stream.
Step 3: Add Relay Sub-rooms
Call this API to bind sub-rooms to the main room:
{
"RoomId": "main_room_001",
"RelayRoomIdList": ["child_room_001", "child_room_002", "child_room_003"]
}
Note:
The sub-room cannot be in a Connection or PK state when being added as a relay sub-room.
Capability Comparison During Relay
|
Watch Live | ✓ | ✓ (main room content) |
Take Seat | ✓ | × |
Connection | ✓ | × |
PK (Battle) | ✓ | × |
FAQ
No video in sub-room after adding?
The main room does not have a host streaming yet. Ensure the host has entered the room, taken a seat, and started publishing. Once the mix stream is generated, sub-rooms will automatically receive the video.
Does the sub-room's layout template take effect?
No. During relaying, the relay template mapped from the main room's template is enforced (see the "Template Mapping" section above). The original template is restored after the relay relationship is removed.
Does switching the main room's template affect sub-rooms?
Yes. All sub-rooms' mix streams are automatically updated to the new category's corresponding relay template.
Can a sub-room be bound to multiple main rooms simultaneously?
No. A sub-room can only be bound to one main room.
Is there a rate limit for add/remove operations?
Yes. Each main room allows at most 1 relay write operation per second (add and remove share the same rate limit).
Reference
Dismiss Room: Relay relationships are automatically cleaned up when a room is dismissed.