PaddleOCR Official API CLI (`paddleocr api`) 实战指南：云端 OCR 与文档解析的命令行调用

PaddleOCR Official API CLI (paddleocr api) 实战指南：云端 OCR 与文档解析的命令行调用

【免费下载链接】PaddleOCR飞桨多语言OCR工具包（实用超轻量OCR系统，支持80+种语言识别，提供数据标注与合成工具，支持服务器、移动端、嵌入式及IoT设备端的训练与部署） Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80+ languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR

PaddleOCR 官方 API CLI 是 PaddleOCR 提供的paddleocr api子命令，用于将本地文件或文件 URL 提交到托管的 PaddleOCR 云服务，异步等待任务完成后输出解析结果，全程不加载本地模型、不执行本地推理。本文将基于仓库中的 cli.en.md 文档，结合paddleocr/_api_client/的源码实现，完整讲解从安装鉴权、参数配置、任务模型选择到输出与错误处理的端到端使用方式。

一、工作原理与适用场景

paddleocr api是对 PaddleOCR 官方 API 的命令行封装，其调用链与 Python SDK 完全一致（见 client.py）：

1. 提交任务：将file_url（远程文件地址）或file_path（本地文件，上传为 multipart 表单）连同模型名、optionalPayload参数提交到任务接口；
2. 轮询等待：以指数退避方式轮询任务状态（pending→running→done/failed），见 poller.py；
3. 拉取结果：任务完成后从resultUrl指向的 JSONL 地址下载结果并解析为结构化对象（OCR 或文档解析两类），见 poller.py。

因此它的典型使用场景是：脚本化批量 OCR、快速验证云端模型效果、无需本地 GPU 与模型下载的文档解析流水线。官方默认服务地址定义在 http.py：DEFAULT_BASE_URL = "https://paddleocr.aistudio-app.com"，接口路径为/api/v2/ocr/jobs。

二、安装与鉴权

2.1 安装

先按 Install paddleocr 安装核心paddleocrPython 包。安装完成后，api子命令开箱即用——它属于核心包自带能力，无需安装任何额外的依赖分组。

从代码看，api子命令由 _cli.py 中的_register_api_command注册，真正实现位于 paddleocr/_api_client/cli.py，使用标准argparse定义参数。

2.2 获取 Access Token

需要先在 AI Studio Access Token 页面获取访问令牌。CLI 默认从环境变量PADDLEOCR_ACCESS_TOKEN读取：

export PADDLEOCR_ACCESS_TOKEN="your-access-token"

也可以显式通过--token传入。底层 client.py 的优先级是：--token参数 >PADDLEOCR_ACCESS_TOKEN环境变量；两者都缺失时抛出AuthError（"Token is required. Set PADDLEOCR_ACCESS_TOKEN or pass token=."），CLI 会将错误打印到 stderr 并以非零退出码结束。

说明：认证采用Authorization: Bearer <token>请求头，见 http.py。请求头中还可通过--client_platform自定义Client-Platform头。

三、基础用法

paddleocr api \ --model_type ocr \ --file_url https://example.com/invoice.pdf

两个强制约束（由源码 cli.py 与 _core.py 共同保证）：

• --model_type必填，只能取ocr或doc_parsing；
• --file_url与--file_path二选一，同时省略或同时提供都会抛出InvalidRequestError。

--file_url提交时走submit_url（JSON body），--file_path走submit_file（multipart 文件上传，且会先校验本地文件存在，见 http.py）。

四、常用参数详解

以下为paddleocr api的完整参数清单，默认值以 cli.py 源码为准：

参数按功能分组，与 SDK 中的选项数据类一一对应：OCR 任务使用OCROptions（见 models.py），doc_parsing中 PaddleOCR-VL 系列使用PaddleOCRVLOptions，PP-StructureV3 使用PPStructureV3Options（其中还包含layout_threshold、temperature、top_p、max_new_tokens等更细粒度参数，models.py 中有完整字段）。

布尔参数在命令行中使用True/False字符串，由str2bool解析；top_p、temperature、min_pixels/max_pixels等在提交前会经过校验（如top_p必须满足0 < top_p <= 1，见 models.py），非法值会以InvalidRequestError拒绝。

五、两种任务的实战示例

5.1 OCR 示例（本地文件）

paddleocr api \ --model_type ocr \ --model PP-OCRv5 \ --file_path ./invoice.pdf \ --request_timeout 300 \ --poll_timeout 600 \ --output ocr-result.json

要点：

