Bắt đầu nhanh
Tạo API key, sau đó gửi một tệp. Tài khoản mới bắt đầu với 50 credit miễn phí.
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"
}'Yêu cầu
POST https://api.ocrrouter.ai/v1/ocr với body dạng JSON và header Authorization: Bearer.
| model | string | Mã định danh model như mistral/mistral-ocr, hoặc auto. |
| file_url | string | URL công khai của tệp PDF hoặc ảnh. Sử dụng một trong các trường: file_url, file_base64 hoặc file_id. |
| file_base64 | string | Tệp dưới dạng base64, tối đa 20 MB. |
| file_id | string | ID trả về từ POST /v1/files, dùng cho các tệp lớn hơn. |
| format | string | markdown (mặc định), json, text, html, csv, docx hoặc xlsx. |
| pages | string | Khoảng trang cần xử lý, ví dụ: 1-5,8. Mặc định là toàn bộ các trang. |
| fallbacks | string[] | Danh sách model ID để thử lần lượt nếu model đầu tiên gặp lỗi. |
| route | string | Khi chọn model auto: quality (mặc định), cheapest hoặc fastest. |
| filename | string | Tên tệp tùy chọn hiển thị trong nhật ký hoạt động của bạn. |
Các endpoint khác:
GET /v1/modelsliệt kê tất cả các model, giá thành và trạng thái khả dụng. Không cần API key.POST /v1/filesnhận tải lên dạng multipart với trườngfilevà trả về mộtfile_idcó hiệu lực trong 24 giờ.GET /v1/requests/:idtrả về kết quả đã xử lý trước đó. Thêm?format=với định dạng mong muốn để nhận kết quả ở định dạng khác.GET /v1/creditskiểm tra số dư credit và mức sử dụng của key này.POST /v1/keys/temporarytrả về key tạm thời với 50 credit. Không cần đăng ký, mỗi ngày một lần.
Định dạng đầu ra
markdown
Toàn bộ tài liệu dưới dạng Markdown. Bảng biểu theo định dạng GitHub-flavoured markdown, công thức toán nằm trong $...$, và các trang được phân tách bằng <!-- page:N -->.
json
Cấu trúc đồng nhất từ mọi model: các trang, mỗi trang gồm các khối định kiểu. Các kiểu khối bao gồm heading, paragraph, list, table, formula, image, header và footer. bbox, confidence và kích thước trang sẽ có giá trị null khi model không hỗ trợ, đây cũng là trường hợp của các model đang hoạt động hiện nay.
{"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
Phản hồi Markdown kèm theo một đối tượng output chứa tệp: format, filename, mime_type, encoding và data. text, html và csv là chuỗi ký tự UTF-8 (encoding: "utf8"); docx và xlsx ở dạng base64 (encoding: "base64"). csv và xlsx chứa các bảng biểu (mỗi sheet một bảng), hoặc các dòng văn bản nếu không có bảng. txt cũng được chấp nhận tương đương với 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}}Định tuyến và fallbacks
Đặt model thành auto và chúng tôi sẽ tự động chọn model phù hợp nhất cho từng tài liệu. Dùng route để chọn tiêu chí ưu tiên: cheapest (rẻ nhất), fastest (nhanh nhất) hoặc quality (chất lượng tốt nhất).
Thêm fallbacks để đảm bảo hệ thống luôn hoạt động ổn định kể cả khi có sự cố. Nếu model đầu tiên gặp lỗi hoặc vượt giới hạn tần suất, model tiếp theo sẽ chạy thay thế. Phản hồi sẽ cho biết model nào đã xử lý, và bạn chỉ trả phí cho duy nhất model đó.
{"model": "mistral/mistral-ocr","fallbacks": ["google/gemini-flash", "tesseract/tesseract"],"file_url": "https://example.com/report.pdf"}Credit
Mỗi model có giá tính theo credit cho từng trang. $1 mua được 1,000 credit và không bao giờ hết hạn. Mỗi phản hồi đều đi kèm thông tin usage.credits.
- Các kết quả lỗi và kết quả rỗng hoàn toàn miễn phí.
- Gửi lại cùng một tệp đến cùng một model sẽ được trả về từ bộ nhớ đệm (cache) miễn phí.
- Mỗi API key có thể thiết lập hạn mức credit riêng.
Mã lỗi
Agent, MCP và CLI
Các coding agent có thể sử dụng OCRRouter mà không cần bước đăng ký. CLI và MCP server sẽ tự động yêu cầu một key tạm thời có 50 credit trong lần đầu sử dụng và lưu tại ~/.ocrrouter/config.json. Đặt biến môi trường OCRROUTER_API_KEY nếu bạn muốn dùng key riêng của mình.
# CLI
npx ocrrouter invoice.pdf --format markdown
# MCP server for Claude Code
claude mcp add ocrrouter -- npx ocrrouter mcpBản tóm tắt cho máy đọc của trang này có tại /llms.txt.