跳到主要内容

语音文件任务结果查询接口

1. 接口介绍

查询 7 天内的语音文件任务状态及结果,可用于轮询任务结果。通常任务有如下几种状态:

  • 正在排队等待处理:待处理任务数量超出上限,排队等待处理
  • 正在处理:任务正在被处理
  • 处理成功:任务处理成功,已有识别结果
  • 处理失败:任务处理失败,可能由于文件链接无法访问等原因导致任务处理失败
  • 已取消:任务被客户取消
  • 已过期:任务结果已过期

2. 请求

2.1 请求地址

区域请求地址
国内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>
提示

<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 请求参数说明 🔥

参数名称类型是否必填说明
requestIdString任务 ID
timestampNumber当前服务器的 Unix 时间戳
nonceNumber随机数
signatureString

RSA-SHA256 算法签名。签名步骤:

  1. 将参与签名的参数(secretIdtimestampnonce)用英文半角逗号 , 拼接,得到 SignString
  2. 使用您的私钥以 RSA-SHA256 算法对 SignString 签名,然后进行 Base64 编码,得到 signature 字符串。
  • 点击 数字证书 下载私钥。私钥有 rsapkcs8 两种格式,通常 Golang,Python 使用 rsa 格式私钥,Java 使用 pkcs8 格式私钥
  • 点击 签名及验证示例 查看签名示例

2.6 请求示例

{
"requestId": "<requestId>",
"timestamp": 1685000000,
"nonce": 1685000000,
"signature": "<signature>"
}

3. 同步响应

3.1 响应参数说明 🔥🔥

参数名称类型说明
signatureString

同步响应或回调请求签名,由图普使用私钥签名,在需要时,您可以通过 图普公钥 进行验签以确保此响应内容来自图普(与您调用接口时使用的公私钥不同)。验签步骤:

  1. json 字段内容为 SignString
  2. signature 字段内容进行 Base64 解码,得到 RawSignature
  3. 使用图普公钥以 SHA256 算法验证 RawSignatureSignString
jsonString

同步响应或回调请求经过 JSON 转义后的字符串,需进一步解析得到业务数据。

  • 字段内容示例:{\"code\":0, \"message\":\"success\"}
  • 字段详见下述 JSON 参数说明
  • 为方便展示,同步响应及回调请求的示例中,均为解析后的 JSON

JSON 参数说明

参数名称类型是否必有说明
codeInt状态码,详见 业务状态码 。可能的返回值包括:

0:任务处理完成
29:任务不存在,或已过期失效
30:任务正在排队等待处理
31:任务正在处理
32:任务已被取消
33:任务处理失败
100/101:服务错误
messageString状态信息
requestIdString任务 ID
suggestionNumber汇总结果,整体的通过/拒绝情况,当业务状态码为 0 时存在,参考 审核场景汇总结果说明
riskTypeNumber汇总结果,整体的风险类型,当业务状态码为 0 时存在,参考 审核场景汇总结果说明
<任务 ID>Object<String, Any>识别任务的结果,每个识别任务会有 全局固定不变taskId 和对应数据结构,当业务状态码为 0 时存在,详见下述链接:

1. 图片类任务结果
2. 文本类任务结果
3. 语音类任务结果
speechInfoSpeechInfo语音文件信息,详见 SpeechInfo 参数说明
customInfoObject<String, Any>提交的自定义信息,请求参数中的 customInfo
nonceNumber随机数
timestampNumber当前服务器的 Unix 时间戳

3.2 响应示例

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
}

4. 更新日志

日期说明
2024-08-09调整并优化任务结果查询接口,将任务状态码收敛到 code 字段,简化解析逻辑;其他字段标记为待废弃