How does the async flow work?

Send isAsync true. A 200 response carries the JSON result immediately. A 202 response carries a Location header; GET that URL with the same Authorization header. The official samples poll every 10 seconds for up to 20 retries.

转变 PDF 可编辑 PDF 使用 OCR

Q: Is the response the PDF file itself?

No. Unlike some PDF4me conversion endpoints, ConvertOcrPdf returns JSON: a docName field and a docContent field holding the output PDF as a Base64 string. Decode docContent to bytes before saving the file.

Q: What does ocrWhenNeeded do?

Set to the string true, it skips recognition on pages that already have a searchable text layer, saving processing on mixed documents. Set to false, every page is OCR-processed regardless.

PDF4me 转变 PDF 可编辑 PDF 使用 OCR 是一个 REST 进行扫描的端点 PDFs 可搜索和可编辑。 POST 一个 Base64 PDF 到 /api/v2/ConvertOcrPdf选择草稿或高质量，然后 OCR 引擎会将真实的文本层写入文档。响应返回最终结果。 PDF 作为 Base64 JSON准备解码并保存。

此端点的作用

拍摄图像或扫描图像 PDF 返回包含可识别、可选择文本的同一文档。 qualityType 在快速单次扫描和（单次扫描之间切换）之间切换草稿，1 API 按文件调用）和按页面识别（高的，2 API 每页调用次数），而 ocrWhenNeeded 跳过 pages 这些内容已经可以搜索。输出结果以以下形式返回： Base64 docContent 领域中的 JSON 回复，或通过 Location 民意调查 URL 202。

验证您的身份 API 要求

每一个 PDF4me REST 通话必须包含您的 API 关键在于 Authorization 请求头设置为基本身份验证。请从开发者控制面板获取或轮换您的密钥。

Get your API Key

端点

POST/api/v2/ConvertOcrPdf

邮递员 URLhttps://api.pdf4me.com/api/v2/ConvertOcrPdf

您不容错过的重要事实

混合字段类型：字符串和布尔值

ocrWhenNeeded 和 outputFormat 是弦吗？ “真的” / “错误的”，尽管 isAsync 和 mergeAllSheets 是 JSON 布尔值。这与官方代码示例一致；混淆两者是导致 400 错误的常见原因。

回答是 JSON不是原始字节

200 响应携带 docName 加 docContent完成 PDF 作为一个 Base64 字符串解码 docContent 保存前请勿将响应正文原样写入磁盘。

Draft 和 High 的计费方式不同。

草案费用 1 API 按文件调用；成本高昂 2 API 每页调用次数，是专为扫描而设计的模式。保持 ocrWhenNeeded： “真的” 所以已经可以搜索了。 pages 直接跳过，不进行重新处理。

HTTP 设置

方法： POST
URL： https://api.pdf4me.com/api/v2/ConvertOcrPdf
内容类型： application/json
Authorization： 基本 <您的 PDF4me API 键>

发送 isAsync：真的 在体内。 200 返回 JSON 和 Base64 docContent。 202 返回一个 Location 带有投票的标题 URL； GET 那 URL 与 Authorization 直到返回 200 状态码为止 JSON 结果。

如何制作扫描件 PDF 可搜索吗？

扫描件 PDF 只是一些图片 pages没有任何内容可供选择，也没有任何内容与文本搜索匹配。 OCR （光学字符识别，参见）概述如何 OCR 作品它读取每一页图像，并将识别出的单词作为真正的文本层写入文件。转换后，文档的行为就像一个原生数字文档。 PDF搜索、复制和屏幕阅读器都能正常工作，并且可以进行后续步骤，例如 PDF/A 归档或者使用查找和替换功能。

选秀对阵高阶	草稿	高的
最适合	普通的 PDFs 主要包含一个文本层	扫描或图像文档
成本	1 API 每个文件的调用	2 API 每页调用次数
认出	光线通过	每页完整内容 OCR
搭配	`ocrWhenNeeded: "true"` 跳过可搜索内容 pages	`language` 返回的文本乱码

API 身体场

范围	必需的	类型	它的作用	例子
`docContent`	Required	string	Base64-encoded bytes of the source PDF. Strip any data:application/pdf;base64, prefix before posting.	`JVBERi0xLjcK...`
`docName`	Required	string	Source filename including the .pdf extension. Used for the output docName.	`scanned-contract.pdf`
`qualityType`	Required	string	Draft for normal PDFs (1 API call per file). High for scanned documents (2 API calls per page).	`High`
`ocrWhenNeeded`	Required	string	The string "true" skips pages that already have a searchable text layer; "false" forces OCR on every page.	`"true"`
`outputFormat`	Required	string	Output format flag, sent as the string "true" in the official samples.	`"true"`
`language`	Conditional	string	Language of the source text (English, Spanish, French, German, and others). Set only when the recognized output is garbled; otherwise let the engine detect it.	`English`
`mergeAllSheets`	Optional	boolean	JSON boolean carried by the official samples; relevant to sheet-based sources.	`true`
`isAsync`	Optional	boolean	true enables the 202 + Location polling pattern, recommended for large scans.	`true`

