快速上手
创建一个 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。