tencent cloud

直播 SDK

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

移除转发子房间

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

功能说明

本接口用于将一个或多个子房间从指定主房间的转发列表中移除。移除成功后，子房间将停止接收主房间的混流转发，恢复为独立房间。
适用场景
活动结束：直播活动结束后，将分会场房间从主舞台中移除。
动态调整：运营中需要减少转发房间数量。
子房间回收：子房间需要恢复独立运营，不再作为转发承载。
注意：
单次操作上限：单次最多移除 5 个子房间。
幂等性：移除不存在的转发关系不会报错（但子房间必须存在且归属于该主房间）。
模板恢复：移除后子房间会自动恢复为创建时的原始布局模板。

接口调用说明

请求 URL 示例

https://xxxxxx/v4/live_engine_http_srv/del_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/del_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-002", "child-room-003"]
}

字段详解

字段
类型
属性
说明
RoomId
String
必填
主房间 ID。仅主房间的房主或管理员可以移除子房间。
RelayRoomIdList
Array of String
必填
待移除的子房间 ID 列表：
单次最多 5 个；
子房间必须存在且属于该主房间，否则对应子房间返回错误。

移除后的效果

项目
移除前（子房间）
移除后（子房间）
混流画面
转发主房间混流内容。
恢复子房间自身混流（若麦位有人），或停止混流（若麦位无人）。
布局模板
使用主房间映射的转发模板。
恢复为创建时的原始模板。
连线/上麦/PK
禁止。
恢复正常，不再受限。
RelayRole
Sub（2）。
None（0）。

返回参数

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

成功响应示例

{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "RequestId": "Id-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "Response": {
        "ResultList": [
            {
                "RoomId": "child-room-002",
                "ErrorCode": 0,
                "ErrorInfo": ""
            },
            {
                "RoomId": "child-room-003",
                "ErrorCode": 0,
                "ErrorInfo": ""
            }
        ]
    }
}

字段详解

字段
类型
说明
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 调用、非房主且非管理员调用、子房间不属于该主房间。
100012
操作频率超限。同一主房间每秒仅允许 1 次转发写操作。
100027
操作进行中。同一主房间有另一个转发写操作正在执行，请稍后重试。

补充说明

子房间自行解散时的行为

当一个已绑定为转发子房间的房间被解散（调用 解散房间）时，系统会自动执行以下清理：
1. 停止子房间的 MCU 混流任务。
2. 从主房间的子房间列表中移除该子房间。
无需额外调用 DelRelayRoom 接口。

主房间解散时的行为

当主房间被解散时，系统会自动遍历所有子房间执行清理：
1. 停止每个子房间的混流任务或恢复为独立混流。
2. 清空每个子房间的转发角色标记。
3. 删除主房间的子房间列表。

运营管理最佳实践

结束直播的推荐流程

1. 先调用本接口移除所有转发子房间。
2. 再依次解散子房间和主房间。
说明：
直接解散主房间时，系统会自动清理所有子房间的转发关系，子房间不会被解散，仅恢复为独立房间。但推荐显式移除以确保状态一致性。

子房间恢复后的状态

移除转发关系后，子房间恢复为完全独立的房间：
可以正常上麦、连线、PK；
若麦位有人，会自动恢复子房间自身模板的混流；
若麦位无人，混流任务将停止。

常见问题

移除后子房间观众会看到什么？

如果子房间麦位有人，观众将看到子房间自身的混流画面；如果麦位无人，观众将看不到任何画面（混流停止）。

子房间被解散时需要先调用移除接口吗？

不需要。子房间被解散时系统会自动从主房间的子房间列表中清除，无需额外调用本接口。

主房间解散后子房间会被解散吗？

不会。主房间解散时系统仅清理转发关系，子房间恢复为独立房间继续存在。

移除操作有频率限制吗？

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

参考

创建房间 ：创建主房间和子房间。
添加转发子房间：将房间设为转发子房间。
查询转发子房间列表：查询房间的转发角色和子房间列表。
解散房间：解散房间时会自动清理转发关系。

上一篇: 添加转发子房间下一篇: 查询转发子房间列表

帮助和支持

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

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

文档反馈

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