hexread

hexread is the official Python client for HexRead - convert PDFs and images to Markdown. It is a thin API client: it talks to the HexRead API at https://api.hexread.com/v1 and never processes documents locally.

API access requires a paid HexRead plan. The free trial is web only, so no API key can be issued for it. Keys are created and revoked in your HexRead dashboard.

Install

pip install hexread

Python 3.10+. The only runtime dependency is httpx.

Quick start

import hexread

res = hexread.convert("report.pdf")  # -> ConvertResult
print(res)                           # str(res) is res.markdown

Use a client when you want metadata, several files, or a custom timeout:

from hexread import HexRead

client = HexRead()  # key from the argument, the environment, or the CLI credential
res = client.convert("report.pdf", progress=True)

print(res.model, res.route_reason, res.pages_remaining)
for page in res.pages:
    print(page.index, page.markdown[:80])

for res in client.convert_many(["a.pdf", "b.png"], max_workers=2):
    print(res)  # str(res) is res.markdown; a failed file yields the exception

print(client.usage().pages_remaining)

AsyncHexRead has the same surface with await:

import asyncio
from hexread import AsyncHexRead

async def main():
    async with AsyncHexRead() as client:
        res = await client.convert("report.pdf")
        print(res.markdown)

asyncio.run(main())

Options

Naming a model requires a plan that allows it; auto is always allowed. client.usage().available_models lists the ones you may request.

The result object

convert() returns a ConvertResult:

Account meters come from client.usage():

u = client.usage()

u.tier                # your plan
u.pages_used          # pages converted in the current window
u.pages_remaining     # pages left before the cap
u.pages_allowance     # the window's allowance
u.concurrency_limit   # conversions this plan may run at once
u.api_access          # True on a plan that may call the API
u.available_models    # models you may request explicitly
u.resets_at           # when the window rolls over

Credentials

Resolved in this order; the first one found wins.

Errors

Every exception subclasses HexReadError and carries .message, .status, .type, .code, .request_id and .retry_after. The class is keyed on the API's error type, not the HTTP status.

MissingAPIKeyError subclasses AuthenticationError, so one except covers both. hexread.PermissionError shadows the builtin inside from hexread import *; import the module or alias it if that matters to you.

One more class covers a rare case: ResultDeliveryError means a result was fetched but could not be handed back (a disk write failed, say). It carries the text on .markdown, because a result is delivered once and the API cannot serve it again.

Related packages

License

Licensed under the MIT License, © HexWorld Solutions GmbH.

The HexRead service and its documentation live at hexread.com; this repository contains the open-source client only.