更新合流转推 UpdatePushMixedStreamToCDN--实时音视频-火山引擎

文档中心

导航

更新合流转推 UpdatePushMixedStreamToCDN

最近更新时间：2025.07.03 18:15:26首次发布时间：2024.01.03 20:25:17

本文档 API 接口为最新版本接口，后续相关功能的新增都会在此更新，推荐使用最新版本接口。旧版接口文档请参考历史版本。

在实时音视频通话场景中，若你已启动合流转推任务，你可以通过调用此接口实现对任务特定参数的更新，包括调整转推包含的音视频流、自定义布局设置、编码参数以及控制选项等。这些更新允许你在不中断现有流的情况下，动态优化直播质量和布局。
请在收到 TranscodeStarted 回调事件后再执行更新操作，否则可能导致更新不成功。

调用此接口时，你需要确保为自定义布局模式，即 Layout.LayoutMode = 2。

使用说明

接口行为

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

TargetStreams
Layout.CustomLayout.Canvas.Background 、Layout.CustomLayout.Canvas.BackgroundImage 和 Layout.CustomLayout.Regions
Encode 中，除 audioProfile、videoCodec 以外的参数。
Control.SpatialConfig
Control.SEIConfig.UserConfigExtraInfo

通过此 OpenAPI，你无法更新除上述参数以外的参数。并且，对于上述参数，如果你在调用 OpenAPI 时，没有传入对应的值，那么，合流转推时使用的值将会被更新为默认值。

注意事项

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

请求说明

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

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

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

Query

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

Body

