Tutorial: Detección de vivacidad en caras

Obtenga información sobre cómo integrar la detección de caras reales en el flujo de trabajo mediante la lógica del lado servidor y las aplicaciones cliente de front-end complementarias.

Sugerencia

Para obtener información general sobre la detección de vitalidad facial, consulte la guía conceptual.

En este tutorial, aprenderá a ejecutar una aplicación de front-end con un servidor de aplicaciones para realizar la detección real. También puede agregar la comprobación facial en varias plataformas e idiomas.

Importante

Los SDK de cliente de Face para la vivacidad son una característica cerrada. Debe solicitar el acceso a la característica de vivacidad rellenando el formulario de acceso de reconocimiento facial. Cuando su suscripción a Azure tenga acceso, podrá descargar el SDK de vivacidad de Face.

Requisitos previos

Una suscripción a Azure: cree una cuenta gratuita
Para poder aceptar los términos de IA responsable y crear un recurso, su cuenta de Azure debe tener asignado un rol de Colaborador de Cognitive Services. Para asignar este rol a su cuenta, siga los pasos descritos en la documentación Asignación de roles o póngase en contacto con el administrador.
Una vez que tenga la suscripción de Azure, cree un recurso de Face en el portal de Azure para obtener su clave y punto de conexión. Tras su implementación, seleccione Ir al recurso.
- Necesita la clave y el punto de conexión del recurso que cree para conectar la aplicación al servicio Face.
Acceso a los artefactos cerrados necesarios para Azure Vision en Foundry Tools Face Client SDK para dispositivos móviles (iOS y Android) y Web.
- Para la introducción, debe solicitar las Características de acceso limitado con reconocimiento facial para obtener acceso al SDK. Para más información, consulte la página de Acceso limitado a Face.
Familiaridad con la función de detección de vitalidad del rostro. Consulte la guía conceptual.

Sugerencia

Después de completar los prerrequisitos, puede probar la experiencia de actividad en vivo en las siguientes plataformas:

iOS: App Store de iOS : pulsa la pantalla de la aplicación 10 veces después de la instalación para habilitar el modo de desarrollador.
Android: Google Play Store : pulsa la pantalla de la aplicación 10 veces después de la instalación para habilitar el modo de desarrollador.
Web: pruébelo directamente en Vision Studio.

También puede compilar y ejecutar un ejemplo de front-end completo (iOS, Android o Web) desde la sección Ejemplos .

Preparación de la aplicación de front-end

Proporcionamos SDK en varios lenguajes para simplificar la integración con la aplicación de front-end. Consulte el archivo Léame del SDK elegido en las secciones siguientes para integrar la interfaz de usuario y el código necesario.

Importante

Cada SDK de front-end requiere acceso a un recurso cerrado para compilar correctamente. Consulte las instrucciones siguientes para configurar este acceso.

Para Swift iOS:

Componentes: SDK de interfaz de usuario de Azure AI Face para iOS
Referencia de API: Referencia de AzureAIVisionFaceUI
Ejemplo: ejemplo de iOS

Para Kotlin/Java Android:

Artefactos: Maven Central: com.azure:azure-ai-vision-face-ui
Referencia de API: azure-ai-vision-face-ui Reference
Ejemplo: Ejemplo de Android

Para JavaScript Web:

Artefacto: @azure/ai-vision-face-ui - npm
Referencia de API: Referencia de AzureAIVisionFaceUI
Ejemplo: Ejemplo web
Compatibilidad con marcos de trabajo: funciona con marcos populares como React (incluido Next.js), Vue.jsy Angular.

Una vez integrado en su aplicación frontend, el SDK inicia la cámara, guía al usuario para ajustar su posición, compone los datos de liveness y los envía al servicio Azure AI Face para su procesamiento.

Supervise la sección Versiones del repositorio para ver las nuevas actualizaciones de la versión del SDK y habilite las alertas de actualización de dependencias automatizadas, como GitHub Dependabot (para repositorios de GitHub) o Renovado (GitHub, GitLab, Bitbucket, Azure Repos).

Realización de la detección de vivacidad

En los pasos siguientes se describe el proceso de orquestación de actividad:

La aplicación frontend inicia la comprobación de liveness y lo notifica al servidor de aplicaciones.

El servidor de aplicaciones crea una nueva sesión de ejecución con Azure AI Face Service. El servicio crea una sesión de ejecución y responde con un token de autorización de sesión. Para obtener más información sobre cada parámetro de solicitud implicado en la creación de una sesión de ejecución, consulte Operación de creación de sesión en vivo.

var endpoint = new Uri(System.Environment.GetEnvironmentVariable("FACE_ENDPOINT"));
var key = new AzureKeyCredential(System.Environment.GetEnvironmentVariable("FACE_APIKEY"));

