接口列表
本节包含设备自定义语音与自定义提示音相关接口等。
接口列表如下：
| 序号 | 接口功能 | 描述 |
|---|---|---|
| 1 | 语音文件上传接口 | 上传本地语音文件 |
| 2 | 语音文件查询接口 | 查询上传的语音文件 |
| 3 | 删除已保存的语音文件接口 | 删除语音文件 |
| 4 | 语音文件下发接口 | 语音文件下发，指定设备播放 |
| 5 | 临时语音下发接口 | 一次性自定义语音下发到设备，不保存到语音列表 |
| 6 | 获取设备语音列表接口 | 获取指定设备的语音列表，GET参数放在请求链接里 |
| 7 | 新增设备语音接口 | 将语音文件下发给设备，POST参数放在请求链接里 |
| 8 | 修改设备语音名称接口 | 修改设备上的指定语音文件的语音名称，PUT参数放在请求链接里 |
| 9 | 删除设备语音接口 | 删除设备上的语音文件，DELETE参数放在请求链接里 |
| 10 | 设备告警提示音设置接口 | 设备告警提示音设置接口，PUT参数放在请求链接里 |
语音文件上传接口
接口功能
上传本地语音文件
请求地址
请求方式
POST
请求参数
| 参数名 | 类型 | ParameterType | 描述 | 是否必填 |
|---|---|---|---|---|
| accessToken | String | body | 访问令牌 | Y |
| voiceFile | MultipartFile | form-data | 语音文件，支持wav、mp3、aac格式，最大20M | Y |
| voiceName | String | body | 语音名称，最长50个字符 | N |
| force | boolean | body | 如果已存在相同voiceName的语音文件，则替换原语音文件，true表示强制替换，false表示如果存在不替换，默认为false | N |
- 返回结果
| 参数名 | 类型 | 描述 |
|---|---|---|
| msg | String | 操作信息 |
| code | String | 操作码，200表示操作成功 |
| data | Object | 语音文件信息 |
| name | String | 语音名称 |
| url | String | 语音文件下载地址，有效期1天 |
- 请求报文
POST /api/lapp/voice/upload HTTP/1.1
Host: <host>:<port>
Content-Type: multipart/form-data
- 返回数据
{
"msg": "Operation succeeded",
"code": "200",
"data": [
{
"name": "babble.wav",
"url": "http://oss-cn-shenzhen.aliyuncs.com/voice/bbe5cc634be34a7484947d63f6361c22.aac?Expires=1583059824&OSSAccessKeyId=testId&&Signature=kM91%2By"
}
]
}
语音文件查询接口
接口功能
查询上传的语音文件
请求地址
请求方式
POST
请求参数
| 参数名 | 类型 | Parameter Type | 描述 | 是否必填 |
|---|---|---|---|---|
| accessToken | String | body | 访问令牌 | Y |
| voiceName | String | body | 模糊匹配语音名称 | N |
| pageStart | int | body | 分页起始页，从0开始 | N |
| pageSize | int | body | 分页大小，默认为10，最大为50 | N |
- 返回结果
| 参数名 | 类型 | 描述 |
|---|---|---|
| msg | String | 操作信息 |
| code | String | 操作码，200表示操作成功 |
| data | Object | 语音文件信息 |
| voiceName | String | 语音名称 |
| fileUrl | String | 语音文件下载地址，有效期1天 |
| duration | int | 语音文件时长，单位秒 |
- 请求报文
POST /api/lapp/voice/query HTTP/1.1
Host: <host>:<port>
Content-Type:application/x-www-form-urlencoded
- 返回数据
{
"msg": "Operation succeeded",
"code": "200",
"data": [
{
"voiceName": "babble.wav",
"fileUrl": "http://oss-cn-shenzhen.aliyuncs.com/voice/bbe5cc634be34a7484947d63f6361c22.aac?Expires=1583059824&OSSAccessKeyId=testId&&Signature=kM91%2By",
"duration": 60
}
],
"page": {
"total": 1,
"size": 10,
"page": 0
}
}
删除已保存的语音文件接口
接口功能
删除语音文件
请求地址
请求方式
POST
请求参数
| 参数名 | 类型 | Parameter Type | 描述 | 是否必填 |
|---|---|---|---|---|
| accessToken | String | body | 访问令牌 | Y |
| voiceName | String | body | 语音名称 | Y |
- 请求报文
POST /api/lapp/voice/delete HTTP/1.1
Host: <host>:<port>
Content-Type: application/x-www-form-urlencoded
- 返回数据
{
"msg": "操作成功!",
"code": "200",
}
语音文件下发接口
接口功能
语音文件下发，指定设备播放
请求地址
请求方式
POST
请求参数
| 参数名 | 类型 | Parameter Type | 描述 | 是否必填 |
|---|---|---|---|---|
| accessToken | String | body | 访问令牌 | Y |
| deviceSerial | String | body | 设备序列号 | Y |
| channelNo | int | body | 通道号，默认通道号为1 | N |
| fileUrl | String | body | 下载音频文件的url（上传接口返回的url） | Y |
- 请求报文
POST /api/lapp/voice/send HTTP/1.1
Host: <host>:<port>
Content-Type: application/x-www-form-urlencoded
- 返回数据
{
"msg": "操作成功!",
"code": "200",
}
- 错误码
| 返回值 | 返回信息 |
|---|---|
| 10001 | 创建ticket失败 |
| 10002 | 连接tts失败 |
| 10003 | 下载文件失败 |
| 10004 | kafka消息格式错误 |
| 10005 | tts断开连接 |
| 10006 | tts url异常 |
| 10007 | 超过并发限制 |
| 10008 | 连接已经存在，重复请求 |
| 10009 | 发送kafka失败 |
| 10010 | 不支持的音频格式 |
临时语音下发接口
接口功能
一次性自定义语音下发到设备，不保存到语音列表
请求地址
请求方式
POST
请求参数
| 参数名 | 类型 | Parameter Type | 描述 | 是否必填 |
|---|---|---|---|---|
| accessToken | String | body | 访问令牌 | Y |
| voiceFile | MultipartFile | form-data | 语音文件 | Y |
| deviceSerial | String | body | 设备序列号 | Y |
| channelNo | int | body | 通道号，默认通道号为1 | N |
- 请求报文
POST /api/lapp/voice/sendonce HTTP/1.1
Host: <host>:<port>
Content-Type: multipart/form-data
- 返回数据
{
"msg": "操作成功!",
"code": "200"
}
获取设备语音列表接口
接口功能
获取指定设备的语音列表，GET参数放在请求链接里
请求地址
请求方式
GET
请求参数
| 参数名 | 类型 | Parameter Type | 描述 | 是否必填 |
|---|---|---|---|---|
| accessToken | String | query | 访问令牌 | Y |
| deviceSerial | String | query | 设备序列号 | Y |
- 返回结果
| 参数名 | 类型 | 描述 |
|---|---|---|
| code | Int | 操作码，200表示操作成功 |
| message | String | 提示信息 |
| moreInfo | object | 详细信息 |
| voiceinfos | object | 设备语音文件信息 |
| voiceId | Int | 语音文件id |
| voiceName | String | 语音名称 |
| voiceUrl | String | 语音文件url |
| status | Int | 平台和设备语音同步状态,0:同步完成,1:正在同步,2:同步失败 |
| time | Int | 语音创建时间 |
- 请求报文
GET /api/route/voice/v3/devices/voices HTTP/1.1
Host: <host>:<port>
Content-Type: multipart/form-data
- 返回数据
{
"meta": {
"code": 200,
"message": "操作成功",
"moreInfo": null
},
"voiceInfos": [
{
"voiceId": 1,
"voiceName": "测试语音",
"voiceUrl": "http://custom-voice-reminder-hn.oss-cn-shenzhen.aliyuncs.com/voice/e8e131c4e4684f4f8460f4676b5b777d.aac?Expires=1584433153&OSSAccessKeyId=LTAI4Fvm85GR68d4cEW63uMy&Signature=uhIlWro4OUKWmZ4pj5wlYIML0Fw=",
"status": 1,
"time": 1584375603
}
]
}
新增设备语音接口
接口功能
将语音文件下发给设备，POST参数放在请求链接里
请求地址
请求方式
POST
请求参数
| 参数名 | 类型 | Parameter Type | 描述 | 是否必填 |
|---|---|---|---|---|
| accessToken | String | query | 访问令牌 | Y |
| deviceSerial | String | query | 设备序列号 | Y |
| voiceName | String | query | 设备语音名称 | Y |
| voiceUrl | String | query | 语音文件url | Y |
- 返回结果
| 参数名 | 类型 | 描述 |
|---|---|---|
| code | Int | 操作码，200表示操作成功 |
| message | String | 提示信息 |
| moreInfo | object | 详细信息 |
| voiceinfos | object | 设备语音文件信息 |
| voiceId | Int | 语音文件id |
- 请求报文
POST /api/route/voice/v3/devices/voices HTTP/1.1
Host: <host>:<port>
Content-Type: multipart/form-data
- 返回数据
{
"meta": {
"code": 200,
"message": "操作成功",
"moreInfo": null
},
"voiceInfo": {
"voiceId": 1
}
}
修改设备语音名称接口
接口功能
修改设备上的指定语音文件的语音名称，PUT参数放在请求链接里
请求地址
请求方式
PUT
请求参数
| 参数名 | 类型 | Parameter Type | 描述 | 是否必填 |
|---|---|---|---|---|
| accessToken | String | query | 访问令牌 | Y |
| deviceSerial | String | query | 设备序列号 | Y |
| voiceId | Int | query | 设备语音唯一id | Y |
| voiceName | String | query | 设备语音名称 | Y |
| voiceUrl | String | query | 语音文件url Y |
- 返回结果
| 参数名 | 类型 | 描述 |
|---|---|---|
| code | Int | 操作码，200表示操作成功 |
| message | String | 提示信息 |
| moreInfo | object | 详细信息 |
- 请求报文
PUT /api/route/voice/v3/devices/voices HTTP/1.1
Host: <host>:<port>
Content-Type: multipart/form-data
- 返回数据
{
"meta": {
"code": 200,
"message": "操作成功",
"moreInfo": null
}
}
删除设备语音接口
接口功能
删除设备上的语音文件，DELETE参数放在请求链接里
请求地址
请求方式
DELETE
请求参数
| 参数名 | 类型 | Parameter Type | 描述 | 是否必填 |
|---|---|---|---|---|
| accessToken | String | query | 访问令牌 | Y |
| deviceSerial | String | query | 设备序列号 | Y |
| voiceId | Int | query | 设备语音唯一id | Y |
| voiceName | String | query | 设备语音名称 | Y |
| voiceUrl | String | query | 语音文件url | Y |
- 返回结果
| 参数名 | 类型 | 描述 |
|---|---|---|
| code | Int | 操作码，200表示操作成功 |
| message | String | 提示信息 |
| moreInfo | object | 详细信息 |
- 请求报文
DELETE /api/route/voice/v3/devices/voices HTTP/1.1
Host: <host>:<port>
Content-Type: multipart/form-data
- 返回数据
{
"meta": {
"code": 200,
"message": "操作成功",
"moreInfo": null
}
}
设备告警提示音设置接口
接口功能
设备告警提示音设置接口，PUT参数放在请求链接里
请求地址
https://open.ys7.com/api/route/alarm/v3/devices/{deviceSerial}/alarm/sound
请求方式
PUT
请求参数
| 参数名 | 类型 | Parameter Type | 描述 | 是否必填 |
|---|---|---|---|---|
| accessToken | String | query | 访问令牌 | Y |
| deviceSerial | String | query | 设备序列号 | Y |
| voiceId | Int query | 设备语音唯一id，soundType=3是有效 | N | |
| enable | Int | query | 0-关闭，1-开启 | Y |
| soundType | Int | query | 0-短叫，1-长叫，2-静音，3-自定义语音 | Y |
- 返回结果
| 参数名 | 类型 | 描述 |
|---|---|---|
| code | Int | 操作码，200表示操作成功 |
| message | String | 提示信息 |
| moreInfo | object | 详细信息 |
- 请求报文
PUT /api/route/alarm/v3/devices/{deviceSerial}/alarm/sound HTTP/1.1
Host: <host>:<port>
Content-Type: multipart/form-data
- 返回数据
{
"meta": {
"code": 200,
"message": "操作成功",
"moreInfo": null
}
}
- 错误码
| 返回值 | 返回信息 |
|---|---|
| 111001 | 语音文件格式错误 |
| 111002 | 语音文件时长不合法 |
| 111003 | 语音文件上传失败 |
| 111004 | 语音文件转换失败 |
| 111005 | 语音文件时长获取 |
| 111006 | 语音文件列表获取失败 |
| 111007 | 下发的语音文件URL不存在 |
| 111008 | 参数错误，语音文件不能为空 |
| 111009 | 参数错误，语音文件URL不能为空 |
| 111010 | 参数错误，设备序列号不能为空 |
| 111011 | 参数错误，通道号不能为空 |