Integrar la API REST del Server

Invoca primero GET /v1/health. Este endpoint siempre es público e informa tanto readiness como auth_enabled. Si auth_enabled es true, todos los demás endpoints requieren Authorization: Bearer <api_key>. Si la autenticación está desactivada, omite por completo el header Authorization; no envíes un header vacío. El primer bloque muestra exactamente la forma sin autenticación y el segundo corresponde a despliegues autenticados.

La API usa JSON snake_case y multipart/form-data para imágenes. Cada respuesta incluye un header UUID x-request-id y los bodies JSON lo repiten como request_id. Las señales de detección y calidad usan 0.0–1.0, pero recognition similarity es el coseno bruto en [-1.0, 1.0], no una probabilidad. threshold acepta el intervalo inclusivo [0.0, 1.0], vale 0.4 por defecto y hay coincidencia cuando similarity >= threshold.

Una Collection es una base de identidades aislada y un contrato de despliegue. Al crearla fija ID y versión del modelo activo, bundle digest, dimensión del embedding, versión de preprocesado, detection profile y exact-search profile. La embedding_contract_id devuelta es opaca: cópiala para trusted external enrollment y nunca la construyas.

Empieza con threshold 0.4 y calíbralo con datos de validación representativos. Las respuestas de Collection exponen detection_revision y la configuración efectiva de búsqueda. Los cambios posteriores del detection profile se aplican a nuevas peticiones, pero no vuelven a extraer FaceSamples existentes. Los perfiles realizan búsqueda plana exhaustiva; los de menor precisión aproximan el coseno FP32, pero no son índices ANN.

El registro usa multipart y admite varias imágenes en una petición. review_mode=off sigue la estrategia de selección de la Collection; standard exige exactamente un rostro utilizable y aplica controles configurados de tamaño, confianza, calidad y pose; strict añade comparaciones de similitud dentro y fuera de la persona. Un lote puede tener éxito parcial con HTTP 201, así que revisa faces y rejected_images.

Search selecciona un query face con el perfil de la Collection, lo compara con cada FaceSample activo y asigna a cada persona la mejor puntuación de sus muestras. Solo devuelve resultados iguales o superiores al threshold efectivo, ordenados por similarity descendente. Valida el flujo con una imagen distinta de las usadas al registrar.

Detect devuelve todos los rostros utilizables ordenados por área, con cajas en píxeles y normalizadas, cinco landmarks, confianza del detector y señales locales de calidad. No devuelve embeddings ni persiste datos. Pasa collection_id para usar el detection profile de esa Collection en lugar del perfil inmutable del sistema.

Compare selecciona un rostro de source y otro de target, calcula la similarity de coseno bruta y devuelve matched según el threshold efectivo. La similarity puede ser negativa y nunca debe presentarse como porcentaje de confianza. Si una imagen no contiene un rostro utilizable, devuelve 422 face_not_found.

Instala el cliente directamente desde este checkout. Usa httpx, no contiene runtime de inferencia y acepta rutas, bytes u objetos binarios de tipo archivo. Espera 65 segundos por defecto, un poco más que el deadline de 60 segundos del servidor.

El ejemplo usa la dirección CPU de la guía, en el puerto 18097, y un servidor autenticado. Con autenticación desactivada, crea Client("http://localhost:18097") sin api_key para no enviar ningún Authorization header. El mismo cliente ofrece create_monitor, update_monitor, monitor_state y monitor_events basado en cursor.

Los errores comparten un envelope JSON con error.code, error.message, details opcionales y request_id. Las asignaciones comunes son 400 parámetros inválidos, 401 key ausente o incorrecta, 404 recurso inexistente, 409 conflicto de estado o modelo, 413 límite de tamaño, 422 imagen inválida o rostro no utilizable, 500 error inesperado y 503 timeout o indisponibilidad del runtime/índice.

GET se puede reintentar con seguridad. Reintenta 429 y 503 transitorios con backoff exponencial acotado y jitter; un 4xx de validación exige cambiar la petición. Tras un fallo de transporte, crear Person o FaceSample queda en estado ambiguo: lee primero el ID que proporcionó el cliente. Si un 503 de registro contiene write_committed: true, la escritura ya está en SQLite; no reintentes a ciegas, lee antes la persona.

Un Monitor es una tarea de reconocimiento RTSP del servidor cuya configuración se guarda en SQLite. Si está enabled se reanuda tras reiniciar el Server y sigue activo al cerrar el navegador. El decoder conserva solo el frame más reciente, de modo que una inferencia lenta reduce la frecuencia efectiva en lugar de acumular retraso. match_threshold: null hereda el threshold de la Collection.

La preview está desactivada deliberadamente por defecto y el reconocimiento no depende de ella. Al activarla, /preview.mjpeg transmite frames JPEG sin anotación y el cliente dibuja cajas usando /state. Nunca pongas la API key en la URL de preview. Consulta /events con su cursor opaco para eventos enter, exit, error y recovery, tratando explícitamente truncated y stream_reset.

Persiste /data, monta /models en solo lectura y respalda SQLite junto con el crop storage configurado mientras las escrituras estén detenidas o mediante un snapshot seguro para SQLite. Trata el volumen y las copias como datos biométricos. Termina HTTPS en un reverse proxy de confianza, permite solo los orígenes CORS necesarios y aplica límites de tasa, cuerpo y tiempo en el borde. Nunca expongas una evaluación con autenticación desactivada.

El código fuente del Server y el SDK de Python usan licencia MIT; los modelos quedan expresamente fuera de ella. La imagen del contenedor no incluye modelos. El instalador muestra su licencia y verify comprueba identidad del paquete, licencia firmada, vigencia y autorización. Los paquetes públicos de InsightFace, incluido buffalo_l, suelen limitarse a investigación académica no comercial salvo licencia comercial independiente.