文档异步识别接口

1. 接口介绍

该接口可以对常见的文档文件进行内容审核，客户通过文档文件异步识别接口提交识别任务，图普下载文件进行识别检测，通过回调通知客户识别结果。为了统一文档的处理方式，我们将文档的基本组成部分抽象为页，在页的基础上抽取图片文本等内容后进行审核：

doc、docx、ppt、pptx、pdf 类文档，每一页与文档的页对应；
xlsx 类电子表格文档，每一页对应文档的工作表（worksheet）；
html 网页会转换为 PDF，每一页与 PDF 文档的页对应；
txt、csv、markdown 类纯文本文档，为方便进行结果展示以及人工复审（尤其是长小说文本），我们会基于一定的长度规则，对文本进行分段，每一段即为一页。

该接口最大支持 500MB 文档，最多可以识别 100 万文本以及 1 万张图片，超出后，后续的文本及图片会忽略。

该接口提供了扩展配置，客户可以根据业务场景，自定义文本长度及图片数量上限，以平衡识别覆盖率、处理速度与成本，详见请求参数说明。

业务流程如下：

提示

图普采用 任务并发数 对异步接口进行并发控制，即任一时刻最多允许 N 个任务同时处理。在测试期间，任务并发数为 30（允许同时处理 30 个任务），正式使用或需要增加时请联系客户经理调整。当超出任务并发数后继续提交任务时，根据接口类型略有不同：
- 异步文件接口：可以正常提交任务，提交的任务排队等待处理；
- 异步流接口：提交任务时返回超出并发状态码（由于流的实时性要求，无法排队等待处理，因此无法继续提交）。
异步文件接口中，视频/语音文件建议小于 10GB，而文档文件须小于 500MB；异步流接口对流的时长没有限制，建议客户在流关闭时主动调用任务关闭接口。

2. 请求

2.1 请求地址

v3.1（推荐）

区域	请求地址
国内	`https://api.open.tuputech.com/v3.1/recognition/doc/async/<secretId>`
国外	`https://api-oversea.open.tuputech.com/v3.1/recognition/doc/async/<secretId>`

提示

<secretId> 需替换为您的应用 SID，请联系客户经理为您开通及配置。关于 SID 详见常见问题（FAQ）。

2.2 请求方法

POST

2.3 请求头

Content-Type: application/json

2.4 超时时间及异常处理

建议配置超时时间 1 秒，在 HTTP 响应状态码非 200 或业务状态码不为 0 时进行重试。

2.5 请求参数说明 🔥

v3.1（推荐）

参数名称	类型	是否必填	说明
`doc`	Doc	是	文档文件信息，详见 Doc 参数说明
`tasks`	Array<String>	否	指定的任务 ID。通常单个应用（接口）下会配置多个识别任务，可根据业务需要指定其中的部分任务进行识别
`customInfo`	Object<String, Any>	否	自定义信息，用于给请求附加额外信息或扩展参数（比如：关联的信息）。目前支持的扩展参数： 1. 限制相关参数。客户可以通过下述参数自定义限制，平衡识别覆盖率、处理速度与成本： - `maxImages`：识别图片的最大数量，取值范围为 `[100, 10000]`，默认 `1000`。该参数有效时，仅识别该数量内的图片，超出后忽略； - `maxTextLength`：识别文本的最大长度，取值范围为 `[1000, 1000000]`，默认 `10000`。该参数有效时，仅识别该数量内的文本，超出后忽略
`nonce`	Number	是	随机数
`timestamp`	Number	是	当前服务器的 Unix 时间戳
`signature`	String	是	`RSA-SHA256` 算法签名。签名步骤：将参与签名的参数（`secretId`，`timestamp`，`nonce`）用英文半角逗号 `,` 拼接，得到 `SignString`；使用您的私钥以 `RSA-SHA256` 算法对 `SignString` 签名，然后进行 `Base64` 编码，得到 `signature` 字符串。点击数字证书下载私钥。私钥有 rsa 和 pkcs8 两种格式，通常 Golang，Python 使用 rsa 格式私钥，Java 使用 pkcs8 格式私钥点击签名及验证示例查看签名示例

Doc 参数说明

