tencent cloud

Mobile Live Video Broadcasting

DokumentasiMobile Live Video BroadcastingServer APIsREST APIRoom RelatedAdd Relay Room

Add Relay Room

Download
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-09-02 16:39:05
Diterjemahkan oleh AI

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.
Parameter
Description
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
You can obtain the SdkAppId from your application's card page in the Tencent RTC console.
identifier
Must be an application admin account. For details, see Application Administrator.
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

Field
Type
Required
Description
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:
Operation
Description
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:
Main Room Template Category
Sub-room Relay Template
Description
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

Field
Type
Description
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:
Error Code
Description
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

Capability
Main Room
sub-room
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

Create Room: Create main rooms and sub-rooms.
Remove Relay Sub-rooms: Remove sub-rooms from the main room.
Query Relay Sub-rooms: Query relay roles and sub-room lists.
Dismiss Room: Relay relationships are automatically cleaned up when a room is dismissed.
Topik sebelumnya: Get Room StatisticsTopik selanjutnya: Delete Relay Room

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan