256 lines
4.9 KiB
Plaintext
256 lines
4.9 KiB
Plaintext
|
智能语音助手模块接口文档
|
|||
|
|
===================
|
|||
|
|
|
|||
|
|
基础信息
|
|||
|
|
-------
|
|||
|
|
- 基础路径: /api/v1/assistant
|
|||
|
|
- 请求方式: REST
|
|||
|
|
- 数据格式: JSON
|
|||
|
|
- 认证方式: Bearer Token
|
|||
|
|
|
|||
|
|
数据结构
|
|||
|
|
-------
|
|||
|
|
|
|||
|
|
VoiceCommand 语音指令对象:
|
|||
|
|
{
|
|||
|
|
id: number, // 指令ID
|
|||
|
|
phrase: string, // 语音短语
|
|||
|
|
action: string, // 执行动作
|
|||
|
|
type: string, // 指令类型
|
|||
|
|
enabled: boolean, // 是否启用
|
|||
|
|
createTime: string // 创建时间
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
VoiceReminder 语音提醒对象:
|
|||
|
|
{
|
|||
|
|
id: number, // 提醒ID
|
|||
|
|
title: string, // 提醒标题
|
|||
|
|
content: string, // 提醒内容
|
|||
|
|
time: string, // 提醒时间
|
|||
|
|
repeat: string[], // 重复周期
|
|||
|
|
voiceEnabled: boolean, // 是否启用语音
|
|||
|
|
status: string // 提醒状态
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
VoiceMessage 对话消息对象:
|
|||
|
|
{
|
|||
|
|
id: number, // 消息ID
|
|||
|
|
role: string, // 消息角色(user/assistant)
|
|||
|
|
content: string, // 消息内容
|
|||
|
|
type: string, // 消息类型(text/voice)
|
|||
|
|
time: string, // 消息时间
|
|||
|
|
audioUrl?: string // 语音URL（可选）
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
API 接口
|
|||
|
|
-------
|
|||
|
|
|
|||
|
|
1. 语音识别
|
|||
|
|
POST /api/v1/assistant/recognize
|
|||
|
|
Content-Type: multipart/form-data
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|||
|
|
| audio | File | 是 | 语音文件(WAV/MP3) |
|
|||
|
|
| lang | string | 否 | 语言代码(zh-CN/en-US) |
|
|||
|
|
|
|||
|
|
响应示例：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": {
|
|||
|
|
"text": "打开电视",
|
|||
|
|
"confidence": 0.95
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
2. 语音合成
|
|||
|
|
POST /api/v1/assistant/synthesize
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
{
|
|||
|
|
"text": "好的，已为您打开电视",
|
|||
|
|
"voice": "female",
|
|||
|
|
"rate": 1.0,
|
|||
|
|
"pitch": 1.0
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
响应示例：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": {
|
|||
|
|
"audioUrl": "https://example.com/audio/123.mp3",
|
|||
|
|
"duration": 3.5
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
3. 执行语音指令
|
|||
|
|
POST /api/v1/assistant/execute
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
{
|
|||
|
|
"command": "打开电视",
|
|||
|
|
"context": {
|
|||
|
|
"room": "客厅",
|
|||
|
|
"device": "tv"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
响应示例：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": {
|
|||
|
|
"action": "tv_on",
|
|||
|
|
"status": "success",
|
|||
|
|
"response": "好的，已为您打开电视"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
4. 获取语音指令列表
|
|||
|
|
GET /api/v1/assistant/commands
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|||
|
|
| type | string | 否 | 指令类型 |
|
|||
|
|
| enabled| boolean| 否 | 是否启用 |
|
|||
|
|
|
|||
|
|
响应示例：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": [
|
|||
|
|
{
|
|||
|
|
"id": 1,
|
|||
|
|
"phrase": "打开电视",
|
|||
|
|
"action": "tv_on",
|
|||
|
|
"type": "device",
|
|||
|
|
"enabled": true,
|
|||
|
|
"createTime": "2024-03-20 10:00:00"
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
5. 添加语音提醒
|
|||
|
|
POST /api/v1/assistant/reminders
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
{
|
|||
|
|
"title": "吃药提醒",
|
|||
|
|
"content": "该吃降压药了",
|
|||
|
|
"time": "08:00",
|
|||
|
|
"repeat": ["mon", "wed", "fri"],
|
|||
|
|
"voiceEnabled": true
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
响应示例：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": {
|
|||
|
|
"id": 1,
|
|||
|
|
"title": "吃药提醒",
|
|||
|
|
"content": "该吃降压药了",
|
|||
|
|
"time": "08:00",
|
|||
|
|
"repeat": ["mon", "wed", "fri"],
|
|||
|
|
"voiceEnabled": true,
|
|||
|
|
"status": "pending"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
6. 获取对话历史
|
|||
|
|
GET /api/v1/assistant/messages
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|||
|
|
| page | number | 否 | 页码，默认1 |
|
|||
|
|
| size | number | 否 | 每页数量，默认20 |
|
|||
|
|
|
|||
|
|
响应示例：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": {
|
|||
|
|
"total": 100,
|
|||
|
|
"records": [
|
|||
|
|
{
|
|||
|
|
"id": 1,
|
|||
|
|
"role": "user",
|
|||
|
|
"content": "今天天气怎么样",
|
|||
|
|
"type": "voice",
|
|||
|
|
"time": "2024-03-20 10:00:00",
|
|||
|
|
"audioUrl": "https://example.com/audio/q123.mp3"
|
|||
|
|
},
|
|||
|
|
{
|
|||
|
|
"id": 2,
|
|||
|
|
"role": "assistant",
|
|||
|
|
"content": "今天天气晴朗，气温20度，适合外出活动",
|
|||
|
|
"type": "text",
|
|||
|
|
"time": "2024-03-20 10:00:01"
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
7. 更新语音设置
|
|||
|
|
PUT /api/v1/assistant/settings
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
{
|
|||
|
|
"volume": 80,
|
|||
|
|
"rate": 1.0,
|
|||
|
|
"voice": "female",
|
|||
|
|
"wakeWord": "小助手",
|
|||
|
|
"autoReply": true
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
响应示例：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": {
|
|||
|
|
"volume": 80,
|
|||
|
|
"rate": 1.0,
|
|||
|
|
"voice": "female",
|
|||
|
|
"wakeWord": "小助手",
|
|||
|
|
"autoReply": true,
|
|||
|
|
"updateTime": "2024-03-20 10:00:00"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
错误码说明
|
|||
|
|
--------
|
|||
|
|
| 错误码 | 说明 |
|
|||
|
|
| 200 | 成功 |
|
|||
|
|
| 400 | 请求参数错误 |
|
|||
|
|
| 401 | 未授权 |
|
|||
|
|
| 403 | 禁止访问 |
|
|||
|
|
| 404 | 资源不存在 |
|
|||
|
|
| 500 | 服务器内部错误 |
|
|||
|
|
|
|||
|
|
注意事项
|
|||
|
|
-------
|
|||
|
|
1. 语音文件格式要求：
|
|||
|
|
- 支持格式：WAV、MP3
|
|||
|
|
- 采样率：16kHz
|
|||
|
|
- 时长限制：60秒
|
|||
|
|
|
|||
|
|
2. 语音识别支持的语言：
|
|||
|
|
- 中文（zh-CN）
|
|||
|
|
- 英文（en-US）
|
|||
|
|
|
|||
|
|
3. 语音合成注意事项：
|
|||
|
|
- 速率范围：0.5-2.0
|
|||
|
|
- 音量范围：0-100
|
|||
|
|
- 支持的声音：男声、女声
|
|||
|
|
|
|||
|
|
4. 性能优化<E4BC98><E58C96>
|
|||
|
|
- 语音文件建议压缩后上传
|
|||
|
|
- 长文本建议分段合成
|
|||
|
|
- 使用WebSocket保持实时连接
|
|||
|
|
|
|||
|
|
5. 安全建议：
|
|||
|
|
- 语音文件存储时加密
|
|||
|
|
- 定期清理历史记录
|
|||
|
|
- 设置访问频率限制
|