> ## 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: сравнение 1:1 > Didit: сравнение лиц 1:1 через POST /v3/face-match/. Верификация личности и контроль доступа. Менее 2s, оплата по факту, без ежемесячного минимума. ## OpenAPI ````yaml ru/openapi-25.json POST /v3/face-match/ 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/face-match/: post: tags: - Standalone APIs summary: Сравнение лиц description: >- Сравните два изображения лиц (1:1) и получите оценку сходства `score` (0–100), а также `status` со значением `Approved`/`Declined`. **Как это работает.** Оба изображения декодируются и анализируются биометрической моделью (установите `rotate_image=true`, если снимки могут быть повёрнуты набок или перевёрнуты), после чего вычисляется оценка сходства между двумя лицами. Оценка **строго выше** `face_match_score_decline_threshold` (по умолчанию `30`) возвращает `status: "Approved"`; оценка, равная этому значению или ниже него, возвращает `Declined` с предупреждением `LOW_FACE_MATCH_SIMILARITY`. Если пару лиц вообще невозможно оценить, вызов всё равно возвращает `200` со `status: "Declined"` и предупреждением `NO_REFERENCE_IMAGE` — `score` равен `null` при стандартном сохранении или `0` при `save_api_request=false`. Для наилучших результатов передавайте по одному чёткому лицу анфас на каждом изображении. **Биллинг.** Каждый ответ `200` расходует один API-кредит функции Сравнение лиц (списывается из кредитов вашего тарифа или баланса пополнения). Если на балансе организации недостаточно средств для вызова, endpoint возвращает `403` с ошибкой нехватки кредитов до начала какой-либо обработки изображений. **Сохранение сессии (`save_api_request`, по умолчанию `true`).** При значении `true` вызов сохраняется как сессия типа API: она отображается в Business Console, возвращённый `request_id` является реальным идентификатором сессии, который можно передать в `GET /v3/session/{sessionId}/decision/`, оба изображения сохраняются как исходное/целевое изображения сравнения лиц сессии, а на настроенные адреса назначения webhook отправляется webhook `status.updated`. При значении `false` ничего не сохраняется, а `request_id` представляет собой разовый корреляционный UUID, который нельзя запросить позже. **Индекс поиска по лицу.** Этот endpoint никогда не регистрирует лица в вашем индексе поиска по лицу и не выполняет проверку по спискам блокировки или поиск дубликатов — для этого используйте `POST /v3/passive-liveness/` или `POST /v3/face-search/`. **Песочница.** API-ключи песочницы пропускают всю обработку и биллинг: после валидации запроса (некорректный ввод по-прежнему возвращает `400`) endpoint возвращает статический тестовый payload со статусом `Approved`, сессия не сохраняется и кредиты не расходуются. **Аутентификация.** Передавайте API-ключ вашего приложения в заголовке `x-api-key`. При отсутствии или недействительности учетных данных возвращается `403` (`{"detail": "You do not have permission to perform this action."}`) — этот API никогда не возвращает `401`. **Лимит запросов.** Общий лимит на запись составляет 300 запросов/мин на API-ключ для всех endpoint POST/PATCH/DELETE; при его превышении возвращается `429`. operationId: post_v3face-match parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image - ref_image properties: user_image: type: string format: binary description: >- Изображение живого лица или лица-кандидата для верификации (например, селфи). Отправьте одну фотографию анфас, на которой лицо субъекта чётко видно и хорошо освещено. Допустимые расширения: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Максимальный размер загружаемого файла: **5 MB** (файлы большего размера отклоняются с ошибкой `400`). Изображения автоматически сжимаются примерно до 0,5 МБ перед обработкой, поэтому сверхвысокое разрешение не повышает точность. ref_image: type: string format: binary description: >- Эталонное изображение лица для сравнения (например, фото из удостоверения личности или ранее зарегистрированная фотография). Те же ограничения по формату и размеру, что и для `user_image`. face_match_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- Порог сходства (0–100), определяющий `status` в ответе. Вычисленная оценка **на уровне или ниже** этого значения устанавливает `status` в `Declined` и добавляет предупреждение `LOW_FACE_MATCH_SIMILARITY`; оценка строго выше него возвращает `Approved`. Значение по умолчанию `30` является мягким — увеличьте его (например, до `50`–`60`) для более строгой верификации. Значения вне диапазона 0–100 возвращают `400`. example: 50 rotate_image: type: boolean default: false description: >- Когда `true`, сервис поворачивает входные изображения с шагом 90 градусов (0, 90, 180, 270) и использует ориентацию, обеспечивающую наилучшее обнаружение лица — полезно для мобильных снимков с отсутствующей ориентацией EXIF. Увеличивает задержку, поэтому включайте только в том случае, если вы не можете гарантировать правильную ориентацию изображений. example: false save_api_request: type: boolean default: true description: >- Если `true` (по умолчанию), сохраняет вызов как сессию типа API — видимую в Business Console, доступную через `GET /v3/session/{sessionId}/decision/` по возвращенному `request_id` и с уведомлением через webhook `status.updated`. Если `false`, ничего не сохраняется, а `request_id` является временным UUID только для сопоставления ответа. example: true vendor_data: type: string description: >- Необязательная непрозрачная строка (ваш внутренний идентификатор пользователя, email, UUID…), сохраняемая в сессии и возвращаемая в ответе. Используйте её для сопоставления вызовов API с вашими собственными записями и для последующей фильтрации сессий. example: user-123 metadata: type: object additionalProperties: true description: >- Необязательный объект JSON, сохраняемый вместе с сессией (когда `save_api_request=true`) и возвращаемый обратно в ответе. В multipart-запросах отправляйте его как строковое поле в формате JSON (например, `metadata={"flow":"login"}`) — он парсится в объект. example: flow: login device_id: abc123 example: user_image: (binary JPEG/PNG of the live selfie) ref_image: (binary JPEG/PNG of the reference photo) face_match_score_decline_threshold: 50 rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: login responses: '200': description: >- Сравнение лиц вычислено. `face_match.score` представляет собой число с плавающей точкой от 0 до 100 (два знака после запятой); `status` имеет значение `Approved`, если оценка строго выше `face_match_score_decline_threshold`, иначе `Declined` с поясняющим предупреждением. При низкой схожести или невозможности оценить пару все равно возвращается `200`: проверяйте `face_match.status` и `face_match.warnings`, а не только HTTP-код. Если `save_api_request=true`, `request_id` является сохраненным id сессии. content: application/json: examples: Approved: summary: Тот же человек — оценка выше порога value: request_id: f9f5a777-8002-44c6-baaf-128bcfd6e226 face_match: status: Approved score: 99.41 user_image: entities: - bbox: - 661 - 728 - 1688 - 2188 confidence: 0.732973 age: 26.91 gender: male race: null best_angle: 0 ref_image: entities: - bbox: - 653 - 745 - 1691 - 2185 confidence: 0.722082 age: 27 gender: male race: null best_angle: 0 warnings: [] vendor_data: user-123 metadata: flow: login created_at: '2026-06-12T01:04:42.763237+00:00' Declined - low similarity: summary: Оценка на уровне порога отклонения или ниже его value: request_id: 7cdda24e-311a-46d3-a3bb-e5d9b564ce73 face_match: status: Declined score: 24.87 user_image: entities: - bbox: - 661 - 728 - 1688 - 2188 confidence: 0.732973 age: 26.91 gender: male race: null best_angle: 0 ref_image: entities: - bbox: - 156 - 234 - 679 - 898 confidence: 0.717775 age: 41.2 gender: male race: null best_angle: 0 warnings: - risk: LOW_FACE_MATCH_SIMILARITY feature: FACEMATCH additional_data: null log_type: error short_description: Low face match similarity long_description: >- The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch. vendor_data: user-123 metadata: null created_at: '2026-06-12T01:08:19.859116+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- Идентификатор сохраненной сессии при `save_api_request=true` (доступен для использования с `GET /v3/session/{sessionId}/decision/`); в противном случае это временный корреляционный UUID. face_match: type: object properties: status: type: string enum: - Approved - Declined description: >- `Approved`, если оценка сходства строго выше `face_match_score_decline_threshold` и оценку удалось рассчитать; в противном случае `Declined` (причина указана в предупреждении). score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Оценка сходства от 0 до 100 — уверенность модели в том, что на обоих изображениях запечатлен один и тот же человек. Округляется до двух знаков после запятой, только если параметр `save_api_request` равен true; при `save_api_request=false` возвращается исходное число с плавающей точкой. `null`, если не удалось оценить пару лиц (при значении по умолчанию `save_api_request=true`); при `save_api_request=false` то же условие может возвращаться как `score: 0`. В любом случае присутствует предупреждение `NO_REFERENCE_IMAGE`, а `status` равен `Declined`. example: 99.41 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 description: >- Поворот (в градусах: 0, 90, 180 или 270), при котором было достигнуто наилучшее обнаружение лица. Отличен от нуля, только если `rotate_image=true` скорректировал ориентацию. example: 0 ref_image: type: object description: >- Результаты обнаружения лица для эталонного изображения, та же структура, что и у `user_image`. 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 example: 0 warnings: type: array description: >- Пусто при чистом одобрении. `NO_REFERENCE_IMAGE` (`error`) — не удалось оценить пару лиц; `LOW_FACE_MATCH_SIMILARITY` (`error`) — оценка на уровне или ниже порога отклонения. Любое из этих событий устанавливает для `status` значение `Declined`. items: type: object properties: risk: type: string enum: - NO_REFERENCE_IMAGE - LOW_FACE_MATCH_SIMILARITY description: Машиночитаемый код риска. feature: type: string enum: - FACEMATCH description: >- Функция, вызвавшая предупреждение. На этом endpoint всегда `FACEMATCH`. additional_data: type: object nullable: true additionalProperties: true description: Всегда `null` для предупреждений сравнения лиц. log_type: type: string enum: - error - warning - information description: >- Серьёзность. Предупреждения `error` переводят `status` в `Declined`; записи `warning` и `information` носят информационный характер и сами по себе никогда не приводят к отклонению. short_description: type: string description: >- Краткая сводка риска в одну строку в понятном человеку формате. long_description: type: string description: Понятное объяснение риска. 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: >- Ошибка валидации. Возвращается, если обязательное изображение отсутствует, превышает 5 МБ, имеет неподдерживаемое расширение или если значение параметра выходит за допустимые пределы. Тело ответа представляет собой стандартную обёртку ошибок полей DRF: один массив сообщений на каждое некорректное поле. content: application/json: examples: Missing required image: summary: '`ref_image` (или `user_image`) не передан в данных формы' value: ref_image: - No file was submitted. 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 Threshold out of range: summary: '`face_match_score_decline_threshold` вне диапазона 0–100' value: face_match_score_decline_threshold: - Ensure this value is less than or equal to 100. '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/face-match/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'user_image=@./selfie.jpg' \ -F 'ref_image=@./id_portrait.jpg' \ -F 'face_match_score_decline_threshold=50' \ -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.face_match.compare( user_image=open("user_image.jpg", "rb"), ref_image=open("ref_image.jpg", "rb"), face_match_score_decline_threshold=50.0, rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "login"}, ) 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.faceMatch.compare({ user_image: await fileFromPath("user_image.jpg"), ref_image: await fileFromPath("ref_image.jpg"), face_match_score_decline_threshold: 50.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "login" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FaceMatch.Compare(ctx, didit.FaceMatchCompareParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tRefImage: didit.FileFromPath(\"ref_image.jpg\"),\n\tFaceMatchScoreDeclineThreshold: didit.Float(50.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\": \"login\"}),\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.FaceMatchCompareParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.faceMatch().compare(FaceMatchCompareParams.builder() .userImage(Path.of("user_image.jpg")) .refImage(Path.of("ref_image.jpg")) .faceMatchScoreDeclineThreshold(50.0) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "login")) .build()); System.out.println(result); - lang: php label: PHP source: |- faceMatch->compare([ 'user_image' => File::fromPath('user_image.jpg'), 'ref_image' => File::fromPath('ref_image.jpg'), 'face_match_score_decline_threshold' => 50.0, 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'login'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.face_match.compare( user_image: Pathname("user_image.jpg"), ref_image: Pathname("ref_image.jpg"), face_match_score_decline_threshold: 50.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "login" } ) 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.FaceMatch.CompareAsync(new FaceMatchCompareParams { UserImage = FileUpload.FromPath("user_image.jpg"), RefImage = FileUpload.FromPath("ref_image.jpg"), FaceMatchScoreDeclineThreshold = 50.0, RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "login" }, }); 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.