本文档 API 接口为最新版本接口，后续相关功能的新增都会在此更新，推荐使用最新版本接口。旧版接口文档请参考历史版本。
如果你已启用云端录制，并进行了自定义布局的合流录制，你可以更新录制的配置参数。你可以使用 UpdateRecord 这个 OpenAPI 实现这一功能。
关于如何启用云端录制，参看开始云端录制 StartRecord。

使用说明

接口行为

你可以调用 UpdateRecord 接口，覆盖此前在 StartRecord 或 UpdateRecord 中设定的以下参数：

TargetStreams
Layout.CustomLayout.Canvas.Background 和 Layout.CustomLayout.Canvas.BackgroundImage
Layout.CustomLayout.Regions

在开始录制前，你必须已经启用云端录制，并启用了合流录制。参看开始云端录制 StartRecord。
并且，仅在启动云端录制的配置中 RecordMode=0 且 Layout.LayoutMode=2 时，才可以调用此接口，即只有合流录制的自定义布局模式下，才可以更新任务参数。

调用接口

关于调用接口的服务地址、通信协议、字符编码和签名机制，参看调用 OpenAPI。

注意事项

请求频率：QPS 不得超过 60。

请求说明

请求方式：POST
请求地址：https://rtc.volcengineapi.com?Action=UpdateRecord&Version=2023-11-01

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`UpdateRecord`	接口名称。当前 API 的名称为 `UpdateRecord`。
Version	String	是	`2023-11-01`	接口版本。当前 API 的版本为 `2023-11-01`。

Body

参数	类型	是否必选	示例值	描述
AppId	String	是	`Your_AppId`	你的音视频应用的唯一标志
BusinessId	String	否	`Your_BusinessId`	业务标识
RoomId	String	是	`Your_RoomId`	房间的 ID，是房间的唯一标志
TaskId	String	是	`Your_TaskId`	云端录制任务 ID。你必须对每个云端录制任务设定 TaskId，且在进行任务更新时也须使用该 TaskId。 `TaskId` 是任务的标识，在一个 `AppId` 的 `RoomId` 下 `taskId` 是唯一的，不同 `AppId` 或者不同 `RoomId` 下 `TaskId` 可以重复，因此 `AppId` + `RoomId` + `TaskId` 是任务的唯一标识，可以用来标识指定 `AppId` 下某个房间内正在运行的任务，从而能在此任务运行中进行更新或者停止此任务。关于 TaskId 及以上 Id 字段的命名规则符合正则表达式：`[a-zA-Z0-9_@\-\.]{1,128}`
TargetStreams	Object of Streams	否		你可以通过本参数设定需要录制的音视频流。单流录制模式下，如果参数为空，默认录制对房间内所有人进行单流录制。最多17人。
Layout	Object of Layout	否		布局参数。

Streams

参数	类型	是否必选	示例值	描述
StreamList	Array of Stream	否	`-`	由`Stream`组成的列表，可以为空。为空时，表示订阅房间内所有流。在一个 `StreamList` 中，`Stream.Index` 不能重复。

Layout

参数类型是否必选示例值描述

参数	类型	是否必选	示例值	描述
LayoutMode	Integer	否	`0`	布局模式。默认值为 `0`，值的范围为 `{0, 1, 2, 3}`。 `0` 为自适应布局模式。参看自适应布局。 `1` 为垂直布局模式。参看垂直布局。 `2` 为自定义布局模式。 `3` 为并排布局模式。参看并排布局
MainVideoStream	Object of Stream	否		在垂直布局模式下生效，指定主画面流的属性。如果此参数为空，则主画面为随机的一路流。
CustomLayout	Object of CustomLayout	否		使用自定义布局模式时，使用此参数进行具体设置。

LayoutMode

Integer

否

0

布局模式。默认值为 0，值的范围为 {0, 1, 2, 3}。

0 为自适应布局模式。参看自适应布局。
1 为垂直布局模式。参看垂直布局。
2 为自定义布局模式。
3 为并排布局模式。参看并排布局

MainVideoStream Object of Stream 否在垂直布局模式下生效，指定主画面流的属性。如果此参数为空，则主画面为随机的一路流。

CustomLayout Object of CustomLayout 否使用自定义布局模式时，使用此参数进行具体设置。

Stream

参数	类型	是否必选	示例值	描述
Index	Integer	否	`0`	在自定义布局中，使用 `Index` 对流进行标志。后续在 `Layout.regions.StreamIndex` 中，你需要使用 `Index` 指定对应流的布局设置。
UserId	String	是	`Your_UserId`	用户Id，表示这个流所属的用户。
StreamType	Integer	否	`0`	流的类型，值可以取`0`或`1`，默认值为`0`。`0`表示普通音视频流，`1`表示屏幕流。

