Référence API

Vue d'Ensemble

Base URL : http://localhost:8000

Authentification : Header X-API-Key ou Basic Auth

Authentification

Avec API Key

bash

curl -H "X-API-Key: your_api_key" http://localhost:8000/cameras

Avec Basic Auth

bash

curl -u username:password http://localhost:8000/cameras

Obtenir une Clé API

bash

curl -X POST http://localhost:8000/auth/keys \
  -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
  -H "Content-Type: application/json" \
  -d '{"name": "my_app", "ttl_days": 365}'

Réponse :

json

{
  "key": "sk-0x7f8a9b1c2d3e4f5g6h7i",
  "created_at": "2025-01-15T10:30:00Z",
  "expires_at": "2026-01-15T10:30:00Z"
}

Endpoints

1. Health Check

GET /health

Vérifier l'état du système.

Réponse (200 OK)

json

{
  "status": "healthy",
  "components": {
    "api": "ok",
    "redis": "ok",
    "ollama": "ok",
    "database": "ok"
  },
  "timestamp": "2025-01-15T10:30:00Z"
}

2. Lister les Caméras

GET /cameras

Récupérer la liste de toutes les caméras.

Paramètres Query

Param	Type	Description
`enabled`	boolean	Filtrer par état (optionnel)

Réponse (200 OK)

json

{
  "cameras": [
    {
      "id": "cam_001",
      "name": "Entrée Principal",
      "rtsp_url": "rtsp://user:pass@192.168.1.100:554/Streaming/Channels/101",
      "enabled": true,
      "zones": [
        {
          "name": "Zone Porte",
          "points": [[0, 0], [100, 0], [100, 100], [0, 100]],
          "sensitivity": 0.8
        }
      ],
      "status": "streaming",
      "fps": 25,
      "resolution": "1920x1080"
    }
  ],
  "count": 1
}

3. Récupérer une Caméra

GET /cameras/{id}

Obtenir les détails d'une caméra spécifique.

Paramètres Path

Param	Type	Description
`id`	string	Identifiant caméra (ex: cam_001)

Réponse (200 OK)

json

{
  "id": "cam_001",
  "name": "Entrée Principal",
  "rtsp_url": "rtsp://user:pass@192.168.1.100:554/Streaming/Channels/101",
  "enabled": true,
  "zones": [...],
  "status": "streaming",
  "fps": 25,
  "resolution": "1920x1080",
  "last_frame_timestamp": "2025-01-15T10:30:15Z"
}

4. Créer une Caméra

POST /cameras

Ajouter une nouvelle caméra.

Body

json

{
  "id": "cam_002",
  "name": "Parking",
  "rtsp_url": "rtsp://user:pass@192.168.1.101:554/Streaming/Channels/101",
  "enabled": true,
  "zones": []
}

Réponse (201 Created)

json

{
  "id": "cam_002",
  "name": "Parking",
  "status": "created"
}

5. Mettre à Jour une Caméra

PUT /cameras/{id}

Modifier la configuration d'une caméra.

Body

json

{
  "name": "Parking Sud",
  "enabled": true
}

Réponse (200 OK)

json

{
  "id": "cam_002",
  "name": "Parking Sud",
  "updated_at": "2025-01-15T10:35:00Z"
}

6. Supprimer une Caméra

DELETE /cameras/{id}

Retirer une caméra du système.

Réponse (204 No Content)

7. Lister les Événements

GET /events

Récupérer les alertes détectées.

Paramètres Query

Param	Type	Description
`camera_id`	string	Filtrer par caméra (optionnel)
`limit`	integer	Nombre max résultats (défaut: 50)
`offset`	integer	Pagination (défaut: 0)
`since`	ISO8601	Depuis timestamp (optionnel)

Réponse (200 OK)

json

{
  "events": [
    {
      "uuid": "evt-550e8400-e29b-41d4-a716-446655440000",
      "camera_id": "cam_001",
      "timestamp": "2025-01-15T10:30:45Z",
      "detection_type": "person",
      "confidence": 0.94,
      "photo_url": "/events/550e8400-e29b-41d4-a716-446655440000.jpg",
      "ai_response": "Personne suspecte détectée à l'entrée",
      "alert_sent": true
    }
  ],
  "total": 156,
  "count": 50
}

8. Récupérer un Événement

GET /events/{uuid}

Obtenir les détails complets d'un événement.

Paramètres Path

