Liveness Session Operations - Create Liveness Session

Servicio:: Azure AI Services

Versión de la API:: v1.2

Cree una nueva sesión de detección de ejecución.
Una sesión es mejor para escenarios de dispositivos cliente en los que los desarrolladores desean autorizar a un dispositivo cliente a realizar solo una detección de ejecución sin conceder acceso completo a su recurso. Las sesiones creadas tienen un período de vida limitado y solo autorizan a los clientes a realizar la acción deseada antes de que expire el acceso.

Los permisos incluyen...

- Duración del token de 10 minutos.

Note

El acceso de cliente se puede revocar mediante la eliminación de la sesión mediante la operación Eliminar sesión de ejecución. Para recuperar un resultado, use la sesión Get Liveness. Para auditar las solicitudes individuales realizadas por un cliente al recurso, use las entradas de auditoría de sesión de ejecución de lista.

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

Parámetros de identificador URI

Nombre	En	Requerido	Tipo	Description
apiVersion	path	True	string	Versión de la API
endpoint	path	True	string (uri)	Puntos de conexión de Cognitive Services admitidos (protocolo y nombre de host, por ejemplo: https://{resource-name}.cognitiveservices.azure.com).

Cuerpo de la solicitud

Nombre	Requerido	Tipo	Description
livenessOperationMode	True	LivenessOperationMode	Tipo de modo de vida que debe seguir el cliente.
authTokenTimeToLiveInSeconds		integer (int32) minimum: 60 maximum: 86400	Segundos para los que debe durar la sesión. El intervalo es de 60 a 86400 segundos. El valor predeterminado es 600.
deviceCorrelationId		string	Guid único por cada dispositivo de usuario final. Esto es para proporcionar limitación de velocidad y anti-martillo. Si "deviceCorrelationIdSetInClient" es true en esta solicitud, "deviceCorrelationId" debe ser NULL.
deviceCorrelationIdSetInClient		boolean	Indica si se va a permitir que el cliente establezca su propio "deviceCorrelationId" mediante el SDK de Vision. El valor predeterminado es false y "deviceCorrelationId" debe establecerse en este cuerpo de la solicitud.
enableSessionImage		boolean	Indica si almacena o no la imagen de sesión.
livenessModelVersion		LivenessModel	Versión del modelo que se usa para la clasificación de vida. Se trata de un parámetro opcional y, si no se especifica, se elegirá la versión más reciente del modelo compatible.

Respuestas

Nombre	Tipo	Description
200 OK	LivenessSession	Una llamada correcta crea una sesión para un dispositivo cliente y proporciona un token de autorización para que lo use la aplicación cliente con un propósito y un tiempo limitados.
Other Status Codes	FaceErrorResponse	Una respuesta de error inesperada. Encabezados x-ms-error-code: string

Nombre

Tipo

Description

200 OK

LivenessSession

Una llamada correcta crea una sesión para un dispositivo cliente y proporciona un token de autorización para que lo use la aplicación cliente con un propósito y un tiempo limitados.

Other Status Codes

FaceErrorResponse

Una respuesta de error inesperada.

Encabezados

x-ms-error-code: string

Seguridad

Ocp-Apim-Subscription-Key

Clave secreta de la suscripción de Azure AI Face.

Tipo: apiKey
En: header

AADToken

Flujo de OAuth2 de Azure Active Directory

Tipo: oauth2
Flujo: accessCode
Dirección URL de autorización: https://api.example.com/oauth2/authorize
Dirección URL del token: https://api.example.com/oauth2/token

Ámbitos

Nombre	Description
https://cognitiveservices.azure.com/.default

Ejemplos

Create Liveness Session

Solicitud de ejemplo

HTTP

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

{
  "livenessOperationMode": "Passive",
  "deviceCorrelationIdSetInClient": false,
  "deviceCorrelationId": "your_device_correlation_id",
  "authTokenTimeToLiveInSeconds": 60
}

Respuesta de muestra

status code:: 200

{
  "sessionId": "b12e033e-bda7-4b83-a211-e721c661f30e",
  "authToken": "eyJhbGciOiJFUzI1NiIsIm",
  "status": "NotStarted",
  "modelVersion": "2024-11-15",
  "results": {
    "attempts": []
  }
}

Definiciones

Nombre	Description
CreateLivenessSessionContent	Modelo de solicitud para crear una sesión de ejecución.
FaceError	Objeto de error. Para obtener detalles completos sobre los códigos de error y los mensajes devueltos por face Service, consulte el vínculo siguiente: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Respuesta que contiene los detalles del error.
FaceRectangle	Rectángulo dentro del cual se puede encontrar una cara.
LivenessColorDecisionTarget	Destino de la imagen de color utilizada para la clasificación de vida.
LivenessDecision	Resultado de la clasificación de vida.
LivenessDecisionTargets	Destinos usados para la clasificación de vida.
LivenessError	Error de la clasificación de vida.
LivenessModel	Versión del modelo que se usa para la clasificación de vida.
LivenessOperationMode	Modo de operación de ejecución para impulsar la experiencia del usuario final del cliente.
LivenessResult	Resultados de la clasificación de vida.
LivenessSession	Resultado de la sesión de detección de la ejecución.
LivenessSessionAttempt	El intento de sesión de ejecución.
LivenessSessionResults	Resultados de la sesión de ejecución.
OperationState	Estado actual de la sesión.

CreateLivenessSessionContent

Object

Modelo de solicitud para crear una sesión de ejecución.

Nombre	Tipo	Valor predeterminado	Description
authTokenTimeToLiveInSeconds	integer (int32) minimum: 60 maximum: 86400	600	Segundos para los que debe durar la sesión. El intervalo es de 60 a 86400 segundos. El valor predeterminado es 600.
deviceCorrelationId	string		Guid único por cada dispositivo de usuario final. Esto es para proporcionar limitación de velocidad y anti-martillo. Si "deviceCorrelationIdSetInClient" es true en esta solicitud, "deviceCorrelationId" debe ser NULL.
deviceCorrelationIdSetInClient	boolean		Indica si se va a permitir que el cliente establezca su propio "deviceCorrelationId" mediante el SDK de Vision. El valor predeterminado es false y "deviceCorrelationId" debe establecerse en este cuerpo de la solicitud.
enableSessionImage	boolean		Indica si almacena o no la imagen de sesión.
livenessModelVersion	LivenessModel		Versión del modelo que se usa para la clasificación de vida. Se trata de un parámetro opcional y, si no se especifica, se elegirá la versión más reciente del modelo compatible.
livenessOperationMode	LivenessOperationMode		Tipo de modo de vida que debe seguir el cliente.

FaceError

Object

Objeto de error. Para obtener detalles completos sobre los códigos de error y los mensajes devueltos por face Service, consulte el vínculo siguiente: https://aka.ms/face-error-codes-and-messages.

Nombre	Tipo	Description
code	string	Uno de un conjunto definido por el servidor de códigos de error.
message	string	Representación legible del error.

FaceErrorResponse

Object

Respuesta que contiene los detalles del error.

Nombre	Tipo	Description
error	FaceError	Objeto de error.

FaceRectangle

Object

Rectángulo dentro del cual se puede encontrar una cara.

Nombre	Tipo	Description
height	integer (int32)	Alto del rectángulo, en píxeles.
left	integer (int32)	Distancia desde el borde izquierdo si la imagen al borde izquierdo del rectángulo, en píxeles.
top	integer (int32)	Distancia desde el borde superior si la imagen hasta el borde superior del rectángulo, en píxeles.
width	integer (int32)	Ancho del rectángulo, en píxeles.

LivenessColorDecisionTarget

Object

Destino de la imagen de color utilizada para la clasificación de vida.

Nombre	Tipo	Description
faceRectangle	FaceRectangle	Región facial en la que se realizó la clasificación de vida.

LivenessDecision

Enumeración

Resultado de la clasificación de vida.

Valor	Description
uncertain	El algoritmo no pudo clasificar la cara de destino como real o suplantación de identidad.
realface	El algoritmo ha clasificado la cara de destino como real.
spoofface	El algoritmo ha clasificado la cara de destino como una suplantación de identidad.

LivenessDecisionTargets

Object

Destinos usados para la clasificación de vida.

Nombre	Tipo	Description
color	LivenessColorDecisionTarget	Destino de la imagen de color utilizada para la clasificación de vida.

LivenessError

Object

Error de la clasificación de vida.

Nombre	Tipo	Description
code	string	Código de error.
message	string	Mensaje de error.
targets	LivenessDecisionTargets	Destinos usados para la clasificación de vida.

LivenessModel

Enumeración

Versión del modelo que se usa para la clasificación de vida.

Valor	Description
2024-11-15

LivenessOperationMode

Enumeración

Modo de operación de ejecución para impulsar la experiencia del usuario final del cliente.

Valor	Description
Passive	Utiliza una técnica de vida pasiva que no requiere acciones adicionales del usuario. Requiere iluminación interior normal y brillo de pantalla alta para un rendimiento óptimo. Por lo tanto, este modo tiene un sobre operativo estrecho y no será adecuado para escenarios que requieren que el usuario final esté en condiciones de iluminación brillantes. Nota: este es el único modo admitido para la solución Mobile (iOS y Android).
PassiveActive	Este modo utiliza una técnica de vida activa o pasiva híbrida que requiere la cooperación del usuario. Está optimizado para requerir movimiento activo solo bajo condiciones de iluminación poco óptimas. A diferencia del modo pasivo, este modo no tiene restricciones de iluminación y, por tanto, ofrece un sobre operativo más amplio. Este modo es preferible en soluciones basadas en Web debido a la falta de control automático de brillo de pantalla disponible en exploradores que dificultan el sobre operativo del modo pasivo en soluciones basadas en Web.

Valor

Description

Passive

Utiliza una técnica de vida pasiva que no requiere acciones adicionales del usuario. Requiere iluminación interior normal y brillo de pantalla alta para un rendimiento óptimo. Por lo tanto, este modo tiene un sobre operativo estrecho y no será adecuado para escenarios que requieren que el usuario final esté en condiciones de iluminación brillantes. Nota: este es el único modo admitido para la solución Mobile (iOS y Android).

PassiveActive

Este modo utiliza una técnica de vida activa o pasiva híbrida que requiere la cooperación del usuario. Está optimizado para requerir movimiento activo solo bajo condiciones de iluminación poco óptimas. A diferencia del modo pasivo, este modo no tiene restricciones de iluminación y, por tanto, ofrece un sobre operativo más amplio. Este modo es preferible en soluciones basadas en Web debido a la falta de control automático de brillo de pantalla disponible en exploradores que dificultan el sobre operativo del modo pasivo en soluciones basadas en Web.

LivenessResult

Object

Resultados de la clasificación de vida.

Nombre	Tipo	Description
digest	string	Resumen calculado del servidor para esta solicitud. Si el resumen notificado por el cliente difiere del resumen calculado del servidor, la integridad del mensaje entre el cliente y el servicio se ha puesto en peligro y el resultado no debe ser de confianza. Para obtener más información, consulte guías sobre cómo aprovechar este valor para proteger la solución de un extremo a otro.
livenessDecision	LivenessDecision	Clasificación de vida de la cara de destino.
sessionImageId	string	Identificador de imagen de la solicitud de sesión.
targets	LivenessDecisionTargets	Destinos usados para la clasificación de vida.