MUU Biometria -- API de Verificacao Biometrica Bovina

Status da API

Verifica se a API esta operacional e quais modelos de ML estao carregados. Use este endpoint para confirmar que o servico esta pronto antes de enviar requisicoes de verificacao. Este endpoint nao requer autenticacao.

Quando Usar

Cenario	Como interpretar	Acao recomendada
Startup da aplicacao	Confirma se os modelos 60, 62 e 64 carregaram corretamente.	So liberar trafego de verificacao quando `status="ok"`.
Monitoramento	Serve como endpoint leve para health checks e readiness probes.	Chamar periodicamente a partir do orquestrador ou monitor.
Falha operacional	Mostra se a API ainda responde mesmo quando os modelos nao estao prontos.	Se `status="degraded"`, investigar logs e reinicializacao dos modelos.

Exemplo de Requisicao

Exemplo simples de health check com curl:

curl -X GET http://127.0.0.1:8000/health

Campos da Resposta

Campo	Tipo	Range / Valores	Descricao
`status`	string	`"ok"` \| `"degraded"`	"ok" = servico operacional, todos os modelos carregados. "degraded" = servico respondendo mas modelos nao carregaram (requisicoes de verificacao retornarao 503).
`models_loaded`	int[]	`[60, 62, 64]`, `[]`, ou parcial	Lista de IDs dos modelos TensorFlow carregados. [60, 62, 64] = todos OK. [] = nenhum modelo carregou. [60, 62] = alguns falharam.

Exemplo de Resposta

{ "status": "ok", "models_loaded": [60, 62, 64] }

Exemplo: degraded

Caso em que a API responde, mas os modelos ainda nao foram carregados ou falharam na inicializacao:

{ "status": "degraded", "models_loaded": [] }

Guia Operacional

Resposta	Significado	Impacto
`{"status":"ok","models_loaded":[60,62,64]}`	Servico e modelos prontos.	`/predict` e `/domain-check` devem responder normalmente.
`{"status":"degraded","models_loaded":[]}`	API no ar, mas nenhum modelo pronto.	Endpoints de inferencia retornarao `503 Models not loaded`.
`{"status":"ok","models_loaded":[60,62]}`	Carregamento parcial detectado.	Investigar imediatamente; o comportamento esperado e ter os 3 modelos.

Verificacao de Identidade Bovina

Envie 3 fotos de referencia de um animal conhecido e 1 foto de prova para verificar se pertencem ao mesmo individuo. O sistema utiliza um ensemble de 3 modelos siameses com perda triplet para comparar embeddings do focinho bovino -- a "digital" unica de cada animal.

Como Funciona

Cadastrar

3 fotos do focinho de referencia

→

Verificar

1 foto de prova

→

Resultado

Mesmo animal? + confianca

Criterios de Decisao

Todos os criterios devem ser atendidos para decision.verdict retornar MATCH:

Metrica	Limiar	Unidade	Descricao
Similaridade Cosseno	>= 0.60	[0.0, 1.0]	Similaridade probe vs template de referencia. Maior = mais similar.
Distancia Euclidiana	<= 0.85	[0.0, ~2.0]	Distancia no espaco de embeddings. Menor = mais similar.
Similaridade Mutua	>= 0.55	[0.0, 1.0]	Consistencia entre as 3 referencias. Maior = referencias sao do mesmo animal.
Verificacao de Dominio	passar	binario	Fotos devem ser focinhos validos, nao ruido ou imagens fora do dominio.

Exemplo de Requisicao

Exemplo JSON com 3 referencias e 1 probe em base64:

curl -X POST http://127.0.0.1:8000/predict \ -H "Content-Type: application/json" \ -H "X-API-Key: SUA_API_KEY" \ -d '{ "reference_photos": [ "BASE64_REF_1", "BASE64_REF_2", "BASE64_REF_3" ], "probe_photo": "BASE64_PROBE" }'

Campos da Resposta CONSUMER-FACING

A resposta tem 3 secoes de nivel raiz. decision e summary sao para o consumidor final. details e para debugging tecnico.

decision -- Veredicto e metricas principais

