Integrate InsightFace Server REST API

Call GET /v1/health first. It is always public and reports both readiness and auth_enabled. When auth_enabled is true, every other endpoint requires Authorization: Bearer <api_key>. When authentication is disabled, omit the Authorization header completely—do not send an empty header. The first command block shows that exact unauthenticated form; the second is for authenticated deployments.

The API uses snake_case JSON and multipart/form-data for images. Every response has an x-request-id UUID header, and JSON bodies repeat it as request_id. Detection and quality signals use 0.0–1.0, but recognition similarity is the raw cosine value in [-1.0, 1.0], not a probability. Threshold accepts the inclusive range [0.0, 1.0], defaults to 0.4, and a match means similarity >= threshold.

A Collection is an isolated identity database and a deployment contract. At creation, it binds the active model ID, version, bundle digest, embedding dimension, preprocessing version, detection profile, and exact-search profile. The returned embedding_contract_id is opaque: copy it for trusted external enrollment and never construct it yourself.

Start with threshold 0.4, then calibrate it on representative validation data. Collection responses expose a detection_revision and resolved search settings. Later detection-profile changes apply to new requests but do not re-extract existing FaceSamples. Search profiles are exact flat searches; lower-precision profiles approximate FP32 cosine values but are not ANN indexes.

Enrollment is multipart and can accept several images in one request. review_mode=off follows the Collection face-selection strategy; standard requires exactly one usable face and applies configured size, confidence, quality, and pose checks; strict adds within-person versus outside-person similarity checks. A batch may partially succeed with HTTP 201, so always inspect both faces and rejected_images.

Search selects one query face with the Collection profile, compares it with every live FaceSample, assigns each Person that Person's highest sample score, and returns only scores at or above the effective threshold. Results are ordered by similarity. Use a different image from enrollment when validating the flow.

Detect returns all usable faces in descending area order, including pixel and normalized boxes, five landmarks, detector confidence, and local quality signals. It returns neither embeddings nor persisted data. Pass collection_id when you want that Collection's detection profile instead of the immutable system profile.

Compare selects one face from source and target, computes raw cosine similarity, and returns matched using the effective threshold. Similarity can be negative and must never be shown as a confidence percentage. If either image has no usable face, Compare returns 422 face_not_found.

Install the client directly from this checkout. It uses httpx and contains no inference runtime. It accepts image paths, bytes, or binary file-like objects and waits up to 65 seconds by default, slightly longer than the server's 60-second request deadline.

The example uses the user-guide CPU address on port 18097 and an authenticated server. When authentication is disabled, construct Client("http://localhost:18097") without api_key so no Authorization header is sent. The same client also exposes create_monitor, update_monitor, monitor_state, and cursor-based monitor_events.

Errors use one JSON envelope with error.code, error.message, optional details, and request_id. Common mappings are 400 for invalid parameters, 401 for a missing or invalid key, 404 for a missing resource, 409 for state or model conflicts, 413 for size limits, 422 for an invalid image or unusable face, 500 for an unexpected error, and 503 for timeout or runtime/index unavailability.

GET is safe to retry. Retry 429 and transient 503 with bounded exponential backoff and jitter; validation 4xx responses require changing the request. Treat Person or FaceSample creation as ambiguous after a transport failure: first read the client-supplied resource ID. If a registration 503 includes write_committed: true, SQLite already contains the write, so do not blindly retry—read the Person before deciding what to do.

A Monitor is a server-side RTSP recognition task whose configuration is stored in SQLite. An enabled task resumes after Server restart and keeps running when the browser closes. The decoder retains only the newest frame, so slow inference lowers the effective rate instead of creating a stale queue. match_threshold: null inherits the Collection threshold.

Preview is deliberately off by default and recognition does not depend on it. When enabled, /preview.mjpeg streams raw, unannotated JPEG frames; clients use /state to draw boxes. Never put an API key in the preview URL. Poll /events with its opaque cursor for enter, exit, error, and recovery events, and handle truncated or stream_reset explicitly.

Persist /data, mount /models read-only, and back up SQLite plus configured crop storage together while writes are stopped or with a SQLite-safe snapshot. Treat the volume and every backup as biometric data. Terminate HTTPS at a trusted reverse proxy, allow only required CORS origins, add edge rate/body/time limits, and never expose an evaluation deployment with authentication disabled.

The Server source and Python SDK are MIT-licensed; models are expressly not covered by that license. The container image does not include models. The installer displays the model license and verify checks the package identity, signed license, validity dates, and current authorization. Public InsightFace model packages—including buffalo_l—are generally limited to non-commercial academic research unless a separate commercial license has been issued. Code availability or a successful model download is not commercial deployment permission.