tencent cloud

直播 SDK

文档直播 SDK服务端 APIREST API房间相关添加转发子房间

添加转发子房间

下载
聚焦模式
字号
最后更新时间： 2026-09-02 16:39:05

功能说明

本接口用于将一个或多个已创建的直播间设置为指定主房间的转发子房间。设置成功后，子房间将自动订阅主房间的混流画面并进行转发，观众在子房间内即可观看主房间的直播内容。
适用场景
跨房间转播：一个主播开播后，将内容同步转发到多个子房间，实现"一处开播、多处观看"。
多频道分发：同一场活动在不同房间同步播出，观众根据喜好选择子房间观看。
大型赛事转播：主赛场直播内容转发至各分会场房间。
注意：
子房间限制：子房间被添加为转发子房间后，不能连线（Connection）、不能上麦（TakeSeat）、不能 PK（Battle），只作为主房间流的转发承载。
单次操作上限：单次最多添加 5 个子房间。
子房间总数上限：单个主房间最多绑定 50 个子房间。
幂等性：重复添加已绑定到同一主房间的子房间不会报错，直接返回成功。
互斥限制：子房间不能处于连线或 PK 状态，且必须开启混流（IsUnlimitedRoomEnabled = true）。

接口调用说明

请求 URL 示例

https://xxxxxx/v4/live_engine_http_srv/add_relay_room?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

请求参数说明

下表仅列出调用本接口时涉及修改的参数及其说明，更多参数详情请参见 REST API 简介。
参数
说明
xxxxxx
SDKAppID 所在国家/地区对应的专属域名：
中国：console.tim.qq.com
新加坡：adminapisgp.im.qcloud.com
硅谷：adminapiusa.im.qcloud.com
雅加达：adminapiidn.im.qcloud.com
v4/live_engine_http_srv/add_relay_room
添加转发子房间接口。
sdkappid
您可以在 Tencent RTC 控制台 的应用卡片中获取 SdkAppId。
identifier
必须为 App 管理员账号，更多详情请参见 App 管理员。
usersig
App 管理员账号生成的签名，具体操作请参见 生成 UserSig。
random
请输入随机的32位无符号整数，取值范围0 - 4294967295。
contenttype
请求格式固定值为 json。

最高调用频率

同一 SDKAppID 下，同一主房间每秒最多 1 次转发写操作（AddRelayRoom / DelRelayRoom 共享限频）。

请求参数

请求包体为 JSON 格式。

请求示例

{
    "RoomId": "main-room-001",
    "RelayRoomIdList": ["child-room-001", "child-room-002", "child-room-003"]
}

字段详解

字段
类型
属性
说明
RoomId
String
必填
主房间 ID。主房间是内容的源头，其混流画面将被转发到所有子房间。
RelayRoomIdList
Array of String
必填
转发子房间 ID 列表：
单次最多 5 个子房间；
子房间必须是已创建的房间；
子房间不能是另一个主房间；
子房间不能已绑定到其他主房间（但绑定到同一主房间视为幂等成功）。

子房间的使用限制

子房间被添加为转发子房间后，以下操作将被服务端拒绝：
操作
说明
连线（Connection）
子房间不能发起或接受连线邀请。
上麦（TakeSeat）
子房间内观众不能上麦。
PK（Battle）
子房间不能参与 PK 对战。
子房间只作为主房间流的转发承载，观众在子房间内观看的内容完全来自主房间的混流画面。

主房间与子房间的模板映射

子房间的混流布局会根据主房间的 SeatTemplate 自动选择对应的转发模板，无需手动指定：
主房间模板分类
子房间转发使用的模板
说明
竖屏视频
VideoPortrait10Seats
竖屏动态 1v9 浮动布局。
横屏视频
VideoLandscapeAudioMix10Seats
横屏动态 1v9 布局。
音频（语聊房/KTV）
Karaoke
KTV 玩法语音混流。
说明：
子房间自身创建时的 SeatTemplate 不影响转发期间的混流布局——转发期间强制使用上表中映射的模板。
当主房间切换模板导致跨分类（如从竖屏切到横屏）时，所有子房间的混流任务会自动更新为新分类对应的模板。
解除转发关系后，子房间自动恢复为创建时的原始模板。

返回参数

接口返回 HTTP 200 状态码时，需根据包体中的 ErrorCode 判断业务逻辑是否成功。