var body = JsonSerializer.Serialize(new
{
    livenessOperationMode = "PassiveActive",
    deviceCorrelationId = "723d6d03-ef33-40a8-9682-23a1feb7bccd",
    enableSessionImage = true
});

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", key);

var response = await client.PostAsync(
    $"{endpoint}/face/v1.2/detectLiveness-sessions",
    new StringContent(body, Encoding.UTF8, "application/json"));

response.EnsureSuccessStatusCode();

using var doc  = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var root       = doc.RootElement;

Console.WriteLine("Session created");
Console.WriteLine($"sessionId : {root.GetProperty("sessionId").GetString()}");
Console.WriteLine($"authToken : {root.GetProperty("authToken").GetString()}");

String endpoint = System.getenv("FACE_ENDPOINT");
String key = System.getenv("FACE_APIKEY");

String body = """
{
    "livenessOperationMode": "PassiveActive",
    "deviceCorrelationId": "723d6d03-ef33-40a8-9682-23a1feb7bccd",
    "enableSessionImage": true,
}
""";

HttpRequest req = HttpRequest.newBuilder()
        .uri(URI.create(endpoint + "/face/v1.2/detectLiveness-sessions"))
        .header("Content-Type", "application/json")
        .header("Ocp-Apim-Subscription-Key", key)
        .POST(HttpRequest.BodyPublishers.ofString(body))
        .build();

HttpResponse<String> res = HttpClient.newHttpClient()
        .send(req, HttpResponse.BodyHandlers.ofString());

if (res.statusCode() != 200) throw new RuntimeException("HTTP error: " + res.statusCode());

JsonNode json = new ObjectMapper().readTree(res.body());
System.out.println("Session created");
System.out.println("sessionId : " + json.get("sessionId").asText());
System.out.println("authToken : " + json.get("authToken").asText());

endpoint = os.environ["FACE_ENDPOINT"]
key = os.environ["FACE_APIKEY"]

url  = f"{endpoint}/face/v1.2/detectLiveness-sessions"
body = {
    "livenessOperationMode": "PassiveActive",
    "deviceCorrelationId":  "723d6d03-ef33-40a8-9682-23a1feb7bccd",
    "enableSessionImage":   True
}

headers = {
    "Ocp-Apim-Subscription-Key": key,
    "Content-Type": "application/json"
}

res = requests.post(url, headers=headers, data=json.dumps(body))
res.raise_for_status()

data = res.json()
print("Session created")
print("sessionId :", data["sessionId"])
print("authToken :", data["authToken"])

const endpoint = process.env['FACE_ENDPOINT'];
const apikey = process.env['FACE_APIKEY'];

const url  = `${endpoint}/face/v1.2/detectLiveness-sessions`;
const body = {
    livenessOperationMode: "PassiveActive",
    deviceCorrelationId:  "723d6d03-ef33-40a8-9682-23a1feb7bccd",
    enableSessionImage:   true
};

const headers = {
    "Ocp-Apim-Subscription-Key": key,
    "Content-Type": "application/json"
};

async function createLivenessSession() {
    const res = await fetch(url, {
        method: "POST",
        headers,
        body: JSON.stringify(body)
    });

    if (!res.ok) {
        throw new Error(`${res.status} ${await res.text()}`);
    }

    const data = await res.json();
    console.log("Session created");
    console.log("sessionId :", data.sessionId);
    console.log("authToken :", data.authToken);
}

curl --request POST --location "%FACE_ENDPOINT%/face/v1.2/detectLiveness-sessions" ^
--header "Ocp-Apim-Subscription-Key: %FACE_APIKEY%" ^
--header "Content-Type: application/json" ^
--data ^
"{ ^
    ""livenessOperationMode"": ""passiveactive"", ^
    ""deviceCorrelationId"": ""723d6d03-ef33-40a8-9682-23a1feb7bccd"", ^
    ""enableSessionImage"": ""true"" ^
}"

curl --request POST --location "${FACE_ENDPOINT}/face/v1.2/detectLivenesswithVerify-sessions" \
--header "Ocp-Apim-Subscription-Key: ${FACE_APIKEY}" \
--header "Content-Type: application/json" \
--data \
'{
    "livenessOperationMode": "passiveactive",
    "deviceCorrelationId": "723d6d03-ef33-40a8-9682-23a1feb7bccd",
    "enableSessionImage": "true"
}'

Ejemplo del cuerpo de la respuesta:

{
    "sessionId": "a6e7193e-b638-42e9-903f-eaf60d2b40a5",
    "authToken": "<session-authorization-token>",
    "status": "NotStarted",
    "modelVersion": "2025-05-20",
    "results": {
        "attempts": []
    }
}

