文档异步识别接口（大模型版）

1. 接口介绍

该接口可以对常见的文档文件进行自然语言处理，客户通过文档文件异步识别接口提交识别任务，图普下载文件进行识别，通过回调通知客户识别结果。该接口最大支持 500MB 文档。业务流程如下：

提示

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

1.1 接入指南

联系客户经理开通账号
同客户经理沟通详细需求与审核标准。根据您的需求，客户经理将为您开通对应的应用（SID）
访问控制台 - 数字证书获取用于接口鉴权的 API Key
查阅下方的接口参数文档，了解如何构建请求以及如何解析响应数据
使用示例资源调用接口，进行调试和测试
查阅审核场景汇总结果说明，了解如何通过汇总结果判断内容是否违规，以及如何解析汇总结果
添加异常处理逻辑，以处理可能出现的错误和异常情况，增强代码的健壮性和稳定性

如果在接入过程中遇到任何技术问题，请联系客户经理以获取帮助。

2. 请求

2.1 请求地址

v3.1（预览）

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

提示

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

2.2 请求方法

POST

2.3 请求头

请求头名称	取值	是否必需	示例	说明
`Content-Type`	`application/json`	是	`Content-Type: application/json`	请求数据类型为 JSON
`X-API-Key`	`<API Key>`	是	`X-API-Key: <API Key>`	API Key 用于接口鉴权。请访问控制台 - 数字证书获取 API Key

2.4 超时时间及异常处理

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

2.5 请求参数说明 🔥

v3.1（预览）

参数名称	类型	是否必填	说明
`doc`	Doc	是	文档文件信息，详见 Doc 参数说明
`customInfo`	Object<String, Any>	否	自定义信息，用于为请求附加业务信息（如房间 ID、文件 ID 等）或其他扩展参数
`timestamp`	Int	否	当前服务器的 Unix 时间戳。当前已废弃，仅保持兼容（采用该鉴权方式的调用不受影响）。新接入请使用 API Key 接口鉴权
`nonce`	Float	否	随机数（建议使用 Unix 时间戳或若干位随机整数）。当前已废弃，仅保持兼容（采用该鉴权方式的调用不受影响）。新接入请使用 API Key 接口鉴权
`signature`	String	否	`RSA-SHA256` 算法签名。当前已废弃，仅保持兼容（采用该鉴权方式的调用不受影响）。新接入请使用 API Key 接口鉴权。签名步骤：将参与签名的参数（`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`、`png`、`jpg`、`jpeg`，其他纯文本类文档及常见图片类型文件； 2. 出于安全考虑，文档链接端口除 `80`, `443` 端口外，应在 `1025-65535` 范围内； 3. 文档大小须小于 500MB，超出时回调状态码 `14`（文件错误）； 4. 链接须支持 HEAD 请求，以便进行文档大小探测
`format`	String	否	文档文件格式。未指定时，会下载文件的部分内容进行格式探测。 1. 可选值：`doc`、`docx`、`xlsx`、`ppt`、`pptx`、`pdf`、`html`、`txt`、`png`、`jpg`、`jpeg`； 2. 对 `txt`、`csv`、`markdown` 及其他纯文本类文档，均会按照纯文本处理； 3. 不指定文档格式时，链接建议支持分片下载，以免重复下载完整文件
`callback`	String	否	识别结果回调接口地址，用于接收 POST 回调；未指定时忽略回调

2.6 请求示例

v3.1（预览）

{
  "doc": {
    "url": "<url>",
    "callback": "<callback>"
  },
  "customInfo": {
    "docId": "<docId>"
  },
  "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`	Int	是	状态码，详见业务状态码
`message`	String	是	状态信息
`result`	Result	否	任务提交结果，详见 Result 参数说明
`nonce`	Float	是	随机数（建议使用 Unix 时间戳或若干位随机整数）
`timestamp`	Int	是	当前服务器的 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`	Int	是	状态码，详见业务状态码
`message`	String	是	状态信息
`requestId`	String	是	任务唯一 ID
`result`	Object<String, Any>	是	大模型识别结果，具体字段需沟通确定
`customInfo`	Object<String, Any>	否	透传的自定义信息，请求参数中的 `customInfo`

4.6 回调请求解析伪代码

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

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

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

// 3. 解析识别结果
handleResult(result.result)

4.7 请求示例

v3.1（预览）

{
  "code": 0,
  "requestId": "<requestId>",
  "customInfo": {
    "docId": "<docId>"
  },
  "result": {
    "<key>": "<value>"
  },
  "timestamp": 1685000000,
  "nonce": 1685000000
}

5. 更新日志

日期	说明
2025-07-22	新增接口文档

文档异步识别接口（大模型版）

1. 接口介绍​

1.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 参数说明​

4.6 回调请求解析伪代码​

4.7 请求示例​

5. 更新日志​

1. 接口介绍

1.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 参数说明

4.6 回调请求解析伪代码

4.7 请求示例

5. 更新日志