Intégrer l’API REST du Server

Appelez d’abord GET /v1/health. Cet endpoint reste public et indique readiness ainsi que auth_enabled. Quand auth_enabled vaut true, tous les autres endpoints exigent Authorization: Bearer <api_key>. Lorsque l’authentification est désactivée, omettez entièrement le header Authorization : n’envoyez pas un header vide. Le premier bloc montre exactement cette forme sans authentification, le second concerne les déploiements authentifiés.

L’API utilise du JSON snake_case et multipart/form-data pour les images. Chaque réponse porte un header UUID x-request-id, repris comme request_id dans les bodies JSON. Les signaux de détection et de qualité vont de 0.0 à 1.0, mais recognition similarity est le cosinus brut dans [-1.0, 1.0], pas une probabilité. threshold accepte l’intervalle inclusif [0.0, 1.0], vaut 0.4 par défaut, et il y a correspondance si similarity >= threshold.

Une Collection est à la fois une base d’identités isolée et un contrat de déploiement. À sa création, elle fixe model ID, version, bundle digest, embedding dimension, preprocessing version, detection profile et exact-search profile du modèle actif. L’embedding_contract_id renvoyé est opaque : copiez-le pour trusted external enrollment, ne le fabriquez jamais.

Commencez avec threshold 0.4, puis calibrez-le sur des données de validation représentatives. Les réponses Collection exposent detection_revision et les paramètres de recherche résolus. Les modifications ultérieures du detection profile s’appliquent aux nouvelles requêtes sans réextraire les FaceSamples existants. Les profils effectuent une recherche exhaustive à plat ; les faibles précisions approchent les cosinus FP32 mais ne sont pas des index ANN.

L’enrôlement est multipart et accepte plusieurs images par requête. review_mode=off suit la stratégie de sélection de la Collection ; standard exige exactement un visage exploitable et applique les contrôles configurés de taille, confiance, qualité et pose ; strict ajoute les comparaisons de similarité intra- et extra-personne. Un lot peut réussir partiellement avec HTTP 201 : vérifiez toujours faces et rejected_images.

Search choisit un query face avec le profil de la Collection, le compare à chaque FaceSample actif et attribue à chaque personne le meilleur score de ses échantillons. Seuls les résultats au-dessus ou égaux au threshold effectif sont renvoyés par similarity décroissante. Validez avec une image différente de celles d’enrôlement.

Detect renvoie tous les visages exploitables par aire décroissante, avec boîtes pixel/normalisées, cinq landmarks, confiance du détecteur et signaux locaux de qualité. Il ne renvoie pas d’embedding et ne persiste rien. Passez collection_id pour employer le detection profile d’une Collection plutôt que le profil système immuable.

Compare sélectionne un visage dans source et target, calcule la similarity cosinus brute et renvoie matched selon le threshold effectif. La similarity peut être négative et ne doit jamais devenir un pourcentage de confiance. Si l’une des images ne contient aucun visage exploitable, la réponse est 422 face_not_found.

Installez le client directement depuis ce checkout. Fondé sur httpx, il n’embarque aucun runtime d’inférence et accepte chemins d’image, bytes ou objets fichier binaires. Son timeout par défaut de 65 secondes dépasse légèrement la deadline serveur de 60 secondes.

L’exemple utilise l’adresse CPU du User Guide sur le port 18097 et un serveur authentifié. Si l’authentification est désactivée, construisez Client("http://localhost:18097") sans api_key afin de ne transmettre aucun Authorization header. Le client expose aussi create_monitor, update_monitor, monitor_state et monitor_events avec cursor.

Les erreurs suivent un envelope JSON commun avec error.code, error.message, details optionnels et request_id. Les correspondances usuelles sont 400 paramètres invalides, 401 key absente/invalide, 404 ressource absente, 409 conflit d’état ou de modèle, 413 limite de taille, 422 image invalide ou visage inutilisable, 500 erreur inattendue et 503 timeout ou runtime/index indisponible.

GET peut être repris sans risque. Réessayez 429 et les 503 transitoires avec exponential backoff borné et jitter ; un 4xx de validation exige de corriger la requête. Après une panne transport, la création Person/FaceSample est ambiguë : lisez d’abord l’ID fourni par le client. Si un 503 d’enrôlement contient write_committed: true, l’écriture existe déjà dans SQLite. Ne réessayez pas aveuglément ; lisez la personne avant de décider.

Un Monitor est une tâche serveur de reconnaissance RTSP dont la configuration est stockée dans SQLite. Une tâche enabled reprend après redémarrage du Server et continue quand le navigateur se ferme. Le decoder ne garde que la dernière frame : une inférence lente réduit le débit effectif au lieu d’accumuler du retard. match_threshold: null hérite du threshold de la Collection.

La preview est volontairement désactivée par défaut et la reconnaissance n’en dépend pas. Activé, /preview.mjpeg transmet des frames JPEG brutes sans annotation ; le client dessine les boîtes avec /state. Ne placez jamais l’API key dans l’URL de preview. Interrogez /events avec son cursor opaque pour les événements enter, exit, error et recovery, et traitez explicitement truncated et stream_reset.

Persistez /data, montez /models en lecture seule et sauvegardez SQLite avec le crop storage configuré, écritures arrêtées ou via un snapshot sûr pour SQLite. Traitez volume et sauvegardes comme données biométriques. Terminez HTTPS sur un reverse proxy de confiance, n’autorisez que les origins CORS nécessaires et ajoutez des limites edge de débit, body et temps. N’exposez jamais une évaluation sans authentification.

Le code source du Server et le SDK Python sont sous licence MIT ; les modèles en sont expressément exclus. L’image du conteneur ne contient aucun modèle. L’installateur affiche la licence modèle et verify contrôle identité du package, licence signée, validité et autorisation. Les packages publics InsightFace, dont buffalo_l, sont généralement réservés à la recherche académique non commerciale sans licence commerciale séparée.