数据结构 - 音视频通话 2.0

开发者中心

音视频通话 2.0

服务端 API

数据结构

更新时间： 2025/10/30 16:41:12

本文介绍了网易云信音视频通话 2.0 部分服务端接口的共同参数结构。

recordConfig

录制模式。

被以下接口引用：

参数名称	类型	是否必选	示例值	说明
recordType	Number	否	1	录制模式。默认值为 0。录制模式的详细说明，请参考录制模式。可设置为： 0：合流+单流录制。 1：合流录制。 2：单流录制。 100：模板文件集合模式。
- modeList	JsonArray	否	-	模板文件集合模式列表。`recordType` 填 `100` 时，该字段必填。
mode	Number	否	0	录制模式： 0：单流录制。 1：录制带有共享屏幕的画廊视图。 2：录制带有共享屏幕的当前演讲者。 3：单独录制当前演讲者。 4：单独录制画廊视图。 5：单独录制屏幕共享。 6：录制单独音频文件。 100：单人视频+混合音频，每个用户单独生成文件。
layoutType	Number	否	0	布局类型，默认为通过控制台设置的自定义布局。录制模式的详细说明，请参考录制布局。可设置为： 0：画廊模式。 1：主讲人模式。 2：自定义布局。 3：悬浮布局。 4：垂直布局。
layout	Object	否	0	自定义布局时，设置合流录制的画面布局。详细的参数说明，请参考使用自定义布局。
watermark	Object	否	-	水印配置。详细信息请参见 watermark。
- userNameDisplay	Object	否	-	用户名显示配置。
enable	Boolean	否	true	是否启用用户名展示。
position	Number	否	0	用户名显示位置。取值范围 [0, 8]，默认 0。 `0`：左下角 `1`：下方居中 `2`：右下角 `3`：左边居中 `4`：正中心 `5`：右边居中 `6`：左上角 `7`：上方居中 `8`：右上角
fontSize	Number	否	12	用户名字体大小字号。默认 12。
fontColor	String	否	"#FFFFFF"	用户名字体颜色（十六进制 RGB 值、或字符串）。默认为 "#FFFFFF"，表示白色。
fontAlpha	Number	否	255	用户名字体透明度。取值范围 [0, 255]，0 表示全透明，255 表示不透明。默认为 255。
bgColor	String	否	"#000000"	用户名背景颜色（十六进制 RGB 值、或字符串）。默认为 "#000000"，表示黑色。
bgAlpha	Number	否	128	用户名背景透明度。取值范围 [0, 255]，0 为全透明，255 为不透明。默认为 128，表示半透明。
offsetX	Number	否	20	显示位置横向偏移，相对窗口宽度百分比。取值范围 [-100, 100]，默认为 0。
offsetY	Number	否	-20	显示位置纵向偏移，相对窗口高度百分比。取值范围 [-100, 100]，默认为 0。

layoutConfig

录制布局配置。

被以下接口引用：

参数名称	类型	是否必选	示例值	说明
layoutType	Number	否	0	布局类型，默认为通过控制台设置的自定义布局。录制模式的详细说明，请参考录制布局。可设置为： 0：画廊模式 1：主讲人模式 2：自定义布局。 3：悬浮布局。 4：垂直布局。
hostUid	Number	否	66602	主讲人 UID。支持在主讲人模式、悬浮布局和垂直布局下设置。
layout	Object	否	无	自定义布局时，设置合流录制的画面布局。详细的参数说明，请参考使用自定义布局。

参数名称

类型

是否必选

示例值

说明

layoutType

Number

否

布局类型，默认为通过控制台设置的自定义布局。录制模式的详细说明，请参考录制布局。可设置为：

0：画廊模式
1：主讲人模式
2：自定义布局。
3：悬浮布局。
4：垂直布局。

hostUid

Number

否

66602

主讲人 UID。
支持在主讲人模式、悬浮布局和垂直布局下设置。

layout

Object

否

无

自定义布局时，设置合流录制的画面布局。详细的参数说明，请参考使用自定义布局。

streamSubscribe

录制订阅配置。

被以下接口引用：

