通用 PDF 文件流 OCR 到文本

PDF 文字识别与纯文本提取。

上传 PDF 文件即可识别并返回文字；

支持文本型、扫描型及混合 PDF；

支持中文、英文及常见混排内容；

可处理多页文档，按页面顺序提取文字；

单次支持不超过 20 MiB、20 页的 PDF；

返回纯文本，便于复制、整理和保存；

可衔接全文检索、知识库与内容分析；

适合合同、报告、课件与档案数字化；

JSON 结果便于接入业务系统和文档流程；

复杂排版和低清扫描件建议人工复核。
APPKEY 支持 Query、multipart appkey、AppKey/X-GUGUDATA-APPKEY/X-API-Key 请求头及 Bearer。同值允许，冲突返回 501；缺失返回 504。未知及重复参数不接受。

当前接口契约

接口详情：https://www.gugudata.com/api/details/pdf2text

请求参数

参数	类型	必填	默认值	说明
pdffile	string/binary	是	无	multipart 单个未加密 PDF；20 MiB、20 页。APPKEY 可通过 Query、multipart appkey、AppKey/X-GUGUDATA-APPKEY/X-API-Key 请求头或 Bearer 传递；同值允许，冲突返回 501。
appkey	string	否	无	APPKEY；也可使用 Query 或请求头。 AppKey 整体必填；在本操作已声明支持的鉴权位置任选一个提供，本位置无需重复填写。多处填写时须一致。

正常响应字段

字段	类型	说明
DataStatus.RequestParameter	string	实际业务请求参数；上传展示文件名，Demo 展示公开样例文件链接，不包含文件内容或鉴权凭据。
DataStatus.StatusCode	integer	业务状态码
DataStatus.StatusDescription	string	业务状态说明
DataStatus.ResponseDateTime	string	本次响应时间
DataStatus.DataTotalCount	integer	成功为 1，失败为 0，不表示行数或页数。
Data	string	完整纯文本；合法无文字 PDF 成功返回空字符串，失败为 null。

业务状态说明

业务状态码	业务状态码解释	备注
100	成功	HTTP 200
501	参数或 PDF 文件无效	HTTP 400
502	请求频率受限	HTTP 429
503	订单到期	HTTP 403
504	APPKEY 缺失或无效	HTTP 401
505	额度耗尽	HTTP 403
900	内部错误	HTTP 500
901	PDF 文字识别暂不可用	HTTP 503

常见问题

怎么上传 PDF？可以传文件网址吗？

使用 POST 发送 multipart/form-data，在 pdffile 字段上传一个 PDF 文件，并传入对应的 AppKey。只有文件网址时，先下载文件，再上传。

扫描件和文字型 PDF 都能识别吗？

支持文字型 PDF、扫描件，以及同时包含文字页和扫描页的 PDF。请上传未加密的文件。低清扫描件、多栏和复杂表格的识别结果建议对照原文复核。

一个 PDF 最大能传多少？超过限制怎么办？

每次上传一个文件，大小不超过 20 MiB，且不超过 20 页。超限时可将原文件按页拆分，确保每份都符合两个限制，再分别提交并按原页序合并文本。

返回的文字怎么读取？DataTotalCount 为 1 代表一页吗？

识别成功时，Data 是按页序合并的纯文本字符串。解析 JSON 后直接读取 Data 即可。DataStatus.DataTotalCount 为 1 表示返回一份识别结果，和 PDF 页数无关。合法的无文字 PDF 也可能成功，此时 Data 为空字符串。失败时 Data 为 null，可结合业务状态码判断。

识别失败时，怎么判断该改文件还是稍后重试？

先看 DataStatus.StatusCode。返回 501 时，检查上传字段、文件格式、加密状态、大小和页数。返回 504 时，检查 AppKey。返回 901 时，识别服务暂时不可用，可稍后重试。

Demo 和正式接口有什么区别？

Demo 无需 AppKey，供接口请求测试和开发调试使用，返回固定 PDF 样例的识别文本，数据结构与正式接口一致。正式接口需使用对应的 AppKey，识别你上传的 PDF。

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200成功

application/json

成功（业务码 100）。

Bodyapplication/json

示例

