Tutorial: detectar atividade em rostos

Saiba como integrar a detecção de vivacidade facial ao seu fluxo de trabalho usando a lógica do lado do servidor e aplicativos complementares de front-end do cliente.

Dica

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

Neste tutorial, você aprenderá como executar um aplicativo de front-end com um servidor de aplicação para realizar a detecção de vivacidade. Você também pode adicionar a verificação facial em várias plataformas e idiomas.

Importante

Os SDKs do cliente de Detecção Facial para atividade são um recurso fechado. Solicite acesso ao recurso de atividade preenchendo o formulário de admissão de Reconhecimento Facial. Quando sua assinatura do Azure receber acesso, você poderá baixar o SDK da atividade de Detecção Facial.

Pré-requisitos

Assinatura do Azure – Criar uma gratuitamente
Sua conta do Azure deve ter uma função de Colaborador dos Serviços Cognitivos atribuída para que você possa concordar com os termos de IA responsáveis e criar um recurso. Para que essa função seja atribuída à sua conta, siga as etapas descritas na documentação Atribuir funções ou entre em contato com o administrador.
Depois de obter sua assinatura do Azure, crie um recurso da Detecção Facial no portal do Azure para obter a chave e o ponto de extremidade. Após a implantação, selecione Ir para recurso.
- Você precisa da chave e do ponto de extremidade do recurso criado para conectar seu aplicativo ao serviço de Detecção Facial.
Acesso aos artefatos restritos necessários para a Visão do Azure no SDK de Cliente de Detecção Facial das Foundry Tools para Dispositivos Móveis (iOS e Android) e Web.
- Para começar, você precisa se inscrever para os Recursos de Acesso Limitado ao Reconhecimento Facial para obter acesso aos artefatos restritos. Para mais informações, veja a página Acesso Limitado à Detecção Facial.
Familiaridade com o recurso de atividade de Detecção Facial. Consulte o guia conceitual.

Dica

Depois de concluir os pré-requisitos, experimente a experiência de atividade nas seguintes plataformas:

iOS: App Store do iOS – toque na tela do aplicativo 10 vezes após a instalação para habilitar o modo de desenvolvedor.
Android: Google Play Store — toque na tela do aplicativo 10 vezes após a instalação para habilitar o modo de desenvolvedor.
Web: experimente diretamente no Vision Studio.

Você também pode criar e executar um exemplo de front-end completo (iOS, Android ou Web) na seção Exemplos .

Preparar o aplicativo de front-end

Fornecemos SDKs em vários idiomas para simplificar a integração com seu aplicativo de front-end. Consulte o README do SDK escolhido nas seções a seguir para integrar a interface do usuário e o código necessário.

Importante

Cada SDK de front-end requer acesso a um ativo fechado para compilar com êxito. Confira as instruções a seguir para configurar esse acesso.

Para o Swift iOS:

Artefatos: SDK da Interface do Usuário de Detecção Facial da IA do Azure para iOS
Referência da API: Referência de AzureAIVisionFaceUI
Exemplo: exemplo do iOS

Para Kotlin/Java Android:

Artefatos: Maven Central: com.azure:azure-ai-vision-face-ui
Referência de API: azure-ai-vision-face-ui Reference
Exemplo: exemplo do Android

Para JavaScript Web:

Artefatos: @azure/ai-vision-face-ui - npm
Referência da API: Referência de AzureAIVisionFaceUI
Exemplo: exemplo da Web
Suporte à estrutura: funciona com estruturas populares, como React (incluindo Next.js), Vue.jse Angular.

Depois de integrado ao aplicativo front-end, o SDK inicia a câmera, orienta o usuário a ajustar sua posição, compõe o payload de vivacidade e o envia para o serviço de Detecção Facial de IA do Azure para processamento.

Monitore a seção Versões do repositório para novas atualizações de versão do SDK e habilite alertas automatizados de atualização de dependência, como o GitHub Dependabot (para repositórios do GitHub) ou Renovar (GitHub, GitLab, Bitbucket, Azure Repos).

Executar a detecção de atividade

As etapas a seguir descrevem o processo de orquestração de vivacidade:

O aplicativo front-end inicia a verificação de atividade e notifica o servidor de aplicativos.

O servidor de aplicativos cria uma nova sessão de atividade com o Serviço de Detecção Facial da IA do Azure. O serviço cria uma sessão de vivacidade e responde com um token de autorização de sessão. Para obter mais informações sobre cada parâmetro de solicitação envolvido na criação de uma sessão de liveness, consulte Liveness Create Session Operation.

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 do corpo da resposta:

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

O servidor de aplicativos fornece o token de autorização de sessão de volta para o aplicativo de front-end.

O aplicativo front-end usa o token de autorização de sessão para iniciar o detector de vivacidade facial, 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âmera, orienta o usuário a se posicionar corretamente e, em seguida, prepara o payload para chamar o ponto de extremidade do serviço de detecção de vivacidade.
O SDK chama o serviço Azure Vision Face para executar a detecção de vivacidade. Depois que o serviço responder, o SDK notificará o aplicativo front-end que a verificação de vivacidade foi concluída. Observação: a resposta do serviço não contém a decisão de vivacidade. Você precisa consultar essas informações do servidor de aplicativos.
O aplicativo front-end retransmite a conclusão da verificação de atividade para o servidor de aplicativos.

O servidor do aplicativo consulta o resultado da detecção de vivacidade do serviço de Detecção Facial da Visão do Azure.

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 do corpo da 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 aplicativos exclui 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 detecção de atividade com verificação facial

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

A integração da detecção de vivacidade com a verificação envolve duas partes:

Etapa 1 – Selecionar uma imagem de referência

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

Etapa 2 - Configurar a orquestração de vivacidade com verificação

As etapas a seguir mostram como orquestrar a vivacidade com verificação:

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

O servidor de aplicativos fornece a imagem de referência ao criar a sessão de atividade. Para obter mais informações sobre cada parâmetro de solicitação envolvido na criação de uma sessão de liveness com verificação, consulte 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"'

Um exemplo do corpo da 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 front-end fornece a imagem de referência ao inicializar os SDKs móveis. Não há suporte para esse cenário 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 de aplicativos agora pode consultar o resultado da verificação, além do resultado da atividade.

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 do corpo da 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 poderá 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}"

Executar outras operações faciais após a detecção de atividade

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

Defina o parâmetro enableSessionImage para true durante a etapa Session-Creation.
Extraia o sessionImageId da etapa Session-Get-Result.
Baixe a imagem da sessão (referenciada na API de Operação de Imagem de Sessão de Vivacidade) ou forneça o sessionImageId na operação Detectar da API de ID de Imagem de Sessão para continuar com outras operações de análise facial ou identidade facial. Para obter mais informações sobre essas operações, consulte conceitos de detecção facial e conceitos de Reconhecimento Facial.

Opções de suporte

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

Para saber como integrar a solução de liveness ao aplicativo existente, consulte a referência do Azure Vision SDK.

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

Operações da Sessão Dinâmica

Comentários

Esta página foi útil?

Last updated on 2025-11-23

Compartilhar via

Tutorial: detectar atividade em rostos

Pré-requisitos

Preparar o aplicativo de front-end

Executar a detecção de atividade

Realizar detecção de atividade com verificação facial

Etapa 1 – Selecionar uma imagem de referência

Etapa 2 - Configurar a orquestração de vivacidade com verificação

Executar outras operações faciais após a detecção de atividade

Opções de suporte

Conteúdo relacionado

Comentários

Recursos adicionais