Sentinel API v1

最初のAPI呼び出しから本番運用まで

Model providers

Edge-first, not edge-only

Stream capture, RTSP credentials, local detection and tracking, event state, and retained evidence stay at the edge. The semantic VLM can run on the same host, a customer-private endpoint, or an explicitly selected cloud service.

local_*

Local VLM

Current Docker profiles use NVIDIA GPU/vLLM; inference images stay on-site.

private

Private OpenAI-compatible

Connect to a customer-controlled LAN, VPN, or datacenter endpoint.

gemini

Optional cloud

Only bounded images selected by the monitor go to the explicitly configured provider.

cloud_gemini is an explicitly selected, server-owned profile used end to end by durable Monitors. Put it into production only after GET /v1/system/models reports provider=gemini, POST /v1/system/models/test succeeds, and representative-image acceptance passes. When enabled, bounded inference images and provider-required metadata leave the Edge; there is no silent fallback.

Switch from mock to a real provider

Quickstart has already created deploy/api/.env with private API and Webhook secrets. Bootstrap intentionally will not overwrite it. Preserve those secrets and merge only the selected provider fields from deploy/api/profiles into the existing .env; never replace the whole file with an example fragment.

docker compose config --quiet

# local_* only: start the pinned GPU provider and recreate API
docker compose --profile gpu up -d --build --force-recreate api vllm

# private/cloud: recreate API after its endpoint/key fields are configured
docker compose up -d --build --force-recreate api

# verify the selected provider before adding a camera
GET  /v1/system/models
POST /v1/system/models/test

If readiness remains 503, inspect checks.inference_provider and the model test's model_unavailable response. Never switch back to mock and treat it as a production result.

Inspect the active data boundary

GET  /v1/system/models
POST /v1/system/models/test

Responses expose provider kind, a sanitized target, profile, data boundary, whether a credential is configured, and the currently available readiness value—never the key. The test operation returns provider/probe status or a structured model_unavailable error.

Private OpenAI-compatible endpoint

SENTINEL_INFERENCE_PROVIDER=vllm
SENTINEL_VLLM_BASE_URL=http://gpu.internal:8080/v1
SENTINEL_VLLM_MODEL=your-vision-model
SENTINEL_VLLM_API_KEY=<server-side-secret>

Provider tests validate a real model catalog or inference response shape; an unrelated HTTP 200 page is not healthy. Provider unavailability must never be interpreted as a safe visual result.