示例有效载荷

高模式。扫描文档 OCR

{
 "docContent": "JVBERi0xLjcKJcfsj6IKNSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZw...",
 "docName": "scanned-contract.pdf",
 "qualityType": "High",
 "ocrWhenNeeded": "true",
 "language": "English",
 "outputFormat": "true",
 "isAsync": true
}

草稿模式。混合文档，跳过可搜索文档 pages

{
 "docContent": "JVBERi0xLjcKJcfsj6IKNSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZw...",
 "docName": "mixed-report.pdf",
 "qualityType": "Draft",
 "ocrWhenNeeded": "true",
 "outputFormat": "true",
 "isAsync": true
}

邮递员收款小贴士

Headers

Content-Type: application/json + Authorization: Basic <apiKey>.

Body

raw JSON. Copy a payload above and replace docContent with your Base64. Keep the quotes around "true" for ocrWhenNeeded and outputFormat.

Response

The 200 body is JSON. Copy the docContent value and Base64-decode it to get the PDF. If 202, GET the Location URL with the same Authorization until 200.

Quality

Use High for scans and expect 2 API calls per page. Draft is enough when most pages already have selectable text.

curl 示例

curl -X POST https://api.pdf4me.com/api/v2/ConvertOcrPdf \
 -H "Content-Type: application/json" \
 -H "Authorization: Basic YOUR_API_KEY" \
 -d '{
 "docContent": "'"$(base64 -w 0 scanned-contract.pdf)"'",
 "docName": "scanned-contract.pdf",
 "qualityType": "High",
 "ocrWhenNeeded": "true",
 "outputFormat": "true",
 "isAsync": true
 }' | python -c "import sys, json, base64; open('searchable.pdf','wb').write(base64.b64decode(json.load(sys.stdin)['docContent']))"

什么 API 返回？

JSON不是原始文件字节。解码 docContent 进入该领域以获得最终成果 PDF。

场地	类型	它包含什么
docName (HTTP 200)	String	The output PDF filename, derived from the docName you sent.
docContent (HTTP 200)	String (Base64)	The searchable, editable PDF encoded as Base64. Decode to bytes and save with a .pdf extension.
Location header (HTTP 202)	String (URL)	Poll URL for an async job that is still running. GET it with the same Authorization header; the official samples poll every 10 seconds, up to 20 retries.
Poll response (HTTP 200)	JSON	The same docName + docContent JSON, returned once processing completes.

代码示例

完成端到端的实现，每个实现都附带一个扫描样本。 PDF 以及此页面的确切有效载荷：

常问问题

How do you make a scanned PDF searchable?+

Run it through OCR. POST the Base64 PDF to /api/v2/ConvertOcrPdf with qualityType High and ocrWhenNeeded "true"; the engine recognizes the text on each scanned page and writes a searchable, selectable text layer into the returned PDF.

Is the response the PDF file itself?+

No. ConvertOcrPdf returns JSON: a docName field and a docContent field holding the output PDF as a Base64 string. Decode docContent to bytes before saving the file.

What does ocrWhenNeeded do?+

Set to the string "true", it skips recognition on pages that already have a searchable text layer, saving processing on mixed documents. Set to "false", every page is OCR-processed regardless.

Which quality mode should I use, Draft or High?+

Draft costs 1 API call per file and suits normal PDFs. High costs 2 API calls per page and is built for scanned documents where every page needs recognition. Use High whenever the source is a scan or photo.

Why are some fields strings and others booleans?+

That is the contract the official code samples ship: ocrWhenNeeded and outputFormat are the strings "true" or "false", while isAsync and mergeAllSheets are JSON booleans. Sending the wrong type is a common cause of 400 errors.

The recognized text is garbled. What now?+

Set the language field to match the document (English, Spanish, French, German, and others) and rerun. Language only needs to be set when automatic detection gets it wrong.

Does OCR change how the pages look?+

No. The text layer is added behind the page image, so the visual appearance stays identical while search, selection, and copy start working.

Can I OCR a PDF and then extract its tables to Excel?+

Yes, but you do not need two calls: the Convert PDF to Excel endpoint runs OCR itself when you set its qualityType to High. Use ConvertOcrPdf when the deliverable should stay a PDF.