PDF OCR

从扫描的 PDF 文档中逐页提取文本，无需将 PDF 发送到外部服务。内置 fast 层使用 Tesseract。可选的 balanced 和 best 层使用 RapidOCR 和固定的 PP-OCR ONNX 模型。

韩语 OCR 兼容性

快速 OCR 支持 auto、en、de、es、fr、zh 和 ja，但不支持韩语 (ko)。韩语需要精确 OCR 包以及 balanced 或 best。该包可在官方 Linux amd64 和 arm64 容器上运行；即使是 NVIDIA 主机，OCR 仍使用 CPU。不受支持的系统会返回明确的兼容性错误，绝不会静默回退到 fast。韩语与 fast 或旧版 tesseract 别名的组合会在入队前以 FEATURE_INCOMPATIBLE 和 fast-korean-unsupported 拒绝。

API Endpoint

POST /api/v1/tools/pdf/ocr-pdf

接受包含一个 PDF 文件和一个可选的 JSON settings 字段的 multipart 表单数据。

Parameters

Parameter	Type	Required	Default	Description
file	file	是的	-	PDF 文件（多部分），最多 512 个 MiB 编码；较低的运营商上传限制仍然适用
quality	string	不	动态的	OCR 质量等级：fast、balanced 或 best
language	string	No	"auto"	文档语言：auto、en、de、fr、es、zh、ja、ko
pages	string	No	"all"	页面选择，例如 "all"、"1-3"、"1,3,5"
enhance	boolean	不	取决于层级	提高识别前的局部对比度。快速直接应用；仅当校准评分改善结果时，平衡和最佳才会保留变体。对于 best 默认为 true，对于 fast/balanced 默认为 false
engine	string	不	-	已弃用的兼容性别名。请改用 quality。 tesseract 映射到 fast；旧版 paddleocr 值映射到 balanced 但不加载 PaddlePaddle

省略 quality 和 engine 时，SnapOtter 会按 best、balanced、fast 的顺序选择可用的最高质量层。韩语绝不会选择 fast；它会使用 best，其次是 balanced，否则返回精确运行时的安装或兼容性错误。

Example Request

curl -X POST http://localhost:1349/api/v1/tools/pdf/ocr-pdf \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@scanned.pdf" \
  -F 'settings={"quality": "best", "language": "en", "pages": "1-5", "enhance": true}'

Example Response

返回 202 Accepted。通过 SSE 在 /api/v1/jobs/{jobId}/progress 跟踪进度。

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "async": true
}

Notes

• 接受的输入格式：.pdf。
• 内置fast，并在官方镜像中添加了约25个 MiB。 balanced 和 best 需要可选的精确 OCR 包（大约下载 208-234 MiB 并安装 409-488 MiB，具体取决于目标）。
• 准确包支持 Linux amd64 和 arm64，并在 CPU（包括 NVIDIA 主机）上使用 ONNX Runtime。
• 明确请求的等级绝不会默默降级。如果 balanced 或 best 不可用，则 API 返回 501 和 FEATURE_NOT_INSTALLED 或 FEATURE_INCOMPATIBLE。
• PDF 页面在 OCR 之前以高分辨率进行光栅化。 best 运行更高精度的中型 PP-OCRv6 模型，并对方向和增强变体进行评分，以速度为代价提高识别能力。
• auto 语言设置可以跨支持的脚本集进行识别；明确的提示可以改善已知文档语言的结果。
• 你可以使用范围（"1-3"）、逗号分隔的列表（"1,3,5"）或 "all" 来针对特定页面处理所有页面。
• 一个请求最多可以处理 50 个页面。光栅化暂存数据的上限为 512 MiB，聚合 UTF-8 OCR 响应的上限为 1,000,000 字节；超出限制的作业失败而不是返回部分文本。
• 对于已经包含可选择文本的 PDF，请考虑改用更快的 PDF to Text 工具。