Campo	Tipo	Range / Valores	Descricao
`decision.verdict`	string	`"MATCH"` \| `"NO_MATCH"` \| `"INVALID_INPUT"`	MATCH = probe e o mesmo animal das referencias. NO_MATCH = animal diferente. INVALID_INPUT = fotos fora do dominio ou referencias inconsistentes entre si.
`decision.score`	float	[0.0, 1.0]	ESTA E A METRICA PRINCIPAL. Similaridade cosseno do ensemble. Mostre este numero ao usuario final. Quanto mais proximo de 1.0, maior a similaridade. O veredicto e determinado comparando este valor com PREDICT_COSINE_THRESHOLD.
`decision.confidence`	float	[0.0, 1.0]	Score de confianca derivado da distancia euclidiana. Formula: max(0, min(1, (threshold - distance) / threshold)). Quanto maior, mais confiavel o veredicto. 0.0 = distancias muito altas, definitivamente animais diferentes.
`decision.confidence_label`	string	`"NOT_THE_ANIMAL"` \| `"FAIR"` \| `"GOOD"` \| `"EXCELLENT"`	Classificacao de confianca em texto. NOT_THE_ANIMAL = confidence 0.0, definitely different. EXCELLENT = near-certain match.
`decision.explanation`	string	texto	Explicacao em texto do resultado. Use este campo para exibir ao usuario final sem precisar interpretar valores numericos.

summary -- Detalhamento dos criterios

Campo	Tipo	Descricao
`summary.criteria[].metric`	string	Nome da metrica: `cosine_similarity`, `euclidean_distance`, `mutual_similarity`, `domain_check`. Use para identificar programaticamente qual criterio foi avaliado.
`summary.criteria[].value`	float	Valor observado da metrica para esta predicao.
`summary.criteria[].threshold`	float	Limiar usado na comparacao. Compare value vs threshold: para cosine/mutual, passed = value >= threshold; para euclidean, passed = value <= threshold.
`summary.criteria[].passed`	bool	True = criterio satisfeito. False = criterio falhou. TODOS os criterios devem passar para MATCH.
`summary.criteria[].description`	string	Explicacao em texto do que foi avaliado, valor observado, limiar e se passou. Pronto para exibir ao usuario.

details -- Dados tecnicos por modelo TECHNICAL / DEBUG

Campo	Tipo	Descricao
`details.models[].model_id`	int	ID do modelo TensorFlow: 60, 62, ou 64. Cada modelo e um siames treinado independentemente. Use para auditar comportamento por modelo.
`details.models[].template_vs_probe_cosine`	float	Similaridade cosseno entre o embedding medio das 3 referencias e o probe, computado neste modelo especifico. Range [0.0, 1.0].
`details.models[].reference_vs_probe[].reference_index`	int	Indice da referencia comparada: 0 (primeira), 1 (segunda), 2 (terceira).
`details.models[].reference_vs_probe[].cosine_similarity`	float	Similaridade cosseno entre esta referencia especifica e o probe. Range [0.0, 1.0]. Valores acima de ~0.60 tipicamente indicam mesmo animal.
`details.models[].reference_vs_probe[].euclidean_distance`	float	Distancia euclidiana entre esta referencia especifica e o probe. Range [0.0, ~2.0]. Valores abaixo de ~0.85 tipicamente indicam mesmo animal.
`details.models[].mean_cosine`	float	Media das 3 similaridades cosseno por referencia. Range [0.0, 1.0]. Resume a concordancia geral entre referencias e probe.
`details.models[].min_cosine`	float	Minimo das 3 similaridades cosseno. Range [0.0, 1.0]. Score mais conservador. Se min_cosine e alto mas mean_cosine tambem, ha consistencia.
`details.models[].max_cosine`	float	Maximo das 3 similaridades cosseno. Range [0.0, 1.0]. Score mais otista. Se max >> min, as referencias podem ser inconsistentes.
`details.ensemble.template_vs_probe_cosine`	float	Similaridade cosseno no espaco do ensemble (384 dimensoes = 3 modelos x 128). Este e o valor usado em `decision.score`. Range [0.0, 1.0].
`details.ensemble.template_vs_probe_distance`	float	Distancia euclidiana no espaco do ensemble. Este valor e usado para calcular `decision.confidence`. Range [0.0, ~2.0].
`details.reference_mutual_similarity`	float	Media da similaridade cosseno entre todos os pares das 3 fotos de referencia. Range [0.0, 1.0]. Valores altos indicam que as 3 referencias sao do mesmo animal. Valores baixos (< PREDICT_MUTUAL_MIN) indicam que as referencias sao de animais diferentes.

Exemplo de Resposta Completo

Caso de MATCH -- mesmas 3 referencias e probe do mesmo animal:

