云录制 RESTful API

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

如何调用API

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

获取录制资源:applyrecord

功能介绍

在启动云录制之前,你需要调用该方法获取一个资源resid。

构造请求

  • 请求方法:GET
  • 方法名:app/{appid}/v1/recordoss/applyrecord?traceId={yourTraceId}

注意:

每个 appid 每秒钟的请求数限制为 10 次。

请求示例

  • 请求 URL:
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启动云录制。

构造请求

  • 请求方法:POST
  • 方法名:app/{appid}/v1/recordoss/startrecord?traceId={yourTraceId}

请求参数

名称类型混流源流描述
residstring必填必填调用获取录制资源后返回的 resid
appidint必填必填你的项目使用的 appid
roomidstring必填必填待录制的房间号
recordtypeint必填必填录制类型
0:音视频录制(默认)
1:视频录制
2:音频录制
取值范围:0,1,2
streamtypeint121:混流录制
2:源流录制
取值范围:1,2
mixconfigJSON必填不填混流配置
uidstring不填必填用户id
storagecfgJSON必填必填OSS存储配置
callbackurlstring可选可选指定回调地址

mixconfig

参数类型预设画面布局自定义画面布局描述
intputJSONArray不填必填输入参数,使用预设画面布局的情况不填
templateidint必填不填布局模板,详见 混流布局
1:水平布局
2:垂直布局
3:平铺布局
4:角落布局
5:5人水平布局
只针对同房间的混流有效
outputJSON必填必填输出参数

input

参数类型音视频流纯视频流纯音频流描述
uidstring自定义自定义自定义用户ID
roomidstring自定义自定义自定义用户ID所在的房间号
streamtypeint012流类型:0-音视频,1-纯视频,2-纯音频
zOrderint自定义自定义不填图层(0为最底层,1为从底往上第1层,依次类推,最多设置16层)
layoutXint自定义自定义不填在画布中的左上角横坐标(坐标系:横轴向右增长,纵轴向下增长),取值范围:[0,1920]
layoutYint自定义自定义不填在画布中的左上角纵坐标,取值范围:[0,1920]
layoutHint自定义自定义不填在画布中的高度,取值范围:(0,1920]
layoutWint自定义自定义不填在画布中的宽度,取值范围:(0,1920]
cropint自定义自定义不填缩放模式
0:居中显示,补黑边
1:尽量填满,居中裁剪
cropXint可选可选不填若输入是原画中的抠图,抠图区域在原图中的x坐标
取值范围:[0,1920]
cropYint可选可选不填若输入是原画中的抠图,抠图区域在原图中的y坐标
取值范围:[0,1920]
cropHint可选可选不填若输入是原画中的抠图,抠图区域的高度
取值范围:(0,1920]
cropWint可选可选不填若输入是原画中的抠图,抠图区域的宽度
取值范围:(0,1920]
alphafloat可选可选不填在混流画面的透明度,取值范围:[0,1.0]
0-完全透明,1.0-完全不透明

output

参数类型音视频流纯视频流纯音频流描述
streamtypeint012流类型:0-音视频,1-纯视频,2-纯音频
videoheightint自定义自定义不填视频高度,取值范围[16,1920],必须为4的整数倍,不满足时向下取整
videowidthint自定义自定义不填视频宽度,取值范围[16,1920],必须为4的整数倍,不满足时向下取整
videobitrateint自定义自定义不填视频码率,取值范围(0,10000],单位:kbps
videofpsint推荐15推荐15不填视频帧率,取值范围(0,60],默认值为 15fps 。若帧率设置高于60,服务后台会调整为 60 。
videogopint推荐30推荐30不填视频GOP,单位:帧,取值范围:(0,1000),默认值:30帧
计算方式:videogop = videofps × 关键帧时间间隔(秒),且为videofps的整数倍,不满足时则 videogop/videofps 向上取整
videoencodeint100100不填视频编码:100-H264(暂不支持H265)
audiobitrateint128可选128音频码率,单位:kbps,固定取值 128
audiochannelint2可选2音频声道数:固定取值 2(双声道)
audiosampleint48000可选48000音频采样率,固定取值 48000
audioformatint2可选2音频编码格式:固定取值2(AAC)
patchint可选可选不填输出视频补帧方式
0-不补帧
1-补黑屏
2-补最后一帧
3-补指定图片
patchUrlstring可选可选不填输出视频补帧方式:固定取值3(指定图片地址),长度不超过256个字节
watermarkJSON可选可选不填水印
backgroundJSON可选可选不填背景图、背景色
base64seidatastring可选可选不填自定义视频帧 SEI 信息,信息串为 Base64 编码,原始长度不超过 2048 字节,将解码内容打入每个视频帧。纯音频流设置无效。

