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。

常見問題