256 lines
5.0 KiB
Plaintext
256 lines
5.0 KiB
Plaintext
语音助手模块接口文档
|
||
================
|
||
|
||
基础信息
|
||
-------
|
||
- 基础路径: /api/v1/voice-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/voice-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/voice-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/voice-assistant/execute
|
||
|
||
请求参数：
|
||
{
|
||
"command": "打开电视",
|
||
"context": {
|
||
"room": "客厅",
|
||
"device": "tv"
|
||
}
|
||
}
|
||
|
||
响应示例：
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"action": "tv_on",
|
||
"status": "success",
|
||
"response": "好的，已为您打开电视"
|
||
}
|
||
}
|
||
|
||
4. 获取语音指令列表
|
||
GET /api/v1/voice-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/voice-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/voice-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/voice-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. 性能优化：
|
||
- 语音文件建议压缩后上传
|
||
- 长文本建议分段合成
|
||
- 使用WebSocket保持实时连接
|
||
|
||
5. 安全建议：
|
||
- 语音文件存储时加密
|
||
- 定期清理历史记录
|
||
- 设置访问频率限制 |