HTTP clients¶

Client and AsyncClient share an identical method surface — anything you can do with one, you can await with the other.

Construct either directly with base_url, from env vars with Client.from_env(), or pass a pre-built httpx.Client via http_client=. The introspection properties (.base_url, .auth_scheme, .default_headers, .timeout, .retry) read back the resolved config.

`Client`¶

Client ¶

Client(*, base_url: str | None = None, api_key: str | None = None, auth_scheme: AuthScheme = 'bearer', timeout: float = DEFAULT_TIMEOUT, default_headers: Mapping[str, str] | None = None, retry: RetryPolicy | None = None, transport: BaseTransport | None = None, http_client: Client | None = None, limits: Limits | None = None, on_request: SyncRequestHook | None = None, on_response: SyncResponseHook | None = None)

Bases: _BaseClient

Synchronous HTTP client for the Turbo-OCR server.

Holds a pooled httpx.Client and the auth / retry configuration used by every request method. Prefer instantiating with with Client(...) as client: so the underlying connection pool is closed deterministically.

Build a Client and (unless http_client is supplied) its httpx.Client.

PARAMETER	DESCRIPTION
`base_url`	Server origin, e.g. `"https://ocr.example.com"`. Falls back to the `TURBO_OCR_BASE_URL` env var, and finally to `"http://localhost:8000"` when both are absent. TYPE: `str \| None` DEFAULT: `None`
`api_key`	Secret used for bearer auth (or `X-API-Key` when `auth_scheme="x-api-key"`). Falls back to the `TURBO_OCR_API_KEY` env var. May be `None` for unauthenticated deployments. TYPE: `str \| None` DEFAULT: `None`
`auth_scheme`	`"bearer"` (default) sends `Authorization: Bearer <key>`; `"x-api-key"` sends an `X-API-Key` header. May also be a custom callable `(api_key) -> (header_name, header_value)` for non-standard schemes. TYPE: `AuthScheme` DEFAULT: `'bearer'`
`timeout`	Per-request timeout in seconds, applied to the underlying `httpx.Client`. Overridable per call via the `timeout=` kwarg on each `recognize_` method. TYPE:* `float` DEFAULT: `DEFAULT_TIMEOUT`
`default_headers`	Extra headers merged into every request (e.g. tenant tags, trace IDs). Authorization headers derived from `api_key`/`auth_scheme` win on conflict. TYPE: `Mapping[str, str] \| None` DEFAULT: `None`
`retry`	`RetryPolicy` for transient failures. Defaults to `RetryPolicy()` (3 attempts, 0.25s base backoff with jitter, retrying 429/502/503/504). TYPE: `RetryPolicy \| None` DEFAULT: `None`
`transport`	Optional `httpx.BaseTransport` to swap in — useful for `httpx.MockTransport` in tests. Ignored when `http_client` is also passed. TYPE: `BaseTransport \| None` DEFAULT: `None`
`http_client`	Pre-configured `httpx.Client` to reuse instead of letting `Client` build its own. When supplied, `transport`, `limits`, `on_request`, `on_response`, and the auth/header kwargs only affect the auth dict used per request — the provided client's own headers/transport are respected as-is. TYPE: `Client \| None` DEFAULT: `None`
`limits`	Connection pool sizing. Defaults to `max_connections=100`, `max_keepalive_connections=20`, `keepalive_expiry=15.0s`. TYPE: `Limits \| None` DEFAULT: `None`
`on_request`	Synchronous hook `(httpx.Request) -> None` invoked before each request is sent. Use for trace propagation or logging. TYPE: `SyncRequestHook \| None` DEFAULT: `None`
`on_response`	Synchronous hook `(httpx.Response) -> None` invoked after each response is received. TYPE: `SyncResponseHook \| None` DEFAULT: `None`

RAISES	DESCRIPTION
`InvalidParameter`	If `auth_scheme` is unrecognised when `api_key` is present.

