Argus Face API

Início rápido

1. Crie sua conta em Criar conta grátis. O plano gratuito já libera a API para testes.
2. Gere uma chave de API no portal, em Chaves de API. Ela tem o formato agk_xxxx.yyyy e só aparece uma vez: guarde em local seguro.
3. Crie uma coleção, indexe um rosto e busque, como abaixo.

Autenticação

Toda requisição leva a sua chave no header X-Api-Key:

X-Api-Key: agk_7f3a9c21.Qm9kZS1zZWNyZXQtZXhhbXBsZQ

• Cada chave pertence à sua conta, e você só enxerga as suas coleções. Duas contas podem ter coleções com o mesmo nome sem conflito.
• O número de chaves ativas depende do plano. Revogue uma chave no portal a qualquer momento: ela para de funcionar na hora.
• Não coloque a chave em apps, sites ou código que roda no aparelho do usuário. Chame a API a partir do seu servidor.
• Chave inválida, revogada ou de assinatura inativa recebe 401 UnrecognizedClientException.

Formato das requisições

A API segue o protocolo JSON 1.1 da AWS. Todas as operações usam POST com corpo JSON e campos em PascalCase, iguais aos da documentação do Rekognition. Há duas formas equivalentes de chamar uma operação:

POST /
X-Amz-Target: RekognitionService.DetectFaces
Content-Type: application/x-amz-json-1.1
X-Api-Key: agk_...

POST /DetectFaces
Content-Type: application/json
X-Api-Key: agk_...

A resposta é sempre JSON (application/x-amz-json-1.1). Campos sem valor são omitidos, como na AWS. Operações que listam itens são paginadas com MaxResults e NextToken: repita a chamada com o NextToken recebido até ele não vir mais.

Usando os SDKs da AWS

Use o cliente oficial do Rekognition de qualquer linguagem. Basta apontar o endpoint para o Argus Face e adicionar o header X-Api-Key. O SDK exige credenciais AWS, mas elas não são usadas: informe qualquer valor. A região também é indiferente.

Depois de configurar o cliente, chame as operações exatamente como faria na AWS (index_faces, IndexFacesCommand, IndexFacesAsync...). Nos SDKs, Image.Bytes recebe os bytes do arquivo: o SDK converte para base64.

Imagens

• Envie a imagem em Image.Bytes, codificada em base64 no JSON. Formatos: JPEG, PNG e WebP. A orientação EXIF é aplicada automaticamente.
• Tamanho máximo da requisição: 40 MB.
• Image.S3Object não é suportado: a imagem precisa ir no corpo (InvalidS3ObjectException).
• São detectados até 100 rostos por imagem. Para identificar pessoas, use fotos em que o rosto tenha pelo menos uns 40 pixels de largura.
• O reconhecimento funciona com máscara, óculos, debaixo d'água, em movimento e com iluminação ruim. Fotos melhores ainda dão resultados melhores.

QualityFilter

Nas operações que recebem imagem, QualityFilter controla quais rostos são aceitos: NONE (todos), AUTO (padrão), LOW, MEDIUM ou HIGH (só rostos grandes e nítidos). Em IndexFaces, os rostos descartados aparecem em UnindexedFaces com o motivo.

Similaridade e limiares

Similarity vai de 0 a 100, na mesma escala do Rekognition. Quanto maior, mais parecidos os rostos. Os limiares (FaceMatchThreshold, SimilarityThreshold, UserMatchThreshold) usam a mesma escala.

Limiar mais baixo traz mais resultados e mais falsos positivos. Limiar mais alto traz menos resultados e mais certeza. Ajuste com as suas próprias fotos.

Fluxos comuns

Face Liveness

Confere se há uma pessoa real diante da câmera, e não uma foto, uma tela ou um vídeo gravado. O usuário vê o próprio rosto num oval, a tela pisca uma sequência de cores sorteada pelo servidor e ele olha para a esquerda, a direita, para cima e para baixo, em ordem sorteada. Setas e uma barra de progresso guiam cada movimento, e o próximo passo só começa quando o servidor confirma que a pessoa fez o anterior. A análise combina a detecção de fraude do motor Argus (foto impressa, tela) com o reflexo das cores no rosto, o movimento e a confirmação de que é a mesma pessoa do começo ao fim.

1. Seu servidor chama CreateFaceLivenessSession com a chave de API e entrega o SessionId à página.
2. A página carrega argus-liveness.js e chama ArgusLiveness.start({ sessionId }). O componente abre a câmera, conduz o desafio e envia a captura para StartFaceLivenessSession. Não use a chave de API no navegador: o SessionId é a credencial, vale uma vez e expira em 5 minutos.
3. Seu servidor chama GetFaceLivenessSessionResults e decide pelo Confidence. A nota nunca passa pelo navegador.

• Confidence vai de 0 a 100. Sugerimos aceitar a partir de 80. Abaixo disso, peça uma nova tentativa ou siga um fluxo de revisão.
• ReferenceImage é um quadro frontal da captura: use com CompareFaces ou SearchFacesByImage para saber quem é a pessoa (por exemplo, selfie × documento). Até 4 AuditImages ficam disponíveis para auditoria.
• Os resultados ficam guardados por 24 horas. As imagens voltam em Bytes (S3 não é suportado).
• Para testar sem escrever código, entre no portal e abra Testar Face Liveness.
• Diferenças da AWS: a captura usa o nosso componente (argus-liveness.js), não o FaceLivenessDetector do Amplify, e não há certificação iBeta. Para decisões de alto risco, combine o liveness com outras verificações.

Erros

Erros seguem o formato da AWS: status HTTP, o código no header x-amzn-ErrorType e um corpo JSON com __type e a mensagem. Os SDKs da AWS transformam esse corpo na exceção correspondente (por exemplo, ResourceNotFoundException). Trate os erros pelo código: o texto de Message é para pessoas e pode mudar.

HTTP/1.1 400 Bad Request
x-amzn-ErrorType: ResourceNotFoundException

{ "__type": "ResourceNotFoundException", "Code": "ResourceNotFoundException", "Message": "Coleção faces não encontrada." }

Limites e cotas

O consumo do mês aparece no portal, em Relatórios, com o total de imagens, rostos indexados e imagens sem rosto.

Cobrança

A cobrança é por imagem processada, como na AWS, em dólar (US$). Cada chamada abaixo conta 1 imagem na cota do plano ou na fatura do plano Livre:

IndexFaces SearchFacesByImage SearchFaces DetectFaces CompareFaces SearchUsers SearchUsersByImage

• Imagens sem rosto também são cobradas, porque a imagem foi processada. Isso vale mesmo quando a operação responde com erro por não encontrar rosto.
• Imagens corrompidas ou em formato inválido (InvalidImageFormatException) não são cobradas.
• Operações de gerenciamento são gratuitas: criar, listar, descrever e apagar coleções, faces e usuários, além de associar e desassociar faces.
• No plano Livre, as faces armazenadas também entram na fatura, por face por mês.
• Face Liveness é cobrado por verificação concluída (a captura enviada e analisada). Nos planos com cota, cada verificação consome 15 imagens, a mesma proporção de custo da AWS. No plano Livre, tem tabela própria, com o mesmo desconto sobre o preço da AWS.

Valores e planos em Preços.

Operações não suportadas

Estas operações existem no Rekognition, mas não fazem parte do Argus Face, que é especializado em rostos: DetectLabels, DetectText, DetectModerationLabels, DetectProtectiveEquipment, RecognizeCelebrities, DetectCustomLabels, operações de vídeo e de jobs em lote. Chamadas a elas recebem AccessDeniedException.