OCRRouter

Dokumentasi API

Panduan untuk konsep utama. Setiap endpoint dan parameter tersedia di referensi API.

Quickstart

Buat API key, lalu kirim berkas. Akun baru dimulai dengan 50 kredit gratis.

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

Permintaan

POST https://api.ocrrouter.ai/v1/ocr dengan body JSON dan header Authorization: Bearer.

modelstringID model seperti mistral/mistral-ocr, atau auto.
file_urlstringURL publik dari PDF atau gambar. Gunakan salah satu dari file_url, file_base64, atau file_id.
file_base64stringBerkas dalam format base64, hingga 20 MB.
file_idstringID yang dikembalikan oleh POST /v1/files, untuk berkas yang lebih besar.
formatstringmarkdown (default), json, text, html, csv, docx, atau xlsx.
pagesstringRentang halaman, contohnya 1-5,8. Default ke semua halaman.
fallbacksstring[]Daftar ID model yang dicoba berurutan jika model pertama gagal.
routestringJika model auto: quality (default), cheapest, atau fastest.
filenamestringNama opsional yang ditampilkan di log aktivitas Anda.

Endpoint lainnya:

  • GET /v1/models menampilkan daftar semua model, harganya, dan status ketersediaannya. Tidak memerlukan API key.
  • POST /v1/files menerima unggahan multipart dengan kolom file dan mengembalikan file_id yang berlaku selama 24 jam.
  • GET /v1/requests/:id mengembalikan hasil sebelumnya. Tambahkan ?format= dengan format output apa pun untuk mendapatkannya dalam format lain.
  • GET /v1/credits menampilkan saldo Anda dan penggunaan API key ini.
  • POST /v1/keys/temporary mengembalikan API key sementara dengan 50 kredit. Tanpa daftar, satu per hari.

Format output

markdown

Seluruh dokumen sebagai Markdown. Tabel menggunakan format GitHub-flavored markdown, rumus diapit oleh $...$, dan halaman dipisahkan oleh <!-- page:N -->.

json

Struktur yang seragam dari setiap model: halaman, masing-masing dengan blok yang memiliki tipe. Tipe blok meliputi heading, paragraph, list, table, formula, image, header, dan footer. bbox, confidence, dan ukuran halaman bernilai null jika model tidak menyediakannya, seperti pada model yang aktif saat ini.

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

Respons Markdown beserta objek output yang memuat berkas: format, filename, mime_type, encoding, dan data. text, html, dan csv berupa string UTF-8 (encoding: "utf8"); docx dan xlsx berupa base64 (encoding: "base64"). csv dan xlsx berisi tabel (satu sheet per tabel), atau baris teks jika tidak ada tabel. txt juga diterima sebagai alias dari 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}}

Perutean dan fallback

Atur model ke auto dan kami akan memilih model terbaik untuk setiap dokumen. Gunakan route untuk menentukan prioritas: cheapest, fastest, atau quality.

Tambahkan fallbacks agar sistem tetap berjalan saat terjadi gangguan. Jika model pertama error atau terkena rate limit, model berikutnya akan dijalankan. Respons akan memberi tahu model mana yang menjawab, dan Anda hanya membayar untuk model tersebut.

{"model": "mistral/mistral-ocr","fallbacks": ["google/gemini-flash", "tesseract/tesseract"],"file_url": "https://example.com/report.pdf"}

Kredit

Setiap model memiliki tarif dalam kredit per halaman. $1 membeli 1,000 kredit dan tidak memiliki masa kedaluwarsa. Setiap respons menyertakan usage.credits.

  • Hasil yang gagal dan kosong gratis.
  • Mengirim berkas yang sama ke model yang sama lagi akan diambil dari cache secara gratis.
  • Setiap API key dapat memiliki batas kredit tersendiri.

Error

400Format permintaan salah atau jenis berkas tidak didukung.
401API key tidak disertakan atau telah dicabut.
402Kredit tidak mencukupi, atau API key telah mencapai batas kreditnya.
413Ukuran berkas melebihi batas untuk model ini.
429Terlalu banyak permintaan. Coba lagi setelah waktu yang tertera pada header Retry-After.
502Semua model dalam rantai fallback gagal. Anda tidak dikenakan biaya.
503Model yang Anda minta belum terhubung.

Agent, MCP, dan CLI

Coding agent dapat menggunakan OCRRouter tanpa tahap pendaftaran. CLI dan server MCP meminta API key sementara dengan 50 kredit pada penggunaan pertama dan menyimpannya di ~/.ocrrouter/config.json. Atur OCRROUTER_API_KEY untuk menggunakan API key Anda sendiri.

# CLI
npx ocrrouter invoice.pdf --format markdown

# MCP server for Claude Code
claude mcp add ocrrouter -- npx ocrrouter mcp

Ringkasan halaman ini yang dapat dibaca mesin tersedia di /llms.txt.

Pertanyaan