调用StartStreamingOut接口启动旁路推流-音视频通信-阿里云

本接口用于开始旁路推流任务。

接口说明

使用说明

本接口用于开始在线频道旁路推流任务。

QPS 限制

本接口的单用户 QPS 限制为 10 次/秒。超过限制，API 调用会被限流，这可能会影响您的业务，请合理调用。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作	访问级别	资源类型	条件关键字	关联操作
rtc:StartStreamingOut	create	App `acs:rtc::{#accountId}:app/{#AppId}`	无	无

请求参数

名称	类型	必填	描述	示例值
AppId	string	是	应用 ID，通过控制台创建和查询，仅支持传单个 ID。	eo85****
ChannelId	string	是	已存在的频道 ID，仅支持传单个 ID。	testid
TemplateId	string	是	模版 ID。	567
Url	string	是	直播推流地址，仅支持传单个地址。该地址不可多个任务同时使用。	rtmp://example.com/live/stream
TaskId	string	否	本次旁路推流的任务 ID，仅支持传单个 ID。由大小写字母、数字、下划线、短划线（-）组成，最大 55 字节，不填，则由系统自动生成。	123
CropMode	integer	否	裁剪方式。取值： 1：保持比例裁剪。 2：保持比例留边（默认值）。 3：拉伸铺满。	2
ReservePaneForNoCameraUser	boolean	否	未推摄像头流用户窗格占位。默认为 true，表示用户未推摄像头流时保留一个窗格。为 false 时，表示用户未推摄像头流时不保留窗格。
ShowDefaultBackgroundOnMute	boolean	否	mute 时是否显示窗格默认底图。 true: 显示（默认值） false: 不显示（设置的局部窗格底图依然显示）
SubHighResolutionStream	boolean	否	订阅高分辨率流。 false：根据窗格面积订阅不同分辨率的流。（默认值） true：默认用客户端推的最高分辨率的流进行填充。
StartWithoutChannel	boolean	否	是否允许频道不存在时开启任务。 true: 是 false: 否（默认值）
StartWithoutChannelWaitTime	integer	否	当 StartWithoutChannel 参数为 true 的时候，设置该值才有意义，表示房间未开启时，任务等待时长，单位为秒，区间限制为[30,120]。	30
Annotation	string	否	标注开关。	disable
Panes	array<object>	否	单元格设置。	eo85****
	object	否
VideoOrder	string	否	SourceType 为 video 时，填充顺序。 screenFirst，屏幕共享优先（默认值） cameraFirst，摄像头优先	cameraFirst
SourceType	string	否	单元格媒体类型。取值： video：用户摄像头或者屏幕共享流（默认值）。 camera：摄像头流。 screen：共享屏幕流。 whiteboard：白板。	video
Images	array<object>	否	窗格局部图片水印。
	object	否
PaneImageCropMode	integer	否	裁剪方式。取值： 1：保持比例裁剪。 2：保持比例留边。 3：拉伸铺满。	2
Alpha	double	否	透明度。	0.9
X	double	是	横坐标。	0.2
Y	double	是	纵坐标。	0.3
Height	double	是	高。	0.2
Width	double	是	宽。	0.2
Layer	integer	否	z 轴层级。	0
Url	string	是	对应的图片内容在推流期间不支持更新。	https://aliyun.com/123xxx.jpg
Display	string	否	水印显示时机。 streamOnly：当前用户有视频流时显示（默认值）。 backup：当前用户无视频流时显示。 always：总是显示。	backup
Texts	array<object>	否	窗格局部文字水印。
	object	否
