Guides
Start typing to search…

Liveness

El servicio de "Liveness" de JAAK asegura la autenticidad de una persona que se presenta a través de una transmisión de video. Cuando un usuario proporciona un video en formato base64 para una verificación de liveness, el servicio de Liveness analiza una serie de indicadores clave, como movimientos faciales, expresiones y parpadeos, para determinar si la persona en el video es genuina y está presente en el momento de la prueba. El servicio captura lo que llamamos el bestFrame, que es el fotograma con el mejor análisis facial que podemos obtener.


Empezando

Para proceder, es indispensable generar una clave API con un tiempo de expiración definido.

Este proceso puede completarse fácilmente mediante el panel de administrado. Esto garantiza un acceso seguro y gestionado a los recursos necesarios durante el tiempo estipulado.

Para más detalles, consulta la documentación específica de cada método disponible a través de los siguientes enlaces:


Guía Rápida para Usar Liveness

Paso 1: Capturar el Video

  • Abre la cámara del usuario y graba un video. Asegúrate de que el video cumpla con los siguientes criterios:

    • Duración: El video debe tener una duración mínima de 3 segundos y máxima de 8 segundos.
    • Visibilidad: El video debe mostrar claramente el rostro. Si no se detecta ningún rostro, el servicio devolverá un error.
    • Iluminación y Calidad: Asegura una buena iluminación y una captura de video de alta calidad. El rostro debe estar lo suficientemente cerca de la cámara para permitir una visibilidad y análisis claros.

Paso 2: Enviar el Video

  • Codifica el video en formato base64 y envíalo al endpoint /api/v1/liveness/verify-and-bestframe. Este proceso analizará el video y devolverá una foto de la persona (bestFrame) junto con una puntuación que indica el nivel de confianza de la detección de liveness. Para mas información sobre que es el formato Base64 ve a Base64.

Para más detalles visita la referencia de la API aquí.

Paso 3: Revisar los Resultados

  • Examina el bestFrame devuelto y la puntuación de liveness. Esta puntuación ayuda a determinar la probabilidad de que el video haya sido de una persona viva presente en el momento de la grabación en lugar de un video pregrabado o un intento de engaño.

Requisitos

  • Debes tener un video de un rostro que cumpla con los requisitos de duración, visibilidad, iluminación y calidad en Base64.
  • Asegúrate de que el video esté disponible en el dispositivo desde el cual se realizará la prueba.
    Necesitas una clave API válida de una empresa activa y configurarla como Bearer Token en el encabezado de tu solicitud. Para más información sobre el uso del Bearer Token consulta aquí.

Verify

POST basePath/api/v1/liveness/verify

Este endpoint realiza la validación de vida del video base64.

Descripción de la Solicitud

Petición

curl --request POST \
     --url https://sandbox.api.jaak.ai/api/v1/liveness/verify \
     --header 'Authorization: <token-de-acceso>' \
     --header 'Latitude: 40.7128' \
     --header 'Longitude: -74.0060' \
     --header 'Request-Id: d99fe2d2-c0c3-4396-bd97-a502b4c30fa3' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{"video":"string"}'
{
"video": "videoBase64"
}

Agrega localización

Si deseas agregar localización a la ejecución del evento agrega las cabeceras Longitude y Latitude con los valores numericos de la ubicación de la cual se esta ejecutando tu petición.

curl -X POST "https://sandbox.api.jaak.ai/api/v1/liveness/verify" \
     -H 'accept: application/json' \
     -H 'content-type: application/json' \
     -H 'Authorization: Bearer <api_key>' \
     -H 'Longitude: -70' \
     -H 'Latitude: 100' \
     -d '{...}'

Descripción de los parámetros

ParámetroDescripción
videoVideo codificado en Base64 .

Respuesta

{
    "eventId": "73e8babe-8d41-491a-8b88-a3719522f64f",
    "requestId": "73e8babe-8d41-491a-8b88-a3719522f64f",
    "processTime": 2588,
    "score": 0.73340136,
    "state": {
        "isRealPerson": true,
        "message": ""
    }
}

Parámetros de Respuesta

ParámetroDescripción
eventIdIdentificador único del evento de verificación de liveness.
processTimeTiempo en milisegundos que tomó procesar la solicitud de verificación.
requestIdIdentificador único de la solicitud de verificación enviada al servicio de Liveness.
scorePuntuación que indica el nivel de confianza en la detección de liveness. Un valor más alto indica mayor confianza.
Ejemplos de Solicitudes
{
"eventId": "",
"video": "GkXfo59ChoEBQveBAULygQRC84EIQoKEd2Vib -- videoBase64"
}
{
    "eventId": "73e8babe-8d41-491a-8b88-a3719522f64f",
    "requestId": "73e8babe-8d41-491a-8b88-a3719522f64f",
    "processTime": 2588,
    "score": 0.73340136,
    "state": {
        "isRealPerson": true,
        "message": ""
    }
}

Verify and best frame

POST basePath/api/v1/liveness/verify-and-bestframe

Este endpoint realiza la validación de vida del video base64 y obtiene el mejor fotograma del video para el análisis facial.

Descripción de la Solicitud

Petición

