OCRRouter

API 文档

这里讲主要概念。每个接口和参数的细节见 API 参考。

快速上手

创建一个 API Key,然后发送文件。新账户赠送 50 免费积分。

curl https://api.ocrrouter.ai/v1/ocr \
  -H "Authorization: Bearer $OCRROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "file_url": "https://example.com/invoice.pdf",
    "format": "markdown"
  }'

请求

POST https://api.ocrrouter.ai/v1/ocr,请求体为 JSON,并带上 Authorization: Bearer 请求头。

modelstring模型 ID,例如 mistral/mistral-ocr,或 auto。
file_urlstringPDF 或图片的公开 URL。file_url、file_base64、file_id 三选一。
file_base64stringbase64 编码的文件,最大 20 MB。
file_idstringPOST /v1/files 返回的 ID,用于较大的文件。
formatstringmarkdown(默认)、json、text、html、csv、docx 或 xlsx。
pagesstring页码范围,例如 1-5,8。默认全部页面。
fallbacksstring[]第一个模型失败时依次尝试的模型 ID。
routestringmodel 为 auto 时使用:quality(默认)、cheapest 或 fastest。
filenamestring可选,显示在你的调用记录中的文件名。

其他接口:

  • GET /v1/models 列出所有模型、价格以及是否可用。无需 Key。
  • POST /v1/files 接收带 file 字段的 multipart 上传,返回 24 小时内有效的 file_id。
  • GET /v1/requests/:id 返回之前的结果。加上 ?format= 并填任一输出格式,即可换成该格式。
  • GET /v1/credits 返回你的余额和当前 Key 的用量。
  • POST /v1/keys/temporary 返回一个带 50 积分的临时 Key。无需注册,每天一个。

输出格式

markdown

整份文档输出为 Markdown。表格为 GitHub 风格表格,公式用 $...$ 包裹,页面之间用 <!-- page:N --> 分隔。

json

每个模型返回相同的结构:按页组织,每页包含带类型的块。块类型有 heading、paragraph、list、table、formula、image、header 和 footer。模型不提供时,bbox、confidence 和页面尺寸为 null,目前已上线的模型都是这种情况。

200result
{"id": "req_8f2c1a41d0b3c7e9a2","model": "mistral/mistral-ocr","format": "json","attempts": [{ "model": "mistral/mistral-ocr", "ok": true, "ms": 1180 }],"pages": [{"index": 1,"width": null,"height": null,"blocks": [{"type": "heading","level": 1,"text": "Invoice INV-2041","bbox": null,"confidence": null},{"type": "paragraph","text": "Acme Supply Co.\n14 Harbour Street, Sydney NSW 2…","bbox": null,"confidence": null},{"type": "table","rows": [["Item", "Qty", "Unit price", "Amount"],["A4 paper, 5 reams", "4", "$24.00", "$96.00"]],"markdown": "| Item | Qty | Unit price | Amount |\n|---|---|-…","bbox": null,"confidence": null}]}],"usage": {"pages": 1,"credits": 25,"latency_ms": 1180,"cached": false}}

text, html, csv, docx, xlsx

在 Markdown 响应之外多一个 output 对象,里面是文件:format、filename、mime_type、encoding 和 data。text、html、csv 是 UTF-8 字符串(encoding: "utf8");docx、xlsx 是 base64(encoding: "base64")。csv 和 xlsx 放表格(每个表格一个工作表),没有表格时放文本行。txt 等同于 text。

200result
{"id": "req_8f2c1a41d0b3c7e9a2","model": "mistral/mistral-ocr","format": "docx","attempts": [{ "model": "mistral/mistral-ocr", "ok": true, "ms": 1180 }],"markdown": "<!-- page:1 -->\n# Invoice INV-2041\n…","pages": [{ "index": 1, "markdown": "# Invoice INV-2041\n…" }],"output": {"format": "docx","filename": "invoice.docx","mime_type": "application/vnd.openxmlformats-officedocument.w…","encoding": "base64","data": "UEsDBBQAAAAIA…"},"usage": {"pages": 1,"credits": 25,"latency_ms": 1180,"cached": false}}

路由和备用模型

把 model 设为 auto,我们会为每份文档选择模型。用 route 指定你更看重什么:cheapest、fastest 或 quality。

加上 fallbacks,服务中断时也能继续工作。第一个模型出错或被限流时,会运行下一个。响应会告诉你是哪个模型返回的结果,你只为这个模型付费。

{"model": "mistral/mistral-ocr","fallbacks": ["google/gemini-flash", "tesseract/tesseract"],"file_url": "https://example.com/report.pdf"}

积分

每个模型都有按页计算的积分价格。1 美元可买 1,000 积分,积分永不过期。每个响应都包含 usage.credits。

  • 失败和空结果不收费。
  • 把同一文件再次发给同一模型时,从缓存返回,不收费。
  • 每个 API Key 都可以单独设置积分上限。

错误

400请求格式错误,或文件类型不受支持。
401API Key 缺失或已被撤销。
402积分不足,或 Key 已达到积分上限。
413文件超过该模型的大小上限。
429请求过多。请在 Retry-After 响应头给出的时间后重试。
502备用链中的所有模型都失败了。不会收费。
503你请求的模型尚未接入。

Agent、MCP 和 CLI

编程 Agent 无需注册即可使用 OCRRouter。CLI 和 MCP 服务器在首次使用时会申请一个带 50 积分的临时 Key,并保存在 ~/.ocrrouter/config.json。设置 OCRROUTER_API_KEY 即可使用你自己的 Key。

# CLI
npx ocrrouter invoice.pdf --format markdown

# MCP server for Claude Code
claude mcp add ocrrouter -- npx ocrrouter mcp

本页的机器可读摘要见 /llms.txt。

常见问题