OCR

Document text extraction.

Methods on this page are called through client.ocr.

client.ocr.document

client.ocr.document(request: OcrDocumentRequest, requestOptions?: RequestOptions): Promise<OcrDocumentResponseShape>

Runs layout-aware OCR on the provided document bytes and returns per-page results. When a page range is provided, only the inclusive subset is processed. Requires OCR_DOCUMENT permission.

HTTP: POST /v1/ocr:document

Parameters

Parameter	Type	Description
`request`	`OcrDocumentRequest`	Request body.
`requestOptions`	`RequestOptions` optional	Per-call signal, timeout, or headers.

Returns: Promise<OcrDocumentResponseShape>

Example

const ocr = await client.ocr.document({
  content: "JVBERi0xLjQKJc...",
  includeMarkdown: true,
});
console.log(ocr.pages[0]?.page?.markdown);

Data Models

Enum Values

OcrCategory

UNSPECIFIED, CAPTION, FOOTNOTE, FORMULA, LIST_ITEM, PAGE_FOOTER, PAGE_HEADER, PICTURE, SECTION_HEADER, TABLE, TEXT, TITLE, OTHER, UNKNOWN

OcrInputFormat

AUTO, PDF, TIFF, PNG, JPEG, BMP

Interfaces

BoundingBox

Bounding box coordinates in page space.

Field	Type	Required	Description
`x1`	`number`	yes	Left coordinate
`y1`	`number`	yes	Top coordinate
`x2`	`number`	yes	Right coordinate
`y2`	`number`	yes	Bottom coordinate

DocumentTimings

Aggregate timing statistics for an OCR request.

Field	Type	Required	Description
`wallTimeMs`	`number`	yes	End-to-end request time (ms)
`sumQueueWaitMs`	`number`	yes	Sum of per-page queue wait times (ms)
`sumRenderMs`	`number`	yes	Sum of per-page render times (ms)
`sumOcrMs`	`number`	yes	Sum of per-page OCR times (ms)
`sumPageTotalMs`	`number`	yes	Sum of per-page total times (ms)

ImageInfo

Rendered image metadata for an OCR page.

Field	Type	Required	Description
`widthPx`	`number`	yes	Rendered image width in pixels
`heightPx`	`number`	yes	Rendered image height in pixels
`dpi`	`number`	yes	Rendering DPI

OcrCell

Single OCR layout element.

Field	Type	Required	Description
`bbox`	`BoundingBox \| null`	no	Bounding box in page coordinates
`categoryLabel`	`string`	yes	Raw category label emitted by OCR
`category`	`OcrCategory`	yes	Normalized OCR category
`text`	`string`	yes	OCR text content

OcrDocumentRequest

Request body for OCR document processing.

Field	Type	Required	Description
`content`	`string \| null`	yes	Base64-encoded document bytes
`format`	`OcrInputFormat \| null`	no	Input format hint (AUTO, PDF, TIFF, PNG, JPEG, BMP)
`includeRawJson`	`boolean \| null`	no	Include raw OCR JSON payload in the response
`includeMarkdown`	`boolean \| null`	no	Include markdown rendering in the response
`startPage`	`number \| null`	no	0-based inclusive start page
`endPage`	`number \| null`	no	0-based inclusive end page

OcrDocumentResponse

Response containing page-ordered OCR results.

Field	Type	Required	Description
`detectedFormat`	`OcrInputFormat`	yes	Detected input format
`pageCount`	`number`	yes	Number of pages processed after applying the range
`pages`	`Array<OcrPageResult>`	yes	Ordered per-page OCR results
`timings`	`DocumentTimings`	yes	Aggregate timing statistics

OcrLayout

Parsed OCR layout output for a page.

Field	Type	Required	Description
`cells`	`Array<OcrCell>`	yes	Layout cells in reading order

OcrPage

OCR output for a single page.

Field	Type	Required	Description
`rawJson`	`string \| null`	no	Raw OCR JSON payload when requested
`markdown`	`string \| null`	no	Markdown rendering when requested
`layout`	`OcrLayout`	yes	Parsed layout output
`timings`	`PageTimings`	yes	Timing breakdown for the page
`image`	`ImageInfo`	yes	Rendered image metadata

OcrPageResult

