Liveness Session Operations - Create Liveness With Verify Session

Serviço:: Azure AI Services

Versão da API:: v1.2

Crie uma nova sessão de dinâmica com verificação. Forneça a imagem de verificação durante a criação da sessão.
Uma sessão é melhor para cenários de dispositivo cliente em que os desenvolvedores desejam autorizar um dispositivo cliente a executar apenas uma detecção de atividade sem conceder acesso total ao recurso. As sessões criadas têm um tempo de vida limitado e só autorizam os clientes a executar a ação desejada antes que o acesso expire.

As permissões incluem...

- Um tempo de vida do token de 10 minutos.

Note

- O acesso ao cliente pode ser revogado excluindo a sessão usando a operação Excluir Liveness With Verify Session.
- Para recuperar um resultado, use a sessão Get Liveness With Verify.
- Para auditar as solicitações individuais feitas por um cliente ao seu recurso, use o Modo de Vida da Lista com As Entradas de Auditoria de Sessão de Verificação.

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

Parâmetros de URI

Nome	Em	Obrigatório	Tipo	Description
livenessOperationMode	formData	True	LivenessOperationMode	Tipo de modo de vida que o cliente deve seguir.
verifyImage	formData	True	file	O fluxo de imagem para verificar. O campo de cabeçalho Content-Disposition para essa parte deve ter nome de arquivo.
authTokenTimeToLiveInSeconds	formData		integer (int32) minimum: 60 maximum: 86400	Segundos para os quais a sessão deve durar. O intervalo é de 60 a 86400 segundos. O valor padrão é 600.
deviceCorrelationId	formData		string	Guid exclusivo por cada dispositivo de usuário final. Isso é para fornecer limitação de taxa e anti-martelada. Se 'deviceCorrelationIdSetInClient' for verdadeiro nesta solicitação, essa 'deviceCorrelationId' deverá ser nula.
deviceCorrelationIdSetInClient	formData		boolean	Se o cliente deve ou não permitir que o cliente defina sua própria 'deviceCorrelationId' por meio do SDK de Visão. O padrão é false e 'deviceCorrelationId' deve ser definido nesse corpo da solicitação.
enableSessionImage	formData		boolean	Armazenar ou não a imagem da sessão.
livenessModelVersion	formData		LivenessModel	A versão do modelo usada para a classificação de dinâmica. Esse é um parâmetro opcional e, se isso não for especificado, a versão mais recente do modelo com suporte será escolhida
returnVerifyImageHash	formData		boolean	Se retorna ou não o hash da imagem de verificação.
verifyConfidenceThreshold	formData		number (float) minimum: 0 maximum: 1	Limite de confiança da verificação facial. Consulte a documentação para obter mais detalhes. https://learn.microsoft.com/legal/cognitive-services/face/characteristics-and-limitations?context=%2Fazure%2Fai-services%2Fcomputer-vision%2Fcontext%2Fcontext#recognition-confidence-score
apiVersion	path	True	string	Versão da API
endpoint	path	True	string (uri)	Pontos de extremidade dos Serviços Cognitivos com suporte (protocolo e nome do host, por exemplo: https://{resource-name}.cognitiveservices.azure.com).

Respostas

Nome	Tipo	Description
200 OK	LivenessWithVerifySession	Uma chamada bem-sucedida cria uma sessão para um dispositivo cliente e fornece um token de autorização para uso pelo aplicativo cliente para uma finalidade e tempo limitados.
Other Status Codes	FaceErrorResponse	Uma resposta de erro inesperada. Cabeçalhos x-ms-error-code: string

Nome

Tipo

Description

200 OK

LivenessWithVerifySession

Uma chamada bem-sucedida cria uma sessão para um dispositivo cliente e fornece um token de autorização para uso pelo aplicativo cliente para uma finalidade e tempo limitados.

Other Status Codes

FaceErrorResponse

Uma resposta de erro inesperada.

Cabeçalhos

x-ms-error-code: string

Segurança

Ocp-Apim-Subscription-Key

A chave secreta para sua assinatura do Azure AI Face.

Tipo: apiKey
Em: header

AADToken

O fluxo OAuth2 do Azure Active Directory

Tipo: oauth2
Flow: accessCode
URL de Autorização: https://api.example.com/oauth2/authorize
URL do Token: https://api.example.com/oauth2/token

Escopos

Nome	Description
https://cognitiveservices.azure.com/.default

Exemplos

Create LivenessWithVerify Session

Solicitação de exemplo

HTTP

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

Resposta de exemplo

Código de status:: 200

{
  "sessionId": "b12e033e-bda7-4b83-a211-e721c661f30e",
  "authToken": "eyJhbGciOiJFUzI1NiIsIm",
  "status": "NotStarted",
  "modelVersion": "2024-11-15",
  "results": {
    "attempts": [],
    "verifyReferences": [
      {
        "referenceType": "image",
        "faceRectangle": {
          "top": 316,
          "left": 131,
          "width": 498,
          "height": 677
        },
        "qualityForRecognition": "high"
      }
    ]
  }
}

Definições

Nome	Description
FaceError	O objeto de erro. Para obter detalhes abrangentes sobre códigos de erro e mensagens retornadas pelo Serviço de Detecção Facial, consulte o seguinte link: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Uma resposta que contém detalhes do erro.
FaceRectangle	Um retângulo no qual um rosto pode ser encontrado.
ImageType	O tipo de imagem.
LivenessColorDecisionTarget	O destino da imagem de cor usada para a classificação de vida útil.
LivenessDecision	O resultado da classificação de vida útil.
LivenessDecisionTargets	Os destinos usados para a classificação de dinâmica.
LivenessError	O erro da classificação de dinâmica.
LivenessModel	A versão do modelo usada para a classificação de dinâmica.
LivenessOperationMode	O modo de operação de atividade para conduzir a experiência do usuário final do cliente.
LivenessWithVerifyOutputs	A saída de verificação facial.
LivenessWithVerifyReference	O detalhe da face para verificação.
LivenessWithVerifyResult	Os resultados da dinâmica com a chamada de verificação.
LivenessWithVerifySession	Resultado da sessão de detectar a dinâmica com a verificação.
LivenessWithVerifySessionAttempt	A dinâmica com a tentativa de verificação da sessão.
LivenessWithVerifySessionResults	Os resultados da dinâmica com a sessão de verificação.
OperationState	O status atual da sessão.
QualityForRecognition	Indica a qualidade da imagem para reconhecimento.

FaceError

Objeto

O objeto de erro. Para obter detalhes abrangentes sobre códigos de erro e mensagens retornadas pelo Serviço de Detecção Facial, consulte o seguinte link: https://aka.ms/face-error-codes-and-messages.

Nome	Tipo	Description
code	string	Um de um conjunto definido pelo servidor de códigos de erro.
message	string	Uma representação legível pelo ser humano do erro.

FaceErrorResponse

Objeto

Uma resposta que contém detalhes do erro.

Nome	Tipo	Description
error	FaceError	O objeto de erro.

FaceRectangle

Objeto

Um retângulo no qual um rosto pode ser encontrado.

Nome	Tipo	Description
height	integer (int32)	A altura do retângulo, em pixels.
left	integer (int32)	A distância da borda esquerda se a imagem até a borda esquerda do retângulo, em pixels.
top	integer (int32)	A distância da borda superior se a imagem até a borda superior do retângulo, em pixels.
width	integer (int32)	A largura do retângulo, em pixels.

ImageType

Enumeração

O tipo de imagem.

Valor	Description
Color	Imagem colorida.
Infrared	Imagem infravermelha.
Depth	Imagem de profundidade.

LivenessColorDecisionTarget

Objeto

O destino da imagem de cor usada para a classificação de vida útil.

Nome	Tipo	Description
faceRectangle	FaceRectangle	A região da face em que a classificação de dinâmica foi feita.

LivenessDecision

Enumeração

O resultado da classificação de vida útil.

Valor	Description
uncertain	O algoritmo não pôde classificar o rosto de destino como real ou falsificado.
realface	O algoritmo classificou a face de destino como real.
spoofface	O algoritmo classificou o rosto de destino como uma falsificação.

LivenessDecisionTargets

Objeto

Os destinos usados para a classificação de dinâmica.

Nome	Tipo	Description
color	LivenessColorDecisionTarget	O destino da imagem de cor usada para a classificação de vida útil.

LivenessError

Objeto

O erro da classificação de dinâmica.

Nome	Tipo	Description
code	string	O código de erro.
message	string	A mensagem de erro.
targets	LivenessDecisionTargets	Destinos usados para classificação de vida útil.

LivenessModel

Enumeração

A versão do modelo usada para a classificação de dinâmica.

Valor	Description
2024-11-15

LivenessOperationMode

Enumeração

O modo de operação de atividade para conduzir a experiência do usuário final do cliente.

Valor	Description
Passive	Utiliza uma técnica de vida passiva que não requer ações adicionais do usuário. Requer iluminação interna normal e brilho de tela alta para um desempenho ideal. Portanto, esse modo tem um envelope operacional estreito e não será adequado para cenários que exigem que os usuários finais estejam em condições de iluminação brilhantes. Observação: este é o único modo com suporte para a solução Móvel (iOS e Android).
PassiveActive	Esse modo utiliza uma técnica de vida ativa ou passiva híbrida que exige a cooperação do usuário. Ele é otimizado para exigir movimento ativo apenas em condições de iluminação abaixo do ideal. Ao contrário do modo passivo, esse modo não tem restrições de iluminação e, portanto, oferece um envelope operacional mais amplo. Esse modo é preferível em soluções baseadas na Web devido à falta de controle automático de brilho de tela disponível em navegadores, o que dificulta o envelope operacional do modo passivo em soluções baseadas na Web.

Valor

Description

Passive

Utiliza uma técnica de vida passiva que não requer ações adicionais do usuário. Requer iluminação interna normal e brilho de tela alta para um desempenho ideal. Portanto, esse modo tem um envelope operacional estreito e não será adequado para cenários que exigem que os usuários finais estejam em condições de iluminação brilhantes. Observação: este é o único modo com suporte para a solução Móvel (iOS e Android).

PassiveActive

Esse modo utiliza uma técnica de vida ativa ou passiva híbrida que exige a cooperação do usuário. Ele é otimizado para exigir movimento ativo apenas em condições de iluminação abaixo do ideal. Ao contrário do modo passivo, esse modo não tem restrições de iluminação e, portanto, oferece um envelope operacional mais amplo. Esse modo é preferível em soluções baseadas na Web devido à falta de controle automático de brilho de tela disponível em navegadores, o que dificulta o envelope operacional do modo passivo em soluções baseadas na Web.

LivenessWithVerifyOutputs

Objeto

A saída de verificação facial.

Nome	Tipo	Description
isIdentical	boolean	Se a face da dinâmica de destino e a face da imagem de comparação correspondem.
matchConfidence	number (float) minimum: 0 maximum: 1	A face de vida facial de destino e a confiança de verificação facial da imagem de comparação.

LivenessWithVerifyReference

Objeto

O detalhe da face para verificação.

Nome	Tipo	Description
faceRectangle	FaceRectangle	A região do rosto em que a classificação da imagem de comparação foi feita.
qualityForRecognition	QualityForRecognition	Qualidade da imagem facial para reconhecimento.
referenceType	ImageType	O tipo de imagem que contém o retângulo facial no qual a classificação de dinâmica foi feita.

LivenessWithVerifyResult

Objeto

Os resultados da dinâmica com a chamada de verificação.

Nome	Tipo	Description
digest	string	O resumo calculado do servidor para essa solicitação. Se o resumo relatado pelo cliente for diferente do resumo calculado do servidor, a integridade da mensagem entre o cliente e o serviço será comprometida e o resultado não deverá ser confiável. Para obter mais informações, confira como orientar sobre como aproveitar esse valor para proteger sua solução de ponta a ponta.
livenessDecision	LivenessDecision	A classificação de dinâmica para a face de destino.
sessionImageId	string	A ID da imagem da solicitação de sessão.
targets	LivenessDecisionTargets	Destinos usados para classificação de vida útil.
verifyImageHash	string	O hash sha256 da imagem de verificação na solicitação.
verifyResult	LivenessWithVerifyOutputs	A saída de verificação facial. Disponível somente quando a solicitação é dinâmica com verificação.

LivenessWithVerifySession

Objeto

Resultado da sessão de detectar a dinâmica com a verificação.

Nome	Tipo	Description
authToken	string	Token de portador para fornecer autenticação para o SDK da Visão em execução em um aplicativo cliente. Esse token de portador tem permissões limitadas para executar apenas a ação necessária e expira após a hora TTL. Também é auditável.
modelVersion	LivenessModel	A versão do modelo usada para a classificação de dinâmica. Esse é um parâmetro opcional e, se isso não for especificado, a versão mais recente do modelo com suporte será escolhida
results	LivenessWithVerifySessionResults	Os resultados da dinâmica com a sessão de verificação.
sessionId	string	A ID exclusiva para fazer referência a esta sessão.
status	OperationState	O status atual da sessão.

LivenessWithVerifySessionAttempt

Objeto

A dinâmica com a tentativa de verificação da sessão.

Nome	Tipo	Description
attemptId	integer (int32)	A ID da tentativa, comece a partir de 1.
attemptStatus	OperationState	O status da tentativa.
error	LivenessError	O erro da dinâmica com a chamada de verificação será nulo se houver resultado.
result	LivenessWithVerifyResult	O resultado da dinâmica com a chamada de verificação será nulo se houver erro.

LivenessWithVerifySessionResults

Objeto

Os resultados da dinâmica com a sessão de verificação.

Nome	Tipo	Description
attempts	LivenessWithVerifySessionAttempt[]	As tentativas de dados de vida subjacente com a chamada de verificação com a sessão.
verifyReferences	LivenessWithVerifyReference[]	As referências usadas para verificação facial.

OperationState

Enumeração

O status atual da sessão.

Valor	Description
NotStarted	A operação não foi iniciada.
Running	A operação está em andamento.
Succeeded	A operação foi concluída com êxito.
Failed	A operação falhou.
Canceled	A operação foi cancelada pelo usuário.

QualityForRecognition

Enumeração

Indica a qualidade da imagem para reconhecimento.

Valor	Description
low	Baixa qualidade.
medium	Qualidade média.
high	Alta qualidade.

Compartilhar via

Liveness Session Operations - Create Liveness With Verify Session

Parâmetros de URI

Respostas

Segurança

Ocp-Apim-Subscription-Key

AADToken

Escopos

Exemplos

Create LivenessWithVerify Session

Solicitação de exemplo

Resposta de exemplo

Definições

FaceError

FaceErrorResponse

FaceRectangle

ImageType

LivenessColorDecisionTarget

LivenessDecision

LivenessDecisionTargets

LivenessError

LivenessModel

LivenessOperationMode

LivenessWithVerifyOutputs

LivenessWithVerifyReference

LivenessWithVerifyResult

LivenessWithVerifySession

LivenessWithVerifySessionAttempt

LivenessWithVerifySessionResults

OperationState

QualityForRecognition