Response models

All response objects are immutable pydantic v2 models with extra="allow" — additive server changes survive a SDK version skew by landing on .model_extra instead of failing parse.

OcrResponse

Returned by recognize_image() and recognize_pixels().

OcrResponse

Bases: _Frozen

Single-image OCR result returned by recognize_image / recognize_pixels.

ATTRIBUTE	DESCRIPTION
results	Token-level text items in detection order. Always populated. TYPE: list[TextItem]
layout	Region boxes (titles, paragraphs, tables, figures, …). Populated only when the call was made with layout=True; empty list otherwise. TYPE: list[LayoutBox]
reading_order	Indices into results giving human reading order. Populated only when reading_order=True was requested. TYPE: list[int]
blocks	Paragraph-level groupings with their own reading order. Populated only when include_blocks=True was requested. TYPE: list[Block]
text	Cached property — the full text joined in reading order (blocks > reading_order > raw results). TYPE: str
tables	Computed view of blocks filtered to table-like labels. TYPE: list[Table]
formulas	Computed view of blocks filtered to formula-like labels (display, numbered, and inline). TYPE: list[Formula]

results instance-attribute

results: list[TextItem]

layout class-attribute instance-attribute

layout: list[LayoutBox] = Field(default_factory=list)

reading_order class-attribute instance-attribute

reading_order: list[int] = Field(default_factory=list)

blocks class-attribute instance-attribute

blocks: list[Block] = Field(default_factory=list)

tables class-attribute instance-attribute

tables: list[Table] = Field(default_factory=list)

formulas class-attribute instance-attribute

formulas: list[Formula] = Field(default_factory=list)

text_degraded class-attribute instance-attribute

text_degraded: bool = False

table_degraded class-attribute instance-attribute

table_degraded: bool = False

formula_degraded class-attribute instance-attribute

formula_degraded: bool = False

text_warning class-attribute instance-attribute

text_warning: str | None = None

table_warning class-attribute instance-attribute

table_warning: str | None = None

formula_warning class-attribute instance-attribute

formula_warning: str | None = None

text cached property

text: str

PdfResponse

Returned by recognize_pdf().

PdfResponse

Bases: _Frozen

Multi-page PDF OCR result returned by recognize_pdf.

ATTRIBUTE	DESCRIPTION
pages	One PdfPage per input page, in order. Each page carries its own results, optional layout, reading_order, blocks, plus per-page metadata (page, page_index, dpi, width, height, mode, text_layer_quality). TYPE: list[PdfPage]
text	Cached property — full document text joined across pages with blank-line separators. TYPE: str
tables	Flattened view of tables across every page. TYPE: list[Table]
formulas	Flattened view of formulas across every page. TYPE: list[Formula]

pages instance-attribute

pages: list[PdfPage]

text cached property

text: str

tables property

tables: list[Table]

formulas property

formulas: list[Formula]

PdfPage

Bases: _Frozen

ATTRIBUTE	DESCRIPTION
page	TYPE: int
page_index	TYPE: int
dpi	TYPE: int
width	TYPE: int
height	TYPE: int
results	TYPE: list[TextItem]
layout	TYPE: list[LayoutBox]
reading_order	TYPE: list[int]
blocks	TYPE: list[Block]
tables	TYPE: list[Table]
formulas	TYPE: list[Formula]
mode	TYPE: PdfMode
text_layer_quality	TYPE: str
orientation_deg	TYPE: int | None
image_b64	TYPE: str | None
image_content_type	TYPE: str | None
text_degraded	TYPE: bool
table_degraded	TYPE: bool
formula_degraded	TYPE: bool
text_warning	TYPE: str | None
table_warning	TYPE: str | None
formula_warning	TYPE: str | None
image_bytes	Decoded page image when the request used images="inline". TYPE: bytes | None

page instance-attribute

page: int

page_index instance-attribute

page_index: int

dpi instance-attribute

dpi: int

width instance-attribute

width: int

height instance-attribute

height: int

results instance-attribute

results: list[TextItem]

layout class-attribute instance-attribute

layout: list[LayoutBox] = Field(default_factory=list)

reading_order class-attribute instance-attribute