参数名称	类型	是否必填	说明
`url`	String	是	文档文件链接。 1. 支持的文档格式：`doc`、`docx`、`xlsx`、`ppt`、`pptx`、`pdf`、`html`，`txt`、`csv`、`markdown` 及其他纯文本类文档； 2. 出于安全考虑，文档链接端口除 `80`, `443` 端口外，应在 `1025-65535` 范围内； 3. 文档大小须小于 500MB，超出时回调状态码 `14`（文件错误）； 4. 链接须支持 HEAD 请求，以便进行文档大小探测
`format`	String	否	文档文件格式。未指定时，会下载文件的部分内容进行格式探测。 1. 可选值：`doc`、`docx`、`xlsx`、`ppt`、`pptx`、`pdf`、`html`、`txt`； 2. 对 `txt`、`csv`、`markdown` 及其他纯文本类文档，均会按照纯文本处理； 3. 不指定文档格式时，链接建议支持分片下载，以免重复下载完整文件
`callback`	String	否	识别结果回调接口地址，用于接收 POST 回调；未指定时忽略回调
`callbackRule`	String	否	回调规则，主要影响审核场景的识别任务，如色情识别，默认为 `violation`。 `violation`：仅回调违规页（含违规需复审）的识别结果

2.6 请求示例

v3.1（推荐）

{
  "doc": {
    "url": "<url>",
    "callback": "<callback>",
    "callbackRule": "violation"
  },
  "tasks": [
    "<taskId>"
  ],
  "customInfo": {
    "docId": "<docId>",
    "maxImages": 1000,
    "maxTextLength": 10000
  },
  "timestamp": 1685000000,
  "nonce": 1685000000,
  "signature": "<signature>"
}

3. 同步响应

3.1 响应参数说明 🔥🔥

参数名称类型说明

参数名称	类型	说明
`signature`	String	同步响应或回调请求签名，由图普使用私钥签名，在需要时，您可以通过图普公钥进行验签以确保此响应内容来自图普（与您调用接口时使用的公私钥不同）。验签步骤：取 `json` 字段内容为 `SignString`；将 `signature` 字段内容进行 `Base64` 解码，得到 `RawSignature`；使用图普公钥以 `SHA256` 算法验证 `RawSignature` 及 `SignString`
`json`	String	同步响应或回调请求经过 JSON 转义后的字符串，需进一步解析得到业务数据。字段内容示例：`{\"code\":0, \"message\":\"success\"}`；字段详见下述 JSON 参数说明；为方便展示，同步响应及回调请求的示例中，均为解析后的 JSON

signature

String

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

取 json 字段内容为 SignString；
将 signature 字段内容进行 Base64 解码，得到 RawSignature；
使用图普公钥以 SHA256 算法验证 RawSignature 及 SignString

json

String

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

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

JSON 参数说明

v3.1（推荐）

参数名称	类型	是否必有	说明
`code`	Number	是	状态码，详见业务状态码
`message`	String	是	状态信息
`result`	Result	否	任务提交结果，详见 Result 参数说明
`nonce`	Number	是	随机数
`timestamp`	Number	是	当前服务器的 Unix 时间戳

Result 参数说明

参数名称	类型	是否必有	说明
`requestId`	String	是	任务唯一 ID，回调中携带该任务 ID。字符串长度 24~128
`url`	String	是	提交的文档文件地址
`callback`	String	否	提交的识别结果回调接口地址

3.2 响应示例

v3.1（推荐）

{
  "code": 0,
  "message": "success",
  "result": {
    "requestId": "<requestId>",
    "url": "<url>",
    "callback": "<callback>"
  },
  "timestamp": 1685000000,
  "nonce": 1685000000
}

4. 回调请求

4.1 请求地址

callback 参数指定的地址。

4.2 请求方法

POST

4.3 请求头

Content-Type: application/json

4.4 超时时间及异常处理

回调超时时间 5 秒，在 HTTP 响应状态码非 200 时进行重试，最多重试 3 次。

建议客户在处理回调时进行异步处理，响应回调时可以返回字符串或 JSON，示例如下：

// JSON
{
  "message": "ok"
}

// 字符串
success

4.5 请求参数说明 🔥🔥🔥

参数名称类型说明