CustomLayout

参数类型是否必选示例值描述

Canvas Object of Canvas 否整体屏幕（画布）的宽高以及背景色。

参数	类型	是否必选	示例值	描述
Canvas	Object of Canvas	否		整体屏幕（画布）的宽高以及背景色。
Regions	Array of Region	否		在自定义布局模式下，你可以使用 `Regions` 对每一路视频流进行画面布局设置。其中，每个 `Region` 对一路视频流进行画面布局设置。自定义布局模式下，对于 `StreamList` 中的每个 `Stream`，`Regions` 中都需要给出对应的布局信息，否则会返回请求不合法的错误。即 `Regions.Region.StreamIndex` 要与 `TargetStreams.StreamList.Stream.Index` 的值一一对应，否则自定义布局设置失败，返回 `InvalidParameter` 错误码。当传入的必填参数值不合法时，返回错误码 `InvalidParameter` 。

Regions

Array of Region

否

在自定义布局模式下，你可以使用 Regions 对每一路视频流进行画面布局设置。其中，每个 Region 对一路视频流进行画面布局设置。
自定义布局模式下，对于 StreamList 中的每个 Stream，Regions 中都需要给出对应的布局信息，否则会返回请求不合法的错误。即 Regions.Region.StreamIndex 要与 TargetStreams.StreamList.Stream.Index 的值一一对应，否则自定义布局设置失败，返回 InvalidParameter 错误码。

当传入的必填参数值不合法时，返回错误码 InvalidParameter 。

Canvas

参数	类型	是否必选	示例值	描述
Width	Integer	否	`640`	整体屏幕（画布）的宽度，单位为像素，范围为 `[2, 1920]`，必须是偶数。默认值为 `640`。
Height	Integer	否	`480`	整体屏幕（画布）的高度，单位为像素，范围为 `[2, 1920]`，必须是偶数。默认值为 `480`。
Background	String	否	`#000000`	整体屏幕（画布）的背景色，格式为 #RGB(16进制)，默认值为 `#000000`（黑色）, 范围为 `#000000 ~ #ffffff` (大小写均可)。
BackgroundImage	String	否	`/`	背景图片的 URL。长度最大为 1024 byte。可以传入的图片的格式包括：JPG, JPEG, PNG。如果背景图片的宽高和整体屏幕的宽高不一致，背景图片会缩放到铺满屏幕。如果你设置了背景图片，背景图片会覆盖背景色。

Region