El servidor de aplicaciones devuelve el token de autorización de sesión a la aplicación de front-end.

La aplicación front-end utiliza el token de autorización de sesión para iniciar el detector de caras reales, que pone en marcha el flujo de vivacidad.

    FaceLivenessDetector(
        sessionAuthorizationToken = FaceSessionToken.sessionToken,
        verifyImageFileContent = FaceSessionToken.sessionSetInClientVerifyImage,
        deviceCorrelationId = "null",
        onSuccess = viewModel::onSuccess,
        onError = viewModel::onError
    )

struct HostView: View {
   @State var livenessDetectionResult: LivenessDetectionResult? = nil
   var token: String
   var body: some View {
       if livenessDetectionResult == nil {
           FaceLivenessDetectorView(result: $livenessDetectionResult,
                                    sessionAuthorizationToken: token)
       } else if let result = livenessDetectionResult {
           VStack {
               switch result { 
                   case .success(let success):
                   /// <#show success#>
                   case .failure(let error):
                   /// <#show failure#>
               }
           }
       }
   }
}

faceLivenessDetector = document.createElement("azure-ai-vision-face-ui");
document.getElementById("container").appendChild(faceLivenessDetector);
faceLivenessDetector.start(session.authToken)

El SDK inicia la cámara, guía al usuario para que se coloque correctamente y, a continuación, prepara la carga para llamar al punto de conexión de servicio de detección de vivacidad.
El SDK llama al servicio Face de Visión de Azure para realizar la detección de la vivacidad. Una vez que el servicio responde, el SDK notifica a la aplicación de front-end que se ha completado la comprobación de ejecución. Nota: la respuesta del servicio no contiene la decisión de vivacidad. Debe consultar esta información desde el servidor de aplicaciones.
La aplicación de front-end retransmite la finalización de la comprobación de vivacidad al servidor de aplicaciones.

El servidor de aplicaciones consulta el resultado de la detección de vivacidad del servicio Azure Vision Face.

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", key);

var response = await client.GetAsync(
    $"{endpoint}/face/v1.2/livenessSessions/{sessionId}/result");

response.EnsureSuccessStatusCode();

using var doc = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var root = doc.RootElement;
var attempts = root.GetProperty("results").GetProperty("attempts");
var latestAttempt = attempts[attempts.GetArrayLength() - 1];
var attemptStatus = latestAttempt.GetProperty("attemptStatus").GetString();

Console.WriteLine($"Session id: {root.GetProperty("sessionId").GetString()}");
Console.WriteLine($"Session status: {root.GetProperty("status").GetString()}");
Console.WriteLine($"Latest attempt status: {attemptStatus}");

if (attemptStatus == "Succeeded")
    Console.WriteLine($"Liveness detection decision: {latestAttempt.GetProperty("result").GetProperty("livenessDecision").GetString()}");
else
{
    var error = latestAttempt.GetProperty("error");
    Console.WriteLine($"Error: {error.GetProperty("code").GetString()} - {error.GetProperty("message").GetString()}");
}

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(endpoint + "/face/v1.2/livenessSessions/" + sessionId + "/result"))
    .header("Ocp-Apim-Subscription-Key", key)
    .GET()
    .build();

HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());

if (res.statusCode() != 200) throw new RuntimeException("HTTP error: " + res.statusCode());

JsonNode root = new ObjectMapper().readTree(res.body());
JsonNode attempts = root.path("results").path("attempts");
JsonNode latestAttempt = attempts.get(attempts.size() - 1);

String attemptStatus = latestAttempt.path("attemptStatus").asText();

System.out.println("Session id: " + root.path("sessionId").asText());
System.out.println("Session status: " + root.path("status").asText());
System.out.println("Latest attempt status: " + attemptStatus);

if ("Succeeded".equals(attemptStatus)) {
    System.out.println("Liveness detection decision: " +
        latestAttempt.path("result").path("livenessDecision").asText());
} else {
    JsonNode error = latestAttempt.path("error");
    System.out.println("Error: " + error.path("code").asText() + " - " +
        error.path("message").asText());
}

url = f"{endpoint}/face/v1.2/livenessSessions/{sessionId}/result"
headers = { "Ocp-Apim-Subscription-Key": key }

res = requests.get(url, headers=headers)
res.raise_for_status()

data = res.json()
attempts = data["results"]["attempts"]
latest_attempt = attempts[-1]
attempt_status = latest_attempt.get("attemptStatus")

print(f"Session id: {data['sessionId']}")
print(f"Session status: {data['status']}")
print(f"Latest attempt status: {attempt_status}")