参数名称	类型	说明
`signature`	String	同步响应或回调请求签名，由图普使用私钥签名，在需要时，您可以通过图普公钥进行验签以确保此响应内容来自图普（与您调用接口时使用的公私钥不同）。验签步骤：取 `json` 字段内容为 `SignString`；将 `signature` 字段内容进行 `Base64` 解码，得到 `RawSignature`；使用图普公钥以 `SHA256` 算法验证 `RawSignature` 及 `SignString`
`json`	String	同步响应或回调请求经过 JSON 转义后的字符串，需进一步解析得到业务数据。字段内容示例：`{\"code\":0, \"message\":\"success\"}`；字段详见下述 JSON 参数说明；为方便展示，同步响应及回调请求的示例中，均为解析后的 JSON

signature

String

取 json 字段内容为 SignString；
将 signature 字段内容进行 Base64 解码，得到 RawSignature；
使用图普公钥以 SHA256 算法验证 RawSignature 及 SignString

json

String

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

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

JSON 参数说明

v3.1（推荐）

参数名称	类型	是否必有	说明
`code`	Number	是	状态码，详见业务状态码
`message`	String	是	状态信息
`requestId`	String	是	任务唯一 ID
`docInfo`	DocInfo	是	文档信息，详见 DocInfo 参数说明
`suggestion`	Number	否	汇总结果，整体的通过/拒绝情况，参考审核场景汇总结果说明
`riskType`	Number	否	汇总结果，整体的风险类型，参考审核场景汇总结果说明
`customInfo`	Object<String, Any>	否	提交的自定义信息
`pages`	Array<PageResult>	否	每页的识别结果，当文档中未识别到违规内容（且回调规则为仅回调违规页）时，可能为空。详见 PageResult 参数说明

PageResult 参数说明

参数名称	类型	是否必有	说明
`page`	Int	是	当前页索引，从 `1` 开始
`summary`	PageSummary	是	当前页汇总结果，详见 PageSummary 参数说明
`images`	Array<PageImageResult>	否	当前页提取到的图片识别结果数组，为空时该字段省略。详见 PageImageResult 参数说明
`text`	PageTextResult	否	当前页文本识别结果，为空时该字段省略。详见 PageTextResult 参数说明

PageSummary 参数说明

参数名称	类型	是否必有	说明
`suggestion`	Number	是	当前页汇总结果，整体的通过/拒绝情况，参考审核场景汇总结果说明
`riskType`	Number	是	当前页汇总结果，整体的风险类型，参考审核场景汇总结果说明

PageImageResult 参数说明

参数名称	类型	是否必有	说明
`url`	String	是	图片链接
`name`	String	是	图片名称，根据所在页及图片索引生成，用以唯一标识文档中的图片
`suggestion`	Number	是	当前图片汇总结果，整体的通过/拒绝情况，参考审核场景汇总结果说明
`riskType`	Number	是	当前图片汇总结果，整体的风险类型，参考审核场景汇总结果说明
`details`	Details	是	各任务识别结果，详见 Details 参数说明

PageTextResult 参数说明

参数名称	类型	是否必有	说明
`url`	String	是	当前页文本 txt 文件链接。 1. 我们将文档分页后，将每页的文本以纯文本的形式保存在 txt 文件中，以减小结果回调的大小。您可以通过 HTTP 请求下载该文件获取纯文本
`suggestion`	Number	是	当前页文本汇总结果，整体的通过/拒绝情况，参考审核场景汇总结果说明
`riskType`	Number	是	当前页文本汇总结果，整体的风险类型，参考审核场景汇总结果说明
`details`	Details	是	各任务识别结果，详见 Details 参数说明

Details 参数说明

参数名称	类型	是否必有	说明
`<任务 ID>`	Object	是	识别任务的结果，每个识别任务会有全局固定不变的 `taskId` 和对应数据结构，详见下述链接： 1. 图片类任务结果 2. 文本类任务结果 3. 语音类任务结果

DocInfo 参数说明

参数名称	类型	是否必有	说明
`pages`	Int	是	文档中包含的页数量
`images`	Int	是	文档中包含的图片数量。 1. 由于实际识别时会根据识别上限进行截断，因此该值不等同于计费数，仅供参考
`textLength`	Int	是	文档中包含的文本长度。 1. 该值为包含空格及其他制表符的 unicode 字符数； 2. 由于实际识别时会对文本进行处理/修剪/截断，因此该值不等同于计费数，仅供参考

