🔍 JConsult Detect

Documentation API - Système de Reconnaissance Faciale

Version 1.0.0 ArcFace + FAISS Python 3.10

🚀 Démarrage rapide

Base URL

http://localhost:5000

🔑 Authentification

Toutes les requêtes API nécessitent le header suivant :

x-api-key: APK-JCONSULT-DEV
⚠️ IMPORTANT - Clé API par défaut
La clé APK-JCONSULT-DEV est pour le développement uniquement.
En production, vous DEVEZ utiliser une clé sécurisée personnalisée !

🎯 Exemple Python minimal

import requests

# Configuration
url = "http://localhost:5000/api/add"
headers = {"x-api-key": "APK-JCONSULT-DEV"}

# Enregistrer un visage
files = {"image": open("photo.jpg", "rb")}
data = {"nom": "Jean Dupont"}
response = requests.post(url, headers=headers, files=files, data=data)

print(response.json())
# {"success": true, "message": "Jean Dupont ajouté (Visage)."}

🎯 Exemple cURL

curl -X POST http://localhost:5000/api/add \
  -H "x-api-key: APK-JCONSULT-DEV" \
  -F "nom=Jean Dupont" \
  -F "image=@photo.jpg"

📊 Stack Technique

Composant Technologie Version Rôle
Framework Web Flask 2.3.2 API REST et serveur web
Modèle Facial ArcFace (DeepFace) 0.0.98 Extraction vecteurs 512-D
Recherche FAISS 1.13.2 Similarité cosinus ultra-rapide
Détection OpenCV 4.8.1 Détection de visages
Base de données SQLite + FAISS 3.x Métadonnées + vecteurs

📡 Documentation des Endpoints

POST /api/add

Description : Enregistre un nouveau visage dans la base de données avec extraction automatique de la signature faciale (vecteur 512-D).

🔑 Headers requis

Header Type Valeur
x-api-key string APK-JCONSULT-DEV Requis
Content-Type string multipart/form-data Auto

📥 Paramètres (form-data)

Paramètre Type Description Contraintes
nom string Nom complet de la personne à enregistrer Obligatoire
image file Photo du visage (JPG, PNG, BMP)
Min: 640x480px | Max: 10MB		 Obligatoire

✅ Réponse succès (200 OK)

{
  "success": true,
  "message": "Jean Dupont ajouté (Visage)."
}

❌ Réponse erreur (200 OK - success: false)

{
  "success": false,
  "message": "Erreur lors de l'enregistrement du visage : Face could not be detected...",
  "error": "Face could not be detected"
}

💻 Exemple complet

curl -X POST http://localhost:5000/api/add \
  -H "x-api-key: APK-JCONSULT-DEV" \
  -F "nom=Jean Dupont" \
  -F "image=@photo_jean.jpg"
POST /api/search

Description : Identifie une personne à partir d'une photo en comparant avec la base de données vectorielle. Retourne le nom et le score de confiance.

🔑 Headers requis

Header Type Valeur
x-api-key string APK-JCONSULT-DEV Requis
Content-Type string multipart/form-data Auto

📥 Paramètres (form-data)

Paramètre Type Description Contraintes
image file Photo du visage à identifier (JPG, PNG, BMP)
Min: 640x480px | Max: 10MB		 Obligatoire

✅ Réponse (personne identifiée)

{
  "success": true,
  "result": "Jean Dupont",
  "score": 98.5
}
Champ Type Description
success boolean Statut de la requête
result string Nom de la personne identifiée
score float Score de confiance (0-100) - Seuil: 65%

❓ Réponse (personne inconnue)

{
  "success": true,
  "result": null,
  "message": "Aucune correspondance trouvée dans la base."
}

❌ Réponse (erreur)

{
  "success": false,
  "message": "Erreur lors de l'analyse du visage : la photo ne contient pas de visage détectable..."
}

💻 Exemple complet

curl -X POST http://localhost:5000/api/search \
  -H "x-api-key: APK-JCONSULT-DEV" \
  -F "image=@photo_test.jpg"

📊 Codes de réponse HTTP

Code HTTP Signification Description
200 OK Requête traitée avec succès (vérifier success dans le JSON)
401 Unauthorized Clé API invalide, manquante ou incorrecte dans le header x-api-key
400 Bad Request Paramètres manquants, invalides ou malformés
500 Internal Error Erreur interne du serveur (vérifier les logs)

⚙️ Paramètres et Configuration

🔑 Configuration de la clé API

Variable d'environnement : JC_API_KEY
Valeur par défaut : APK-JCONSULT-DEV
Fichier : app.py ligne 11
Type : string