参数名称	类型	是否必选	示例值	说明
streamType	Number	否	1	音视频订阅类型。默认值为 2。可设置为： 0：仅订阅音频。 1：仅订阅视频。 2：订阅音频和视频。
audioUidList	Object	否	无	音频订阅名单，可指定黑名单或白名单。黑名单和白名单不可同时指定。若您希望订阅音频，必须设置 audioUidList。若指定 streamType 为 1，同时设置 audioUidList 时会报错 414。
audioUidList.unSubscribeUids	JsonArray	否	无	音频订阅黑名单，即不订阅哪些用户的音频流。不可与 audioUidList.subscribeUids 同时设置。若此参数传空，表示音频流全订阅。
audioUidList.subscribeUids	JsonArray	否	无	音频订阅白名单，即订阅哪些用户的音频流。不可与 audioUidList.unSubscribeUids 同时设置。若此参数传空，表示音频流全不订阅。
videoUidList	Object	否	无	视频订阅名单，可指定黑名单或白名单。黑名单和白名单不可同时指定。若您希望订阅视频，必须设置 videoUidList。若指定 streamType 为 0，同时设置 videoUidList 时会报错 414。
videoUidList.unSubscribeUids	JsonArray	否	无	视频订阅黑名单，即不订阅哪些用户的视频流。不可与 videoUidList.subscribeUids 同时设置。若此参数传空，表示视频流全订阅。
videoUidList.subscribeUids	JsonArray	否	无	视频订阅白名单，即订阅哪些用户的视频流。不可与 videoUidList.unSubscribeUids 同时设置。若此参数传空，表示视频流全不订阅。

detect

内容安全审核配置。

被以下接口引用：

参数名称	类型	是否必选	示例值	说明
enableSpamDetect	Boolean	否	TRUE	是否开启云端录制文件内容安全审核。可设置为： true：开启。 false：（默认）关闭。
scFrequency	Number	否	10	安全审核截图检测频率，取值范围为 1 ~ 60 秒。默认 5 秒截图检测一次。
detectType	Number	否	1	检测类型。可设置为： 0：（默认）视频与音频同时检测。 1：仅检测视频。

参数名称

类型

是否必选

示例值

说明

enableSpamDetect

Boolean

否

TRUE

是否开启云端录制文件内容安全审核。可设置为：

true：开启。
false：（默认）关闭。

scFrequency

Number

否

安全审核截图检测频率，取值范围为 1 ~ 60 秒。默认 5 秒截图检测一次。

detectType

Number

否

检测类型。可设置为：

0：（默认）视频与音频同时检测。
1：仅检测视频。

watermark

水印配置。

被以下接口引用：

watermark 包含的字段说明如下表所示。

参数名称	类型	是否必选	示例值	说明
imgWms	watermark.imgWms	否	-	图片水印配置。若设置则必须填写 `imgWms` 中所有字段。
transparentLayers	watermark.transparentLayers	否	-	透明层水印框配置。若设置则必须填写 `transparentLayers` 中所有字段。
literaWms	watermark.literaWms	否	-	文字水印配置。若设置则必须填写 `literaWms` 中所有字段。
timestampWm	watermark.timestampWm	否	-	时间戳水印配置。设置则必须填写 `timestampWm` 中所有字段。

支持多个水印叠加，叠加后图层展示的优先顺序为：时间戳 > 文字 > 透明层 > 图片。

watermark.imgWms

imgWms 的参数说明如下表所示。

参数名称	类型	是否必选	示例值	说明
url	String	是	https://freepngimg.com/XXX/XXX/3-2-love-hearts-eyes-emoji-png.png	图片地址。
wmWidth	Number	是	100	图片宽度。
wmHeight	Number	是	100	图片高度。
offsetX	Number	是	0	图片水印左上角与视频画布左上角的水平距离。
offsetY	Number	是	0	图片水印左上角与视频画布左上角的垂直距离。

watermark.transparentLayers

transparentLayers 的参数说明如下表所示。

参数名称	类型	是否必选	示例值	说明
offsetX	Number	是	0	水印框左上角与视频画布左上角的水平距离。
offsetY	Number	是	0	水印框左上角与视频画布左上角的垂直距离。
wmWidth	Number	是	480	水印框宽度。
wmHeight	Number	是	100	水印框高度。
bgTransparency	Number	是	1	水印框透明度。可设置为： 1：透明度高。 2：透明度中等。 3：透明度低。

watermark.literaWms

literaWms 的参数说明如下表所示。

参数名称	类型	是否必选	示例值	说明
wmLitera	String	是	您好啊 xxxxJJJJJLLLL	文字水印内容。
fontSize	Number	是	50	文字大小。
fontColor	String	是	#FF0000	文字颜色。格式为 #RRGGBB。最大值为 #FFFFFF。
offsetX	Number	是	0	文字水印左上角与视频画布左上角的水平距离。
offsetY	Number	是	0	文字水印左上角与视频画布左上角的垂直距离。