METHOD	DESCRIPTION
`from_env`	Construct a `Client` driven by `TURBO_OCR_BASE_URL` / `TURBO_OCR_API_KEY` env vars.
`close`	Close the underlying HTTP session. Use the context manager when possible.
`recognize_image`	OCR a single image and return text plus optional layout structure.
`recognize_base64`	OCR an image whose bytes are already base64-encoded.
`recognize_pixels`	OCR a raw RGB/RGBA pixel buffer, skipping image-decode on both ends.
`recognize_batch`	OCR multiple images in a single round-trip.
`recognize_pdf`	OCR every page of a PDF.
`health`	Probe the server's health endpoints.
`make_searchable_pdf`	Return a PDF with an invisible OCR text layer.
`to_markdown`	One-call OCR + layout + reading-order + blocks → Markdown.

from_env `classmethod` ¶

from_env(**overrides: Unpack[_ClientKwargs]) -> Self

Construct a Client driven by TURBO_OCR_BASE_URL / TURBO_OCR_API_KEY env vars.

Plain Client() already reads those env vars when the corresponding kwarg is None. This factory exists for callers who want the env-aware origin to be explicit in their code. Pass keyword overrides to take precedence over the env values.

close ¶

close() -> None

Close the underlying HTTP session. Use the context manager when possible.

recognize_image ¶

recognize_image(image: ImageInput, *, layout: BoolParam = None, reading_order: BoolParam = None, include_blocks: BoolParam = None, timeout: float | None = None) -> OcrResponse

OCR a single image and return text plus optional layout structure.

Accepts the broadest possible set of image-shaped inputs: file paths (str / Path), in-memory bytes, file-like objects with .read(), numpy arrays, and PIL Image instances. The bytes are POSTed as multipart/form-data; image decoding happens server-side.

PARAMETER	DESCRIPTION
`image`	The image to recognize. See `ImageInput` for the accepted types. TYPE: `ImageInput`
`layout`	Pass `True` to have the server return region classifications (titles, paragraphs, tables, formulas, …) on `OcrResponse.layout`. Defaults to the server's default when `None`. TYPE: `BoolParam` DEFAULT: `None`
`reading_order`	Pass `True` to receive a `reading_order` list of indices into `results` giving human reading order. Requires `layout` (implicitly enabled server-side). TYPE: `BoolParam` DEFAULT: `None`
`include_blocks`	Pass `True` for paragraph-level blocks with their reading order on `OcrResponse.blocks` (and synthesises `.tables` / `.formulas`). TYPE: `BoolParam` DEFAULT: `None`
`timeout`	Per-request timeout override in seconds. `None` uses the client-level `timeout`. TYPE: `float \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`OcrResponse`	An `OcrResponse` with `.results` (token
`OcrResponse`	boxes), plus `.layout`, `.reading_order`, `.blocks`, `.tables`,
`OcrResponse`	and `.formulas` when requested.

RAISES	DESCRIPTION
`InvalidParameter`	Malformed input (e.g. unsupported image format, missing file).
`ImageDecodeError`	The server could not decode the bytes as an image.
`DimensionsTooLarge`	Image exceeds the server's pixel budget.
`APIConnectionError`	Network failure, timeout, or unparseable response after the retry policy is exhausted.
`ServerError`	5xx response that is not retryable.

Example

from turboocr import Client

with Client(base_url="http://localhost:8000") as client:
    response = client.recognize_image(
        "invoice.png", layout=True, reading_order=True
    )
    print(response.text)
    for table in response.tables:
        print(table.text)

recognize_base64 ¶

recognize_base64(b64: str, *, layout: BoolParam = None, reading_order: BoolParam = None, include_blocks: BoolParam = None, timeout: float | None = None) -> OcrResponse

OCR an image whose bytes are already base64-encoded.

Useful when the image arrived over a JSON wire and you'd rather not round-trip through b64decode just to hand it back to the SDK.

PARAMETER	DESCRIPTION
`b64`	Base64-encoded image bytes (the raw payload — no `"data:image/..."` URI prefix). TYPE: `str`
`layout`	Same semantics as `recognize_image`. TYPE: `BoolParam` DEFAULT: `None`
`reading_order`	Same semantics as `recognize_image`. TYPE: `BoolParam` DEFAULT: `None`
`include_blocks`	Same semantics as `recognize_image`. TYPE: `BoolParam` DEFAULT: `None`
`timeout`	Per-request timeout override in seconds. TYPE: `float \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`OcrResponse`	An `OcrResponse`, identical in shape to
`OcrResponse`	what `recognize_image`
`OcrResponse`	returns.

