Tutorial: Detetar vivacidade em rostos

Aprenda a integrar a deteção de liveness facial no seu fluxo de trabalho usando lógica do lado do servidor e aplicações frontend associadas.

Sugestão

Para obter informações gerais sobre a deteção de vivacidade facial, consulte o guia conceitual.

Neste tutorial, aprendes a executar uma aplicação frontend com um servidor de aplicações para realizar a deteção de atividade. Também pode adicionar verificação facial em várias plataformas e idiomas.

Importante

Os SDKs do cliente Face para deteção de vivacidade são um recurso restrito. Você deve solicitar acesso ao recurso de vivacidade preenchendo o formulário de admissão de Reconhecimento Facial. Quando a sua subscrição do Azure tiver acesso concedido, poderá descarregar o SDK de verificação de vivacidade facial.

Pré-requisitos

Subscrição do Azure - Criar uma gratuitamente
A sua conta Azure deve ter atribuída a função Contribuidor de Serviços Cognitivos para que possa aceitar os termos de IA responsável e criar um recurso. Para que este papel seja atribuído à sua conta, siga as etapas na documentação Atribuir papéis ou entre em contato com um administrador.
Depois de ter a sua assinatura do Azure, crie um recurso Face no portal do Azure para obter a sua chave e o ponto de extremidade. Depois que for implantado, selecione Ir para recurso.
- Você precisa da chave e do ponto de extremidade do recurso criado para conectar seu aplicativo ao serviço Face.
Acesso aos artefactos bloqueados necessários para Azure Vision no Foundry Tools Face Client SDK para Mobile (iOS e Android) e Web.
- Para começar, é necessário solicitar as funcionalidades de acesso restrito de reconhecimento facial para ter acesso aos artefatos controlados. Para obter mais informações, consulte a página Acesso Limitado ao Face.
Familiaridade com o recurso de deteção de vivacidade facial. Consulte o guia conceptual.

Sugestão

Depois de completar os pré-requisitos, pode experimentar a experiência liveness nas seguintes plataformas:

iOS: App Store iOS — toque no ecrã da aplicação 10 vezes após a instalação para ativar o modo de programador.
Android: Google Play Store — toque no ecrã da aplicação 10 vezes após a instalação para ativar o modo de programador.
Web: Experimente diretamente no Vision Studio.

Também pode construir e executar um exemplo completo de frontend (iOS, Android ou Web) a partir da secção de Exemplos .

Preparar o aplicativo frontend

Fornecemos SDKs em vários idiomas para simplificar a integração com seu aplicativo frontend. Consulte o README para o SDK escolhido nas secções seguintes para integrar tanto a interface como o código necessário.

Importante

Cada SDK de frontend requer acesso a um ativo fechado para ser compilado com êxito. Consulte as seguintes instruções para configurar este acesso.

Para Swift iOS:

Componentes: SDK de UI do Azure AI Face para iOS
Referência da API: AzureAIVisionFaceUI Reference
Exemplo: Exemplo de iOS

Para Kotlin/Java Android:

Artefactos: Maven Central: com.azure:azure-ai-vision-face-ui
Referência da API: azure-ai-vision-face-ui Reference
Exemplo: Exemplo de Android

Para JavaScript Web:

Artefactos: @azure/ai-vision-face-ui - npm
Referência da API: AzureAIVisionFaceUI Reference
Exemplo: Exemplo da Web
Suporte a estruturas: Funciona com estruturas populares como React (incluindo Next.js), Vue.jse Angular.

Uma vez integrado na sua aplicação frontend, o SDK inicia a câmara, orienta o utilizador para ajustar a sua posição, compõe a carga útil de liveness e envia-a para o serviço Azure AI Face para processamento.

Monitorize a secção de Releases do repositório para atualizações de novas versões do SDK e ative alertas automáticos de atualização de dependências — como GitHub Dependabot (para repositórios GitHub) ou Renovate (GitHub, GitLab, Bitbucket, Azure Repos).

Realizar a deteção de vida

Os passos seguintes descrevem o processo de orquestração da vivacidade:

O aplicativo frontend inicia a verificação de vivacidade e notifica o servidor do aplicativo.

O servidor de aplicações cria uma nova sessão de vivacidade com o Azure AI Face Service. O serviço cria uma sessão de liveness e responde com um token de autorização de sessão. Para mais informações sobre cada parâmetro de pedido envolvido na criação de uma sessão de liveness, consulte Operação de Criação de Sessão de Liveness.

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"
}'