{ "decision": { "verdict": "MATCH", "score": 0.87, "confidence": 0.61, "confidence_label": "GOOD", "is_same_animal": true, "explanation": "The probe photo matches the reference animal with GOOD confidence." }, "summary": { "criteria": [ {"metric": "cosine_similarity", "value": 0.87, "threshold": 0.62, "passed": true, "description": "Cosine similarity (0.87) is above threshold (0.62)"}, {"metric": "euclidean_distance", "value": 0.41, "threshold": 0.85, "passed": true, "description": "Euclidean distance (0.41) is below threshold (0.85)"}, {"metric": "mutual_similarity", "value": 0.79, "threshold": 0.40, "passed": true, "description": "Reference photos are consistent (0.79 > 0.40)"}, {"metric": "domain_check", "value": 1, "threshold": 1, "passed": true, "description": "Domain check passed for all 4 photos"} ] }, "details": { "models": [ { "model_id": 60, "template_vs_probe_cosine": 0.86, "template_vs_probe_distance": 0.44, "reference_vs_probe": [ {"cosine": 0.85, "distance": 0.47}, {"cosine": 0.87, "distance": 0.43}, {"cosine": 0.86, "distance": 0.45} ], "mean_cosine": 0.86, "min_cosine": 0.85, "max_cosine": 0.87 }, { "model_id": 62, "template_vs_probe_cosine": 0.88, "template_vs_probe_distance": 0.39, "reference_vs_probe": [ {"cosine": 0.87, "distance": 0.41}, {"cosine": 0.89, "distance": 0.38}, {"cosine": 0.88, "distance": 0.40} ], "mean_cosine": 0.88, "min_cosine": 0.87, "max_cosine": 0.89 }, { "model_id": 64, "template_vs_probe_cosine": 0.85, "template_vs_probe_distance": 0.51, "reference_vs_probe": [ {"cosine": 0.84, "distance": 0.53}, {"cosine": 0.86, "distance": 0.49}, {"cosine": 0.85, "distance": 0.51} ], "mean_cosine": 0.85, "min_cosine": 0.84, "max_cosine": 0.86 } ], "ensemble": { "template_vs_probe_cosine": 0.87, "template_vs_probe_distance": 0.41, "mean_cosine": 0.87, "min_cosine": 0.84, "max_cosine": 0.89 }, "reference_mutual_similarity": 0.79 } }

Exemplo: NO_MATCH

Caso em que o probe e de um animal diferente das referencias:

{ "decision": { "verdict": "NO_MATCH", "score": 0.54, "confidence": 0.21, "confidence_label": "FAIR", "is_same_animal": false, "explanation": "The probe photo does not match the reference animal." }, "summary": { "criteria": [ {"metric": "cosine_similarity", "value": 0.54, "threshold": 0.62, "passed": false, "description": "Cosine similarity (0.54) is below threshold (0.62)"}, {"metric": "euclidean_distance", "value": 1.02, "threshold": 0.85, "passed": false, "description": "Euclidean distance (1.02) exceeds threshold (0.85)"}, {"metric": "mutual_similarity", "value": 0.81, "threshold": 0.40, "passed": true, "description": "Reference photos are consistent (0.81 > 0.40)"}, {"metric": "domain_check", "value": 1, "threshold": 1, "passed": true, "description": "Domain check passed for all 4 photos"} ] }, "details": { "models": [ { "model_id": 60, "template_vs_probe_cosine": 0.53, "template_vs_probe_distance": 1.05, "reference_vs_probe": [ {"cosine": 0.52, "distance": 1.08}, {"cosine": 0.54, "distance": 1.04}, {"cosine": 0.53, "distance": 1.06} ], "mean_cosine": 0.53, "min_cosine": 0.52, "max_cosine": 0.54 }, { "model_id": 62, "template_vs_probe_cosine": 0.56, "template_vs_probe_distance": 0.98, "reference_vs_probe": [ {"cosine": 0.55, "distance": 1.01}, {"cosine": 0.57, "distance": 0.96}, {"cosine": 0.56, "distance": 0.99} ], "mean_cosine": 0.56, "min_cosine": 0.55, "max_cosine": 0.57 }, { "model_id": 64, "template_vs_probe_cosine": 0.51, "template_vs_probe_distance": 1.12, "reference_vs_probe": [ {"cosine": 0.50, "distance": 1.15}, {"cosine": 0.52, "distance": 1.10}, {"cosine": 0.51, "distance": 1.13} ], "mean_cosine": 0.51, "min_cosine": 0.50, "max_cosine": 0.52 } ], "ensemble": { "template_vs_probe_cosine": 0.54, "template_vs_probe_distance": 1.02, "mean_cosine": 0.54, "min_cosine": 0.50, "max_cosine": 0.57 }, "reference_mutual_similarity": 0.81 } }

