9.3 修改合流任务 9.4 停止合流任务
9.1 启动合流任务
功能介绍
调用此接口创建合流转码任务。
支持纯音频录制和音视频录制：
● 纯音频录制
encode_template填audio_only，音频合流会动态选择最大三方的声音。
layout_template、layout_panes以及其他视频相关参数都不填，填就忽略。
● 音视频录制（包括共享桌面）
encode_template非audio_only，layout_template、layout_panes必须非空。
音频合流会动态选择最大三方的声音。
API触发合流录制流名规则：{jobtype}_{jobid}_{roomid}，其中jobtype取值为 'm'代表合流录制。
调试
您可以在API Explorer中调试该接口。
URI
POST /v2/apps/{app_id}/mix-stream-jobs
API 参考 9 合流任务管理
表9-1 路径参数
参数 是否必选 参数类型 描述
app_id 是 String 应用id
请求参数
表9-2 请求 Header 参数
参数 是否必选 参数类型 描述
Content-Type 是 String 内容类型。
X-Auth-Token 否 String 用户Token。使用Token鉴权方 式时必选。通过调用IAM服务获 取用户Token接口获取（响应消 息头中X-Subject-Token的 值）。
Authorization 否 String 使用AK/SK方式认证时必选，携 带的鉴权信息。
X-Sdk-Date 否 String 使用AK/SK方式认证时必选，请 求的发生时间。
X-Project-Id 否 String 使用AK/SK方式认证时必选，携 带项目ID信息。
表9-3 请求 Body 参数
参数 是否必选 参数类型 描述
mix_param 是 MixParam
object 合流参数 publish_para
m 否 PublishPara
m object 转推参数 record_param 否 RecordParam
object 录制参数
表9-4 MixParam
参数 是否必选 参数类型 描述
room_id 是 String 房间id
API 参考 9 合流任务管理
参数 是否必选 参数类型 描述 encode_templ
ate 是 String 输出编码模板名称,模板名称中
的'x'是英文小写字母x
● 1920x1080_30_4620：输出 流是1080p，帧率30，码率 4.62Mbps
● 1920x1080_15_3460：输出 流是1080p，帧率15，码率 3.46Mbps
● 1280x720_30_3420：输出流 是720p，帧率30，码率 3.42Mbps
● 1280x720_15_2260：输出流 是720p，帧率15，码率 2.26Mbps
● 640x480_15_1000：输出流 是480p，帧率15，码率
● nine_grids_view：九宫格模 板（自适应模板）
● screen_share_left：主视图 在左边的屏幕共享模板（自 适应模板）
● screen_share_right：主视图 在右边的屏幕共享模板（自 适应模板）
● custom：自定义布局 default_user_
参数 是否必选 参数类型 描述 screen_backgr
ound_image 否 String 共享屏幕的背景图地址，图片先 上传obs，格式s3://bucket/
layout_panes 否 Array of MixLayoutPa ne objects
需要混流的视频列表。若不需要 混流视频，则可不传递该参数。
nine_grids_view模板不需要填 写本字段。
user_backgro
und_images 否 Array of MixUserBack
表9-5 MixLayoutPane
参数 是否必选 参数类型 描述
id 否 Integer 窗口id，从1开始编号
user_id 否 String 加入房间的用户id
video_type 否 String 标识视频流的类型，可选摄像头 流或者屏幕分享流。
● CAMERASTREAM：摄像头 视频流
● SCREENSTREAM：屏幕分享 视频流
参数 是否必选 参数类型 描述
zorder 否 Integer 叠放顺序，0为最底层，1层在0 层之上，以此类推，最大支持 25层，自定义布局场景下填写 本字段。
crop_mode 否 String 裁剪模式，自定义布局场景下填 写本字段，支持两种模式：
● KEEP_RATIO_PADDING ： 保持比例留边。
● KEEP_RATIO_CROP ：保持 比例裁剪。
表9-6 MixUserBackgroundImage
参数 是否必选 参数类型 描述
user_id 是 String 需要设置背景图的用户ID
image_uri 是 String 需要设置背景图的地址，图片先 上传obs，格式s3://bucket/
object
表9-7 PublishParam
参数 是否必选 参数类型 描述
rtmp_urls 是 Array of
strings 合流任务完成后，转推的RTMP 推流地址。
API 参考 9 合流任务管理
表9-8 RecordParam
参数 是否必选 参数类型 描述
record_rule_id 是 String 录制规则id。
响应参数
状态码： 201
表9-9 响应 Header 参数
参数 参数类型 描述
X-request-Id String 此字段携带请求ID号，以便任务跟踪。
表9-10 响应 Body 参数
参数 参数类型 描述
job_id String 任务编号，可以用于修改、查看和停止合流任务 stream_name String 流名
app_id String 应用id room_id String 房间id mix_param MixParam
object 合流参数 record_param RecordParam
object 录制参数
create_time String 任务创建的时间，形如
“2006-01-02T15:04:05.075Z”，时区为：UTC update_time String 任务中的布局更新的时间，形如
“2006-01-02T15:04:05.075Z”，时区为：UTC state String 任务状态。
● INIT：任务正在初始化
● RUNNING：任务正在运行
● STOPPED：任务已停止 stop_reason String 任务结束原因
description String 状态描述，对state字段的一些补充说明，可用于 人工查阅。
start_time String 任务开始时间，形如
“2006-01-02T15:04:05.075Z”，时区为：UTC
API 参考 9 合流任务管理
参数 参数类型 描述
stop_time String 任务结束时间，形如
“2006-01-02T15:04:05.075Z”，时区为：UTC
表9-11 MixParam
参数 参数类型 描述
room_id String 房间id encode_templ
ate String 输出编码模板名称,模板名称中的'x'是英文小写字 母x
● 1920x1080_30_4620：输出流是1080p，帧率 30，码率4.62Mbps
● 1920x1080_15_3460：输出流是1080p，帧率 15，码率3.46Mbps
● 1280x720_30_3420：输出流是720p，帧率 30，码率3.42Mbps
● 1280x720_15_2260：输出流是720p，帧率 15，码率2.26Mbps
● 640x480_15_1000：输出流是480p，帧率 15，码率1.00Mbps
● nine_grids_view：九宫格模板（自适应模板）
● screen_share_left：主视图在左边的屏幕共享 模板（自适应模板）
● screen_share_right：主视图在右边的屏幕共 享模板（自适应模板）
● custom：自定义布局 default_user_
background_i mage
String 默认用户背景图地址，图片先上传obs，格式s3://
bucket/object。默认使用等比缩放裁剪，保证铺 满。
API 参考 9 合流任务管理
参数 参数类型 描述 screen_backgr
ound_image String 共享屏幕的背景图地址，图片先上传obs，格式 s3://bucket/object。
在一大多小的布局场景下，无论大窗是显示非指 定用户（屏幕共享人的桌面）还是指定用户的共 享桌面，都通过该字段指定背景图。
background_i
mage String 画布背景图地址，图片先上传obs，格式s3://
bucket/object。默认使用等比缩放裁剪，保证铺 满。
layout_panes Array of MixLayoutPa ne objects
需要混流的视频列表。若不需要混流视频，则可 不传递该参数。
nine_grids_view模板不需要填写本字段。
user_backgro
und_images Array of MixUserBack groundImage objects
指定用户背景图，优先级大于 default_user_background_image
表9-12 MixLayoutPane
参数 参数类型 描述
id Integer 窗口id，从1开始编号 user_id String 加入房间的用户id
video_type String 标识视频流的类型，可选摄像头流或者屏幕分享 流。
● CAMERASTREAM：摄像头视频流
● SCREENSTREAM：屏幕分享视频流 默认为CAMERASTREAM。
width Float 窗格宽，归一化百分比，小数取值范围在float 内，自定义布局场景下填写本字段。
height Float 窗格高，归一化百分比，小数取值范围在float 内，自定义布局场景下填写本字段。
API 参考 9 合流任务管理
参数 参数类型 描述
zorder Integer 叠放顺序，0为最底层，1层在0层之上，以此类 推，最大支持25层，自定义布局场景下填写本字 段。
crop_mode String 裁剪模式，自定义布局场景下填写本字段，支持 两种模式：
● KEEP_RATIO_PADDING ：保持比例留边。
● KEEP_RATIO_CROP ：保持比例裁剪。
表9-13 MixUserBackgroundImage
参数 参数类型 描述
user_id String 需要设置背景图的用户ID
image_uri String 需要设置背景图的地址，图片先上传obs，格式 s3://bucket/object
表9-14 RecordParam
参数 参数类型 描述
record_rule_id String 录制规则id。
状态码： 400
表9-15 响应 Header 参数
参数 参数类型 描述
X-request-Id String 此字段携带请求ID号，以便任务跟踪。
表9-16 响应 Body 参数
参数 参数类型 描述
error_code String 错误码 error_msg String 错误描述
状态码： 404
API 参考 9 合流任务管理
表9-17 响应 Header 参数
参数 参数类型 描述
X-request-Id String 此字段携带请求ID号，以便任务跟踪。
表9-18 响应 Body 参数
参数 参数类型 描述
error_code String 错误码 error_msg String 错误描述
状态码： 500
表9-19 响应 Header 参数
参数 参数类型 描述
X-request-Id String 此字段携带请求ID号，以便任务跟踪。
表9-20 响应 Body 参数
参数 参数类型 描述
error_code String 错误码 error_msg String 错误描述
请求示例
● 九宫格录制请求样例
POST https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/mix-stream-jobs { "mix_param" : {
"room_id" : "room001",
"encode_template" : "1280x720_15_2260", "max_idle_time" : 30,
"layout_template" : "nine_grids_view"
}, "record_param" : {
"record_rule_id" : "5f5e172b9016ed5b0961a43"
}}
● 共享屏幕录制请求样例--主视窗显示共享屏幕
POST https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/mix-stream-jobs {
API 参考 9 合流任务管理
"room_id" : "room001",
"encode_template" : "1280x720_15_2260", "max_idle_time" : 30,
"layout_template" : "screen_share_right", "layout_panes" : {
"id" : 1, "user_id" : "",
"video_type" : "SCREENSTREAM", "filling_policy" : "SHARED_SCREEN"
}
}, "record_param" : {
"record_rule_id" : "5f5e172b9016ed5b0961a43"
}}
● 共享屏幕录制请求样例--主视窗显示摄像头
POST https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/mix-stream-jobs { "mix_param" : {
"room_id" : "room001",
"encode_template" : "1280x720_15_2260", "max_idle_time" : 30,
"layout_template" : "screen_share_right", "layout_panes" : {
"id" : 1,
"user_id" : "user1",
"video_type" : "CAMERASTREAM", "filling_policy" : "FIXED_USER"
}
}, "record_param" : {
"record_rule_id" : "5f5e172b9016ed5b0961a43"
}}
● 自定义布局录制请求样例
POST https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/mix-stream-jobs { "mix_param" : {
"room_id" : "room001",
"encode_template" : "1280x720_15_2260", "max_idle_time" : 30,
"layout_template" : "custom", "layout_panes" : [ {
"id" : 1,
"user_id" : "user1",
"video_type" : "CAMERASTREAM", "x" : 0,
"y" : 0, "width" : 0.666, "height" : 0.333,
"crop_mode" : "KEEP_RATIO_CROP"
}, { "id" : 2,
"user_id" : "user2",
"video_type" : "CAMERASTREAM", "x" : 0.666,
"y" : 0, "width" : 0.333, "height" : 0.666,
"crop_mode" : "KEEP_RATIO_CROP"
} ]
}, "record_param" : {
"record_rule_id" : "5f5e172b9016ed5b0961a43"
API 参考 9 合流任务管理
}}
响应示例
状态码： 201
任务创建成功，返回job的概要信息
{ "job_id" : "607824b4fa163e19fe301cc817dda855", "job_unique_id" : "707e5bfb1ccf4eef",
"stream_name" : "m_607824b4fa163e19fe301cc817dda855_gigu", "app_id" : "123456789abcdefghijklmno",
"room_id" : "gigu", "mix_param" : { "room_id" : "gigu",
"encode_template" : "1920x1080_30_4620", "max_idle_time" : 0,
"layout_template" : "nine_grids_view"
}, "record_param" : {
"record_rule_id" : "5f5e172b9016ed5b0961a43"
}, "create_time" : "2021-04-16T16:22:44Z", "update_time" : "2021-04-16T16:22:44Z", "state" : "INIT",
"start_time" : "2021-04-16T16:22:44Z", "stop_time" : "0001-01-01T00:00:00Z"
}
状态码： 400
创建合流任务失败，语义有误，当前请求无法被服务器理解，或参数有误
{ "error_code" : "RTC.00001003", "error_msg" : "InvalidParameterValue"
}
状态码： 404 app编号不存在
{ "error_code" : "RTC.00001003", "error_msg" : "InvalidParameterValue"
}
状态码： 500
创建合流任务失败，服务器错误
{ "error_code" : "RTC.00002xxx", "error_msg" : "InternalError"
}
状态码
状态码 描述
201 任务创建成功，返回job的概要信息
API 参考 9 合流任务管理
状态码 描述
400 创建合流任务失败，语义有误，当前请求无法被服务器理解，或参数有 误
404 app编号不存在
500 创建合流任务失败，服务器错误
错误码
请参见错误码。