BoxBorderw	integer	否	矩形框线宽。	5
FontColor	object	否	字体颜色。
R	integer	否	R。	255
B	integer	否	B。	255
G	integer	否	G。	255
Texture	string	是	水印内容。	文字水印
Layer	integer	否	z 轴层级。	0
Font	integer	否	字体。 0：阿里巴巴普惠体 Regular 1：阿里巴巴普惠体 Light 2：阿里巴巴普惠体 Medium 3：阿里巴巴普惠体 Bold 4：阿里巴巴普惠体 Heavy 5：阿里妈妈数黑体 6：钉钉进步体 7：阿里妈妈刀隶体 8：阿里妈妈东方大楷 9：阿里妈妈方圆体	0
BoxColor	object	否	矩形框颜色。
R	integer	否	R。	255
B	integer	否	B。	255
G	integer	否	G。	255
FontSize	integer	否	字体大小。	36
Alpha	double	否	水印透明度。	0.9
X	double	是	横坐标。	0.2
HasBox	boolean	否	是否需要矩形框。
Y	double	是	纵坐标。	0.2
BoxAlpha	double	否	矩形框透明度。	0.6
Display	string	否	水印显示时机。 streamOnly：当前用户有视频流时显示（默认值）。 backup：当前用户无视频流时显示。 always：总是显示。	backup
PaneCropMode	integer	否	裁剪方式。取值： 1：保持比例裁剪。 2：保持比例留边。 3：拉伸铺满。	2
PaneId	string	是	窗格 ID，从 0 开始。	0
Source	string	否	单元格媒体源。可指定 userId，如需指定特定用户类型。可使用通配符配置，支持以下类型。 $ActiveSpeaker：当前频道发言人 $ScreenShare：屏幕共享用户，当频道中有多个屏幕共享时，将按照先后顺序依次填充	22
Backgrounds	array<object>	否	局部背景图片
	object	否
Alpha	double	否	透明度。	0.9
X	double	是	横坐标。	0.2
Y	double	是	纵坐标。	0.2
PaneBackgroundCropMode	integer	否	裁剪方式。取值： 1：保持比例裁剪。 2：保持比例留边。 3：拉伸铺满。	2
Height	double	是	高。	0.2
Width	double	是	宽。	0.3
Layer	integer	否	z 轴层级。	0
Url	string	是	图片地址。	https://aliyun.com/123xx.jpg
Display	string	否	显示时机。 streamOnly：当前用户有视频流时显示（默认值）。 backup：当前用户无视频流时显示。 always：总是显示。	backup
Whiteboard	object	否	白板配置。
WhiteboardId	string	否	白板 ID，默认为 default。	default
ReservePaneForOfflineUser	boolean	否	未入会用户窗格占位。默认为 true，表示宫格指定的具体用户或通配符用户离线时，窗格强制占位。为 false 时，表示宫格指定的具体用户或通配符用户离线时，将按自动填充顺序显示视频流。
Backgrounds	array<object>	否	背景图片。
	object	否
BackgroundCropMode	integer	否	裁剪方式。取值： 1：保持比例裁剪。 2：保持比例留边。 3：拉伸铺满。	2
Alpha	double	否	透明度。	0.9
X	double	是	横坐标。	0.2
Y	double	是	纵坐标。	0.2
Height	double	是	高。	0.2
Width	double	是	宽。	0.2
Layer	integer	否	z 轴层级。	0
Url	string	是	图片地址。	https://aliyun.com/123.jpg
Images	array<object>	否	全局图片水印。	30
	object	否
Alpha	double	否	透明度。	0.9
X	double	是	横坐标。	0.2
Y	double	是	纵坐标。	0.2
Height	double	是	高。	0.2
ImageCropMode	integer	否	裁剪方式。取值： 1：保持比例裁剪。 2：保持比例留边。 3：拉伸铺满。	2
Width	double	是	宽。	0.2
Layer	integer	否	z 轴层级。	0
Url	string	是	图片地址。对应的图片内容在推流期间不支持更新	https://aliyun.com/123xxx.jpg
Texts	array<object>	否	全局文字水印。
	object	否
BoxBorderw	integer	否	矩形框线宽。	5
BoxColor	object	否	矩形框颜色。
R	integer	否	R。	255
B	integer	否	B。	255
G	integer	否	G。	255
FontSize	integer	否	字体大小。	36
Alpha	double	否	水印透明度。	0.1
FontColor	object	否	字体颜色。
R	integer	否	R。	255
B	integer	否	B。	255
G	integer	否	G。	255
X	double	是	横坐标。	0.2
HasBox	boolean	否	是否需要矩形框。
Y	double	是	纵坐标。	0.2
Texture	string	是	水印内容。	文字水印
Layer	integer	否	z 轴层级。	0
Font	integer	否	字体。 0：阿里巴巴普惠体 Regular 1：阿里巴巴普惠体 Light 2：阿里巴巴普惠体 Medium 3：阿里巴巴普惠体 Bold 4：阿里巴巴普惠体 Heavy 5：阿里妈妈数黑体 6：钉钉进步体 7：阿里妈妈刀隶体 8：阿里妈妈东方大楷 9：阿里妈妈方圆体	0
BoxAlpha	double	否	矩形框透明度。	0.6
ClockWidgets	array<object>	否	全局时钟水印。
	object	否
