实时音视频
实时音视频
文档指南
请输入
- 文档首页
实时音视频实时音视频服务端 API 参考云端录制更新合流录制 UpdateRecord
复制全文
下载 pdf更新合流录制 UpdateRecord
文档反馈
问问助手在合流录制（仅自定义布局模式）过程中，动态调整布局参数，如画布背景和各路流的画面布局。可更新以下参数：
- TargetStreams
- Layout.CustomLayout.Canvas.Background 和 Layout.CustomLayout.Canvas.BackgroundImage
- Layout.CustomLayout.Regions
注意
调用此接口时，需确保云端录制功能已启用且当前处于合流录制的自定义布局模式，即 RecordMode=0 且 Layout.LayoutMode=2。
注意事项
请求频率：QPS 不得超过 60。
请求说明
- 请求方式：POST
- 请求地址：https://rtc.volcengineapi.com?Action=UpdateRecord&Version=2023-11-01
调试
API Explorer
您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。
请求参数
Query
Action String 必选 示例值：UpdateRecord
接口名称。当前 API 的名称为 UpdateRecord。
Version String 必选 示例值：2023-11-01
接口版本。当前 API 的版本为 2023-11-01。
Body
AppId String 必选 示例值：66****3cf
BusinessId String 可选 示例值：B****1
RoomId String 必选 示例值：Room1
目标房间 ID。
TaskId String 必选 示例值：Task1
云端录制任务 ID。
TargetStreams Object 可选 示例值：-
指定需要录制的音视频流。单流录制模式下，如果参数为空，默认录制对房间内所有人进行单流录制。最多 17 路流。
StreamList Object[] 可选 示例值：-
目标流列表。
Index Integer 可选 示例值：0
流的唯一索引，用于在自定义布局中标识该流。在 Layout.CustomLayout.regions.StreamIndex 中会引用此 Index 来配置对应流的布局。
在一个 StreamList 中，Stream.Index 不能重复。
UserId String 必选 示例值：user1
目标流所属的用户 ID。在客户端定义的。
StreamType Integer 可选 示例值：0
流的类型：
- 0（默认值）：普通音视频流。
- 1：屏幕共享流。
Layout Object 可选 示例值：-
布局参数。
LayoutMode Integer 可选 示例值：2
布局模式。调用本接口时仅支持取值 2，表示自定义布局。
MainVideoStream Object 可选 示例值：-
垂直布局配置。
Index Integer 可选 示例值：0
流的唯一索引，用于在自定义布局中标识该流。在 Layout.regions.StreamIndex 中会引用此 Index 来配置对应流的布局。默认为 0。
在一个 StreamList 中，Stream.Index 不能重复。
UserId String 必选 示例值：user1
目标流所属的用户 ID。在客户端定义的。
StreamType Integer 可选 示例值：0
流的类型：
- 0（默认值）：普通音视频流。
- 1：屏幕共享流。
CustomLayout Object 可选 示例值：-
自定义布局配置。
Canvas Object 可选 示例值：-
整体屏幕（画布）的宽高以及背景色。
Width Integer 可选 示例值：640
整体屏幕（画布）的宽度，取值范围为 [2, 4096]，必须是偶数，单位为像素，默认值为 640。
Height Integer 可选 示例值：480
整体屏幕（画布）的高度，取值范围为 [2, 2160]，必须是偶数，单位为像素，默认值为 480。
Background String 可选 示例值：#000000
整体屏幕（画布）的背景色, 范围为 #000000 ~ #ffffff (大小写均可)，格式为 #RGB(16进制)，默认值为 #000000（黑色）。
BackgroundImage String 可选 示例值：-
背景图片的 URL。长度最大为 1024 byte。可以传入的图片的格式包括：JPG、JPEG、PNG。
如果背景图片的宽高和整体屏幕的宽高不一致，背景图片会缩放到铺满屏幕。
如果你设置了背景图片，背景图片会覆盖背景色。
Regions Object[] 可选 示例值：-
在自定义布局模式下，你可以使用 Regions 对每一路视频流进行画面布局设置。其中，每个 Region 对一路视频流进行画面布局设置。
自定义布局模式下，对于 StreamList 中的每个 Stream，Regions 中都需要给出对应的布局信息，否则会返回请求不合法的错误。即 Regions.StreamIndex 要与 TargetStreams.StreamList.Index 的值一一对应，否则自定义布局设置失败，返回 InvalidParameter 错误码。
当传入的必填参数值不合法时，返回错误码 InvalidParameter 。
StreamIndex Integer 必选 示例值：0
流的标识。这个标志应和 TargetStreams.StreamList.Stream.Index 对应。
LocationX Integer 可选 示例值：0
视频流对应区域左上角的横坐标相对整体画面左上角原点的横向位移，取值的范围为 [0, Canvas.Width)。默认值为 0。若传入该参数，服务端会对该参数进行校验，若不合法会返回错误码 InvalidParameter。
LocationY Integer 可选 示例值：0
视频流对应区域左上角的纵坐标相对整体画面左上角原点的纵向位移，取值的范围为 [0, Canvas.Height)。默认值为 0。若传入该参数，服务端会对该参数进行校验，若不合法会返回错误码 InvalidParameter。
Width Integer 必选 示例值：640
视频流对应区域宽度的像素绝对值，取值的范围为 (0, Canvas.Width]。
Height Integer 必选 示例值：480
视频流对应区域高度的像素绝对值，取值的范围为 (0, Canvas.Height]。
ZOrder Integer 可选 示例值：0
当多个流的画面有重叠时，使用此参数设置指定画面的图层顺序。
- 取值范围为 [0, 100]。0 表示该区域图像位于最下层，100 表示该区域图像位于最上层。
- 默认值为 0。
Alpha Float 可选 示例值：0.5
画面的透明度。
- 取值范围为 (0.0, 1.0]。0.0 表示完全透明，1.0 表示完全不透明。
- 默认值为 1.0。
RenderMode Integer 可选 示例值：0
画面的渲染模式。支持取值及含义如下：
- 0 ：按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形
- 1 ：按照显示区域的长宽比裁减视频，然后等比拉伸或缩小视频，占满显示区域。
- 2 ：按照原始画面的宽高比缩放视频，在显示区域居中显示。如果原始画面宽高比与指定的宽高比不同，就会导致画面有空缺，空缺区域为填充的背景色值。
- 3 ：按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形。
- 默认值为 0。
- 目前 0 和 3 均为按照指定的宽高直接缩放，但我们推荐你使用 3 以便与客户端实现相同逻辑。
SourceCrop Object 可选 示例值：-
源流剪切功能，可以在源视频帧渲染之前进行裁剪，即预处理一次再渲染。
LocationX Float 可选 示例值：0.1
裁剪后得到的视频帧左上角的横坐标相对裁剪前整体画面的比例，取值的范围为 [0.0, 1.0)。默认值为 0.0。
LocationY Float 可选 示例值：0.1
裁剪后得到的视频帧左上角的纵坐标相对裁剪前整体画面的比例，取值的范围为 [0.0, 1.0)。默认值为 0.0。
WidthProportion Float 可选 示例值：0.5
裁剪后得到的视频帧宽度相对裁剪前整体画面宽度的比例，取值范围为 (0.0, 1.0]。默认值为 1.0。
HeightProportion Float 可选 示例值：0.5
裁剪后得到的视频帧高度相对裁剪前整体画面宽度的比例，取值范围为 (0.0, 1.0]。默认值为 1.0。
AlternateImage String 可选 示例值：-
补位图片的 url。长度不超过 1024 个字符。
- 在 Region.StreamIndex 对应的视频流没有发布，或被暂停采集时，AlternateImage 对应的图片会填充 Region 对应的画布空间。当视频流被采集并发布时，AlternateImage 不造成任何影响。
- 可以传入的图片的格式包括：JPG、JPEG、PNG。
- 当图片和画布尺寸不一致时，图片根据 RenderMode 的设置，在画布中进行渲染。
ApplySpatialAudio Boolean 可选 示例值：-
该路流对应的用户是否开启空间音频效果。
- true：开启空间音频效果。
- false：关闭空间音频效果。
- 默认值为 true
SpatialPosition Integer[] 可选 示例值：[0,0,0]
空间音频下，房间内指定用户所在位置的三维坐标，默认值为 [0, 0, 0]。数组长度为 3，三个值依次对应X、Y、Z，每个值的取值范围为 [-100,100]。
CornerRadius Float 可选 示例值：0.1
转推直播下边框圆角半径与画布宽度的比例值，取值范围为 [0,1]。默认值为 0，表示没有圆角效果。
圆角半径的像素位不能超过 Region 宽高最小值的一半，否则不会出现圆角效果。
MediaType Integer 可选 示例值：0
该路流参与混流的媒体类型。支持取值及含义如下：
- 0：音视频
- 1：纯音频
- 2：纯视频
- 默认值为 0。
- 例如该路流为音视频流，MediaType设为 1，则只混入音频内容。
AlternateImageFillMode Integer 可选 示例值：0
画面的渲染模式。支持取值及含义如下：
- 0：按照用户原始视频帧比例进行缩放
- 1：保持图片原有比例
- 默认值为 0。
返回参数
其中返回值 Result 仅在请求成功时返回 ok，失败时为空。
请求示例
返回示例
错误码
最近更新时间：2026.08.21 13:49:53
这个页面对您有帮助吗？
有用
有用
无用
无用