RAISES	DESCRIPTION
`InvalidParameter`	Malformed or non-base64 input.
`ImageDecodeError`	Decoded bytes are not a valid image.
`APIConnectionError`	Network failure, timeout, or unparseable response.
`ServerError`	5xx response.

recognize_pixels ¶

recognize_pixels(pixels: ImageInput, *, width: int, height: int, channels: int = 3, layout: BoolParam = None, reading_order: BoolParam = None, include_blocks: BoolParam = None, timeout: float | None = None) -> OcrResponse

OCR a raw RGB/RGBA pixel buffer, skipping image-decode on both ends.

The server's JPEG/PNG decoder is bypassed, which removes ~5-15 ms per request for pipelines that already hold uncompressed pixels.

PARAMETER	DESCRIPTION
`pixels`	Raw pixel buffer. Pass `bytes` directly, or anything `ImageInput` accepts (numpy `.tobytes()`, PIL `Image.tobytes()`, …). TYPE: `ImageInput`
`width`	Image width in pixels. Must match the buffer's row stride. TYPE: `int`
`height`	Image height in pixels. TYPE: `int`
`channels`	Number of channels per pixel — `3` for RGB (default), `4` for RGBA. Other values are rejected by the server. TYPE: `int` DEFAULT: `3`
`layout`	Same semantics as `recognize_image`. TYPE: `BoolParam` DEFAULT: `None`
`reading_order`	Same semantics as `recognize_image`. TYPE: `BoolParam` DEFAULT: `None`
`include_blocks`	Same semantics as `recognize_image`. TYPE: `BoolParam` DEFAULT: `None`
`timeout`	Per-request timeout override in seconds. TYPE: `float \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`OcrResponse`	An `OcrResponse`.

RAISES	DESCRIPTION
`InvalidParameter`	Dimensions or channel count are invalid, or `width * height * channels` does not match the buffer length.
`DimensionsTooLarge`	Image exceeds the server's pixel budget.
`APIConnectionError`	Network failure or timeout.
`ServerError`	5xx response.

recognize_batch ¶

recognize_batch(images: Iterable[ImageInput], *, layout: BoolParam = None, reading_order: BoolParam = None, include_blocks: BoolParam = None, timeout: float | None = None) -> BatchResponse

OCR multiple images in a single round-trip.

Per-slot failures are surfaced on BatchResponse.errors (a parallel list[str | None]) so one bad input never fails the whole batch.

PARAMETER	DESCRIPTION
`images`	Iterable of image inputs (mixed types are fine — paths, bytes, file-like objects, numpy arrays, PIL images may all appear in the same batch). TYPE: `Iterable[ImageInput]`
`layout`	Applied uniformly to every image. Same semantics as `recognize_image`. TYPE: `BoolParam` DEFAULT: `None`
`reading_order`	Applied uniformly to every image. TYPE: `BoolParam` DEFAULT: `None`
`include_blocks`	Applied uniformly to every image. TYPE: `BoolParam` DEFAULT: `None`
`timeout`	Per-request timeout override in seconds. TYPE: `float \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`BatchResponse`	A `BatchResponse` whose
`BatchResponse`	`batch_results` and `errors` lists are parallel and the same
`BatchResponse`	length as `images`. Prefer
`BatchResponse`	`BatchResponse.iter_results`
`BatchResponse`	for tagged `BatchSuccess` / `BatchFailure` iteration instead of
`BatchResponse`	zipping the two lists by hand.

