Developers · API Reference

Developers & API

Integra detección facial, comparación biométrica, enrolamiento, verificación y búsqueda 1:N mediante APIs seguras. Namespace /v1/dafkface/* con API Key, trazabilidad y separación por tenant.

Solicitar acceso técnico Ver producto

Metadata

Información técnica

API: DafkFace Recognition Engine
Namespace: /v1/dafkface/*
Versión OpenAPI: 2.0.0
Autenticación: X-API-Key
Trazabilidad: X-Request-ID
Tenant técnico: X-Tenant-ID

Seguridad

Autenticación

Los endpoints operativos requieren el header X-API-Key. El endpoint de health puede permanecer disponible para monitoreo según configuración.

Las rutas administrativas de API keys requieren una clave de administración.

X-Tenant-ID debe ser un identificador técnico para logs y trazabilidad; no debe contener PII.

Header requerido http · demo

X-API-Key: <YOUR_API_KEY>

Ejemplo demostrativo. No representa un entorno productivo.

Headers opcionales http · demo

X-Request-ID: <TRACE_ID>
X-Tenant-ID: <TECHNICAL_TENANT_ID>

Ejemplo demostrativo. No representa un entorno productivo.

Referencia

Endpoints principales

Superficie oficial del Recognition Engine. Referencia de integración para equipos de desarrollo.

Método	Endpoint	Uso
GET	/v1/dafkface/health	Estado operativo del motor
POST	/v1/dafkface/embed	Generar embedding biométrico (multipart)
POST	/v1/dafkface/embed/json	Generar embedding biométrico (JSON)
POST	/v1/dafkface/compare	Comparación 1:1 (multipart)
POST	/v1/dafkface/compare/json	Comparación 1:1 (JSON)
POST	/v1/dafkface/enroll	Enrolar referencia facial
POST	/v1/dafkface/enroll/json	Enrolar referencia facial (JSON)
POST	/v1/dafkface/verify	Verificación 1:1 contra referencias activas
POST	/v1/dafkface/verify/json	Verificación 1:1 (JSON)
POST	/v1/dafkface/search	Búsqueda facial 1:N
POST	/v1/dafkface/search/json	Búsqueda facial 1:N (JSON)
POST	/v1/dafkface/delete	Revocación lógica de referencias
POST	/v1/dafkface/purge	Eliminación física administrativa (si está habilitada)

Superficie

API versionada para equipos de producto

Contratos claros, autenticación por proyecto y respuestas accionables para onboarding, verificación y búsqueda facial.

Quick start

Ejemplos de integración

Requests demostrativos para las operaciones más usadas.

1. Enroll

POST /v1/dafkface/enroll/json

Registra una referencia facial para un tenant y una identidad técnica.

enroll/json json · demo

{
  "tenant_id": "tenant_demo",
  "person_id": "person_xyz",
  "image_base64": "<BASE64_JPEG_WITH_FACE>",
  "source": "api",
  "meta": {
    "channel": "web-demo"
  }
}

Ejemplo demostrativo. No representa un entorno productivo.

2. Verify

POST /v1/dafkface/verify/json

Verifica un rostro contra referencias activas asociadas a un person_id.

verify/json json · demo

{
  "tenant_id": "tenant_demo",
  "person_id": "person_xyz",
  "image_base64": "<BASE64_JPEG_WITH_FACE>"
}

Ejemplo demostrativo. No representa un entorno productivo.

3. Search

POST /v1/dafkface/search/json

Busca coincidencias faciales 1:N dentro de un tenant.

search/json json · demo

{
  "tenant_id": "tenant_demo",
  "image_base64": "<BASE64_JPEG_WITH_FACE>",
  "top_k": 5
}

Ejemplo demostrativo. No representa un entorno productivo.

4. Compare

POST /v1/dafkface/compare/json

Compara dos rostros por similitud biométrica.

compare/json json · demo

{
  "image_a_base64": "<BASE64_JPEG_WITH_FACE>",
  "image_b_base64": "<BASE64_JPEG_WITH_FACE>"
}

Ejemplo demostrativo. No representa un entorno productivo.

5. Embed

POST /v1/dafkface/embed/json

Genera la representación biométrica. Por defecto no se expone el vector completo porque es un dato sensible. Usa return_embedding=true solo cuando la integración lo requiera.

embed/json json · demo

{
  "image_base64": "<BASE64_JPEG_WITH_FACE>",
  "return_embedding": false
}

Ejemplo demostrativo. No representa un entorno productivo.

Respuesta

Estructura conceptual de respuesta

Ejemplo demostrativo. Los campos específicos dependen del endpoint y del modelo de respuesta.

Response demo json · demo

{
  "success": true,
  "operation": "face_verify_1_1",
  "decision": "MATCH",
  "similarity": {
    "score": 0.87,
    "metric": "cosine"
  },
  "quality": {
    "status": "ok"
  },
  "vector_store": {
    "engine": "qdrant",
    "collection": "dafkface_embeddings_v1"
  },
  "trace": {
    "request_id": "req_demo_123"
  },
  "error_code": null
}

Ejemplo demostrativo. No representa un entorno productivo.

Errores

Manejo de errores

La API normaliza códigos públicos mediante error_code para que los clientes implementen lógica consistente.

Estos códigos permiten diferenciar errores de calidad, imagen, disponibilidad del modelo, disponibilidad del motor vectorial y referencias biométricas.

FACE_NOT_DETECTED
MULTIPLE_FACES_DETECTED
FACE_QUALITY_REJECTED
FACE_DETECTION_SCORE_TOO_LOW
IMAGE_TOO_LARGE
INVALID_BASE64
INVALID_IMAGE
MODEL_NOT_READY
CUDA_NOT_AVAILABLE
QDRANT_NOT_CONFIGURED
QDRANT_UNAVAILABLE
REFERENCE_NOT_FOUND

Integración

Buenas prácticas

Recomendaciones para consumir el motor de forma segura y trazable.

No exponer embeddings sin necesidad

Las representaciones biométricas son datos sensibles. Solicita return_embedding=true solo cuando la integración lo requiera.

Usar X-Request-ID

Enviar un identificador de trazabilidad por operación facilita auditoría y soporte técnico.

Evitar PII en X-Tenant-ID

Usa identificadores técnicos opacos para logs y trazabilidad. No incluyas datos personales.

Separar tenant y person_id

tenant_id representa el espacio de operación; person_id representa una identidad técnica dentro de ese espacio.

Reglas de negocio fuera del motor

DAFKFace entrega inferencia biométrica y trazabilidad. Las políticas de aprobación, rechazo o revisión humana se definen en el sistema consumidor.

Monitorear health

GET /v1/dafkface/health permite diagnosticar el estado operativo del motor antes y durante la operación.

¿Listo para conversar sobre tu proyecto?

IA, automatización, cloud, software o biometría: evaluemos arquitectura, alcance e integración para tu operación.

Agendar reunión Contactar por WhatsApp