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)

text cached property

text: str

tables property

tables: list[Table]

formulas property

formulas: list[Formula]

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]
mode	TYPE: PdfMode
text_layer_quality	TYPE: str
tables	TYPE: list[Table]
formulas	TYPE: list[Formula]

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)

mode instance-attribute

mode: PdfMode

text_layer_quality instance-attribute

text_layer_quality: str

tables property

tables: list[Table]

formulas property

formulas: list[Formula]

PdfMode

Bases: StrEnum

ATTRIBUTE	DESCRIPTION
ocr
text
auto
auto_verified
geometric

ocr class-attribute instance-attribute

ocr = 'ocr'

text class-attribute instance-attribute

text = 'text'

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