Exemplo: INVALID_INPUT

Caso em que as referencias nao sao consistentes entre si (possivelmente de animais diferentes):

{ "decision": { "verdict": "INVALID_INPUT", "score": 0.0, "confidence": 0.0, "confidence_label": "NOT_THE_ANIMAL", "is_same_animal": false, "explanation": "Reference photos are not consistent with each other." }, "summary": { "criteria": [ {"metric": "cosine_similarity", "value": 0.0, "threshold": 0.62, "passed": false, "description": "Cosine similarity (0.0) is below threshold (0.62)"}, {"metric": "euclidean_distance", "value": 0.0, "threshold": 0.85, "passed": false, "description": "Euclidean distance (0.0) is below threshold (0.85)"}, {"metric": "mutual_similarity", "value": 0.29, "threshold": 0.40, "passed": false, "description": "Reference photos are NOT consistent (0.29 < 0.40) -- possibly different animals"}, {"metric": "domain_check", "value": 1, "threshold": 1, "passed": true, "description": "Domain check passed for all 4 photos"} ] }, "details": { "models": [ { "model_id": 60, "template_vs_probe_cosine": 0.0, "template_vs_probe_distance": 0.0, "reference_vs_probe": [ {"cosine": 0.0, "distance": 0.0}, {"cosine": 0.0, "distance": 0.0}, {"cosine": 0.0, "distance": 0.0} ], "mean_cosine": 0.0, "min_cosine": 0.0, "max_cosine": 0.0 }, { "model_id": 62, "template_vs_probe_cosine": 0.0, "template_vs_probe_distance": 0.0, "reference_vs_probe": [ {"cosine": 0.0, "distance": 0.0}, {"cosine": 0.0, "distance": 0.0}, {"cosine": 0.0, "distance": 0.0} ], "mean_cosine": 0.0, "min_cosine": 0.0, "max_cosine": 0.0 }, { "model_id": 64, "template_vs_probe_cosine": 0.0, "template_vs_probe_distance": 0.0, "reference_vs_probe": [ {"cosine": 0.0, "distance": 0.0}, {"cosine": 0.0, "distance": 0.0}, {"cosine": 0.0, "distance": 0.0} ], "mean_cosine": 0.0, "min_cosine": 0.0, "max_cosine": 0.0 } ], "ensemble": { "template_vs_probe_cosine": 0.0, "template_vs_probe_distance": 0.0, "mean_cosine": 0.0, "min_cosine": 0.0, "max_cosine": 0.0 }, "reference_mutual_similarity": 0.29 } }

Niveis de Confianca

Label	Faixa de confidence	Significado
NOT_THE_ANIMAL	0.00	Distancia euclidiana excedeu o limiar. Definitivamente animais diferentes.
FAIR	0 < c < 0.65	Possivel correspondencia, revisao recomendada.
GOOD	0.65 <= c < {{GOOD_THRESHOLD}}	Alta probabilidade de correspondencia.
EXCELLENT	c >= {{GOOD_THRESHOLD}}	Correspondencia quase certa.

Requisitos de Imagem

Formato e Tamanho

JPEG ou PNG (base64)
Maximo 10MB por imagem
Minimo 56x56 pixels (redimensionado automaticamente)
Exatamente 3 referencias + 1 probe

Qualidade

Boa iluminacao, sem sombras
Angulo frontal do focinho
Foco nitido no padrao
Sem obstrucoes (cabresto, grama, sujeira)

Autenticacao

Todas as requisicoes exigem header X-API-Key. Limite: 30 req / 60s por IP.

Erros

Codigo	Descricao
401	API Key invalida ou ausente
422	Payload invalido (menos de 3 referencias, tamanho excedido)
429	Limite de requisicoes excedido (Retry-After header)
500	Erro interno de processamento
503	Modelos nao carregados

Sobre a MUU Biometria

A MUU Agrotech e uma empresa brasileira de inovacao tecnologica que desenvolveu a MUU Biometria, um sistema de rastreabilidade por biometria facial bovina. A tecnologia utiliza o focinho do animal como identificador unico -- uma verdadeira "digital" do gado.

Rastreabilidade Bovina

Acompanhe cada animal da fazenda ao frigorifico com identidade verificada e inalteravel.

Anti-Fraude

Impeca a substituicao de animais em transacoes comerciais.

API Key (X-API-Key)

Deixe vazio se API_KEY nao estiver configurado

Foto de Referencia 1 (base64 JPEG)

Foto de Referencia 2 (base64 JPEG)

