Liveness Session Operations - Create Liveness With Verify Session

Служба:: Azure AI Services

Версия API:: v1.2

Создайте новый сеанс активности с проверкой. Укажите изображение проверки во время создания сеанса.
Сеанс лучше всего подходит для сценариев клиентского устройства, в которых разработчики хотят авторизовать клиентское устройство только для обнаружения активности, не предоставляя полный доступ к своему ресурсу. Созданные сеансы имеют ограниченный срок жизни и разрешают только клиентам выполнять требуемое действие до истечения срока действия.

Разрешения включают...

- Время существования токена составляет 10 минут.

Note

- Доступ к клиенту можно отменить, удалив сеанс с помощью операции удаления liveness с проверкой сеанса.
- Чтобы получить результат, используйте метод Get Liveness с проверкой сеанса.
- Чтобы проверить отдельные запросы, внесенные клиентом в ресурс, используйте список liveness с записями аудита сеансов.

POST {endpoint}/face/{apiVersion}/detectLivenessWithVerify-sessions

Параметры URI

Имя	В	Обязательно	Тип	Описание
livenessOperationMode	formData	True	LivenessOperationMode	Тип режима активности, который должен следовать клиенту.
verifyImage	formData	True	file	Поток изображения для проверки. Поле заголовка Content-Disposition для этой части должно иметь имя файла.
authTokenTimeToLiveInSeconds	formData		integer (int32) minimum: 60 maximum: 86400	Секунды сеанса должны длиться в течение. Диапазон составляет от 60 до 86400 секунд. Значение по умолчанию — 600.
deviceCorrelationId	formData		string	Уникальный guid для каждого устройства конечного пользователя. Это обеспечивает ограничение скорости и анти-молоток. Если параметр deviceCorrelationIdSetInClient имеет значение true в этом запросе, этот параметр deviceCorrelationId должен иметь значение NULL.
deviceCorrelationIdSetInClient	formData		boolean	Следует ли разрешить клиенту устанавливать собственный deviceCorrelationId с помощью пакета SDK для визуального распознавания. Значение по умолчанию равно false, и в тексте запроса должен быть задан параметр deviceCorrelationId.
enableSessionImage	formData		boolean	Независимо от того, хранится ли образ сеанса.
livenessModelVersion	formData		LivenessModel	Версия модели, используемая для классификации активности. Это необязательный параметр, и если это не указано, будет выбрана последняя поддерживаемая версия модели.
returnVerifyImageHash	formData		boolean	Возвращает ли хэш изображения проверки.
verifyConfidenceThreshold	formData		number (float) minimum: 0 maximum: 1	Пороговое значение для проверки подлинности лица. Дополнительные сведения см. в документации. https://learn.microsoft.com/legal/cognitive-services/face/characteristics-and-limitations?context=%2Fazure%2Fai-services%2Fcomputer-vision%2Fcontext%2Fcontext#recognition-confidence-score
apiVersion	path	True	string	Версия API
endpoint	path	True	string (uri)	Поддерживаемые конечные точки Cognitive Services (протокол и имя узла, например https://{имя ресурса}.cognitiveservices.azure.com).

Ответы

Имя	Тип	Описание
200 OK	LivenessWithVerifySession	Успешный вызов создает сеанс для клиентского устройства и предоставляет маркер авторизации для использования клиентским приложением для ограниченной цели и времени.
Other Status Codes	FaceErrorResponse	Непредвиденное сообщение об ошибке. Заголовки x-ms-error-code: string

Имя

Тип

Описание

200 OK

LivenessWithVerifySession

Успешный вызов создает сеанс для клиентского устройства и предоставляет маркер авторизации для использования клиентским приложением для ограниченной цели и времени.

Other Status Codes

FaceErrorResponse

Непредвиденное сообщение об ошибке.

Заголовки

x-ms-error-code: string

Безопасность

Ocp-Apim-Subscription-Key

Секретный ключ для подписки Azure AI Face.

Тип: apiKey
В: header

AADToken

Поток OAuth2 Azure Active Directory

Тип: oauth2
Flow: accessCode
URL-адрес авторизации: https://api.example.com/oauth2/authorize
URL-адрес токена: https://api.example.com/oauth2/token

Области

Имя	Описание
https://cognitiveservices.azure.com/.default

Примеры

Create LivenessWithVerify Session

Образец запроса

HTTP

POST {endpoint}/face/v1.2/detectLivenessWithVerify-sessions

Пример ответа

Код состояния:: 200

{
  "sessionId": "b12e033e-bda7-4b83-a211-e721c661f30e",
  "authToken": "eyJhbGciOiJFUzI1NiIsIm",
  "status": "NotStarted",
  "modelVersion": "2024-11-15",
  "results": {
    "attempts": [],
    "verifyReferences": [
      {
        "referenceType": "image",
        "faceRectangle": {
          "top": 316,
          "left": 131,
          "width": 498,
          "height": 677
        },
        "qualityForRecognition": "high"
      }
    ]
  }
}

Определения

Имя	Описание
FaceError	Объект ошибки. Подробные сведения о кодах ошибок и сообщениях, возвращаемых службой распознавания лиц, см. по следующей ссылке: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Ответ, содержащий сведения об ошибке.
FaceRectangle	Прямоугольник, в котором можно найти лицо.
ImageType	Тип изображения.
LivenessColorDecisionTarget	Целевой объект из цветового изображения, используемого для классификации активности.
LivenessDecision	Результат классификации активности.
LivenessDecisionTargets	Целевые объекты, используемые для классификации активности.
LivenessError	Ошибка классификации активности.
LivenessModel	Версия модели, используемая для классификации активности.
LivenessOperationMode	Режим работы с динамической жизнью для обеспечения взаимодействия с конечным пользователем клиента.
LivenessWithVerifyOutputs	Выходные данные проверки лиц.
LivenessWithVerifyReference	Подробности лица для проверки.
LivenessWithVerifyResult	Результаты активности с проверкой вызова.
LivenessWithVerifySession	Результат сеанса обнаружения активности с проверкой.
LivenessWithVerifySessionAttempt	Динамическая жизнь с проверкой попытки сеанса.
LivenessWithVerifySessionResults	Результаты активности с проверкой сеанса.
OperationState	Текущее состояние сеанса.
QualityForRecognition	Указывает качество изображения для распознавания.

FaceError

Object

Объект ошибки. Подробные сведения о кодах ошибок и сообщениях, возвращаемых службой распознавания лиц, см. по следующей ссылке: https://aka.ms/face-error-codes-and-messages.

Имя	Тип	Описание
code	string	Один из определяемых сервером кодов ошибок.
message	string	Читаемое пользователем представление ошибки.

FaceErrorResponse

Object

Ответ, содержащий сведения об ошибке.

Имя	Тип	Описание
error	FaceError	Объект ошибки.

FaceRectangle

Object

Прямоугольник, в котором можно найти лицо.

Имя	Тип	Описание
height	integer (int32)	Высота прямоугольника в пикселях.
left	integer (int32)	Расстояние от левого края, если изображение до левого края прямоугольника в пикселях.
top	integer (int32)	Расстояние от верхнего края, если изображение до верхнего края прямоугольника в пикселях.
width	integer (int32)	Ширина прямоугольника в пикселях.

ImageType

Перечисление

Тип изображения.

Значение	Описание
Color	Цветное изображение.
Infrared	Инфракрасное изображение.
Depth	Глубина изображения.

LivenessColorDecisionTarget

Object

Целевой объект из цветового изображения, используемого для классификации активности.

Имя	Тип	Описание
faceRectangle	FaceRectangle	Область лица, на которой была сделана классификация активности.

LivenessDecision

Перечисление

Результат классификации активности.

Значение	Описание
uncertain	Алгоритм не мог классифицировать целевое лицо как реальное или спуофное.
realface	Алгоритм классифицировал целевое лицо как реальное.
spoofface	Алгоритм классифицировал целевое лицо как спуф.

LivenessDecisionTargets

Object

Целевые объекты, используемые для классификации активности.

Имя	Тип	Описание
color	LivenessColorDecisionTarget	Целевой объект из цветового изображения, используемого для классификации активности.

LivenessError

Object

Ошибка классификации активности.

Имя	Тип	Описание
code	string	Код ошибки.
message	string	Сообщение об ошибке.
targets	LivenessDecisionTargets	Целевые объекты, используемые для классификации активности.

LivenessModel

Перечисление

Версия модели, используемая для классификации активности.

Значение	Описание
2024-11-15

LivenessOperationMode

Перечисление

Режим работы с динамической жизнью для обеспечения взаимодействия с конечным пользователем клиента.

Значение	Описание
Passive	Использует метод пассивной активности, который не требует дополнительных действий от пользователя. Требует нормального освещения помещений и высокой яркости экрана для оптимальной производительности. Таким образом, этот режим имеет узкий операционный конверт и не подходит для сценариев, требующих, чтобы конечный пользователь был в условиях яркого освещения. Примечание. Это единственный поддерживаемый режим для решения Mobile (iOS и Android).
PassiveActive	Этот режим использует метод гибридной пассивной или активной активности, который требует сотрудничества пользователей. Он оптимизирован для того, чтобы требовать активное движение только в неоптимальных условиях освещения. В отличие от пассивного режима, этот режим не имеет ограничений освещения и, таким образом, предлагая более широкий операционный конверт. Этот режим предпочтительнее для веб-решений из-за отсутствия автоматического управления яркостью экрана, доступного в браузерах, что препятствует операционному конверту пассивного режима в веб-решениях.

Значение

Описание

Passive

Использует метод пассивной активности, который не требует дополнительных действий от пользователя. Требует нормального освещения помещений и высокой яркости экрана для оптимальной производительности. Таким образом, этот режим имеет узкий операционный конверт и не подходит для сценариев, требующих, чтобы конечный пользователь был в условиях яркого освещения. Примечание. Это единственный поддерживаемый режим для решения Mobile (iOS и Android).

PassiveActive

Этот режим использует метод гибридной пассивной или активной активности, который требует сотрудничества пользователей. Он оптимизирован для того, чтобы требовать активное движение только в неоптимальных условиях освещения. В отличие от пассивного режима, этот режим не имеет ограничений освещения и, таким образом, предлагая более широкий операционный конверт. Этот режим предпочтительнее для веб-решений из-за отсутствия автоматического управления яркостью экрана, доступного в браузерах, что препятствует операционному конверту пассивного режима в веб-решениях.

LivenessWithVerifyOutputs

Object

Выходные данные проверки лиц.

Имя	Тип	Описание
isIdentical	boolean	Соответствует ли целевое лицо живости и сравнение изображения лица.
matchConfidence	number (float) minimum: 0 maximum: 1	Целевое лицо живости лица и сравнение изображения лица проверки достоверности.

LivenessWithVerifyReference

Object

Подробности лица для проверки.

Имя	Тип	Описание
faceRectangle	FaceRectangle	Область лица, в которой была сделана классификация изображения сравнения.
qualityForRecognition	QualityForRecognition	Качество изображения лица для распознавания.
referenceType	ImageType	Тип изображения, содержащий прямоугольник лица, на котором была сделана классификация активности.

LivenessWithVerifyResult

Object

Результаты активности с проверкой вызова.

Имя	Тип	Описание
digest	string	Сервер вычисляет дайджест для этого запроса. Если клиент сообщает, что дайджест отличается от вычисляемого дайджеста сервера, то целостность сообщений между клиентом и службой была скомпрометирована, и результат не должен быть доверенным. Дополнительные сведения см. в руководстве по использованию этого значения для защиты комплексного решения.
livenessDecision	LivenessDecision	Классификация активности для целевого лица.
sessionImageId	string	Идентификатор изображения запроса сеанса.
targets	LivenessDecisionTargets	Целевые объекты, используемые для классификации активности.
verifyImageHash	string	Хэш sha256 для образа проверки в запросе.
verifyResult	LivenessWithVerifyOutputs	Выходные данные проверки лиц. Доступно только в том случае, если запрос находится в режиме реального времени с проверкой.

LivenessWithVerifySession

Object

Результат сеанса обнаружения активности с проверкой.

Имя	Тип	Описание
authToken	string	Маркер носителя для проверки подлинности пакета SDK для визуального распознавания, запущенного в клиентском приложении. Этот маркер носителя имеет ограниченные разрешения для выполнения только необходимых действий и истекает после времени TTL. Он также доступен для аудита.
modelVersion	LivenessModel	Версия модели, используемая для классификации активности. Это необязательный параметр, и если это не указано, будет выбрана последняя поддерживаемая версия модели.
results	LivenessWithVerifySessionResults	Результаты активности с проверкой сеанса.
sessionId	string	Уникальный идентификатор для ссылки на этот сеанс.
status	OperationState	Текущее состояние сеанса.

LivenessWithVerifySessionAttempt

Object

Динамическая жизнь с проверкой попытки сеанса.

Имя	Тип	Описание
attemptId	integer (int32)	Идентификатор попытки, начиная с 1.
attemptStatus	OperationState	Состояние попытки.
error	LivenessError	Ошибка активности при проверке вызова будет иметь значение NULL, если есть результат.
result	LivenessWithVerifyResult	Результат активности при проверке вызова будет иметь значение NULL, если возникает ошибка.

LivenessWithVerifySessionResults

Object

Результаты активности с проверкой сеанса.

Имя	Тип	Описание
attempts	LivenessWithVerifySessionAttempt[]	Попытки данных базовой активности с проверкой вызова с помощью сеанса.
verifyReferences	LivenessWithVerifyReference[]	Ссылки, используемые для проверки лиц.

OperationState

Перечисление

Текущее состояние сеанса.

Значение	Описание
NotStarted	Операция не запущена.
Running	Операция выполняется.
Succeeded	Операция успешно завершена.
Failed	Операция завершилась ошибкой.
Canceled	Операция отменена пользователем.

QualityForRecognition

Перечисление

Указывает качество изображения для распознавания.

Значение	Описание
low	Низкое качество.
medium	Среднего качества.
high	Высокое качество.

Поделиться через

Liveness Session Operations - Create Liveness With Verify Session

Параметры URI

Ответы

Безопасность

Ocp-Apim-Subscription-Key

AADToken

Области

Примеры

Create LivenessWithVerify Session

Образец запроса

Пример ответа

Определения

FaceError

FaceErrorResponse

FaceRectangle

ImageType

LivenessColorDecisionTarget

LivenessDecision

LivenessDecisionTargets

LivenessError

LivenessModel

LivenessOperationMode

LivenessWithVerifyOutputs

LivenessWithVerifyReference

LivenessWithVerifyResult

LivenessWithVerifySession

LivenessWithVerifySessionAttempt

LivenessWithVerifySessionResults

OperationState

QualityForRecognition