API 接入文档
OfficeClaw OCR 提供兼容 OpenAI 格式的 RESTful API，支持快速集成到任何现有应用中。
概述
兼容性：API 遵循 OpenAI 格式规范，可使用任何 OpenAI SDK 直接对接，只需修改
base_url 和 api_key。
认证与 Token
所有 API 请求（除健康检查外）必须在 Header 中携带 Bearer Token：
http
Authorization: Bearer <YOUR_API_TOKEN>
🔑 在线测试 Token
输入您的 API Token，可在此页面直接测试 API 连通性。
获取 Token：前往 申请页面 提交申请，审核通过后 API Key 将发送至您的邮箱。每个 Token 绑定服务版本和页数额度。
Token 权限与额度
| 字段 | 说明 |
|---|---|
tier | 服务版本：basic / standard / professional |
quota | 剩余页数当量 |
rate_limit | 速率限制（请求/分钟） |
查询 Token 信息：
bash
curl https://ocr.office-claw.cn/v1/dashboard/billing/usage \
-H "Authorization: Bearer $TOKEN"
Base URL
| 环境 | 地址 |
|---|---|
| 公网 | https://ocr.office-claw.cn |
| 局域网 | http://192.168.124.x:9000（同网络内直连） |
图片 / PDF OCR
POST /v1/ocr/ocr
识别图片或 PDF 中的文字内容，返回纯文本。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
file | file | 是* | 图片（PNG/JPG）或 PDF 文件（multipart 上传） |
image_url | string | 是* | 图片 URL 或 base64 data URI（JSON 请求） |
prompt | string | 否 | OCR 提示词，默认"请识别图片中的所有文字，按原始布局输出。" |
* file 和 image_url 二选一。PDF 仅支持 file 上传。
请求示例
bash
# 图片 OCR
curl -X POST https://ocr.office-claw.cn/v1/ocr/ocr \
-H "Authorization: Bearer $TOKEN" \
-F "file=@image.jpg" \
-F "prompt=请识别图片中的所有文字"
# PDF OCR
curl -X POST https://ocr.office-claw.cn/v1/ocr/ocr \
-H "Authorization: Bearer $TOKEN" \
-F "file=@document.pdf"
返回示例
json
{
"text": "识别内容...",
"backend": "paddleocr-vl-1.5"
}
PDF 返回额外字段：
json
{
"text": "--- 第 1 页 ---\n识别内容...\n\n--- 第 2 页 ---\n识别内容...",
"is_pdf": true,
"pages": 2
}
文档解析
POST /v1/ocr/parse
完整文档解析，支持 Markdown 格式输出。
bash
curl -X POST https://ocr.office-claw.cn/v1/ocr/parse \
-H "Authorization: Bearer $TOKEN" \
-F "file=@document.pdf" \
-F "output_format=markdown"
双层 PDF 生成
POST /v1/ocr/sandwich-pdf
生成可搜索的双层 PDF：在原始扫描图像上叠加不可见的 OCR 文字层，使 PDF 可全文搜索、可复制。
请求参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
file | file | 是 | — | 图片或 PDF 文件 |
preprocess | string | 否 | auto | 预处理模式 |
llm_correct | bool | 否 | false | 启用 AI 智能纠错 |
output_pdfa | bool | 否 | false | 输出 PDF/A 合规格式 |
page_start | int | 否 | 1 | 起始页码 |
page_end | int | 否 | 0(末页) | 结束页码 |
请求示例
bash
# 标准版：智能预处理 + 双层 PDF
curl -X POST https://ocr.office-claw.cn/v1/ocr/sandwich-pdf \
-H "Authorization: Bearer $TOKEN" \
-F "file=@scan.pdf" \
-F "preprocess=auto" \
-o output.pdf
# 专业版：全功能 + 纠错 + PDF/A
curl -X POST https://ocr.office-claw.cn/v1/ocr/sandwich-pdf \
-H "Authorization: Bearer $TOKEN" \
-F "file=@scan.pdf" \
-F "preprocess=auto" \
-F "llm_correct=true" \
-F "output_pdfa=true" \
-o output_pdfa.pdf
响应
Content-Type: application/pdf，响应体为 PDF 二进制数据。
响应头 X-OCR-Pages 包含每页 OCR 统计信息：
json
[
{"page": 1, "ocr_ms": 643, "text_length": 681, "lines": 18, "deskew_angle": 0.5},
{"page": 2, "ocr_ms": 986, "text_length": 1093, "lines": 28, "deskew_angle": 0.0}
]
智能预处理
preprocess 参数控制图像预处理步骤：
| 模式 | 说明 |
|---|---|
auto | AI 自动分析图像质量，选择最优预处理步骤（推荐） |
none | 不做预处理 |
deskew | 仅倾斜校正 |
denoise | 仅降噪 |
decontaminate | 背景纯净化 + 黑边裁剪 |
brightness | 仅亮度/对比度调节 |
| 组合 | deskew,denoise / deskew,denoise,decontaminate 等 |
错误码
| HTTP 状态码 | 错误类型 | 说明 |
|---|---|---|
| 401 | unauthorized | Token 缺失或无效 |
| 402 | quota_exceeded | 页数额度已用完 |
| 429 | rate_limit | 请求频率超限 |
| 413 | file_too_large | 文件超过 200MB 限制 |
| 415 | unsupported_format | 不支持的文件格式 |
| 503 | service_unavailable | 后端服务暂时不可用 |
支持文件格式
| 类别 | 格式 | 扩展名 |
|---|---|---|
| 图片 | PNG / JPEG | .png .jpg .jpeg |
| 文档 |
限制说明
| 项目 | 限制 |
|---|---|
| 单文件大小 | 500MB |
| PDF 最大页数 | 无硬限制（按页计费） |
| 请求频率 | 根据套餐不同：10~60 次/分钟 |
| 并发连接 | 根据套餐不同：1~5 个 |
| 请求超时 | 600 秒（大文件处理） |
需要帮助？ 如有接入问题，请联系 15171576@qq.com 或致电 0596-2933183。
© 2026 OfficeClaw. All rights reserved. ｜ 闽ICP备2025100676号