watermark.timestampWm

timestampWm 的参数说明如下表所示。

参数名称	类型	是否必选	示例值	说明
fontSize	Number	是	50	时间戳的字体大小。
fontColor	String	是	#FF0000	时间戳的字体颜色。格式为 #RRGGBB。最大值为 #FFFFFF。
offsetX	Number	是	0	时间戳水印左上角与视频画布左上角的水平距离。
offsetY	Number	是	0	时间戳水印左上角与视频画布左上角的垂直距离。

layout

旁路推流画面布局设置。配置示例请参考旁路推流画面布局。

被以下接口引用：

参数名称	类型	是否必选	示例值	说明
canvas	layout.canvas	是	-	用于设置混流视频的整体画布属性。
users	layout.users	是	-	用于设置混流视频中每个参与者对应的画面属性。注意：用户窗口边界不能超出 canvas 画布。视频互动中最多添加 7 人，纯语音互动中最多添加 21 人。如果人数超限，可能会造成服务故障。
subStreams	layout.subStreams	否	-	用于设置混流视频中所有参与者发布的视频辅流对应的画面属性。开启辅流形式屏幕共享之后，辅流画面默认展示为指定布局样式，详细信息请参考存在辅流的模板布局。您也可以通过此参数调整每个辅流画面在直播画面中的位置。
images	layout.images	否	-	用于设置混流视频中占位图片属性。若参数 users 指定的用户未上线，会在其对应的区域展示占位图片。

layout.canvas

canvas 参数说明：

参数名称	类型	是否必选	示例值	说明
height	Number	是	640	整体画布的高度，单位为 px。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。整体画布的高度与宽度的乘积不得大于 1920*1080。
width	Number	是	0	整体画布的宽度，单位为 px。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。整体画布的高度与宽度的乘积不得大于 1920*1080。
color	String	否	0	画面背景颜色，默认为 0，即黑色。支持以下格式的颜色码： 256 * 256 * R + 256 * G + B 的和。请将对应 RGB 的值分别带入此公式计算即可。十六进制颜色码，即#RRGGBB 或 RRGGBB 格式。例如 #CC00FF。

参数名称

类型

是否必选

示例值

说明

height

Number

是

640

整体画布的高度，单位为 px。
取值范围为 0~1920，若设置为奇数值，会自动向下取偶。整体画布的高度与宽度的乘积不得大于 1920*1080。

width

Number

是

整体画布的宽度，单位为 px。
取值范围为 0~1920，若设置为奇数值，会自动向下取偶。整体画布的高度与宽度的乘积不得大于 1920*1080。

color

String

否

画面背景颜色，默认为 0，即黑色。支持以下格式的颜色码：

256 * 256 * R + 256 * G + B 的和。请将对应 RGB 的值分别带入此公式计算即可。
十六进制颜色码，即#RRGGBB 或 RRGGBB 格式。例如 #CC00FF。

layout.users

users 参数说明：

参数名称	类型	是否必选	示例值	说明
uid	Number	是	1111	将指定 uid 对应用户的视频流拉入直播。如果添加多个 users，则 uid 不能重复。
x	Number	是	0	通过 x 和 y 指定画布坐标中的一个点，该点将作为用户图像的左上角。 x 参数用于设置画布的横轴坐标值。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
y	Number	是	0	通过 x 和 y 指定画布坐标中的一个点，该点将作为用户图像的左上角。 y 参数用于设置画布的纵轴坐标值。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
width	Number	是	360	该用户图像在画布中的宽度。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
height	Number	是	360	该用户图像在画布中的高度。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
adaption	Number	否	1	用于设置占位图片和指定区域的适应属性。可设置为： 0：适应图片。即保证视频内容全部显示，未覆盖区域默认填充背景色。 1：适应区域。即保证所有区域被填满，视频超出部分会被裁剪。若未设置，则默认为 1。
pushAudio	Boolean	否	true	是否在直播中混流该用户的对应音频流。可设置为： true：在直播中混流该用户的对应音频流。 false：在直播中将该用户设置为静音。若未设置，默认为 true。
pushVideo	Boolean	否	true	是否在直播中向观看者播放该用户的对应视频流。可设置为： true：在直播中播放该用户的视频流。 false：在直播中不播放该用户的视频流。若未设置，则默认为 true。
zOrder	Number	否	1	直播视频上用户视频帧的图层编号。取值范围为 0~100，默认为 0。最小值为 0（默认值），表示该区域图像位于最下层。最大值为 100，表示该区域图像位于最上层。

