Русский · English
Готовые примеры работы с OCR API на шести языках: Python, TypeScript (Node.js), Go, Java, C#, PHP. Извлечь текст из изображения одним HTTP-запросом: картинка уходит в Base64, обратно приходит распознанный текст. Это единственный 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Демо-ключ: сервис ВЕРНЁТ СГЕНЕРИРОВАННЫЙ ТЕКСТ (мок), а не результат
настоящего распознавания вашей картинки. Контракт и формат ответа —
настоящие; качество OCR проверяется только боевым ключом.
Файл: sample.png · PNG · 240 байт
Распознанный текст: t3gqk
Время распознавания: 617 мс
Вердикт: текст распознан — запрос тарифицируется.
Демо-ключ не распознаёт вашу картинку. Он возвращает сгенерированный captcha-подобный текст (в примере выше —
t3gqk, хотя наsample.pngнаписано «ATLORIUM»). Это осознанно: в песочнице вы проверяете контракт, формат ответа и свою интеграцию, а не качество OCR. Настоящее распознавание включается боевым ключом — код при этом не меняется, только переменная окружения. Ответ мока детерминирован (seed берётся из самой картинки), поэтому на нём удобно писать стабильные тесты.
- Оцифровка документов и сканов — превратить фотографию накладной, чека или анкеты в текст.
- Разметка датасетов — вытащить подписи и надписи с изображений массово, а не глазами.
- Автоматический разбор графических кодов подтверждения (CAPTCHA) — в своих же системах и в автотестах, где картинка с кодом стоит между тестом и следующим шагом сценария.
Примеры не просто печатают JSON, а применяют ответ: в каждом есть функция extractText(), которая читает файл с диска, кодирует его в Base64, отправляет POST и выносит вердикт по полю solved.
solved=false означает: текст уверенно распознать не удалось — и деньги за такой запрос не списываются. То же самое при 503: за сбой на нашей стороне вы не платите. Практический смысл: нечитаемую картинку можно прогнать, увидеть solved=false, улучшить её (поднять контраст, обрезать поля, подсказать numeric) и повторить — счёт от этого не вырастет. Именно поэтому solved проверяется во всех шести примерах первым делом.
Проверить 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)\",\"numeric\":false}"{"solved":true,"text":"t3gqk","elapsedMs":617}| Язык | Запуск | Требуется |
|---|---|---|
| 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
Подсказать, что на картинке только цифры: python main.py ../sample.png --numeric
Без аргумента берётся 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,... |
numeric |
bool | нет | Подсказка «на картинке только цифры». Повышает точность распознавания числовых кодов. По умолчанию false — допускаются и буквы, и цифры |
module |
string | нет | Имя специализированного модуля распознавания под конкретный тип картинки. Пусто — модуль по умолчанию. Если не знаете, какой модуль вам нужен, — не передавайте это поле |
{
"image": "iVBORw0KGgoAAAANSUhEUgAA...",
"numeric": true
}ImageOcrResponse:
| Поле | Тип | Что содержит |
|---|---|---|
solved |
bool | Ключевое поле. true — текст распознан и лежит в text. false — распознать не удалось; плата не взимается |
text |
string | null | Распознанный текст. null, если solved=false |
elapsedMs |
int64 | Время распознавания в миллисекундах. По спеке допустимы и число, и строка — примеры принимают оба варианта |
Честно и заранее, чтобы не тратить ваше время:
- Только изображения: PNG и JPG. PDF этот сервис не разбирает — на вход идёт картинка, а не документ. Если у вас PDF, разложите его на страницы-изображения и отправляйте их. Все шесть примеров проверяют сигнатуру файла и отдельно сообщают про PDF, а не молча падают.
- Размер картинки — до 1 МБ в декодированном виде (то есть до кодирования в Base64). Больше — сервис отвечает
400, запрос не тарифицируется. Примеры проверяют размер локально, чтобы не тратить запрос впустую. - Структуру документа сервис не извлекает. Ответ — плоский текст, а не таблицы, поля и координаты блоков.
- Демо-ключ не показывает качество OCR. Он отдаёт мок: сгенерированный captcha-подобный текст вместо содержимого вашей картинки. В песочнице проверяется контракт и интеграция; точность распознавания — только на боевом ключе.
| Код | Причина | Что делать |
|---|---|---|
400 |
Картинка не передана, битый Base64 или размер больше 1 МБ | Проверьте кодирование и размер. Запрос не тарифицируется |
401 |
Ключ отсутствует, просрочен или недействителен | Проверьте заголовок Authorization |
402 |
Недостаточно кредитов на балансе | Пополнить на atlorium.com |
429 |
Превышен rate-limit | Повторить с задержкой. В примерах есть потолок ожидания (120 с): дольше не спим, а честно сообщаем, что квота исчерпана |
503 |
Сервис распознавания временно недоступен | Повторить позже. За сбой на нашей стороне деньги не списываются |
Во всех шести примерах коды разложены в человекочитаемые причины — смотрите класс AtloriumError.
Отдельно: solved=false — это не ошибка, а штатный ответ 200. Картинка обработана, но текст уверенно не прочитан. Плата не берётся.
Оплата pay-as-you-go, без подписки: платите только за успешно распознанные картинки. Нераспознанная картинка бесплатна.
Актуальные цены и лимиты: atlorium.com/pricing
Как отправить картинку в API? Прочитать файл в байты, закодировать в Base64 и положить в поле image JSON-тела POST-запроса. Ровно это и делает функция extractText() в каждом из шести примеров — можно скопировать целиком.
Можно ли отправить data-URL из браузера? Да. Строка вида data:image/png;base64,iVBORw0... принимается как есть — префикс сервис срежет сам.
Распознаёт ли API текст из PDF? Нет. Сервис работает только с изображениями (PNG/JPG). PDF нужно предварительно разложить на страницы-картинки.
Можно ли распознать капчу? Да, это один из основных сценариев: сервис умеет читать графические коды подтверждения — в том числе искажённые. Для чисто цифровых кодов передавайте numeric: true, это повышает точность.
Что делать, если solved=false? Ничего не платить — за такой запрос деньги не списываются. Улучшите картинку: поднимите контраст, обрежьте лишние поля, увеличьте масштаб, и передайте подсказку numeric, если на картинке только цифры.
Какой максимальный размер картинки? 1 МБ в декодированном виде. Для сканов этого хватает с запасом: чек или капча весят десятки килобайт.
Обязательна ли регистрация, чтобы попробовать? Нет. Демо-ключ публичный и работает без аккаунта — но возвращает мок, а не распознавание вашей картинки.
Распознанный текст обычно нужно с чем-то сверить. Из того же аккаунта и тем же ключом доступны:
- ЕГРЮЛ/ЕГРИП — проверка контрагента по ИНН/ОГРН: статус, адрес, капитал
- ИИ-чат — модели, сессии, суммаризация текста
- Справочник БИК ЦБ РФ — реквизиты банка и контрольный ключ расчётного счёта
- Проверка почты — синтаксис, 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 — берите код и используйте как хотите, в том числе в коммерческих проектах.