> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # API пассивной проверки живости: детекция дипфейков > Didit: детекция масок, распечаток, повторов и дипфейков по одному снимку. Полностью пассивно, инференс до 2 с, оплата за использование. ## OpenAPI ````yaml ru/openapi-25.json POST /v3/passive-liveness/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: >- API верификации личности. Аутентификация выполняется с помощью заголовка x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/passive-liveness/: post: tags: - Standalone APIs summary: Пассивная проверка живости description: >- Обнаружение атак предъявления (распечатанных фотографий, воспроизведения с экранов, масок, дипфейков) по одной фотографии лица. Не требует видео, движений или действий со стороны пользователя. **Как это работает.** Модель биометрии анализирует изображение; оценивается самое крупное обнаруженное лицо и вычисляется `score` живости (0–100). `status` принимает значение `Declined`, если срабатывает любое предупреждение с уровнем важности `error`: - `NO_FACE_DETECTED`: модель живости не обнаружила лицо, - `LOW_LIVENESS_SCORE`: оценка равна или ниже порога `face_liveness_score_decline_threshold` (по умолчанию `30`), - `LIVENESS_FACE_ATTACK`: модель обнаружила атаку предъявления, - `FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST`: лицо совпадает с записью в вашем списке блокировки лиц. `MULTIPLE_FACES_DETECTED` является сигналом с уровнем важности `warning` (не приводит к отклонению), а `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` являются сигналами с уровнем важности `information`, указывающими на то, что это же лицо уже встречалось в другой одобренной сессии (они никогда не приводят к отклонению). Параметры `face_quality` и `face_luminance` (0–100, допускают значение null) описывают качество захваченного изображения. **Проверка по списку блокировки и на дубликаты.** Выполняется при **каждом** вызове (с `save_api_request` или без него) путем сопоставления обнаруженного лица с поисковым индексом лиц вашего приложения. Предыдущие лица с тем же `vendor_data` исключаются из всего поиска по индексу, поэтому повторный запуск проверки живости для того же пользователя не вызывает срабатывание `DUPLICATED_FACE`, а лицо из списка блокировки, полученное из сессии с собственным `vendor_data` вызывающей стороны, также НЕ помечается (проверка `FACE_IN_BLOCKLIST` пропускается для лиц с одинаковым `vendor_data`). **Биллинг.** Каждый ответ `200` расходует один кредит Passive Liveness API (списывается с кредита вашего тарифа или с баланса пополнения). При недостаточном балансе возвращается `403` до начала обработки изображения. **Сохранение сессии и регистрация лица (`save_api_request`, по умолчанию `true`).** При значении `true` вызов сохраняется как сессия типа API (Business Console, `GET /v3/session/{sessionId}/decision/` по возвращённому `request_id`, webhook `status.updated`), сохраняются эталонное изображение и кадрированное изображение лица, а обнаруженное лицо **вносится в ваш поисковый индекс лиц**, чтобы последующие вызовы «Поиск по лицу» и проверки на дубликаты могли найти с ним совпадение. При значении `false` вызов является разовым: ничего не сохраняется и лицо не вносится в индекс (проверка по списку блокировки и на дубликаты при этом выполняется). **Песочница.** API-ключи песочницы пропускают всю обработку и биллинг: после валидации запроса (некорректный ввод по-прежнему возвращает `400`) endpoint возвращает статический тестовый payload со статусом `Approved`, сессия не сохраняется, а кредиты не расходуются. **Аутентификация.** Передавайте API-ключ вашего приложения в заголовке `x-api-key`. При отсутствии или недействительности учетных данных возвращается `403` (`{"detail": "You do not have permission to perform this action."}`); этот API никогда не возвращает `401`. **Лимит запросов.** Общий бюджет на запись составляет 300 запросов/мин на API-ключ для всех endpoints POST/PATCH/DELETE; при его превышении возвращается `429`. operationId: post_v3passive-liveness parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image properties: user_image: type: string format: binary description: >- Фронтальное изображение лица (например, селфи). Допустимые расширения: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Максимальный размер загружаемого файла: **5 MB** (файлы большего размера отклоняются с ошибкой `400`). Перед обработкой изображения автоматически сжимаются примерно до 0.5 MB, поэтому сверхвысокое разрешение не повышает точность. На изображении должен быть только один человек — если лиц несколько, оценивается самое крупное и добавляется предупреждение `MULTIPLE_FACES_DETECTED`. face_liveness_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- Порог оценки проверки живости (0–100). Вычисленная оценка **на уровне или ниже** этого значения генерирует предупреждение `LOW_LIVENESS_SCORE` и устанавливает `status` в `Declined`. По умолчанию `30`; увеличьте его для более строгой защиты от спуфинга. Значения вне диапазона 0–100 возвращают `400`. example: 30 rotate_image: type: boolean default: false description: >- Когда `true`, сервис пробует поворачивать входное изображение с шагом 90 градусов и использует ориентацию, обеспечивающую наилучшее обнаружение лица. Полезно, когда отсутствуют данные ориентации EXIF. Увеличивает задержку ответа. example: false save_api_request: type: boolean default: true description: >- Когда `true` (по умолчанию), сохраняет вызов как сессию типа API, сохраняет изображения лица, отправляет webhook `status.updated` и регистрирует обнаруженное лицо в вашем индексе Поиска по лицу. Когда `false`, вызов является однократным — ничего не сохраняется, а лицо не регистрируется. Проверки по списку блокировки и на дубликаты выполняются в обоих случаях. example: true vendor_data: type: string description: >- Необязательный непрозрачный идентификатор (ваш идентификатор пользователя, email, UUID…), сохраняемый в сессии и возвращаемый обратно. Также используется для исключения предыдущих сессий с тем же `vendor_data` из проверки на дубликаты лиц, благодаря чему повторная верификация того же пользователя не вызывает ошибку `DUPLICATED_FACE`. example: user-123 metadata: type: object additionalProperties: true description: >- Необязательный объект JSON, сохраняемый вместе с сессией (когда `save_api_request=true`) и возвращаемый обратно. В multipart-запросах отправляйте его как строковое поле в формате JSON — он парсится в объект. example: flow: withdrawal example: user_image: (binary JPEG/PNG selfie) face_liveness_score_decline_threshold: 30 rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: withdrawal responses: '200': description: >- Пассивная проверка живости завершена. `liveness.score` представляет собой оценку уверенности модели от 0 до 100 в том, что на изображении живой человек; `status` имеет значение `Approved`, если не сработало предупреждение уровня `error`. Лицо с признаками спуфинга или из списка блокировки всё равно возвращает `200`: проверяйте `liveness.status` и `liveness.warnings`, а не только HTTP-код. Если `save_api_request=true`, `request_id` является сохранённым идентификатором сессии. content: application/json: examples: Approved: summary: Живое лицо — предупреждений нет value: request_id: a1b2c3d4-e5f6-7890-1234-567890abcdef liveness: status: Approved method: PASSIVE score: 95 user_image: entities: - bbox: - 661 - 728 - 1688 - 2188 confidence: 0.732973 age: 26.91 gender: male race: null best_angle: 0 warnings: [] face_quality: 84.21 face_luminance: 50.33 vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' Declined - presentation attack: summary: >- Модель зафиксировала спуфинг (печать, воспроизведение видео, маска…) value: request_id: f1c8c9b2-d3e4-4f5a-9b8c-7d6e5f4a3b2c liveness: status: Declined method: PASSIVE score: 12.5 user_image: entities: - bbox: - 100 - 120 - 420 - 540 confidence: 0.81 age: 30.1 gender: female race: null best_angle: 0 warnings: - risk: LOW_LIVENESS_SCORE feature: LIVENESS additional_data: null log_type: error short_description: Low liveness score long_description: >- The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data. - risk: LIVENESS_FACE_ATTACK feature: LIVENESS additional_data: null log_type: error short_description: Liveness Face Attack long_description: >- The system detected a potential attempt to bypass the liveness check. face_quality: 72.4 face_luminance: 48.2 vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' Declined - face on blocklist: summary: Живое лицо, но совпадает с записью в списке блокировки value: request_id: 0b54a1de-22aa-4e0f-9c84-5a2b1f3c4d5e liveness: status: Declined method: PASSIVE score: 93.75 user_image: entities: - bbox: - 40 - 40 - 100 - 100 confidence: 0.722082 age: 27 gender: male race: null best_angle: 0 warnings: - risk: FACE_IN_BLOCKLIST feature: LIVENESS additional_data: blocklisted_session_id: 882c42d5-8a4d-4d20-8080-a22f57822c86 blocklisted_session_number: 3242 api_service: null log_type: error short_description: Face in blocklist long_description: >- The system identified a face in the blocklist, which means the face is not allowed to be verified. face_quality: null face_luminance: null vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- Идентификатор сохраненной сессии при `save_api_request=true` (доступен для использования с `GET /v3/session/{sessionId}/decision/`); в противном случае это временный корреляционный UUID. liveness: type: object properties: status: type: string enum: - Approved - Declined description: >- `Declined`, если сработало хотя бы одно предупреждение с уровнем важности `error` (лицо не обнаружено, низкая оценка, атака предъявления или совпадение со списком блокировки); в противном случае `Approved`. Записи `warning`/`information` (несколько лиц, дубликаты) сами по себе никогда не приводят к отклонению. method: type: string enum: - PASSIVE description: Всегда `PASSIVE` для этого endpoint. score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Уверенность проверки живости (0–100, два знака после запятой) в том, что на изображении запечатлён живой человек, а не спуфинг. `null`, если модель не вернула уверенность. example: 95 user_image: type: object description: >- Результаты обнаружения лица для переданного изображения. properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Ограничивающий прямоугольник обнаруженного лица в координатах пикселей `[x_min, y_min, x_max, y_max]` на обработанном изображении. example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: Уверенность обнаружения лица (0–1). example: 0.732973 age: type: number format: float description: >- Возраст обнаруженного лица в годах, оцененный моделью. Только для справки — не влияет на решение о проверке живости. example: 26.91 gender: type: string description: >- Пол обнаруженного лица, спрогнозированный моделью (`male` или `female`). Только для справки. example: male race: type: string nullable: true description: >- Зарезервированное поле — всегда `null` в ответах от этого endpoint. example: null description: >- Одна запись на каждое обнаруженное лицо. Оценивается самое крупное лицо. best_angle: type: integer nullable: true description: >- Поворот (в градусах), при котором было достигнуто наилучшее обнаружение лица; отличен от нуля, только если `rotate_image=true` скорректировал ориентацию. example: 0 warnings: type: array description: >- Сигналы риска. Серьёзность `error` (отклонения): `NO_FACE_DETECTED`, `LOW_LIVENESS_SCORE` (оценка на уровне порога или ниже), `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, `POSSIBLE_FACE_IN_BLOCKLIST`. Серьёзность `warning` (проверка, без отклонения): `MULTIPLE_FACES_DETECTED`. Серьёзность `information` (без отклонения): `DUPLICATED_FACE`, `POSSIBLE_DUPLICATED_FACE` — то же самое лицо уже появлялось в другой одобренной сессии. items: type: object properties: risk: type: string enum: - NO_FACE_DETECTED - LOW_LIVENESS_SCORE - LIVENESS_FACE_ATTACK - MULTIPLE_FACES_DETECTED - FACE_IN_BLOCKLIST - POSSIBLE_FACE_IN_BLOCKLIST - DUPLICATED_FACE - POSSIBLE_DUPLICATED_FACE description: Машиночитаемый код риска. feature: type: string enum: - LIVENESS description: >- Функция, вызвавшая предупреждение. На этом endpoint всегда `LIVENESS`. additional_data: type: object nullable: true additionalProperties: true description: >- `null` для большинства предупреждений. Срабатывания по списку блокировки содержат `{blocklisted_session_id, blocklisted_session_number, api_service}`; срабатывания по дубликатам содержат `{duplicated_session_id, duplicated_session_number, api_service}`, указывающие на совпадающую сессию. log_type: type: string enum: - error - warning - information description: >- Серьёзность. Предупреждения `error` переводят `status` в `Declined`; записи `warning` и `information` носят информационный характер и сами по себе никогда не приводят к отклонению. short_description: type: string description: >- Краткая сводка риска в одну строку в понятном человеку формате. long_description: type: string description: Понятное объяснение риска. face_quality: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Оценка качества захвата обнаруженного лица, нормализованная до 0–100. `null`, если модель не смогла сформировать надёжное значение. example: 84.21 face_luminance: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Яркость обнаруженного лица, нормализованная в диапазоне 0–100. `null`, если значение недоступно. example: 50.33 vendor_data: type: string nullable: true description: Эхо-значение переданного вами `vendor_data` или `null`. metadata: type: object nullable: true additionalProperties: true description: >- Эхо-значение переданного вами объекта `metadata` или `null`. created_at: type: string format: date-time description: >- Временная метка ISO 8601 (UTC) момента генерации ответа, например `2026-06-12T01:04:42.763237+00:00`. '400': description: >- Ошибка валидации. Возвращается, если `user_image` отсутствует, превышает 5 МБ, имеет неподдерживаемое расширение, не проходит декодирование изображения на стороне сервера или если значение параметра выходит за допустимые пределы. Ошибки полей используют обёртку DRF `{field: [messages]}`; сбои декодирования изображения используют `{"error": ...}`. content: application/json: examples: Missing image: summary: '`user_image` не включён в данные формы' value: user_image: - No file was submitted. Invalid image format: summary: >- Разрешённое расширение, но не поддающееся декодированию содержимое изображения value: error: Invalid user image format. code: invalid_image Unsupported file extension: summary: Расширение файла отличается от tiff/jpg/jpeg/png/webp value: user_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp. File too large: summary: Размер загружаемого файла превышает лимит в 5 МБ value: user_image: - File size should not exceed 5 MB '403': description: >- В доступе отказано. Возвращается, если заголовок `x-api-key` отсутствует, а также если баланс вызывающей организации не покрывает вызов; неверный, отозванный или истекший ключ возвращает `401`. Отсутствующий ключ возвращает `403` с `{"detail": ...}`; неверный, отозванный или истекший ключ возвращает `401`. При нехватке кредитов возвращается `403` с `{"error": ...}` до начала любой обработки изображения. content: application/json: examples: Missing or invalid API key: summary: >- Отсутствует заголовок `x-api-key`, либо ключ недействителен/отозван value: detail: You do not have permission to perform this action. Not enough credits: summary: Баланс организации недостаточен для совершения вызова value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Превышен лимит запросов. Endpoint'ы POST/PATCH/DELETE делят общий лимит в 300 запросов на запись в минуту на один API-ключ (для создания транзакций и отправки событий действует отдельный лимит в 600). Ответ содержит заголовки `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` и `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Более 300 запросов на запись в текущую минуту value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/passive-liveness/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'user_image=@./selfie.jpg' \ -F 'face_liveness_score_decline_threshold=30' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.passive_liveness.check( user_image=open("user_image.jpg", "rb"), face_liveness_score_decline_threshold=30.0, rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "withdrawal"}, ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.passiveLiveness.check({ user_image: await fileFromPath("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "withdrawal" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.PassiveLiveness.Check(ctx, didit.PassiveLivenessCheckParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tFaceLivenessScoreDeclineThreshold: didit.Float(30.0),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"withdrawal\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import java.util.Map; import me.didit.Didit; import me.didit.types.PassiveLivenessCheckParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.passiveLiveness().check(PassiveLivenessCheckParams.builder() .userImage(Path.of("user_image.jpg")) .faceLivenessScoreDeclineThreshold(30.0) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "withdrawal")) .build()); System.out.println(result); - lang: php label: PHP source: |- passiveLiveness->check([ 'user_image' => File::fromPath('user_image.jpg'), 'face_liveness_score_decline_threshold' => 30.0, 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'withdrawal'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.passive_liveness.check( user_image: Pathname("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "withdrawal" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.PassiveLiveness.CheckAsync(new PassiveLivenessCheckParams { UserImage = FileUpload.FromPath("user_image.jpg"), FaceLivenessScoreDeclineThreshold = 30.0, RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "withdrawal" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- API-ключ вашего приложения из раздела «Разработчикам» -> «API-ключи» в Business Console. Основной ключ имеет полный доступ. Именованный ключ может иметь ограниченную область действия: без доступа, чтение или запись для каждого ресурса, ограничение определенными сценариями или одобренными сессиями, списком IP-адресов и сроком действия. 401 означает, что ключ неверен, отозван или его срок действия истек; 403 означает, что ключ не был передан, у ключа нет доступа к этому ресурсу или действию, либо запрос поступил с адреса вне его списка IP-адресов; 404 на маршруте сессии означает, что сессия не входит в сценарии или статусы ключа. Ключ без доступа к медиа получает URL изображений, видео и PDF как null, а ключ без прав на запись сессий получает ссылки на сессии и токены как null. См. https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.