Перейти к основному содержанию
POST
cURL

Авторизации

x-api-key
string
header
обязательно

API-ключ вашего приложения из раздела «Разработчикам» -> «API-ключи» в Business Console. Основной ключ имеет полный доступ. Именованный ключ может иметь ограниченную область действия: без доступа, чтение или запись для каждого ресурса, ограничение определенными сценариями или одобренными сессиями, списком IP-адресов и сроком действия. 401 означает, что ключ неверен, отозван или его срок действия истек; 403 означает, что ключ не был передан, у ключа нет доступа к этому ресурсу или действию, либо запрос поступил с адреса вне его списка IP-адресов; 404 на маршруте сессии означает, что сессия не входит в сценарии или статусы ключа. Ключ без доступа к медиа получает URL изображений, видео и PDF как null, а ключ без прав на запись сессий получает ссылки на сессии и токены как null. См. https://docs.didit.me/console/api-keys.

Тело

multipart/form-data
user_image
file
обязательно

Фронтальное изображение лица для поиска. Допустимые расширения: tiff, jpg, jpeg, png, webp. Максимальный размер загружаемого файла: 5 MB (файлы большего размера отклоняются с ошибкой 400). Перед обработкой изображения автоматически сжимаются примерно до 0.5 MB, поэтому сверхвысокое разрешение не повышает точность. На изображении должно быть хотя бы одно распознаваемое лицо — иначе endpoint возвращает 400. Если лиц несколько, поиск выполняется по самому крупному и добавляется предупреждение MULTIPLE_FACES_DETECTED.

search_type
enum<string>
по умолчанию:most_similar

Политика поиска. most_similar (по умолчанию) ранжирует все зарегистрированные лица в вашем приложении по сходству. blocklisted_or_approved ограничивает кандидатов лицами из списка блокировки, белого списка, лицами из одобренных сессий и импортированными лицами из профилей пользователей, при этом записи из списка блокировки располагаются первыми.

Доступные опции:
most_similar,
blocklisted_or_approved
Пример:

"most_similar"

rotate_image
boolean
по умолчанию:false

Когда true, сервис пробует поворачивать входное изображение с шагом 90 градусов и использует ориентацию, обеспечивающую наилучшее обнаружение лица. Полезно, когда отсутствуют данные ориентации EXIF. Увеличивает задержку ответа.

Пример:

false

save_api_request
boolean
по умолчанию:true

Когда true (по умолчанию), сохраняет вызов как сессию типа API, отправляет webhook status.updated, генерирует предварительно подписанные URL для значений match_image_url и регистрирует найденное лицо в вашем индексе Поиска по лицу (зарегистрированные лица исключаются из будущих поисков). Когда false, поиск является однократным — сессия не сохраняется, а лицо не регистрируется.

Пример:

true

vendor_data
string

Необязательный непрозрачный идентификатор (ваш user id, email, UUID…), сохраняемый в сессии и возвращаемый обратно. Он не исключает лица того же пользователя из результатов поиска.

Пример:

"user-123"

metadata
object

Необязательный объект JSON, сохраняемый вместе с сессией (когда save_api_request=true) и возвращаемый обратно. В multipart-запросах отправляйте его как строковое поле в формате JSON — он парсится в объект.

Пример:

Ответ

Поиск по лицу завершен. face_search.matches содержит до 5 похожих лиц, отсортированных по схожести; пустой массив означает, что ни одно зарегистрированное лицо не превысило минимальный порог схожести. status принимает значение Declined только при совпадениях со списком блокировки — совпадения-дубликаты возвращают Approved, поэтому проверяйте matches и warnings, а не только status. Если save_api_request=true, request_id является сохраненным id сессии. Каждое совпадение содержит source (session, imported, list_entry или retained_template), vendor_user_id и biometric_template_id; совпадение retained_template поступает из биометрического шаблона без изображений, сохраненного после удаления исходной сессии, и содержит null в полях сессии, match_image_url и user_details.

request_id
string<uuid>

Идентификатор сохраненной сессии при save_api_request=true (доступен для использования с GET /v3/session/{sessionId}/decision/); в противном случае это временный корреляционный UUID.

vendor_data
string | null

Эхо-значение переданного вами vendor_data или null.

metadata
object | null

Эхо-значение переданного вами объекта metadata или null.

created_at
string<date-time>

Временная метка ISO 8601 (UTC) момента генерации ответа, например 2026-06-12T01:04:42.763237+00:00.

Последнее изменение 7 ноября 2026 г.