参数	类型	是否必选	示例值	描述
AppId	String	是	`661e****543cf`	你的音视频应用的唯一标志，参看获取 AppId。
BusinessId	String	否	`B****23`	业务标识
RoomId	String	是	`Room1`	房间的 ID，是房间的唯一标志
TaskId	String	是	`Task1`	合流转推任务 ID。你必须对每个合流转推任务，设定 TaskId，且在进行任务更新时也须使用该 TaskId。 `TaskId` 是任务的标识，在一个 `AppId` 的 `RoomId` 下 `taskId` 是唯一的，不同 `AppId` 或者不同 `RoomId` 下 `TaskId` 可以重复，因此 `AppId` + `RoomId` + `TaskId` 是任务的唯一标识，可以用来标识指定 `AppId` 下某个房间内正在运行的任务，从而能在此任务运行中进行更新或者停止此任务。关于 TaskId 及以上 Id 字段的命名规则符合正则表达式：`[a-zA-Z0-9_@\-\.]{1,128}`
TargetStreams	Object	否	`-`	转推包含的房间内的流。
StreamList	Object[]	否	`-`	音视频流列表，由`Stream`组成，可以为空。为空时，表示订阅房间内所有流。在一个 `StreamList` 中，`Stream.Index` 不能重复。
Layout	Object	否	`-`	房间内多路流合为一路时的布局参数
LayoutMode	Integer	否	`0`	布局模式。支持取值及含义如下： `0`：自适应布局。 `1`：垂直布局 `2` ：自定义布局。 `3` ：并排布局默认值为`0`
MainVideoStream	Object	否	`-`	在垂直布局模式下生效，指定主画面流的属性。垂直布局时，此参数必填。
CustomLayout	Object	否	`-`	使用自定义布局模式时，使用此参数进行具体设置。
Encode	Object	否	`-`	音视频编码参数
VideoWidth	Integer	否	`640`	画面宽度。取值范围为 `[2, 1920]`，必须是偶数，单位为像素，默认值为 `640`。该参数在垂直布局和并排布局下生效，自定义布局下请使用 `canvas.Width` 设置画面宽度。
VideoHeight	Integer	否	`480`	画面高度，取值范围为 `[2, 1920]`，必须是偶数，单位为像素，默认值为 `480`。该参数在垂直布局和并排布局下生效，自定义布局下请使用 `canvas.Height` 设置画面宽度。
VideoFps	Integer	否	`15`	视频帧率。取值范围为 `[1, 60]`，单位为 `FPS`，默认值为 `15`。
VideoBitrate	Integer	否	`0`	视频码率。取值范围为 `[0, 10000]`，单位为 Kbps，默认值为 `0`。 `0` 表示自适应码率，会自动根据 `VideoFps`、`VideoWidth` 以及 `VideoHeight` 计算出合理的码率。自适应码率模式下，RTC 默认不会设置超高码率。如果订阅屏幕流，建议自行设置高码率。不同场景下设置码率等视频发布参数，请参考设置视频发布参数。
VideoCodec	Integer	否	`0`	视频编码协议。支持取值及含义如下： `0`：`H.264` `1`：`ByteVC1` 默认值为 `0`。
VideoGop	Integer	否	`4`	输出视频 GOP。取值范围为 `[1, 5]`，单位为秒，默认值为 `4`。
AudioCodec	Integer	否	`0`	音频编码协议。仅支持取 `0`，表示 AAC 编码协议。
AudioProfile	Integer	否	`0`	音频配置文件类型。支持取值及含义如下： `0` :采用 LC 规格。 `1`: 采用 HE-AAC v1 规格。 `2`: 采用 HE-AAC v2 规格。此时，只支持输出流音频声道数为双声道。默认值为 `0`。
AudioBitrate	Integer	否	`64`	音频码率。取值范围为 `[32, 192]`，单位为 `Kbps`。该参数若不填，RTC 会根据音频配置文件类型、采样率、声道数的配置生成音频码率取值。该参数若填写，实际生效的码率也会随着音频配置文件类型、采样率、声道数的配置而变化。若你发现生效的码率值没有达到你设定的值，可能是该值已经超过该场景下的极限码率。
AudioSampleRate	Integer	否	`48000`	音频采样率。可取值为：`{32000, 44100，48000}`，单位为 Hz，默认值为 `48000`。
AudioChannels	Integer	否	`2`	音频声道数。支持取值及含义如下： `1`：单声道。 `2`：双声道。默认值为 `2`。
Control	Object	否	`-`	配置选项。若合流转推的音频参数设置为单声道，空间音频无效。
MediaType	Integer	否	`0`	流的类型，用于全局控制订阅的流的类型。支持取值及含义如下： `0` ：音视频。 `1` ：纯音频。默认值为 `0`。
FrameInterpolationMode	Integer	否	`0`	选择补帧模式。支持取值及含义如下： `0`：补最后一帧。 `1`：补黑帧。默认值为`0`。自动布局模式下，没有补帧的逻辑。补帧是指在音视频录制或合流转推时，视频的帧率通常是固定的。但是，因为网络波动或其他原因，实际帧率可能无法达到预设的帧率。此时，需要补帧以保持视频流畅。补最后一帧意味着补充的视频帧和中断前的最后一帧相同，此时看到的画面可能会有短暂静止；补黑帧意味着补充的视频帧是全黑的。使用占位图、补帧和上一帧的关系: 你可以在 `Region` 中传入 `Alternateimage` 字段设置占位图,在 `Control` 中传入 `FrameInterpolationMode` 字段设置补帧模式,但占位图优先级高于补帧模式。在 `Region.StreamIndex` 对应的视频流停止发布时, `Region` 对应的画布空间会根据设置填充占位图或补帧。但当视频流为屏幕流时，补帧模式不生效。当 `Region.StreamIndex` 对应的视频流发布后停止采集或推送时, `Region` 对应的画布空间会填充上一帧。当 `Region.StreamIndex` 对应的视频流发布时,设置的占位图或补顿模式不造成任何影响。
MaxIdleTime	Integer	否	`180`	任务的空闲超时时间，超过此时间后，任务自动终止。取值范围为 `[10, 86400]`，单位为秒。默认值为 `180`。
SpatialConfig	Object	否	`-`	空间音频配置。若合流转推的音频参数设置为单声道，空间音频无效。
PushStreamMode	Integer	否	`0`	转推直播推流模式，用于控制触发推流的时机。支持取值及含义如下： `0`：房间内有用户推 RTC 流时即触发 CDN 推流。 `1`：调用接口发起推流任务后，无论房间内是否有用户推 RTC 流,均可触发 CDN 推流。默认值为 `0`。任务超时逻辑不变，依然是无用户推流即判定为超时。
SEIConfig	Object	否	`-`	SEI 相关配置。
IsUpdatePartialParam	Boolean	否	`false`	是否更新部分参数。 `false`：否。 `true`：是。默认值为 `false`。开启部分更新后，必须按照参数层级传入，且数组类参数需要传入该数组中所有参数。
SequenceNumber	Integer	否	`0`	更新请求序列号。填写该参数后，服务端会对请求进行校验，请确保最后一次更新请求的序列号大于前一次请求的序列号。建议更新部分参数场景下传入此参数，以确保服务端按照最新请求进行更新。

返回参数

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

请求示例

POST https://rtc.volcengineapi.com?Action=UpdatePushMixedStreamToCDN&Version=2023-11-01
{
    "AppId": "661e****543cf",
    "BusinessId": "B****23",
    "RoomId": "Room1",
    "TaskId": "Task1",
    "TargetStreams": {
        "StreamList": [
            {
                "Index": 0,
                "UserId": "user1_3"
            },
            {
                "Index": 1,
                "UserId": "user1_4",
                "StreamType": 1
            }
        ]
    },
    "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
                }
            ]
        }
    }
}

返回示例

{
    "Result": "ok",
    "ResponseMetadata": {
        "RequestId": "20230****10420",
        "Action": "UpdatePushMixedStreamToCDN",
        "Version": "2023-11-01",
        "Service": "rtc",
        "Region": "cn-north-1"
    }
}

错误码

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