SDK · Python

`ocrqueen` — Python

Typed Python client. Sync + idempotency baked in. Zero configuration after the install.

Install

bash

pip install ocrqueen

Quickstart

python

from ocrqueen import OCRQueen

client = OCRQueen(api_key="pk_test_xxx")
result = client.extract("invoice.pdf")

print(result.markdown)
for block in result.blocks:
    print(block.type, block.text)

That's the whole loop. extract() uploads, asks the server to hold the connection up to 25 seconds (sync mode), and falls back to polling automatically for longer documents.

Environment variables

The client picks up your key from the environment if you don't pass it explicitly — convenient for production and CI:

bash

export OCRQUEEN_API_KEY=pk_live_xxx
# optional — for staging / self-hosted
export OCRQUEEN_BASE_URL=https://api.ocrqueen.com

Idempotent retries

Pass any stable string to make retries safe across queue redelivery, crashes, and network blips:

python

result = client.extract(
    "invoice.pdf",
    idempotency_key="invoice-3034-2026-05-14",
)

See the idempotency reference for the contract.

Fire-and-forget with webhooks

For batch pipelines, swap extract() for submit() — returns immediately with a job handle. We POST the completed result to your webhook URL when done.

python

job = client.submit(
    "invoice.pdf",
    callback_url="https://your-server.com/hooks/ocrqueen",
)
print(job.job_id)

The batch + webhooks cookbook walks through a real receiver with HMAC verification.

Error handling

python

from ocrqueen import (
    RateLimitError,
    InvalidRequestError,
    ExtractionFailed,
)

try:
    result = client.extract("doc.pdf")
except RateLimitError as e:
    time.sleep(e.retry_after or 5)
    # retry
except ExtractionFailed as e:
    print("can't extract:", e.code)  # e.g. "PDF_PASSWORD_PROTECTED"
except InvalidRequestError:
    # Bad input — fix the request, don't retry.
    raise

Full reference

The complete API surface (every method, every option, every exception type) lives in the package README:

github.com/ocrqueen/ocrqueen-python →