Document Scan / OCR (totalum-sdk/scan)

import … from 'totalum-sdk/scan' — or the same namespace on totalum from 'totalum-sdk'. Install, configuration and errors: Totalum SDK.

Read documents and images: extract the fields you describe (an invoice's number, date and total) as JSON with document(), or get the plain text of every page with ocr(). The document can be a project file, a URL or a file name of the project. Billed in credits.

const { data } = await totalum.scan.document({
  key: invoice.key,
  properties: { total: { type: 'number', description: 'the invoice total' } },
});

#totalumScan

totalumScan(options?: TotalumClientOptions): TotalumScan

Creates the scan namespace (the same object as totalum.scan, scope scan): documents and images read by a vision model.

Parameters

Returns TotalumScan — The scan namespace: the methods below.

Example

import { totalumScan } from 'totalum-sdk/scan';

const scan = totalumScan();
const { text } = await scan.ocr({ key: 'p/acme-crm/01M4P0SFVZXNRS871ZSKZNWHY0.png' });

The namespace's type is exported as TotalumScan (import type { TotalumScan } from 'totalum-sdk/scan').

#scan.document

scan.document(input: ScanDocumentInput): Promise<ScanDocumentResult>

Reads a document or image (a PDF, a photo, a scan) and returns the fields you describe — an invoice's number, date and total, an ID card's name — as JSON. Describe each field with a JSON Schema type and a description; fields not found are null. Pass exactly one of key, fileName or url.

Parameters

Returns Promise<ScanDocumentResult> — The extracted fields, details of the scan, and what it cost.

Errors — besides the errors every call can throw:

Example

const scan = await totalum.scan.document({
  key: invoice.key,
  properties: {
    invoiceNumber: { type: 'string', description: 'the invoice number' },
    issueDate: { type: 'string', description: 'the issue date as YYYY-MM-DD' },
    total: { type: 'number', description: 'the total amount including tax' },
  },
});

Result:

{
  "data": { "invoiceNumber": "F-2026-0012", "issueDate": "2026-09-30", "total": 1210 },
  "metadata": { "usageUnits": 1, "exactUsageUnits": 1, "pages": 1, "provider": "totalum", "credits": 0.0039 },
  "usage": { "credits": 0.0039 }
}

#scan.ocr

scan.ocr(input: ScanOcrInput): Promise<{ pages, text, fullDetails?, usage }>

The text of a document or image (OCR), as Markdown per page, keeping reading order and tables. Use it to index a PDF for search, or to read a photo of a sign. Long PDFs are read in parallel chunks. Pass exactly one of key, fileName or url.

Parameters

Returns Promise<{ pages, text, fullDetails?, usage }> — The whole text, the text of each page, and what it cost.

Errors — besides the errors every call can throw:

Example

const { text, pages } = await totalum.scan.ocr({ key: 'p/acme-crm/01M4P0SFVZXNRS871ZSKZNWHY0.png' });

Result:

{
  "text": "TOTALUM 42",
  "pages": [{ "markdown": "TOTALUM 42", "width": 0, "height": 0 }],
  "usage": { "credits": 0.021 }
}

#ScanDocumentInput

The input of scan.document(): one document and the fields to extract.

#ScanDocumentResult

What scan.document() returns: the extracted fields (one set per page with processEveryPdfPageAsDifferentScan), details of the scan, and what it cost.

#ScanOcrInput

The input of scan.ocr(): one document.

#ScanOcrOutput

The text of a document, from scan.ocr().