watermark

参数类型是否必选描述
timestampJSON时间戳水印
textListJSON Array文字水印
imageListJSON Array图片水印

timestamp

参数类型是否必选描述
xint以左上角为原点横轴坐标,取值范围 [0,1920),不超过混画输出宽度
yint以左上角为原点纵轴坐标,取值范围 [0,1920),不超过混画输出高度
formatstring支持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
fontstring字体格式,只支持默认值 "NotoSansCJK"
sizeint字体大小,(0,100]
colorstring字体颜色,RGB颜色定义,取值 000000-FFFFFF,字母都为大写或者都为小写的,默认为 "FFFFFF" 白色
backgroundColorstring背景颜色,RGB颜色定义,取值 000000-FFFFFF,字母都为大写或者都为小写的,默认为 "000000" 黑色
alphafloat透明度,[0.0, 1.0],0.0 表示该区域图像完全透明,而 1.0 表示该区域图像完全不透明

textList

参数类型是否必选描述
xint以左上角为原点横轴坐标,取值范围 [0, 1920),不超过混画输出宽度
yint以左上角为原点纵轴坐标,取值范围 [0, 1920),不超过混画输出高度
contentstring显示内容串
fontstring字体格式,只支持默认值 "NotoSansCJK"
sizeint字体大小,(0,100]
colorstring字体颜色,RGB颜色定义,取值 000000-FFFFFF,字母都为大写或者都为小写的,默认为 "FFFFFF" 白色
backgroundColorstring背景颜色,RGB颜色定义,取值 000000-FFFFFF,字母都为大写或者都为小写的,默认为 "000000" 黑色
alphafloat透明度,[0.0, 1.0],0.0 表示该区域图像完全透明,而 1.0 表示该区域图像完全不透明

imageList

参数类型是否必选描述
xint以左上角为原点横轴坐标,取值范围 [0, 1920),不超过混画输出宽度
yint以左上角为原点纵轴坐标,取值范围 [0, 1920),不超过混画输出高度
widthint图片宽度,取值范围 (0, 1920),不超过混画输出宽度
heightint图片高度,取值范围 (0, 1920),不超过混画输出高度
urlstring图片url地址,长度不超过256字节
scaleint缩放/裁剪模式,0:等比例缩放裁剪,1:拉伸铺满整块画布
alphafloat透明度,[0.0, 1.0],0.0 表示该区域图像完全透明,而 1.0 表示该区域图像完全不透明

background

参数类型是否必选描述
colorstring背景色,RGB颜色定义,取值 000000-FFFFFF,字母都为大写或者都为小写的,默认为 000000 (黑色)
imageJSON背景图,color 与 image 都填时 image 会覆盖 color

image

参数类型是否必选描述
urlstring背景图url地址,长度不超过256字节
scaleint缩放/裁剪模式,0:等比例缩放裁剪,1:拉伸铺满整块画布

storagecfg

名称类型是否必选描述
venderint厂商类型
0:阿里云
1:腾讯云
2:七牛云
endpointstringOSS的endpoint
bucketstringOSS的bucket
accesskeystringOSS的accesskey
secretkeystringOSS的secretkey
fileprefixJSONArray数组格式,由多个字符串组成,用于指定录制文件在第三方云存储中的存储目录
举例:fileprefix = ["aaaa","bbbb"], 存储目录将加上 "aaaa/bbbb/" 的前缀,即 aaaa/bbbb/testtest.m3u8。加上斜杠符号,整个前缀的长度不得超过 128 个字符。每个字符串本身不得含斜杠符号。只支持 [A,Z],[a,z],[0,9] 等字符的排列组合

注意:

  • 请求数限制为每个 appid 每秒钟 10 次。
  • 使用布局模板 templateid 无需填写输入流信息,但只针对同房间混流有效,如果需要使用跨房间混流请填input参数。
  • 使用混流的音频录制功能时,混流配置 只需要填音频相关参数即可。如果不填input参数,则表示针对同房间的所有音频流进行混流音频录制,如果需要使用跨房间混流请填input参数。
  • 源流录制不需要设置 混流配置

