阅读本章节前请确保你已经了解过 快速开始。
事项 | 说明 |
---|---|
请求URL | {https}://{域名}/app/{appid}/v1/recordoss/{方法名}?traceId={yourTraceId} appid:项目AppID,可从官网控制台 获取AppID traceId:用于跟踪每条API调用,建议格式:服务器 IP + 产生 ID 时候的时间 + 自增序列 + 当前进程号 |
域名 | 中国大陆:api.jocloud.com 中国大陆以外区域:api-oversea.jocloud.com |
Head | Content-Type:application/json;charset=UTF-8 AppID:项目AppID,可从官网控制台 获取AppID Nonce:随机数组成的字符串,与 Timestamp 联合起来,用于防止重放攻击。 Timestamp:时间戳,记录发起 API 请求的时间。例如1541144032646,如果与当前时间相差过大,会引起签名过期错误 Signature: 签名结果串,签名的计算方法请参考 HTTP签名规则 |
签名规则 | 请参考 HTTP签名规则 |
applyrecord
在启动云录制之前,你需要调用该方法获取一个资源resid。
注意:
每个 appid 每秒钟的请求数限制为 10 次。
https://api.jocloud.com/app/10034/v1/recordoss/applyrecord?traceId=23116613407505472693518435
{
"code": 0,
"message": "success",
"resid": "1d3fe093f9b9dbfa2d34e22cb34a12496ed6b057896358131208a0d981eb-ba11073100006be2",
"traceId": "23116613407505472693518435"
}
code
: int,响应返回码。message
: string, success代表成功,其它情况为一些错误的描述信息。resid
: string,云录制资源ID,使用这个ID 可以启动一次云录制。这个ID 的有效期为 5 分钟,超时需要重新请求。traceId
: string, 请求时带的traceId,便于追踪startrecord
在调用 applyrecord 获取resid之后,调用该API启动云录制。
名称 | 类型 | 混流 | 源流 | 描述 |
---|---|---|---|---|
resid | string | 必填 | 必填 | 调用获取录制资源后返回的 resid |
appid | int | 必填 | 必填 | 你的项目使用的 appid |
roomid | string | 必填 | 必填 | 待录制的房间号 |
recordtype | int | 必填 | 必填 | 录制类型 0:音视频录制(默认) 1:视频录制 2:音频录制 取值范围:0,1,2 |
streamtype | int | 1 | 2 | 1:混流录制 2:源流录制 取值范围:1,2 |
mixconfig | JSON | 必填 | 不填 | 混流配置 |
uid | string | 不填 | 必填 | 用户id |
storagecfg | JSON | 必填 | 必填 | OSS存储配置 |
callbackurl | string | 可选 | 可选 | 指定回调地址 |
参数 | 类型 | 预设画面布局 | 自定义画面布局 | 描述 |
---|---|---|---|---|
intput | JSONArray | 不填 | 必填 | 输入参数,使用预设画面布局的情况不填 |
templateid | int | 必填 | 不填 | 布局模板,详见 混流布局: 1:水平布局 2:垂直布局 3:平铺布局 4:角落布局 5:5人水平布局 只针对同房间的混流有效 |
output | JSON | 必填 | 必填 | 输出参数 |
参数 | 类型 | 音视频流 | 纯视频流 | 纯音频流 | 描述 |
---|---|---|---|---|---|
uid | string | 自定义 | 自定义 | 自定义 | 用户ID |
roomid | string | 自定义 | 自定义 | 自定义 | 用户ID所在的房间号 |
streamtype | int | 0 | 1 | 2 | 流类型:0-音视频,1-纯视频,2-纯音频 |
zOrder | int | 自定义 | 自定义 | 不填 | 图层(0为最底层,1为从底往上第1层,依次类推,最多设置16层) |
layoutX | int | 自定义 | 自定义 | 不填 | 在画布中的左上角横坐标(坐标系:横轴向右增长,纵轴向下增长),取值范围:[0,1920] |
layoutY | int | 自定义 | 自定义 | 不填 | 在画布中的左上角纵坐标,取值范围:[0,1920] |
layoutH | int | 自定义 | 自定义 | 不填 | 在画布中的高度,取值范围:(0,1920] |
layoutW | int | 自定义 | 自定义 | 不填 | 在画布中的宽度,取值范围:(0,1920] |
crop | int | 自定义 | 自定义 | 不填 | 缩放模式 0:居中显示,补黑边 1:尽量填满,居中裁剪 |
cropX | int | 可选 | 可选 | 不填 | 若输入是原画中的抠图,抠图区域在原图中的x坐标 取值范围:[0,1920] |
cropY | int | 可选 | 可选 | 不填 | 若输入是原画中的抠图,抠图区域在原图中的y坐标 取值范围:[0,1920] |
cropH | int | 可选 | 可选 | 不填 | 若输入是原画中的抠图,抠图区域的高度 取值范围:(0,1920] |
cropW | int | 可选 | 可选 | 不填 | 若输入是原画中的抠图,抠图区域的宽度 取值范围:(0,1920] |
alpha | float | 可选 | 可选 | 不填 | 在混流画面的透明度,取值范围:[0,1.0] 0-完全透明,1.0-完全不透明 |
参数 | 类型 | 音视频流 | 纯视频流 | 纯音频流 | 描述 |
---|---|---|---|---|---|
streamtype | int | 0 | 1 | 2 | 流类型:0-音视频,1-纯视频,2-纯音频 |
videoheight | int | 自定义 | 自定义 | 不填 | 视频高度,取值范围[16,1920],必须为4的整数倍,不满足时向下取整 |
videowidth | int | 自定义 | 自定义 | 不填 | 视频宽度,取值范围[16,1920],必须为4的整数倍,不满足时向下取整 |
videobitrate | int | 自定义 | 自定义 | 不填 | 视频码率,取值范围(0,10000],单位:kbps |
videofps | int | 推荐15 | 推荐15 | 不填 | 视频帧率,取值范围(0,60],默认值为 15fps 。若帧率设置高于60,服务后台会调整为 60 。 |
videogop | int | 推荐30 | 推荐30 | 不填 | 视频GOP,单位:帧,取值范围:(0,1000),默认值:30帧 计算方式:videogop = videofps × 关键帧时间间隔(秒),且为videofps的整数倍,不满足时则 videogop/videofps 向上取整 |
videoencode | int | 100 | 100 | 不填 | 视频编码:100-H264(暂不支持H265) |
audiobitrate | int | 128 | 可选 | 128 | 音频码率,单位:kbps,固定取值 128 |
audiochannel | int | 2 | 可选 | 2 | 音频声道数:固定取值 2(双声道) |
audiosample | int | 48000 | 可选 | 48000 | 音频采样率,固定取值 48000 |
audioformat | int | 2 | 可选 | 2 | 音频编码格式:固定取值2(AAC) |
patch | int | 可选 | 可选 | 不填 | 输出视频补帧方式 0-不补帧 1-补黑屏 2-补最后一帧 3-补指定图片 |
patchUrl | string | 可选 | 可选 | 不填 | 输出视频补帧方式:固定取值3(指定图片地址),长度不超过256个字节 |
watermark | JSON | 可选 | 可选 | 不填 | 水印 |
background | JSON | 可选 | 可选 | 不填 | 背景图、背景色 |
base64seidata | string | 可选 | 可选 | 不填 | 自定义视频帧 SEI 信息,信息串为 Base64 编码,原始长度不超过 2048 字节,将解码内容打入每个视频帧。纯音频流设置无效。 |
参数 | 类型 | 是否必选 | 描述 |
---|---|---|---|
timestamp | JSON | 否 | 时间戳水印 |
textList | JSON Array | 否 | 文字水印 |
imageList | JSON Array | 否 | 图片水印 |
参数 | 类型 | 是否必选 | 描述 |
---|---|---|---|
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 表示该区域图像完全不透明 |
参数 | 类型 | 是否必选 | 描述 |
---|---|---|---|
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 表示该区域图像完全不透明 |
参数 | 类型 | 是否必选 | 描述 |
---|---|---|---|
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 表示该区域图像完全不透明 |
参数 | 类型 | 是否必选 | 描述 |
---|---|---|---|
color | string | 否 | 背景色,RGB颜色定义,取值 000000-FFFFFF,字母都为大写或者都为小写的,默认为 000000 (黑色) |
image | JSON | 否 | 背景图,color 与 image 都填时 image 会覆盖 color |
参数 | 类型 | 是否必选 | 描述 |
---|---|---|---|
url | string | 是 | 背景图url地址,长度不超过256字节 |
scale | int | 是 | 缩放/裁剪模式,0:等比例缩放裁剪,1:拉伸铺满整块画布 |
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
vender | int | 是 | 厂商类型 0:阿里云 1:腾讯云 2:七牛云 |
endpoint | string | 是 | OSS的endpoint |
bucket | string | 是 | OSS的bucket |
accesskey | string | 是 | OSS的accesskey |
secretkey | string | 是 | OSS的secretkey |
fileprefix | JSONArray | 否 | 数组格式,由多个字符串组成,用于指定录制文件在第三方云存储中的存储目录 举例:fileprefix = ["aaaa","bbbb"], 存储目录将加上 "aaaa/bbbb/" 的前缀,即 aaaa/bbbb/testtest.m3u8。加上斜杠符号,整个前缀的长度不得超过 128 个字符。每个字符串本身不得含斜杠符号。只支持 [A,Z],[a,z],[0,9] 等字符的排列组合 |
注意:
https://api.jocloud.com/app/10034/v1/recordoss/startrecord?traceId=82719231231166134075054726935
{
"resid": "1d3fe093f9b9dbfa2d34e22cb34a12496ed6b057896358131208a0d981eb-ba11073100006be2",
"appid": 10034,
"roomid": "abcabc",
"recordtype": 0,
"streamtype": 1,
"mixconfig":{
"input":[
{
"uid":"10266666",
"roomid":"abcabc",
"streamtype":0,
"zOrder":0,
"layoutX":0,
"layoutY":0,
"layoutH":600,
"layoutW":400,
"crop":0
},
{
"uid":"10277777",
"roomid":"efdefd",
"streamtype":0,
"zOrder":1,
"layoutX":400,
"layoutY":0,
"layoutH":600,
"layoutW":400,
"crop":0
}
],
"output":{
"streamtype":0,
"videoheight":600,
"videowidth":800,
"videobitrate":600,
"videofps":24,
"videogop":72,
"videoencode":100,
"audiobitrate":128,
"audiosample":48000,
"audiochannel":2,
"audioformat":2
}
},
"storagecfg": {
"vender": 0,
"endpoint": "xxxx-test-endpoint",
"bucket": "xxxx-test-bucket",
"accesskey": "xxxx-test-accesskey",
"secretkey": "xxxx-test-secretkey",
"fileprefix": ["test1","test2"]
}
}
{
"code": 0,
"message": "success",
"recordid": "ba1107310000565164da34f816f842da94d",
"traceId": "82719231231166134075054726935"
}
code
: int,响应返回码。message
: string, success代表成功,其它情况为一些错误的描述信息。recordid
: string,云录制任务ID,标识一次录制任务,后续如变更混流布局或停止录制,需带上该ID。traceId
: string, 请求时带的traceId,便于追踪。stoprecord
启动录制后,调用该API停止录制。
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
appid | int | 是 | 你的项目使用的appid |
resid | string | 是 | 调用 获取录制资源 后返回的 resid |
roomid | string | 是 | 待录制的房间号 |
recordid | string | 是 | 调用 启动录制 成功返回的 录制id |
注意:
- 请求数限制为每个 appid 每秒钟 10 次。
- 当房间内没流或者没流数据超过预设时间(默认为 30 秒) 后,云端录制也会自动停止录制,如需特殊配置请联系与您对接的技术支持人员。
- 录制停止后如需再次录制,必须再调用 applyrecord 方法请求一个新的 resid。
https://api.jocloud.com/app/10034/v1/recordoss/stoprecord?traceId=214325255213407589332213
{
"resid": "1d3fe093f9b9dbfa2d34e22cb34a12496ed6b057896358131208a0d981eb-ba11073100006be2",
"appid": 10034,
"roomid": "abcabc",
"recordid": "ba1107310000565164da34f816f842da94d"
}
{
"code": 0,
"message": "success",
"recordid": "ba1107310000565164da34f816f842da94d",
"traceId": "214325255213407589332213"
}
code
: int,响应返回码。message
: string, success代表成功,其它情况为一些错误的描述信息。recordid
: string,云录制任务ID,标识一次录制任务,调用startrecord
返回的ID。traceId
: string, 请求时带的traceId,便于追踪。updatemixrecord
启动混流录制后,可调用该API更新该次录制任务的混流布局。
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
resid | string | 是 | 调用 获取录制资源 后返回的 resid |
appid | int | 是 | 你的项目使用的appid |
roomid | string | 是 | 待录制的房间号 |
recordid | string | 是 | 调用 启动录制 成功返回的 录制id |
mixconfig | JSON | 是 | 混流配置 |
注意:
- 请求数限制为每个 appid 每秒钟 10 次。
- 在启动录制后,停止录制结束前,调用该API,否则会报错。
- 该API只支持混流录制,对源流录制会返回报错(响应返回码:4019,录制任务类型非混流录制)。
- 录制停止后如需再次录制,必须再调用 applyrecord 方法请求一个新的 resid。
https://api.jocloud.com/app/10034/v1/recordoss/updatemixrecord?traceId=82719231231166134075054726935
{
"resid": "1d3fe093f9b9dbfa2d34e22cb34a12496ed6b057896358131208a0d981eb-ba11073100006be2",
"appid": 10034,
"roomid": "abcabc",
"recordid": "ba1107310000565164da34f816f842da94d",
"mixconfig":{
"input":[
{
"uid":"10266666",
"roomid":"abcabc",
"streamtype":0,
"zOrder":0,
"layoutX":0,
"layoutY":0,
"layoutH":600,
"layoutW":400,
"crop":0
},
{
"uid":"10277777",
"roomid":"efdefd",
"streamtype":0,
"zOrder":1,
"layoutX":400,
"layoutY":0,
"layoutH":600,
"layoutW":400,
"crop":0
}
],
"output":{
"streamtype":0,
"videoheight":720,
"videowidth":1280,
"videobitrate":1000,
"videofps":24,
"videogop":72,
"videoencode":100,
"audiobitrate":128,
"audiosample":48000,
"audiochannel":2,
"audioformat":2
}
}
}
{
"code": 0,
"message": "success",
"recordid": "ba1107310000565164da34f816f842da94d",
"traceId": "82719231231166134075054726935"
}
code
: int,响应返回码。message
: string, success代表成功,其它情况为一些错误的描述信息。recordid
: string,云录制任务ID,标识录制任务,调用startrecord
返回的ID。traceId
: string, 请求时带的traceId,便于追踪。queryrecord
启动录制后,可调用该API查询该次录制任务的状态。
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
appid | int | 是 | 你的项目使用的appid |
roomid | string | 是 | 调用 启动录制 的房间号 |
recordid | string | 是 | 调用 启动录制 成功返回的 录制id |
注意:
- 请求数限制为每个 recordid 每秒钟 10 次。
- 在启动录制后,停止录制结束前,调用该API。
- 在录制任务停止后调用(含主动停止和超时停止场景),该API会返回报错(响应返回码:4013,录制 recordid 不存在)。
https://api.jocloud.com/app/10034/v1/recordoss/queryrecord/abcabc/ba1107310000565164da34f816f842da94d?traceId=82719231231166134075054726935
{
"code": 0,
"message": "success",
"recordid": "ba1107310000565164da34f816f842da94d",
"data": {
"recordid": "ba1107310000565164da34f816f842da94d",
"appid": 10034,
"roomid": "abcabc",
"status": 0,
"createtime": 1608084987733,
"starttime": 0
},
"traceId": "82719231231166134075054726935"
}
code
: int,响应返回码,在录制任务停止后调用,该API会返回 4013 报错。
message
: string, success代表成功,其它情况为一些错误的描述信息。
recordid
: string,云录制任务ID,标识录制任务,调用 startrecord
返回的ID。
traceId
: string, 请求时带的traceId,便于追踪。
data
: JSON, 录制任务的信息,详情如下:
名称 | 类型 | 描述 |
---|---|---|
appid | int | 你的项目使用的 appid |
roomid | string | 调用 启动录制 的房间号 |
recordid | string | 调用 启动录制 成功返回的 录制id |
status | int | 录制任务状态 0: 初始化完成 1: 任务启动 |
createtime | int | 录制创建时间点,单位毫秒 |
starttime | int | 录制启动时间点,单位毫秒 |
返回码 | 描述 | 备注 |
---|---|---|
0 | 成功 | 请求成功 |
1000 | 没有token授权 | 业务调用接口header头部没有带token |
1001 | token不合法 | token格式有误、内容不对 |
1002 | appid不存在 | appid不存在 |
2101 | 参数非法 | 接口参数非法 |
2103 | 超时 | 请求超时 |
2104 | 内部错误 | 内部服务访问出错 |
2105 | 命令调用错误 | 命令调用太频繁 |
2106 | 资源过载 | 资源过载 |
4001 | 录制错误 | 录制操作超时 |
4004 | 录制错误 | 录制参数不支持 |
4005 | 录制错误 | 房间未开播 |
4006 | 录制错误 | 录制时间参数非法 |
4007 | 录制错误 | 录制操作超时 |
4008 | 录制错误 | 录制停止失败 |
4009 | 录制错误 | 录制停止超时 |
4011 | 录制错误 | 录制任务已存在 |
4012 | 录制错误 | 录制 resid 非法或已超时失效 |
4013 | 录制错误 | 录制 recordid 不存在 |
4014 | 录制错误 | 混流操作失败 |
4015 | 录制错误 | 混流操作超时 |
4016 | 录制错误 | 混流参数非法 |
4017 | 录制错误 | 混流操作失败 |
4018 | 录制错误 | 混流内部错误 |
4019 | 录制错误 | 录制任务类型非混流录制 |
下面仅列出使用过程中的常见错误码或错误信息,如果遇到其他错误,也可先查 响应返回码 ,或请联系与您对接的技术支持人员。
HTTP响应 404 情况:
2101:参数非法,请确保参数类型正确、大小写正确、必填的参数均已填写。
4005:请确保房间内已开播。
4011:录制已经在进行中 ,请勿用同一个 resid 重复 start 请求。如需发起多路录制,需要再次调用 applyrecord 方法获取新的 resid。
4012:resid 失效或过期。获得 resid 后必须在 5 分钟内开始云端录制。请重新调用 applyrecord 获取新的 resid。