成功响应示例

{
    "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": ""
            }
        ]
    }
}

部分失败响应示例

{
    "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": "child room not exist"
            }
        ]
    }
}

字段详解

字段
类型
说明
ActionStatus
String
请求处理的结果：
OK 表示处理成功；
FAIL 表示失败。
ErrorCode
Integer
错误码：
0：表示成功；
非0：表示整体请求失败。
ErrorInfo
String
错误信息。
RequestId
String
唯一请求 ID，每次请求都会返回，定位问题时需要提供该次请求的 RequestId。
Response.ResultList
Array
每个子房间的操作结果列表，顺序与请求中的 RelayRoomIdList 一致。
Response.ResultList[i].RoomId
String
子房间 ID。
Response.ResultList[i].ErrorCode
Integer
该子房间的操作结果。0 表示成功，非 0 表示失败。
Response.ResultList[i].ErrorInfo
String
该子房间的错误信息。

常见错误码

公共错误码（60000 到 79999）参见 错误码 文档，本 API 私有错误码如下：
错误码
含义说明
100001
服务器内部错误，请重试。
100002
请求参数非法，请根据错误描述检查请求是否正确。常见原因：子房间不存在、RelayRoomIdList 为空。
100006
权限不足。常见原因：非 REST API 调用（端上 SDK 不允许调用此接口）、非房主且非管理员调用。
100012
操作频率超限。同一主房间每秒仅允许 1 次转发写操作。
100027
操作进行中。同一主房间有另一个转发写操作正在执行，请稍后重试。

完整操作流程

整个转发功能分为三步：创建房间、开始推流、建立转发关系。

步骤 1：创建主房间和子房间

通过 创建房间 接口分别创建主房间和子房间。
主房间示例：
{
    "RoomInfo": {
        "RoomId": "main_room_001",
        "RoomType": "Live",
        "Owner_Account": "anchor_001",
        "TakeSeatMode": "ApplyToTake",
        "SeatTemplate": "VideoDynamicGrid9Seats",
        "RoomName": "主舞台直播间"
    }
}
子房间示例：
{
    "RoomInfo": {
        "RoomId": "child_room_001",
        "RoomType": "Live",
        "Owner_Account": "admin_001",
        "SeatTemplate": "VideoDynamicGrid9Seats",
        "RoomName": "分会场A"
    }
}
说明：
子房间的 SeatTemplate 在转发期间不生效，强制使用主房间模板对应的转发模板。单个主房间最多绑定 50 个子房间。

步骤 2：主房间主播推流

主播通过客户端 SDK 进入主房间 → 上麦（TakeSeat）→ 推送音视频流。服务端会自动触发混流（MCU）生成混流画面，转发内容来源于此混流画面。

步骤 3：添加转发子房间

调用本接口将子房间绑定到主房间：
{
    "RoomId": "main_room_001",
    "RelayRoomIdList": ["child_room_001", "child_room_002", "child_room_003"]
}
绑定成功后，当主房间有混流画面时，子房间观众即可看到主房间的直播内容。
注意：
子房间不能处于连线状态。

转发期间的能力对照

能力
主房间
子房间
观看直播
✓
✓（主房间画面）
上麦
✓
×
连线
✓
×
PK
✓
×

常见问题

子房间添加后没有画面？

主房间还没有主播推流。确保主播已进房、上麦并推流，混流生成后子房间会自动获得画面。

子房间的布局模板会生效吗？

转发期间不生效，强制使用主房间模板对应的转发模板（参见上方"主房间与子房间的模板映射"章节）。解除转发后恢复原始模板。

主房间切换模板会影响子房间吗？

会。所有子房间的混流会自动更新为新模板对应的转发模板。

一个子房间可以同时绑定多个主房间吗？

不可以。一个子房间只能绑定到一个主房间。

添加和移除操作有频率限制吗？

有。同一主房间每秒最多 1 次转发写操作（添加和移除共享限频）。

参考

创建房间 ：创建主房间和子房间。
移除转发子房间：从主房间中移除子房间。
查询转发子房间列表：查询房间的转发角色和子房间列表。
解散房间：解散房间时会自动清理转发关系。
上一篇: 获取房间统计数据下一篇: 移除转发子房间

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈

搜索
    请输入关键词搜索文档