Param	Type	Description
`uuid`	string	UUID de l'événement

Réponse (200 OK)

json

{
  "uuid": "evt-550e8400-e29b-41d4-a716-446655440000",
  "camera_id": "cam_001",
  "timestamp": "2025-01-15T10:30:45Z",
  "detection_type": "person",
  "confidence": 0.94,
  "photo": "<binary>",
  "ai_response": "Personne suspecte détectée à l'entrée",
  "modules_triggered": ["bytetrack", "pose"],
  "module_results": {
    "bytetrack": {
      "tracks": [
        {
          "track_id": 1,
          "bbox": [100, 150, 200, 400],
          "confidence": 0.95
        }
      ]
    },
    "pose": {
      "keypoints": [...],
      "person_action": "standing"
    }
  },
  "rules_triggered": ["rule_001"],
  "alerts_sent": ["telegram", "email"],
  "user_feedback": null
}

9. Envoyer une Alerte de Test

POST /alert/test

Tester les canaux d'alerte.

Body

json

{
  "channels": ["telegram", "email", "physical"],
  "message": "Test CCTV Smart",
  "photo_path": null
}

Réponse (200 OK)

json

{
  "telegram": {
    "status": "sent",
    "message_id": 12345
  },
  "email": {
    "status": "sent",
    "recipients": 2
  },
  "physical": {
    "status": "triggered",
    "devices": ["siren"]
  }
}

10. Récupérer les Stats Système

GET /system/stats

Statistiques CPU, mémoire, GPU.

Réponse (200 OK)

json

{
  "cpu": {
    "percent": 35.2,
    "cores": 16,
    "temp_celsius": 58
  },
  "memory": {
    "used_gb": 6.4,
    "total_gb": 16,
    "percent": 40
  },
  "gpu": {
    "available": true,
    "model": "NVIDIA RTX 4080",
    "memory_used_gb": 4.2,
    "memory_total_gb": 24,
    "utilization_percent": 65
  },
  "disk": {
    "used_gb": 128,
    "total_gb": 512,
    "percent": 25
  },
  "redis": {
    "connected": true,
    "queue_gemma": 5,
    "queue_modules": 2
  },
  "uptime_hours": 42.5
}

11. Récupérer la Configuration

GET /system/config

Obtenir la configuration active (sections sensibles masquées).

Réponse (200 OK)

json

{
  "system": {
    "name": "CCTV Smart",
    "environment": "production"
  },
  "hardware": {
    "tier": "A",
    "cpu_cores": 16,
    "ram_gb": 16
  },
  "eye": {
    "fps": 1,
    "yolo_model": "yolov8m"
  },
  "modules_enabled": ["bytetrack", "fire_smoke", "ppe"],
  "cameras_count": 4,
  "rules_count": 12
}

12. Déclencher un Module

POST /modules/{name}/trigger

Lancer manuellement un module spécialisé.

Paramètres Path

Param	Type	Description
`name`	string	Nom du module (bytetrack, lpr, ocr, ppe, fire_smoke, pose, hand, gesture)

Body

json

{
  "image_path": "/path/to/frame.jpg",
  "context": {
    "camera_id": "cam_001",
    "timestamp": "2025-01-15T10:30:45Z"
  }
}

Réponse (202 Accepted)

json

{
  "job_id": "job-abc123def456",
  "module": "lpr",
  "status": "queued",
  "queue_position": 3
}

13. Récupérer Résultats Module

GET /modules/jobs/{job_id}

Vérifier l'état et les résultats d'un travail de module.

Réponse (200 OK) — Queued

json

{
  "job_id": "job-abc123def456",
  "status": "processing",
  "progress": 0.35
}

Réponse (200 OK) — Completed

json

{
  "job_id": "job-abc123def456",
  "status": "completed",
  "module": "lpr",
  "results": {
    "plates": [
      {
        "plate": "AB-123-CD",
        "confidence": 0.92,
        "bbox": [100, 50, 300, 150]
      }
    ]
  },
  "processing_time_ms": 1250
}

14. Soumettre un Feedback Utilisateur

POST /events/{uuid}/feedback

Envoyer un retour sur un événement (faux positif, confirmation).

Body

json

{
  "feedback_type": "false_positive",
  "confidence": 0.1,
  "comment": "Ombrage de l'arbre"
}

Réponse (200 OK)

json

