A Tesseract OCR API in 53 lines, no key needed

# A small Tesseract OCR REST API: POST a page image, get its text back.
# Run: python3 server.py
# Try: curl --data-binary @page.png "localhost:8884/?lang=eng"
import hmac
import os
import subprocess
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from urllib.parse import parse_qs, urlparse

TOKEN = os.environ.get("OCR_TOKEN", "")  # set one before it goes online
MAX_BYTES = 20 * 1024 * 1024
listed = subprocess.run(["tesseract", "--list-langs"],
                        capture_output=True, text=True).stdout
LANGS = set(listed.split("\n")[1:]) - {""}


class OCR(BaseHTTPRequestHandler):
    protocol_version = "HTTP/1.1"  # so curl gets "100 Continue" at once

    def do_POST(self):
        size = self.headers.get("Content-Length", "")
        if not size.isdigit() or not 0 < int(size) <= MAX_BYTES:
            self.close_connection = True  # the body was not read
            return self.reply(413, "Send one image of up to 20 MB\n")
        page = self.rfile.read(int(size))
        auth = self.headers.get("Authorization", "")
        if TOKEN and not hmac.compare_digest(auth, f"Bearer {TOKEN}"):
            return self.reply(401, "Send Authorization: Bearer <token>\n")
        query = parse_qs(urlparse(self.path).query)
        lang = query.get("lang", ["eng"])[0].replace(" ", "+")  # a + in a URL means space
        if not all(code in LANGS for code in lang.split("+")):
            return self.reply(400, f"Languages: {' '.join(sorted(LANGS))}\n")
        try:
            run = subprocess.run(["tesseract", "stdin", "stdout", "-l", lang],
                                 input=page, capture_output=True, timeout=120)
        except subprocess.TimeoutExpired:
            return self.reply(504, "Took over 120 seconds\n")
        if run.returncode:
            return self.reply(422, "Tesseract could not read that file\n")
        self.reply(200, run.stdout.decode())

    def reply(self, code, text):
        body = text.encode()
        self.send_response(code)
        self.send_header("Content-Type", "text/plain; charset=utf-8")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)


host = os.environ.get("HOST", "127.0.0.1")
port = int(os.environ.get("PORT", "8884"))
ThreadingHTTPServer((host, port), OCR).serve_forever()

No. Tesseract is free software that you run, under the Apache 2.0 license. Only a hosted service, like ours, asks for a key.

The C and C++ API is in libtesseract. Start with the API examples page in the Tesseract docs, then the headers capi.h and baseapi.h.

No. Tesseract does not read PDF files, so the server answers 422. Turn each page into an image first, or send the PDF to our Actor.

• Pages: 55 printed pages from 11 public domain books on Wikisource, as JPEGs 1,920 px wide. I left out one hand-lettered book.
• Truth: each page's proofread text. A word counts if the output holds it, in any order.
• "Matched" means the SHA-256 of the output was the same.
• Speed: one run each on an Apple M5 Max with other jobs running, so read it as rough.
• The server and Docker commands ran as printed, with a test token.

• Ready-made Tesseract server images from Docker Hub.
• Windows, servers on the open internet, and the 120 second timeout.
• Phone photos, handwriting, and languages other than English.
• Hosted OCR APIs other than ours.

• Mac: Tesseract 5.5.3 from Homebrew.
• Docker 29.8.2: Debian 13, Tesseract 5.5.0, Python 3.13.5.
• Tesseract README, for the library and the command.
• Tesseract FAQ, for OMP_THREAD_LIMIT.