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.

modelstringИдентификатор модели, например mistral/mistral-ocr, или auto.
file_urlstringПубличный URL файла PDF или изображения. Укажите один из параметров: file_url, file_base64 или file_id.
file_base64stringФайл в кодировке base64, до 20 МБ.
file_idstringИдентификатор, возвращаемый POST /v1/files, для файлов большего размера.
formatstringmarkdown (по умолчанию), json, text, html, csv, docx или xlsx.
pagesstringДиапазон страниц, например 1-5,8. По умолчанию — все страницы.
fallbacksstring[]Список моделей по порядку для повторной попытки, если первая модель вернет ошибку.
routestringПри model: 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-flavored Markdown, формулы обрамлены $...$, а страницы разделены комментариями <!-- 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 сохраняются таблицы (по одному листу на таблицу) либо строки текста, если таблиц нет. Вместо text можно указывать txt.

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Ни одна модель из цепочки fallbacks не смогла обработать запрос. Средства не списаны.
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.

Вопросы и ответы