说明：使用云端混流功能将产生转码费用，相关计费说明请参见 直播转码。
接口描述
HTTP 协议请求接口 cgi
http://fcgi.video.qcloud.com/common_access- 只支持 HTTP 协议，此接口暂不支持 HTTPS 协议
- 请使用 POST 方法访问
- Content - Type 为
application/json
通过 URI 传递鉴权参数
http://fcgi.video.qcloud.com/common_access?appid=1252500000&interface=Mix_StreamV2&t=t&sign=sign参数说明：
| 参数名称 | 参数含义 | 输入类型 | 备注 | 是否必填 |
|---|---|---|---|---|
| appid | 客户 ID | int32 | 填写直播 APPID，用于区分不同客户的身份。 | 是 |
| interface | 接口名称 | string | 混流接口名称固定填写：Mix_StreamV2。 | 是 |
| t | 有效时间 | int64 | UNIX时间戳，即从1970年1月1日（UTC/GMT的午夜）开始所经过的秒数；这个字段表示的是请求过期时间，请您在获取当前时间（秒）的基础上加60秒偏移。 | 是 |
| sign | 安全签名 | string | sign = MD5（key + t） ，即把加密 key 和 t 进行字符串拼接后，计算 md5 值。这里的 key 是您在【域名管理】>推流域名>【基本信息】中查看的 API key。 | 是 |
安全签名 sign 计算方法:
key = "40328529ca4381a80c6ecf2e6aa57438" //API 鉴权 key
t = 1490858347 //t 过期时间
key + t = "40328529ca4381a80c6ecf2e6aa574381490858347" //key 和 t 进行字符串拼接
sign = MD5（key + t） = "7f29ed83c61b77de1b0d66936fd4fd44" //对拼接后的字符串计算 MD5混流参数
云端混流将一系列由启动混流开始，到取消混流结束的操作称为一次混流会话。若几次混流请求，参数中的 mix_stream_session_id 与 output_stream_id 一致，则这几次操作属于同一个混流会话。
申请混流
示例:
{
"timestamp":int(time.time()), # UNIX 时间戳数
"eventId":int(time.time()), # 取随机数即可，标识一次网络请求
"interface":
{
"interfaceName":"Mix_StreamV2", # 固定值
"para":
{
"app_id": appid, # 填写直播 APPID
"interface": "mix_streamv2.start_mix_stream_advanced", # 固定值
"mix_stream_session_id" : "lewis_room",#标识一次网络请求
"output_stream_id": "stream_lewis01", # 填输出流 ID
"input_stream_list":
[
# 背景画面
{
"input_stream_id":"stream_lewis01", # 流 ID
"layout_params":
{
"image_layer": 1 # 图层号，背景填1;
}
},
# 小画面1
{
"input_stream_id":"stream_lewis02", # 流 ID
"layout_params":
{
"image_layer": 2, # 图层标识号
"image_width": 160, # 画面宽度
"image_height": 240, # 画面高度
"location_x": 380, # x偏移：相对于背景画面左上角的横向偏移
"location_y": 630 # y偏移：相对于背景画面左上角的纵向偏移
}
}
]
}
}
}注意：混流指定画布时，需提前设置画布大小，具体设置详见 demo。
完整的请求参数包括两部分：CGI 参数，混流参数。
CGI 参数说明:
| 参数名称 | 参数含义 | 输入类型 | 备注 | 是否必填 |
|---|---|---|---|---|
| timestamp | 当前时间 | int64 | 取当前时间（秒）即可。 | 是 |
| eventId | 标识一次网络请求 | int32 | 取随机值即可。 | 是 |
| interfaceName | 接口标识 | string | Mix_StreamV2，固定值，表明使用混流接口 。 | 是 |
混流参数说明：混流参数按作用可以分为三个部分：
- 混流会话参数。
- 输出流参数。
- 输入流参数。
混流会话参数说明：
| 参数名称 | 参数含义 | 输入类型 | 范围 | 备注 | 是否必填 |
|---|---|---|---|---|---|
| app_id | 直播 APPID | int32 | - | 直播 APPID。 | 是 |
| interface | 混流接口名称 | string | mix_streamv2.start_mix_stream_advanced mix_streamv2.cancel_mix_stream |
申请混流：mix_streamv2.start_mix_stream_advanced。 取消混流：mix_streamv2.cancel_mix_stream。 |
是 |
| mix_stream_session_id | 混流会话（申请混流开始到取消混流结束）标识 ID | string | 80字节以内，仅含字母、数字以及下划线的字符串 | 申请混流成功后，业务需要记录该值，在取消混流时，将申请混流时的 mix_stream_session_id 填入。 |
是 |
| mix_stream_template_id | 输入模板 ID，若设置该参数，将按默认模板布局输出，无需填入自定义位置参数 | int32 | 0，10，20，30，40，50 310，390，391，410，510，590，610 |
不填默认为0。 两输入源支持10，20，30，40，50。 三输入源支持310，390，391。 四输入源支持410。 五输入源支持510，590。 六输入源支持610。 |
否 |
输出流参数说明
| 参数名称 | 参数含义 | 输入类型 | 范围 | 备注 | 是否必填 |
|---|---|---|---|---|---|
| output_stream_id | 输出流 ID | string | 80字节以内，仅含字母、数字以及下划线的字符串 | 指定输出流 ID。 | 是 |
| output_stream_type | 输出流类型 | int32 | 0，1 | 不填默认为0。 当输出流为输入流 list 中的一条时，填写0。 当期望生成的混流结果成为一条新流时，该值填为1。 该值为1时，output_stream_id 不能出现在 input_stram_list 中，且直播后台中，不能存在相同 ID 的流。 |
否 |
| output_stream_bitrate | 输出码率 | int32 | [1，50000] | 不填系统会自动判断。 | 否 |
输入源流参数说明
| 参数名称 | 参数含义 | 输入类型 | 范围 | 备注 | 是否必填 |
|---|---|---|---|---|---|
| input_stream_id | 输入流 ID | string | 80字节以内，仅含字母、数字以及下划线的字符串 | 指定输入流 ID（即 StreamName）。 | 是 |
| image_layer | 图层标识号 | int32 | [1，16] | 1)背景流（即大主播画面或画布）的 image_layer 填1。 2)纯音频混流，该参数也需填。 |
是 |
| input_type | 输入源类型 | int32 | [0，5] | 目前支持： 不填默认为0。 0表示输入流为音视频。 2表示输入流为图片。 3表示输入流为画布。 4表示输入流为音频。 5表示输入流为纯视频。 |
否 |
| image_width | 输入画面在输出时的宽度 | double | 像素：[0，3000] 百分比：[0.01，0.99] |
不填默认为输入流的宽度。 使用百分比时，期望输出为（百分比 * 背景宽）。 |
否 |
| image_height | 输入画面在输出时的高度 | double | 像素：[0，3000] 百分比：[0.01，0.99] |
不填默认为输入流的高度。 使用百分比时，期望输出为（百分比 * 背景高）。 |
否 |
| location_x | x 偏移 | double | 像素：[0，3000] 百分比：[0.01，0.99] |
不填默认为0。 相对于大主播背景画面左上角的横向偏移。 使用百分比时，期望输出为（百分比 * 背景宽）。 |
否 |
| location_y | y 偏移 | double | 像素：[0，3000] 百分比：[0.01，0.99] |
不填默认为0。 相对于大主播背景画面左上角的纵向偏移。 使用百分比时，期望输出为（百分比 * 背景高）。 |
否 |
| color | 颜色 | string | - | 使用画布（input_type = 3）时填写，常用的颜色有： 红色：0xcc0033。 黄色：0xcc9900。 绿色：0xcccc33。 蓝色：0x99CCFF。 黑色：0x000000。 白色：0xFFFFFF。 灰色：0x999999。 |
否 |
| picture_id | 水印 ID | int32 | - | 使用图片（input_type = 2）时填写，填入将图片上传为水印后生成的 ID。 | 否 |
自定义位置参数的填写说明
注意：位置参数 location_x 和 location_y 为小画面左上角相对背景画面左上角的绝对像素距离。
接口返回
{"code":0, "message":"Success!", "event_id": "1527240138","timestamp":1490079362}参数说明:
| 参数名 | 参数含义 | 类型 | 备注 |
|---|---|---|---|
| code | 返回错误码 | int32 | 0表示成功，其他表示失败。 |
| message | 错误信息 | string | 返回错误信息。 |
| timestamp | 时间戳 | int64 | 返回时间。 |
| event_id | 请求 ID | int32 | 网络请求标识。 |
常见错误码说明
| 错误码 | 原因 | 排查建议 |
|---|---|---|
| -1 | 解析输入参数错误 | 检查请求体 body json 格式是否正确。 检查 interface name 是否为 mix_streamv2.start_mix_stream_advanced。 检查 input_stream_list 是否为空。 |
| -2 | 输入参数错误 | 检查 appid 和 eventid 是否为0。 检查画面参数是否溢出。 |
| -3 | 流数目错误 | 检查输入流数目是否在[1，16]范围内。 |
| -4 | 流参数错误 | 检查输入输出长宽在（0，3000）范围内。 检查输入流数目是否在（0，16]范围内。 检查输入流是否携带 layout_params 。 检查 input_type 是否支持（合法数值：0，2，3，4，5）。 检查流 ID 长度是否满足（1，80）。 |
| -11 | 图层错误 | 检查图层个数与输入流个数是否一致。 检查图层 ID 是否重复。 检查图层 ID 是否在（0，16]之间。 |
| -20 | 输入参数与接口不匹配 | 检查输入流条数是否匹配模板 ID。 检查颜色参数是否正确。 |
| -21 | 混流输入流条数错误 | 检查输入流的条数是否至少为两条。 |
| -28 | 获取背景长宽失败 | 如果设置画布，检查画布的长宽是否设置。 检查背景流是否存在（推流后需等待5s再混流）。 |
| -29 | 裁剪参数错误 | 检查裁剪位置是否超出流的长宽。 |
| -33 | 水印图片 ID 错误 | 检查输入图片 ID 是否设置。 |
| -34 | 获取水印图片 URL 失败 | 检查图片是否上传成功，是否已经生成 URL。 |
| -111 | output_stream_id 参数与 output_stream_type 不匹配 | output_stream_type 为0,output_stram_id 必须出现在 input_stream_list 中。 output_stream_type 为1,output_stram_id 必须不在 input_stream_list 中。 |
| -300 | 输出流 ID 已经被使用 | 检查当前输出流是否已经是另一个混流的输出流。 |
| -505 | 输入流无法在 upload 查到 | 是否推流成功5s后发起混流。 检查能否播放。 检查混流参数中 appid 是否填写正确。 |
| -507 | 流长宽参数查询失败 | 检查画布宽、高是否设置。 检查推流是否已经成功，建议推流后5s再开始混流。 |
| -508 | 输出流 ID 错误 | 检查是否存在同样 sessionid 使用不同输出流 ID 的情况。 |
| -10031 | 触发混流失败 | 建议推流后等待5s再混流。 |
| -30300 -31001 -31002 |
取消混流时 sessionid 不存在 | 检查 sessionid 是否存在。 |
| -31003 | 输出流 ID 与 session 中输出流 ID 不匹配 | 检查取消混流时填入的输出流 ID。 |
| -31004 | 输出流码率不合法 | 检查输出流码率是否在[1，50000]之间。 |
| 其他 | 其他错误，请联系客服提供技术支持 | - |
取消混流
使用 mix_streamv2.cancel_mix_stream 接口取消混流，取消混流参数中只需填入 CGI 参数及混流会话参数即可。
示例:
{
"timestamp":int(time.time()), # UNIX时间戳数
"eventId":int(time.time()), # 混流事件ID，取时间戳即可
"interface":
{
"interfaceName":"Mix_StreamV2", # 固定取值"Mix_StreamV2"
"para":
{
"app_id": appid, # 填写直播APPID
"interface": "mix_streamv2.cancel_mix_stream", # 取消混流
"mix_stream_session_id" : "lewis_room",# 标识一次网络请求
"output_stream_id": "stream_lewis01"# 输出流id
}
}
}注意：
- 申请混流后，请至少等待5s后再取消混流。
- 取消混流后，半分钟后才可使用相同的 session id 申请混流。
云端混流功能说明
功能支持列表
- 最大支持同时16条流混流。
- 支持混入5种输入源类型（音视频，纯音频，纯视频，水印，画布）。
- 支持混流合成全新流。
- 支持裁剪，水印功能。
- 支持模板配置。
- 支持混流录制。
- 支持自动混流。
- 支持实时混流种类与位置切换。
- 混流启动与取消无缝平滑过渡。
常见云端场景示例
demo 文件可在最下方 DEMO 下载中获取。
大主播与小主播连麦
请参考 demo_template_20.py。
主播PK
请参考 demo_pk.py。
多人会议/多人游戏
请参考 demo_stream_and_canvas.py。
语音通话
请参考 demo_audio.py。
常用布局模板说明
常用的模板有10、30、40、310、410、510和610。使用这八种模板时，输入流不需要填写位置和长宽参数，为原始画面的等比例缩放。只需要传入模板 ID 即可。
- 模板10效果图：
- 模板30效果图：
- 模板40效果图：
- 模板310效果图：
- 模板410效果图：
- 模板510效果图：
- 模板610效果图：
云端裁剪
参数说明:
{
"input_stream_id":"5000_lewis03", # 流ID
"layout_params":
{
"image_layer": 3, # 图层标识号
"image_width": 320, # 画面宽度
"image_height": 240, # 画面高度
"location_x": 580, # x偏移：相对于背景画面左上角的横向偏移
"location_y": 830 # y偏移：相对于背景画面左上角的纵向偏移
}
"crop_params":
{
"crop_width":200, # 裁剪宽度
"crop_height":100, # 裁剪高度
"crop_x":100, # 裁剪x偏移：相对于原画面左上角的横向偏移
"crop_y":1 # 裁剪y偏移：相对于原画面左上角的纵向偏移
}
}示意图：
裁剪参数
| 参数名称 | 参数含义 | 输入类型 | 范围 | 备注 | 是否必填 |
|---|---|---|---|---|---|
| crop_width | 裁剪源画面的宽度 | int32 | 像素：[0，3000] | - | 否 |
| crop_height | 裁剪源画面的高度 | int32 | 像素：[0，3000] | - | 否 |
| crop_x | 相对裁剪源画面左上角横向偏移 | int32 | 像素：[0，3000] | - | 否 |
| crop_y | 相对裁剪源画面左上角纵向偏移 | int32 | 像素：[0，3000] | - | 否 |
注意：
- 输入的宽高和位置参数全部是像素绝对值，对于不同分辨率的流，需要不同处理。
- 位置参数 crop_x 和 crop_y 表示相对原始流左上角绝对像素的位置坐标。
- 如果 layout_params 中指定了 image_width 和 image_height，会将裁剪后的画面缩放到指定的宽高。示例中，会将从原始画面裁剪出的200 * 100的画面缩放成320 * 249输出。
自动混流
若需求较简单，只要实现一个大主播和一个小主播混流，可以使用自动混流功能。只需在原先的推流地址中加入自动混流参数 mixv2=t_id:x;session_id:xxx;layer:x 即可使用。
示例：
rtmp://1234.livepush.myqcloud.com/live/1234_lewis01?from=interactive&bizid=1234&mixv2=t_id:1;session_id:1234_lewis_room;layer:b
rtmp://1234.livepush.myqcloud.com/live/1234_lewis02?from=interactive&bizid=1234&mixv2=t_id:1;session_id:1234_lewis_room;layer:s说明：在两条流均推流成功后，会自动开始混流，输出流 ID 为背景流 ID，示例中输出流 ID 为1234_lewis01。
参数说明
| 参数 | 含义 | 输入类型 | 范围 | 备注 | 是否必填 |
|---|---|---|---|---|---|
| t_id | 模板 ID | int32 | [1,2] | 1：两条音视频流混流。 2：两条纯音频混流。 |
是 |
| session_id | 混流操作标识 | string | 80 字节以内，仅含字母、数字以及下划线的字符串 | 参与自动混流的两条流，session_id 需一致。 | 是 |
| layer | 图层 | string | s，b | 大主播图层，填 b。 小主播图层，填 s。 |
是 |
自动混流效果图
注意：
- 自动混流只支持两条输入流，音视频混流和纯音频混流均支持。
- 自动混流的输入源中有一条流断流则自动取消。
- 自动混流不支持自定义长宽和位置参数。
混流常见问题
- 推流后混流，为什么会返回-505错误码？
推流后等待5s左右再混流。 - 混流接口返回 code 为-505时，如何自查？
混流接口报-505，代表该流 ID 在直播后台中无数据。1、可以通过拉流的方式查看是否推流成功。如果拉流成功，则说明推流成功。2、如果可以拉流，但接口报-505，请检查混流参数中，appid 填写是否正确。 - 纯音频混流后听不到小主播声音？
检查纯音频流的 input_type 是否填为4。 - 连麦场景，输出流 ID 不变，小主播流 ID 变化，是否要取消混流后再重新混流？
不需要，直接用新的小主播 ID 发新的混流请求即可。 - 申请混流后，如果一直未取消混流，会出现什么情况？
混流会一直进行，直到收到取消混流命令。 - 混流过程中，输入流突然断开会出现什么情况？
非背景流断开，断掉的流画面会停在最后一帧，背景流断开，则整个画面都会卡住。在15分钟内该流以同一流 ID 重新推流成功，则自动恢复混流。 - 如何获取录制的混流结果？
请参考录制文档 录制。 - 为什么混流后的视频有黑边？
混流后有黑边有两种情况：1、原始流就有黑边；2、混流参数中的输出长宽比与原始流的长宽比不匹配。如混流期望的长宽比为16：9，原始视频长宽比为4：3，混流后台会在原始视频长宽比基础上补黑边，满足期望的16：9输出。
如果不希望产生黑边，也有两种方案，1、输出长宽比与输入长宽比一致。2、使用裁剪参数，请参考裁剪功能的使用方法。 - 为什么混流的小主播画面有的时候与期望的位置不同？
这种情况一般是参与混流的输入源分辨率发生了变化引起的，例如，申请混流时，长宽为1280 * 720，过了一段时间后，流分辨率变为了2560 * 1440，这个时候，混流输出的画面就会发生改变，与期望的输出有区别。
不建议在混流过程中，变更输入流的分辨率，如确有需要，需计算位置参数后重新申请混流。 - 混流输出是否支持 H265 编码？
混流目前只支持输出 H264 编码。即使输入流均为 H265 编码，输出流也以 H264 编码输出。 - 取消混流后，再次取消，返回-30300错误?
取消混流接口只需要调用一次，成功后无需重复调用。 - 混流过程中，输入流断开后何时自动取消混流？
以两条流混流为例，如果其中一条流断开，混流不会自动取消，如果开了录制，录制也将继续进行。如果两条流均断开，15分钟后混流自动取消。 - 为何调用混流时，画面会出现回退？
混流转码实现机制中，会尽量保证双方画面的一致，因此在处理过程中会有轻微的回退现象。为避免这种情况对业务使用造成影响，如无特殊使用场景，请勿频繁调用混流接口。 - 混流过程中，如果有主播下播，混流会自动更改混流布局吗？
不会，混流调度不会修改客户的布局参数，如果有主播下播的业务场景，需要业务方自行重新计算布局参数，重新发起混流。
DEMO 下载
混流 demo 下载：请单击 此处 下载 demo。