Quickstart Code Example

The OCR API takes a file as a raw request body and returns layout-aware text. This page builds up a working client in four steps; the complete script is at the end.

You need an API key. Set it in your environment rather than putting it in code:

$
export OCR_API_KEY='...'

Create a session

Authentication is an API key sent as a bearer token. Putting it on a requests.Session means every call below carries it.

1
import os
2
import requests
3
4
BASE = "https://ocr.emtelligent.com"
5
6
session = requests.Session()
7
session.headers["Authorization"] = f"Bearer {os.environ['OCR_API_KEY']}"

Submit a document

Post the file as the raw request body — not multipart, and not a JSON wrapper. The format is detected from the file’s own bytes, so the Content-Type header is ignored; PDF, PNG, JPEG and TIFF are accepted. X-Filename sets the job’s display name and is optional.

1
with open("report.pdf", "rb") as fp:
2
    response = session.post(
3
        f"{BASE}/jobs",
4
        data=fp,
5
        headers={"X-Filename": "report.pdf"},
6
    )
7
response.raise_for_status()
8
job_id = response.json()["job_id"]

Wait for it to finish

A job moves through queued → rendering → ocr → done, or ends in failed. Poll the status endpoint until it reaches a terminal state.

1
import time
2
3
while True:
4
    status = session.get(f"{BASE}/jobs/{job_id}").json()
5
    if status["state"] in ("done", "failed"):
6
        break
7
    time.sleep(2)
8
9
if status["state"] == "failed":
10
    raise RuntimeError(status.get("error") or "OCR failed")

Read the result

1
result = session.get(f"{BASE}/jobs/{job_id}/result").json()

Results auto-purge after retrieval or a short retention window, so read them once and store what you need. To release the input file and rendered pages immediately:

1
session.delete(f"{BASE}/jobs/{job_id}")

The whole thing

1
import os
2
import time
3
4
import requests
5
6
BASE = "https://ocr.emtelligent.com"
7
8
session = requests.Session()
9
session.headers["Authorization"] = f"Bearer {os.environ['OCR_API_KEY']}"
10
11
12
def ocr(path):
13
    """Submit one file and return its OCR result."""
14
    with open(path, "rb") as fp:
15
        response = session.post(
16
            f"{BASE}/jobs",
17
            data=fp,
18
            headers={"X-Filename": os.path.basename(path)},
19
        )
20
    response.raise_for_status()
21
    job_id = response.json()["job_id"]
22
23
    while True:
24
        status = session.get(f"{BASE}/jobs/{job_id}").json()
25
        if status["state"] in ("done", "failed"):
26
            break
27
        time.sleep(2)
28
29
    if status["state"] == "failed":
30
        raise RuntimeError(status.get("error") or "OCR failed")
31
32
    return session.get(f"{BASE}/jobs/{job_id}/result").json()
33
34
35
if __name__ == "__main__":
36
    print(ocr("report.pdf"))

Next