API Documentation

Disponible para el plan Pro. Integra el análisis facial de Phivara en tu software de gestión.

Base URL

https://api.phivara.com

Autenticación

Todas las requests autenticadas requieren este header:

X-API-Key: phv_tu_api_key_aquí

Endpoints

POST/api/v1/analyze

Análisis facial completo. Envía las features extraídas y recibe score + reporte.

Request body
{
  "features": {
    "facial_width_height":   0.78,
    "eye_spacing_width":     0.44,
    "jaw_width_facial":      0.72,
    "thirds_balance":        0.95,
    "nose_width_facial":     0.28,
    "mouth_width_facial":    0.38,
    "jaw_angle":             125,
    "eye_tilt":              2.3,
    "symmetry":              0.87,
    "eye_mouth_ratio":       0.36,
    "nose_intercantal_match":0.98,
    "lower_third_ratio":     0.31,
    "upper_third_pct":       0.33,
    "lower_third_pct":       0.34
  },
  "demographic": "european",
  "gender":      "female",
  "locale":      "es"
}
Response
{
  "score":       74,
  "percentile":  68,
  "summary":     "Proporciones muy armónicas con rasgos diferenciadores positivos.",
  "strengths":   ["Alta simetría facial", "Tercios bien equilibrados"],
  "improvements":["Anchura nasal por encima del promedio"],
  "recommendations": ["..."],
  "subscores":   { "proporciones": 65, "simetria": 85, "armonia": 72 },
  "activeRules": [...],
  "flags":       ["good_symmetry", "balanced_thirds", "wide_nose"]
}
GET/api/v1/usage

Consulta el uso actual de tu API key.

Response
{
  "plan":      "pro",
  "rateLimit": 50,
  "used":      47,
  "resetsAt":  "2026-06-05T00:00:00.000Z"
}
GET/api/v1/health

Health check público. No requiere autenticación.

Sin autenticación
Response
{ "status": "ok", "version": "1.6.0" }

Rate Limits

Pro50 requests/día

El contador se resetea a las 00:00 UTC cada día. Si excedes el límite, recibirás HTTP 429.

Códigos de error

400Payload inválido — ver campo "details"
401API key inválida o inactiva
429Rate limit excedido — espera hasta las 00:00 UTC
500Error interno

Grupos demográficos

universaleuropeanafricaneast_asiansouth_asianlatinomiddle_eastern

Cada grupo tiene distribuciones estadísticas propias (media + desviación estándar) para las 14 métricas faciales. Esto asegura que el score sea justo independientemente de la etnicidad del paciente.

¿Aún no tienes una API key?

Ver planes →