RAISES	DESCRIPTION
`ValueError`	Empty input. The server rejects empty batches — feed at least one image, or skip the call entirely.
`APIConnectionError`	Network failure or timeout on the round-trip itself (per-slot decode failures land in `errors`, not as exceptions).
`ServerError`	5xx response.

Example

from turboocr import Client

with Client() as client:
    batch = client.recognize_batch(["a.png", "b.png", "c.png"])
    for result in batch.iter_results():
        if isinstance(result, BatchSuccess):
            print(result.index, result.response.text)
        else:
            print(result.index, "failed:", result.error)

recognize_pdf ¶

recognize_pdf(pdf: ImageInput, *, dpi: int = 150, mode: PdfMode | str | None = None, layout: BoolParam = None, reading_order: BoolParam = None, include_blocks: BoolParam = None, timeout: float | None = None) -> PdfResponse

OCR every page of a PDF.

PARAMETER	DESCRIPTION
`pdf`	PDF bytes, path, or file-like object. See `ImageInput`. TYPE: `ImageInput`
`dpi`	Server-side rasterization DPI (default `150`). Increase to `200`-`300` for tiny text; higher values cost proportionally more compute. TYPE: `int` DEFAULT: `150`
`mode`	PDF reader strategy. One of: `"ocr"` — re-OCR every page, ignoring any embedded text. `"text"` — use the embedded text layer verbatim; no OCR. `"auto"` — server decides per page based on whether a text layer exists. `"auto_verified"` — like `"auto"` but cross-checks the text layer against OCR and falls back to OCR when they disagree. `"geometric"` — skip text recognition and recover only layout / reading order. `None` defers to the server default (currently `"auto"`). Accepts either the `PdfMode` enum or a plain string. TYPE: `PdfMode \| str \| None` DEFAULT: `None`
`layout`	Per-page layout. Same semantics as `recognize_image`. TYPE: `BoolParam` DEFAULT: `None`
`reading_order`	Per-page reading order. TYPE: `BoolParam` DEFAULT: `None`
`include_blocks`	Per-page block grouping. TYPE: `BoolParam` DEFAULT: `None`
`timeout`	Per-request timeout override in seconds. TYPE: `float \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`PdfResponse`	A `PdfResponse` with one
`PdfResponse`	`PdfPage` per input page and a flattened
`PdfResponse`	`.text` joiner.

RAISES	DESCRIPTION
`InvalidParameter`	`mode` is not a valid `PdfMode`, or `dpi` is out of the server's accepted range.
`PdfRenderError`	Server failed to rasterize the PDF (corrupt file, encrypted without a password, etc.).
`APIConnectionError`	Network failure or timeout.
`ServerError`	5xx response.

Example

from turboocr import Client

with Client() as client:
    response = client.recognize_pdf(
        "report.pdf", dpi=200, mode="auto_verified"
    )
    for page in response.pages:
        print(page.page, page.text_layer_quality)

health ¶

health(*, ready: bool = False, live: bool = False) -> HealthStatus

Probe the server's health endpoints.

PARAMETER	DESCRIPTION
`ready`	Hit `/readyz` instead of `/healthz`. `/readyz` additionally requires the pipeline pool to be initialised and the GPU engines loaded. TYPE: `bool` DEFAULT: `False`
`live`	Hit `/livez` instead of `/healthz`. `/livez` is the cheapest probe — it returns 200 as long as the process is up. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`HealthStatus`	A `HealthStatus` carrying the HTTP
`HealthStatus`	status code, raw body, and (when JSON) the parsed body.

RAISES	DESCRIPTION
`InvalidParameter`	Both `ready` and `live` are `True`.
`APIConnectionError`	Network failure or timeout (note: HTTP errors are reflected as `status_code` / `ok=False`, not exceptions).

make_searchable_pdf ¶

make_searchable_pdf(source: ImageInput, *, dpi: int = 200, mode: PdfMode | str | None = None, font_path: str | None = None) -> bytes

Return a PDF with an invisible OCR text layer.

Accepts a PDF or a single-page image. Tested input formats: PDF, PNG, JPEG, BMP, TIFF, GIF, WebP. The SDK detects format from the first bytes and dispatches to recognize_pdf or recognize_image accordingly, wrapping the image into a one-page PDF when needed.

Output is visually identical to the input; the text is selectable, copyable, and full-text-searchable in every viewer. The bundled glyphless font covers every Basic Multilingual Plane codepoint so non-Latin scans (CJK, Arabic, Cyrillic, …) work with no font setup.

PARAMETER	DESCRIPTION
`source`	PDF or image bytes / path / file-like object. See `ImageInput`. TYPE: `ImageInput`
`dpi`	Rasterization DPI for PDF inputs and the page dimension used when wrapping an image input (default `200`). TYPE: `int` DEFAULT: `200`
`mode`	PDF reader strategy; see `recognize_pdf`. Ignored for image inputs. `None` uses the server default. TYPE: `PdfMode \| str \| None` DEFAULT: `None`
`font_path`	Absolute path to a custom `.ttf`/`.otf` to use instead of the bundled glyphless font. Only useful if you specifically want a visible-text overlay. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`bytes`	The output PDF as `bytes`, ready to write to disk or stream.

RAISES	DESCRIPTION
`FontGlyphMissing`	Only when you pass a `font_path` to a font that lacks glyphs for some of the OCR text. The default code path never raises this.
`PdfRenderError`	Server failed to rasterize the PDF.
`APIConnectionError`	Network failure or timeout on the underlying recognise call.
`ServerError`	5xx response.

to_markdown ¶

to_markdown(image_or_pdf: ImageInput, *, dpi: int = 150, mode: PdfMode | str | None = None, style: MarkdownStyle | None = None, timeout: float | None = None) -> MarkdownDocument

One-call OCR + layout + reading-order + blocks → Markdown.

Detects PDF vs image by the magic bytes b"%PDF-", then calls recognize_pdf or recognize_image with include_blocks=True and pipes the response through render_to_markdown.

PARAMETER	DESCRIPTION
`image_or_pdf`	Image or PDF input. See `ImageInput`. TYPE: `ImageInput`
`dpi`	Rasterization DPI for the PDF branch (default `150`). Ignored for images. TYPE: `int` DEFAULT: `150`
`mode`	PDF reader strategy for the PDF branch; see `recognize_pdf`. Ignored for images. TYPE: `PdfMode \| str \| None` DEFAULT: `None`
`style`	`MarkdownStyle` controlling label-to-node mapping and per-kind renderers. `None` uses `DEFAULT_STYLE`. TYPE: `MarkdownStyle \| None` DEFAULT: `None`
`timeout`	Per-request timeout override in seconds. TYPE: `float \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`MarkdownDocument`	A `MarkdownDocument` with the
`MarkdownDocument`	rendered `.markdown` string and the structured `.nodes` list.

