快速上手
建立一個 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 請求頭。
| model | string | 模型 ID,例如 mistral/mistral-ocr,或 auto。 |
| file_url | string | PDF 或圖片的公開 URL。file_url、file_base64、file_id 三選一。 |
| file_base64 | string | base64 編碼的檔案,最大 20 MB。 |
| file_id | string | POST /v1/files 返回的 ID,用於較大的檔案。 |
| format | string | markdown(預設)、json、text、html、csv、docx 或 xlsx。 |
| pages | string | 頁碼範圍,例如 1-5,8。預設全部頁面。 |
| fallbacks | string[] | 第一個模型失敗時依次嘗試的模型 ID。 |
| route | string | model 為 auto 時使用:quality(預設)、cheapest 或 fastest。 |
| filename | string | 可選,顯示在你的呼叫記錄中的檔名。 |
其他介面:
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,目前已上線的模型都是這種情況。
{"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。
{"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 都可以單獨設定點數上限。
錯誤
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。