Skip to content

PaddleOCR official API TypeScript SDK

The TypeScript SDK targets Node.js 18+ and calls the PaddleOCR official API for OCR and document parsing. It uses hosted PaddleOCR services and does not run local PaddleOCR inference.

Install And Authenticate

First obtain an access token from the AI Studio Access Token page.

npm install @paddleocr/api-sdk
export PADDLEOCR_ACCESS_TOKEN="your-access-token"

The client reads PADDLEOCR_ACCESS_TOKEN by default and also accepts token:

import { PaddleOCRClient } from "@paddleocr/api-sdk";

const client = new PaddleOCRClient({
  token: process.env.PADDLEOCR_ACCESS_TOKEN,
});

Quick Start

import { Model, PaddleOCRClient } from "@paddleocr/api-sdk";

const client = new PaddleOCRClient();
const result = await client.ocr({
  fileUrl: "https://example.com/invoice.pdf",
  model: Model.PPOCRv5,
});
console.log(result.jobId, result.pages.length);

Use filePath for a local file. Pass exactly one of fileUrl or filePath.

Public API

Common TypeScript public methods include:

  • ocr(...): submit an OCR job, wait for completion, and return an OCR result.
  • parseDocument(...): submit a document parsing job, wait for completion, and return a document parsing result.
  • submitOcr(...): submit only an OCR job and return a job object.
  • submitDocumentParsing(...): submit only a document parsing job and return a job object.
  • getStatus(jobId): perform one non-blocking status request.
  • waitOcrResult(job): wait for an OCR job and parse its result.
  • waitDocumentParsingResult(job): wait for a document parsing job and parse its result.
  • saveResource(resourceUrl, destination, options): save one resource URL.
  • saveOcrResultResources(result, destination, options): save resources referenced by an OCR result object.
  • saveDocumentParsingResultResources(result, destination, options): save resources referenced by a document parsing result object.

Choose Models

The Model enum values in the table are type-safe aliases for the official API model-name strings. They are serialized to the corresponding model name when the request is submitted. You can also pass the official API model-name string directly, for example model: "PaddleOCR-VL-1.6".

Task Interfaces Default model Supported models Option type
OCR ocr, submitOcr, waitOcrResult Model.PPOCRv6 Model.PPOCRv5, Model.PPOCRv6 OCROptions
Document parsing parseDocument, submitDocumentParsing, waitDocumentParsingResult Model.PaddleOCRVL16 Model.PPStructureV3, Model.PaddleOCRVL, Model.PaddleOCRVL15, Model.PaddleOCRVL16 Use PPStructureV3Options with PPStructureV3, and PaddleOCRVLOptions with PaddleOCR-VL models.

Configuration

Client Configuration

const client = new PaddleOCRClient({
  requestTimeout: 300_000,
  pollTimeout: 600_000,
});

requestTimeout limits one HTTP request, including submit, status, and resource downloads. pollTimeout limits the total wait time for ocr, parseDocument, waitOcrResult, and waitDocumentParsingResult. Public methods can also accept an AbortSignal for caller-driven cancellation.

Override the service base URL via the PADDLEOCR_BASE_URL environment variable or the baseUrl option:

const client = new PaddleOCRClient({
  baseUrl: "https://my-proxy.com/paddle",
});

Inject a custom fetch implementation for proxies or custom network layers:

const client = new PaddleOCRClient({
  fetch: myCustomFetch,
});

Request Options

TypeScript SDK field names use camelCase, matching the official API directly. Omitted fields are not sent. See the interface source or Official API Reference for complete field definitions.

OCROptions (common fields)

Field Type Description
useDocOrientationClassify boolean Document orientation classification
useDocUnwarping boolean Document unwarping
visualize boolean Return visualization images

PPStructureV3Options (common fields)

Field Type Description
useTableRecognition boolean Table recognition
useFormulaRecognition boolean Formula recognition
useChartRecognition boolean Chart recognition
prettifyMarkdown boolean Markdown prettification

PaddleOCRVLOptions (common fields)

Field Type Description
useLayoutDetection boolean Layout detection
useChartRecognition boolean Chart recognition
temperature number Sampling temperature
prettifyMarkdown boolean Markdown prettification

Error Handling

All SDK errors inherit from PaddleOCRAPIError. Common typed errors include AuthError, InvalidRequestError, RateLimitError, ServiceUnavailableError, APIError, NetworkError, JobFailedError, RequestTimeoutError, PollTimeoutError, ResponseFormatError, and ResultParseError.

Official API Reference

Quota and Error Codes

Comments