Foto de Referencia 3 (base64 JPEG)

Foto de Prova (base64 JPEG)

Upload de Arquivos de Imagem

Variante do endpoint /predict que aceita arquivos JPEG ou PNG via multipart/form-data em vez de strings base64. Ideal para integracoes que enviam imagens diretamente do disco ou camera.

Quando Usar

Cenario	Endpoint recomendado	Motivo
Frontend web/mobile com arquivo local	`POST /predict/file`	Evita converter imagem para base64 no cliente.
Backend ja trabalha com JSON/base64	`POST /predict`	Mais simples para pipelines que trafegam payload JSON.
Integracao com camera, form HTML ou upload direto	`POST /predict/file`	`multipart/form-data` e o formato natural nesses casos.

Campos do Formulario

Campo	Tipo	Obrigatorio	Descricao
reference_photo_1	file	sim	Primeira foto de referencia do animal conhecido. Use uma foto nitida do focinho.
reference_photo_2	file	sim	Segunda referencia do mesmo animal. Preferencialmente outro angulo ou iluminacao.
reference_photo_3	file	sim	Terceira referencia do mesmo animal. As 3 referencias devem ser do mesmo individuo.
probe_photo	file	sim	Foto de prova a ser comparada com o template medio das 3 referencias.

Validacoes de Entrada

Regra	Valor	Consequencia
Tipos aceitos	`image/jpeg` ou `image/png`	Qualquer outro content-type retorna `422`.
Tamanho maximo	10MB por arquivo	Arquivos acima do limite retornam `422`.
Quantidade	3 referencias + 1 probe	Qualquer ausencia invalida a requisicao.

Exemplo de Requisicao

Exemplo com curl usando upload multipart:

curl -X POST http://127.0.0.1:8000/predict/file \ -H "X-API-Key: SUA_API_KEY" \ -F "reference_photo_1=@ref_1.jpg" \ -F "reference_photo_2=@ref_2.jpg" \ -F "reference_photo_3=@ref_3.jpg" \ -F "probe_photo=@probe.jpg"

Resposta

Identica ao POST /predict: mesmos campos, criterios, niveis de confianca e estrutura decision + summary + details. Use a secao de POST /predict como referencia canonica para interpretar a resposta.

Erros Comuns

Codigo	Causa tipica	Como corrigir
401	Header `X-API-Key` ausente ou invalido	Enviar a chave correta ou desabilitar auth no ambiente de desenvolvimento.
422	Arquivo ausente, formato invalido ou tamanho excedido	Garantir os 4 arquivos, usar JPEG/PNG e respeitar o limite por arquivo.
503	Modelos nao carregados	Consultar `GET /health` antes da chamada.

Validacao de Imagem de Focinho

Verifica se uma unica imagem e um focinho bovino valido (em oposicao a ruido, imagens em branco, ou conteudo completamente fora do dominio). Analisa estatisticas dos embeddings gerados pelos 3 modelos siameses.

Nota: Este endpoint nao compara com referencias. Para verificar se uma foto e de um animal especifico, use POST /predict. Este endpoint apenas determina se a foto parece ser um focinho valido.

Quando Usar

Cenario	Use este endpoint?	Observacao
Triagem de qualidade antes do cadastro	Sim	Ajuda a filtrar imagens obviamente invalidas antes de chamar `/predict`.
Validar se uma foto e do mesmo animal	Nao	Para identidade, use `POST /predict`.
Pipeline de upload em etapas	Sim	Pode rodar primeiro o domain check e depois o predict apenas nas imagens aprovadas.

Exemplo de Requisicao

Envie uma unica imagem em base64 dentro de JSON:

curl -X POST http://127.0.0.1:8000/domain-check \ -H "Content-Type: application/json" \ -H "X-API-Key: SUA_API_KEY" \ -d '{ "photo": "BASE64_DA_IMAGEM" }'

Como Funciona

A foto e passada pelos 3 modelos siameses (IDs: 60, 62, 64), gerando 3 embeddings de 128 dimensoes cada (ensemble de 384 dimensoes). Duas estatisticas sao calculadas:

embedding_variance: variancia dos valores do embedding ensemble. Imagens em branco/ruido geram variancia proxima de zero. Focinhos validos geram variancia > 0.1200.
cross_model_consistency: similaridade cosseno media par-a-par entre os 3 embeddings individuais. Valores muito altos (perto de 1.0) indicam que todos os modelos colapsaram para o mesmo ponto -- sinal forte de conteudo fora do dominio.

Criterios de Validacao

