📖 Documentação Técnica & Roadmap da BioFace API
Guia definitivo para integradores de controle de acesso, portaria remota, totens, catracas de academias e verificação de identidade KYC.
🎯 Objetivo do Roadmap:
Siga esta sequência lógica de 5 passos para construir sua integração do zero à produção sem falhas de autenticação ou estouro de cota.
1
Obtenha sua Chave e Configure a Whitelist de Proteção
Toda requisição deve conter o cabeçalho HTTP X-API-Key: {sua_chave}. Para garantir segurança contra vazamento ou furto da sua chave em código frontend, cada chave deve ser configurada com seu ambiente:
- Ambiente Local (Desenvolvimento): Aceita requisições vindas de
localhost e 127.0.0.1.
- Ambiente de Produção (VPS / Servidor / Catraca): Informe o IP fixo da sua VPS (ex:
185.190.22.45) ou o Domínio do seu SaaS (ex: https://meucondominio.com.br). Qualquer requisição fora dessa lista receberá 403 Forbidden.
X-API-Key: bio_live_a1b2c3d4e5f67890
Content-Type: multipart/form-data
2
Cadastre os Sujeitos / Moradores (POST /api/v1/subjects)
Antes de realizar o reconhecimento, você precisa cadastrar os rostos da sua base (moradores do condomínio, alunos da academia ou colaboradores).
Envie o nome do sujeito e uma imagem frontal nítida.
🛡️ 100% LGPD Privacy-by-Design: A BioFace API extrai imediatamente o vetor matemático (embedding de 512 números float32) e descarta o arquivo de imagem. Nenhuma foto de morador é salva em disco, impossibilitando reconstrução visual reversa.
O endpoint retorna um id único (ex: subj_f92a10). Salve esse ID no banco de dados do seu sistema vinculado ao cadastro do usuário.
3
Reconhecimento 1:N em Tempo Real (POST /api/v1/recognize)
Este é o coração da integração para catracas e controle de portaria: envie uma foto capturada pela câmera ou webcam. O motor da BioFace API detecta a face presente no frame e calcula a similaridade cosseno contra todos os vetores da sua organização em menos de 15ms.
- threshold (limiar): Valor de 0.0 a 1.0 (Padrão:
0.45). Se a similaridade for superior ou igual ao limiar, o sujeito é identificado em best_match.
- Recomendação de Calibração: Utilize
0.45 para condomínios e academias; use 0.55 a 0.60 para salas de segurança máxima (CPD/Cofre).
4
Verificação 1:1 KYC / Documentos (POST /api/v1/verify)
Ideal para onboarding digital em aplicativos mobile, autorização de transações financeiras ou validação de CNH/RG contra selfie.
Não necessita de cadastro prévio na base: envie source_image e target_image. O motor compara as duas faces instantaneamente e retorna se is_match: true/false com o percentual exato de similaridade.
5
Detecção e Validação Prévia de Rosto (POST /api/v1/detect)
Antes de enviar uma foto para cadastro ou para verificar se há múltiplas pessoas tentando passar na catraca ao mesmo tempo, utilize a detecção facial pura.
Retorna a contagem de rostos, bounding box [x1, y1, x2, y2] de cada um, score de confiança e 5 pontos de landmarks faciais (olhos, nariz e cantos da boca).
Identifica quem é a pessoa presente na imagem comparando contra todo o banco de sujeitos cadastrados da organização.
Parâmetros (multipart/form-data):
| Campo | Tipo | Obrigatório? | Padrão | Descrição |
|---|
file | Arquivo (JPG/PNG) | Sim | - | Foto capturada pela câmera ou frame de vídeo |
threshold | Float (0.0 a 1.0) | Não | 0.45 | Limiar mínimo de similaridade para considerar match |
limit | Inteiro | Não | 5 | Número máximo de candidatos correspondentes retornados |
{
"count": 1,
"faces": [
{
"detection": {
"bbox": [142.5, 95.0, 310.2, 320.8],
"score": 0.998,
"landmarks": [[185.0, 150.0], [260.0, 148.0], [220.0, 195.0], [190.0, 245.0], [250.0, 243.0]]
},
"best_match": {
"subject_id": "subj_9a12bc",
"subject_name": "Marcelo Oliveira",
"similarity": 0.865
},
"matches": [
{ "subject_id": "subj_9a12bc", "subject_name": "Marcelo Oliveira", "similarity": 0.865 }
]
}
]
}
Compara duas fotos diretamente e informa se pertencem ao mesmo indivíduo.
Parâmetros (multipart/form-data):
| Campo | Tipo | Obrigatório? | Padrão | Descrição |
|---|
source_image | Arquivo | Sim | - | Primeira foto (ex: Selfie ao vivo ou foto cadastrada) |
target_image | Arquivo | Sim | - | Segunda foto (ex: Foto da CNH ou documento de identidade) |
threshold | Float | Não | 0.45 | Limiar de tolerância para aprovação do match |
{
"is_match": true,
"similarity": 0.892,
"threshold": 0.45,
"source_face_detected": true,
"target_face_detected": true
}
Detecta a presença de rostos na imagem, calcula caixas delimitadoras e identifica landmarks faciais.
Parâmetros (multipart/form-data):
| Campo | Tipo | Obrigatório? | Padrão | Descrição |
|---|
file | Arquivo | Sim | - | Imagem a ser analisada |
threshold | Float | Não | 0.50 | Score de confiança mínimo de detecção |
{
"count": 1,
"faces": [
{
"bbox": [110.0, 75.0, 290.0, 280.0],
"score": 0.999,
"landmarks": [[150.0, 120.0], [235.0, 118.0], [192.0, 165.0], [160.0, 210.0], [225.0, 208.0]]
}
]
}
Cadastra uma pessoa na base biométrica da organização. Requer cota disponível no plano.
Parâmetros (multipart/form-data):
| Campo | Tipo | Obrigatório? | Descrição |
|---|
name | String | Sim | Nome ou identificador da pessoa (Ex: "Morador Ap 402 - Carlos") |
file | Arquivo | Sim | Foto frontal nítida da pessoa |
{
"id": "subj_642af1",
"name": "Morador Ap 402 - Carlos",
"created_at": "2026-09-21T18:30:00Z"
}
Retorna a lista de todos os sujeitos cadastrados pela sua organização.
[
{ "id": "subj_642af1", "name": "Carlos Silva", "created_at": "2026-09-21T18:30:00Z" },
{ "id": "subj_881ba4", "name": "Mariana Souza", "created_at": "2026-09-21T18:35:00Z" }
]
Remove o vetor biométrico do sujeito da base e libera imediatamente 1 vaga na cota de rostos do seu plano. Retorna 204 No Content.
Endpoint público para checar a saúde e status operacional do motor de IA.
{
"status": "ok",
"version": "1.0.0",
"total_tenants": 12,
"subjects_count": 840
}
