- Фамилия / Surname
- ИВАНОВ
- Имя / Given names
- ИВАН
- Дата рождения
- 12.04.1990
- Пол / Sex
- М/M
- Номер / No.
- PE 1995338
- Действителен до
- 01.08.2029
API распознавания документов
Читает документы с одного снимка
Паспорт, ID-карта, миграционная карта, уведомление о прибытии, экран Амины. Giga Vision сам определяет тип, извлекает поля с оценкой уверенности и проверяет селфи с документом.
Для банков, МФО, платёжных сервисов и кадровых платформ
- не экран и не распечатка
- без наложений
- verificationPassed
типов документов распознаёт сервис, включая миграционный контур
языков интерфейса Амины / КИГИГ: RU, EN, UZ, TJ, KY, KK, HY
запрос на фото — тип документа и поля приходят вместе
за ошибки 4xx и 502 — списание только за обработанный запрос
Живое демо
Попробуйте на своём документе
Тот же API, что и в продакшене. Ответ обычно приходит за несколько секунд, иногда до двух минут.
document_type: —
Здесь появятся тип документа, извлечённые поля и уверенность по каждому.
Распознаём… 0 с
Ответ может занимать до 120 секунд. Не закрывайте страницу.
Каталог
Поддерживаемые документы
Актуальный список — GET /v1/vision/document-types. В продакшене передавайте auto и смотрите document_type в ответе, а не то, что отправили.
01Личность
- passport_photo
- Загранпаспорт, страница с данными
- id_card_photo
- Пластиковая национальная ID-карта
- identity_document_photo
- Паспорт или ID; в полях дополнительно documentType
- selfie_photo
- Селфи с паспортом или ID в руках
Поля: ФИО (кириллица, MRZ транслитерируется), дата рождения, выдачи и окончания, пол, номер без пробелов, кем выдан, место рождения, гражданство, PINFL / IIN.
02Миграционный контур
- migration_card_photo
- Миграционная карта, полный кадр
- migration_front_photo
- Лицевая сторона миграционной карты
- arrival_notification_photo
- Уведомление о прибытии: фото или скрин Госуслуг
- arrival_notification_doc
- Уведомление о прибытии: бланк или скан
- amina_photo
- Экран Амина / КИГИГ на RU, EN, UZ, TJ, KY, KK, HY
Поля: серия и номер миграционки, сроки пребывания, адрес регистрации, номер и дата УОП, орган, номер КИГИГ, телефон.
03Служебные
- auto
- Автоопределение типа и набор полей этого типа. Рекомендуется в продакшене.
- unsupported_photo
- Не документ KYC: случайный экран телефона, не тот тип. Приходит rejectReason.
Экран Амины никогда не выдаётся за паспорт: даже при запросе паспорта тип станет amina_photo, а номер паспорта не будет выдуман. КИГИГ — не номер паспорта.
KYC
Документ, затем селфи с ним
HTTP 200 значит «запрос обработан», а не «человек прошёл проверку». Решение — только по verificationPassed.
- 01
Документ в режиме auto
Пользователь снимает паспорт или ID. Сервис определяет тип и возвращает поля.
- 02
Берёте номер
Сохраняете ФИО и fields.documentNumber.
- 03
Селфи с этим документом
Второй вызов: selfie_photo и expected_document_number.
- 04
Решение
KYC пройден, только если status = success и verificationPassed = true.
Почему селфи может не пройти
Коды в spoofReason через запятую, если причин несколько.
| not_selfie_with_document | Нет живого селфи с документом в кадре |
| face_mismatch | Лицо не совпадает с фото в документе или сравнить нельзя |
| overlay_or_watermark | Наложение, водяной знак, чужой интерфейс поверх кадра |
| printed_or_screen | Фото с экрана или распечатки |
| expected_document_missing | Не передали номер с шага паспорта |
| document_number_mismatch | На селфи прочитался другой номер |
Как сравнивается номер
Без пробелов и регистра: pe-199 5338 = PE1995338. Расхождение в один символ на длинном номере не считается отказом.
Номер на селфи часто не читается — это нормально и не отказ. В этом случае documentNumberMatches = unread. Если ожидаемый номер — идентификатор КИГИГ, сравнение пропускается: skipped.
Как снимать
- Документ занимает большую часть кадра, текст резкий.
- Без блика на серии, номере и ФИО.
- Миграционка — весь бланк или чёткая лицевая сторона.
- Селфи — лицо и документ в одном кадре, не с экрана.
- Повтор той же смазанной фотографии не улучшает результат.
Интеграция
Подключение за день
Отдельный REST API под документы. Ключ выдаёт поддержка, передаётся в Authorization: Bearer. Вызывайте с вашего бэкенда, не из клиентского приложения.
- Базовый URL
- https://airouter.host
- Зеркало РФ
- https://ru.airouter.host
| Метод | Путь | Ключ |
|---|---|---|
| GET | /v1/vision/document-types | не нужен |
| POST | /v1/vision/recognize | обязателен |
- Получить ключ у поддержки. Хранить его вне репозитория.
- Проверить GET document-types — вернётся список id.
- Файл → JPEG → base64 → POST recognize, таймаут 130 с, document_type: "auto".
- Разобрать document_type и нужные ключи fields.
- Пустые поля и низкая уверенность — «переснять / оператор».
- Логировать request_id. На 502 можно повторить.
IMG_B64=$(base64 -w 0 < ./document.jpg)
curl -sS --max-time 130 https://airouter.host/v1/vision/recognize \
-H "Authorization: Bearer $VISION_KEY" \
-H "Content-Type: application/json" \
-d "{
\"document_type\": \"auto\",
\"image_url\": \"data:image/jpeg;base64,${IMG_B64}\"
}"
import base64, json, os, urllib.request
BASE = "https://airouter.host" # РФ: https://ru.airouter.host
KEY = os.environ["VISION_KEY"]
def recognize(path, doc_type="auto", expected=None):
b64 = base64.b64encode(open(path, "rb").read()).decode()
payload = {"document_type": doc_type,
"image_url": f"data:image/jpeg;base64,{b64}"}
if expected:
payload["expected_document_number"] = expected
req = urllib.request.Request(
f"{BASE}/v1/vision/recognize",
data=json.dumps(payload).encode(),
headers={"Authorization": f"Bearer {KEY}",
"Content-Type": "application/json"},
method="POST")
with urllib.request.urlopen(req, timeout=130) as r:
return json.loads(r.read())
import { readFile } from 'node:fs/promises';
const b64 = (await readFile('./document.jpg')).toString('base64');
const res = await fetch('https://airouter.host/v1/vision/recognize', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.VISION_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
document_type: 'auto',
image_url: `data:image/jpeg;base64,${b64}`,
}),
signal: AbortSignal.timeout(130_000),
});
const data = await res.json();
console.log(data.document_type, data.fields.lastName?.value);
Коды ответа
| Код | Когда | Списание |
|---|---|---|
| 200 | Запрос обработан, в том числе status: rejected | да |
| 400 | Пустой или битый image, слишком большой файл, неизвестный тип | нет |
| 401 | Нет ключа или ключ неверный | нет |
| 402 | Недостаточно средств на счёте | нет |
| 403 | Ключ не для Vision, неактивен или отозван | нет |
| 422 | Тело не JSON или нет image_url | нет |
| 502 | Сбой распознавания, можно повторить | нет |
Следующий шаг
Подключение
Ключ доступа выдаёт поддержка Giga Vision. Перед запуском прогоняем тестовые кадры на ваших документах и настраиваем сценарий: только документ или документ и селфи.
- Ключ доступа и базовый URL
- Распознавание документов и проверка селфи
- Сопровождение интеграции, разбор инцидентов по request_id
- Списание только за обработанный запрос (HTTP 200). Ошибки 4xx и 502 не тарифицируются.