文档首页/ 实时音视频 SparkRTC/ API参考/ 合流任务管理/ 启动合流任务
更新时间：2025-09-09 GMT+08:00
查看PDF
分享

启动合流任务

功能介绍

调用此接口创建合流转码任务。

支持纯音频录制和音视频录制：

  • 纯音频录制

    encode_template填audio_only，音频合流会动态选择最大三方的声音。

    layout_template、layout_panes以及其他视频相关参数都不填，填就忽略。

  • 音视频录制（包括共享桌面）

    encode_template非audio_only，layout_template、layout_panes必须非空。

    音频合流会动态选择最大三方的声音。

    API触发合流录制流名规则：{jobtype}_{jobid}_{roomid}，其中jobtype取值为'm'代表合流录制。

URI

POST /v2/apps/{app_id}/mix-stream-jobs

表1 路径参数

参数

是否必选

参数类型

描述

app_id

是

String

应用id

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

Content-Type

是

String

内容类型。取值application/json。

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信息。
表3 请求Body参数

参数

是否必选

参数类型

描述

mix_param

是

MixParam object

合流参数

record_param

否

RecordParam object

录制参数
表4 MixParam

参数

是否必选

参数类型

描述

room_id

是

String

房间id

encode_template

是

String

输出编码模板名称

  • 1920*1080_30_4620：输出流是1080p，帧率30，码率4.62Mbps

  • 1920*1080_30_3150：输出流是1080p，帧率30，码率3.15Mbps

  • 1920*1080_15_3460：输出流是1080p，帧率15，码率3.46Mbps

  • 1920*1080_15_2080：输出流是1080p，帧率15，码率2.08Mbps

  • 1280*720_30_3420：输出流是720p，帧率30，码率3.42Mbps

  • 1280*720_30_1710：输出流是720p，帧率30，码率1.71Mbps

  • 1280*720_15_2260：输出流是720p，帧率15，码率2.26Mbps

  • 1280*720_15_1130：输出流是720p，帧率15，码率1.13Mbps

  • 640*480_30_1500：输出流是480p，帧率30，码率1.50Mbps

  • 640*480_15_500：输出流是480p，帧率15，码率500Kbps

  • 640*480_30_1000 输出流是480p，帧率30，码率1000Kbps

  • 480*360_30_490：输出流是360p，帧率30，码率490Kbps

  • 480*360_15_320：输出流是360p，帧率15，码率320Kbps

max_idle_time

否

Integer

最长空闲频道时间。

取值范围：[5，43200]，默认值为30。

单位：秒。

如果频道内无连麦方的状态持续超过该时间，录制程序会自动退出。退出后，再次调用start请求，会产生新的录制任务。

连麦方指：joiner或者publisher的用户。

layout_template

否

String

视频布局模板编号，不混视频的时候，不需要带。

  • nine_grids_view：九宫格模板（自适应模板）

  • screen_share_left：主视图在左边的屏幕共享模板（自适应模板）

  • screen_share_right：主视图在右边的屏幕共享模板（自适应模板）

  • custom：自定义布局

default_user_background_image

否

String

默认用户背景图地址，图片先上传obs，格式s3://bucket/object，如：s3://rtc-bucket-cn-north-4/img/testImg.jpg。默认使用等比缩放裁剪，保证铺满。

screen_background_image

否

String

共享屏幕的背景图地址，图片先上传obs，格式s3://bucket/object，如：s3://rtc-bucket-cn-north-4/img/testImg.jpg。

在一大多小的布局场景下，无论大窗是显示非指定用户（屏幕共享人的桌面）还是指定用户的共享桌面，都通过该字段指定背景图。

background_image

否

String

画布背景图地址，使用背景图功能需先上传图片到obs，填写此字段要求格式为s3://bucket/object，其中bucket和object指图片所在的桶和路径，如：s3://rtc-bucket-cn-north-4/img/testImg.jpg。默认使用等比缩放裁剪，保证铺满。

layout_panes

否

Array of MixLayoutPane objects

需要混流的视频列表。若不需要混流视频，则可不传递该参数。

nine_grids_view模板不需要填写本字段。

user_background_images

否

Array of MixUserBackgroundImage objects

指定用户背景图，优先级大于default_user_background_image
表5 MixLayoutPane

参数

是否必选

参数类型

描述

id

否

Integer

窗口id，从1开始编号

user_id

否

String

加入房间的用户id

video_type

否

String

