InsightFace Server REST API を統合

最初に GET /v1/health を呼び出します。この endpoint は常に公開され、readiness と auth_enabled の両方を返します。auth_enabled が true の場合、その他すべての endpoint に Authorization: Bearer <api_key> が必要です。認証が無効なら Authorization header は完全に省略し、空の header を送ってはいけません。最初の command block が正しい無認証形式、次が認証済み deployment 用です。

API は snake_case JSON を使い、画像は multipart/form-data で受け取ります。全レスポンスに x-request-id UUID header があり、JSON body では request_id として再掲されます。検出・品質 signal は 0.0–1.0 ですが、認識 similarity は [-1.0, 1.0] の raw cosine であり、確率ではありません。threshold は閉区間 [0.0, 1.0]、既定値 0.4 で、similarity >= threshold が match です。

Collection は隔離された identity database であると同時に deployment contract です。作成時に active model の ID、version、bundle digest、embedding dimension、preprocessing version、detection profile、exact-search profile を固定します。返される embedding_contract_id は opaque です。trusted external enrollment ではそのままコピーし、自作してはいけません。

まず threshold 0.4 から始め、代表的な validation data で調整します。Collection response は detection_revision と解決済み search setting を公開します。後の detection-profile 変更は新規 request にのみ作用し、既存 FaceSample は再抽出されません。各 search profile は flat exhaustive search で、低精度 profile は FP32 cosine を近似しますが ANN index ではありません。

Enrollment は multipart で、1 request に複数画像を含められます。review_mode=off は Collection の face-selection strategy を使い、standard は usable face がちょうど1つであることと size、confidence、quality、pose を確認し、strict はさらに within-person と outside-person の similarity を比較します。batch は HTTP 201 で部分成功するため、faces と rejected_images の両方を必ず確認します。

Search は Collection profile で query face を1つ選び、全 live FaceSample と比較し、Person ごとに最も高い sample score を採用します。effective threshold 以上だけを similarity 降順で返します。動作確認には enrollment と別の画像を使ってください。

Detect は usable face を面積降順で返し、pixel/normalized box、5 landmarks、detector confidence、local quality signal を含みます。embedding は返さず、データも保存しません。immutable system profile ではなく Collection の detection profile を使う場合は collection_id を渡します。

Compare は source と target からそれぞれ1顔を選び、raw cosine similarity を計算し、effective threshold に基づく matched を返します。similarity は負にもなり得るため、confidence percentage として表示してはいけません。どちらかに usable face がなければ 422 face_not_found です。

client はこの checkout から直接インストールします。httpx ベースで inference runtime を含まず、画像 path、bytes、binary file-like object を受け取れます。既定 timeout は 65 秒で、Server の 60 秒 request deadline よりわずかに長く設定されています。

例は user guide の CPU address、18097 番ポートと認証済み Server を使います。認証が無効なら api_key を付けず Client("http://localhost:18097") を構築し、Authorization header を送信しないでください。同じ client に create_monitor、update_monitor、monitor_state、cursor-based monitor_events もあります。

Error は error.code、error.message、任意の details、request_id を持つ共通 JSON envelope です。代表的には 400 が invalid parameter、401 が key 不足/不正、404 が resource 不在、409 が state/model conflict、413 が size limit、422 が invalid image/usable face 不在、500 が unexpected error、503 が timeout または runtime/index unavailable です。

GET は安全に再試行できます。429 と一時的 503 は、回数と上限を設けた exponential backoff + jitter で再試行し、validation 4xx は request を直します。transport failure 後の Person/FaceSample creation は結果が曖昧です。まず client が指定した resource ID を読み取ってください。registration の 503 details に write_committed: true がある場合、SQLite への write は完了しています。盲目的に再試行せず Person を読んでから判断します。

Monitor は設定を SQLite に保存する server-side RTSP recognition task です。enabled task は Server restart 後に復帰し、browser を閉じても動作します。decoder は newest frame だけを保持するため、推論が遅い場合は古い frame を溜めず effective rate を下げます。match_threshold: null は Collection threshold の継承です。

Preview は意図的に既定無効で、認識は preview なしでも続きます。有効時の /preview.mjpeg は annotation のない raw JPEG frame を送り、client が /state から box を描きます。API key を preview URL に入れてはいけません。opaque cursor で /events を poll し、enter/exit/error/recovery event と truncated/stream_reset を処理します。

/data を永続化し、/models は read-only mount にします。write を停止するか SQLite-safe snapshot を使って、SQLite と crop storage を一緒に backup します。volume と全 backup を biometric data として扱ってください。trusted reverse proxy で HTTPS を終端し、必要な CORS origin のみ許可し、edge rate/body/time limit を設けます。認証無効の evaluation deployment を network に公開してはいけません。

Server source と Python SDK は MIT license ですが、model は明示的にその対象外です。Container image に model は含まれません。installer は model license を表示し、verify は package identity、signed license、validity date、current authorization を検証します。buffalo_l を含む公開 InsightFace model package は、別の commercial license がない限り原則として non-commercial academic research 専用です。code が入手できることや download 成功は商用配備の許可ではありません。