if attempt_status == "Succeeded":
    print(f"Liveness detection decision: {latest_attempt['result']['livenessDecision']}")
else:
    err = latest_attempt.get("error", {})
    print(f"Error: {err.get('code')} - {err.get('message')}")

const url = `${endpoint}/face/v1.2/livenessSessions/${sessionId}/result`;
const headers = {
    "Ocp-Apim-Subscription-Key": apikey
};

async function getLivenessSessionResult() {
    const res = await fetch(url, { method: "GET", headers });
    if (!res.ok) {
        throw new Error(`${res.status} ${await res.text()}`);
    }

    const data = await res.json();
    const attempts = data.results.attempts;
    const latestAttempt = attempts[attempts.length - 1];
    const attemptStatus = latestAttempt.attemptStatus;

    console.log("Session id :", data.sessionId);
    console.log("Session status :", data.status);
    console.log("Latest attempt status :", attemptStatus);

    if (attemptStatus === "Succeeded") {
        console.log("Liveness detection decision :", latestAttempt.result.livenessDecision);
    } else {
            const err = latestAttempt.error || {};
            console.log(`Error: ${err.code} - ${err.message}`);
    }
}

curl --request GET --location "%FACE_ENDPOINT%/face/v1.2/detectLiveness-sessions/<session-id>" ^
--header "Ocp-Apim-Subscription-Key: %FACE_APIKEY%"

curl --request GET --location "${FACE_ENDPOINT}/face/v1.2/detectLiveness-sessions/<session-id>" \
--header "Ocp-Apim-Subscription-Key: ${FACE_APIKEY}"

Ejemplo del cuerpo de la respuesta:

{
    "sessionId": "b12e033e-bda7-4b83-a211-e721c661f30e",
    "authToken": "eyJhbGciOiJFUzI1NiIsIm",
    "status": "NotStarted",
    "modelVersion": "2024-11-15",
    "results": {
        "attempts": [
            {
                "attemptId": 2,
                "attemptStatus": "Succeeded",
                "result": {
                "livenessDecision": "realface",
                "targets": {
                    "color": {
                    "faceRectangle": {
                            "top": 669,
                            "left": 203,
                            "width": 646,
                            "height": 724
                        }
                    }
                },
                "digest": "B0A803BB7B26F3C8F29CD36030F8E63ED3FAF955FEEF8E01C88AB8FD89CCF761",
                "sessionImageId": "Ae3PVWlXAmVAnXgkAFt1QSjGUWONKzWiSr2iPh9p9G4I"
                }
            },
            {
                "attemptId": 1,
                "attemptStatus": "Failed",
                "error": {
                "code": "FaceWithMaskDetected",
                "message": "Mask detected on face image.",
                "targets": {
                        "color": {
                        "faceRectangle": {
                            "top": 669,
                            "left": 203,
                            "width": 646,
                            "height": 724
                        }
                        }
                    }
                }
            }
        ]
    }
}

El servidor de aplicaciones elimina la sesión después de consultar todos los resultados de la sesión.

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", key);

await client.DeleteAsync($"{endpoint}/face/v1.2/livenessSessions/{sessionId}");
Console.WriteLine($"Session deleted: {sessionId}");

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(endpoint + "/face/v1.2/livenessSessions/" + sessionId))
    .header("Ocp-Apim-Subscription-Key", key)
    .DELETE()
    .build();

HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
System.out.println("Session deleted: " + sessionId);

headers = { "Ocp-Apim-Subscription-Key": key }
requests.delete(f"{endpoint}/face/v1.2/livenessSessions/{sessionId}", headers=headers)
print(f"Session deleted: {sessionId}")

const headers = { "Ocp-Apim-Subscription-Key": apikey };
await fetch(`${endpoint}/face/v1.2/livenessSessions/${sessionId}`, { method: "DELETE", headers });
console.log(`Session deleted: ${sessionId}`);

curl --request DELETE --location "%FACE_ENDPOINT%/face/v1.2/detectLiveness-sessions/<session-id>" ^
--header "Ocp-Apim-Subscription-Key: %FACE_APIKEY%"

curl --request DELETE --location "${FACE_ENDPOINT}/face/v1.2/detectLiveness-sessions/<session-id>" \
--header "Ocp-Apim-Subscription-Key: ${FACE_APIKEY}"

Realización de la detección de vivacidad con verificación facial

La combinación de la verificación facial con detección de vivacidad permite la verificación biométrica de una persona determinada de interés con una garantía agregada de que la persona está físicamente presente en el sistema.

La integración de la detección de vivacidad con verificación consta de dos partes:

Paso 1: Seleccionar una imagen de referencia

