Русский · English
Готовые примеры работы с OCR API на шести языках: Python, TypeScript (Node.js), Go, Java, C#, PHP. Извлечь содержимое страницы из изображения одним HTTP-запросом: картинка уходит в Base64, обратно приходит разметка Markdown — заголовки, абзацы, таблицы и формулы с сохранённой структурой страницы. Это не «буквы одной строкой». Единственный POST-сервис Atlorium, и в каждом примере показано, как корректно собрать и отправить JSON-тело с картинкой внутри.
Каждый пример запускается сразу — без регистрации, без ключа, без карты. В коде зашит публичный демо-ключ, а в репозитории лежит образец картинки sample.png — искать своё изображение не нужно.
git clone https://github.com/atlorium-api/image-ocr-api-client
cd image-ocr-api-client/python && pip install -r requirements.txt && python main.pyДемо-ключ: сервис ВЕРНЁТ СГЕНЕРИРОВАННУЮ СТРАНИЦУ (мок), а не результат
настоящего распознавания вашего изображения. Контракт, разметка и формат
ответа — настоящие; качество распознавания проверяется боевым ключом.
Файл: sample.png · PNG · 240 байт
Формат ответа: markdown — содержимое страницы с разметкой
Структура: заголовков - 1, строк таблиц - 4, строк текста - 9
Время обработки: 1183 мс
Режим: document, единиц работы: 4
--- начало распознанного текста ---
# Счёт-фактура № 4821 от 14.03.2025
**Поставщик:** ООО «Гарант-Сервис»
**Покупатель:** ЗАО «Северный ветер»
| № | Наименование | Кол-во | Цена | Сумма |
|---|---|---|---|---|
| 1 | Кабель силовой ВВГнг 3х2.5 | 7 | 1234,50 | 8641,50 |
| 2 | Автомат защиты 16А | 3 | 890,00 | 2670,00 |
| 3 | Щит распределительный ЩРН-24 | 12 | 445,20 | 5342,40 |
**Итого:** 16653,90 руб.
--- конец распознанного текста ---
Вердикт: страница распознана полностью — запрос тарифицируется.
Демо-ключ не читает вашу картинку. Он возвращает сгенерированный документ (на
sample.pngнаписано «ATLORIUM», а в ответе будет накладная или счёт). Это осознанно: в песочнице вы проверяете контракт, формат ответа и свою интеграцию, а не качество распознавания. При этом форма ответа настоящая — заголовок, абзацы и Markdown-таблица со сходящимся итогом, ровно как у боевого ключа, поэтому разбор, написанный на песочнице, продолжит работать и в бою. Ответ мока детерминирован (seed берётся из самой картинки), так что на нём удобно писать стабильные тесты.
- Оцифровка документов и сканов — превратить фотографию накладной, счёта, акта или анкеты в текст, пригодный для поиска и ввода в учётную систему.
- Перенос таблиц из сканов — табличная часть возвращается Markdown-таблицей со строками и столбцами, а не «кашей» из чисел в одну строку.
- Учебные и научные материалы — математические выражения распознаются как формулы, а не как случайный набор символов.
- Разметка датасетов — вытащить текст с изображений массово, а не глазами.
- Доступность (accessibility) — извлечение текста с изображений для незрячих пользователей.
Примеры не просто печатают JSON, а применяют ответ: в каждом есть функция extractText(), которая читает файл с диска, проверяет формат и размер локально, кодирует в Base64, отправляет POST — и выносит вердикт по трём полям сразу.
| Поле | Что с ним делает extractText() |
|---|---|
recognized |
Читаемого текста не нашлось — сообщаем об этом и советуем, что улучшить в скане. Деньги за такой запрос не списываются. |
format |
markdown — разбираем разметку страницы и печатаем её структуру (сколько заголовков, строк таблиц, строк текста; функция analyzeLayout()). plain — печатаем строку как есть. Незнакомое значение трактуется как plain — так предписывает контракт, и это заранее защищает интеграцию от пополнения списка форматов. |
truncated |
Ответ оборван по длине: страница распознана не полностью. Примеры не прячут это в лог, а поднимают до вердикта «результат требует ручной проверки». |
Про truncated стоит сказать отдельно. Это самое коварное поле контракта: обрезанный текст выглядит совершенно нормальным — заголовок на месте, таблица на месте, — и без явной проверки потеря части документа проходит незамеченной, а дальше по конвейеру уезжает неполный документ. Проверка стоит одной строки кода, поэтому она есть во всех шести примерах.
recognized=false означает: читаемого текста на изображении найти не удалось — и деньги за такой запрос не списываются. То же самое при 503: за сбой или перегрузку на нашей стороне вы не платите, и при 400 — за собственный некорректный запрос тоже. Практический смысл: нечитаемую страницу можно прогнать, увидеть recognized=false, улучшить скан (выпрямить перекос, убрать тень от сгиба, поднять контраст) и повторить — счёт от этого не вырастет. Именно поэтому recognized проверяется во всех шести примерах первым делом.
Проверить API вообще без клонирования (картинка кодируется в Base64 прямо в команде):
curl -X POST "https://atlorium.com/api/Ocr/image-to-text" \
-H "Authorization: Bearer ak_sandbox_demo_mockdata_v1" \
-H "Content-Type: application/json" \
-d "{\"image\":\"$(base64 -w0 sample.png)\"}"{
"recognized": true,
"text": "# Счёт-фактура № 4821 от 14.03.2025\n\n**Поставщик:** ...",
"format": "markdown",
"truncated": false,
"mode": "document",
"units": 4,
"elapsedMs": 1183
}| Язык | Запуск | Требуется |
|---|---|---|
| Python | pip install -r requirements.txt && python main.py |
Python 3.10+ |
| TypeScript / Node.js | npm install && npm start |
Node.js 20+ |
| Go | go run . |
Go 1.22+ |
| Java | java Main.java |
JDK 17+ (без зависимостей) |
| C# | dotnet run |
.NET 8+ |
| PHP | php main.php |
PHP 8.1+ |
Свою картинку — аргументом: python main.py /путь/к/scan.jpg
Режим распознавания — флагом --mode: python main.py ../sample.png --mode digits (значения: auto, document, table, formula, line, digits; по умолчанию auto).
Без аргумента берётся sample.png из корня репозитория — путь ../sample.png одинаково резолвится из любой языковой подпапки.
Ключ передаётся в заголовке Authorization:
Authorization: Bearer ВАШ_КЛЮЧ
| Ключ | Что делает |
|---|---|
ak_sandbox_demo_mockdata_v1 |
Демо-ключ. Публичный, один на всех. Возвращает мок — сгенерированный документ в настоящем формате ответа, а не распознавание вашей картинки. Денег не списывает, регистрации не требует. Ответы детерминированы — на них можно писать стабильные тесты. |
| Боевой ключ | Настоящее распознавание. Получить в личном кабинете: atlorium.com |
Переход на боевой ключ не требует правок в коде — все примеры читают переменную окружения:
export ATLORIUM_API_KEY="ak_ваш_боевой_ключ"Каждый ответ песочницы помечен заголовком X-Atlorium-Sandbox: true — перепутать мок с реальным распознаванием невозможно.
Базовый адрес: https://atlorium.com
| Метод | Путь | Назначение |
|---|---|---|
POST |
/api/Ocr/image-to-text |
Распознать содержимое страницы. Единственный эндпоинт сервиса |
Тело запроса — JSON (ImageOcrRequest):
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
image |
string | да | Картинка в Base64. Принимается и «голый» base64, и data-URL вида data:image/png;base64,... |
mode |
string | нет | Режим распознавания. По умолчанию auto — сервис сам различает короткую строку и страницу. Значения: auto, document (страница целиком), table (только таблица), formula (формула в LaTeX), line (строка из букв и цифр), digits (только цифры). Неизвестное значение сервис отвергает кодом 400, а не подменяет молча |
Других полей у запроса нет.
{
"image": "iVBORw0KGgoAAAANSUhEUgAA..."
}ImageOcrResponse:
| Поле | Тип | Что содержит |
|---|---|---|
recognized |
bool | Ключевое поле. true — содержимое страницы распознано и лежит в text. false — читаемого текста не нашлось; плата не взимается |
text |
string | null | Содержимое страницы. null, если recognized=false |
format |
string | Что именно лежит в text: "markdown" — страница с разметкой (заголовки, абзацы, списки, таблицы); "plain" — простая строка (режимы line/digits); "latex" — формула. Выбирайте ветку разбора по этому полю, а не по содержимому. Список значений может пополниться — незнакомое значение разумно обрабатывать как plain |
truncated |
bool | true — текст оборван по внутреннему пределу длины, страница распознана не полностью. Проверять обязательно: обрезанный ответ внешне неотличим от полного, и без этой проверки потеря части документа пройдёт незамеченной. Встречается редко — на нестандартно плотных страницах |
mode |
string | Режим, в котором изображение распознано на самом деле. Совпадает с запрошенным, кроме auto — там видно решение сервиса (line для короткой строки, document для страницы). Если результат оказался не тем, что ожидался, смотреть надо в первую очередь сюда |
units |
int | Единицы работы, в которые обошёлся запрос: по ним он и тарифицирован. Короткая строка — всегда 1; страница — столько, сколько на ней распознано областей. Позволяет свести расход по пакету, не заглядывая в личный кабинет |
elapsedMs |
int64 | Время обработки в миллисекундах — включая ожидание в очереди, а не только само распознавание. Поэтому по нему удобно подбирать степень параллелизма пакетной обработки: растёт при неизменных картинках — конвейер упёрся в пропускную способность, и увеличивать число потоков дальше бессмысленно. По спеке допустимы и число, и строка — примеры принимают оба варианта |
Честно и заранее, чтобы не тратить ваше время:
- Только растровые изображения — PNG, JPEG, GIF, BMP, WEBP, TIFF. PDF на вход не принимается: многостраничный файл нужно отрендерить в страницы-картинки и отправлять постранично. Заодно вы сами управляете dpi и цветом, то есть скоростью обработки пакета. Все шесть примеров проверяют сигнатуру файла и отдельно сообщают про PDF, а не молча падают.
- Размер картинки — до 10 МБ в декодированном виде (то есть до кодирования в Base64). Скан листа A4 в 300 dpi укладывается с запасом. Больше — сервис отвечает
400, запрос не тарифицируется. Примеры проверяют размер локально, чтобы не тратить запрос впустую. Это предел, а не рекомендация: выше 300 dpi точность уже не растёт, разумный диапазон — 150–300 dpi. - Координат блоков в ответе нет. Структура страницы приезжает разметкой внутри
text; отдельных полей под координаты слов или список вариантов распознавания не предусмотрено. - Рукописный текст не заявляется. Сервис рассчитан на печатные документы. Рукописную строку он может прочитать, а может выдать правдоподобную ерунду, и отличить одно от другого по ответу нельзя.
- Оценки уверенности (confidence) нет. Есть только
recognized: да или нет. Порог «отправить оператору при уверенности ниже 0,8» построить не на чем — его роль выполняют проверки формата и контрольные суммы реквизитов у вас на стороне. - Юридической значимости у результата нет. Распознанный текст — удобная копия для поиска и ввода, а не документ. Это распознавание, а не проверка подлинности: сверять данные с оригиналом нужно вам.
- Обрыв по длине (
truncated) в песочнице воспроизвести нельзя — мок всегда укладывается в предел. Эту ветку приходится писать «вслепую», и именно она подведёт в бою, если её пропустить. Поэтому она есть во всех шести примерах. - Демо-ключ не показывает качество распознавания. Он отдаёт мок: сгенерированный документ вместо содержимого вашей картинки. В песочнице проверяется контракт и интеграция; точность — только на боевом ключе.
| Код | Причина | Что делать |
|---|---|---|
400 |
Картинка не передана, битый Base64 или размер больше 10 МБ | Проверьте кодирование и размер. Запрос не тарифицируется |
401 |
Ключ отсутствует, просрочен или недействителен | Проверьте заголовок Authorization |
402 |
Недостаточно кредитов на балансе | Пополнить на atlorium.com |
429 |
Превышен rate-limit | Повторить с задержкой. В примерах есть потолок ожидания: дольше него не спим, а честно сообщаем, что квота исчерпана, и выходим |
503 |
Сервис временно недоступен или перегружен | Повторить позже. За сбой на нашей стороне деньги не списываются |
Во всех шести примерах коды разложены в человекочитаемые причины — смотрите класс AtloriumError.
Отдельно: recognized=false — это не ошибка, а штатный ответ 200. Изображение обработано, но читаемого текста на нём не нашлось. Плата не берётся.
Оплата pay-as-you-go, без подписки: платите только за успешно распознанные страницы, причём по фактическому объёму — в единицах работы (поле units): короткая строка это одна единица, плотная страница — несколько. Нераспознанная картинка бесплатна.
Лимиты в песочнице — те же, что получит зарегистрированный пользователь: это сделано намеренно, чтобы условия были видны до оплаты, а не после. Отличие боевого ключа в том, что лимит считается по ключу, а не по общему публичному IP демо-ключа.
Актуальные цены и лимиты: atlorium.com/pricing
Как отправить картинку в API? Прочитать файл в байты, закодировать в Base64 и положить в поле image JSON-тела POST-запроса. Ровно это и делает функция extractText() в каждом из шести примеров — можно скопировать целиком.
В каком виде приходит результат? Обычный режим возвращает содержимое страницы в разметке Markdown: заголовки, абзацы, списки, таблицы, формулы. Поле format сообщает это явно, чтобы не приходилось угадывать разбор по содержимому.
Распознаются ли таблицы? Да. Табличная часть возвращается Markdown-таблицей с сохранением строк, столбцов и порядка чтения — отдельно вырезать ячейки не требуется. Значения из таблицы всё равно стоит проверить у себя: сумма строк должна сходиться с итогом.
Можно ли отправить data-URL из браузера? Да. Строка вида data:image/png;base64,iVBORw0... принимается как есть — префикс сервис срежет сам.
Распознаёт ли API текст из PDF? Нет. Сервис работает только с растровым изображением страницы. PDF нужно предварительно отрендерить в картинки и отправлять их по одной.
Поддерживается ли русский язык? Да, наравне с английским и ещё несколькими языками.
Что делать, если recognized=false? Ничего не платить — за такой запрос деньги не списываются. Улучшите скан: поднимите разрешение (150–300 dpi), выпрямите перекос, уберите тень от сгиба, увеличьте контраст. Повторять тот же файл без изменений бесполезно — он даст тот же результат.
Что делать, если truncated=true? Считать страницу распознанной не полностью и отправить её на ручную сверку. Если такое повторяется на однотипных документах — разрежьте плотную страницу на части и распознайте их по отдельности.
Какой максимальный размер картинки? 10 МБ в декодированном виде. Скан A4 в 300 dpi проходит с запасом, поэтому специально сжимать страницу не нужно. Поднимать разрешение выше 300 dpi смысла нет: точность не растёт, а обработка занимает больше времени — на пакете это заметно.
Обязательна ли регистрация, чтобы попробовать? Нет. Демо-ключ публичный и работает без аккаунта — но возвращает мок, а не распознавание вашей картинки.
Распознанный документ обычно нужно с чем-то сверить. Из того же аккаунта и тем же ключом доступны:
- ЕГРЮЛ/ЕГРИП — проверка контрагента по ИНН/ОГРН: статус, адрес, капитал
- ИИ-чат — модели, сессии, суммаризация текста
- Справочник БИК ЦБ РФ — реквизиты банка и контрольный ключ расчётного счёта
- Проверка почты — синтаксис, MX-записи, одноразовые адреса
- SWIFT/BIC — разбор кода по ISO-9362 и сверка перед международным переводом
- Валидация телефона — формат, тип номера, оператор диапазона
Полный каталог — atlorium.com
- Документация API (Swagger): atlorium.com/ocrAPI
- Описание сервиса: atlorium.com/ocrDescription
- Веб-интерфейс: atlorium.com/ocrGUI
- OpenAPI-спецификация: ocr_ru.json
- Поддержка: support@atlorium.com
MIT — берите код и используйте как хотите, в том числе в коммерческих проектах.