服务端 API v2
  • API概览
  • 调用方式
  • 房间信令接口
  • 混流接口
  • 媒体服务接口
  • 媒体文件接口
  • 音视频流审核接口
  • 回调说明
  • 全局返回码
  • 调测指南

开始混流

更新时间:2022-01-20 15:51

1 描述

调用本接口开始混流/更新混流任务。 混流功能的介绍请参考 多路混流,相关回调请参考 混流开始回调混流结束回调

首次使用本接口之前,请在 ZEGO 控制台 自助接入服务开通“混流”(开通步骤请参考 控制台 - 项目管理 中的“服务接入”),或联系 ZEGO 技术支持开通。

2 接口原型

  • 请求方法:POST/JSON
  • 请求地址:https://rtc-api.zego.im/?Action=StartMix
  • 传输协议:HTTPS
  • 调用频率限制:100 次/秒

3 请求参数

以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表请参考 调用方式 - 公共请求参数

此接口中只有部分参数在开始混流后支持动态更新,未标注的则不支持动态更新,详情请参考下表中的参数描述。

测试环境下(详见 调用方式 - 公共参数 中 “IsTest” 的参数说明),输入流的流 ID 和 输出流的流 ID 需要加上 “zegotest-AppId-” 前缀,否则会导致混流失败(混流服务器拉不到输入流或拉不到混流输出流)。例如,流 ID 为 “test”,在 AppId 为 “123456789” 的测试环境下,流 ID 应为 “zegotest-123456789-test”。

名称 类型 是否必选 描述
TaskId String 任务 ID,混流任务的唯一标识。作为判断新增或更新混流任务的依据。
Sequence Int 混流请求的序列号,用于保证时序,同个任务的参数修改需要保证序列号的递增。
UserId String 用户 ID。同一个任务的用户 ID 需要一致。通过 UserId 可以实现混流任务的用户归属,也就是该用户才能更新或者停止对应 TaskId 的混流任务,该功能需要联系 ZEGO 技术支持开通。
RoomId String 房间 ID。
UserData String

用户数据,自定义的数据客户端是通过收到媒体次要信息的 onPlayerRecvSEI 回调获得。长度限制为 [1, 1000] 单位字节,建议小于 850 字节。

该参数在开始混流后支持动态更新。

SoundLevel Int

混流声浪。支持混流过程中实时更新。

  • 1:开启。
  • 0:不开启,默认值。

该参数在开始混流后支持动态更新。

ByPass Int 单流透传开关,即输入流就一个时是否按输出参数重新编码,该功能需要联系 ZEGO 技术支持开通。
  • 1:启用。
  • 0:不启用,默认值。
SoundChannel String 输出音频声道数,当没有指定输出流时使用该配置。
  • 1:单声道,默认值。
  • 2:双声道。
BackgroundImage String

背景图,支持 JPG 和 PNG 格式。支持以下 2 种使用方式:

  • URI:将图片提供给 ZEGO 技术支持进行配置,配置完成后会提供图片 URI,例如:preset-id://xxx.jpg。
  • URL:仅支持 HTTP 协议,默认 URL 个数为 20,如果需要变更图片,建议直接同名(同个 URL)更新图片文件。

该参数在开始混流后支持动态更新。

BackgroundColor Int64

混流背景颜色。传入前需要对颜色数值进行处理,例如:背景色需要纯白色,对应 16 进制的 RGB 颜色代码为 “#FFFFFF”,需要去掉 “#” 并在末尾加上 “00” 得到 “FFFFFF00”,最后将 “FFFFFF00” 转换成 10 进制得到 “4294967040”,这个值就是纯白色的配置值。

该参数在开始混流后支持动态更新。

MixInput Array of Object 输入流信息,支持多个,默认上限为 9,如果有更多的需求,请联系 ZEGO 技术支持处理。
└ StreamId String 混流输入流 ID,表示该流 ID 来自 RTC 服务。

StreamId 和 StreamUrl 二者取其一即可,若填写了 StreamId,则 StreamUrl 不生效。

└ StreamUrl String 混流输入流 URL,支持 RTMP 和 HTTP-FLV 两种协议。

StreamId 和 StreamUrl 二者取其一即可,若填写了 StreamUrl ,则 StreamId 不生效。

└ ContentControl Int

内容控制。

  • 0:取音视频,默认值。
  • 2:取视频。

该参数在开始混流后支持动态更新。

└ SoundLevelId Int 音浪 ID。
└ RectInfo Object 输入流位置信息。
  └ Layer Int

图层层次。0 表示最底层,数值越大层次越高。