endpoint

  • 当 vender = 0,即第三方云存储为阿里云时,endpoint的内容为OSS的外网Endpoint。
    例如:oss-cn-shenzhen.aliyuncs.com

img

  • 当 vender = 1,即第三方云存储为腾讯云时,endpoint的内容为上传域名除去 BucketName-APPID 的字符串。
    例如:cos.ap-guangzhou.myqcloud.com

img

  • 当 vender = 2,即第三方云存储为七牛云时,endpoint的内容为访问 Endpoint 名。
    例如:s3-cn-south-1.qiniucs.com

img

请求示例

  • 请求 URL:
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停止录制。

构造请求

  • 请求方法:POST
  • 方法名:app/{appid}/v1/recordoss/stoprecord?traceId={yourTraceId}

请求参数

名称类型是否必选描述
appidint你的项目使用的appid
residstring调用 获取录制资源 后返回的 resid
roomidstring待录制的房间号
recordidstring调用 启动录制 成功返回的 录制id

注意:

  • 请求数限制为每个 appid 每秒钟 10 次。
  • 当房间内没流或者没流数据超过预设时间(默认为 30 秒) 后,云端录制也会自动停止录制,如需特殊配置请联系与您对接的技术支持人员。
  • 录制停止后如需再次录制,必须再调用 applyrecord 方法请求一个新的 resid。

请求示例

  • 请求 URL:
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更新该次录制任务的混流布局。

构造请求

  • 请求方法:POST
  • 方法名:app/{appid}/v1/recordoss/updatemixrecord?traceId={yourTraceId}

请求参数

名称类型是否必选描述
residstring调用 获取录制资源 后返回的 resid
appidint你的项目使用的appid
roomidstring待录制的房间号
recordidstring调用 启动录制 成功返回的 录制id
mixconfigJSON混流配置

注意:

  • 请求数限制为每个 appid 每秒钟 10 次。
  • 在启动录制后,停止录制结束前,调用该API,否则会报错。
  • 该API只支持混流录制,对源流录制会返回报错(响应返回码:4019,录制任务类型非混流录制)。
  • 录制停止后如需再次录制,必须再调用 applyrecord 方法请求一个新的 resid。

请求示例

  • 请求 URL:
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查询该次录制任务的状态。

构造请求

  • 请求方法:GET
  • 方法名:app/{appid}/v1/recordoss/queryrecord/{roomid}/{recordid}?traceId={yourTraceId}

请求参数

名称类型是否必选描述
appidint你的项目使用的appid
roomidstring调用 启动录制 的房间号
recordidstring调用 启动录制 成功返回的 录制id

注意:

  • 请求数限制为每个 recordid 每秒钟 10 次。
  • 在启动录制后,停止录制结束前,调用该API。
  • 在录制任务停止后调用(含主动停止和超时停止场景),该API会返回报错(响应返回码:4013,录制 recordid 不存在)。

请求示例

  • 请求 URL:
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, 录制任务的信息,详情如下:

    名称类型描述
    appidint你的项目使用的 appid
    roomidstring调用 启动录制 的房间号
    recordidstring调用 启动录制 成功返回的 录制id
    statusint录制任务状态
    0: 初始化完成
    1: 任务启动
    createtimeint录制创建时间点,单位毫秒
    starttimeint录制启动时间点,单位毫秒

附录

响应返回码

返回码描述备注
0成功请求成功
1000没有token授权业务调用接口header头部没有带token
1001token不合法token格式有误、内容不对
1002appid不存在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 情况:

  • Content-type 错误,请确保 Content-type 为 application/json;charset=utf-8。
  • 使用了错误的 HTTP (GET/POST)方法。

2101:参数非法,请确保参数类型正确、大小写正确、必填的参数均已填写。
4005:请确保房间内已开播。
4011:录制已经在进行中 ,请勿用同一个 resid 重复 start 请求。如需发起多路录制,需要再次调用 applyrecord 方法获取新的 resid。
4012:resid 失效或过期。获得 resid 后必须在 5 分钟内开始云端录制。请重新调用 applyrecord 获取新的 resid。

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

有帮助 没帮助
提交成功,非常感谢您的反馈!

反馈

TOP