API

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

如何调用API

事项	说明
请求URL	{https}://{域名}/app/{appid}/v2/rtmpforward/{方法名}?traceId={yourTraceId} appid：项目AppID，可从官网控制台获取AppID traceId：用于跟踪每条API调用，建议格式：服务器 IP + 产生 ID 时候的时间 + 自增序列 + 当前进程号
域名	中国大陆：rtc-api.yy.com 中国大陆以外区域：api-oversea.jocloud.com
Head	Content-Type：application/json;charset=UTF-8 AppID：项目AppID，可从官网控制台获取AppID Nonce：随机数组成的字符串，与 Timestamp 联合起来，用于防止重放攻击。 Timestamp：时间戳，记录发起 API 请求的时间。例如1541144032646，如果与当前时间相差过大，会引起签名过期错误 Signature：签名结果串，签名的计算方法请参考 HTTP签名规则
签名规则	请参考 HTTP签名规则

启动旁路推流

功能介绍

启动旁路推流，并设置布局参数来配置混流画面布局。

构造请求

请求方法：POST
方法名：app/appid/v2/rtmpforward/startrtmp?traceId={yourTraceId}

请求参数

参数名称	混流	源流	数据类型	说明
appid	必填	必填	uint64	项目AppID，可从官网控制台获取AppID
roomid	必填	必填	string	房间号
rtmpurl	必填	必填	string	旁路推流地址，多个地址用 `,` 分隔，最多支持5个
streamtype	必填	必填	uint32	流类型：1-混流、2-源流
taskid	必填	不填	string	混流任务ID（需保证唯一性），标识混流推流任务
mixconfig	必填	不填	JSON	混流参数
uid	不填	必填	string	用户ID
seqnum	可选	可选	uint64	业务方保证递增，值越大表示请求越新，启动与停止推流用同一个自增seqnum，用以解决请求顺序问题。若不填，服务器以收到请求的顺序为准

mixconfig

参数	类型	选择预设画面布局	自定义画面布局	描述
templateid	int	必填	不填	布局模板，详见混流布局 1：水平布局 2：垂直布局 3：平铺布局 4：角落布局只针对同房间的混流有效
intput	JSON	不填	必填	自定义布局参数，指定用户视频在混合画面中的显示位置
output	JSON	必填	必填	混流输出编码参数

input

参数	类型	音视频流	纯视频流	纯音频流	描述
uid	string	必填自定义	必填自定义	必填自定义	用户ID
roomid	string	必填自定义	必填自定义	必填自定义	用户所在的房间号
streamtype	int	0	1	2	需要混合的流类型：0-音视频流、1-纯视频流、2-纯音频流
cropX	int	可选	可选	不填	字段cropX、cropY、cropH和 cropW组合使用，可截取整个用户视频画面的部分区域，进行局部输出，视频裁剪画面坐标布局详见视频裁剪坐标体系指定输出区域在用户视频原图中的x坐标取值范围：[0, 1920]
cropY	int	可选	可选	不填	指定输出区域在用户视频原图中的y坐标取值范围：[0, 1920]
cropH	int	可选	可选	不填	指定输出区域相对于用户视频原图中的高度取值范围：(0, 1920]
cropW	int	可选	可选	不填	指定输出区域相对于用户视频原图中的宽度取值范围：(0, 1920]
zOrder	int	必填	必填	不填	图层：0为最底层，1为从底往上第1层，依次类推，最多设置16层，默认为0
layoutX	int	必填	必填	不填	该用户输出流在输出时在画布中的左上角横坐标（坐标系：横轴向右增长，纵轴向下增长），取值范围：[0, 1920]，详见布局坐标体系
layoutY	int	必填	必填	不填	该用户输出流在输出时在画布中的左上角纵坐标，取值范围：[0, 1920]
layoutH	int	必填	必填	不填	该用户输出流在输出时在画布中的高度，取值范围：(0, 1920]
layoutW	int	必填	必填	不填	该用户输出流在输出时在画布中的宽度，取值范围：(0, 1920]
crop	int	必填	必填	不填	缩放模式 0：输入流居中显示，补黑边 1：输入流尽量填满，居中裁剪
alpha	float	可选	可选	不填	该用户输出流在混流画面的透明度，取值范围：[0, 1.0] 0-完全透明、1.0-完全不透明
shape	int	可选	可选	不填	该用户输出流在混流画面的形状类型。可取值：0-矩形、1-圆形；默认值为0。其中，圆形规则详见圆形渲染规则

