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

查询合流任务 - ShowMixJob

功能介绍

调用此接口查询合流转码任务状态。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见权限和授权项。

URI

GET /v2/apps/{app_id}/mix-stream-jobs/{job_id}

表1 路径参数

参数

是否必选

参数类型

描述

app_id

是

String

应用id

job_id

是

String

任务编号

请求参数

表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信息。

响应参数

状态码：200

表3 响应Header参数

参数

参数类型

描述

X-request-Id

String

此字段携带请求ID号，以便任务跟踪。

表4 响应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

表5 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

表6 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 ：共享屏幕填充。

表7 MixUserBackgroundImage

参数

参数类型

描述

user_id

String

需要设置背景图的用户ID

image_uri

String

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

表8 RecordParam

参数

参数类型

描述

record_rule_id

String

录制规则id。

状态码：404

表9 响应Header参数

参数

参数类型

描述

X-request-Id

String

此字段携带请求ID号，以便任务跟踪。

表10 响应Body参数

参数

参数类型

描述

error_code

String

错误码

error_msg

String

错误描述

状态码：500

表11 响应Header参数

参数

参数类型

描述

X-request-Id

String

此字段携带请求ID号，以便任务跟踪。

表12 响应Body参数

参数

参数类型

描述

error_code

String

错误码

error_msg

String

错误描述

请求示例

查询指定应用id和任务编号的合流录制任务状态

GET https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/mix-stream-jobs/{job_id}

响应示例

状态码：200

查询合流转码成功，查询结果详情

{
  "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"
}

状态码：404

查询合流转码失败，任务编号不存在

{
  "error_code" : "RTC.00001003",
  "error_msg" : "InvalidParameterValue"
}

状态码：500

查询合流转码失败，服务器端错误

{
  "error_code" : "RTC.00002xxx",
  "error_msg" : "InternalError"
}

状态码

状态码

描述

200

查询合流转码成功，查询结果详情

404

查询合流转码失败，任务编号不存在

500

查询合流转码失败，服务器端错误

错误码

请参见错误码。

父主题：合流任务管理