RAISES	DESCRIPTION
`ProtocolError`	Server returned a layout-enabled response with inconsistent IDs (text item missing `layout_id`, dangling reference to a layout box).
`InvalidParameter`	Underlying recognise call rejected the input.
`APIConnectionError`	Network failure or timeout.
`ServerError`	5xx response.

`AsyncClient`¶

AsyncClient ¶

AsyncClient(*, base_url: str | None = None, api_key: str | None = None, auth_scheme: AuthScheme = 'bearer', timeout: float = DEFAULT_TIMEOUT, default_headers: Mapping[str, str] | None = None, retry: RetryPolicy | None = None, transport: AsyncBaseTransport | None = None, http_client: AsyncClient | None = None, limits: Limits | None = None, on_request: AsyncRequestHook | None = None, on_response: AsyncResponseHook | None = None)

Bases: _BaseClient

Asynchronous HTTP client for the Turbo-OCR server.

Mirror of Client over httpx.AsyncClient. Every request method is the awaitable counterpart of the sync one; see the Client method for full docs.

METHOD	DESCRIPTION
`from_env`	Async equivalent of `Client.from_env`.
`aclose`	Close the underlying async HTTP session. Prefer `async with` over this.
`recognize_image`	Async equivalent of `Client.recognize_image`.
`recognize_base64`	Async equivalent of `Client.recognize_base64`.
`recognize_pixels`	Async equivalent of `Client.recognize_pixels`.
`recognize_batch`	Async equivalent of `Client.recognize_batch`.
`recognize_pdf`	Async equivalent of `Client.recognize_pdf`.
`health`	Async equivalent of `Client.health`.
`make_searchable_pdf`	Async equivalent of
`to_markdown`	Async equivalent of `Client.to_markdown`.