Para obtener los resultados de reconocimiento más precisos, siga las sugerencias enumeradas en los requisitos de composición para escenarios de comprobación de identificadores.

Paso 2: configuración de la orquestación de la verificación de vivacidad

Los siguientes pasos generales muestran cómo orquestar la disponibilidad con verificación:

Proporcione la imagen de referencia de verificación mediante uno de los dos métodos siguientes:

El servidor de aplicaciones proporciona la imagen de referencia al crear la sesión de vivacidad. Para obtener más información sobre cada parámetro de solicitud implicado en la creación de una sesión de liveness con verificación, vea Liveness With Verify Create Session Operation.

var endpoint = new Uri(System.Environment.GetEnvironmentVariable("FACE_ENDPOINT"));
var key      = System.Environment.GetEnvironmentVariable("FACE_APIKEY");

// Create the JSON part
var jsonPart = new StringContent(
    JsonSerializer.Serialize(new
    {
        livenessOperationMode = "PassiveActive",
        deviceCorrelationId = "723d6d03-ef33-40a8-9682-23a1feb7bcc",
        enableSessionImage = true
    }),
    Encoding.UTF8,
    "application/json"
);
jsonPart.Headers.ContentDisposition = new ContentDispositionHeaderValue("form-data")
{
    Name = "CreateLivenessWithVerifySessionRequest"
};

// Create the file part
using var fileStream = File.OpenRead("test.png");
var filePart = new StreamContent(fileStream);
filePart.Headers.ContentType = new MediaTypeHeaderValue("image/png");
filePart.Headers.ContentDisposition = new ContentDispositionHeaderValue("form-data")
{
    Name = "VerifyImage",
    FileName = "test.png"
};

// Build multipart form data
using var formData = new MultipartFormDataContent();
formData.Add(jsonPart);
formData.Add(filePart);

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", key);

var response = await client.PostAsync($"{endpoint}/face/v1.2/createLivenessWithVerifySession", formData);
response.EnsureSuccessStatusCode();

using var doc = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var root = doc.RootElement;

Console.WriteLine("Session created.");
Console.WriteLine($"Session id: {root.GetProperty("sessionId").GetString()}");
Console.WriteLine($"Auth token: {root.GetProperty("authToken").GetString()}");

String endpoint = System.getenv("FACE_ENDPOINT");
String key      = System.getenv("FACE_APIKEY");

String json = """
{
"livenessOperationMode": "PassiveActive",
"deviceCorrelationId": "723d6d03-ef33-40a8-9682-23a1feb7bcc",
"enableSessionImage": true
}
""";

byte[] img = Files.readAllBytes(Path.of("test.png"));
String boundary = "----faceBoundary" + java.util.UUID.randomUUID();

var head =
    "--" + boundary + "\r\n" +
    "Content-Disposition: form-data; name=\"CreateLivenessWithVerifySessionRequest\"\r\n" +
    "Content-Type: application/json\r\n\r\n" +
    json + "\r\n" +
    "--" + boundary + "\r\n" +
    "Content-Disposition: form-data; name=\"VerifyImage\"; filename=\"test.png\"\r\n" +
    "Content-Type: image/png\r\n\r\n";

var tail = "\r\n--" + boundary + "--\r\n";

byte[] body = java.nio.ByteBuffer
    .allocate(head.getBytes(StandardCharsets.UTF_8).length + img.length + tail.getBytes(StandardCharsets.UTF_8).length)
    .put(head.getBytes(StandardCharsets.UTF_8))
    .put(img)
    .put(tail.getBytes(StandardCharsets.UTF_8))
    .array();

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(endpoint + "/face/v1.2/createLivenessWithVerifySession"))
    .header("Ocp-Apim-Subscription-Key", key)
    .header("Content-Type", "multipart/form-data; boundary=" + boundary)
    .POST(HttpRequest.BodyPublishers.ofByteArray(body))
    .build();

HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
if (res.statusCode() != 200) throw new RuntimeException("HTTP error: " + res.statusCode());

JsonNode root = new ObjectMapper().readTree(res.body());
System.out.println("Session created.");
System.out.println("Session id: " + root.get("sessionId").asText());
System.out.println("Auth token: " + root.get("authToken").asText());

endpoint = os.environ["FACE_ENDPOINT"]
key      = os.environ["FACE_APIKEY"]

url = f"{endpoint}/face/v1.2/createLivenessWithVerifySession"
files = {
    "CreateLivenessWithVerifySessionRequest": (
        "request.json",
        json.dumps({
            "livenessOperationMode": "PassiveActive",
            "deviceCorrelationId": "723d6d03-ef33-40a8-9682-23a1feb7bcc",
            "enableSessionImage": True
        }),
        "application/json"
    ),
    "VerifyImage": ("test.png", open("test.png", "rb"), "image/png")
}
headers = { "Ocp-Apim-Subscription-Key": key }

