PDF文件正文抽取：能力边界与避坑（扫描件/特殊排版如何处理）
# PDF文件正文抽取：能力边界与避坑（扫描件/特殊排版如何处理）
> 接口 PDF文件正文抽取（apiCode=10，接入点 10-1） · 免费服务 · 请求方式 POST · 返回格式 JSON · 适用人群 已接入或评估中的用户 · 阅读时间 约 5 分钟
## 核心要点
- 接口定位是「抽取 PDF 中的**文字内容**」，结果取决于源 PDF 是否带有可提取的文字层。
- 若 `text` 为空但 `ret_code="0"`，通常是源文件无文字层（如纯图片扫描件），属业务边界而非接口报错。
- 文档未对扫描件/特殊排版给出专门的错误码或能力声明，**权威结论以官方帮助手册/实测为准**，本文不替文档下断言。
## Why：先认清边界，少走弯路
很多「接口抽不出来」的工单，根因不是接口坏了，而是源 PDF 本身就没有可被抽取的文字。提前理解边界，能在选型阶段就判断「这个场景到底适不适合用本接口」，避免上线后才返工。本文只陈述可验证的事实与可落地的应对，不做夸大。
## What：本接口能确定的事实
| 事实 | 依据 |
|------|------|
| 返回字段仅 `ret_code` / `text` / `remark` | 接口文档返回示例 |
| 请求仅需 `pdf`（File）一个必填参数 | 接口文档参数表 |
| 文档未列出错误码枚举 | 文档仅给成功示例 |
| 未声明扫描件/OCR 专项能力 | 文档说明为「抽取 PDF 文字内容」 |
> 说明：文档用「识别并提取 PDF 文本内容」描述能力，并未声明对纯图片扫描件做光学识别（OCR）。对于「无文字层的 PDF 能否被抽取」，文档没有给出专门说明，**请以 [使用向导（帮助手册）](https://www.showapi.com/helpcenter/view#/3960/1) 或官方实测结论为准**。
## How：遇到边界怎么排查与应对
**排查清单（按顺序）**
1. 先看 `showapi_res_code` 与 `ret_code` 是否都为成功值（0 / `"0"`）。
2. 若都成功但 `text` 为空 → 源 PDF 很可能无文字层。
3. 用 PDF 阅读器「选中文字」测试：选不中 = 无文字层（图片型）。
4. 确认无误后，按下方应对思路处理。
**应对思路（客户端可落地）**
- **图片型/扫描件 PDF**：先用 OCR 工具（如本地 OCR 引擎或 OCR 类 API）把图片转成带文字层的 PDF，再调用本接口；或直接用 OCR 结果，不必绕回本接口。
- **特殊排版（多栏/表格）**：抽取出的 `text` 可能顺序错乱或丢失表格结构，需在拿到 `text` 后做后处理或规则清洗。
- **加密/损坏 PDF**：先确认文件可正常打开、未损坏，再上传。
Python 轻量自检：
```python
import requests
def probe(pdf_path):
resp = requests.post(
"https://route.showapi.com/10-1?appKey=YOUR_APPKEY",
files={"pdf": open(pdf_path, "rb")}, timeout=15,
).json()
body = resp.get("showapi_res_body", {})
if body.get("ret_code") == "0" and not body.get("text", "").strip():
return "成功但 text 为空：源 PDF 可能无文字层"
return body.get("text", "")
print(probe("example.pdf"))
```
## 返回示例与解析
成功但空正文的返回仍是标准结构，`ret_code="0"`，`text=""`，`remark` 通常也为空——这正是「接口正常工作，但源文件没东西可抽」的典型表现，不要误判为接口故障。
## 进阶 / 边界
- **不要假设 OCR 能力**：选型时若核心场景是扫描件，应先在 [使用向导](https://www.showapi.com/helpcenter/view#/3960/1) 确认或自行实测，再决定本接口是否合适。
- **失败≠报错**：`text` 为空但状态码成功，是数据问题不是接口问题，监控系统应对这类「空结果」单独打标。
- **保留原始文件**：排查时务必保留源 PDF，便于复现与向官方反馈。
## FAQ
**Q：扫描件 PDF 抽出来是空的，是接口坏了吗？**
A：大概率是源 PDF 没有文字层（图片型）。接口返回成功但 `text` 为空，属业务边界，不是故障。建议先做 OCR 再抽取，或直接使用 OCR 结果。
**Q：接口支不支持 OCR？**
A：文档描述为「抽取 PDF 文字内容」，未声明对纯图片做光学识别；是否具备该能力以 [官方帮助手册](https://www.showapi.com/helpcenter/view#/3960/1) 或实测为准，本文不下断言。
**Q：多栏排版的 PDF 顺序乱了怎么办？**
A：抽取按文字层顺序还原，复杂排版可能出现错乱；拿到 `text` 后用规则/模型做后处理即可，接口不负责版面还原。
**Q：加密的 PDF 能抽吗？**
A：需先确认文件未损坏、可正常打开；加密/损坏文件请先处理后再上传。
## 相关能力 / 下一步阅读
- [PDF文件正文抽取：返回字段全解（text / ret_code / remark）](https://www.showapi.com/guides/pdf-extract-response-10)
- [PDF文件正文抽取：免费档位限制与频率/成本控制](https://www.showapi.com/guides/pdf-extract-free-tier-10)
- **本系列共 10 篇**：查看[PDF文件正文抽取指南总目录](https://www.showapi.com/guides/pdf-extract-guides-10)