该参数在开始混流后支持动态更新。

  └ Top Int

上边框。距离输出画布上边框的像素大小。

该参数在开始混流后支持动态更新。

  └ Left Int

左边框。距离输出画布左边框的像素大小。

该参数在开始混流后支持动态更新。

  └ Bottom Int

下边框。距离输出画布上边框的像素大小。

该参数在开始混流后支持动态更新。

  └ Right Int

右边框。距离输出画布左边框的像素大小。

该参数在开始混流后支持动态更新。

└ RenderMode Int

混流输入填充模式。

  • 0:裁剪模式,默认值。
  • 1:填充模式。
WaterMark Object 水印配置。
└ Image String

水印图片,支持 JPG 和 PNG 格式。使用方式同背景图 BackgroundImage。

该参数在开始混流后支持动态更新。

└ RectInfo Object

水印位置信息。

该参数在开始混流后支持动态更新。

  └ Top Int 上边框。距离输出画布上边框的像素大小。
  └ Left Int 左边框。距离输出画布左边框的像素大小。
  └ Bottom Int 下边框。距离输出画布上边框的像素大小。
  └ Right Int 右边框。距离输出画布左边框的像素大小。
MixOutput Array of Object 输出流信息,目前最多支持 3 个。当输出目标为 URL 格式时,目前只支持 RTMP URL 格式:rtmp://xxxxxxxx,且不能传入两个相同的混流输出的地址。
└ StreamId String 输出流 ID。默认情况下表示混流输出至 RTC 或低延迟直播产品,也可联系 ZEGO 技术支持配置混流输出至 ZEGO 代理的 CDN 直播产品,生效范围为整个 AppID。如果希望控制指定流输出至 CDN 直播产品,则不能配置混流默认输出至 ZEGO 代理 CDN,应按需设置 StreamUrl。
└ StreamUrl String 仅支持 RTMP 协议,表示混流输出至 CDN 直播服务,观众可以从 CDN 直播拉混流。StreamUrl 和 StreamId 二者取其一即可,若填写了 StreamUrl ,则 StreamId 不生效。
└ VideoBitrate Int

视频码率,单位为 bps。纯音频混流时,推荐填写 1。支持混流过程中实时更新。

该参数在开始混流后支持动态更新。

└ Fps Int 视频帧率。
└ Width Int

宽,范围为 [0, 3000],数值必须是 2 的倍数。纯音频混流时,推荐填写 1。支持混流过程中实时更新。

该参数在开始混流后支持动态更新。

└ Height Int

高,范围为 [0, 3000],数值必须是 2 的倍数。纯音频混流时,推荐填写 1。支持混流过程中实时更新。

该参数在开始混流后支持动态更新。

└ AudioCodec Int 音频编码及采样率。如需修改采样率,请联系 ZEGO 技术支持配置。
  • 0:HE-AAC,采样率:44100 KHz,默认值。
  • 1:LC-AAC,采样率:44100 KHz。
  • 2:MP3,采样率:44100 KHz。
  • 3:OPUS,采样率:48000 KHz。
└ AudioBitrate Int 混流输出音频码率,不填时默认值为 48000,单位为 bps。
└ SoundChannel Int 输出音频声道数,优先级比全局参数高。
  • 1:单声道,默认值。
  • 2:双声道。
ExPara Array of Object 拓展参数,根据实际情况填入,常规任务可不填。
└ Key String key 值。
└ Value String value 值。

4 请求示例

4.1 请求 url 示例

https://rtc-api.zego.im/?Action=StartMix
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=7a2c0f11145fb760d607a07b54825013
&SignatureVersion=2.0
&IsTest=false

4.2 全部业务参数示例

以下是全部业务参数的示例说明:

