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 тяло и заглавна част (header) Authorization: Bearer.

modelstringИдентификатор на модел като mistral/mistral-ocr или auto.
file_urlstringПубличен URL на PDF или изображение. Използвайте едно от: file_url, file_base64 или file_id.
file_base64stringФайлът като base64, до 20 MB.
file_idstringID, върнат от POST /v1/files, за по-големи файлове.
formatstringmarkdown (по подразбиране), json, text, html, csv, docx или xlsx.
pagesstringДиапазон от страници, например 1-5,8. По подразбиране са всички страници.
fallbacksstring[]Идентификатори на модели, които да се опитат подред, ако първият модел се провали.
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.

Въпроси