语音文件任务结果查询接口
1. 接口介绍
查询 7 天内的语音文件任务状态及结果,可用于轮询任务结果。通常任务有如下几种状态:
- 正在排队等待处理:待处理任务数量超出上限,排队等待处理
- 正在处理:任务正在被处理
- 处理成功:任务处理成功,已有识别结果
- 处理失败:任务处理失败,可能由于文件链接无法访问等原因导致任务处理失败
- 已取消:任务被客户取消
- 已过期:任务结果已过期
2. 请求
2.1 请求地址
- v3.1(推荐)
- v3
区域 | 请求地址 |
---|---|
国内 | https://api.speech.tuputech.com/v3.1/recognition/speech/recording/result/<secretId> |
国外 | https://api-oversea.speech.tuputech.com/v3.1/recognition/speech/recording/result/<secretId> |
区域 | 请求地址 |
---|---|
国内 | https://api.speech.tuputech.com/v3/recognition/speech/recording/result/<secretId> |
国外 | https://api-oversea.speech.tuputech.com/v3/recognition/speech/recording/result/<secretId> |
提示
<secretId>
需替换为您的应用 SID
,请联系客户经理为您开通及配置。关于 SID
详见 常见问题(FAQ)。
2.2 请求方法
POST
2.3 请求头
Content-Type: application/json
2.4 超时时间及异常处理
- 建议配置超时时间
1
秒,在 HTTP 响应状态码非200
或业务状态码为100/101
(服务错误)时立即进行重试; - 在业务状态码为
30/31
(正在排队或正在处理)时,间隔若干时间(取决于应用 QPS 及文件时长)进行重试; - 在业务状态码为
29/32/33
(任务已过期、取消或失败)时立即返回
2.5 请求参数说明 🔥
- v3.1(推荐)
- v3
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
requestId | String | 是 | 任务 ID |
timestamp | Number | 是 | 当前服务器的 Unix 时间戳 |
nonce | Number | 是 | 随机数 |
signature | String | 是 |
|
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
requestId | String | 是 | 任务 ID |
timestamp | Number | 是 | 当前服务器的 Unix 时间戳 |
nonce | Number | 是 | 随机数 |
signature | String | 是 |
|
2.6 请求示例
- v3.1(推荐)
- v3
{
"requestId": "<requestId>",
"timestamp": 1685000000,
"nonce": 1685000000,
"signature": "<signature>"
}
{
"requestId": "<requestId>",
"timestamp": 1685000000,
"nonce": 1685000000,
"signature": "<signature>"
}
3. 同步响应
3.1 响应参数说明 🔥🔥
参数名称 | 类型 | 说明 |
---|---|---|
signature | String | 同步响应或回调请求签名,由图普使用私钥签名,在需要时,您可以通过 图普公钥 进行验签以确保此响应内容来自图普(与您调用接口时使用的公私钥不同)。验签步骤:
|
json | String | 同步响应或回调请求经过 JSON 转义后的字符串,需进一步解析得到业务数据。
|
JSON 参数说明
- v3.1(推荐)
- v3
参数名称 | 类型 | 是否必有 | 说明 |
---|---|---|---|
code | Int | 是 | 状态码,详见 业务状态码 。可能的返回值包括:0 :任务处理完成 29 :任务不存在,或已过期失效 30 :任务正在排队等待处理 31 :任务正在处理 32 :任务已被取消 33 :任务处理失败 100/101 :服务错误 |
message | String | 是 | 状态信息 |
requestId | String | 是 | 任务 ID |
suggestion | Number | 否 | 汇总结果,整体的通过/拒绝情况,当业务状态码为 0 时存在,参考 审核场景汇总结果说明 |
riskType | Number | 否 | 汇总结果,整体的风险类型,当业务状态码为 0 时存在,参考 审核场景汇总结果说明 |
<任务 ID> | Object<String, Any> | 否 | 识别任务的结果,每个识别任务会有 全局固定不变 的 taskId 和对应数据结构,当业务状态码为 0 时存在,详见下述链接:1. 图片类任务结果 2. 文本类任务结果 3. 语音类任务结果 |
speechInfo | SpeechInfo | 是 | 语音文件信息,详见 SpeechInfo 参数说明 |
customInfo | Object<String, Any> | 否 | 提交的自定义信息,请求参数中的 customInfo |
nonce | Number | 是 | 随机数 |
timestamp | Number | 是 | 当前服务器的 Unix 时间戳 |
参数名称 | 类型 | 是否必有 | 说明 |
---|---|---|---|
code | Int | 是 | 状态码,详见 业务状态码 |
message | String | 是 | 返回信息 |
nonce | Number | 是 | 随机数 |
timestamp | Number | 是 | 当前服务器的 Unix 时间戳 |
status | String | 否 | 任务当前状态。pending :正在排队;running :正在处理; |
requestId | String | 是 | 客户提交的音频的唯一请求 id |
speechInfo | Object | 是 | 语音文件信息,详见 SpeechInfo 参数说明 |
roomId | String | 否 | 房间 id |
userId | String | 否 | 用户 id |
forumId | String | 否 | 板块 id,数据 id |
[taskId] | Object | 否 | taskId 为审核任务的 id,value 为审核任务的结果, 具体解释参考审核结果说明 和 响应示例 |
SpeechInfo 参数
字段名 | 类型 | 必填 | 描述 |
---|---|---|---|
duration | Number | 是 | 语音文件时长,单位: 秒 |
信息
返回字段特别说明:
参数名为: status
的字段,仅在查询成功且识别任务还未结束时存在,表示当前请求的音频处理状态
调用者判定步骤:
- 先判断
code
字段是否为公共服务状态码中表示调用成功的值。 - 再判断
status
字段,说明如下:- 值为
pending
: 识别任务等待处理。 - 值为
running
: 识别任务正在处理。 - 无: 识别任务已结束,可以按照语音异步接口的返回结果进行解析
- 值为
3.2 响应示例
- v3.1(推荐)
- v3
3.2.1 任务处理成功
{
"code": 0,
"message": "success",
"requestId": "<requestId>",
"riskType": 1,
"suggestion": 1,
"customInfo": {
"roomId": "<roomId>"
},
"<任务 ID>": {},
"nonce": 1685000000,
"timestamp": 1685000000
}
3.2.2 任务正在处理
{
"code": 31,
"message": "异步任务:任务正在处理",
"requestId": "<requestId>",
"customInfo": {
"roomId": "<roomId>"
},
"nonce": 1685000000,
"timestamp": 1685000000
}
3.2.3 任务处理失败
{
"code": 33,
"message": "异步任务:任务处理失败 (文件错误:文件无效或下载错误)",
"requestId": "<requestId>",
"customInfo": {
"roomId": "<roomId>"
},
"nonce": 1685000000,
"timestamp": 1685000000
}
{
"code": 0,
"message": "success",
"nonce": "0.01627771095362096",
"timestamp": 1552391372490,
"requestId": "tupu_request_id",
"roomId": "your_room_id",
"userId": "your_user_id",
"forumId": "your_forum_id",
"customInfo": {
"hello": true,
"other": "your customInfo"
},
"5c8213b9bc807806aab0a574": {
"violations": [
{
"label": 1,
"review": false,
"details": [
{
"startTime": 5,
"endTime": 10,
"label": 1,
"rate": 0.7449841499328613
}
]
}
]
},
"5ca1bd6b3872ecc9afb99132": {
"text": "床前明月光,疑是地上霜。举头望明月,低头思故乡"
},
"5caee6b2a76925c55a09a6d2": {
"label": "Politics",
"review": false,
"rate": 0.896484,
"action": "block",
"text": "毛泽东,你好",
"violations": [
{
"startTime": 12,
"endTime": 15,
"content": "毛泽东",
"action": "block",
"label": "Politics",
"review": false,
"rate": 0.896484,
"details": [
{
"keyword": "毛泽东",
"hint": "毛泽东",
"mainLabel": "Politics",
"subLabel": "National_Leader"
}
]
}
]
}
}
4. 更新日志
日期 | 说明 |
---|---|
2024-08-09 | 调整并优化任务结果查询接口,将任务状态码收敛到 code 字段,简化解析逻辑;其他字段标记为待废弃 |