{
    'TaskId': '2213699902971205739',  # N,string,任务ID,同一个任务需要一致
    'Sequence': 1,  # Y,int,混流请求的序列号,修改混流参数时需保证递增
    'UserId': '123',  # Y,string用户ID;
    'RoomId': '321',  # N,string,房间ID;
    'UserData': 'DoraTest',  # N,string,用户数据,自定义的数据客户端是通过收到媒体次要信息的接口 onPlayerRecvSEI 回调 长度限制:[1, 1000]单位字节,建议小于850字节;支持混流过程中实时更新
    'SoundLevel': 1,  # N,int,混流声浪,1: 开启,0:不开启;默认值是0;支持混流过程中实时更新
    'BackgroundImage': 'http://47.101.46.7:8090/no_camera_icon.png',  # N,string,背景图,支持线上URL
    'BackgroundColor': 4294967040,  # N,int64,背景颜色
    'ByPass': 1,  # N,单流透传开关,也就是输入流就一个的时候是否混流(默认不启用) 1: 启用, 0:不启用
    'MixInput': [{  # 输入流列表;必填;
            'StreamId': 'input5',  # Y,输入流地址,StreamUrl和StreamId二者取其一即可,若填写了 StreamUrl,则 StreamId 不生效
            'StreamUrl': 'rtmp://ip/appname/streamid',  # Y,支持RTMP/HTTP-FLV两种协议,StreamUrl和StreamId二者取其一即可,若填写了 StreamUrl,则 StreamId 不生效
            'SoundLevelId': 0,  # N,int,音浪Id
            'ContentControl': 2,  # N,int,内容控制。0:取音视频,2:取视频
            'RectInfo': {  # 流的位置信息;必填
                'Layer': 0,  # N,int,图层层次
                'Top': 0,  # 必填
                'Left': 0,  # 必填
                'Bottom': 650,  # 必填
                'Right': 380  # 必填
                #   原点在左上角,top/bottom/left/right 定义如下:
                #
                #   (left, top)-----------------------
                #   |                                |
                #   |                                |
                #   |                                |
                #   |                                |
                #   -------------------(right, bottom)
                        },
            'RenderMode': 0  # N,int,混流输入填充模式。0:裁剪模式,默认值,1:填充模式
                }
    ],
    'WaterMark': {
        'Image': 'http://47.101.46.7:8090/no_camera_icon.png',# Y,string,水印图片
        'RectInfo': {  # 水印的位置信息;必填
            'Top': 0,  # 必填
            'Left': 0,  # 必填
            'Bottom': 200,  # 必填
            'Right': 150  # 必填
            #   原点在左上角,top/bottom/left/right 定义如下:
            #
            #   (left, top)-----------------------
            #   |                                |
            #   |                                |
            #   |                                |
            #   |                                |
            #   -------------------(right, bottom)
        }
    },
    'MixOutput': [{  # 输出流列表;必填  
            'StreamId': 'test',  # Y,输入流地址,StreamUrl和StreamId二者取其一即可,若填写了 StreamUrl,则 StreamId 不生效
            #'StreamUrl': 'rtmp://ip/appname/streamid', StreamUrl和StreamId二者取其一即可,若填写了 StreamUrl,则 StreamId 不生效
            'VideoBitrate': 1200000,  # Y,int,视频码率(单位:bps),纯音频混流的时候,推荐填写0;支持混流过程中实时更新
            'Fps': 15,  # Y,int,视频帧率
            'Width': 1280,  # Y,int,宽,范围[0-3000];数值必须是2的倍数,纯音频混流的时候,推荐填写0
            'Height': 1080,  # Y,int,高,范围[0-3000];数值必须是2的倍数,纯音频混流的时候,推荐填写0
            'AudioCodec': 0,  # N,int,音频编码 0:HE-AAC,1:LC-AAC,2:MP3;默认0
            'AudioBitrate': 48000,  # N,int,混流输出音频码率,默认48000,单位 bps
            'SoundChannel': 2,  # N,int,声道数, 1:单声道,2:双声道
        },
        {
            #'StreamId': 'test',
            'StreamUrl': 'rtmp://domian/appname/test', # CDN 直播服务的推流地址
            'VideoBitrate': 1200000,  # Y,int,视频码率(单位:bps)
            'Fps': 15,
            'Width': 1280,  # Y,int,宽,范围[0-3000];数值必须是2的倍数,纯音频混流的时候,推荐填写0
            'Height': 1080
        }
    ],
    #'ExPara',  # N,扩展参数(json结构体格式),具体联系技术支持,比如video_encode/sei_mode,可参见数据示例
    "ExPara": [
        {
            "Key": "video_encode",
            "Value": "vp8"
        },
        {
            "Key": "sei_mode",
            "Value": "1"
        },
        {
            "Key": "mixowner_userid",
            "Value": "[\"456\"]"
        }
    ]
}

4.3 部分业务参数示例

  1. 混流配置描述

混流输出流 ID 为 “test_mix_bing”,帧率为 15fps,分辨率为 640*480,码率为 1200000 bps,音频码率为 48000 bps。其中两路输入流 “test_bing1” 和 “test_bing2” 的画面各占输出画布的一半。

  1. 输出画布示例以及 rect 说明
