Liveness Session Operations - Create Liveness With Verify Session

Servicio:: Azure AI Services

Versión de la API:: v1.2

Cree una nueva sesión de ejecución con comprobación. Proporcione la imagen de comprobación durante la creación de la sesió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 ejecución con comprobación de sesión.
- Para recuperar un resultado, use Get Liveness With Verify Session.
- Para auditar las solicitudes individuales realizadas por un cliente al recurso, use las entradas List Liveness With Verify Session Audit Entries (Enumerar vida con comprobar la auditoría de sesión).

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

Parámetros de identificador URI

Nombre	En	Requerido	Tipo	Description
livenessOperationMode	formData	True	LivenessOperationMode	Tipo de modo de vida que debe seguir el cliente.
verifyImage	formData	True	file	Flujo de imagen para comprobarlo. El campo de encabezado Content-Disposition para esta parte debe tener el nombre de archivo.
authTokenTimeToLiveInSeconds	formData		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	formData		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	formData		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	formData		boolean	Indica si almacena o no la imagen de sesión.
livenessModelVersion	formData		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.
returnVerifyImageHash	formData		boolean	Indica si devuelve o no el hash de comprobación de la imagen.
verifyConfidenceThreshold	formData		number (float) minimum: 0 maximum: 1	Umbral de confianza de la comprobación facial. Consulte la documentación para obtener más detalles. 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	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).

Respuestas

Nombre	Tipo	Description
200 OK	LivenessWithVerifySession	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

LivenessWithVerifySession

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 LivenessWithVerify Session

Solicitud de ejemplo

HTTP

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

Respuesta de muestra

status code:: 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"
      }
    ]
  }
}

Definiciones

Nombre	Description
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.
ImageType	Tipo de imagen.
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.
LivenessWithVerifyOutputs	Salida de comprobación facial.
LivenessWithVerifyReference	Detalle de la cara para la comprobación.
LivenessWithVerifyResult	Resultados de la ejecución con la llamada verify.
LivenessWithVerifySession	Resultado de la sesión de detección de la ejecución con comprobación.
LivenessWithVerifySessionAttempt	La ejecución con el intento de comprobación de la sesión.
LivenessWithVerifySessionResults	Resultados de la ejecución con la sesión de comprobación.
OperationState	Estado actual de la sesión.
QualityForRecognition	Indica la calidad de la imagen para el reconocimiento.

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.

ImageType

Enumeración

Tipo de imagen.

Valor	Description
Color	Imagen en color.
Infrared	Imagen infrarroja.
Depth	Imagen de profundidad.

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.

LivenessWithVerifyOutputs

Object

Salida de comprobación facial.

Nombre	Tipo	Description
isIdentical	boolean	Si la cara de la vida de destino y la coincidencia de la cara de imagen de comparación.
matchConfidence	number (float) minimum: 0 maximum: 1	Confianza de verificación facial de comparación y cara de destino.

LivenessWithVerifyReference

Object

Detalle de la cara para la comprobación.

Nombre	Tipo	Description
faceRectangle	FaceRectangle	Región facial en la que se realizó la clasificación de la imagen de comparación.
qualityForRecognition	QualityForRecognition	Calidad de la imagen facial para el reconocimiento.
referenceType	ImageType	Tipo de imagen que contiene el rectángulo facial en el que se realizó la clasificación de vida.

LivenessWithVerifyResult

Object

Resultados de la ejecución con la llamada verify.

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.
verifyImageHash	string	Hash sha256 de la imagen de comprobación en la solicitud.
verifyResult	LivenessWithVerifyOutputs	Salida de comprobación facial. Solo está disponible cuando la solicitud es activa con la comprobación.

LivenessWithVerifySession

Object

Resultado de la sesión de detección de la ejecución con comprobación.

Nombre	Tipo	Description
authToken	string	Token de portador para proporcionar autenticación para el SDK de Vision que se ejecuta en una aplicación cliente. Este token de portador tiene permisos limitados para realizar solo la acción necesaria y expira después del tiempo de TTL. También es auditable.
modelVersion	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.
results	LivenessWithVerifySessionResults	Resultados de la ejecución con la sesión de comprobación.
sessionId	string	Identificador único que se va a hacer referencia a esta sesión.
status	OperationState	Estado actual de la sesión.

LivenessWithVerifySessionAttempt

Object

La ejecución con el intento de comprobación de la sesión.

Nombre	Tipo	Description
attemptId	integer (int32)	El identificador de intento, comience desde 1.
attemptStatus	OperationState	Estado del intento.
error	LivenessError	El error de la ejecución con la llamada verify será NULL si hay un resultado.
result	LivenessWithVerifyResult	El resultado de la ejecución con la llamada verify será NULL si hay un error.

LivenessWithVerifySessionResults

Object

Resultados de la ejecución con la sesión de comprobación.

Nombre	Tipo	Description
attempts	LivenessWithVerifySessionAttempt[]	Intenta los datos de la ejecución subyacente con la llamada de comprobación con la sesión.
verifyReferences	LivenessWithVerifyReference[]	Referencias usadas para la comprobación facial.

OperationState

Enumeración

Estado actual de la sesión.

Valor	Description
NotStarted	La operación no se ha iniciado.
Running	La operación está en curso.
Succeeded	La operación se ha completado correctamente.
Failed	Error en la operación.
Canceled	El usuario canceló la operación.

QualityForRecognition

Enumeración

Indica la calidad de la imagen para el reconocimiento.

Valor	Description
low	Baja calidad.
medium	Calidad media.
high	Alta calidad.

Compartir a través de

Liveness Session Operations - Create Liveness With Verify Session

Parámetros de identificador URI

Respuestas

Seguridad

Ocp-Apim-Subscription-Key

AADToken

Ámbitos

Ejemplos

Create LivenessWithVerify Session

Solicitud de ejemplo

Respuesta de muestra

Definiciones

FaceError

FaceErrorResponse

FaceRectangle

ImageType

LivenessColorDecisionTarget

LivenessDecision

LivenessDecisionTargets

LivenessError

LivenessModel

LivenessOperationMode

LivenessWithVerifyOutputs

LivenessWithVerifyReference

LivenessWithVerifyResult

LivenessWithVerifySession

LivenessWithVerifySessionAttempt

LivenessWithVerifySessionResults

OperationState

QualityForRecognition