Server REST API integrieren

Rufen Sie zuerst GET /v1/health auf. Dieser endpoint ist immer öffentlich und meldet sowohl readiness als auch auth_enabled. Ist auth_enabled true, benötigen alle anderen endpoints Authorization: Bearer <api_key>. Bei deaktivierter Authentifizierung muss der Authorization header vollständig entfallen; senden Sie keinen leeren Header. Der erste Befehlsblock zeigt genau diese unauthentifizierte Form, der zweite gilt für authentifizierte Deployments.

Die API verwendet snake_case JSON und multipart/form-data für Bilder. Jede Antwort trägt einen x-request-id UUID header; JSON bodies wiederholen ihn als request_id. Detection- und Qualitätssignale liegen zwischen 0.0 und 1.0, die recognition similarity ist jedoch der rohe Cosinuswert in [-1.0, 1.0] und keine Wahrscheinlichkeit. threshold akzeptiert das inklusive Intervall [0.0, 1.0], hat den Standardwert 0.4, und similarity >= threshold bedeutet eine Übereinstimmung.

Eine Collection ist eine isolierte Identitätsdatenbank und zugleich ein Deployment-Vertrag. Bei der Erstellung bindet sie model ID, version, bundle digest, embedding dimension, preprocessing version, detection profile und exact-search profile des aktiven Modells. Die zurückgegebene embedding_contract_id ist undurchsichtig: für trusted external enrollment kopieren, niemals selbst konstruieren.

Beginnen Sie mit threshold 0.4 und kalibrieren Sie ihn anschließend auf repräsentativen Validierungsdaten. Collection-Antworten zeigen detection_revision und die aufgelösten Sucheinstellungen. Spätere Änderungen am detection profile gelten für neue Requests, extrahieren bestehende FaceSamples aber nicht erneut. Die Search-Profile führen eine exakte lineare Suche aus; niedrigere Präzision approximiert FP32-Cosinuswerte, ist aber kein ANN-Index.

Enrollment verwendet multipart und kann mehrere Bilder in einem Request aufnehmen. review_mode=off folgt der Gesichtsauswahl der Collection; standard verlangt genau ein nutzbares Gesicht und prüft konfigurierte Größe, Konfidenz, Qualität und Pose; strict ergänzt den Vergleich von Similarity innerhalb und außerhalb der Person. Ein Batch kann mit HTTP 201 teilweise erfolgreich sein, deshalb müssen faces und rejected_images geprüft werden.

Search wählt mit dem Collection-Profil ein query face, vergleicht es mit jedem aktiven FaceSample und verwendet für jede Person deren höchsten Sample-Score. Nur Ergebnisse ab dem effektiven threshold werden in absteigender Similarity zurückgegeben. Testen Sie mit einem anderen Bild als bei der Registrierung.

Detect liefert alle nutzbaren Gesichter nach absteigender Fläche mit Pixel- und normalisierten Boxen, fünf Landmarks, Detector-Konfidenz und lokalen Qualitätssignalen. Es gibt weder Embeddings zurück noch persistiert es Daten. Übergeben Sie collection_id, wenn statt des unveränderlichen Systemprofils das detection profile einer Collection gelten soll.

Compare wählt jeweils ein Gesicht aus source und target, berechnet die rohe Cosinus-Similarity und ermittelt matched mit dem effektiven threshold. Similarity kann negativ sein und darf nie als Confidence-Prozentwert dargestellt werden. Fehlt in einem Bild ein nutzbares Gesicht, folgt 422 face_not_found.

Installieren Sie den Client direkt aus diesem Checkout. Er basiert auf httpx, enthält keine Inference Runtime und akzeptiert Bildpfade, Bytes oder binäre file-like objects. Der Standard-Timeout von 65 Sekunden liegt knapp über der 60-Sekunden-Deadline des Servers.

Das Beispiel nutzt die CPU-Adresse aus dem User Guide auf Port 18097 und einen authentifizierten Server. Ist die Authentifizierung aus, erzeugen Sie Client("http://localhost:18097") ohne api_key, damit kein Authorization header gesendet wird. Der Client bietet außerdem create_monitor, update_monitor, monitor_state und cursor-basiertes monitor_events.

Fehler verwenden ein gemeinsames JSON envelope mit error.code, error.message, optionalen details und request_id. Typische Zuordnungen sind 400 für ungültige Parameter, 401 für fehlenden oder falschen key, 404 für fehlende Ressourcen, 409 für Zustands- oder Modellkonflikte, 413 für Größenlimits, 422 für ungültige Bilder oder unbrauchbare Gesichter, 500 für unerwartete Fehler und 503 für Timeout oder eine nicht verfügbare Runtime bzw. einen Index.

GET darf sicher wiederholt werden. Wiederholen Sie 429 und vorübergehende 503 mit begrenztem exponential backoff und jitter; bei Validierungs-4xx muss der Request geändert werden. Nach einem Transportfehler ist die Erstellung von Person oder FaceSample mehrdeutig: lesen Sie zuerst die vom Client vorgegebene Ressourcen-ID. Enthält ein Registrierungs-503 write_committed: true, steht der Write bereits in SQLite. Nicht blind wiederholen, sondern zuerst die Person lesen.

Ein Monitor ist ein serverseitiger RTSP-Erkennungsjob, dessen Konfiguration in SQLite liegt. Ein aktivierter Job wird nach einem Serverneustart fortgesetzt und läuft unabhängig vom Browser. Der Decoder hält nur den neuesten Frame; langsame Inferenz senkt daher die effektive Rate, statt veraltete Frames aufzustauen. match_threshold: null übernimmt den Collection threshold.

Die Vorschau ist absichtlich standardmäßig aus und für die Erkennung nicht erforderlich. Wenn aktiviert, streamt /preview.mjpeg rohe, unbeschriftete JPEG-Frames; Clients zeichnen mit /state die Boxen. Einen API key niemals in die Preview-URL schreiben. /events mit dem undurchsichtigen Cursor auf enter-, exit-, error- und recovery-Ereignisse abfragen und truncated bzw. stream_reset explizit behandeln.

Persistieren Sie /data, mounten Sie /models read-only und sichern Sie SQLite zusammen mit konfiguriertem Crop-Speicher bei gestoppten Writes oder mit einem SQLite-sicheren Snapshot. Volume und Backups sind als biometrische Daten zu schützen. HTTPS an einem vertrauenswürdigen Reverse Proxy terminieren, nur notwendige CORS origins erlauben und am Edge Rate-, Body- und Zeitlimits setzen. Eine Evaluierungsinstanz ohne Authentifizierung darf nicht ins Netz.

Der Server-Quellcode und das Python SDK stehen unter MIT; Modelle sind ausdrücklich nicht von dieser Lizenz umfasst. Das Container-Image enthält keine Modelle. Der Installer zeigt die Modelllizenz, verify prüft Paketidentität, signierte Lizenz, Gültigkeit und aktuelle Autorisierung. Öffentliche InsightFace-Modellpakete wie buffalo_l sind üblicherweise nur für nichtkommerzielle akademische Forschung freigegeben, solange keine separate kommerzielle Lizenz vorliegt.