标识视频流的类型，可选摄像头流或者屏幕分享流。

  • CAMERASTREAM：摄像头视频流

  • SCREENSTREAM：屏幕分享视频流

默认为CAMERASTREAM。

x

否

Float

坐标x，归一化百分比，画布上该画面左上角的横坐标的相对值，范围是 [0.0,1.0]。从左到右布局，0.0在最左端，1.0在最右端，小数取值范围在float内，自定义布局场景下填写本字段。

y

否

Float

坐标y，归一化百分比，画布上该画面左上角的纵坐标的相对值，范围是 [0.0,1.0]。从上到下布局，0.0在最上端，1.0在最下端，小数取值范围在float内，自定义布局场景下填写本字段。

width

否

Float

窗格宽，归一化百分比，小数取值范围在float内，自定义布局场景下填写本字段。

height

否

Float

窗格高，归一化百分比，小数取值范围在float内，自定义布局场景下填写本字段。

zorder

否

Integer

叠放顺序，0为最底层，1层在0层之上，以此类推，最大支持25层，自定义布局场景下填写本字段。

crop_mode

否

String

裁剪模式，自定义布局场景下填写本字段，支持两种模式：

  • KEEP_RATIO_PADDING ：保持比例留边。

  • KEEP_RATIO_CROP ：保持比例裁剪。

filling_policy

否

String

填充策略，仅限屏幕共享模板(包括screen_share_right、screen_share_left)场景下填写本字段，支持两种模式：

  • FIXED_USER ：固定用户填充。

  • SHARED_SCREEN ：共享屏幕填充。
表6 MixUserBackgroundImage

参数

是否必选

参数类型

描述

user_id

是

String

需要设置背景图的用户ID

image_uri

是

String

需要设置背景图的地址，图片先上传obs，格式s3://bucket/object，如：s3://rtc-bucket-cn-north-4/img/testImg.jpg
表7 RecordParam

参数

是否必选

参数类型

描述

record_rule_id

是

String

录制规则id。

响应参数

状态码：201

表8 响应Header参数

参数

参数类型

描述

X-request-Id

String

此字段携带请求ID号，以便任务跟踪。
表9 响应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

任务结束原因

  • TENANT_STOP

  • EXCEED_MAX_IDLE_TIME

  • INTERNAL_ERROR

description

String

状态描述，对state字段的一些补充说明，可用于人工查阅。

start_time

String

任务开始时间，形如“2006-01-02T15:04:05.075Z”，时区为：UTC

stop_time

String

任务结束时间，形如“2006-01-02T15:04:05.075Z”，时区为：UTC
表10 MixParam

参数

参数类型

描述

room_id

String

房间id

encode_template

String

输出编码模板名称

  • 1920*1080_30_4620：输出流是1080p，帧率30，码率4.62Mbps

  • 1920*1080_30_3150：输出流是1080p，帧率30，码率3.15Mbps

  • 1920*1080_15_3460：输出流是1080p，帧率15，码率3.46Mbps

  • 1920*1080_15_2080：输出流是1080p，帧率15，码率2.08Mbps

  • 1280*720_30_3420：输出流是720p，帧率30，码率3.42Mbps

  • 1280*720_30_1710：输出流是720p，帧率30，码率1.71Mbps

  • 1280*720_15_2260：输出流是720p，帧率15，码率2.26Mbps

  • 1280*720_15_1130：输出流是720p，帧率15，码率1.13Mbps

  • 640*480_30_1500：输出流是480p，帧率30，码率1.50Mbps

  • 640*480_15_500：输出流是480p，帧率15，码率500Kbps

  • 640*480_30_1000 输出流是480p，帧率30，码率1000Kbps

  • 480*360_30_490：输出流是360p，帧率30，码率490Kbps

  • 480*360_15_320：输出流是360p，帧率15，码率320Kbps

max_idle_time

Integer

最长空闲频道时间。

取值范围：[5，43200]，默认值为30。

单位：秒。

如果频道内无连麦方的状态持续超过该时间，录制程序会自动退出。退出后，再次调用start请求，会产生新的录制任务。

连麦方指：joiner或者publisher的用户。

layout_template

String

视频布局模板编号，不混视频的时候，不需要带。

  • nine_grids_view：九宫格模板（自适应模板）

  • screen_share_left：主视图在左边的屏幕共享模板（自适应模板）

  • screen_share_right：主视图在右边的屏幕共享模板（自适应模板）

  • custom：自定义布局

default_user_background_image

String

默认用户背景图地址，图片先上传obs，格式s3://bucket/object，如：s3://rtc-bucket-cn-north-4/img/testImg.jpg。默认使用等比缩放裁剪，保证铺满。