output

参数	类型	音视频流	纯音频流	描述
streamtype	int	0	2	需要输出的流类型：0-音视频流、2-纯音频流、1-预留参数
videoheight	int	必填	不填	视频输出高度，取值范围：[16, 1920]，必须为4的整数倍，不满足时向下取整
videowidth	int	必填	不填	视频输出宽度，取值范围：[16, 1920]，必须为4的整数倍，不满足时向下取整
videobitrate	int	必填	不填	视频输出码率，取值范围：(0,10000]，单位：kbps
videofps	int	必填	不填	视频输出帧率，取值范围：(0, 60]，默认值为 15fps 。若帧率设置高于60，服务后台会调整为 60
videogop	int	必填	不填	视视频输出GOP，单位：帧，取值范围：(0,1000)，默认值：30帧计算方式：videogop = videofps × 关键帧时间间隔（秒），且为videofps的整数倍，不满足时则 videogop/videofps 向上取整
videoencode	int	必填推荐100	不填	视频编码 100：H.264 101：H.265（H.265格式说明）
audiobitrate	int	必填	必填	音频码率，单位：kbps，取值范围：[24,192]，默认值：64
audiochannel	int	必填	必填	音频声道数，1-单声道，2-双声道，默认值：2 注意：编码格式为AAC+不支持单声道
audiosample	int	必填	必填	音频采样率，可选值：32000、44100（默认）、48000 单位：Hz
audioformat	int	必填	必填	音频编码 1：AAC+ 2：AAC
patch	int	可选	不填	输出视频补帧方式 0：不补帧 1：补黑屏 2：补最后一帧 3：补指定图片
patchUrl	string	可选	不填	输出视频补帧方式：固定取值3（指定图片地址），长度不超过256个字节
seilayout	int	可选	不填	混流SEI选项，seilayout=1时将视频源流布局信息打进混流视频中的SEI字段，SEI nal格式详见 seilayout和base64seidata
watermark	JSON	可选	不填	水印
background	JSON	可选	不填	背景图/色
base64seidata	string	可选	不填	自定义视频帧SEI信息，信息串为Base64编码，原始长度不超过2048字节，将解码内容打入视频帧，SEI格式详见 seilayout和base64seidata

watermark

参数名称	是否必填	数据类型	说明
timestamp	否	JSON	时间戳水印
textList	否	JSON Array	文字水印
imageList	否	JSON Array	图片水印

timestamp

参数名称	是否必填	数据类型	说明
x	是	int	以左上角为原点横轴坐标，取值范围[0,1920)，不超过混画输出宽度
y	是	int	以左上角为原点纵轴坐标，取值范围[0,1920)，不超过混画输出高度
format	是	string	支持posix时间显示格式，支持以下几种： "%Y/%m/%d": 显示为2020/01/01 "%Y-%m-%d": 显示为2020-01-01 "%H:%M:%S": 显示为13:00:00 "%Y/%m/%d %H:%M:%S": 显示为2020/01/01 13:00:00 "%Y-%m-%d %H:%M:%S": 显示为2020-01-01 13:00:00
font	否	string	字体格式，只支持默认值NotoSansCJK
size	是	int	字体大小，(0,100]
color	否	string	字体颜色，RGB颜色定义,取值000000-FFFFFF，字母都为大写或者都为小写的，默认为”FFFFFF” 白色
backgroundColor	否	string	背景颜色，RGB颜色定义,取值000000-FFFFFF，字母都为大写或者都为小写的，默认为”000000” 黑色
alpha	否	float	透明度，[0.0, 1.0],0.0表示该区域图像完全透明,而1.0表示该区域图像完全不透明

textList

参数名称	是否必填	数据类型	说明
x	是	int	以左上角为原点横轴坐标，取值范围[0,1920)，不超过混画输出宽度
y	是	int	以左上角为原点纵轴坐标，取值范围[0,1920)，不超过混画输出高度
content	是	string	显示内容串
font	否	string	字体格式，只支持默认值NotoSansCJK
size	是	int	字体大小，(0,100]
color	否	string	字体颜色，RGB颜色定义，取值000000-FFFFFF，字母都为大写或者都为小写的，默认为”FFFFFF” 白色
backgroundColor	否	string	背景颜色，RGB颜色定义，取值000000-FFFFFF，字母都为大写或者都为小写的，默认为”000000” 黑色
alpha	否	float	透明度，[0.0, 1.0],0.0表示该区域图像完全透明,而1.0表示该区域图像完全不透明