原点在左上角,输入流 top/bottom/left/right 定义如下:

  (0,0)---------(320,0)-----------------
  |                |                |
  |                |                |
  |                |                |
  |   test_bing1    |   test_bing2    |
  |                |                |
  |                |                |
  |                |                |
  -------------(320,480)--------(640,480)
  1. 参数示例
{
    "Sequence": 2,
    "UserId": "admin",
    "MixInput": [
        {
            "RectInfo": {
                "Bottom": 480,
                "Layer": 0,
                "Left": 0,
                "Right": 320,
                "Top": 0
            },
            "SoundLevelId": 1,
            "StreamId": "test_bing1"
        },
        {
            "RectInfo": {
                "Bottom": 480,
                "Layer": 0,
                "Left": 320,
                "Right": 640,
                "Top": 0
            },
            "SoundLevelId": 2,
            "StreamId": "test_bing2"
        }
    ],
    "MixOutput": [
        {
            "Fps": 15,
            "Width": 640,
            "Height": 480,
            "StreamId": "test_mix_bing",
            "VideoBitrate": 1200
        }
    ]
}

5 响应参数

参数 类型 描述
Code Number 返回码。
Message String 操作结果描述。
RequestId String 请求 ID。
Data Array of Object 响应数据。
└ UserId String 用户 ID。
└ Sequence Int 序列号。
└ RoomId String 房间 ID。
└ PlayInfo Array of Object 播放信息
  └ StreamId String 流 ID。
  └ RTMP String RTMP 协议对应的 CDN 播放地址(如果指定混流输出地址是 CDN 并且配置了这个协议的拉流域名)。
  └ HLS String HLS 协议对应的 CDN 播放地址(如果指定混流输出地址是 CDN 并且配置了这个协议的拉流域名)。
  └ FLV String HTTP-FLV 协议对应的 CDN 播放地址(如果指定混流输出地址是 CDN 并且配置了这个协议的拉流域名)。

6 响应示例

{
    "Code": 0, 
    "Data": {
        "PlayInfo": [
            {
                "FLV": "http://domain/appname/test.flv", 
                "HLS": "http://domain/appname/test/playlist.m3u8", 
                "RTMP": "rtmp://domain/appname/test", 
                "Status": 0, 
                "StreamId": "test", 
                "UserName": ""
            }
        ], 
        "RoomId": "", 
        "Sequence": 2, 
        "UserId": "admin"
    }, 
    "Message": "success", 
    "RequestId": "8472822294336370476"
}

7 返回码

以下仅列出了接口业务逻辑相关的返回码,完整返回码请参考 全局返回码

返回码 说明
110200001 失败。
110200002 输入参数错误。
110200003 鉴权失败。
110200004 解析输入参数失败。
110200005 混流开始获取分布式锁失败。
110200006 混流结束获取分布式锁失败。
110200007 更新混流请求失败。
110200008 混流开始协议转换失败。
110200009 混流开始请求转发失败。
110200010 混流开始回调失败。
110200011 混流开始数据旁路失败。
110200012 关闭混流发起者其他混流任务失败。
110200013 更新混流归属失败。
110200014 混流结束协议转换失败。
110200015 混流结束请求转发失败。
110200016 混流结束回调失败。
110200017 清理混流状态信息失败。
110200103 seq 错误。
110200150 混流输入流不存在。
110200151 混流失败。
110200152 结束混流失败。
110200153 混流输入流错误。
110200154 混流输出流错误。
110200155 混流输入流格式错误。
110200156 混流输出流格式错误。
110200157 混流权限未开。
110200158 混流输入流条数过限。
110200159 混流 dispatch 失败。
110200160 非所有者关闭混流。
110200170 水印参数错误。
110200171 水印参数为空。
110200172 扩展参数错误。
110200173 背景图超出数量限制。
110200174 水印图超出数量限制。
110200175 输入流重复。
110200176 输出流重复。
110200177 焦点语音超出限制。
110200178 输出流超出数量限制。
110200180 开始混流 token 为空。
110200181 开始混流 token 非法。
110200182 结束混流 token 为空。
110200183 结束混流 token 非法。
110200184 混流开始参数解析失败。
110200185 混流结束参数解析失败。
110200190 混流开始请求过载。
110200191 混流结束请求过载。
110200192 混流任务批量查询请求过载。
110200193 混流任务查询请求过载。
110200194 混流请求过载。
110240002 token 非法。
110240003 AppId 为空。
110240004 AppId 错误。
110200901 LiveRoom 混流命令参数为空。
110200902 LiveRoom 混流命令参数值不存在。
110208000 混流状态转推服务错误。
110208001 混流状态转推服务解码错误。
110208002 没有配置混流转推服务地址。
110208003 混流转推服务过载。
110208004 混流转推服务请求错误。