curl --request POST \
     --url https://sandbox.api.jaak.ai/api/v1/liveness/verify-and-bestframe \
     --header 'Authorization: <token-de-acceso>' \
     --header 'Latitude: 40.7128' \
     --header 'Longitude: -74.0060' \
     --header 'Request-Id: d99fe2d2-c0c3-4396-bd97-a502b4c30fa3' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{"video":"string"}'
{
"video": "videoBase64"
}

Agrega localización

Si deseas agregar localización a la ejecución del evento agrega las cabeceras Longitude y Latitude con los valores numericos de la ubicación de la cual se esta ejecutando tu petición.

curl -X POST "https://sandbox.api.jaak.ai/api/v1/liveness/verify-and-bestframe" \
     -H 'accept: application/json' \
     -H 'content-type: application/json' \
     -H 'Authorization: Bearer <api_key>' \
     -H 'Longitude: -70' \
     -H 'Latitude: 100' \
     -d '{...}'

Descripción de los parámetros

ParámetroDescripción
videoVideo codificado en Base64 .

Respuesta

{
    "eventId": "73e8babe-8d41-491a-8b88-a3719522f64f",
    "requestId": "73e8babe-8d41-491a-8b88-a3719522f64f",
    "processTime": 2588,
    "score": 0.73340136,
  	"bestFrame": "best_frame_base_64",
    "state": {
        "isRealPerson": true,
        "message": ""
    }
}

Parámetros de Respuesta

ParámetroDescripción
bestFrameMejor fotograma base64 capturado del video para análisis facial.
eventIdIdentificador único del evento de verificación de Liveness.
processTimeTiempo en milisegundos que tomó procesar la solicitud de verificación.
requestIdIdentificador único de la solicitud de verificación enviada al servicio de Liveness.
scorePuntuación que indica el nivel de confianza en la detección de liveness. Un valor más alto indica mayor confianza.
stateSe utiliza para verificar si el rostro capturado corresponde a una persona real durante el proceso de autenticación o verificación en tiempo real.
Ejemplos de Solicitudes
{
"eventId": "",
"video": "GkXfo59ChoEBQveBAULygQRC84EIQoKEd2Vib -- videoBase64"
}
{
    "eventId": "8707c205-1ea3-4481-b888-c472582b3e33",
    "requestId": "8707c205-1ea3-4481-b888-c472582b3e33",
    "processTime": 1717,
    "score": 0.9520403,
    "bestFrame": "iVBORw0KGgoAAAANSUhEUgAAAoAAAAHgI="
}

Integraciones

Ejemplo HTML y JS

Integración web que implementa la guía rápida para usar liveness.

document.getElementById('startButton').addEventListener('click', function() {
    let video = document.getElementById('video');
    let mediaRecorder;
    let recordedBlobs;

    navigator.mediaDevices.getUserMedia({ video: true, audio: false })
        .then(stream => {
            video.srcObject = stream;
            let options = { mimeType: 'video/webm; codecs=vp9' };
            recordedBlobs = [];
            mediaRecorder = new MediaRecorder(stream, options);
            
            mediaRecorder.ondataavailable = (event) => {
                if (event.data && event.data.size > 0) {
                    recordedBlobs.push(event.data);
                }
            };
            
            mediaRecorder.onstop = () => {
                const videoBlob = new Blob(recordedBlobs, { type: 'video/webm' });
                const reader = new FileReader();
                
                reader.onload = () => {
                    const base64String = reader.result;
                    console.log('Base64 Video String:', base64String);
                  //AQUÍ DEBES ENVIAR EL VIDEO A LA API
                };
                
                reader.readAsDataURL(videoBlob);
                stream.getTracks().forEach(track => track.stop()); // Detener la transmisión de la cámara
            };

            mediaRecorder.start();
            console.log('MediaRecorder started', mediaRecorder);

            // Detener la grabación después de 4 segundos
            setTimeout(() => {
                mediaRecorder.stop();
            }, 4000);
        })
        .catch(error => {
            console.error('Error al acceder a los dispositivos de medios.', error);
        });
});
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Capturar Video de 4 Segundos</title>
</head>
<body>
<video id="video" width="720" height="480" autoplay></video>
<button id="startButton">Iniciar Grabación</button>
<video id="recorded" width="720" height="480" controls></video>
<script src="app.js"></script>
</body>
</html>

📘

Obtener video como una cadena base64

Conversión a Base64:

  • Creación de un Blob: Una vez que se detiene la grabación, se crea un Blob a partir de recordedBlobs, que contiene los datos del video.
  • Lectura del Blob: Se utiliza un FileReader para leer los datos del Blob.
  • Conversión a Base64: El FileReader lee el Blob como una URL de datos (que incluye datos codificados en Base64). Cuando la lectura está completa, se dispara el evento onload, y el atributo result del FileReader contiene la cadena codificada en Base64 del video.
  • Registro de la Cadena Base64: La cadena Base64 se registra en la consola. También puedes usar esta cadena para enviar los datos del video a un servidor o procesarlos según sea necesario.

Para obtener información más detallada sobre la integración y solución de problemas de esta API, consulta la documentación de la API de Liveness. Asegúrate de manejar los datos de manera sensible y conforme a las regulaciones de privacidad.

Updated about 2 months ago