res = requests.post(url, headers=headers, files=files)
res.raise_for_status()

data = res.json()
print("Session created.")
print("Session id:", data["sessionId"])
print("Auth token:", data["authToken"])

const endpoint = process.env["FACE_ENDPOINT"];
const apikey   = process.env["FACE_APIKEY"];

const form = new FormData();
form.append(
    "CreateLivenessWithVerifySessionRequest",
    new Blob([JSON.stringify({
        livenessOperationMode: "PassiveActive",
        deviceCorrelationId: "723d6d03-ef33-40a8-9682-23a1feb7bcc",
        enableSessionImage: true
    })], { type: "application/json" }),
    "request.json"
);
// If your runtime doesn't support Blob here, you can use fs.createReadStream instead.
form.append("VerifyImage", new Blob([fs.readFileSync("test.png")], { type: "image/png" }), "test.png");

const res = await fetch(`${endpoint}/face/v1.2/createLivenessWithVerifySession`, {
    method: "POST",
    headers: { "Ocp-Apim-Subscription-Key": apikey },
    body: form
});
if (!res.ok) {
    throw new Error(`${res.status} ${await res.text()}`);
}

const data = await res.json();
console.log("Session created.");
console.log("Session id:", data.sessionId);
console.log("Auth token:", data.authToken);

curl --request POST --location "%FACE_ENDPOINT%/face/v1.2/detectLivenesswithVerify-sessions" ^
--header "Ocp-Apim-Subscription-Key: %FACE_APIKEY%" ^
--form "Parameters=""{\\\""livenessOperationMode\\\"": \\\""passiveactive\\\"", \\\""deviceCorrelationId\\\"": \\\""723d6d03-ef33-40a8-9682-23a1feb7bccd\\\"", ""enableSessionImage"": ""true""}""" ^
--form "VerifyImage=@""test.png"""

curl --request POST --location "${FACE_ENDPOINT}/face/v1.2/detectLivenesswithVerify-sessions" \
--header "Ocp-Apim-Subscription-Key: ${FACE_APIKEY}" \
--form 'Parameters="{
    \"livenessOperationMode\": \"passiveactive\",
    \"deviceCorrelationId\": \"723d6d03-ef33-40a8-9682-23a1feb7bccd\"
}"' \
--form 'VerifyImage=@"test.png"'

Ejemplo del cuerpo de la respuesta:

{
    "sessionId": "3847ffd3-4657-4e6c-870c-8e20de52f567",
    "authToken": "<session-authorization-token>",
    "status": "NotStarted",
    "modelVersion": "2024-11-15",
    "results": {
        "attempts": [],
        "verifyReferences": [
        {
            "referenceType": "image",
            "faceRectangle": {
            "top": 98,
            "left": 131,
            "width": 233,
            "height": 300
            },
            "qualityForRecognition": "high"
        }
        ]
    }
}

La aplicación de front-end proporciona la imagen de referencia al inicializar los SDK móviles. Este escenario no se admite en la solución web.

    FaceLivenessDetector(
        sessionAuthorizationToken = FaceSessionToken.sessionToken,
        verifyImageFileContent = FaceSessionToken.sessionSetInClientVerifyImage,
        deviceCorrelationId = "null",
        onSuccess = viewModel::onSuccess,
        onError = viewModel::onError
    )

struct HostView: View {
    @State var livenessDetectionResult: LivenessDetectionResult? = nil
    var token: String
    var body: some View {
        if livenessDetectionResult == nil {
            FaceLivenessDetectorView(result: $livenessDetectionResult,
                                        sessionAuthorizationToken: token)
        } else if let result = livenessDetectionResult {
            VStack {
                switch result { 
                    case .success(let success):
                    /// <#show success#>
                    case .failure(let error):
                    /// <#show failure#>
                }
            }
        }
    }
}

Not supported.

El servidor de aplicaciones ahora puede consultar el resultado de la verificación además del resultado de vivacidad.

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", key);

var response = await client.GetAsync($"{endpoint}/face/v1.2/livenessSessions/{sessionId}/result");
response.EnsureSuccessStatusCode();

using var doc = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var root = doc.RootElement;

var attempts = root.GetProperty("results").GetProperty("attempts");
var latestAttempt = attempts[attempts.GetArrayLength() - 1];
var attemptStatus = latestAttempt.GetProperty("attemptStatus").GetString();

Console.WriteLine($"Session id: {root.GetProperty("sessionId").GetString()}");
Console.WriteLine($"Session status: {root.GetProperty("status").GetString()}");
Console.WriteLine($"Latest attempt status: {attemptStatus}");