{
  "DataStatus": {
    "RequestParameter": "input=pdffile&bytes=18810&pages=1",
    "StatusCode": 100,
    "StatusDescription": "请求成功。",
    "ResponseDateTime": "2026-09-06 14:38:19.989",
    "DataTotalCount": 1
  },
  "Data": "Sample PDF\r\nThis is a simple PDF file. Fun fun fun.\r\nLorem ipsum dolor sit amet, consectetuer adipiscing elit. Phasellus facilisis odio sed mi. Curabitur suscipit. Nullam vel nisi. Etiam semper ipsum ut lectus. Proin aliquam, erat eget pharetra commodo, eros mi condimentum quam, sed commodo justo quam ut velit. Integer a erat. Cras laoreet ligula cursus enim. Aenean scelerisque velit et tellus. Vestibulum dictum aliquet sem. Nulla facilisi. Vestibulum accumsan ante vitae elit. Nulla erat dolor, blandit in, rutrum quis, semper pulvinar, enim. Nullam varius congue risus. Vivamus sollicitudin, metus ut interdum eleifend, nisi tellus pellentesque elit, tristique accumsan eros quam et risus. Suspendisse libero odio, mattis sit amet, aliquet eget, hendrerit vel, nulla. Sed vitae augue. Aliquam erat volutpat. Aliquam feugiat vulputate nisl. Suspendisse quis nulla pretium ante pretium mollis. Proin velit ligula, sagittis at, egestas a, pulvinar quis, nisl.\r\nPellentesque sit amet lectus. Praesent pulvinar, nunc quis iaculis sagittis, justo quam lobortis tortor, sed vestibulum dui metus venenatis est. Nunc cursus ligula. Nulla facilisi. Phasellus ullamcorper consectetuer ante. Duis tincidunt, urna id condimentum luctus, nibh ante vulputate sapien, id sagittis massa orci ut enim. Pellentesque vestibulum convallis sem. Nulla consequat quam ut nisl. Nullam est. Curabitur tincidunt dapibus lorem. Proin velit turpis, scelerisque sit amet, iaculis nec, rhoncus ac, ipsum. Phasellus lorem arcu, feugiat eu, gravida eu, consequat molestie, ipsum. Nullam vel est ut ipsum volutpat feugiat. Aenean pellentesque.\r\nIn mauris. Pellentesque dui nisi, iaculis eu, rhoncus in, venenatis ac, ante. Ut odio justo, scelerisque vel, facilisis non, commodo a, pede. Cras nec massa sit amet tortor volutpat varius. Donec lacinia, neque a luctus aliquet, pede massa imperdiet ante, at varius lorem pede sed sapien. Fusce erat nibh, aliquet in, eleifend eget, commodo eget, erat. Fusce consectetuer. Cras risus tortor, porttitor nec, tristique sed, convallis semper, eros. Fusce vulputate ipsum a mauris. Phasellus mollis. Curabitur sed urna. Aliquam nec sapien non nibh pulvinar convallis. Vivamus facilisis augue quis quam. Proin cursus aliquet metus. Suspendisse lacinia. Nulla at tellus ac turpis eleifend scelerisque. Maecenas a pede vitae enim commodo interdum. Donec odio. Sed sollicitudin dui vitae justo.\r\nMorbi elit nunc, facilisis a, mollis a, molestie at, lectus. Suspendisse eget mauris eu tellus molestie cursus. Duis ut magna at justo dignissim condimentum. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Vivamus varius. Ut sit amet diam suscipit mauris ornare aliquam. Sed varius. Duis arcu. Etiam tristique massa eget dui. Phasellus congue. Aenean est erat, tincidunt eget, venenatis quis, commodo at, quam."
}

🟠400参数或 PDF 文件无效（业务码 501）。

🟠401APPKEY 缺失或无效（业务码 504）。

🟠403订单到期（业务码 503）；额度耗尽（业务码 505）。

🟠429请求频率受限（业务码 502）。

🔴500内部错误（业务码 900）。

🔴503PDF 文字识别暂不可用（业务码 901）。

当前接口契约#

请求参数#

正常响应字段#

业务状态说明#

常见问题#

怎么上传 PDF？可以传文件网址吗？#

扫描件和文字型 PDF 都能识别吗？#

一个 PDF 最大能传多少？超过限制怎么办？#

返回的文字怎么读取？DataTotalCount 为 1 代表一页吗？#

识别失败时，怎么判断该改文件还是稍后重试？#

Demo 和正式接口有什么区别？#

请求参数

请求示例代码

返回响应

当前接口契约

请求参数

正常响应字段

业务状态说明

常见问题

怎么上传 PDF？可以传文件网址吗？

扫描件和文字型 PDF 都能识别吗？

一个 PDF 最大能传多少？超过限制怎么办？

返回的文字怎么读取？DataTotalCount 为 1 代表一页吗？

识别失败时，怎么判断该改文件还是稍后重试？

Demo 和正式接口有什么区别？