OCRRouter

Tài liệu API

Hướng dẫn các khái niệm cốt lõi. Chi tiết từng endpoint và tham số có trong tài liệu tham khảo API.

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.

modelstringMã định danh model như mistral/mistral-ocr, hoặc auto.
file_urlstringURL 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_base64stringTệp dưới dạng base64, tối đa 20 MB.
file_idstringID trả về từ POST /v1/files, dùng cho các tệp lớn hơn.
formatstringmarkdown (mặc định), json, text, html, csv, docx hoặc xlsx.
pagesstringKhoảng trang cần xử lý, ví dụ: 1-5,8. Mặc định là toàn bộ các trang.
fallbacksstring[]Danh sách model ID để thử lần lượt nếu model đầu tiên gặp lỗi.
routestringKhi chọn model auto: quality (mặc định), cheapest hoặc fastest.
filenamestringTê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/models liệ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/files nhận tải lên dạng multipart với trường file và trả về một file_id có hiệu lực trong 24 giờ.
  • GET /v1/requests/:id trả 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/credits kiểm tra số dư credit và mức sử dụng của key này.
  • POST /v1/keys/temporary trả 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.

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

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.

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}}

Đị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

400Yêu cầu không đúng định dạng hoặc loại tệp không được hỗ trợ.
401API key bị thiếu hoặc đã bị thu hồi.
402Không đủ credit, hoặc key đã đạt đến hạn mức giới hạn.
413Tệp vượt quá kích thước cho phép của model này.
429Quá nhiều yêu cầu. Vui lòng thử lại sau khoảng thời gian được nêu trong header Retry-After.
502Tất cả các model trong chuỗi fallback đều thất bại. Bạn không bị trừ phí.
503Model bạn yêu cầu hiện chưa được kết nố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 mcp

Bản tóm tắt cho máy đọc của trang này có tại /llms.txt.

Câu hỏi thường gặp