酷虎云音频转文字（STT）接口开发文档
1. 接口概述
本接口为酷虎云提供的音频转文字（Speech-to-Text, STT）服务接口，支持通过提交音频URL的方式批量发起转写任务，并可查询任务状态及获取转写结果（含可导出为SRT格式的字幕信息），适用于需要将音频内容转化为文本或字幕的开发场景。
2. 接口基础信息
项目 内容
-------------------------------------------------------------------------------------------
接口地址 `https://#/api/stt/audiototexturls`
请求方式 HTTP POST
返回格式 application/json
Content-Type application/json（请求头必须包含此参数，否则会导致请求失败）
在线调试工具 apifox
3. 请求参数说明
接口请求参数分为URL参数和请求体参数，需根据`type`（任务类型）传入对应参数。
3.1 通用URL参数（必传）
所有请求均需在URL中携带以下参数：
参数名 是否必填 类型 示例值 说明
---------------------------------------------------------------------------------------------------------------------------------
key 是 string 35kj5jnlj53453kl5j43nj5 接口密钥，用于身份验证，可在酷虎云控制台「密钥管理」页面获取。
type 是 string start / query 任务类型：<br>- `start`：提交音频转写任务，返回任务ID；<br>- `query`：查询指定任务的状态及转写结果。
3.2 按任务类型的请求体参数
3.2.1 提交任务（type=start）
当`type=start`时，需在请求体中传入音频URL列表，用于批量发起转写任务。
参数名 是否必填 类型 示例值 说明
--------------------------------------------------------------------------------------------------------------------------------------------------------------------
audio_urls 是 array ["https://#/audio1.mp3", "https://#/audio2.mp3"] 音频URL数组，支持批量提交多个音频地址，仅支持`http/https`协议的URL，音频格式需为MP3（其他格式可能导致识别失败）。
请求体示例：
```json
{
"audio_urls": [
"https://#/audio_sample1.mp3",
"https://#/audio_sample2.mp3"
]
}
```
3.2.2 查询任务（type=query）
当`type=query`时，需在请求体中传入任务ID，用于查询该任务的详细信息（含转写结果）。
参数名 是否必填 类型 示例值 说明
-----------------------------------------------------------------------------------------------------------------------------------
task_id 是 string b68b6285901bb8621f680fbabe796d6e 任务ID，由`type=start`请求返回，用于唯一标识一个转写任务。
请求体示例：
```json
{
"task_id": "b68b6285901bb8621f680fbabe796d6e"
}
```
4. 返回参数说明
所有请求的返回格式均为JSON，包含状态码、状态信息及对应业务数据，不同任务类型的返回数据结构略有差异。
4.1 通用返回字段（所有请求均包含）
字段名 类型 说明
-------------------------------------------------------------------------------------------
code int 状态码：<br>- 200：请求成功；<br>- 非200：请求失败（具体原因见`msg`）。
msg string 状态信息，描述请求成功/失败的原因（如“任务提交成功”“任务ID不存在”）。
exec_time float 接口执行耗时（单位：秒），用于性能参考。
user_ip string 客户端IP地址，用于排查请求来源问题。
debug string/array 调试数据，仅在接口异常时返回，包含详细错误日志（非必返字段）。
4.2 按任务类型的业务返回字段
4.2.1 提交任务（type=start）返回
当`type=start`且请求成功（code=200）时，返回数据中包含任务ID，用于后续查询。
字段名 类型 说明
-----------------------------------------------------------------------------------------
task_id string 任务ID，唯一标识当前提交的转写任务，需保存用于后续查询任务结果。
data string 任务提交结果描述（如“批量任务已创建，共2个音频文件”）。
返回示例（成功）：
```json
{
"code": 200,
"msg": "任务提交成功",
"data": "批量任务已创建，共2个音频文件",
"task_id": "b68b6285901bb8621f680fbabe796d6e",
"exec_time": 0.32,
"user_ip": "123.45.67.89",
"debug": ""
}
```
4.2.2 查询任务（type=query）返回
当`type=query`且请求成功（code=200）时，返回数据中包含任务状态、音频信息及转写结果（含字幕信息）。
字段名 类型 说明
---------------------------------------------------------------------------------------------
data object 任务结果数据集，包含以下子字段（仅任务完成时返回完整数据）：
├─ display array 识别信息组，每个元素对应一段音频的转写详情（多音频任务返回多个元素）。
│ ├─ source string 音频源URL，对应提交时的`audio_urls`中的某个地址。
│ ├─ seconds string 音频时长（单位：秒），如“125.3”表示125秒300毫秒。
│ └─ phrases array 字幕断句列表，每个元素为一段字幕的详细信息：
│ ├─ text string 该段字幕的文本内容。
│ ├─ confidence string 文本识别置信度（0-100），值越高表示识别结果越准确。
│ ├─ start_time string 字幕开始时间（格式：时:分:秒.毫秒），如“00:01:45.300”。
│ └─ duration string 字幕持续时间（格式：时:分:秒.毫秒），如“00:00:08.500”。
task_id string 任务ID，与请求时传入的`task_id`一致。
返回示例（任务完成）：
```json
{
"code": 200,
"msg": "任务查询成功（已完成）",
"data": {
"display": [
{
"source": "https://#/audio_sample1.mp3",
"seconds": "125.3",
"phrases": [
{
"text": "大家好，欢迎使用酷虎云STT接口",
"confidence": "98.5",
"start_time": "00:00:02.100",
"duration": "00:00:05.200"
},
{
"text": "本接口支持批量音频转写和SRT字幕导出",
"confidence": "97.8",
"start_time": "00:00:07.500",
"duration": "00:00:06.800"
}
]
},
{
"source": "https://#/audio_sample2.mp3",
"seconds": "89.6",
"phrases": [
{
"text": "查询任务时需传入正确的任务ID",
"confidence": "99.1",
"start_time": "00:00:01.300",
"duration": "00:00:04.700"
}
]
}
]
},
"task_id": "b68b6285901bb8621f680fbabe796d6e",
"exec_time": 0.58,
"user_ip": "123.45.67.89",
"debug": ""
}
```
返回示例（任务处理中）：
```json
{
"code": 200,
"msg": "任务查询成功（处理中）",
"data": "当前任务进度：60%，请稍后查询",
"task_id": "b68b6285901bb8621f680fbabe796d6e",
"exec_time": 0.21,
"user_ip": "123.45.67.89",
"debug": ""
}
```
5. 常见错误码及解决方案
错误码 错误信息示例 可能原因及解决方案
-----------------------------------------------------------------------------------------------------------------------------
400 "参数缺失：key不能为空" 未在URL中传入`key`参数，需从控制台获取密钥并补充到请求URL中。
400 "参数错误：type必须为start或query" `type`参数值错误，需修正为`start`（提交任务）或`query`（查询任务）。
401 "密钥无效：key不存在或已过期" `key`错误或已失效，需登录控制台检查密钥是否正确，或重新生成新密钥。
403 "无权限：当前密钥无STT接口访问权限" 密钥未开通STT接口权限，需在控制台「接口权限管理」中为该密钥开通权限。
404 "任务不存在：task_id无效" 查询时传入的`task_id`错误或已过期，需确认`task_id`是否与提交任务时返回的一致。
415 "不支持的媒体类型：Content-Type必须为application/json" 请求头未设置`Content-Type: application/json`，需补充该请求头。
500 "服务器错误：音频URL无法访问" 提交的`audio_urls`中存在无法访问的URL，需检查音频地址是否有效、是否支持外部访问。
6. 接口调用流程示例
以“提交转写任务→查询任务结果→导出SRT字幕”为例，完整流程如下：
步骤1：提交转写任务（type=start）
1. 构造请求URL：`https://#/api/stt/audiototexturls?key=你的密钥&type=start`
2. 设置请求头：`Content-Type: application/json`
3. 构造请求体（含2个音频URL）：
```json
{
"audio_urls": [
"https://#/audio1.mp3",
"https://#/audio2.mp3"
]
}
```
4. 发送POST请求，获取返回的`task_id`（如`b68b6285901bb8621f680fbabe796d6e`）。
步骤2：查询任务结果（type=query）
1. 构造请求URL：`https://#/api/stt/audiototexturls?key=你的密钥&type=query`
2. 设置请求头：`Content-Type: application/json`
3. 构造请求体（传入步骤1获取的`task_id`）：
```json
{
"task_id": "b68b6285901bb8621f680fbabe796d6e"
}
```
4. 发送POST请求，若返回`msg`为“任务查询成功（已完成）”，则从`data.display[0].phrases`中获取第一段音频的字幕数据。
步骤3：导出SRT字幕
根据`phrases`中的`start_time`（开始时间）、`duration`（持续时间）和`text`（文本），按SRT格式拼接内容，示例如下：
```srt
1
00:00:02.100 --> 00:00:07.300 // 开始时间 + 持续时间 = 结束时间（2.1+5.2=7.3）
大家好，欢迎使用酷虎云STT接口
2
00:00:07.500 --> 00:00:14.300 // 7.5+6.8=14.3
本接口支持批量音频转写和SRT字幕导出
```
7. 注意事项
1. 密钥安全：`key`为接口访问凭证，请勿泄露给第三方，若怀疑密钥泄露，需立即在控制台重新生成。
2. 音频限制：
- 仅支持`http/https`协议的音频URL，本地文件需先上传至服务器并获取公网可访问的URL；
- 推荐音频格式为MP3，其他格式（如WAV、AAC）可能导致识别成功率下降；
- 单条音频时长建议不超过30分钟，超长音频可能导致任务处理超时。
3. 查询频率：任务提交后需等待处理（通常1-5分钟，视音频时长而定），建议间隔30秒-1分钟查询一次，避免高频请求导致接口限流。
4. SRT导出：`phrases`中的`start_time`为字幕开始时间，`duration`为持续时间，需自行计算字幕结束时间（开始时间+持续时间）后拼接SRT格式。
来源：酷虎云字幕识别转换api接口开放平台
沪ICP备14003863号
贵公网安备 52010202003147号