PaddleOCR 官方 API CLI¶
paddleocr api 是 PaddleOCR CLI 中调用 PaddleOCR 官方 API 的子命令。它把文件 URL 或本地文件提交到官方托管服务，等待任务完成并输出解析结果；它不运行本地推理。
安装与认证¶
先按 安装 paddleocr 安装 Python 包。安装 paddleocr 本体后即可使用此功能，无需安装额外依赖组。
请先在 AI Studio Access Token 页面 获取访问令牌。
CLI 默认读取 PADDLEOCR_ACCESS_TOKEN：
也可以使用 --token 显式传入 token。
基本用法¶
--model_type 必填，可选值为 ocr 或 doc_parsing。--file_url 与 --file_path 必须二选一。
常用参数¶
--model_type：任务类型，ocr或doc_parsing。--model：模型名称。OCR 任务默认使用 PP-OCRv5；文档解析任务未指定时默认使用 PaddleOCR-VL-1.6。--file_url：待处理文件 URL。--file_path：待上传并处理的本地文件路径。--base_url：PaddleOCR API 服务的 base URL；缺省使用官方服务地址（也可通过PADDLEOCR_BASE_URL环境变量设置）。--request_timeout：一次 HTTP 请求的超时时间，单位为秒。--poll_timeout：等待远端任务完成的总超时时间，单位为秒。--output：输出 JSON 文件路径；省略时打印到标准输出。--save_resources：保存结果对象引用资源的目录。--overwrite_resources：保存资源时覆盖已有文件。--page_ranges：页码范围，例如2,4-6。--use_doc_orientation_classify/--no-use_doc_orientation_classify：启用或禁用文档方向分类。--use_doc_unwarping/--no-use_doc_unwarping：启用或禁用文档扭曲矫正。--use_textline_orientation/--no-use_textline_orientation：启用或禁用文本行方向检测。--text_det_limit_side_len：文本检测图像边长限制。--text_det_limit_type：边长限制类型，min或max。--text_rec_score_thresh：文本识别置信度阈值。--use_layout_detection/--no-use_layout_detection：启用或禁用版面检测。--use_seal_recognition/--no-use_seal_recognition：启用或禁用印章识别。--use_table_recognition/--no-use_table_recognition：启用或禁用表格识别。--use_formula_recognition/--no-use_formula_recognition：启用或禁用公式识别。--use_chart_recognition/--no-use_chart_recognition：启用或禁用图表识别。--visualize/--no-visualize：启用或禁用可视化结果图。--prettify_markdown/--no-prettify_markdown：启用或禁用 markdown 美化。
OCR 示例¶
paddleocr api \
--model_type ocr \
--model PP-OCRv5 \
--file_path ./invoice.pdf \
--request_timeout 300 \
--poll_timeout 600 \
--output ocr-result.json
文档解析示例¶
paddleocr api \
--model_type doc_parsing \
--file_url https://example.com/report.pdf \
--use_chart_recognition \
--save_resources ./doc-assets \
--output doc-result.json
模型选择¶
| 任务 | --model_type |
默认模型 | 可选模型 |
|---|---|---|---|
| OCR | ocr |
PP-OCRv5 |
PP-OCRv5 |
| 文档解析 | doc_parsing |
PaddleOCR-VL-1.6 |
PP-StructureV3、PaddleOCR-VL、PaddleOCR-VL-1.5、PaddleOCR-VL-1.6 |
输出行为¶
命令成功时输出格式化 JSON。OCR 结果包含 jobId 和每页的 prunedResult、ocrImageUrl；文档解析结果包含 jobId 和每页的 markdownText、markdownImages、outputImages。如果指定 --output，CLI 写入该文件并打印保存位置；否则直接打印到标准输出。指定 --save_resources 时，CLI 会把结果对象引用的资源保存到目标目录。
错误会输出到标准错误并返回非零退出码。常见原因包括缺少 PADDLEOCR_ACCESS_TOKEN、模型与 --model_type 不匹配、请求超时、轮询超时、远端任务失败或响应格式异常。