Skip to navigation
CapabilitiesParsing

Embed OCR in PDF

Parse can embed recognized words as an invisible text layer in a PDF, making scanned pages searchable and allowing text selection and copying while preserving their appearance. Enable advancedOptions.embedOcrInPdf to use this feature; it defaults to false.

Via the API

Enable embedding and retrieve the PDF

Create a parse run with this configuration:

{
  "file": { "id": "file_Xj8mK2pL9nR4vT7qY5wZ" },
  "config": {
    "advancedOptions": {
      "embedOcrInPdf": true
    }
  }
}

Wait for status: "PROCESSED", then retrieve the file using the completed run’s file.id. The file’s presignedUrl downloads the processed PDF and expires after 15 minutes. Retrieve the file again to get a fresh URL.

Set EXTEND_API_KEY before running these examples. Python, TypeScript, and Java send the embedOcrInPdf wire field through SDK support for additional properties. The Go example creates the run over HTTP, then uses the SDK to poll and retrieve the file, so it also works before the Go SDK exposes a typed field for this option.

from extend_ai import Extend, ParseConfig, ParseConfigAdvancedOptions
client = Extend()
advanced_options = ParseConfigAdvancedOptions(**{"embedOcrInPdf": True})
run = client.parse_runs.create_and_poll(
    file={"id": "file_Xj8mK2pL9nR4vT7qY5wZ"},
    config=ParseConfig(advanced_options=advanced_options),
)
if run.status != "PROCESSED":
    raise RuntimeError(f"Parse ended with status {run.status}")
processed_file = client.files.retrieve(run.file.id)
if not processed_file.presigned_url:
    raise RuntimeError("The file has no download URL")
print(processed_file.presigned_url)

outputUrl is a download URL for the parsed JSON, not the PDF. The PDF download URL is presignedUrl on the Get File response; it is not included in the parse run’s file summary.

What gets embedded

  • Pages without existing text: recognized OCR words are added as an invisible text layer. Pages with no usable OCR words receive no text layer.
  • Pages with existing text: the entire page is skipped, including pages that mix existing text with scanned regions. Existing text layers are preserved rather than replaced or corrected.
  • Selected pages: if you set advancedOptions.pageRanges, only processed pages are candidates for embedding.
  • PDF conversion: embedding applies to PDFs, including supported inputs converted to PDF before parsing with advancedOptions.alwaysConvertToPdf.

Embedding is independent of advancedOptions.returnOcr.words and advancedOptions.returnOcr.lines. Leave both disabled if you only need a searchable PDF; enable them separately if you also need OCR coordinates in the JSON response.

Via Extend Studio

  1. Open the parser in Extend Studio and select a document.
  2. In the parser configuration, expand Output & Structure and enable Embed OCR in PDF.
  3. Run the parser. The processed PDF supports search, text selection, and copying on pages where OCR text was embedded.

When OCR text was embedded, the document viewer displays a message explaining the change. Download Original retrieves the original document.

Reference