reading_order: list[int] = Field(default_factory=list)

blocks class-attribute instance-attribute

blocks: list[Block] = Field(default_factory=list)

tables class-attribute instance-attribute

tables: list[Table] = Field(default_factory=list)

formulas class-attribute instance-attribute

formulas: list[Formula] = Field(default_factory=list)

mode instance-attribute

mode: PdfMode

text_layer_quality class-attribute instance-attribute

text_layer_quality: str = 'absent'

orientation_deg class-attribute instance-attribute

orientation_deg: int | None = None

image_b64 class-attribute instance-attribute

image_b64: str | None = None

image_content_type class-attribute instance-attribute

image_content_type: str | None = None

text_degraded class-attribute instance-attribute

text_degraded: bool = False

table_degraded class-attribute instance-attribute

table_degraded: bool = False

formula_degraded class-attribute instance-attribute

formula_degraded: bool = False

text_warning class-attribute instance-attribute

text_warning: str | None = None

table_warning class-attribute instance-attribute

table_warning: str | None = None

formula_warning class-attribute instance-attribute

formula_warning: str | None = None

image_bytes cached property

image_bytes: bytes | None

Decoded page image when the request used images="inline".

PdfMode

Bases: StrEnum

ATTRIBUTE	DESCRIPTION
ocr
auto
auto_verified
geometric

ocr class-attribute instance-attribute

ocr = 'ocr'

auto class-attribute instance-attribute

auto = 'auto'

auto_verified class-attribute instance-attribute

auto_verified = 'auto_verified'

geometric class-attribute instance-attribute

geometric = 'geometric'

BatchResponse

Returned by recognize_batch(). Per-slot failures are surfaced via iter_results() — use it to walk results without manually zipping batch_results and errors.

BatchResponse

Bases: _Frozen

Multi-image OCR result returned by recognize_batch.

batch_results and errors are parallel lists of equal length: slot i is either a valid OcrResponse with errors[i] is None, or a failure where errors[i] carries the server's error message and batch_results[i] is an empty placeholder OcrResponse(results=[]). Per-slot failures never raise — they land in errors so one bad input cannot fail the whole batch.

Prefer iter_results for a tagged-union iteration instead of zipping the two lists manually.

ATTRIBUTE	DESCRIPTION
batch_results	One OcrResponse per input, in submission order. TYPE: list[OcrResponse]
errors	Parallel str | None list — None for successes, the server's error message otherwise. TYPE: list[str | None]

METHOD	DESCRIPTION
iter_results	Pair batch_results and errors into a tagged-union list.

batch_results instance-attribute

batch_results: list[OcrResponse]

errors instance-attribute

errors: list[str | None]

iter_results

iter_results() -> list[BatchResult]

Pair batch_results and errors into a tagged-union list.

Pythonic iteration; saves users from zipping two parallel lists.

BatchResult

BatchResult = BatchSuccess | BatchFailure

BatchSuccess

Bases: _Frozen

ATTRIBUTE	DESCRIPTION
index	TYPE: int
response	TYPE: OcrResponse

index instance-attribute

index: int

response instance-attribute

response: OcrResponse

BatchFailure

Bases: _Frozen

ATTRIBUTE	DESCRIPTION
index	TYPE: int
error	TYPE: str

index instance-attribute

index: int

error instance-attribute

error: str

HealthStatus

HealthStatus

Bases: _Frozen

ATTRIBUTE	DESCRIPTION
ok	TYPE: bool
status_code	TYPE: int
body	TYPE: str
body_json	TYPE: dict[str, object] | None

ok instance-attribute

ok: bool

status_code instance-attribute

status_code: int

body instance-attribute

body: str

body_json class-attribute instance-attribute

body_json: dict[str, object] | None = None

Capabilities

Capabilities

Bases: _Frozen

GET /capabilities — what the running server actually loaded.

Check features.tables / features.formulas before sending tables=True / formulas=True: those are strict opt-ins and return 400 TABLE_BACKEND_DISABLED / FORMULA_BACKEND_DISABLED when the backend was not configured at server startup.

ATTRIBUTE	DESCRIPTION
build	TYPE: str | None
features	TYPE: CapabilityFeatures
pdf	TYPE: CapabilityPdf
limits	TYPE: CapabilityLimits
endpoints	TYPE: list[str]