4.6 回调请求解析伪代码

下述给出不同使用场景下，解析回调请求的伪代码示例供参考。

4.6.1 仅关注文档是否违规，以及是否需要复审

// 1. 解析回调请求的 json 字段
result = JSON.parse(CallbackRequest.json)

// 2. 校验任务是否处理成功，否的话进入错误处理流程
if (result.code != 0) {
    handleError(result)
    return
}

// 3. 检查汇总结果
switch (result.suggestion) {
    // 3.1 汇总通过，进入正常文档处理流程
    case 0:
        handlePass(result)
        return
        
    // 3.2 汇总拒绝，疑似违规，进入违规文档处理流程
    case 1:
        handleReject(result)
        return
        
    // 3.2 汇总复审，可能违规，进入文档人工复审处理流程
    case 2:
        handleReview(result)
        return
}

4.6.2 当文档疑似违规时，解析风险类型

// 1. 解析回调请求的 json 字段
result = JSON.parse(CallbackRequest.json)

// 2. 解析风险类型
riskType = null
if (result.code == 0 && result.suggestion == 1) {
    riskType = result.riskType
}

handleRiskType(riskType)

4.6.2 当文档疑似违规时，查找违规图片及文本

// 1. 解析回调请求的 json 字段
result = JSON.parse(CallbackRequest.json)


// 2. 查找违规图片及文本
images = []
texts = []
if (result.code == 0 && result.suggestion == 1) {
    // 2.1 遍历每页结果 
    result.pages.forEach( (page) => {
        // 2.2 筛选违规图片
        page.images?.forEach( (image) => {
            if (image.suggestion == 1) {
                images.push(image)
            }
        } )
        
        // 2.3 筛选违规文本
        if (page.text?.suggestion == 1) {
            texts.push(text)
        }
    } )
}

handleContents(images, texts)

4.7 请求示例

v3.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
}

5. 更新日志

日期	说明
2024-07-11	新增接口文档

文档异步识别接口

1. 接口介绍​

2. 请求​

2.1 请求地址​

2.2 请求方法​

2.3 请求头​

2.4 超时时间及异常处理​

2.5 请求参数说明 🔥​

Doc 参数说明​

2.6 请求示例​

3. 同步响应​

3.1 响应参数说明 🔥🔥​

JSON 参数说明​

Result 参数说明​

3.2 响应示例​

4. 回调请求​

4.1 请求地址​

4.2 请求方法​

4.3 请求头​

4.4 超时时间及异常处理​

4.5 请求参数说明 🔥🔥🔥​

JSON 参数说明​

PageResult 参数说明​

PageSummary 参数说明​

PageImageResult 参数说明​

PageTextResult 参数说明​

Details 参数说明​

DocInfo 参数说明​

4.6 回调请求解析伪代码​

4.6.1 仅关注文档是否违规，以及是否需要复审​

4.6.2 当文档疑似违规时，解析风险类型​

4.6.2 当文档疑似违规时，查找违规图片及文本​

4.7 请求示例​

5. 更新日志​

1. 接口介绍

2. 请求

2.1 请求地址

2.2 请求方法

2.3 请求头

2.4 超时时间及异常处理

2.5 请求参数说明 🔥

Doc 参数说明

2.6 请求示例

3. 同步响应

3.1 响应参数说明 🔥🔥

JSON 参数说明

Result 参数说明

3.2 响应示例

4. 回调请求

4.1 请求地址

4.2 请求方法

4.3 请求头

4.4 超时时间及异常处理

4.5 请求参数说明 🔥🔥🔥

JSON 参数说明

PageResult 参数说明

PageSummary 参数说明

PageImageResult 参数说明

PageTextResult 参数说明

Details 参数说明

DocInfo 参数说明

4.6 回调请求解析伪代码

4.6.1 仅关注文档是否违规，以及是否需要复审

4.6.2 当文档疑似违规时，解析风险类型

4.6.2 当文档疑似违规时，查找违规图片及文本

4.7 请求示例

5. 更新日志