旁路直播 RESTful API

阅读本章节前请确保你已经了解过快速开始

API概览

事项说明
请求host国内:api.aivacom.com,海外:api-oversea.aivacom.com
请求url/app/{appid}/v2/rtmpforward/{reqUri}?traceId={yourTraceId}
reqUri为:
- startrtmp
- stoprtmp
HeadContent-Type: application/json;charset=UTF-8
AppID: 123456
Nonce: 0123456789abcdef
Timestamp: 1592956064772
Signature: signature
签名字段生成方法请参考 签名认证

启动旁路推流:startrtmp

旁路推流启动接口携带了混画参数对混流场景进行推流。

  • 请求方法:POST
  • Head:
    • Content-type: application/json;charset=utf-8
    • AppID为 开发者平台分配的App Key
    • Nonce为 随机数组成的字符串,长度限制为30
    • Timestamp为 北京时间戳,从1970年1月1日0点0分0秒开始到现在的毫秒数
    • Signature为 数据签名,生成方法请参考签名认证
  • 请求host:
    • 国内:api.aivacom.com
    • 海外:api-oversea.aivacom.com
  • 请求url:app/{appid}/v2/rtmpforward/startrtmp?traceId={yourTraceId}
    • appid: 你的项目使用的AppID
    • traceId: 用于跟踪每条API调用,可以用“服务器 IP + 产生 ID 时候的时间 + 自增序列 + 当前进程号”

参数说明:

参数名称是否必填数据类型说明
appiduint64业务Appid
roomidstring房间号
rtmpurlstring旁路推流地址,多个地址按,分隔,最多指定5个地址,必填
streamtypeuint32流类型:1=混流推流,2=源流推流
taskid混流推流必填string混流任务ID,标识混画任务
mixconfig混流推流必填JSON混画配置
uid源流推流必填string用户id

mixconfig参数

参数名称是否必填数据类型说明
inputJSON输入参数,json格式数组,使用模板ID的情况可不填
outputJSON输出参数,json格式
templateiduint32模板ID:1=水平布局,2=垂直布局,3=平铺布局,4=角落布局

模板说明:
使用布局模板无需填写输入流信息,布局模板仅适用于同频道连麦,跨频道必须自定义指定每个uid的布局信息。
1、水平布局: 首用户在上方显示大窗画面,其他用户在下方排列显示小窗画面,小窗最多两行,一行最多8个画面,最多支持17个用户画面。
2、垂直布局: 首用户在左侧显示大窗画面,其他用户在右侧排列显示小窗画面,小窗最多两列,一列最多8个画面,最多支持17个用户画面。
3、平铺布局: 根据用户数量自动调整每个画面的大小,每个用户的画面大小一致,最多支持16个画面(4×4)。
4、角落布局: 首用户铺满大窗,每个角落悬浮一个小窗,最多支持4个小窗一共5个画面。

input参数

参数名称是否必填数据类型说明
uidstring主播uid
roomidstring输入流所属主播的开播房间,当前房间可不填
streamtypeint流类型:0音视频,1视频,2音频
layerint(已废弃,更新为参数zOrder) 图层(0为最底层,1为从底往上第1层,依次类推)
zOrderint图层(0为最底层,1为从底往上第1层,依次类推)
pos_xint(已废弃,更新为参数layoutX) 在画布中的左上角横坐标(坐标系:横轴向右增长,纵轴向下增长),纯音频混流时可不填
pos_yint(已废弃,更新为参数layoutY) 在画布中的左上角纵坐标,纯音频混流时可不填
pos_hint(已废弃,更新为参数layoutH) 在画布中的高度,纯音频混流时可不填
pos_wint(已废弃,更新为参数layoutW) 在画布中的宽度,纯音频混流时可不填
layoutXint在画布中的左上角横坐标(坐标系:横轴向右增长,纵轴向下增长),纯音频混流时可不填
layoutYint在画布中的左上角纵坐标,纯音频混流时可不填
layoutHint在画布中的高度,纯音频混流时可不填
layoutWint在画布中的宽度,纯音频混流时可不填
cropint缩放显示选项,0:输入流居中显示,补黑边,1:输入流尽量填满,居中裁剪
cutout_xint(已废弃,更新为参数cropX) 若输入是原画中的抠图,抠图区域在原图中的x坐标
cutout_yint(已废弃,更新为参数cropY) 若输入是原画中的抠图,抠图区域在原图中的y坐标
cutout_hint(已废弃,更新为参数cropH) 若输入是原画中的抠图,抠图区域的高度
cutout_wint(已废弃,更新为参数cropW) 若输入是原画中的抠图,抠图区域的宽度
cropXint若输入是原画中的抠图,抠图区域在原图中的x坐标
cropYint若输入是原画中的抠图,抠图区域在原图中的y坐标
cropHint若输入是原画中的抠图,抠图区域的高度
cropWint若输入是原画中的抠图,抠图区域的宽度
alphafloat当前主播在混流画面的透明度,取值范围(0,1.0)