build class-attribute instance-attribute

build: str | None = None

features class-attribute instance-attribute

features: CapabilityFeatures = Field(default_factory=CapabilityFeatures)

pdf class-attribute instance-attribute

pdf: CapabilityPdf = Field(default_factory=CapabilityPdf)

limits class-attribute instance-attribute

limits: CapabilityLimits = Field(default_factory=CapabilityLimits)

endpoints class-attribute instance-attribute

endpoints: list[str] = Field(default_factory=list)

CapabilityFeatures

Bases: _Frozen

ATTRIBUTE	DESCRIPTION
layout	TYPE: bool
tables	TYPE: bool
formulas	TYPE: bool
autorotate	TYPE: bool

layout class-attribute instance-attribute

layout: bool = False

tables class-attribute instance-attribute

tables: bool = False

formulas class-attribute instance-attribute

formulas: bool = False

autorotate class-attribute instance-attribute

autorotate: bool = False

CapabilityPdf

Bases: _Frozen

ATTRIBUTE	DESCRIPTION
modes	TYPE: list[str]
default_dpi	TYPE: int | None
max_pages	TYPE: int | None

modes class-attribute instance-attribute

modes: list[str] = Field(default_factory=list)

default_dpi class-attribute instance-attribute

default_dpi: int | None = None

max_pages class-attribute instance-attribute

max_pages: int | None = None

CapabilityLimits

Bases: _Frozen

ATTRIBUTE	DESCRIPTION
max_body_mb	TYPE: int | None
max_image_dim	TYPE: int | None
max_batch_images	TYPE: int | None

max_body_mb class-attribute instance-attribute

max_body_mb: int | None = None

max_image_dim class-attribute instance-attribute

max_image_dim: int | None = None

max_batch_images class-attribute instance-attribute

max_batch_images: int | None = None

Server-side Markdown

MarkdownPagesResponse

Bases: _Frozen

ATTRIBUTE	DESCRIPTION
pages	TYPE: list[MarkdownPage]
markdown	All pages joined in order, separated by blank lines. TYPE: str

pages instance-attribute

pages: list[MarkdownPage]

markdown cached property

markdown: str

All pages joined in order, separated by blank lines.

MarkdownPage

Bases: _Frozen

One page of a server-side PDF → Markdown conversion (as_pages=True).

ATTRIBUTE	DESCRIPTION
page_index	TYPE: int
markdown	TYPE: str
text_degraded	TYPE: bool
table_degraded	TYPE: bool
formula_degraded	TYPE: bool

page_index instance-attribute

page_index: int

markdown instance-attribute

markdown: str

text_degraded class-attribute instance-attribute

text_degraded: bool = False

table_degraded class-attribute instance-attribute

table_degraded: bool = False

formula_degraded class-attribute instance-attribute

formula_degraded: bool = False

Streaming

StreamEvent

Bases: _Frozen

One NDJSON line from POST /ocr/stream.

event is one of "meta", "page", "page_error", "error", "end". Page events arrive as each page completes — out of order by design; use page.page_index to reorder client-side if needed.

ATTRIBUTE	DESCRIPTION
event	TYPE: Literal['meta', 'page', 'page_error', 'error', 'end']
kind	TYPE: str | None
pages	TYPE: int | None
dpi	TYPE: int | None
mode	TYPE: str | None
page_index	TYPE: int | None
code	TYPE: str | None
failed	TYPE: int | None
page	The parsed page for event == "page", else None. TYPE: PdfPage | None

event instance-attribute

event: Literal['meta', 'page', 'page_error', 'error', 'end']

kind class-attribute instance-attribute

kind: str | None = None

pages class-attribute instance-attribute

pages: int | None = None

dpi class-attribute instance-attribute

dpi: int | None = None

mode class-attribute instance-attribute

mode: str | None = None

page_index class-attribute instance-attribute

page_index: int | None = None

code class-attribute instance-attribute

code: str | None = None

failed class-attribute instance-attribute

failed: int | None = None

page cached property

page: PdfPage | None

The parsed page for event == "page", else None.