OCRRouter

API dokümantasyonu

Temel kavramlara yönelik rehberler. Tüm uç noktalar ve parametreler API referansında yer alır.

Hızlı başlangıç

Bir API anahtarı oluşturun ve ardından bir dosya gönderin. Yeni hesaplar 50 ücretsiz krediyle başlar.

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

İstek

JSON gövdesi ve bir Authorization: Bearer başlığı ile POST https://api.ocrrouter.ai/v1/ocr.

modelstringmistral/mistral-ocr gibi bir model kimliği ya da auto.
file_urlstringBir PDF veya görselin herkese açık URL'si. file_url, file_base64 veya file_id parametrelerinden birini kullanın.
file_base64string20 MB'a kadar base64 formatında dosya.
file_idstringDaha büyük dosyalar için POST /v1/files tarafından döndürülen kimlik.
formatstringmarkdown (varsayılan), json, text, html, csv, docx veya xlsx.
pagesstringSayfa aralığı, örneğin 1-5,8. Varsayılan olarak tüm sayfalar.
fallbacksstring[]İlk model başarısız olursa sırayla denenecek model kimlikleri.
routestringmodel auto iken: quality (varsayılan), cheapest veya fastest.
filenamestringEtkinlik günlüğünüzde gösterilecek isteğe bağlı ad.

Diğer uç noktalar:

  • GET /v1/models her modeli, fiyatını ve kullanılabilir olup olmadığını listeler. Anahtar gerekmez.
  • POST /v1/files, file alanına sahip çok parçalı (multipart) bir yükleme alır ve 24 saat geçerli bir file_id döndürür.
  • GET /v1/requests/:id önceki bir sonucu döndürür. Başka bir formatta almak için herhangi bir çıktı formatıyla ?format= ekleyin.
  • GET /v1/credits bakiyenizi ve bu anahtarın kullanımını döndürür.
  • POST /v1/keys/temporary 50 krediye sahip geçici bir anahtar döndürür. Kayıt gerekmez, günde bir adet.

Çıktı formatları

markdown

Markdown formatında tüm belge. Tablolar GitHub uyumlu tablolardır, formüller $...$ içine alınır ve sayfalar <!-- page:N --> ile ayrılır.

json

Her modelden aynı yapı: her biri tiplendirilmiş bloklara sahip sayfalar. Blok tipleri heading, paragraph, list, table, formula, image, header ve footer şeklindedir. Model bunları sağlamadığında bbox, confidence ve sayfa boyutu null olur; bugün yayında olan modeller için durum böyledir.

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

Markdown yanıtına ek olarak bir dosya barındıran output nesnesi: format, filename, mime_type, encoding ve data. text, html ve csv UTF-8 dizeleridir (encoding: "utf8"); docx ve xlsx base64 formatındadır (encoding: "base64"). csv ve xlsx tabloları (her tablo için bir sayfa) veya tablo yoksa metin satırlarını içerir. txt, text için alternatif ad olarak kabul edilir.

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

Yönlendirme ve yedekler

model değerini auto olarak ayarlayın, her belge için modeli biz seçelim. Sizin için neyin önemli olduğunu belirtmek için route parametresini kullanın: cheapest, fastest veya quality.

Kesintiler sırasında çalışmaya devam etmek için fallbacks ekleyin. İlk model hata verirse veya hız sınırına takılırsa bir sonraki model çalışır. Yanıt hangi modelin yanıt verdiğini bildirir ve yalnızca onun için ödeme yaparsınız.

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

Krediler

Her modelin sayfa başına kredi cinsinden bir fiyatı vardır. 1 $ ile 1,000 kredi satın alınır ve süreleri dolmaz. Her yanıt usage.credits bilgisini içerir.

  • Başarısız ve boş sonuçlar ücretsizdir.
  • Aynı dosyanın aynı modele tekrar gönderilmesi önbellekten ücretsiz olarak sunulur.
  • Her API anahtarının kendi kredi limiti olabilir.

Hatalar

400İstek hatalı biçimlendirilmiş veya dosya türü desteklenmiyor.
401API anahtarı eksik veya iptal edilmiş.
402Yetersiz kredi veya anahtar kredi limitine ulaştı.
413Dosya bu modelin sınırından daha büyük.
429Çok fazla istek. Retry-After başlığındaki sürenin ardından tekrar deneyin.
502Yedekleme zincirindeki her model başarısız oldu. Ücretlendirilmezsiniz.
503İstediğiniz model henüz bağlı değil.

Ajanlar, MCP ve CLI

Kodlama ajanları kayıt adımına gerek kalmadan OCRRouter kullanabilir. CLI ve MCP sunucusu ilk kullanımda 50 kredili geçici bir anahtar ister ve bunu ~/.ocrrouter/config.json dosyasına kaydeder. Kendi anahtarınızı kullanmak için OCRROUTER_API_KEY ortam değişkenini ayarlayın.

# CLI
npx ocrrouter invoice.pdf --format markdown

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

Bu sayfanın makinelerce okunabilir bir özeti /llms.txt adresindedir.

Sorular