跳转至

PaddleOCR 官方 API TypeScript SDK

TypeScript SDK 面向 Node.js 18 及以上环境，调用 PaddleOCR 官方 API 完成 OCR 与文档解析任务。它使用官方托管服务，不运行本地 PaddleOCR 推理。

安装与认证

请先在 AI Studio Access Token 页面 获取访问令牌。

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

客户端默认读取 PADDLEOCR_ACCESS_TOKEN，也可以传入 token：

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

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

快速开始

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);

本地文件使用 filePath。fileUrl 与 filePath 必须二选一。

公共 API

TypeScript SDK 常用公共方法包括：

  • ocr(...)：提交 OCR 任务，等待完成并返回 OCR 结果。
  • parseDocument(...)：提交文档解析任务，等待完成并返回文档解析结果。
  • submitOcr(...)：只提交 OCR 任务，返回任务对象。
  • submitDocumentParsing(...)：只提交文档解析任务，返回任务对象。
  • getStatus(jobId)：执行一次非阻塞状态查询。
  • waitOcrResult(job)：等待 OCR 任务完成并解析结果。
  • waitDocumentParsingResult(job)：等待文档解析任务完成并解析结果。
  • saveResource(resourceUrl, destination, options)：保存单个资源 URL。
  • saveOcrResultResources(result, destination, options)：保存 OCR 结果对象引用的资源。
  • saveDocumentParsingResultResources(result, destination, options)：保存文档解析结果对象引用的资源。

模型选择

表中的 Model 枚举是官方 API 模型名字符串的类型安全写法，提交请求时会转换为对应的实际模型名。也可以直接传入官方 API 模型名字符串，例如 model: "PaddleOCR-VL-1.6"。

任务 适用接口 默认模型 可选模型 参数类型
OCR ocr、submitOcr、waitOcrResult Model.PPOCRv6 Model.PPOCRv5、Model.PPOCRv6 OCROptions
文档解析 parseDocument、submitDocumentParsing、waitDocumentParsingResult Model.PaddleOCRVL16 Model.PPStructureV3、Model.PaddleOCRVL、Model.PaddleOCRVL15、Model.PaddleOCRVL16 选择 PPStructureV3 时传入 PPStructureV3Options；选择 PaddleOCR-VL 系列模型时传入 PaddleOCRVLOptions。

配置与参数

客户端配置

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

requestTimeout 限制一次 HTTP 请求，包括提交、查询状态和下载资源。pollTimeout 限制 ocr、parseDocument、waitOcrResult 与 waitDocumentParsingResult 的总等待时间。公共方法还可以接收 AbortSignal 以便上层主动取消。

通过环境变量 PADDLEOCR_BASE_URL 或 baseUrl 参数指定自定义服务地址：

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

通过 fetch 选项注入自定义 fetch 实现，适用于需要代理或自定义网络层的场景：

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

请求参数

TypeScript SDK 的参数名使用 camelCase，与官方 API 字段名一致。未设置的字段不会发送，使用服务端默认值。完整字段定义见接口源码或官方 API 参考。

OCROptions（常用字段）

字段 类型 说明
useDocOrientationClassify boolean 文档方向分类
useDocUnwarping boolean 文档扭曲矫正
visualize boolean 是否返回可视化结果图

PPStructureV3Options（常用字段）

字段 类型 说明
useTableRecognition boolean 表格识别
useFormulaRecognition boolean 公式识别
useChartRecognition boolean 图表识别
prettifyMarkdown boolean Markdown 美化

PaddleOCRVLOptions（常用字段）

字段 类型 说明
useLayoutDetection boolean 版面检测
useChartRecognition boolean 图表识别
temperature number 采样温度
prettifyMarkdown boolean Markdown 美化

错误处理

所有 SDK 错误都继承自 PaddleOCRAPIError，常见类型包括 AuthError、InvalidRequestError、RateLimitError、ServiceUnavailableError、APIError、NetworkError、JobFailedError、RequestTimeoutError、PollTimeoutError、ResponseFormatError 和 ResultParseError。

官方 API 参考

配额与错误码

评论