# PDF文件正文抽取：免费档位限制与频率/成本控制
> 接口 PDF文件正文抽取（apiCode=10，接入点 10-1） · 免费服务 · 请求方式 POST · 返回格式 JSON · 适用人群 免费档位用户、批量使用者 · 阅读时间 约 5 分钟
## 核心要点
- 文档明确本接口为**免费服务**，注册后默认可调用，但「为防止滥用设有使用档次限制」。
- 具体档位额度文档未给出，**以 [官方免费 API 档位说明](https://www.showapi.com/free-api) 为准**，本文不编造数字。
- 两大省钱/稳用手段：**结果缓存（避免重复调用）+ 调用限流（避免触发限制）**。
## Why：为什么免费用户更要谈成本
免费不等于无限。文档说明免费调用带有「使用档次限制」——超出就可能调用失败或受限。对偶尔用用的个人无所谓，但一旦做批量（论文、合同、档案），不理解限制、不做控制，就会「前面跑得好好的，突然一批全挂」。本文给你两条可在客户端落地的控制手段。
## What：限制从哪来
| 来源 | 说明 |
|------|------|
| 官方说明 | 免费服务 + 使用档次限制 |
| 额度数字 | 文档未列出，以 [免费 API 档位说明](https://www.showapi.com/free-api) 为准 |
| 触发后果 | 超限可能导致调用被拒/限流，具体以平台返回为准 |
## How：两条控制手段
**手段一：结果缓存，避免重复调用**
同一份 PDF 不要反复抽。用文件哈希做 key，命中缓存直接返回。
```python
import hashlib, requests, os
CACHE = "cache"
os.makedirs(CACHE, exist_ok=True)
def extract(pdf_path):
key = hashlib.md5(open(pdf_path, "rb").read()).hexdigest()
cached = os.path.join(CACHE, key + ".txt")
if os.path.exists(cached): # 命中缓存，免调用
return open(cached, encoding="utf-8").read()
resp = requests.post(
"https://route.showapi.com/10-1?appKey=YOUR_APPKEY",
files={"pdf": open(pdf_path, "rb")}, timeout=15,
).json()
if resp.get("showapi_res_code") != 0:
raise RuntimeError(resp.get("showapi_res_error"))
body = resp["showapi_res_body"]
if body.get("ret_code") != "0":
raise RuntimeError(body.get("remark"))
text = body.get("text", "")
open(cached, "w", encoding="utf-8").write(text)
return text
```
**手段二：调用限流，平稳不触发限制**
批量时加入间隔或令牌桶，控制单位时间请求数。
```python
import time
def rate_limited_calls(tasks, interval=1.0):
for task in tasks:
yield extract(task) # 复用上面的 extract
time.sleep(interval) # 免费档位下建议保留间隔
```
## 返回示例与解析
限流与缓存不改变接口返回结构，仍是 `showapi_res_body.text`。它们只是「在调用之前」做的客户端决策：能不调就不调（缓存）、要调也慢慢调（限流）。
## 进阶 / 边界
- **先确认额度再提速**：先用保守间隔跑通，再到 [免费 API 档位说明](https://www.showapi.com/free-api) 核对你的实际额度，再决定是否提高并发。
- **幂等设计**：同一文件哈希命中缓存，天然幂等，重试安全。
- **监控失败**：记录非 0 返回与 `remark`，便于判断是否触及限制。
## FAQ
**Q：免费到底能调多少次？**
A：文档只说明「免费 + 使用档次限制」，具体额度以 [官方免费 API 档位说明](https://www.showapi.com/free-api) 为准，本文不编造具体数字。
**Q：缓存会不会漏掉文件更新？**
A：缓存 key 用文件内容哈希，文件内容变了哈希就变，会自动重新抽取，不会用到旧结果。
**Q：限流间隔设多少合适？**
A：保守起见从 1 秒/次起步；在不超你档位额度的前提下可再缩短。先稳后再优化。
**Q：缓存文件会很大吗？**
A：每个缓存是一个 `.txt`，大小约等于对应 PDF 的正文长度，通常远小于原 PDF，磁盘压力可控。
## 相关能力 / 下一步阅读
- [PDF文件正文抽取：学术论文与文献 PDF 批量抽取实战](https://www.showapi.com/guides/pdf-extract-academic-10)
- [PDF文件正文抽取：5 分钟从注册到跑通第一条抽取结果](https://www.showapi.com/guides/pdf-extract-quickstart-10)
- **本系列共 10 篇**：查看[PDF文件正文抽取指南总目录](https://www.showapi.com/guides/pdf-extract-guides-10)