output参数

参数名称是否必填数据类型说明
streamtypeint流类型:0音视频,1视频,2音频
videoheightint视频高度(有视频流时填),取值范围(0,10000),8的整数倍,建议值600
videowidthint视频宽度(有视频流时填),取值范围(0,10000),8的整数倍,建议值800
videobitrateint视频码率(有视频流时填),取值范围(0,10000],单位kbps,建议值800
videofpsint视频帧率(有视频流时填),取值范围(0,60],建议值24
videogopint视频GOP(有视频流时填),取值范围(0,1000),videofps的整数倍,计算方式为videofps乘GOP时间间隔(秒),建议值72(即24乘3秒)
videoencodeint视频编码(有视频流时填),100=H264,101=H265,默认H264,暂不支持265)
audiobitrateint音频码率(有音频流时填),单位kbps,填固定值64,实际会根据audioencode值进行调整
audiochannelint音频声道数(有音频流时填),填固定值2
audiosampleint音频采样率(有音频流时填),填固定值44100
audioencodeint音频编码(有音频流时填),1=AAC+,35=AAC(128kbps),建议值1
patchint视频补帧方式:0-不补帧,1-补黑屏,2-补最后一帧,3-补指定图片
patchUrlstring补帧方式=3,指定图片地址,长度不超过256字节
seilayoutint混画sei选项,seilayout=1时将视频源流布局信息打进混流视频中的SEI字段

注意:

traceId标记唯一。
源流推流不需要设置混画参数。
混流推流场景下output参数指定streamtype类型为2后开启纯音频推流。
混流推流场景下taskid如已存在会触发更新混画参数。
支持按照Appid级别配置默认推流任务,如需使用请联系技术支持。

startrtmp 请求示例

  • 请求 URL:
https://api.aivacom.com/app/1470236061/v2/rtmpforward/startrtmp?traceId=biz201909121223210013
  • 请求包体内容
{
    "appid":1470236061,
    "roomid":"123",
    "rtmpurl":"rtmp://aliyunbiz.upstream.biz.com/live/test",
    "streamtype":1,
    "taskid":"biz007",
    "mixconfig":{
        "input":[
            {
                "uid":"111",
                "roomid":"123",
                "streamtype":0,
                "zOrder":0,
                "layoutX":0,
                "layoutY":0,
                "layoutH":600,
                "layoutW":400,
                "crop":0
            },
            {
                "uid":"222",
                "roomid":"123",
                "streamtype":0,
                "zOrder":1,
                "layoutX":400,
                "layoutY":0,
                "layoutH":600,
                "layoutW":400,
                "crop":0
            }
        ],
        "output":{
            "streamtype":0,
            "videoheight":600,
            "videowidth":800,
            "videobitrate":800,
            "videofps":24,
            "videogop":72,
            "videoencode":100,
            "audiobitrate":64,
            "audiosample":44100,
            "audiochannel":2,
            "audioencode":1
        }
    }
}

startrtmp 响应示例