layout.subStreams

subStreams 参数说明：

参数名称	类型	是否必选	示例值	说明
uid	Number	是	1111	将指定 uid 对应用户的屏幕共享流拉入直播。如果添加多个 subStreams，则 uid 不能重复。
x	Number	是	360	通过 x 和 y 指定画布坐标中的一个点，该点将作为辅流视频的左上角。 x 参数用于设置画布的横轴坐标值。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
y	Number	是	0	通过 x 和 y 指定画布坐标中的一个点，该点将作为辅流视频的左上角。 y 参数用于设置画布的纵轴坐标值。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
width	Number	是	360	该辅流视频在画布中的宽度。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
height	Number	是	640	该辅流视频在画布中的高度。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
adaption	Number	否	1	用于设置占位图片和指定区域的适应属性。可设置为： 0：适应图片。即保证视频内容全部显示，未覆盖区域默认填充背景色。 1：适应区域。即保证所有区域被填满，视频超出部分会被裁剪。若未设置，则默认为 1。
pushAudio	Boolean	否	true	是否在直播中向观看者播放该用户的对应音频辅流。可设置为： true（默认）：在直播中播放该用户的音频辅流。 false：在直播中不播放该用户的音频辅流。
pushVideo	Boolean	否	true	是否在直播中向观看者播放该用户的对应视频辅流。可设置为： true（默认）：在直播中播放该用户的视频辅流。 false：在直播中不播放该用户的视频辅流。
zOrder	Number	否	1	直播视频上辅流视频的图层编号。取值范围为 0~100，默认为 0。最小值为 0（默认值），表示该区域图像位于最下层。最大值为 100，表示该区域图像位于最上层。

layout.images

images 参数说明：

参数名称	类型	是否必选	示例值	说明
url	String	是	www.163.com/test.jpg	占位图片的 URL。
x	Number	是	360	通过 x 和 y 指定画布坐标中的一个点，该点将作为占位图片的左上角。 x 参数用于设置画布的横轴坐标值。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
y	Number	是	0	通过 x 和 y 指定画布坐标中的一个点，该点将作为占位图片的左上角。 y 参数用于设置画布的纵轴坐标值。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
width	Number	是	360	该占位图片在画布中的宽度。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
height	Number	是	640	该占位图片在画布中的高度。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
adaption	Number	否	1	用于设置占位图片和指定区域的适应属性。可设置为： 0：适应图片。即保证视频内容全部显示，未覆盖区域默认填充背景色。 1：适应区域。即保证所有区域被填满，视频超出部分会被裁剪。若未设置，则默认为 1。
zOrder	Number	否	1	直播视频上辅流视频的图层编号。取值范围为 0~100，默认为 0。最小值为 0（默认值），表示该区域图像位于最下层。最大值为 100，表示该区域图像位于最上层。

users、subStream 和 images 三个属性均支持设置 zOrder 参数，但在视窗有重叠部分的情况下，三者图层展示的优先顺序为 users > subStream > images。
images 支持最多设置 6 张图片。

rtmpTasks

推流任务详情。

被以下接口引用：查询所有旁路推流任务。

参数名称	类型	是否必选	示例值	说明
taskId	String	-	stream_1	自定义的推流任务 ID。请保证此 ID 唯一。
streamUrl	String	-	rtmp://test.url	推流地址，例如 rtmp://test.url。此处的推流地址可设置为网易云信直播产品中服务端 API 创建房间的返回参数 pushUrl。
layout	Object	-	-	互动直播中的布局相关参数。参数详情请参考 layout。布局参数的配置方式及典型配置示例请参考旁路推流画面布局。
record	Boolean	-	true	旁路推流是否需要进行音视频录制。
version	Number	-	1	推流任务版本，此处请设置为 1。
hostUid	Number	-	111	主播的 UID。
config	Object	-	-	音视频流配置。详细参数说明，请参考 config。
extraInfo	String	-	abc	自定义的媒体补充增强信息。

rtmpTask

推流任务详情。

被以下接口引用：查询指定旁路推流任务。

