API распознавания автомобильных номеров
Отправьте изображение автомобиля в формате JPEG или PNG по HTTPS — и получите распознанный номерной знак в виде JSON. Одна простая конечная точка, авторизация по Bearer-ключу, ответ за доли секунды.
Подключение за 3 шага
От получения ключа до первого распознанного номера.
Получите API-ключ
Напишите нам — мы выдадим индивидуальный ключ для вашей интеграции.
Отправьте JPEG/PNG
Сделайте POST-запрос multipart с полем file и заголовком Authorization: Bearer.
Получите номер в JSON
В ответе — распознанный номер, уверенность модели и время обработки.
Как получить ключ
Каждый клиент получает индивидуальный API-ключ. Ключ передаётся только по вашему запросу.
Напишите на pirsasha@gmail.com — укажите систему, в которую встраиваете распознавание, и примерный объём запросов. Мы выдадим ключ и поможем с интеграцией.
Примеры кода
Замените YOUR_API_KEY на выданный вам ключ и путь к файлу — на своё изображение.
curl.exe -X POST "https://api-alpr.pirogovx.ru/v1/recognize" `
-H "Authorization: Bearer YOUR_API_KEY" `
-F "file=@C:\images\car.jpg" `
-F "request_id=request-001" `
-F "camera_id=gate-01"curl -X POST "https://api-alpr.pirogovx.ru/v1/recognize" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@/path/to/car.jpg" \
-F "request_id=request-001" \
-F "camera_id=gate-01"curl -X POST "https://api-alpr.pirogovx.ru/v1/recognize" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@/Users/you/car.jpg" \
-F "request_id=request-001" \
-F "camera_id=gate-01"import requests
with open("car.jpg", "rb") as f:
resp = requests.post(
"https://api-alpr.pirogovx.ru/v1/recognize",
headers={"Authorization": "Bearer YOUR_API_KEY"},
files={"file": ("car.jpg", f, "image/jpeg")},
data={"request_id": "request-001", "camera_id": "gate-01"},
timeout=30,
)
print(resp.status_code)
print(resp.json())import { readFile } from "node:fs/promises";
const bytes = await readFile("car.jpg");
const form = new FormData();
form.append("file", new Blob([bytes], { type: "image/jpeg" }), "car.jpg");
form.append("request_id", "request-001");
form.append("camera_id", "gate-01");
const res = await fetch("https://api-alpr.pirogovx.ru/v1/recognize", {
method: "POST",
headers: { Authorization: "Bearer YOUR_API_KEY" },
body: form,
});
console.log(res.status);
console.log(await res.json());<?php
$ch = curl_init("https://api-alpr.pirogovx.ru/v1/recognize");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY"],
CURLOPT_POSTFIELDS => [
"file" => new CURLFile("car.jpg", "image/jpeg", "car.jpg"),
"request_id" => "request-001",
"camera_id" => "gate-01",
],
CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL, $response, PHP_EOL;
curl_close($ch);using System.Net.Http.Headers;
using var http = new HttpClient();
using var form = new MultipartFormDataContent();
using var image = new ByteArrayContent(File.ReadAllBytes("car.jpg"));
image.Headers.ContentType = new MediaTypeHeaderValue("image/jpeg");
form.Add(image, "file", "car.jpg");
form.Add(new StringContent("request-001"), "request_id");
form.Add(new StringContent("gate-01"), "camera_id");
http.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", "YOUR_API_KEY");
var resp = await http.PostAsync("https://api-alpr.pirogovx.ru/v1/recognize", form);
Console.WriteLine((int)resp.StatusCode);
Console.WriteLine(await resp.Content.ReadAsStringAsync());Параметры запроса
Запрос — multipart/form-data, метод POST.
| Поле | Обязательность | Описание |
|---|---|---|
file | обязательно | Изображение автомобиля, JPEG или PNG, до 10 МБ. |
request_id | рекомендуется | Уникальный идентификатор события на стороне клиента. Обеспечивает идемпотентность (см. ниже). |
camera_id | опционально | Идентификатор камеры / шлагбаума / точки съёмки. |
captured_at | опционально | Время съёмки кадра (ISO 8601). |
plate_type | опционально | Подсказка формата номера: auto (по умолчанию), single_line, two_line. |
Заголовок авторизации обязателен для всех запросов:
Authorization: Bearer YOUR_API_KEYЗачем нужен request_id
Если ваш клиент отправил изображение, но не получил ответ (обрыв сети,
таймаут) — повторите запрос с тем же request_id. API вернёт
уже посчитанный результат вместо повторного запуска распознавания.
Для нового кадра/события используйте новый request_id.
Так вы гарантируете, что одно событие обрабатывается ровно один раз.
Успешный ответ
HTTP 200, тело — JSON.
{
"ok": true,
"recognized": true,
"plate": "K324XE797",
"confidence": 0.9989,
"request_id": "request-001",
"camera_id": "gate-01",
"processing_ms": 51.35
}| Поле | Описание |
|---|---|
recognized | true, если номер распознан; false, если номер на кадре не найден. |
plate | Распознанный номер (например, K324XE797). null, если номер не найден. |
confidence | Уверенность модели в распознанном тексте (0…1). |
request_id | Ваш идентификатор запроса — возвращается как есть. |
camera_id | Ваш идентификатор камеры — возвращается как есть. |
processing_ms | Время обработки запроса на сервере, миллисекунды. |
Ответ может содержать дополнительные диагностические поля. Игнорируйте поля, которые вам не нужны — контракт остаётся обратно совместимым.
Номер не найден
HTTP 200 с "recognized": false — это нормальный
успешный ответ API, когда на кадре не удалось найти номер.
Не считайте это ошибкой транспорта или сбоем API.
Коды ответов
| HTTP | Значение |
|---|---|
200 | Запрос обработан (номер найден или recognized:false). |
400 | Некорректный запрос или изображение. |
401 | Ключ отсутствует, недействителен, отключён или отозван. |
413 | Файл слишком большой (лимит 10 МБ). |
429 | Превышен лимит запросов — повторите позже. |
500 | Внутренняя ошибка обработки. |
503 | Сервис распознавания временно недоступен. |
Безопасность ключа
Никогда не встраивайте API-ключ во frontend / браузерный JavaScript. Всё, что попало в браузер, публично и должно считаться скомпрометированным.
Используйте API со стороны сервера:
Храните ключ в переменной окружения, секрет-хранилище или защищённом конфиге. Не коммитьте ключ в Git. При компрометации — запросите ротацию ключа.
С каких систем работает API
Любая система, умеющая делать HTTPS multipart POST. Входящий порт на вашей стороне не нужен — только исходящий HTTPS. VPN не требуется.
Вопросы по API
Нужно ли устанавливать ALPR-RU у себя?
Нет. API работает как облачный сервис — вы отправляете изображение по HTTPS и получаете JSON. Ставить что-либо локально не нужно.
Нужен ли VPN или входящий порт?
Нет. Нужен только исходящий доступ по HTTPS с вашей стороны. Входящий порт и VPN не требуются.
Какое фото отправлять?
Полный кадр автомобиля в JPEG или PNG, до 10 МБ. Детектор сам найдёт номерной знак на снимке.
Что если номер не найден?
API вернёт HTTP 200 с "recognized": false. Это штатный успешный ответ, а не ошибка.
Можно ли использовать несколько камер?
Да. Передавайте camera_id для каждой точки съёмки — он вернётся в ответе, что удобно для журналирования проездов.
Что делать при потере ответа?
Повторите запрос с тем же request_id — API вернёт ранее посчитанный результат, не запуская распознавание повторно.
Что делать, если ключ скомпрометирован?
Напишите нам на pirsasha@gmail.com — мы отзовём старый ключ и выдадим новый.
Нужен API-ключ или помощь с интеграцией?
Ответим по подключению, форматам и объёмам. Пишите — поможем встроить распознавание номеров в вашу систему.