{
    "code": 0,
    "message": "success",
    "traceId": "23116613407505472693518435"
}
  • code: int,响应返回码
  • message: string, success代表成功,其它情况为一些错误的描述信息。
  • traceId: string, 请求时带的traceId,便于追踪

停止旁路推流:stoprtmp

对已启动的旁路推流任务进行停止操作

  • Head:
    • Content-typeapplication/json;charset=utf-8
    • AppID为 开发者平台分配的App Key
    • Nonce为 随机数组成的字符串,长度限制为30
    • Timestamp为 北京时间戳,从1970年1月1日0点0分0秒开始到现在的毫秒数
    • Signature为 数据签名,生成方法请参考签名认证
  • 请求host:
    • 国内:api.aivacom.com
    • 海外:api-oversea.aivacom.com
  • 请求url:app/{appid}/v2/rtmpforward/stoprtmp?traceId={yourTraceId}
    • appid: 你的项目使用的AppID
    • traceId: 用于跟踪每条API调用,可以用“服务器 IP + 产生 ID 时候的时间 + 自增序列 + 当前进程号”

参数说明:

参数名称是否必填数据类型说明
appiduint64业务Appid
roomidstring房间号
streamtypeuint32流类型:1=混流推流,2=源流推流
taskid混流推流必填string混流任务ID,对应启动推流任务的taskid
uid源流推流必填string用户id,对应启动推流任务的uid

注意:

支持按照Appid级别配置默认推流任务,如需使用请联系技术支持。

stoprtmp 请求示例

  • 请求 URL:
https://api.aivacom.com/app/1470236061/v2/rtmpforward/stoprtmp?traceId=biz201909121223210014
  • 请求包体内容
{
   "appid":1470236061,
   "roomid":"123",
   "streamtype":1,
   "taskid":"biz007"
}

stoprtmp 响应示例

  • 响应包体内容
{
    "code": 0,
    "message": "success",
    "traceId": "82719231231166134075054726935"
}
  • code: int,响应返回码
  • message: string, success代表成功,其它情况为一些错误的描述信息。
  • traceId: string, 请求时带的traceId,便于追踪。

响应返回码

编码说明备注
0成功请求成功
1000没有token授权业务调用接口header头部没有带token
1001token不合法token格式有误、内容不对
1002appid不存在appid不存在
2101参数非法接口参数非法
2102流状态异常推流状态异常
2103超时请求超时
2104内部错误内部服务访问出错

推流地址

推流鉴权

开启旁路推流服务前请确保第三方服务是否开启地址鉴权,如已开启鉴权,请确保推流地址带上有效的鉴权码,同时在推流返回失败后刷新鉴权码重新推流。

地址更新

推流地址按全量方式更新,在新地址列表中没有记录的旧推流任务会被停止,新地址列表中相对上一次旧推流地址列表新增的地址会被加入推流任务。

地址示例

rtmp://upstream.aivacom.com/live/test?auth_key=1585626386-0-0-8032e26583c58344e43cce3e251173b7

推流回调

服务器在推流过程中通过设定回调地址返回推流的内容及状态,业务可以直接对接cdn回调,但是一般情况下cdn回调只有首次成功后发送,建议业务对接聚联云推流回调,如需聚联云回调请联系聚联云技术支持。

推流回调返回参数

参数名称数据类型说明
urlstring推流地址
appnamestring应用名称
streamnamestring推流流名称
appiduint64业务Appid
roomidstring房间号
taskidstring任务ID,对应启动的推流任务taskid
statusuint32推流状态码,可参考推流回调状态码列表

推流回调状态码列表

代码说明
3000推流正常,定时发送
3001无法拉到音视频流,建议检查频道内上行音视频流,定时发送
3002推流异常中断,定时发送
3003推流终止

注意:

接入推流回调服务需要进行后台配置,如需使用请联系技术支持。

常见回调错误

下面仅列出常见的推流回调状态码,如果遇到其他错误,请联系技术支持。
3001:无法拉流音视频流,常见原因是主播上行或者开播异常,建议业务方检查主播状态。
3002:推流中断,常见原因是推流地址鉴权码错误或者重复推流,建议业务方检查推流地址。

<