screen_background_image

String

共享屏幕的背景图地址，图片先上传obs，格式s3://bucket/object，如：s3://rtc-bucket-cn-north-4/img/testImg.jpg。

在一大多小的布局场景下，无论大窗是显示非指定用户（屏幕共享人的桌面）还是指定用户的共享桌面，都通过该字段指定背景图。

background_image

String

画布背景图地址，使用背景图功能需先上传图片到obs，填写此字段要求格式为s3://bucket/object，其中bucket和object指图片所在的桶和路径，如：s3://rtc-bucket-cn-north-4/img/testImg.jpg。默认使用等比缩放裁剪，保证铺满。

layout_panes

Array of MixLayoutPane objects

需要混流的视频列表。若不需要混流视频，则可不传递该参数。

nine_grids_view模板不需要填写本字段。

user_background_images

Array of MixUserBackgroundImage objects

指定用户背景图，优先级大于default_user_background_image
表11 MixLayoutPane

参数

参数类型

描述

id

Integer

窗口id，从1开始编号

user_id

String

加入房间的用户id

video_type

String

标识视频流的类型，可选摄像头流或者屏幕分享流。

  • CAMERASTREAM：摄像头视频流

  • SCREENSTREAM：屏幕分享视频流

默认为CAMERASTREAM。

x

Float

坐标x，归一化百分比，画布上该画面左上角的横坐标的相对值，范围是 [0.0,1.0]。从左到右布局，0.0在最左端，1.0在最右端，小数取值范围在float内，自定义布局场景下填写本字段。

y

Float

坐标y，归一化百分比，画布上该画面左上角的纵坐标的相对值，范围是 [0.0,1.0]。从上到下布局，0.0在最上端，1.0在最下端，小数取值范围在float内，自定义布局场景下填写本字段。

width

Float

窗格宽，归一化百分比，小数取值范围在float内，自定义布局场景下填写本字段。

height

Float

窗格高，归一化百分比，小数取值范围在float内，自定义布局场景下填写本字段。

zorder

Integer

叠放顺序，0为最底层，1层在0层之上，以此类推，最大支持25层，自定义布局场景下填写本字段。

crop_mode

String

裁剪模式，自定义布局场景下填写本字段，支持两种模式：

  • KEEP_RATIO_PADDING ：保持比例留边。

  • KEEP_RATIO_CROP ：保持比例裁剪。

filling_policy

String

填充策略，仅限屏幕共享模板(包括screen_share_right、screen_share_left)场景下填写本字段，支持两种模式：

  • FIXED_USER ：固定用户填充。

  • SHARED_SCREEN ：共享屏幕填充。
表12 MixUserBackgroundImage

参数

参数类型

描述

user_id

String

需要设置背景图的用户ID

image_uri

String

需要设置背景图的地址，图片先上传obs，格式s3://bucket/object，如：s3://rtc-bucket-cn-north-4/img/testImg.jpg
表13 RecordParam

参数

参数类型

描述

record_rule_id

String

录制规则id。

状态码：400

表14 响应Header参数

参数

参数类型

描述

X-request-Id

String

此字段携带请求ID号，以便任务跟踪。
表15 响应Body参数

参数

参数类型

描述

error_code

String

错误码

error_msg

String

错误描述

状态码：404

表16 响应Header参数

参数

参数类型

描述

X-request-Id

String

此字段携带请求ID号，以便任务跟踪。
表17 响应Body参数

参数

参数类型

描述

error_code

String

错误码

error_msg

String

错误描述

状态码：500

表18 响应Header参数

参数

参数类型

描述

X-request-Id

String

此字段携带请求ID号，以便任务跟踪。
表19 响应Body参数

参数

参数类型

描述

error_code

String

错误码

error_msg

String

错误描述

请求示例

  • 创建一个合流录制任务。房间号：room001，输出流：720p，帧率：15，码率：2.26Mbps，视频布局为九宫格，最长空闲频道时间：30秒，录制规则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" : "nine_grids_view"
  },
  "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" : "",
      "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"
  }
}

响应示例

状态码：201

任务创建成功，返回job的概要信息

{
  "job_id" : "607824b4fa163e19fe301cc817dda855",
  "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的概要信息

400

创建合流任务失败，语义有误，当前请求无法被服务器理解，或参数有误

404

app编号不存在

500

创建合流任务失败，服务器错误

错误码

请参见错误码。

父主题： 合流任务管理