Metrica	Limiar	Unidade	Descricao
embedding_variance	>= 0.1200	[0.0, ~0.25]	Spread dos valores do embedding. Focinhos validos geram variancia alta (> 0.12). Imagens sem informacao (ruido, solido) tem variancia proxima de zero.
cross_model_consistency	<= 0.05	[-1.0, 1.0]	Media da similaridade cosseno par-a-par entre os 3 modelos. Valores perto de 1.0 = colapso de embedding (fora do dominio).

Campos da Resposta

decision -- Veredicto CONSUMER-FACING

Campo	Tipo	Valores	Descricao
`decision.verdict`	string	`"VALID_MUZZLE"` \| `"INVALID_INPUT"`	VALID_MUZZLE = a foto passou em todos os criterios. INVALID_INPUT = falhou em pelo menos um criterio.
`decision.explanation`	string	texto	Explicacao em texto do resultado. Para VALID_MUZZLE, descreve o que passou. Para INVALID_INPUT, nomeia qual criterio falhou e por que. Use este campo para exibir ao usuario.

Metricas numericas

Campo	Tipo	Range	Descricao
`embedding_variance`	float	[0.0, ~0.25]	Variancia dos 384 valores do embedding ensemble. Focinhos validos tipicamente > 0.12. Imagens sem conteudo ou fora do dominio tendem a ter variancia menor.
`cross_model_consistency`	float	[-1.0, 1.0]	Media da similaridade cosseno par-a-par entre modelos 60, 62, 64. Normal: perto de 0.0. Colapso: perto de 1.0. Este valor deve ser <= 0.05 para passar.

summary.criteria -- Detalhamento CONSUMER-FACING

Campo	Tipo	Descricao
`criteria[].metric`	string	Nome da metrica: `embedding_variance` ou `cross_model_consistency`.
`criteria[].value`	float	Valor observado.
`criteria[].threshold`	float	Limiar de comparacao.
`criteria[].passed`	bool	True = criterio satisfeito. False = criterio falhou. Todos devem passar para VALID_MUZZLE.
`criteria[].description`	string	Explicacao em texto. Pronto para exibir ao usuario.

Exemplo: VALID_MUZZLE

Foto de focinho bovino valido -- todos os criterios passam:

{ "decision": { "verdict": "VALID_MUZZLE", "explanation": "The image appears to be a valid muzzle photo. All quality criteria passed." }, "embedding_variance": 0.031, "cross_model_consistency": 0.05, "summary": { "criteria": [ { "metric": "embedding_variance", "value": 0.031, "threshold": 0.005, "passed": true, "description": "Embedding variance (0.031) indicates meaningful content (>0.005)" }, { "metric": "cross_model_consistency", "value": 0.05, "threshold": 0.20, "passed": true, "description": "Cross-model pairwise similarity (0.05) is within expected range (<=0.20)" } ] } }

Exemplo: INVALID_INPUT

Imagem de ruido/cinza solido -- embedding_variance muito baixo indica falta de conteudo:

{ "decision": { "verdict": "INVALID_INPUT", "explanation": "The image failed the domain check. embedding_variance is too low." }, "embedding_variance": 0.0008, "cross_model_consistency": 0.02, "summary": { "criteria": [ { "metric": "embedding_variance", "value": 0.0008, "threshold": 0.005, "passed": false, "description": "Embedding variance (0.0008) is too low -- image has no meaningful content (<0.005)" }, { "metric": "cross_model_consistency", "value": 0.02, "threshold": 0.20, "passed": true, "description": "Cross-model pairwise similarity (0.02) is within expected range (<=0.20)" } ] } }

Exemplo: INVALID_INPUT (colapso de embedding)

Imagem que causa colapso de embedding -- modelos produzem saidas quase identicas (cross_model_consistency alto):

{ "decision": { "verdict": "INVALID_INPUT", "explanation": "The image failed the domain check. cross_model_consistency indicates embedding collapse." }, "embedding_variance": 0.045, "cross_model_consistency": 0.87, "summary": { "criteria": [ { "metric": "embedding_variance", "value": 0.045, "threshold": 0.005, "passed": true, "description": "Embedding variance (0.045) indicates meaningful content (>0.005)" }, { "metric": "cross_model_consistency", "value": 0.87, "threshold": 0.20, "passed": false, "description": "Cross-model pairwise similarity (0.87) is too high -- embedding collapse detected (>0.20)" } ] } }

Autenticacao e Erros