if (attemptStatus == "Succeeded")
{
    var decision = latestAttempt.GetProperty("result").GetProperty("livenessDecision").GetString();
    var verify   = latestAttempt.GetProperty("verifyResult");
    Console.WriteLine($"Liveness detection decision: {decision}");
    Console.WriteLine($"Verify isIdentical: {verify.GetProperty("isIdentical").GetBoolean()}");
    Console.WriteLine($"Verify matchConfidence: {verify.GetProperty("matchConfidence").GetDouble()}");
}
else
{
    var err = latestAttempt.GetProperty("error");
    Console.WriteLine($"Error: {err.GetProperty("code").GetString()} - {err.GetProperty("message").GetString()}");
}

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(endpoint + "/face/v1.2/livenessSessions/" + sessionId + "/result"))
    .header("Ocp-Apim-Subscription-Key", key)
    .GET()
    .build();

HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
if (res.statusCode() != 200) throw new RuntimeException("HTTP error: " + res.statusCode());

ObjectMapper om = new ObjectMapper();
JsonNode root = om.readTree(res.body());

JsonNode attempts = root.path("results").path("attempts");
JsonNode latest   = attempts.get(attempts.size() - 1);
String attemptStatus = latest.path("attemptStatus").asText();

System.out.println("Session id: " + root.path("sessionId").asText());
System.out.println("Session status: " + root.path("status").asText());
System.out.println("Latest attempt status: " + attemptStatus);

if ("Succeeded".equals(attemptStatus)) {
    String decision = latest.path("result").path("livenessDecision").asText();
    JsonNode verify = latest.path("verifyResult");
    System.out.println("Liveness detection decision: " + decision);
    System.out.println("Verify isIdentical: " + verify.path("isIdentical").asBoolean());
    System.out.println("Verify matchConfidence: " + verify.path("matchConfidence").asDouble());
} else {
    JsonNode err = latest.path("error");
    System.out.println("Error: " + err.path("code").asText() + " - " + err.path("message").asText());
}

url = f"{endpoint}/face/v1.2/livenessSessions/{sessionId}/result"
headers = {"Ocp-Apim-Subscription-Key": key}

res = requests.get(url, headers=headers)
res.raise_for_status()

data = res.json()
attempts = data["results"]["attempts"]
latest = attempts[-1]
attempt_status = latest.get("attemptStatus")

print(f"Session id: {data['sessionId']}")
print(f"Session status: {data['status']}")
print(f"Latest attempt status: {attempt_status}")

if attempt_status == "Succeeded":
    decision = latest["result"]["livenessDecision"]
    verify   = latest.get("verifyResult", {})
    print(f"Liveness detection decision: {decision}")
    print(f"Verify isIdentical: {verify.get('isIdentical')}")
    print(f"Verify matchConfidence: {verify.get('matchConfidence')}")
else:
    err = latest.get("error", {})
    print(f"Error: {err.get('code')} - {err.get('message')}")

const url = `${endpoint}/face/v1.2/livenessSessions/${sessionId}/result`;
const headers = { "Ocp-Apim-Subscription-Key": apikey };

async function getLivenessWithVerifyResult() {
const res = await fetch(url, { method: "GET", headers });
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);

const data = await res.json();
const attempts = data.results.attempts;
const latest = attempts[attempts.length - 1];
const attemptStatus = latest.attemptStatus;

console.log("Session id:", data.sessionId);
console.log("Session status:", data.status);
console.log("Latest attempt status:", attemptStatus);

if (attemptStatus === "Succeeded") {
    console.log("Liveness detection decision:", latest.result.livenessDecision);
    console.log("Verify isIdentical:", latest.verifyResult?.isIdentical);
    console.log("Verify matchConfidence:", latest.verifyResult?.matchConfidence);
} else {
    const err = latest.error || {};
    console.log(`Error: ${err.code} - ${err.message}`);
}
}

curl --request GET --location "%FACE_ENDPOINT%/face/v1.2/detectLivenesswithVerify-sessions/<session-id>" ^
--header "Ocp-Apim-Subscription-Key: %FACE_APIKEY%"

curl --request GET --location "${FACE_ENDPOINT}/face/v1.2/detectLivenesswithVerify-sessions/<session-id>" \
--header "Ocp-Apim-Subscription-Key: ${FACE_APIKEY}"

Ejemplo del cuerpo de la respuesta:

{
    "sessionId": "b12e033e-bda7-4b83-a211-e721c661f30e",
    "authToken": "eyJhbGciOiJFUzI1NiIsIm",
    "status": "NotStarted",
    "modelVersion": "2024-11-15",
    "results": {
        "attempts": [
        {
            "attemptId": 2,
            "attemptStatus": "Succeeded",
            "result": {
            "livenessDecision": "realface",
            "targets": {
                "color": {
                "faceRectangle": {
                    "top": 669,
                    "left": 203,
                    "width": 646,
                    "height": 724
                }
                }
            },
            "verifyResult": {
                "matchConfidence": 0.08871888,
                "isIdentical": false
            },
            "digest": "B0A803BB7B26F3C8F29CD36030F8E63ED3FAF955FEEF8E01C88AB8FD89CCF761",
            "sessionImageId": "Ae3PVWlXAmVAnXgkAFt1QSjGUWONKzWiSr2iPh9p9G4I",
            "verifyImageHash": "43B7D8E8769533C3290DBD37A84D821B2C28CB4381DF9C6784DBC4AAF7E45018"
            }
        },
        {
            "attemptId": 1,
            "attemptStatus": "Failed",
            "error": {
                "code": "FaceWithMaskDetected",
                "message": "Mask detected on face image.",
                "targets": {
                    "color": {
                    "faceRectangle": {
                            "top": 669,
                            "left": 203,
                            "width": 646,
                            "height": 724
                        }
                    }
                }
            }
        }
        ],
        "verifyReferences": [
            {
                "referenceType": "image",
                "faceRectangle": {
                "top": 316,
                "left": 131,
                "width": 498,
                "height": 677
                },
                "qualityForRecognition": "high"
            }
        ]
        }
    }

El servidor de aplicaciones puede eliminar la sesión si ya no necesita su resultado.

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", key);

await client.DeleteAsync($"{endpoint}/face/v1.2/livenessWithVerifySessions/{sessionId}");
Console.WriteLine($"Liveness-with-Verify session deleted: {sessionId}");

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(endpoint + "/face/v1.2/livenessWithVerifySessions/" + sessionId))
    .header("Ocp-Apim-Subscription-Key", key)
    .DELETE()
    .build();

HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
System.out.println("Liveness-with-Verify session deleted: " + sessionId);

headers = { "Ocp-Apim-Subscription-Key": key }
requests.delete(f"{endpoint}/face/v1.2/livenessWithVerifySessions/{sessionId}", headers=headers)
print(f"Liveness-with-Verify session deleted: {sessionId}")

const headers = { "Ocp-Apim-Subscription-Key": apikey };
await fetch(`${endpoint}/face/v1.2/livenessWithVerifySessions/${sessionId}`, { method: "DELETE", headers });
console.log(`Liveness-with-Verify session deleted: ${sessionId}`);

curl --request DELETE --location "%FACE_ENDPOINT%/face/v1.2/detectLivenesswithVerify-sessions/<session-id>" ^
--header "Ocp-Apim-Subscription-Key: %FACE_APIKEY%"

curl --request DELETE --location "${FACE_ENDPOINT}/face/v1.2/detectLivenesswithVerify-sessions/<session-id>" \
--header "Ocp-Apim-Subscription-Key: ${FACE_APIKEY}"

Realizar otras operaciones faciales después de la detección de vivacidad

De forma opcional, puede realizar operaciones faciales adicionales después de la verificación de vivacidad, como el análisis facial (para obtener atributos faciales) y operaciones de identidad de cara.

Establezca el enableSessionImage parámetro en true durante el paso de creación de sesión.
Extraiga el sessionImageId del paso Session-Get-Result.
Descargue la imagen de sesión (a la que se hace referencia en Liveness Get Session Image Operation API) o proporcione el sessionImageId en la operación Detect from Session Image ID API para realizar otros análisis faciales u operaciones de reconocimiento facial. Para obtener más información sobre estas operaciones, consulte Conceptos de detección de caras y Conceptos de reconocimiento facial.

Opciones de soporte técnico

Además de usar las principales opciones de soporte técnico de Foundry Tools, también puede publicar sus preguntas en la sección de problemas del repositorio del SDK.

Para aprender cómo integrar la solución de liveness en tu aplicación actual, consulte la referencia del SDK de Azure Vision.

Para más información sobre las características disponibles para orquestación de la solución de vivacidad, consulte la referencia de la API de REST de sesión.

Operaciones de sesiones de vivacidad

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-11-23

Compartir a través de

Tutorial: Detección de vivacidad en caras

Requisitos previos

Preparación de la aplicación de front-end

Realización de la detección de vivacidad

Realización de la detección de vivacidad con verificación facial

Paso 1: Seleccionar una imagen de referencia

Paso 2: configuración de la orquestación de la verificación de vivacidad

Realizar otras operaciones faciales después de la detección de vivacidad

Opciones de soporte técnico

Contenido relacionado

Comentarios

Recursos adicionales