BoxBorderw	integer	否	矩形框线宽。	5
BoxColor	object	否	矩形框颜色。
R	integer	否	R。	255
B	integer	否	B。	255
G	integer	否	G。	255
FontSize	integer	否	时钟字体大小。	30
Zone	integer	否	时区。	8
Alpha	double	否	透明度。	0.9
FontColor	object	否	字体颜色。
R	integer	否	R。	255
B	integer	否	B。	255
G	integer	否	G。	255
X	double	是	横坐标。	0.2
HasBox	boolean	否	是否需要矩形框。
Y	double	是	纵坐标。	0.2
Layer	integer	否	z 轴层级。	0
Font	integer	否	字体。 0：阿里巴巴普惠体 Regular 1：阿里巴巴普惠体 Light 2：阿里巴巴普惠体 Medium 3：阿里巴巴普惠体 Bold 4：阿里巴巴普惠体 Heavy 5：阿里妈妈数黑体 6：钉钉进步体 7：阿里妈妈刀隶体 8：阿里妈妈东方大楷 9：阿里妈妈方圆体	0
BoxAlpha	double	否	矩形框透明度。	0.6
RegionColor	object	否	全局框格底色
R	integer	否	R。	255
G	integer	否	G。	255
B	integer	否	B。	255
BgColor	object	否	全局背景色
R	integer	否	R。	255
G	integer	否	G。	255
B	integer	否	B。	255
LayoutSpecifiedUsers	object	否	布局生成用户指定列表，包括黑/白名单两种。白名单，指定订阅房间里哪些用户视频流。设置后自动填充根据该列表进行顺序填充模版多布局切换时只计算白名单中的人黑名单，指定不订阅房间里哪些用户视频流。模版多布局切换时只计算非黑名单中的人
Type	string	是	用户名单类型，黑名单：black，白名单：white。	white
Ids	array	是	指定用户 ID 列表。
	string	是	具体用户 ID。	123
SpecMixedUserList	array	否	指定需要被混音的用户列表。
	string	否	用户 ID。	456

注意相关补充

局部图片水印数量、局部背景图片水印、全局图片水印数量和全局背景图数量的总和不能超过 16。

高级水印层次说明

RTC 媒体服务器生成的画面会分成以下几个步骤：

绘制视频 -> 绘制图片 -> 绘制文字

视频、图片、文字是完全分开的，从整个画面来看文字优先级 > 图片 > 视频

绘制视频：根据客户定义的布局对视频画面进行布局

a. 宫格中的图片和全局图片的 layer 统一排列。

b. layer 0 位于最底层，layer 越大越位于上方，layer 的取值范围为[0,100] 。
绘制图片图片包括用户自定义的 png/jpg 图片。

a. 根据用户配置宽高、位置、透明度等信息进行绘制。

b. layer 0 位于最底层，layer 越大越位于上方，layer 的取值范围为[0,100] 。
绘制文字文字分为 3 个类型：区域文字全局文字和时间戳文字。

a. 同一类型文字根据 layer 顺序绘制，layer 0 位于最底层，layer 越大越位于上方，layer 的取值范围为[0,100] 。

b. 不同类型文字优先级为：时间戳文字 > 全局文字 > 区域文字。处于重叠位置时，优先级较低的将被覆盖。

重叠部分的显示：

重叠部分，如果没有特别配置，高优先级将覆盖低优先级。
低优先级内容如果不想被高优先级内容覆盖，可以设置高优先级内容的透明度属性为 0。

返回参数

名称	类型	描述	示例值
	object	返回结果。
TaskId	string	本次旁路推流的任务 ID。	123
RequestId	string	请求 ID。	16A96B9A-F203-4EC5-8E43-CB92E68F4CF8

示例

正常返回示例

JSON格式

{
  "TaskId": 123,
  "RequestId": "16A96B9A-F203-4EC5-8E43-CB92E68F4CF8"
}

错误码

访问错误中心查看更多错误码。

变更历史

变更时间	变更内容概要	操作
2025-04-15	OpenAPI 入参发生变更	查看变更详情
2025-02-21	OpenAPI 入参发生变更	查看变更详情
2025-02-12	API 内部配置变更，不影响调用	查看变更详情
2024-12-16	OpenAPI 入参发生变更	查看变更详情
2024-11-06	OpenAPI 入参发生变更	查看变更详情
2024-03-20	API 内部配置变更，不影响调用	查看变更详情