PDF OCR in Python: Send a PDF to our OCR API With httpx and Get JSON Back
← All posts
GuideNov 16, 2026· 4 min read

PDF OCR in Python: Send a PDF to our OCR API With httpx and Get JSON Back

To OCR a PDF from Python and get JSON back, base64-encode the file into a data URI, POST it as {"document_url": "data:application/pdf;base64,..."} to https://api.ocrskill.com/ocr, and read pages[i].markdown from the response. The only third-party package you need is httpx. The response follows the same shape as the Mistral OCR API, so code written for one works with the other.

Get an API key

A free key is enough for uploads:

export OCRSKILL_API_KEY=$(curl -fsS https://api.ocrskill.com/get-key)

Install httpx if you do not have it:

pip install httpx

The example

Save this as ocr_pdf.py:

import base64
import os
import sys

import httpx

pdf_path = sys.argv[1]
api_key = os.environ["OCRSKILL_API_KEY"]

pdf_bytes = open(pdf_path, "rb").read()
document_url = "data:application/pdf;base64," + base64.b64encode(pdf_bytes).decode()

response = httpx.post(
    "https://api.ocrskill.com/ocr",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"document_url": document_url},
    timeout=120.0,
)
response.raise_for_status()
result = response.json()

print(response.headers.get("x-ocr-pages"))  # processed/total, e.g. "35/35"
for page in result["pages"]:
    print(f"--- page {page['index']} ---")
    print(page["markdown"])

Run it:

python ocr_pdf.py lease-contract.pdf

Passing json= makes httpx set Content-Type: application/json. That header is what tells /ocr to answer in JSON. The timeout is generous because multi-page PDFs take longer than a single image.

The response

{
  "pages": [
    {"index": 0, "markdown": "# Commercial Lease Agreement\n\n| Party | Name |\n...", "images": []},
    {"index": 1, "markdown": "## 1. Premises\n...", "images": []},
    ...
    {"index": 34, "markdown": "## Signatures\n...", "images": []}
  ],
  "model": "...",
  "document_annotation": null,
  "usage_info": {"pages_processed": 35, "doc_size_bytes": 2457812}
}

Each page gets its own Markdown string, with headings and tables preserved. That is handy when you want to keep page numbers for citations, split a long document into chunks for a RAG index, or send only the first page to a classifier.

The X-OCR-Pages header reports pages processed and pages in the input, such as 35/35. If your key has a page limit and the PDF is longer, the two numbers differ, so check it before you treat the output as the whole document.

When you want plain Markdown instead

If you upload the PDF as multipart or raw bytes, /ocr returns the whole document as one plain-text Markdown body instead of JSON:

with open("lease-contract.pdf", "rb") as f:
    response = httpx.post(
        "https://api.ocrskill.com/ocr",
        headers={"Authorization": f"Bearer {api_key}"},
        files={"file": ("lease-contract.pdf", f, "application/pdf")},
        timeout=120.0,
    )
markdown = response.text

Use the JSON form when you need page boundaries, and the multipart form when you just want the text.

Errors worth handling

  • 400: the body is empty, or the file type could not be detected. Check that the data URI starts with data:application/pdf;base64,.
  • 401: the key is invalid or expired. Free keys cannot be renewed, so get a paid key at ocrskill.com.
  • 403: you put an https:// URL in document_url with a free key. Downloading from a URL needs a paid key (see OCR document URLs); uploading the bytes as a data URI works on any key.
  • 504: the upstream OCR timed out. Wait for the number of seconds in the Retry-After header and try again.

The maximum upload is 20 MB. Base64 adds about a third to the size, so a PDF near that limit is better sent as multipart.

Need fields, not text?

If you want specific values such as company_name or signature_date as typed JSON, send the same request to /ocr.json?fields=... instead. The field catalog and the required and optional field syntax are in the OCR JSON API reference.