• --file_path上传本地invoice.pdf；
• --request_timeout 300与--poll_timeout 600分别控制单次 HTTP 请求与整体轮询的等待上限，多页大文件建议按需调大；
• --output ocr-result.json将格式化 JSON 写入文件并打印保存路径；不写则直接打印到 stdout。

5.2 文档解析示例（远程文件 URL）

paddleocr api \ --model_type doc_parsing \ --file_url https://example.com/report.pdf \ --use_chart_recognition True \ --save_resources ./doc-assets \ --output doc-result.json

要点：

• 输入走--file_url（服务端直接拉取，无需本地下载）；
• --use_chart_recognition True开启图表识别；
• --save_resources ./doc-assets会把结果中引用的 Markdown 图片与输出图片下载到本地目录（注意：目标目录必须已存在，见 resources.py）。

资源保存的命名规则可在 resources.py 中确认：OCR 结果图片按ocr-page-{页号}.{扩展名}命名；文档解析结果按结果对象中的资源名（markdown_images与output_images的 key）保存。默认遇到同名文件会报错，加--overwrite_resources可覆盖。

六、模型选择

以上模型集合定义在 models.py 的Model枚举与_OCR_MODELS/_DOCUMENT_PARSING_MODELS/_VL_MODELS三个集合中。

需要注意两点（对应 cli.py 的调度逻辑）：

1. 模型与任务必须匹配：例如对--model_type ocr传入PP-StructureV3，CLI 会打印Error: OCR task does not support PP-StructureV3.并以退出码 2 结束；
2. 不同模型走不同的参数集合：doc_parsing任务中，PaddleOCR-VL 系列使用PaddleOCRVLOptions（支持use_layout_detection、use_chart_recognition等），PP-StructureV3 使用PPStructureV3Options（额外支持use_table_recognition、use_formula_recognition等），选择不当会在提交前被resolve_document_options拒绝（见 _core.py）。

七、输出行为与结果结构

7.1 标准输出结构

成功时命令输出格式化 JSON（ensure_ascii=False, indent=2），两种任务的字段由 cli.py 定义：

OCR 输出：jobId+ 每页的prunedResult（裁剪后的识别结果）与ocrImageUrl（识别可视化图地址）：

{ "jobId": "xxx", "pages": [ { "prunedResult": "...", "ocrImageUrl": "https://..." } ] }

文档解析输出：jobId+ 每页的markdownText（Markdown 文本）、markdownImages（Markdown 中引用的图片映射）、outputImages（输出图片映射）：

{ "jobId": "xxx", "pages": [ { "markdownText": "...", "markdownImages": {}, "outputImages": {} } ] }

7.2 输出落盘行为

• --output <path>：写入该文件并打印Result saved to: <path>；省略则直接向 stdout 打印 JSON；
• --save_resources <dir>：将结果引用的资源下载到指定目录，并打印Resources saved to: <dir> (N files)（此提示输出到 stderr）；
• 二者可同时使用。

从源码看，这些结构对应 results.py 中的OCRResult/OCRPage与DocParsingResult/DocParsingPage数据类；服务端返回的是 JSONL 格式，由parse_ocr_result/parse_doc_parsing_result逐行解析（poller.py）。

八、错误处理与排错指南

错误统一打印到 stderr，并以非零退出码返回。常见原因与对应的错误类型（定义见 errors.py）：

排错建议顺序：先确认环境变量PADDLEOCR_ACCESS_TOKEN是否已导出 → 再确认--model与--model_type匹配 → 检查--request_timeout/--poll_timeout是否对大文件过小 → 最后核对本地文件路径是否存在（--file_path不存在会抛FileNotFoundError）。

九、相关资源

• 官方 API 总览：overview.en.md（介绍 Python / TypeScript / Go SDK 与 CLI 四种客户端形态）
• CLI 实现源码：paddleocr/_api_client/cli.py、paddleocr/_api_client/client.py
• 底层通信与轮询：paddleocr/_api_client/_http.py、paddleocr/_api_client/_poller.py
• 参数与结果模型：paddleocr/_api_client/models.py、paddleocr/_api_client/results.py
• 测试用例：tests/api_client/test_cli.py、tests/api_client/test_http.py

各模型的 API 参考文档（PP-OCRv5、PP-StructureV3、PaddleOCR-VL、PaddleOCR-VL-1.5）以及 API 配额规则与错误码说明，可在 AI Studio 官方文档区查阅，以获取最新的模型能力、配额限制与错误码定义。

【免费下载链接】PaddleOCR飞桨多语言OCR工具包（实用超轻量OCR系统，支持80+种语言识别，提供数据标注与合成工具，支持服务器、移动端、嵌入式及IoT设备端的训练与部署） Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80+ languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR