文档结果查询接口
1. 接口介绍
查询 7 天内的异步文档任务状态及结果,可用于轮询任务结果。通常任务有如下几种状态:
- 正在排队等待处理:待处理任务数量超出上限,排队等待处理
- 正在处理:任务正在被处理
- 处理成功:任务处理成功,已有识别结果
- 处理失败:任务处理失败,可能由于文件链接无法访问等原因导致任务处理失败
- 已取消:任务被客户取消
- 已过期:任务结果已过期
2. 请求
2.1 请求地址
- v3.1(推荐)
区域 | 请求地址 |
---|---|
国内 | https://api.open.tuputech.com/v3.1/recognition/doc/result/<secretId> |
国外 | https://api-oversea.open.tuputech.com/v3.1/recognition/doc/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(推荐)
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
requestId | String | 是 | 任务 ID |
timestamp | Number | 是 | 当前服务器的 Unix 时间戳 |
nonce | Number | 是 | 随机数 |
signature | String | 是 |
|
2.6 请求示例
- v3.1(推荐)
{
"requestId": "<requestId>",
"timestamp": 1685000000,
"nonce": 1685000000,
"signature": "<signature>"
}
3. 同步响应
3.1 响应参数说明 🔥🔥
参数名称 | 类型 | 说明 |
---|---|---|
signature | String | 同步响应或回调请求签名,由图普使用私钥签名,在需要时,您可以通过 图普公钥 进行验签以确保此响应内容来自图普(与您调用接口时使用的公私钥不同)。验签步骤:
|
json | String | 同步响应或回调请求经过 JSON 转义后的字符串,需进一步解析得到业务数据。
|
JSON 参数说明
- v3.1(推荐)
参数名称 | 类型 | 是否必有 | 说明 |
---|---|---|---|
code | Int | 是 | 状态码,详见 业务状态码 。可能的返回值包括:0 :任务处理完成 29 :任务不存在,或已过期失效 30 :任务正在排队等待处理 31 :任务正在处理 32 :任务已被取消 33 :任务处理失败 100/101 :服务错误 |
message | String | 是 | 状态信息 |
requestId | String | 是 | 任务 ID |
suggestion | Number | 否 | 汇总结果,整体的通过/拒绝情况,当业务状态码为 0 时存在,参考 审核场景汇总结果说明 |
riskType | Number | 否 | 汇总结果,整体的风险类型,当业务状态码为 0 时存在,参考 审核场景汇总结果说明 |
docInfo | DocInfo | 否 | 文档信息,当业务状态码为 0 时存在,详见 DocInfo 参数说明 |
customInfo | Object<String, Any> | 否 | 提交的自定义信息,请求参数中的 customInfo |
pages | Array<PageResult> | 否 | 每页的识别结果,当文档中未识别到违规内容(且回调规则为仅回调违规页)时,可能为空。详见 PageResult 参数说明 |
nonce | Number | 是 | 随机数 |
timestamp | Number | 是 | 当前服务器的 Unix 时间戳 |
3.2 响应示例
- v3.1(推荐)
3.2.1 任务处理成功
{
"code": 0,
"requestId": "<requestId>",
"riskType": 0,
"suggestion": 0,
"docInfo": {
"images": 20,
"pages": 18,
"textLength": 20
},
"customInfo": {
"docId": "<docId>",
"maxImages": 1000,
"maxTextLength": 10000
},
"pages": [
{
"page": 0,
"summary": {
"suggestion": 0,
"riskType": 0
},
"images": [
{
"url": "https://static.tuputech.com/api/image/original/cloud-api/storage-0831/2024-07-04/18-7/88233df8314a40098ef6df19b946d797-0-1/1720089491.7955079406183515637.jpg",
"name": "<requestId>-0-0",
"suggestion": 0,
"riskType": 0,
"details": {
"54bcfc6c329af61034f7c2fc": {
"fileList": [
{
"label": 2,
"rate": 0.9998252987861633,
"review": false,
"name": "<requestId>-0-0"
}
]
}
}
}
],
"text": {
"url": "https://static.tuputech.com/api/image/original/cloud-api/storage-mw/2024-07-09/14-7/1720505398936472/177726.txt",
"suggestion": 1,
"riskType": 1,
"details": {
"57c4036c557603652aeeb222": {
"texts": [
{
"label": 1,
"review": false,
"rate": 1,
"content": "<文本内容>",
"details": [
{
"mainLabel": 1,
"subLabel": "Political_Negative_events",
"keyword": "<关键词>",
"hint": "<违规内容片段>",
"startPos": 0,
"endPos": 3
}
]
}
]
}
}
}
}
],
"timestamp": 1685000000,
"nonce": 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-12 | 新增任务结果查询接口文档 |