Per-page OCR result containing output or error status.

Field	Type	Required	Description
`pageIndex`	`number`	yes	0-based page index
`page`	`OcrPage \| null`	no	OCR output for the page
`status`	`RpcStatus \| null`	no	Error status for the page

PageTimings

Per-page timing breakdown for OCR processing.

Field	Type	Required	Description
`queueWaitMs`	`number`	yes	Time spent waiting in the render queue (ms)
`renderMs`	`number`	yes	Time spent rendering the page image (ms)
`ocrMs`	`number`	yes	Time spent running OCR (ms)
`totalMs`	`number`	yes	Total page processing time (ms)

RpcStatus

Status payload for per-page OCR errors.

Field	Type	Required	Description
`code`	`number`	yes	gRPC status code as defined by google.rpc.Code
`message`	`string \| null`	no	Human-readable error message

Response Shapes

Response shape types model values returned by the SDK after forward-compatible unknown enum strings are coerced to null.

BoundingBoxResponseShape

Field	Type	Required	Description
`x1`	`number`	yes	Left coordinate
`y1`	`number`	yes	Top coordinate
`x2`	`number`	yes	Right coordinate
`y2`	`number`	yes	Bottom coordinate

DocumentTimingsResponseShape

Field	Type	Required	Description
`wallTimeMs`	`number`	yes	End-to-end request time (ms)
`sumQueueWaitMs`	`number`	yes	Sum of per-page queue wait times (ms)
`sumRenderMs`	`number`	yes	Sum of per-page render times (ms)
`sumOcrMs`	`number`	yes	Sum of per-page OCR times (ms)
`sumPageTotalMs`	`number`	yes	Sum of per-page total times (ms)

ImageInfoResponseShape

Field	Type	Required	Description
`widthPx`	`number`	yes	Rendered image width in pixels
`heightPx`	`number`	yes	Rendered image height in pixels
`dpi`	`number`	yes	Rendering DPI

OcrCellResponseShape

Field	Type	Required	Description
`bbox`	`BoundingBoxResponseShape \| null`	no	Bounding box in page coordinates
`categoryLabel`	`string`	yes	Raw category label emitted by OCR
`category`	`OcrCategory \| null`	yes	Normalized OCR category
`text`	`string`	yes	OCR text content

OcrDocumentResponseShape

Field	Type	Required	Description
`detectedFormat`	`OcrInputFormat \| null`	yes	Detected input format
`pageCount`	`number`	yes	Number of pages processed after applying the range
`pages`	`Array<OcrPageResultResponseShape>`	yes	Ordered per-page OCR results
`timings`	`DocumentTimingsResponseShape`	yes	Aggregate timing statistics

OcrLayoutResponseShape

Field	Type	Required	Description
`cells`	`Array<OcrCellResponseShape>`	yes	Layout cells in reading order

OcrPageResponseShape

Field	Type	Required	Description
`rawJson`	`string \| null`	no	Raw OCR JSON payload when requested
`markdown`	`string \| null`	no	Markdown rendering when requested
`layout`	`OcrLayoutResponseShape`	yes	Parsed layout output
`timings`	`PageTimingsResponseShape`	yes	Timing breakdown for the page
`image`	`ImageInfoResponseShape`	yes	Rendered image metadata

OcrPageResultResponseShape

Type constraint: OcrPageResultResponseShape = RequireExactlyOne<OcrPageResultResponseShapeBase, "page" \| "status">

Field	Type	Required	Description
`pageIndex`	`number`	yes	0-based page index
`page`	`OcrPageResponseShape \| null`	no	OCR output for the page
`status`	`RpcStatusResponseShape \| null`	no	Error status for the page

PageTimingsResponseShape

Field	Type	Required	Description
`queueWaitMs`	`number`	yes	Time spent waiting in the render queue (ms)
`renderMs`	`number`	yes	Time spent rendering the page image (ms)
`ocrMs`	`number`	yes	Time spent running OCR (ms)
`totalMs`	`number`	yes	Total page processing time (ms)

RpcStatusResponseShape

Field	Type	Required	Description
`code`	`number`	yes	gRPC status code as defined by google.rpc.Code
`message`	`string \| null`	no	Human-readable error message

OCR

On this page