更新云端录制布局
更新时间： 2025/10/30 16:35:16
该接口允许您对已创建的云端录制任务进行自定义布局参数的动态更新，适用于实时调整录制内容的显示方式。对于已经 创建云端录制任务 的音视频通话，支持根据需要动态修改录制布局设置。
接口说明
此接口适用于以下场景：
- 当有用户加入或离开音视频房间时，及时调整视频窗口布局。
- 当有用户开始或结束屏幕共享时，调整录制画面的布局。
- 需要在录制过程中调整视频窗口大小和位置。
- 在录制过程中需要调整录制的用户名单。
对于已经通过 创建云端录制任务 接口启动的音视频通话录制，更新录制布局时，您只需要在本接口请求体中修改需要更新的布局参数，其余参数保持原云端录制任务的设置（可通过 查询云端录制配置 接口查询）：
-
布局配置：
- 更新
layoutConfig.layout中的users（用户视频窗口）、subStreams（屏幕共享窗口）、images（图片窗口）的布局位置和大小。 - 更新
recordConfig.modeList[].layout中的users、subStreams、images的布局位置和大小。
- 更新
-
流订阅配置：更新
streamSubscribe参数，动态调整订阅哪些用户的音频流或视频流。 -
水印配置：更新
watermark和recordConfig.modeList[].watermark参数，动态调整图片、文字、透明层或者时间戳水印。
有关录制布局参数的详细说明，请参考《录制布局》布局参数说明 章节和 更新录制布局 章节。
接口限制
默认上限为 50 次/秒，若请求频率超出限制，可能会返回 429 错误码。若您需要上调上限，请参考 如何处理调用服务端 RESTful API 超出频率限制。
请求信息
请求 URL
-
请求方法：POST
-
请求 URL：网易云信为该功能提供以下两个 API 请求地址，使用 V3 地址需在 URL 中指定 cname，您可以根据业务需求调用任一接口。
https://rtc.yunxinapi.com/v2/api/cloudrecord/updatehttps://rtc.yunxinapi.com/v3/api/cloudrecord/update?cname={cname}
请求路径参数
URL 中参数说明：
| 参数名称 | 类型 | 示例 | 说明 |
|---|---|---|---|
| cname | String | abc | 房间名称。仅在调用 V3 接口时需要设置。 |
请求头参数
请求中 Header 的设置请参考 请求结构 描述。
请求体参数
| 参数名称 | 类型 | 是否必选 | 说明 |
|---|---|---|---|
| cid | Number | 必选，仅适用于 V2 接口 | 房间 ID。该 ID 为创建房间接口调用成功后返回的房间 ID。仅在调用 V2 接口时需要设置。 |
| taskId | String | 是 | 任务唯一标识符，房间内唯一。调用 创建云端录制任务 接口后，可在响应体中获取 taskId。 |
| recordConfig | recordConfig | 否 | 录制模式。详细信息请参考 recordConfig。 支持如下三种模式：
|
| streamSubscribe | streamSubscribe | 否 | 在录制过程中，通过黑白名单指定订阅某些用户的音频流或视频流。具体请参考 订阅名单。 默认为订阅房间内所有发布的音视频流。 |
| detect | detect | 否 | 内容安全审核配置。详细信息请参考 detect。 |
|
layoutConfig |
否 |
录制布局配置。详细信息请参考 录制布局
|
|
| watermark | watermark | 否 | 水印配置。详细信息请参考 watermark。 |
请求体示例
更新录制布局时，您只需要在更新录制布局接口请求体中修改需要更新的布局参数，其余参数保持原云端录制任务的设置（可通过 查询云端录制配置 接口查询）。
JSON{
"cid":11***77184,
"taskId":"23d73e2ae2c74135a732c8d24739b71d8723",
"recordConfig": {
"modeList": [
{
"mode": 100
},
{
"layout": {
"canvas": {
"height": 720,
"width": 1280
},
"subStreams": [
{
"adaption": 0,
"height": 720,
"width": 1280,
"x": 0,
"y": 240,
"zOrder": 0
}
],
"users": [
{
"adaption": 0,
"height": 240,
"width": 320,
"x": 0,
"y": 0,
"zOrder": 1
}
]
},
"layoutType": 2,
"mode": 1
}
],
"recordType": 100,
},
"detect":{
"enableSpamDetect":true,
"scFrequency":1,
"detectType":1
},
"layoutConfig":{
"hostUid":66602,
"layoutType":3
},
"streamSubscribe":{
"streamType":2,
"audioUidList":{
"unSubscribeUids":[
66668888
]
},
"videoUidList":{
"subscribeUids":[
2223333
]
}
},
"watermark":{
"literaWms":[
{
"wmLitera": "水印测试",
"fontSize":50,
"fontColor":"#RRGGBB",
"offsetX":0,
"offsetY":0
}
],
"transparentLayers":[
{
"offsetX":0,
"offsetY":0,
"wmWidth":480,
"wmHeight":100,
"bgTransparency":3
}
],
"imgWms":[
{
"url":"https://freepngimg.com/XXX/XXX/example.png",
"offsetX":120,
"offsetY":120,
"wmWidth":100,
"wmHeight":100
}
],
"timestampWm":{
"fontSize":50,
"fontColor":"#RRGGBB",
"offsetX":0,
"offsetY":50
}
}
}
响应信息
响应体参数
返回结构请参考 通用返回结构。其中，业务相关参数封装在 record 参数中，包括：
| 参数名称 | 类型 | 示例 | 说明 |
|---|---|---|---|
| taskId | String | 1143932537695968 | 录制任务 ID，为任务唯一标识符，且房间内唯一。 |
| cid | Number | 123456 | 房间 ID。 |
响应体示例
JSON{
"code": 200,
"record": {
"taskId": "23d73e2ae2c74135a732c8d24739b71d8723",
"cid": 11443***77184
}
}
状态码
响应内容中，code 为 200 表示调用正常，若 code 为其他值，请根据 code 与 errmsg 在 云端录制相关错误码 中查看问题原因与解决方法。
