云录制 RESTful API

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

API概览

事项说明
请求host国内:api.aivacom.com,海外:api-oversea.aivacom.com
请求url/app/{appid}/v1/recordoss/{reqUri}?traceId={yourTraceId}
reqUri为:
- applyrecord
- startrecord
- updatemixrecord
- stoprecord
HeadContent-Type: application/json;charset=UTF-8
token: Basic authorization,生成方法请参考HTTP Basic身份认证

获取录制资源:applyrecord

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

  • 请求方法:GET
  • Head:
    • Content-typeapplication/json;charset=utf-8
    • token 为 Basic authorization,生成方法请参考 HTTP Basic身份认证
  • 请求host:
    • 国内:api.aivacom.com
    • 海外:api-oversea.aivacom.com
  • 请求url:app/{appid}/v1/recordoss/applyrecord?traceId={yourTraceId}
    • appid: 你的项目使用的appid
    • traceId: 用于跟踪每条API调用,可以用“服务器 IP + 产生 ID 时候的时间 + 自增序列 + 当前进程号”

注意:

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

applyrecord 请求示例

  • 请求 URL:
https://api.aivacom.com/app/10034/v1/recordoss/applyrecord?traceId=23116613407505472693518435

applyrecord 响应示例

{
    "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启动云录制。

  • Head:

    • Content-typeapplication/json;charset=utf-8
    • token 为 Basic authorization,生成方法请参考 HTTP Basic身份认证
  • 请求host:

    • 国内:api.aivacom.com
    • 海外:api-oversea.aivacom.com
  • 请求url:app/{appid}/v1/recordoss/startrecord?traceId={yourTraceId}

    • appid: 你的项目使用的appid
    • traceId: 用于跟踪每条API调用,可以用“服务器 IP + 产生 ID 时候的时间 + 自增序列 + 当前进程号”
  • 请求包体参数如下:

    名称类型是否必选示例值描述
    residstring 调用获取录制资源后返回的 resid
    appidint123456789你的项目使用的appid
    roomidstringroom1234待录制的房间号
    recordtypeint0录制类型
    0:音视频录制(默认)
    1:视频录制
    2:音频录制
    取值范围:0,1,2
    streamtypeint1混流录制:1
    取值范围:1
    mixconfigJSON 混流配置
    storagecfgJSON OSS存储配置
    callbackurlstring 指定回调地址

    storagecfg 参数说明

    名称类型是否必选示例值描述
    venderint0厂商类型,0:阿里云
    取值范围:0
    endpointstring OSS的endpoint
    bucketstring OSS的bucket
    accesskeystring OSS的accesskey
    secretkeystring OSS的secretkey
    fileprefixJSONArray 由多个字符串组成的数组,指定录制文件在第三方云存储中的存储位置
    举例:fileprefix = ["test1","test2"], 将在录制文件名前加上前缀 "test1/test2/",即 test1/test2/xxx.m3u8。前缀长度(包括斜杠)不得超过 128 个字符。字符串中不得出现斜杠。以下为支持的字符集范围:
    - 26 个小写英文字母 a-z
    - 26 个大写英文字母 A-Z
    - 10 个数字 0-9

注意:

  • 请求数限制为每个 appid 每秒钟 10 次。
  • 使用布局模板 templateid 无需填写输入流信息,但只针对同房间混流有效,如果需要使用跨房间混流请填input参数。
  • 使用混流的音频录制功能时,混流配置只需要填音频相关参数即可。如果不填input参数,则表示针对同房间的所有音频流进行混流音频录制,如果需要使用跨房间混流请填input参数。
  • 支持按照Appid级别配置录制 默认混流任务,如需使用请联系与您对接的技术支持人员。

startrecord 请求示例

  • 请求 URL:
https://api.aivacom.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,
                   "layer":0,
                   "pos_x":0,
                   "pos_y":0,
                   "pos_h":600,
                   "pos_w":400,
                   "crop":0
               },
               {
                   "uid":"10277777",
                   "roomid":"efdefd",
                   "streamtype":0,
                   "layer":1,
                   "pos_x":400,
                   "pos_y":0,
                   "pos_h":600,
                   "pos_w":400,
                   "crop":0
               }
       ],
       "output":{
           "streamtype":0,
           "videoheight":600,
           "videowidth":800,
           "videobitrate":600,
           "videofps":24,
           "videogop":72,
           "videoencode":100,
           "audiobitrate":128,
           "audiosample":44100,
           "audiochannel":2,
           "audioencode":1
       }
   },
   "storagecfg": {
       "vender": 0,
       "endpoint": "xxxx-test-endpoint",
       "bucket": "xxxx-test-bucket",
       "accesskey": "xxxx-test-accesskey",
       "secretkey": "xxxx-test-secretkey",
       "fileprefix": ["test1","test2"]
   }
}

