OpenNVR

API Reference

OpenNVR breaks its architecture into isolated Clean Architecture microservices. The most critical component is the AI Adapter, a perfectly isolated standalone FastAPI application running on Port 9100.

🌐 The AI Adapter API Engine

Every AI Adapter runs its own native FastAPI web server. By default, it exposes these ports on .localhost, allowing the OpenNVR Kai-C brain to pipe video chunks into it flawlessly.

However, because it exposes standard REST APIs, it is entirely open for third-party consumption.

If you expose this API port globally across your public IP or local network, any generic application—or future autonomous AI Agents we are introducing to OpenNVR—can consume this port directly to execute their own independent visual analysis tasks using the same VRAM-optimized lazy-loading hardware pipeline.

Core System Endpoints (Port 9100)

  • GET /health : Verifies if the inference server is responsive. Returns complete system hardware heuristics (RAM, CPU cores, GPU VRAM) and details exactly which models are loaded securely.
  • GET /capabilities : Returns an array of logical tasks the environment is dynamically ready to process based on active configuration mappings (e.g., ["person_counting", "face_detection", "scene_description"]).
  • GET /adapters : Auto-discovers and lists every physical model adapter connected and enabled within the microservice.

The Unified Inference Interfaces

POST /infer

The single, decoupled workhorse endpoint for executing any analytical reasoning logic. You merely pass a registered task, and the architecture dynamically routes it, lazy-loading heavy constraints instantly.

Requesting Embedded Tracking (e.g., YOLO + ByteTrack):

curl -X POST "http://localhost:9100/infer" \
     -H "Content-Type: application/json" \
     -d '{
        "task": "person_counting",
        "data": {
            "frame": { "uri": "opennvr://frames/camera_0/latest.jpg" }
        }
     }'

Response 200 OK:

{
  "task": "person_counting",
  "count": 3,
  "confidence": 0.89,
  "detections": [
    {
      "bbox": [100, 200, 50, 150],
      "confidence": 0.95,
      "track_id": 1
    },
    ...
  ],
  "latency_ms": 45
}

Requesting Face Analysis (e.g., InsightFace):

curl -X POST "http://localhost:9100/infer" \
     -H "Content-Type: application/json" \
     -d '{
        "task": "face_detection",
        "data": {
            "frame": { "uri": "opennvr://frames/camera_0/person.jpg" }
        }
     }'

Response 200 OK:

{
  "faces": [
    {
      "bbox": [250, 150, 310, 240],
      "confidence": 0.99,
      "landmarks": [[265, 180], [290, 180], ...],
      "age": 28,
      "gender": "M"
    }
  ],
  "face_count": 1,
  "latency_ms": 120
}

Requesting Multi-Modal Scene Cognition (e.g., BLIP Models):

curl -X POST "http://localhost:9100/infer" \
     -H "Content-Type: application/json" \
     -d '{
        "task": "scene_description",
        "data": { 
           "frame": { "uri": "opennvr://camera_0/event_trigger.jpg" }
        }
     }'

Response 200 OK:

{
  "task": "scene_description",
  "caption": "a man in a red shirt walking a dog in a park",
  "model_id": "Salesforce/blip-image-captioning-base",
  "latency_ms": 350
}

POST /pipeline/run

An advanced aggregation protocol explicitly built for complex AI agent sequencing. You can pass sequential arrays of tasks to be processed on a solitary frame, saving network hops.

curl -X POST "http://localhost:9100/pipeline/run" \
     -H "Content-Type: application/json" \
     -d '{
        "steps": ["person_detection", "scene_description"],
        "data": { "frame": {"uri": "opennvr://camera_warehouse/dark_corner.jpg"} }
     }'

🎥 Core NVR Content APIs (Port 8000)

The primary NVR FastAPI backend controls the PostgreSQL database, user administration, and accessing physical network MP4 files. All requests against Port 8000 mandate strict JWT Bearer authentication headers natively retrieved upon user login.

  • GET /api/v1/cameras : Fetch the topology of all connected NVR camera endpoints.
  • GET /api/v1/recordings/{camera_id}?start_unix=X&end_unix=Y : Fetch an array of historical MP4 chunks available for timeline processing.
  • GET /api/v1/events/latest : Fetch the latest AI incident logs systematically tracked and permanently stored in the Postgres tables.
  • GET /api/v1/events/stream : Real-time Server-Sent Events (SSE) and WebSocket stream for live AI inference overlays and instant notifications.