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

Запит

POST https://api.ocrrouter.ai/v1/ocr із тілом JSON та заголовком Authorization: Bearer.

modelstringID моделі, як-от mistral/mistral-ocr, або auto.
file_urlstringПублічна URL-адреса PDF або зображення. Використовуйте один із параметрів: file_url, file_base64 або file_id.
file_base64stringФайл у форматі base64, до 20 МБ.
file_idstringID, отриманий від POST /v1/files, для більших файлів.
formatstringmarkdown (за замовчуванням), json, text, html, csv, docx або xlsx.
pagesstringДіапазон сторінок, наприклад 1-5,8. За замовчуванням — усі сторінки.
fallbacksstring[]Список ID моделей за порядком спроб, якщо перша модель зазнає помилки.
routestringДля моделі auto: quality (за замовчуванням), cheapest або fastest.
filenamestringНеобов'язкова назва, яка відображається в журналі активності.

Інші ендпоїнти:

  • GET /v1/models повертає список усіх моделей, їхні ціни та доступність. Ключ не потрібен.
  • POST /v1/files приймає multipart-завантаження з полем file і повертає file_id, дійсний протягом 24 годин.
  • GET /v1/requests/:id повертає попередній результат. Додайте ?format= із будь-яким форматом, щоб отримати результат в іншому вигляді.
  • GET /v1/credits повертає ваш баланс і використання за цим ключем.
  • POST /v1/keys/temporary повертає тимчасовий ключ із 50 кредитами. Без реєстрації, один на день.

Формати виводу

markdown

Увесь документ у форматі Markdown. Таблиці сформовано як GitHub-flavoured tables, формули обрамлено в $...$, а сторінки розділено тегом <!-- 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 містять таблиці (по одному аркушу на таблицю) або текстові рядки, якщо таблиць немає. 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Некоректний запит або непідтримуваний тип файлу.
401Ключ API відсутній або відкликаний.
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.

Запитання