参数	类型	是否必选	示例值	描述
StreamIndex	Integer	是	`0`	流的标识。这个标志应和 `TargetStreams.StreamList.Stream.Index` 对应。
LocationX	Integer	否	`0`	视频流对应区域左上角的横坐标相对整体画面左上角原点的横向位移，取值的范围为 `[0.0, Canvas.Width)`。默认值为 `0`。若传入该参数，服务端会对该参数进行校验，若不合法会返回错误码 `InvalidParameter`。视频流对应区域左上角的实际坐标是通过画面尺寸和相对位置比例相乘，并四舍五入取整得到的。假如，画布尺寸为`1920`, 视频流对应区域左上角的横坐标相对整体画面的比例为 `0.33`，那么该画布左上角的横坐标为 `634`（1920*0.33=633.6，四舍五入取整）。
LocationY	Integer	否	`0`	视频流对应区域左上角的横坐标相对整体画面左上角原点的纵向位移，取值的范围为 `[0.0, Canvas.Height)`。默认值为 `0`。若传入该参数，服务端会对该参数进行校验，若不合法会返回错误码 `InvalidParameter`。
Width	Integer	是	`640`	视频流对应区域宽度的像素绝对值，取值的范围为 `(0.0, Canvas.Width]`。
Height	Integer	是	`480`	视频流对应区域高度的像素绝对值，取值的范围为 `(0.0, Canvas.Height]`。
ZOrder	Integer	否	`0`	当多个流的画面有重叠时，使用此参数设置指定画面的图层顺序。取值范围为 `[0, 100]`：`0` 表示该区域图像位于最下层，`100` 表示该区域图像位于最上层, 默认值为 `0`。
Alpha	Float	否	`1`	画面的透明度，取值范围为 `(0.0, 1.0]`。`0.0` 表示完全透明，`1.0` 表示完全不透明，默认值为 `1.0`。
RenderMode	Integer	否	`0`	画面的渲染模式，值的范围为 `{0, 1, 2，3}`, 默认值为 `0`： `0` 表示按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形 `1` 表示按照显示区域的长宽比裁减视频，然后等比拉伸或缩小视频，占满显示区域。 `2` 表示按照原始画面的宽高比缩放视频，在显示区域居中显示。如果原始画面宽高比与指定的宽高比不同，就会导致画面有空缺，空缺区域为填充的背景色值。 `3` 表示按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形。目前 `0` 和 `3` 均为按照指定的宽高直接缩放，但我们推荐你使用 `3` 以便与客户端实现相同逻辑。不同渲染模式下，效果如下：
SourceCrop	Object of SourceCrop	否		源流剪切功能，可以在源视频帧渲染之前进行裁剪，即预处理一次再渲染。
AlternateImage	String	否	`rtmp://xxx.xxx`	补位图片的 url。长度不超过 1024 个字符串。在 `Region.StreamIndex` 对应的视频流没有发布，或被暂停采集时，`AlternateImage` 对应的图片会填充 `Region` 对应的画布空间。当视频流被采集并发布时，`AlternateImage` 不造成任何影响。可以传入的图片的格式包括：JPG, JPEG, PNG。当图片和画布尺寸不一致时，图片根据 `RenderMode` 的设置，在画布中进行渲染。
ApplySpatialAudio	Boolean	否	`/`	该路流对应的用户是否开启空间音频效果。 `true`：开启空间音频效果。 `false`：关闭空间音频效果。默认值为 `true`
SpatialPosition	Array of Integer	否	`[0,0,0]`	空间音频下，房间内指定用户所在位置的三维坐标，默认值为`[0,0,0]`。数组长度为`3`，三个值依次对应`X`,`Y`,`Z`，每个值的取值范围为`[-100,100]`。
CornerRadius	Float	否	`0.1`	转推直播下边框圆角半径与画布宽度的比例值，取值范围为 `[0,1]`。圆角半径的像素位不能超过 Region 宽高最小值的一半，否则不会出现圆角效果。
MediaType	Integer	否	`0`	该路流参与混流的媒体类型。 `0`：音视频 `1`：纯音频 `2`：纯视频默认值为 `0`。假如该路流为音视频流，`MediaType`设为`1`，则只混入音频内容。
AlternateImageFillMode	Integer	否	`0`	画面的渲染模式。 `0`：按照用户原始视频帧比例进行缩放 `1`：保持图片原有比例默认值为 `0`。

SourceCrop

参数	类型	是否必选	示例值	描述
LocationX	Float	否	`0`	裁剪后得到的视频帧左上角的横坐标相对裁剪前整体画面的比例，取值的范围为 `[0.0, 1.0)`。默认值为 `0.0`。
LocationY	Float	否	`0`	裁剪后得到的视频帧左上角的纵坐标相对裁剪前整体画面的比例，取值的范围为 `[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`。

返回参数

本接口无特有的返回参数。公共返回参数请见返回结构。
其中返回值 Result 仅在请求成功时返回 ok,失败时为空。

请求示例

POST https://rtc.volcengineapi.com?Action=UpdateRecord&Version=2023-11-01

{
    "AppId": "Your_AppId",
    "BusinessId": "Your_BusinessId",
    "RoomId": "Your_RoomId",
    "TaskId": "Your_TaskId",
    "TargetStreams": {
        "StreamList": [
            {
                "Index": 0,
                "UserId": "Your_UserId_1",
                "StreamType": 1
            },
            {
                "Index": 1,
                "UserId": "Your_UserId_2"
            }
        ]
    },
    "Layout": {
        "LayoutMode": 2,
        "CustomLayout": {
            "Canvas": {
                "Width": 860,
                "Height": 340,
                "Background": "#303342"
            },
            "Regions": [
                {
                    "StreamIndex": 0,
                    "LocationX": 0,
                    "LocationY": 0,
                    "Width": 430,
                    "Height": 340,
                    "ZOrder": 0,
                    "Alpha": 1,
                    "RenderMode": 0
                },
                {
                    "StreamIndex": 1,
                    "LocationX": 430,
                    "LocationY": 0,
                    "Width": 430,
                    "Height": 340,
                    "ZOrder": 1,
                    "Alpha": 1,
                    "RenderMode": 1
                }
            ]
        }
    }
}
json

返回示例

{
    "Result": "ok",
    "ResponseMetadata": {
        "RequestId": "Your_RequestId",
        "Action": "UpdateRecord",
        "Version": "2023-11-01",
        "Service": "rtc",
        "Region": "cn-north-1"
    }
}
json

错误码

您可访问公共错误码，获取更多错误码信息。