{
  "uuid": "evt-550e8400-e29b-41d4-a716-446655440000",
  "feedback_type": "false_positive",
  "timestamp": "2025-01-15T10:35:00Z"
}

15. Logs Système

GET /system/logs

Récupérer les logs d'exécution.

Paramètres Query

Param	Type	Description
`level`	string	Filtrer: DEBUG, INFO, WARNING, ERROR (optionnel)
`limit`	integer	Nombre max lignes (défaut: 100)
`component`	string	Filtrer par composant (optionnel)

Réponse (200 OK)

json

{
  "logs": [
    {
      "timestamp": "2025-01-15T10:35:12Z",
      "level": "INFO",
      "component": "eye.yolo",
      "message": "Detected person at cam_001 confidence=0.94"
    },
    {
      "timestamp": "2025-01-15T10:35:08Z",
      "level": "WARNING",
      "component": "brain.ollama",
      "message": "Queue cctv:queue:gemma is at 48/50 capacity"
    }
  ],
  "count": 2
}

16. Redémarrer le Système

POST /system/restart

Redémarrer CCTV Smart (nécessite auth admin).

Body

json

{
  "graceful": true,
  "timeout_seconds": 30
}

Réponse (202 Accepted)

json

{
  "status": "shutting_down",
  "timeout_seconds": 30,
  "message": "System will restart in 30 seconds"
}

Codes d'Erreur

Code	Message	Cause
400	Bad Request	Paramètre invalide ou format incorrect
401	Unauthorized	Clé API manquante ou invalide
403	Forbidden	Permissions insuffisantes
404	Not Found	Ressource inexistante
409	Conflict	Doublon d'ID ou violation de contrainte
500	Internal Server Error	Erreur serveur
503	Service Unavailable	Redis ou Ollama indisponible

Exemple d'Erreur (400)

json

{
  "error": "invalid_request",
  "message": "Field 'camera_id' is required",
  "timestamp": "2025-01-15T10:30:00Z"
}

Rate Limiting

API Key — 1000 requêtes / 1 heure
Basic Auth — 100 requêtes / 1 heure

Header de Réponse

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1705324200

Webhooks

CCTV Smart peut envoyer des webhooks lors d'événements.

Configuration

yaml

webhooks:
  enabled: true
  endpoints:
    - url: "https://your-app.com/cctv/alert"
      events: ["detection", "alert"]
      auth_type: "bearer"
      token: "${WEBHOOK_TOKEN}"

Payload Exemple (Detection)

json

{
  "event_type": "detection",
  "uuid": "evt-550e8400-e29b-41d4-a716-446655440000",
  "camera_id": "cam_001",
  "detection_type": "person",
  "confidence": 0.94,
  "timestamp": "2025-01-15T10:30:45Z",
  "ai_response": "Personne suspecte détectée"
}

Référence API ​

Vue d'Ensemble ​

Authentification ​

Avec API Key ​

Avec Basic Auth ​

Obtenir une Clé API ​

Endpoints ​

1. Health Check ​

2. Lister les Caméras ​

3. Récupérer une Caméra ​

4. Créer une Caméra ​

5. Mettre à Jour une Caméra ​

6. Supprimer une Caméra ​

7. Lister les Événements ​

8. Récupérer un Événement ​

9. Envoyer une Alerte de Test ​

10. Récupérer les Stats Système ​

11. Récupérer la Configuration ​

12. Déclencher un Module ​

13. Récupérer Résultats Module ​

14. Soumettre un Feedback Utilisateur ​

15. Logs Système ​

16. Redémarrer le Système ​

Codes d'Erreur ​

Rate Limiting ​

Webhooks ​

Configuration ​

Payload Exemple (Detection) ​

Référence API

Vue d'Ensemble

Authentification

Avec API Key

Avec Basic Auth

Obtenir une Clé API

Endpoints

1. Health Check

2. Lister les Caméras

3. Récupérer une Caméra

4. Créer une Caméra

5. Mettre à Jour une Caméra

6. Supprimer une Caméra

7. Lister les Événements

8. Récupérer un Événement

9. Envoyer une Alerte de Test

10. Récupérer les Stats Système

11. Récupérer la Configuration

12. Déclencher un Module

13. Récupérer Résultats Module

14. Soumettre un Feedback Utilisateur

15. Logs Système

16. Redémarrer le Système

Codes d'Erreur

Rate Limiting

Webhooks

Configuration

Payload Exemple (Detection)