Codigo	Causa tipica	Como corrigir
401	Header `X-API-Key` ausente ou invalido	Enviar a chave correta quando a autenticacao estiver habilitada.
422	Imagem ausente, base64 invalido ou tamanho excedido	Validar o payload JSON e o tamanho da string enviada.
503	Modelos nao carregados	Checar `GET /health` antes de usar em producao.

Limitacoes Conhecidas

Limite	Impacto pratico
Este endpoint nao identifica o animal	Uma imagem pode ser um focinho valido e ainda assim nao pertencer ao animal esperado.
Single-image only	Ele nao compara com referencias e nao mede similaridade entre animais.
Nao e classificador anatomico perfeito	Pode aceitar algumas imagens bovinas fora do caso ideal de focinho. Trate como filtro de qualidade inicial.

Validacao de Arquivo de Imagem

Variante do endpoint /domain-check que aceita um arquivo JPEG ou PNG via multipart/form-data em vez de string base64. Mesma logica e formato de resposta. Consulte a documentacao completa de campos em POST /domain-check.

Quando Usar

Cenario	Endpoint recomendado	Motivo
Upload direto do navegador	`POST /domain-check/file`	Nao exige conversao para base64.
Backend ja trafega JSON	`POST /domain-check`	Integra melhor com payloads padronizados.
Validacao de imagem logo apos selecao do arquivo	`POST /domain-check/file`	Fluxo mais direto para formularios com upload.

Campos do Formulario

Campo	Tipo	Obrigatorio	Descricao
photo	file	sim	Imagem do focinho para validar. Aceita JPEG ou PNG com ate 10MB.

Exemplo de Requisicao

curl -X POST http://127.0.0.1:8000/domain-check/file \ -H "X-API-Key: SUA_API_KEY" \ -F "photo=@muzzle.jpg"

Resposta

Identica ao POST /domain-check: decision, embedding_variance, cross_model_consistency e summary. Consulte o endpoint base para interpretar cada campo.

Erros Comuns

Codigo	Causa tipica	Como corrigir
401	Header `X-API-Key` ausente ou invalido	Enviar a chave correta quando auth estiver habilitada.
422	Arquivo ausente, formato invalido ou tamanho excedido	Garantir JPEG/PNG e respeitar 10MB.
503	Modelos nao carregados	Consultar `GET /health` antes do fluxo de validacao.

Geracao de Codigo ML (JSON)

Gera codigos de embedding para 1 a 12 imagens usando os 3 modelos (60, 62, 64). Para cada imagem, retorna os codigos individuais de 128 dimensoes por modelo e o codigo de ensemble concatenado com 384 dimensoes.

Fluxo

Imagem -> 3 modelos ML -> model_codes (3 x 128) -> ensemble_code (384 concatenado). A API tambem executa domain-check por imagem e retorna decision e domain_summary.

Quando Usar

Cenario	Motivo	Observacao
Backend com base64	Evita upload multipart e usa o payload JSON diretamente.	Bom para integracoes server-to-server.
Batch de cadastro	Permite codificar ate 12 imagens em uma chamada.	Use `index` para preservar a ordem.
Pipeline de auditoria	Retorna o domain-check e os codigos no mesmo fluxo.	Facilita rastrear imagens invalidas sem perder o output.

Request

Campo	Tipo	Obrigatorio	Descricao
photos	array[string]	sim	Lista de imagens base64, minimo 1 e maximo 12.

Exemplo de Requisicao

curl -X POST http://127.0.0.1:8000/encode \ -H "Content-Type: application/json" \ -H "X-API-Key: SUA_API_KEY" \ -d '{"photos":["BASE64_IMAGE_1","BASE64_IMAGE_2"]}'

Campos da Resposta

Campo	Tipo	Range / Valores	Descricao
images[].index	int	0..N-1	Indice da imagem na entrada, preserva a sequencia do input.
images[].filename	string	photo_0, photo_1...	Identificador da imagem (JSON usa nome gerado automaticamente).
images[].decision.verdict	string	VALID_MUZZLE / INVALID_INPUT	Resultado do domain-check da imagem.
images[].domain_summary.criteria[]	array	2 criterios	Detalhes de validacao (`embedding_variance` e `cross_model_consistency`).
images[].model_codes[]	array	3 itens	Codigos individuais por modelo (60, 62, 64), cada um com 128 floats.
images[].ensemble_code	array[float]	384 valores	Concatenacao dos 3 codigos individuais (3 x 128).

Exemplo de Resposta

