JConsult Detect

Documentation API - Système de Reconnaissance Faciale

Version 1.0.0 ArcFace + FAISS Python 3.10

Démarrage rapide

Base URL

https://casier-ai.jconsultmy.com/

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 = "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)."}

Exemple cURL

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"

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
method string Choix de l'algorithme récupéré via `method` (deepface ou mediapipe) - par défaut deepface Optionnel

Réponse succès (200 OK)

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

Réponses erreur détaillées

{
    "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"
}
                        

Exemple complet

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"
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
method string `deepface` ou `mediapipe` (défaut : deepface), il suffit d'ajouter un champ `method` dans le form-data Optionnel

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 https://casier-ai.jconsultmy.com/api/search \
  -H "x-api-key: APK-JCONSULT-DEV" \
  -F "image=@photo_test.jpg"

Envoyer une image en base64 (JSON)

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..." }'

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)
GET /api/list-personnes

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.

Headers requis

Header Type Valeur
x-api-key string APK-JCONSULT-DEV Requis

Paramètres query

Paramètre Type Description
method string `deepface`, `mediapipe` ou `all` (défaut : `deepface`)

Réponse

{
  "success": true,
  "method": "deepface",
  "count": 3,
  "people": ["Jean Dupont","Fatou Mbaye","..."]
}
GET /visages

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.

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)
DATABASE_URL string postgresql://postgres:postgres@localhost:5432/jc_detect Connexion PostgreSQL (table `personnes`)

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)
PostgreSQL database PostgreSQL 15+ Table personnes (id, nom, date_ajout) via DATABASE_URL
Sauvegarde critique
Ces 3 éléments contiennent toutes vos données. Sauvegardez-les régulièrement !
tar -czf backup.tar.gz visages.index mapping.pkl et pg_dump --format=custom --file metadata.dump $DATABASE_URL

⚡ 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 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)

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

Tableau des erreurs fréquentes
MessageCause probableSolution
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
Exemples de photos acceptées :
• Visage de face, bien éclairé, net, sans accessoires
• Résolution recommandée : 640x480px ou plus
• Format JPG ou PNG

Exemples de photos refusées :
• Visage de profil, incliné ou partiellement caché
• Lunettes de soleil, masques, objets devant le visage
• Photo floue, sombre, surexposée ou très compressée
• Taille < 80x80px ou > 10MB
Debug & logs :
• En cas d’erreur persistante, consultez les logs serveur pour plus de détails.
• Les messages d’erreur retournés par l’API sont précis et indiquent la cause.
• Contactez le support si le problème n’est pas résolu.
Astuce : Utilisez le paramètre method (deepface ou mediapipe) dans le formulaire pour tester une autre méthode de détection si l’une échoue.
Exemple : method=mediapipe
Recommandations pour de bons résultats :

À faire :
• Photo de face, bien éclairée, nette, sans accessoires gênants
• Résolution recommandée : 640x480 pixels (minimum accepté : 80x80px)
• Formats acceptés : JPG, PNG, BMP
• Arrière-plan neutre de préférence
• Visage bien visible et centré

À éviter :
• Visages de profil, inclinés ou partiellement cachés
• Lunettes de soleil, masques, objets devant le visage
• Photos floues, sombres, surexposées ou très compressées
• Éclairage insuffisant ou contre-jour
• Taille de fichier > 10 MB

En cas d’erreur :
• Vérifiez que le visage est bien visible, de face, et occupe une partie significative de la photo
• Essayez une autre photo avec une meilleure qualité ou un autre angle
• Utilisez le paramètre method pour tester avec mediapipe si deepface échoue (et inversement)
• Consultez les logs serveur pour plus de détails en cas de problème récurrent

JConsult Detect - Système de reconnaissance faciale © 2026

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