364 lines
8.8 KiB
Markdown
364 lines
8.8 KiB
Markdown
# 腾讯云语音识别API对接文档
|
||
|
||
## 功能概述
|
||
|
||
本项目已成功集成腾讯云语音识别（ASR）服务，提供了以下功能：
|
||
|
||
1. **录音文件识别**：适用于较长的音频文件，采用异步方式识别
|
||
2. **一句话识别**：适用于60秒以内的短音频，采用同步方式识别
|
||
3. **任务状态查询**：查询异步识别任务的状态和结果
|
||
|
||
## API文档参考
|
||
|
||
- 官方文档：https://cloud.tencent.com/document/product/1093/35637
|
||
- API概览：https://cloud.tencent.com/document/api/1093/35640
|
||
|
||
## 配置说明
|
||
|
||
### 1. 配置文件 (application.yml)
|
||
|
||
```yaml
|
||
# 腾讯云语音识别配置
|
||
tencent-asr:
|
||
# API密钥ID
|
||
secret-id: AKIDf9OM3TdWBZqqZ1C7k6B0Ypqb6KIzQaT5
|
||
# API密钥Key（需要在实际使用时提供）
|
||
secret-key: ${TENCENT_SECRET_KEY:}
|
||
# API地区
|
||
region: ap-shanghai
|
||
# 连接超时时间（毫秒）
|
||
connect-timeout: 30000
|
||
# 读取超时时间（毫秒）
|
||
read-timeout: 60000
|
||
# 默认引擎模型类型（16k_zh：中文普通话、16k_en：英文）
|
||
default-engine-model: 16k_zh
|
||
# 默认结果文本格式（0：识别结果文本，包含标点符号；1：不带标点的识别结果）
|
||
default-res-text-format: 0
|
||
# 默认音频声道数（1：单声道；2：双声道）
|
||
default-channel-num: 1
|
||
# 是否启用
|
||
enabled: true
|
||
```
|
||
|
||
### 2. 环境变量配置
|
||
|
||
为了安全起见，建议通过环境变量设置 SecretKey：
|
||
|
||
```bash
|
||
export TENCENT_SECRET_KEY=your_secret_key_here
|
||
```
|
||
|
||
或在启动命令中指定：
|
||
|
||
```bash
|
||
java -jar models-integration-0.0.1.jar --tencent-asr.secret-key=your_secret_key_here
|
||
```
|
||
|
||
## API接口说明
|
||
|
||
### 基础URL
|
||
|
||
```
|
||
http://localhost:5081/api/tencent/asr
|
||
```
|
||
|
||
### 1. 创建录音文件识别任务
|
||
|
||
**接口地址**：`POST /api/tencent/asr/create-task`
|
||
|
||
**适用场景**：适用于较长的音频文件（支持多种格式：wav、pcm、mp3、silk、speex、amr、m4a等）
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"url": "https://example.com/audio.wav",
|
||
"engineModelType": "16k_zh",
|
||
"channelNum": 1,
|
||
"resTextFormat": 0,
|
||
"sourceType": 0,
|
||
"callbackUrl": "https://your-callback-url.com/callback",
|
||
"filterDirty": false,
|
||
"filterModal": false,
|
||
"convertNumMode": true
|
||
}
|
||
```
|
||
|
||
**请求参数说明**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| url | String | 是 | 音频文件URL地址 |
|
||
| engineModelType | String | 否 | 引擎模型类型，默认：16k_zh |
|
||
| channelNum | Integer | 否 | 音频声道数，1：单声道；2：双声道，默认：1 |
|
||
| resTextFormat | Integer | 否 | 识别结果文本格式，0：带标点；1：不带标点，默认：0 |
|
||
| sourceType | Integer | 否 | 音频来源，0：音频URL；1：音频数据（base64），默认：0 |
|
||
| callbackUrl | String | 否 | 回调URL，任务完成后将结果POST到该地址 |
|
||
| hotwordId | String | 否 | 热词表ID，用于提高专有名词识别准确率 |
|
||
| filterDirty | Boolean | 否 | 是否过滤脏词，默认：false |
|
||
| filterModal | Boolean | 否 | 是否过滤语气词，默认：false |
|
||
| convertNumMode | Boolean | 否 | 是否进行阿拉伯数字智能转换，默认：false |
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"taskId": "1234567890",
|
||
"status": 0,
|
||
"statusStr": "等待处理",
|
||
"requestId": "req_abc123def456",
|
||
"errorCode": 0,
|
||
"errorMsg": "成功"
|
||
}
|
||
}
|
||
```
|
||
|
||
**引擎模型类型说明**：
|
||
|
||
- `16k_zh`：16k 中文普通话通用
|
||
- `16k_zh_video`：16k 音视频领域
|
||
- `16k_en`：16k 英语
|
||
- `16k_ca`：16k 粤语
|
||
- `8k_zh`：8k 中文普通话通用
|
||
|
||
### 2. 查询识别任务状态
|
||
|
||
**接口地址**：`GET /api/tencent/asr/query-status/{taskId}`
|
||
|
||
**适用场景**：查询异步识别任务的状态和结果
|
||
|
||
**请求示例**：
|
||
|
||
```
|
||
GET /api/tencent/asr/query-status/1234567890
|
||
```
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"taskId": "1234567890",
|
||
"status": 2,
|
||
"statusStr": "识别成功",
|
||
"result": "你好，这是一段语音识别测试内容。",
|
||
"audioDuration": 5.5,
|
||
"errorCode": 0,
|
||
"errorMsg": "",
|
||
"resultDetail": "{\"Result\":[{\"Text\":\"你好，这是一段语音识别测试内容。\"}]}"
|
||
}
|
||
}
|
||
```
|
||
|
||
**任务状态说明**：
|
||
|
||
- `0`：等待处理
|
||
- `1`：执行中
|
||
- `2`：识别成功
|
||
- `3`：识别失败
|
||
|
||
### 3. 一句话识别
|
||
|
||
**接口地址**：`POST /api/tencent/asr/sentence-recognition`
|
||
|
||
**适用场景**：适用于60秒以内的短音频，同步返回识别结果
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"url": "https://example.com/short-audio.wav",
|
||
"engineModelType": "16k_zh",
|
||
"sourceType": 0,
|
||
"filterDirty": false,
|
||
"filterModal": false,
|
||
"convertNumMode": true
|
||
}
|
||
```
|
||
|
||
**请求参数说明**：参数与创建任务接口相同，但不需要 callbackUrl
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"status": 2,
|
||
"statusStr": "识别成功",
|
||
"result": "你好世界",
|
||
"audioDuration": 1.5,
|
||
"requestId": "req_xyz789",
|
||
"errorCode": 0,
|
||
"errorMsg": "成功"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 健康检查
|
||
|
||
**接口地址**：`GET /api/tencent/asr/health`
|
||
|
||
**适用场景**：检查服务是否正常运行
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": "腾讯云语音识别服务运行正常"
|
||
}
|
||
```
|
||
|
||
## 使用流程
|
||
|
||
### 场景1：长音频识别（异步）
|
||
|
||
1. 调用 **创建录音文件识别任务** 接口，获取 taskId
|
||
2. 使用 taskId 调用 **查询识别任务状态** 接口
|
||
3. 当 status 为 2 时，表示识别成功，可从 result 字段获取识别结果
|
||
|
||
### 场景2：短音频识别（同步）
|
||
|
||
1. 直接调用 **一句话识别** 接口
|
||
2. 同步返回识别结果
|
||
|
||
## 测试示例
|
||
|
||
### 使用 curl 测试
|
||
|
||
#### 1. 创建识别任务
|
||
|
||
```bash
|
||
curl -X POST http://localhost:5081/api/tencent/asr/create-task \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"url": "https://example.com/audio.wav",
|
||
"engineModelType": "16k_zh",
|
||
"channelNum": 1,
|
||
"resTextFormat": 0,
|
||
"convertNumMode": true
|
||
}'
|
||
```
|
||
|
||
#### 2. 查询任务状态
|
||
|
||
```bash
|
||
curl http://localhost:5081/api/tencent/asr/query-status/1234567890
|
||
```
|
||
|
||
#### 3. 一句话识别
|
||
|
||
```bash
|
||
curl -X POST http://localhost:5081/api/tencent/asr/sentence-recognition \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"url": "https://example.com/short-audio.wav",
|
||
"engineModelType": "16k_zh",
|
||
"convertNumMode": true
|
||
}'
|
||
```
|
||
|
||
### 使用 Swagger UI 测试
|
||
|
||
启动应用后，访问：http://localhost:5081/swagger-ui.html
|
||
|
||
在 Swagger UI 中找到 "腾讯云语音识别接口" 分组，即可进行可视化测试。
|
||
|
||
## 音频格式要求
|
||
|
||
### 支持的音频格式
|
||
|
||
- wav
|
||
- pcm
|
||
- mp3
|
||
- silk
|
||
- speex
|
||
- amr
|
||
- m4a
|
||
|
||
### 音频参数建议
|
||
|
||
- **采样率**：16k 或 8k（根据选择的引擎模型）
|
||
- **位深度**：16bit
|
||
- **声道数**：1（单声道）或 2（双声道）
|
||
- **编码**：PCM
|
||
|
||
## 注意事项
|
||
|
||
1. **API密钥安全**：
|
||
- 不要将 SecretKey 直接写入配置文件
|
||
- 建议使用环境变量或密钥管理服务
|
||
|
||
2. **音频时长限制**：
|
||
- 一句话识别：≤ 60秒
|
||
- 录音文件识别：≤ 5小时
|
||
|
||
3. **音频大小限制**：
|
||
- 单个音频文件 ≤ 500MB
|
||
|
||
4. **回调地址**：
|
||
- 如果设置了 callbackUrl，任务完成后会自动回调
|
||
- 回调地址必须是公网可访问的 HTTP/HTTPS 地址
|
||
|
||
5. **费用说明**：
|
||
- 腾讯云语音识别服务按使用量计费
|
||
- 请在腾讯云控制台查看具体计费标准
|
||
|
||
## 错误处理
|
||
|
||
常见错误码：
|
||
|
||
| 错误码 | 说明 | 解决方案 |
|
||
|--------|------|----------|
|
||
| InvalidParameter | 参数错误 | 检查请求参数是否正确 |
|
||
| AuthFailure.SignatureFailure | 签名错误 | 检查 SecretId 和 SecretKey 是否正确 |
|
||
| ResourceUnavailable.NotFound | 资源不存在 | 检查 taskId 是否正确 |
|
||
| LimitExceeded | 超过配额限制 | 联系腾讯云增加配额 |
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
src/main/java/com/integration/api/
|
||
├── config/
|
||
│ └── TencentAsrConfig.java # 腾讯云ASR配置类
|
||
├── controller/
|
||
│ └── TencentAsrController.java # ASR控制器
|
||
├── dto/
|
||
│ ├── TencentAsrRequest.java # ASR请求DTO
|
||
│ ├── TencentAsrResponse.java # ASR响应DTO
|
||
│ └── TencentAsrTaskStatus.java # ASR任务状态DTO
|
||
└── service/
|
||
├── TencentAsrService.java # ASR服务接口
|
||
└── impl/
|
||
└── TencentAsrServiceImpl.java # ASR服务实现类
|
||
```
|
||
|
||
## 依赖说明
|
||
|
||
项目使用了腾讯云官方 Java SDK：
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>com.tencentcloudapi</groupId>
|
||
<artifactId>tencentcloud-sdk-java</artifactId>
|
||
<version>3.1.909</version>
|
||
</dependency>
|
||
```
|
||
|
||
## 联系方式
|
||
|
||
如有问题，请联系项目维护者或查看腾讯云官方文档。
|
||
|
||
## 更新日志
|
||
|
||
- **2025-11-05**：初始版本，实现录音文件识别、一句话识别和任务查询功能
|
||
|