{ "images": [ { "index": 0, "filename": "photo_0", "decision": { "verdict": "VALID_MUZZLE", "explanation": "The image appears to be a valid muzzle photo. All quality criteria passed." }, "domain_summary": { "criteria": [ {"metric": "embedding_variance", "value": 0.031, "threshold": 0.005, "passed": true, "description": "..."}, {"metric": "cross_model_consistency", "value": 0.05, "threshold": 0.20, "passed": true, "description": "..."} ] }, "model_codes": [ {"model_id": 60, "code": [0.12, -0.34, 0.22]}, {"model_id": 62, "code": [0.08, -0.11, 0.45]}, {"model_id": 64, "code": [-0.09, 0.27, 0.14]} ], "ensemble_code": [0.12, -0.34, 0.22, 0.08, -0.11, 0.45, -0.09, 0.27, 0.14] } ] }

Erros Comuns

Codigo	Causa tipica	Como corrigir
401	Header `X-API-Key` ausente ou invalido.	Enviar a chave correta quando a autenticacao estiver habilitada.
422	Lista vazia, mais de 12 imagens ou imagem base64 invalida/excessiva.	Enviar de 1 a 12 imagens validas e respeitar o limite de tamanho.
429	Limite de taxa excedido.	Aguardar o periodo configurado antes de reenviar.
503	Modelos nao carregados.	Consultar `GET /health` antes do fluxo de encode.

Geracao de Codigo ML (Multipart)

Mesmo resultado do POST /encode, mas com upload de arquivo (multipart/form-data). Aceita 1 a 12 imagens JPEG/PNG e preserva a ordem de envio no campo index.

Quando Usar

Cenario	Motivo	Observacao
Upload via browser	Recebe arquivos diretamente do formulario ou file picker.	Nao exige conversao previa para base64.
Aplicativo mobile	Facilita enviar fotos capturadas pela camera.	Preserva o nome original em `filename`.
Lote de arquivos	Permite enviar ate 12 arquivos no mesmo request.	A ordem de envio vira `images[].index`.

Request

Campo	Tipo	Obrigatorio	Descricao
photos	file[]	sim	Enviar de 1 a 12 arquivos com o mesmo nome de campo `photos`.

Exemplo de Requisicao

curl -X POST http://127.0.0.1:8000/encode/file \ -H "X-API-Key: SUA_API_KEY" \ -F "photos=@img_1.jpg" \ -F "photos=@img_2.jpg"

Campos da Resposta

Campo	Tipo	Range / Valores	Descricao
images[].index	int	0..N-1	Indice que preserva a ordem original de envio dos arquivos.
images[].filename	string	nome do arquivo enviado	Nome original do arquivo quando disponivel, facilitando o mapeamento visual.
images[].decision.verdict	string	VALID_MUZZLE / INVALID_INPUT	Resultado do domain-check executado antes da entrega do codigo.
images[].domain_summary.criteria[]	array	2 criterios	Detalhes de validacao de dominio para cada imagem.
images[].model_codes[]	array	3 itens	Um codigo de 128 dimensoes por modelo (60, 62, 64).
images[].ensemble_code	array[float]	384 valores	Concatenacao dos 3 codigos individuais em um vetor unico.

Exemplo de Resposta

{ "images": [ { "index": 0, "filename": "img_1.jpg", "decision": { "verdict": "VALID_MUZZLE", "explanation": "The image appears to be a valid muzzle photo. All quality criteria passed." }, "domain_summary": { "criteria": [ {"metric": "embedding_variance", "value": 0.031, "threshold": 0.005, "passed": true, "description": "..."}, {"metric": "cross_model_consistency", "value": 0.05, "threshold": 0.20, "passed": true, "description": "..."} ] }, "model_codes": [ {"model_id": 60, "code": [0.12, -0.34, 0.22]}, {"model_id": 62, "code": [0.08, -0.11, 0.45]}, {"model_id": 64, "code": [-0.09, 0.27, 0.14]} ], "ensemble_code": [0.12, -0.34, 0.22, 0.08, -0.11, 0.45, -0.09, 0.27, 0.14] } ] }

Erros Comuns

Codigo	Causa tipica	Como corrigir
401	Header `X-API-Key` ausente ou invalido.	Enviar a chave correta quando a autenticacao estiver habilitada.
422	Arquivo invalido, formato incorreto, excesso de arquivos ou tamanho excedido.	Enviar entre 1 e 12 arquivos JPEG/PNG e respeitar 10MB por arquivo.
429	Limite de taxa excedido.	Aguardar o periodo configurado antes de reenviar.
503	Modelos nao carregados.	Consultar `GET /health` antes do fluxo de encode.