Um exemplo da estrutura de resposta:

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

O servidor de aplicação fornece o token de autorização de sessão de volta à aplicação frontend.

A aplicação frontend utiliza o token de autorização de sessão para iniciar o detetor de vivacidade da face, que inicia o fluxo de vivacidade.

    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)

O SDK inicia a câmara, guia o utilizador para se posicionar corretamente e, em seguida, prepara o payload para chamar o endpoint do serviço de deteção de presença.
O SDK chama o serviço Azure Vision Face para realizar a deteção de vivacidade. Assim que o serviço responde, o SDK notifica a aplicação frontend de que a verificação de vivacidade está concluída. Nota: A resposta do serviço não contém a decisão de vivacidade. Tens de consultar esta informação a partir do servidor da aplicação.
A aplicação frontal comunica a conclusão da verificação de vivacidade ao servidor da aplicação.

O servidor de aplicações consulta o resultado da deteção de vivacidade do serviço 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}"

Um exemplo da estrutura de resposta:

{
    "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
                        }
                        }
                    }
                }
            }
        ]
    }
}

O servidor de aplicações apaga a sessão depois de consultar todos os resultados da sessão.

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}"

Realizar a deteção de vivacidade com verificação facial

A combinação da verificação facial com a deteção de vivacidade permite a verificação biométrica de uma determinada pessoa de interesse com uma garantia adicional de que a pessoa está fisicamente presente no sistema.

Integrar a deteção de vivacidade com a verificação envolve duas partes:

Etapa 1 - Selecione uma imagem de referência

Para obter resultados de reconhecimento mais precisos, siga as dicas listadas nos requisitos de composição para cenários de verificação de identidade.

Passo 2 - Configurar a orquestração da vivacidade com verificação

Os seguintes passos gerais mostram como orquestrar a vivacidade com verificação:

Forneça a imagem de referência de verificação utilizando um dos seguintes dois métodos:

O servidor do aplicativo fornece a imagem de referência ao criar a sessão de liveness. Para mais informações sobre cada parâmetro de pedido envolvido na criação de uma sessão de liveness com verificação, consulte Operação de Criação de Sessão com Verificação de Liveness.

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"'

Um exemplo da estrutura de resposta:

{
    "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"
        }
        ]
    }
}

O aplicativo frontend fornece a imagem de referência ao inicializar os SDKs móveis. Este cenário não é suportado na solução 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.

O servidor da aplicação agora pode consultar o resultado da verificação, além do resultado de vivacidade.

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}"

Um exemplo da estrutura de resposta:

{
    "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"
            }
        ]
        }
    }

O servidor de aplicativos pode excluir a sessão se você não precisar mais do 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}"

Execute outras operações faciais após a deteção de vivacidade

Opcionalmente, pode realizar operações adicionais de rosto após a verificação de vivacidade, como análise facial (para obter atributos faciais) e operações de identidade facial.

Defina o parâmetro enableSessionImage para true durante a etapa de criação de sessão .
Extraia o sessionImageId do passo Session-Get-Result.
Descarregue a imagem de sessão (referenciada na API de Operação de Imagem de Sessão do Liveness), ou forneça a sessionImageId operação na API Detectar do ID de Imagem de Sessão para continuar com outras análises faciais ou operações de identidade facial. Para obter mais informações sobre essas operações, consulte Conceitos de deteção facial e Conceitos de reconhecimento facial.

Opções de suporte

Além de usar as principais opções de suporte das Foundry Tools, pode também colocar as suas perguntas na secção de problemas do repositório SDK.

Para saber como integrar a solução liveness na sua aplicação existente, consulte a referência Azure Vision SDK.

Para saber mais sobre os recursos disponíveis para orquestrar a solução de liveness, consulte a referência da API REST de sessão.

Operações de Liveness Session

Feedback

Esta página foi útil?

Last updated on 2025-11-23

Partilhar via

Tutorial: Detetar vivacidade em rostos

Pré-requisitos

Preparar o aplicativo frontend

Realizar a deteção de vida

Realizar a deteção de vivacidade com verificação facial

Etapa 1 - Selecione uma imagem de referência

Passo 2 - Configurar a orquestração da vivacidade com verificação

Execute outras operações faciais após a deteção de vivacidade

Opções de suporte

Conteúdos relacionados

Feedback

Recursos adicionais