startrecord 响应示例

  • 响应包体内容
{
    "code": 0,
    "message": "success",
    "recordid": "ba1107310000565164da34f816f842da94d",
    "traceId": "82719231231166134075054726935"
}
  • code: int,响应返回码
  • message: string, success代表成功,其它情况为一些错误的描述信息。
  • recordid: string,云录制任务ID,标识一次录制任务,后续如变更混流布局停止录制,需带上该ID。
  • traceId: string, 请求时带的traceId,便于追踪。

停止录制:stoprecord

启动录制后,调用该API停止录制。

  • 请求方法:POST

  • 请求地址:https://api.aivacom.com/app/{appId}/v1/recordoss/stoprecord?traceId={yourTraceId}

  • Head:

    • Content-typeapplication/json;charset=utf-8
    • token 为 Basic authorization,生成方法请参考 HTTP Basic身份认证
  • 请求host:

    • 国内:api.aivacom.com
    • 海外:api-oversea.aivacom.com
  • 请求url:app/{appid}/v1/recordoss/stoprecord?traceId={yourTraceId}

    • appid: 你的项目使用的appid
    • traceId: 用于跟踪每条API调用,可以用“服务器 IP + 产生 ID 时候的时间 + 自增序列 + 当前进程号”
  • 请求包体参数如下:

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

注意:

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

stoprecord 请求示例

  • 请求 URL:
https://api.aivacom.com/app/10034/v1/recordoss/stoprecord?traceId=214325255213407589332213
  • 请求包体内容
{
   "resid": "1d3fe093f9b9dbfa2d34e22cb34a12496ed6b057896358131208a0d981eb-ba11073100006be2",
   "appid": 10034,
   "roomid": "abcabc",
   "recordid": "ba1107310000565164da34f816f842da94d"
}

stoprecord 响应示例

{
    "code": 0,
    "message": "success",
    "recordid": "ba1107310000565164da34f816f842da94d",
    "traceId": "214325255213407589332213"
}
  • code: int,响应返回码
  • message: string, success代表成功,其它情况为一些错误的描述信息。
  • recordid: string,云录制任务ID,标识一次录制任务,调用startrecord返回的ID。
  • traceId: string, 请求时带的traceId,便于追踪。

更新混流布局:updatemixrecord

启动录制后,可调用该API更新该次录制任务的混流布局。 该API支持对混流的输入参数

  • 请求方法:POST

  • 请求地址:https://api.aivacom.com/app/{appId}/v1/recordoss/updatemixrecord?traceId={yourTraceId}

  • Head:

    • Content-typeapplication/json;charset=utf-8
    • token 为 Basic authorization,生成方法请参考 HTTP Basic身份认证
  • 请求host:

    • 国内:api.aivacom.com
    • 海外:api-oversea.aivacom.com
  • 请求url:app/{appid}/v1/recordoss/updatemixrecord?traceId={yourTraceId}

    • appid: 你的项目使用的appid
    • traceId: 用于跟踪每条API调用,可以用“服务器 IP + 产生 ID 时候的时间 + 自增序列 + 当前进程号”
  • 请求包体参数如下:

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

注意:

  • 请求数限制为每个 appid 每秒钟 10 次。
  • 在启动录制后,停止录制结束前,调用该API,否则会报错。
  • 录制停止后如需再次录制,必须再调用 applyrecord 方法请求一个新的 resid。

updatemixrecord 请求示例

  • 请求 URL:
https://api.aivacom.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,
                   "layer":0,
                   "pos_x":0,
                   "pos_y":0,
                   "pos_h":600,
                   "pos_w":400,
                   "crop":0
               },
               {
                   "uid":"10277777",
                   "roomid":"efdefd",
                   "streamtype":0,
                   "layer":1,
                   "pos_x":400,
                   "pos_y":0,
                   "pos_h":600,
                   "pos_w":400,
                   "crop":0
               }
       ],
       "output":{
           "streamtype":0,
           "videoheight":720,
           "videowidth":1280,
           "videobitrate":1000,
           "videofps":24,
           "videogop":72,
           "videoencode":100,
           "audiobitrate":128,
           "audiosample":44100,
           "audiochannel":2,
           "audioencode":1
       }
   }
}

updatemixrecord 响应示例

{
    "code": 0,
    "message": "success",
    "recordid": "ba1107310000565164da34f816f842da94d",
    "traceId": "82719231231166134075054726935"
}
  • code: int,响应返回码
  • message: string, success代表成功,其它情况为一些错误的描述信息。
  • recordid: string,云录制任务ID,标识录制任务,调用startrecord返回的ID。
  • traceId: string, 请求时带的traceId,便于追踪。

响应返回码

返回码描述备注
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录制错误录制任务类型非混流录制

常见错误

下面仅列出使用云录制 RESTful API 过程中常见的错误码或错误信息,如果遇到其他错误,请联系与您对接的技术支持人员。
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。

<