Documentation API - Système de Reconnaissance Faciale
https://casier-ai.jconsultmy.com/
Toutes les requêtes API nécessitent le header suivant :
x-api-key: APK-JCONSULT-DEV
APK-JCONSULT-DEV est pour le développement uniquement.import requests
# Configuration
url = "https://casier-ai.jconsultmy.com/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)."}
curl -X POST https://casier-ai.jconsultmy.com/api/add \ -H "x-api-key: APK-JCONSULT-DEV" \ -F "nom=Jean Dupont" \ -F "image=@photo.jpg"
| 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 |
Description : Enregistre un nouveau visage dans la base de données avec extraction automatique de la signature faciale (vecteur 512-D).
| Header | Type | Valeur |
|---|---|---|
x-api-key |
string | APK-JCONSULT-DEV Requis |
Content-Type |
string | multipart/form-data Auto |
| 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 |
method |
string | Choix de l'algorithme récupéré via `method` (deepface ou mediapipe) - par défaut deepface | Optionnel |
{
"success": true,
"message": "Jean Dupont ajouté (Visage)."
}
{
"success": false,
"message": "Image non décodable. Format non supporté ou fichier corrompu.",
"error": "Image non décodable"
}
{
"success": false,
"message": "Image trop petite. Utilisez une photo de meilleure qualité (min 80x80px).",
"error": "Image trop petite"
}
{
"success": false,
"message": "Aucun visage détecté sur la photo. Assurez-vous que le visage est bien visible, net, et de face.",
"error": "Aucun visage détecté"
}
{
"success": false,
"message": "Erreur lors de l'enregistrement du visage.",
"error": "Erreur interne"
}
curl -X POST https://casier-ai.jconsultmy.com/api/add \ -H "x-api-key: APK-JCONSULT-DEV" \ -F "nom=Jean Dupont" \ -F "image=@photo_jean.jpg"
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.
| Header | Type | Valeur |
|---|---|---|
x-api-key |
string | APK-JCONSULT-DEV Requis |
Content-Type |
string | multipart/form-data Auto |
| Paramètre | Type | Description | Contraintes |
|---|---|---|---|
image |
file | Photo du visage à identifier (JPG, PNG, BMP) Min: 640x480px | Max: 10MB |
Obligatoire |
method |
string | `deepface` ou `mediapipe` (défaut : deepface), il suffit d'ajouter un champ `method` dans le form-data | Optionnel |
{
"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% |
{
"success": true,
"result": null,
"message": "Aucune correspondance trouvée dans la base."
}
{
"success": false,
"message": "Erreur lors de l'analyse du visage : la photo ne contient pas de visage détectable..."
}
curl -X POST https://casier-ai.jconsultmy.com/api/search \ -H "x-api-key: APK-JCONSULT-DEV" \ -F "image=@photo_test.jpg"
Vous pouvez aussi appeler les endpoints JSON suivants en fournissant une chaîne base64 (avec ou sans préfixe data:image/...).
Ajoutez le champ method (`deepface` ou `mediapipe`) dans le payload pour choisir l'algorithme utilisé.
curl -X POST https://casier-ai.jconsultmy.com/api/add-base64 \
-H "x-api-key: APK-JCONSULT-DEV" \
-H "Content-Type: application/json" \
-d '{ "nom": "Jean Dupont", "image": "data:image/png;base64,iVBORw0KGgoAAAANS..." }'
curl -X POST https://casier-ai.jconsultmy.com/api/search-base64 \
-H "x-api-key: APK-JCONSULT-DEV" \
-H "Content-Type: application/json" \
-d '{ "image": "data:image/png;base64,iVBORw0KGgoAAAANS..." }'
| 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) |
Description : Renvoie la liste des noms enregistrés filtrée par méthode (`deepface` ou `mediapipe`).
Option : `?method=all` pour obtenir les deux pipelines dans la même réponse.
| Header | Type | Valeur |
|---|---|---|
x-api-key |
string | APK-JCONSULT-DEV Requis |
| Paramètre | Type | Description |
|---|---|---|
method |
string | `deepface`, `mediapipe` ou `all` (défaut : `deepface`) |
{
"success": true,
"method": "deepface",
"count": 3,
"people": ["Jean Dupont","Fatou Mbaye","..."]
}
Description : Page web qui liste les visages enregistrés avec filtres `deepface`, `mediapipe` ou toutes les méthodes.
Utilisez le sélecteur pour choisir la méthode, puis le tableau affiche les noms et leur position.
JC_API_KEYAPK-JCONSULT-DEVapp.py ligne 11# 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è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 |
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 |
| 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) |
DATABASE_URL |
string | postgresql://postgres:postgres@localhost:5432/jc_detect | Connexion PostgreSQL (table `personnes`) |
| 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) |
PostgreSQL |
database | PostgreSQL 15+ | Table personnes (id, nom, date_ajout) via DATABASE_URL |
tar -czf backup.tar.gz visages.index mapping.pkl et pg_dump --format=custom --file metadata.dump $DATABASE_URL
| 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 |
| 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 | https://casier-ai.jconsultmy.com/ | Adresse d'écoute (host:port) |
memory_limit |
string | 4G | Limite mémoire Docker (RAM) |
cpus |
string | 2 | Limite CPU Docker (cores) |
Testez les endpoints API directement depuis votre navigateur sans installer d'outils externes.
| Message | Cause probable | Solution |
|---|---|---|
| Image non décodable | Format non supporté, fichier corrompu | Utiliser JPG/PNG, vérifier l'intégrité du fichier |
| Image trop petite | Photo < 80x80px | Utiliser une photo de meilleure qualité |
| Aucun visage détecté | Visage mal cadré, flou, profil, accessoires | Photo nette, visage de face, sans accessoires |
| Erreur interne | Problème logiciel ou serveur | Vérifier les logs, contacter le support |
method (deepface ou mediapipe) dans le formulaire pour tester une autre méthode de détection si l’une échoue.method=mediapipe
method pour tester avec mediapipe si deepface échoue (et inversement)JConsult Detect - Système de reconnaissance faciale © 2026
← Retour à l'accueil | Version 1.0.0 | ArcFace + FAISS