OCRRouter

APIドキュメント

基本コンセプトのガイドです。すべてのエンドポイントとパラメータの詳細はAPIリファレンスに記載されています。

クイックスタート

APIキーを作成してファイルを送信します。新規アカウントには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"
  }'

リクエスト

JSONボディと Authorization: Bearer ヘッダーを付けて POST https://api.ocrrouter.ai/v1/ocr を実行します。

modelstringmistral/mistral-ocr などのモデルID、または auto。
file_urlstringPDFまたは画像の公開URL。file_url、file_base64、file_id のいずれかを使用します。
file_base64stringbase64形式のファイルデータ(最大20MB)。
file_idstring大きなファイル向けに POST /v1/files から返されたID。
formatstringmarkdown(デフォルト)、json、text、html、csv、docx、または xlsx。
pagesstringページ範囲(例: 1-5,8)。デフォルトは全ページ。
fallbacksstring[]最初のモデルが失敗した際に順次試行するモデルIDのリスト。
routestringmodel が auto の場合: quality(デフォルト)、cheapest、または fastest。
filenamestringアクティビティログに表示される任意のファイル名。

その他のエンドポイント:

  • GET /v1/models はすべてのモデル、料金、稼働状況を一覧表示します。キーは不要です。
  • POST /v1/files は file フィールドでのマルチパートアップロードを受け付け、24時間有効な file_id を返します。
  • GET /v1/requests/:id は過去の結果を取得します。?format= に出力形式を追加して別の形式で再取得することも可能です。
  • GET /v1/credits は残高とこのキーの使用状況を返します。
  • POST /v1/keys/temporary は50クレジット付きの一時キーを返します。登録不要で、1日1回利用可能です。

出力形式

markdown

ドキュメント全体をMarkdownとして出力します。表はGitHub仕様のテーブル、数式は $...$、ページ区切りは <!-- page:N --> で表されます。

json

どのモデルからも統一された構造(ページと、型付けされたブロック)で出力されます。ブロックタイプは heading、paragraph、list、table、formula、image、header、footer です。モデルから提供されない場合(現在提供中の全モデルを含む)、bbox、confidence、ページサイズは null になります。

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レスポンスに加え、ファイルを含む output オブジェクト(format、filename、mime_type、encoding、data)を返します。text、html、csv はUTF-8文字列(encoding: "utf8")、docx と xlsx はbase64(encoding: "base64")です。csv と xlsx には抽出された表(表ごとに1シート)、表がない場合はテキスト行が含まれます。txt も 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}}

ルーティングとフォールバック

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キーごとに個別のクレジット上限を設定できます。

エラー

400リクエストが不正であるか、ファイル形式がサポートされていません。
401APIキーがないか、無効化されています。
402クレジットが不足しているか、キーのクレジット上限に達しました。
413ファイルサイズがこのモデルの上限を超えています。
429リクエスト数が上限を超えました。Retry-After ヘッダーに記載された時間以降に再試行してください。
502フォールバックチェーンのすべてのモデルが失敗しました。料金は発生しません。
503リクエストされたモデルは現在接続されていません。

エージェント、MCP、CLI

コーディングエージェントは会員登録なしで OCRRouter を利用できます。CLIおよびMCPサーバーは初回利用時に50クレジット付きの一時キーを要求し、~/.ocrrouter/config.json に保存します。独自のキーを使用する場合は OCRROUTER_API_KEY を設定してください。

# CLI
npx ocrrouter invoice.pdf --format markdown

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

このページのマシンリーダブルな要約は /llms.txt にあります。

よくある質問