from_env `classmethod` ¶

from_env(**overrides: Unpack[_AsyncClientKwargs]) -> Self

Async equivalent of Client.from_env.

aclose `async` ¶

aclose() -> None

Close the underlying async HTTP session. Prefer async with over this.

recognize_image `async` ¶

recognize_image(image: ImageInput, *, layout: BoolParam = None, reading_order: BoolParam = None, include_blocks: BoolParam = None, timeout: float | None = None) -> OcrResponse

Async equivalent of Client.recognize_image.

recognize_base64 `async` ¶

recognize_base64(b64: str, *, layout: BoolParam = None, reading_order: BoolParam = None, include_blocks: BoolParam = None, timeout: float | None = None) -> OcrResponse

Async equivalent of Client.recognize_base64.

recognize_pixels `async` ¶

recognize_pixels(pixels: ImageInput, *, width: int, height: int, channels: int = 3, layout: BoolParam = None, reading_order: BoolParam = None, include_blocks: BoolParam = None, timeout: float | None = None) -> OcrResponse

Async equivalent of Client.recognize_pixels.

recognize_batch `async` ¶

recognize_batch(images: Iterable[ImageInput], *, layout: BoolParam = None, reading_order: BoolParam = None, include_blocks: BoolParam = None, timeout: float | None = None) -> BatchResponse

Async equivalent of Client.recognize_batch.

recognize_pdf `async` ¶

recognize_pdf(pdf: ImageInput, *, dpi: int = 150, mode: PdfMode | str | None = None, layout: BoolParam = None, reading_order: BoolParam = None, include_blocks: BoolParam = None, timeout: float | None = None) -> PdfResponse

Async equivalent of Client.recognize_pdf.

health `async` ¶

health(*, ready: bool = False, live: bool = False) -> HealthStatus

Async equivalent of Client.health.

make_searchable_pdf `async` ¶

make_searchable_pdf(source: ImageInput, *, dpi: int = 200, mode: PdfMode | str | None = None, font_path: str | None = None) -> bytes

Async equivalent of Client.make_searchable_pdf.

to_markdown `async` ¶

to_markdown(image_or_pdf: ImageInput, *, dpi: int = 150, mode: PdfMode | str | None = None, style: MarkdownStyle | None = None, timeout: float | None = None) -> MarkdownDocument

Async equivalent of Client.to_markdown.

HTTP clients¶

Client¶

Client ¶

from_env classmethod ¶

close ¶

recognize_image ¶

recognize_base64 ¶

recognize_pixels ¶

recognize_batch ¶

recognize_pdf ¶

health ¶

make_searchable_pdf ¶

to_markdown ¶

AsyncClient¶

AsyncClient ¶

from_env classmethod ¶

aclose async ¶

recognize_image async ¶

recognize_base64 async ¶

recognize_pixels async ¶

recognize_batch async ¶

recognize_pdf async ¶

health async ¶

make_searchable_pdf async ¶

to_markdown async ¶

`Client`¶

from_env `classmethod` ¶

`AsyncClient`¶

from_env `classmethod` ¶

aclose `async` ¶

recognize_image `async` ¶

recognize_base64 `async` ¶

recognize_pixels `async` ¶

recognize_batch `async` ¶

recognize_pdf `async` ¶

health `async` ¶

make_searchable_pdf `async` ¶

to_markdown `async` ¶