imageList

参数名称	是否必填	数据类型	说明
x	是	int	以左上角为原点横轴坐标，取值范围[0,1920)，不超过混画输出宽度
y	是	int	以左上角为原点纵轴坐标，取值范围[0,1920)，不超过混画输出高度
width	是	int	图片宽度，取值范围(0,1920)，不超过混画输出宽度
height	是	int	图片高度，取值范围(0,1920)，不超过混画输出高度
url	是	string	图片url地址，长度不超过256字节
scale	是	int	缩放/裁剪模式，0：等比例缩放裁剪，1：拉伸铺满整块画布
alpha	否	float	透明度，取值范围：[0.0, 1.0] 0.0-完全透明、1.0-完全不透明

background

参数名称	是否必填	数据类型	说明
color	否	string	背景色，RGB颜色定义，取值000000-FFFFFF，字母都为大写或者都为小写的，默认为”000000” 黑色
image	否	JSON	背景图，color与image都填时image会覆盖color

image

参数名称	是否必填	数据类型	说明
url	是	string	背景图url地址，长度不超过256字节
scale	是	int	缩放/裁剪模式，0：等比例缩放裁剪，1：拉伸铺满整块画布

seilayout和base64seidata

seilayout为混画SEI选项，seilayout=1时将视频源流布局信息打进混流视频中的SEI字段。
base64seidata 为base64编码后的自定义视频帧SEI信息。

SEI nal unit，添加在每帧视频编码数据前面，I帧sps pps后面。SEI nal格式如下：

H.264 SEI

字段名	字段长度（byte）	备注
Nal size	4	大端序，后面所有字段的长度和，不包括本字段
Unit type	1	Zero_bit + ref_idc + unit type 推荐取值：6
Payload type	1	推荐取值：201
Payload size	Payload size/255 + 1	255 + 255 + 255 + …，payload字段的长度
Payload
Tailing bit	1	推荐取值：128

H.265 SEI

字段名	字段长度（byte）	说明
Nal start code	4	取值：0x00000001
Unit type	1	Zero_bit + unit type + reserve 推荐取值：78
Temporal id	1	推荐取值：1
Payload type	1	推荐取值：201
Payload size	Payload size/255 + 1	255 + 255 + 255 + …，payload字段的长度
Payload
Tailing bit	1	推荐取值：128

sei对应的payload如下：

字段名	说明
length	大端序，本类型数据长度（包括本字段），最大长度为2字节
payload type	4-布局数据、6-任务参数指定内容；最大长度为1字节
payload	具体数据

布局数据(payload type取值4: layout data) payload:

字段名	说明
data cnt	主播个数，字段最大长度1字节
layout data1	主播1布局
layout data2	主播2布局
...
outwidth	输出视频宽，字段最大长度2字节
outheight	输出视频高，字段最大长度2字节

layout data：

字段名	字段长度（byte）	说明
layout len	2	本类型数据长度，包括本字段
uid len	1	uid长度
uid data	uid len	uid字符串
Data len	2	业务数据长度
Data	Data len	业务数据
flag	1	(flag & 1) == 1表示存在布局字段； (flag & 2) == 1表示补帧； (flag & 2) == 1表示补帧；
alpha	1	视频透明度（布局字段），取值范围：[0,255]
zorder	1	视频层级（布局字段），取值范围：[0,255]
Src width	2	原始视频宽（布局字段）
Src height	2	原始视频高（布局字段）
crop x	2	裁剪x坐标（布局字段）
crop y	2	裁剪y坐标（布局字段）
crop width	2	裁剪宽度（布局字段）
crop height	2	裁剪高度（布局字段）
Dest x	2	目标视频x坐标（布局字段）
Dest y	2	目标视频y坐标（布局字段）
Dest width	2	目标视频宽度（布局字段）
Dest height	2	目标视频高度（布局字段）

自定义视频帧SEI信息 (payload type取值6: param data) payload：

字段名	字段长度（byte）	说明
Data len	2	数据长度
Data	Data len	任务参数携带数据

响应参数

参数	类型	说明
code	int	响应返回码
message	string	响应描述：success-成功，其它-错误描述信息
traceId	string	请求时带的traceId，便于追踪

