API Reference

A API REST é servida via FastAPI e expõe dois endpoints principais.

Documentação interativa

A API inclui Swagger UI em /docs e ReDoc em /redoc, gerados automaticamente pelo FastAPI.

Base URL

Ambiente	URL
Local	http://localhost:8000
Produção	https://sdk-demo.valid.ia.br

Endpoints

GET /api/health

Verifica o status da API.

Response 200 OK

{
  "status": "ok",
  "version": "0.1.0"
}

POST /api/process

Processa uma imagem de digital e retorna a digital extraída com métricas de qualidade.

Request

• Content-Type: multipart/form-data
• Campo file: imagem (JPEG, PNG, BMP, TIFF)
• Tamanho máximo: 10MB (configurável)

curl -X POST \
  -F "file=@foto_dedo.jpg" \
  http://localhost:8000/api/process

Response — Sucesso 200 OK

{
  "success": true,
  "quality_score": 91.4,
  "quality": {
    "sharpness": 1691.2,
    "contrast": 42.7,
    "ridge_clarity": 1763.3,
    "score": 91.4,
    "is_acceptable": true
  },
  "warnings": [],
  "image_base64": "iVBORw0KGgoAAAANSUhEUg..."
}

Response — Erro de Processamento 200 OK

{
  "success": false,
  "quality_score": null,
  "quality": null,
  "warnings": [],
  "image_base64": null,
  "error": "No skin region detected"
}

Response — Erro de Validação 400 Bad Request

Retornado quando o arquivo não é uma imagem válida ou excede o tamanho máximo.

Schemas

ProcessResponse

Campo	Tipo	Descrição
success	boolean	Se o processamento foi bem-sucedido
quality_score	float?	Score geral de qualidade (0-100)
quality	QualityResponse?	Métricas detalhadas de qualidade
warnings	string[]	Avisos durante o processamento
image_base64	string?	Imagem 500x500 PNG codificada em base64
error	string?	Mensagem de erro, se houver

QualityResponse

Campo	Tipo	Descrição
sharpness	float	Variância do Laplacian (nitidez)
contrast	float	Desvio padrão médio em blocos 32px
ridge_clarity	float	Resposta máxima Gabor (clareza das cristas)
score	float	Score composto 0-100
is_acceptable	boolean	Se atende o score mínimo (padrão: 40)

HealthResponse

Campo	Tipo	Descrição
status	string	Status da API ("ok")
version	string	Versão da API

Erros Comuns

Erro	Causa	Solução
No skin region detected	Imagem sem pele visível	Usar foto com dedo visível, boa iluminação
Segmentation failed	Não conseguiu isolar o dedo	Fundo mais uniforme, dedo mais centralizado
File too large	Arquivo excede 10MB	Redimensionar ou comprimir a imagem
Invalid image type	Content-Type não é image/*	Enviar JPEG, PNG, BMP ou TIFF