跳到主要内容

文档结果查询接口

1. 接口介绍

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

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

2. 请求

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

参数名称类型是否必填说明
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 时存在,参考 审核场景汇总结果说明
docInfoDocInfo文档信息,当业务状态码为 0 时存在,详见 DocInfo 参数说明
customInfoObject<String, Any>提交的自定义信息,请求参数中的 customInfo
pagesArray<PageResult>每页的识别结果,当文档中未识别到违规内容(且回调规则为仅回调违规页)时,可能为空。详见 PageResult 参数说明
nonceNumber随机数
timestampNumber当前服务器的 Unix 时间戳

3.2 响应示例

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新增任务结果查询接口文档