参数名称	类型	是否必选	示例值	说明
taskId	String	-	stream_1	自定义的推流任务 ID。请保证此 ID 唯一。
streamUrl	String	-	rtmp://test.url	推流地址，例如 rtmp://test.url。此处的推流地址可设置为网易云信直播产品中服务端 API 创建房间的返回参数 pushUrl。
layout	Object	-	-	互动直播中的布局相关参数。参数详情请参考 layout。布局参数的配置方式及典型配置示例请参考旁路推流画面布局。
record	Boolean	-	true	旁路推流是否需要进行音视频录制。
version	Number	-	1	推流任务版本，此处请设置为 1。
hostUid	Number	-	111	主播的 UID。
config	Object	-	-	音视频流配置。详细参数说明，请参考 config。
extraInfo	String	-	abc	自定义的媒体补充增强信息。

config

旁路推流时的音视频流配置。

被以下接口引用：

参数名称	类型	是否必选	示例值	说明
singleVideoNoTrans	Boolean	否	true	单路视频透传开关，可选。默认为启用状态（`true`）。开启后，如果房间中只有一路视频流输入，则不对输入视频流进行转码，不遵循转码布局，直接推流 CDN。
subAllAudio	Boolean	否	true	互动直播中是否订阅所有用户的音频流。可选，默认为关闭状态。开启后，房间中所有成员的音频流均会被混流后推往 CDN。
- audioParam	Object	-	无	音频编码参数。
bitRate	Number	否	128	音频推流码率，可选。单位为 kbps，取值范围为 10~192。语音场景建议设置为 64 及以上码率，音乐场景建议设置为 128 及以上码率。
sampleRate	Number	否	48000	音频推流采样率。单位为 Hz，可设置为： 32000：采样率为 32 kHz。 44100：采样率为 44.1 kHz。（默认）48000：采样率为 48 kHz。
channels	Number	否	1	音频推流声道数。 1：单声道。 2：（默认）双声道。
codecProfile	Number	否	1	音频编码规格。 0：（默认）LC-AAC 规格，表示基本音频编码规格。 1：HE-AAC 规格，表示高效音频编码规格。
- videoParam	Object	-	无	视频编码参数。
frameRate	Number	否	20	帧率，每秒视频帧数，单位为 fps，取值范围为 1~30，默认 20
bitRate	Number	否	1000	视频推流码率，单位为 kbps，取值范围为 1~10000。
gopSize	Number	否	20	视频推流关键帧间隔，取值范围为 1~1000，默认取值 frameRate。

data

云端播放任务信息。

被以下接口引用：

参数名称	类型	是否必选	示例值	说明
streamUrl	String	是	rtmp://example.yunxin.io/live/class32/101	实时媒体流直播拉流地址，或音视频文件点播地址。支持如下协议和格式：协议：HTTP、HTTPS、RTMP、RTSP、HLS 格式：FLV、MP4、MPEG-TS、Matroska (MKV)、MP3、wav 不支持中文等特殊字符，且该字段长度不能超过 1024 字节。
uid	Number	是	101	用户 ID。该 uid 房间内唯一，请勿与其他用户 ID 重复。
idleTimeout	Number	否	300	云端播放器处于空闲状态的最大时长（秒），不可设置超过 24 小时。当媒体流为非播放状态的时长超过该设定值时，任务会自动销毁。
playTs	Number	否	1575508644	云端播放器开始播放在线媒体流时的 Unix 时间戳（秒）。当 playTs = 0 或为当前时间时，云端播放器在创建成功时自动播放在线媒体流。当 playTs > 当前时间时，云端播放器会在指定时刻开始播放在线媒体流。此设定适用于定时播放的场景。当 playTs < 当前时间时：若在线媒体流为直播流，则云端播放器在创建成功时直接播放。若在线媒体流为点播流，则云端播放器会自动根据时间差定位到点播文件的中间时间点作为起始播放点。
mediaType	Number	是	0	媒体流类型： 0：音频 1：视频 2：音视频
volume	Number	否	100	设置音量大小，取值范围为 [0,200]。 [0,100)：调低音量。 100（默认）：播放原始音量。 (100,200]：调高音量。
repeatTime	Number	否	1	重复播放次数，默认为 1 次。若此参数传 -1，表示无限循环播放，直到任务停止。

此文档是否对你有帮助？

有帮助

去反馈

recordConfig
layoutConfig
streamSubscribe
detect
watermark
watermark.imgWms
watermark.transparentLayers
watermark.literaWms
watermark.timestampWm
layout
layout.canvas
layout.users
layout.subStreams
layout.images
rtmpTasks
rtmpTask
config
data