Comment changer la clé API

# Linux/macOS
export JC_API_KEY="votre-cle-secrete-64-caracteres-minimum"

# Windows
set JC_API_KEY=votre-cle-secrete-64-caracteres-minimum

# Docker (.env ou docker-compose.yml)
JC_API_KEY=votre-cle-secrete-64-caracteres-minimum

🎯 Paramètres de Reconnaissance Faciale

Paramètre Type Valeur Localisation Description
SEUIL_RECONNAISSANCE float 0.65 engine.py:65 Seuil de reconnaissance (0.0 - 1.0)
Plus haut = plus strict
model_name string ArcFace engine.py:20 Modèle d'extraction de signature faciale
detector_backend string opencv engine.py:23 Backend de détection de visages
enforce_detection boolean True engine.py:22 Forcer la détection (erreur si aucun visage)
align boolean True engine.py:24 Aligner les visages avant extraction
DIMENSION integer 512 database.py:9 Dimension des vecteurs faciaux (embeddings)
API_KEY string APK-JCONSULT-DEV app.py:11 Clé d'authentification API
UPLOAD_FOLDER string uploads app.py:7 Répertoire des images temporaires

📈 Calibration du seuil de reconnaissance

Le seuil (SEUIL_RECONNAISSANCE) détermine la sensibilité du système. Modifier dans engine.py ligne 65 :

SEUIL_RECONNAISSANCE = 0.65  # Valeur actuelle (recommandée)
Plage Type Sécurité Comportement
0.30 - 0.40 float Souple Reconnaissance large, risque élevé de faux positifs
0.40 - 0.50 float Équilibrée Bon compromis précision/rappel (usage général)
0.60 - 0.70 float Stricte Haute sécurité, peu de faux positifs ✅ Recommandé
> 0.70 float Très stricte Ultra-sécurisé, risque de faux négatifs

🌐 Variables d'environnement système

Variable Type Défaut Description
JC_API_KEY string APK-JCONSULT-DEV Clé d'authentification API (⚠️ changer en prod)
FLASK_APP string app.py Point d'entrée de l'application Flask
FLASK_ENV string production Environnement (development | production)
PYTHONUNBUFFERED string 1 Logs en temps réel (0 = bufferisé, 1 = immédiat)

📁 Fichiers de données

Fichier Type Format Contenu
visages.index binary FAISS Index vectoriel (embeddings 512-D normalisés L2)
mapping.pkl pickle Python list Mapping ID→Nom (liste ordonnée synchronisée avec FAISS)
donnees.db database SQLite Métadonnées (table: personnes avec id, nom, date_ajout)
⚠️ Sauvegarde critique
Ces 3 fichiers contiennent toutes vos données. Sauvegardez-les régulièrement !
tar -czf backup.tar.gz visages.index mapping.pkl donnees.db

⚡ Performances système

Opération Type retour Temps moyen Notes
Extraction signature (1er appel) array[512] ~1-2 secondes Chargement des modèles IA en mémoire
Extraction signature (suivants) array[512] ~0.3-0.5 sec Modèles déjà en cache
Recherche FAISS (1K visages) int, float < 0.01 seconde Recherche vectorielle ultra-rapide ⚡
Recherche FAISS (10K visages) int, float < 0.05 seconde Temps de recherche quasi-constant
Détection visage boolean ~0.1-0.2 sec OpenCV Cascade Classifier

🐳 Configuration Docker

Paramètre Type Valeur Description
workers integer 4 Nombre de processus Gunicorn parallèles
timeout integer 120 Timeout requête en secondes (important IA)
bind string 0.0.0.0:5000 Adresse d'écoute (host:port)
memory_limit string 4G Limite mémoire Docker (RAM)
cpus string 2 Limite CPU Docker (cores)

🧪 Console de test interactive

Testez les endpoints API directement depuis votre navigateur sans installer d'outils externes.

📥 Endpoint : POST /api/add

🔍 Endpoint : POST /api/search

💡 Recommandations pour de bons résultats :

✅ À faire :
• Photo de face, bien éclairée et nette
• Résolution minimum : 640x480 pixels
• Formats acceptés : JPG, PNG, BMP
• Arrière-plan neutre de préférence
• Visage bien visible et centré

❌ À éviter :
• Visages de profil ou partiellement cachés
• Lunettes de soleil, masques, chapeaux
• Photos floues ou très compressées
• Éclairage insuffisant ou contre-jour
• Taille de fichier > 10 MB

JConsult Detect - Système de reconnaissance faciale © 2026

← Retour à l'accueil | Version 1.0.0 | ArcFace + FAISS