示例

请求示例

请求 URL

https://api.jocloud.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,
            "audioformat":2,
            "audiobitrate":128,
            "audiosample":44100,
            "audiochannel":2
        }
    }
}

响应示例

{
    "code": 0,
    "message": "success",
    "traceId": "23116613407505472693518435"
}

停止旁路推流

功能介绍

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

构造请求

请求方法：POST
方法名：app/{appid}/v2/rtmpforward/stoprtmp?traceId={yourTraceId}

请求参数

参数名称	混流	源流	数据类型	说明
appid	必填	必填	uint64	项目AppID，可从官网控制台获取AppID
roomid	必填	必填	string	房间号
streamtype	必填	必填	uint32	流类型：1-混流推流，2-源流推流
taskid	必填	不填	string	混流任务ID，对应启动推流任务的 taskid 说明：支持按照AppID级别配置默认推流任务，如需使用请联系技术支持
uid	不填	必填	string	用户ID，对应启动推流任务的 uid
seqnum	可选	可选	uint64	业务方保证递增，值越大表示请求越新，启动与停止推流用同一个自增seqnum，用以解决请求顺序问题。若不填，服务器以收到请求的顺序为准

响应参数

参数	类型	说明
code	int	响应返回码
message	string	响应描述：success-成功，其它-错误描述信息
traceId	string	请求时带的traceId，便于追踪

示例

请求示例

请求 URL

https://api.jocloud.com/app/1470236061/v2/rtmpforward/stoprtmp?traceId=biz201909121223210014

请求包体内容

{
   "appid":1470236061,
   "roomid":"123",
   "streamtype":1,
   "taskid":"biz007"
}

响应示例

响应包体内容

{
    "code": 0,
    "message": "success",
    "traceId": "82719231231166134075054726935"
}

附录

响应返回码

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

推流地址

推流鉴权

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

地址更新

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

地址示例

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

推流回调

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

回调请求

回调地址支持HTTPS或HTTP

事项	说明
请求URL	业务方提供的回调地址
Head	Content-Type：application/json;charset=UTF-8 AppID：项目AppID，可从官网控制台获取AppID Nonce：随机数组成的字符串，与 Timestamp 联合起来，用于防止重放攻击。 Timestamp：时间戳，记录发起 API 请求的时间。例如1541144032646，如果与当前时间相差过大，会引起签名过期错误 Signature：签名结果串，签名的计算方法请参考 HTTP签名规则
签名规则	请参考 HTTP签名规则，业务方通过校验Signature字段识别请求有效性

返回参数

返回参数为JSON格式，参数说明如下：

参数名称	数据类型	说明
url	string	推流地址
appname	string	应用名称
streamname	string	推流流名称
appid	uint64	业务Appid
roomid	string	房间号
taskid	string	任务ID，对应启动的推流任务taskid
status	uint32	推流状态码，可参考推流回调状态码列表
version	uint64	回调版本号，唯一递增
errcode	uint32	推流错误码，参考推流回调详细错误码
description	string	推流详细信息

状态码

下面仅列出常见的推流回调状态码，如果遇到其他错误，请联系技术支持。

代码	说明
3000	推流正常，定时发送
3001	无法拉到音视频流。常见原因是主播上行或者开播异常，建议业务方检查主播状态。建议检查频道内上行音视频流，定时发送
3002	推流异常中断，定时发送。常见原因是推流地址鉴权码错误或者重复推流，建议业务方检查推流地址。
3003	推流终止

错误码

代码	说明
0	推流正常
1	URL格式错误
2	推流并发路数达到上限
3	推流超时
1001	tcp连接中断
1002	tcp连接失败
1003	rtmp推流被拒，请检查鉴权参数或者推流流名称是否重复等
2001	推流数据停止
2002	推流数据不存在
2003	推流服务器内部失败

API

如何调用API

启动旁路推流

功能介绍

构造请求

请求参数

mixconfig

input

output

watermark

timestamp

textList

imageList

background

image

seilayout和base64seidata

响应参数

示例

请求示例

响应示例

停止旁路推流

功能介绍

构造请求

请求参数

响应参数

示例

请求示例

响应示例

附录

响应返回码

推流地址

推流鉴权

地址更新

地址示例

推流回调

回调请求

返回参数

状态码

错误码

文档是否有解决您的问题？