news 2026/9/10 3:17:26

InsightFace Server REST API 完全指南：人脸检测、识别检索与 RTSP 监控接口实战

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
InsightFace Server REST API 完全指南：人脸检测、识别检索与 RTSP 监控接口实战

InsightFace Server REST API 完全指南：人脸检测、识别检索与 RTSP 监控接口实战

【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface

InsightFace Server 是 insightface 项目内置的多人脸识别服务端，所有公共接口统一挂载在/v1路径下，以 JSON（snake_case）为数据格式、以multipart/form-data接收图片。本文基于 api.ko.md 完整梳理系统诊断、无状态人脸处理、Collection 身份库、Person/FaceSample 注册、相似度检索与 RTSP 实时监控六大模块的每个端点：输入参数、服务器处理逻辑、成功结果与错误语义，并结合 app.py 与 server.toml 的源码实现解释底层行为。读完本文，你可以用curl独立完成"建库 → 注册 → 检索"全流程，也能正确配置并轮询一个 RTSP 门禁监控任务。

本文以仓库中server/docs/api.ko.md为骨架，补充了英文原版 api.md 中更完整的 JSON 示例与源码佐证。容器与模型的启动方式请参考 用户指南；当前运行版本的确切 Schema 以/docs与/openapi.json为准。

公共约定：路径、认证、请求 ID 与阈值语义

基础约定

  • 所有 API 根路径为/v1，JSON 字段使用snake_case；
  • 图片以 JPEG/PNG/WebP 的 multipart 形式上传，解码前会应用 EXIF 方向矫正；
  • 该 API 不是 AWS Rekognition 或 CompreFace 的兼容契约（见 api.md）。

认证规则

仓库自带的 Compose 文件默认关闭认证，仅用于隔离环境评估。当运维人员开启认证后，除GET /v1/health之外的所有端点都要求：

Authorization: Bearer <api_key>

GET /v1/health保持公开，供容器编排器和 Web UI 探测就绪状态以及判断 API 认证是否开启。关闭认证时不要发送空的Authorization头，应完全省略。

请求 ID 与限流

  • 每个响应都带x-request-id（UUID 头），JSON 响应体中同名request_id与之对应；
  • 成功删除请求返回 HTTP 204 且无响应体；
  • 第一阶段并未内置限流器（见 api.md），当前仓库的 429 语义仅用于 RTSP Monitor 数量上限。

分数与阈值语义（务必区分）

  • detection_score：检测器置信度；
  • quality.score、sharpness、brightness、pose：本地质量信号，不是AWS 指标；
  • similarity：原始 cosine 值，范围[-1.0, 1.0]，不是概率；
  • 识别threshold接受[0.0, 1.0]，默认0.4；
  • 阈值是包含式判定：similarity >= threshold即视为匹配。

边界框同时返回像素坐标与归一化坐标两种形式：

{ "pixels": {"x": 120, "y": 80, "width": 240, "height": 280}, "normalized": {"left": 0.12, "top": 0.08, "width": 0.24, "height": 0.28} }

尺寸限制与游标

  • 压缩图片默认上限 10 MiB，解码后上限 4000 万像素，单请求总上限 64 MiB；
  • cursor是不透明令牌：必须原样回传给同一端点、同一 Collection、同一 Person、同一过滤条件，客户端禁止解析或构造它。

错误封装与通用状态码

所有错误使用标准 HTTP 状态码 + 统一错误封装：

{ "error": { "code": "face_not_found", "message": "No usable face was detected.", "details": {} }, "request_id": "3ed21e89-4595-4eed-a699-1df42ca62032" }

通用状态映射：400 参数非法、401 API Key 缺失/非法、404 资源不存在、409 资源/模型冲突、413 请求或图片过大、422 图片非法或人脸不可用、500 未预期错误、503 超时或运行时不可用。

首次调用的最小环境

BASE_URL=http://127.0.0.1:18097 AUTH_HEADER="Authorization: Bearer ${INSIGHTFACE_API_KEY}" curl -fsS "${BASE_URL}/v1/health"

仅当 health 返回auth_enabled: false时才可留空AUTH_HEADER。

系统端点：健康检查、运行诊断与模型清单

GET /v1/health

公开的就绪探针，无参数。当启动完成且 SQLitequick_check通过时返回 200：

{"status":"ready","auth_enabled":false,"request_id":"..."}

否则返回503 not_ready。auth_enabled只告知客户端是否应展示 API Key 输入控件，不会暴露已配置的 Key 或其哈希。该端点故意不要求认证（对应 app.py 中注册的公开健康路由）。

GET /v1/system

面向运维的安全诊断接口，无参数。返回服务器/OS/架构/CPU、GPU 及 Compute Capability（存在时）、NVIDIA 驱动、CUDA/cuDNN/ONNX Runtime、实际生效的 Provider、模型摘要、数据库与路径状态、聚合计数、API Key 状态、安全限制与近期结构化错误摘要。不会返回API Key、图片或 embedding。

其中safe_config.detection报告不可变的系统级检测 profile，safe_config.max_detected_faces报告检测数量安全上限；系统 profile 没有运行时修改端点。safe_config.inference_max_concurrency报告进程级模型推理预算（CPU 默认 4，CUDA 默认 8），运行时诊断还会暴露当前活跃、等待与峰值模型任务数——Detect、Compare、Embeddings、注册、Search 查询特征提取与 RTSP 识别共享这一预算（详见 server.toml 的[inference] max_concurrency = "auto"注释）。

Collection 创建时会复制该系统 profile，除非请求显式覆盖；Collection profile 持久化在 SQLite 中，可被 PATCH，且用于该 Collection 的注册与检索。profile 变更后不会自动重新提取已有 embedding。常见错误：401 unauthorized；诊断超时返回503 request_timeout。

curl -sS "${BASE_URL}/v1/system" -H "${AUTH_HEADER}"

GET /v1/models

读取已验证的模型包与实际 Provider，无参数。返回 200 的models、execution_provider和已验证的 License 摘要；不返回模型字节或私钥签名。常见错误仅401 unauthorized。

curl -sS "${BASE_URL}/v1/models" -H "${AUTH_HEADER}"

无状态人脸处理：detect / compare / embeddings

这三个端点不落库，适合在注册之外做即时判断。

POST /v1/detect

检测一张图内的所有人脸。multipart 字段：

  • image（必填）；
  • max_faces（可选，1–100）；
  • collection_id（可选，使用该 Collection 的检测 profile 而非系统 profile）。

服务器会在多个输入分辨率上分别运行动态 SCRFD，把所有候选框映射回原图坐标，再做一次全局 NMS 合并，最后按面积降序排列（对应 server.toml 的input_sizes = [[96, 96], [512, 512]]与nms_threshold = 0.40）。检测不到人脸属于正常成功，返回faces: []。

curl -sS http://localhost:18097/v1/detect \ -H "Authorization: Bearer ${INSIGHTFACE_API_KEY}" \ -F 'image=@group.jpg' \ -F 'max_faces=10' \ -F 'collection_id=employees'

成功返回 200，含faces、processing_ms与request_id；每张脸含像素/归一化边界框、5 点关键点、检测置信度与质量信号，不返回也不持久化 embedding。错误：400 request_detection_override_not_supported（已废弃的min_score参数）、未知 Collection 的404、尺寸超限413、422 invalid_image、503 request_timeout。

POST /v1/compare

从两张图中各选一张人脸做相似度比较，不持久化。multipart 字段：

  • source与target（必填）；
  • threshold（可选，0.0..1.0，服务端默认0.4）；
  • collection_id（可选，检测 profile 来源）。

使用当前 profile 的单脸选择策略（single_face_selection，见 server.toml），任一张图无人脸则返回422 face_not_found。

curl -sS http://localhost:18097/v1/compare \ -H "Authorization: Bearer ${INSIGHTFACE_API_KEY}" \ -F 'source=@source.jpg' \ -F 'target=@target.jpg' \ -F 'threshold=0.4'

成功返回 200，含matched（布尔）、原始 cosinesimilarity、生效的threshold、选中的人脸摘要、processing_ms与request_id。错误：未知 Collection404、尺寸413、422 invalid_image/face_not_found、503 request_timeout。

POST /v1/embeddings

为可信集成方提取所选人脸的 embedding。multipart 字段：image（必填）、collection_id（可选）。

curl -sS "${BASE_URL}/v1/embeddings" -H "${AUTH_HEADER}" \ -F 'image=@portrait.jpg' -F 'collection_id=employees'

成功返回 200，faces中仅一个元素，含 L2 归一化 embedding、model、processing_ms与request_id。该受认证端点故意不用于普通注册/检索流程——embedding 是敏感的生物特征模板，不会写入日志。错误：废弃face_selection参数触发400、未知 Collection404、413、422（invalid_image/face_not_found）、503。

Collection：隔离的身份库与搜索契约

Collection 是一个隔离的身份数据库，创建时固定模型、检测与搜索契约。

POST /v1/collections

发送application/json：

{ "id": "employees", "name": "Company Employees", "description": "Employee face collection", "threshold": 0.4, "save_face_crops": false, "detection": { "input_sizes": [[96, 96], [512, 512]], "threshold": 0.5, "nms_threshold": 0.4, "single_face_selection": "largest" }, "search": { "profile": "fp32_v1", "capacity_rows": 100000, "max_faces_per_person": 20, "load_policy": "lazy" }, "metadata": {"site": "shanghai"} }
  • id为_default，或 1–64 个字符、以字母或数字开头、仅含字母/数字/./_/-；name必填；省略threshold时使用INSIGHTFACE_DEFAULT_THRESHOLD；
  • search.profile仅接受fp32_v1、fp16_v1、bf16_v1、int8_x736_v1、int8_x1000_v1，没有隐式重排（rerank）profile；默认/推荐的 INT8 缩放为 736，Collection 整体默认仍是 FP32。其余默认值为 10 万行容量、每人 20 个 FaceSample、懒加载；_default在未提供加载策略时使用 eager 加载；
  • CPU 原生后端支持 FP32/BF16/INT8，FP16 仅 CUDA 支持；CUDA 后端支持全部五个 profile。持久化的 profile 若不被当前后端支持会显式失败，绝不静默降级到其他 profile 或 Provider；CUDA 下 BF16 还要求 SM80 及以上设备；
  • 创建时绑定模型 ID、版本、bundle 摘要、embedding 维度与预处理版本，这些字段不可 PATCH；每个 Collection 响应还暴露稳定的不透明embedding_contract_id，外部可信注册时必须复制该 ID 而非自行构造；
  • single_face_selection接受largest与center_largest；center_largest最大化像素空间分数area - 2.0 * ((face_cx - image_cx)^2 + (face_cy - image_cy)^2)，检测置信度不参与该选择；
  • save_face_crops默认取部署环境变量INSIGHTFACE_SAVE_FACE_CROPS（默认为false），解析结果持久化在 Collection 上，不随环境后续变化；开启后，被接受的 112×112 边界框裁剪图（不是原始上传图）会以 JPEG 编码并作为 BLOB 存入 SQLite，可能显著增大数据库与备份体积。
curl -sS "${BASE_URL}/v1/collections" -H "${AUTH_HEADER}" \ -H 'Content-Type: application/json' \ -d '{"id":"employees","name":"Employees","threshold":0.4}'

成功返回 201 与完整的collection（含不可变模型绑定、检测 profile、搜索设置、计数与时间戳）。错误：400 invalid_detection_profile/unsupported_search_profile/search_capacity_too_large、409 collection_exists、503 search_index_unavailable。

GET /v1/collections

分页列出 Collection。Query：limit1–100（默认 50）、可选cursor。

curl -sS "${BASE_URL}/v1/collections?limit=50" -H "${AUTH_HEADER}"

成功返回 200，含collections与可空的next_cursor（原样回传）。错误：400 invalid_cursor、401 unauthorized。

GET /v1/collections/{collection_id}

curl -sS "${BASE_URL}/v1/collections/employees" -H "${AUTH_HEADER}"

成功返回 200，含collection、当前person_count、face_count与embedding_contract_id。错误：404 resource_not_found；在模型绑定不兼容的活动 bundle 下使用会返回409 collection_model_mismatch。

PATCH /v1/collections/{collection_id}

更新可变策略。JSON 体可更新name、description、threshold、metadata、save_face_crops（影响后续注册请求，已有裁剪图不回填也不删除）；嵌套search可更新capacity_rows、max_faces_per_person、load_policy（不兼容的缩减会被拒绝），search_profile不可变（变更需重建索引）；嵌套detection可更新任意检测字段，进行中的请求保持其原有不可变快照。未知字段与显式 null 会被拒绝，不会重新处理已有 FaceSample。

curl -sS -X PATCH "${BASE_URL}/v1/collections/employees" \ -H "${AUTH_HEADER}" -H 'Content-Type: application/json' \ -d '{"threshold":0.45,"detection":{"single_face_selection":"center_largest"}}'

成功返回 200 与完整更新后的collection。错误：400、404、409（容量缩减或模型契约冲突）、503。

DELETE /v1/collections/{collection_id}

Query 参数force（布尔，默认false）。空 Collection 直接删除；非空返回409 collection_not_empty，只有明确要删除全部 Person/FaceSample 时才用force=true重试。

curl -sS -X DELETE "${BASE_URL}/v1/collections/employees?force=true" \ -H "${AUTH_HEADER}"

成功返回 204 无响应体。错误：404、409 collection_not_empty、503。

另外两条容量约束：注册将超出capacity_rows时返回409 collection_capacity_exceeded且不提交多余 FaceSample；超出max_faces_per_person时返回409 person_face_limit_exceeded。

Person 与 FaceSample：注册、审核与外部可信向量

POST /v1/collections/{collection_id}/persons

一次请求创建 Person 并注册一个或多个 FaceSample。multipart 字段：

  • images（必填且可重复，默认最多 20 张）；
  • id（可选，省略时生成 UUID）；
  • name、external_id（可选）；
  • metadata（可选，JSON 对象编码为 multipart 字符串，默认{}）；
  • review_mode：off/standard/strict，默认off；
  • embedding_mode：server/external_trusted，默认server；
  • external_embeddings（仅external_trusted必填，JSON 数组，每个images部分恰好一个特征向量）；
  • embedding_contract_id（仅external_trusted必填，精确复制当前 Collection 的值）。
curl -sS http://localhost:18097/v1/collections/employees/persons \ -H "Authorization: Bearer ${INSIGHTFACE_API_KEY}" \ -F 'id=employee-001' \ -F 'name=Alice' \ -F 'external_id=HR-1001' \ -F 'metadata={"department":"sales"}' \ -F 'review_mode=standard' \ -F 'images=@alice1.jpg' \ -F 'images=@alice2.jpg'

审核模式语义：所有模式都要求有效图片中至少检测到一张脸，且 embedding 有限、尺寸正确、L2 归一化。off使用 Collection 的单脸策略并跳过可配置的质量阈值；standard与strict要求恰好一张脸，standard额外应用最小人脸尺寸、检测分数、质量与姿态规则；strict在standard基础上，要求候选人与自己 Person 现有样本的最大相似度严格大于其与其他所有 Person的最大相似度（使用 Collection 固定的搜索 profile 计算，平局即拒绝）。Person 无现有样本时，第一个 standard 质量候选直接引导该 Person 并跳过相似度比较；同一 multipart 请求中的后续候选以先前已接受的候选作为类内参照。批次可以部分成功。

外部可信向量：embedding_mode=external_trusted时仍会解码、检测图片并执行相同的review_mode规则，但不运行识别模型。off模式下可信调用方断言向量i属于图片部分i中的最大人脸；不存在自动回退到服务器提取，图片与向量数量必须一致。外部向量必须为有限数值、非零、维度与embedding_contract_id匹配、L2 范数在1.0 ± 0.0002内；超差则按invalid_external_embedding拒绝该图片（不静默修复）。通过的向量在 FP32 转换后会再次归一化以消除浮点漂移，strict审核使用该最终向量做类内/类外比较。可信调用方全权负责保证向量确实来自配对图片且使用声明管道提取——服务端有意不重新提取特征来验证关联。

成功响应示例（HTTP 201，部分成功也算 201）：

{ "person": {"id": "employee-001", "face_count": 1}, "faces": [{"id": "a-face-uuid", "quality": {"score": 0.91}}], "rejected_images": [ {"index": 1, "filename": "alice2.jpg", "reason": "multiple_faces"} ], "request_id": "a-uuid" }

拒绝原因全集：invalid_image、image_too_large、face_not_found、multiple_faces、face_too_small、low_detection_score、low_quality、extreme_pose、invalid_embedding、identity_similarity_conflict。strict 相似度拒绝还会报告same_person_similarity、other_person_similarity、other_person_id、matched_face_id。若没有任何图片被接受，返回422 registration_failed且不创建 Person。

错误：400（ID/metadata 非法或图片过多）、404Collection、409（Person/external-ID、embedding 契约、容量或每人上限冲突）、413、422 registration_failed、503 search_index_unavailable。若 503 带write_committed: true，不要盲目重试——先读取该 Person。

GET /v1/collections/{collection_id}/persons

Query：limit1–100（默认 50）、不透明cursor、可选search（最长 200 字符，匹配 Person ID、name 或 external_id）。

curl -sS "${BASE_URL}/v1/collections/employees/persons?limit=50&search=alice" \ -H "${AUTH_HEADER}"

成功返回 200，含persons与可空next_cursor。错误：400 invalid_cursor、404。

GET /v1/collections/{collection_id}/persons/{person_id}

curl -sS "${BASE_URL}/v1/collections/employees/persons/alice" \ -H "${AUTH_HEADER}"

成功返回 200，含person、当前face_count与时间戳。错误：404。

PATCH /v1/collections/{collection_id}/persons/{person_id}

JSON 体接受name、external_id与对象型metadata；未知字段被拒绝，metadata不能为 null。

curl -sS -X PATCH "${BASE_URL}/v1/collections/employees/persons/alice" \ -H "${AUTH_HEADER}" -H 'Content-Type: application/json' \ -d '{"name":"Alice Chen","metadata":{"department":"sales"}}'

成功返回 200 与完整更新的person。错误：400、404、409 external_id_exists。

DELETE /v1/collections/{collection_id}/persons/{person_id}

删除 Person 及其全部 FaceSample、embedding 与可选裁剪图，并同步更新活动搜索索引（同进程内后续检索不会返回已删除行）。

curl -sS -X DELETE "${BASE_URL}/v1/collections/employees/persons/alice" \ -H "${AUTH_HEADER}"

成功返回 204。错误：404、503 search_index_unavailable。

POST /v1/collections/{collection_id}/persons/{person_id}/faces

向已有 Person 追加 FaceSample。可重复的 multipartimages；review_mode、embedding_mode、external_embeddings、embedding_contract_id与 Person 创建语义完全一致。

curl -sS "${BASE_URL}/v1/collections/employees/persons/alice/faces" \ -H "${AUTH_HEADER}" -F 'review_mode=standard' \ -F 'images=@alice-2.jpg' -F 'images=@alice-3.webp'

成功返回 201，含faces与rejected_images，允许部分成功。错误与 Person 创建一致，另加404Person。

GET /v1/collections/{collection_id}/persons/{person_id}/faces

分页读取 FaceSample 元数据。Query：limit1–100（默认 50）、cursor。不返回存储的 embedding 与裁剪图字节；仅当存在存储裁剪图时该项has_crop: true。

curl -sS "${BASE_URL}/v1/collections/employees/persons/alice/faces?limit=50" \ -H "${AUTH_HEADER}"

成功返回 200，含faces与可空next_cursor。错误：400 invalid_cursor、404。

GET /v1/collections/{collection_id}/persons/{person_id}/faces/{face_id}/image

下载可选的已存裁剪图（管理用途）。返回存储的 112×112 边界框裁剪图，类型image/jpeg，带Cache-Control: no-store；要求与其他非 health 接口相同的 Bearer 认证。该响应没有 JSONrequest_id，请用x-request-id头。FaceSample 存在但无存储裁剪图时返回 not-found 错误，不会合成或重建图片。

curl -sS http://localhost:18097/v1/collections/employees/persons/employee-001/faces/face-uuid/image \ -H "Authorization: Bearer ${INSIGHTFACE_API_KEY}" \ -o face-crop.jpg

错误：404（FaceSample 或face_image_not_found）、401 unauthorized。

DELETE /v1/collections/{collection_id}/persons/{person_id}/faces/{face_id}

删除一个 FaceSample、其 embedding 与可选裁剪图；从活动索引移除该行后才算成功。

curl -sS -X DELETE "${BASE_URL}/v1/collections/employees/persons/alice/faces/face-uuid" \ -H "${AUTH_HEADER}"

成功返回 204。错误：404、503 search_index_unavailable。

搜索：POST /v1/collections/{collection_id}/search

用查询图片中的选定人脸检索整个 Collection。multipart 字段：

  • image（必填）；
  • limit（可选，1–100，默认 5）；
  • threshold（可选0.0..1.0，默认取 Collection 阈值）。

处理逻辑：Collection profile 选出输入人脸 → 与每个 FaceSample 逐一比较 → 每个 Person 取其最高 FaceSample 分数 → 只返回达到阈值的人，按分数降序。无匹配时matches: []；查询图无可用人脸时422 face_not_found。

curl -sS http://localhost:18097/v1/collections/employees/search \ -H "Authorization: Bearer ${INSIGHTFACE_API_KEY}" \ -F 'image=@unknown.jpg' \ -F 'limit=5'

匹配示例：

{ "person": { "id": "employee-001", "name": "Alice", "external_id": "HR-1001", "metadata": {"department": "sales"} }, "similarity": 0.8642, "matched_face_id": "a-face-uuid" }

成功返回 200，含searched_face、有序matches、生效threshold、processing_ms与request_id。错误：404Collection、409 collection_model_mismatch、413、422 invalid_image/face_not_found、503 search_index_unavailable/request_timeout。

RTSP Monitor：持久化实时识别任务

Monitor 是服务端持久化的 RTSP 识别任务：配置存储在 SQLite 中，启用的任务在服务器重启后自动恢复；视频帧永不保存；近期事件只存在于有界内存环形缓冲区中，重启即丢失。解码器只保留最新帧，推理慢会降低实际处理帧率而不是堆积延迟帧队列。相关端点在 tests/api/test_rtsp_streams.py 中有对应测试覆盖。

POST /v1/monitors

创建（并可立即启动）一个持久化 Monitor。发送application/json：

{ "id": "front-gate", "name": "Front gate", "description": "Main entrance", "enabled": true, "source": {"type": "rtsp", "url": "rtsp://viewer:secret@camera.example/live"}, "collection_id": "employees", "inference_fps": 2.0, "match_threshold": null, "event_buffer_size": 1000, "event_policy": { "confirm_frames": 3, "absence_timeout_seconds": 3.0, "cooldown_seconds": 10.0, "emit_unknown": true }, "preview_enabled": false }

要点：

  • source.url只接受rtsp://或rtsps://；凭据以 AES-GCM 加密存储于/data下，API 只返回打码后的 source；
  • match_threshold: null继承 Collection 阈值；
  • event_buffer_size范围为 10–10000；
  • Web 预览默认关闭；识别与事件收集不依赖任何观看者。
curl -sS "${BASE_URL}/v1/monitors" -H "${AUTH_HEADER}" \ -H 'Content-Type: application/json' -d @monitor.json

成功返回 201，含monitor、打码后的 source、生效默认值与运行摘要。错误：400 invalid_request、404Collection、409 monitor_exists、429 monitor_limit_exceeded。

GET /v1/monitors

分页列出持久化配置与紧凑运行摘要。Query：limit1–100（默认 50）、不透明cursor。

curl -sS "${BASE_URL}/v1/monitors?limit=50" -H "${AUTH_HEADER}"

成功返回 200，含有序monitors与可空next_cursor。错误：400 invalid_cursor、401 unauthorized。

GET /v1/monitors/{monitor_id}

读取单个 Monitor 配置与最新运行摘要。返回的 RTSP URL 会省略用户信息与 query 值。

curl -sS "${BASE_URL}/v1/monitors/front-gate" -H "${AUTH_HEADER}"

成功返回 200，含event_policy、preview_enabled、时间戳与runtime。错误：404 monitor_not_found、401。

PATCH /v1/monitors/{monitor_id}

部分更新 Monitor，id不可变；event_policy本身支持部分更新。仅在轮换 RTSP URL 或凭据时发送新source；match_threshold置null可回到 Collection 默认值。变更 source、Collection、速率、阈值或事件策略会重启该 Monitor 任务；enabled置false/true可停止/启动；name、description、preview、buffer 大小变更无需重启任务。

curl -sS -X PATCH "${BASE_URL}/v1/monitors/front-gate" \ -H "${AUTH_HEADER}" -H 'Content-Type: application/json' \ -d '{"inference_fps":1.5,"event_policy":{"confirm_frames":5}}'

成功返回 200 与完整更新后的monitor。错误：400 invalid_request、404、429 monitor_limit_exceeded。

DELETE /v1/monitors/{monitor_id}

永久删除 Monitor 配置：停止解码器与推理线程、释放 RTSP 连接、丢弃内存状态与事件，但不删除其绑定的 Collection。

curl -sS -X DELETE "${BASE_URL}/v1/monitors/front-gate" \ -H "${AUTH_HEADER}"

成功返回 204。错误：404、401。

GET /v1/monitors/{monitor_id}/state

供无界面客户端或 Web UI 轮询实时状态。结果字段：status、connected、源尺寸/FPS、配置与实际推理速率、处理耗时、跳帧数、当前已识别/未识别人脸、预览观看者数、重连计数与最近安全错误。永不包含embedding 与源凭据。

curl -sS "${BASE_URL}/v1/monitors/front-gate/state" -H "${AUTH_HEADER}"

成功返回 200；禁用的 Monitor 通常报告stopped。错误：404、401。

GET /v1/monitors/{monitor_id}/events

拉取近期进入/离开/错误/恢复事件，无需长连接。Query：limit1–1000（默认 100）；下次轮询时回传上次的next_cursor。游标是包含内部流纪元与序号的不透明签名串。

首次无游标调用返回最新事件（至多limit条），后续调用返回之后的事件。truncated: true表示客户端落后于有界环形缓冲区；stream_reset: true表示任务已重启、旧游标属于另一纪元。事件不可持久化，进程重启即丢失。

curl -sS "${BASE_URL}/v1/monitors/front-gate/events?limit=100" \ -H "${AUTH_HEADER}"

成功返回 200，含events、next_cursor、has_more、truncated、stream_reset。错误：400 invalid_cursor、404、401。

GET /v1/monitors/{monitor_id}/preview.mjpeg

打开可选的原始 MJPEG 预览流。认证方式与其他 API 相同（Bearer 头），不要把 API Key 放进 URL。端点返回无标注的multipart/x-mixed-replaceJPEG 帧，客户端用/state接口自行绘制框与标签。

JPEG 编码仅在preview_enabled为 true 且至少一个观看者在线时惰性执行；关闭预览不会停止识别。传输中断后客户端应以有界退避重连。成功响应为 200 的长生命周期二进制流（非 JSON）。错误：409 preview_disabled、503 stream_unavailable、404、401。

客户端重试安全规则

  • 客户端超时应大于服务端配置的请求超时；
  • 把x-request-id作为关联 ID 记录日志，但不要记录图片、embedding、RTSP 凭据或 API Key；
  • 不透明next_cursor只能在同一端点/Collection/Person/filter 下复用，绝不解析或构造；
  • GET 可安全重试；DELETE 重试前先检查当前状态；网络结果不确定时不要自动重试Person/FaceSample 创建，先按客户端提供的资源 ID 查询；
  • 仅对429与瞬时503使用有上限的指数退避 + jitter 重试；4xx校验错误应修改请求；
  • Content-Type 语义：Collection/Person 的 PATCH 用 JSON，图片操作与注册用 multipart，已存人脸端点返回 JPEG，MJPEG 是流式响应。

源码佐证与进一步阅读

  • API 端点集中实现在 app.py（含/v1/health路由与请求校验）；响应模型与 Schema 定义在 api/responses.py 与 api/schemas.py；
  • 检测/推理与并发预算： config.py 与 inference；多分辨率 SCRFD 检测与全局 NMS 的配置见 server.toml；
  • 搜索后端与索引同步： search，含原生后端与同步删除逻辑；
  • 注册、图片处理与 RTSP 任务的服务层： services；
  • API 契约测试： tests/api（含test_rtsp_streams.py、test_detection_profiles.py、test_external_trusted.py、test_face_crop_database.py等），可作为端到端调用范本。

结合 api.md（英文原版）与 user-guide.ko.md（部署指南）阅读，可以覆盖从容器启动、模型校验到全部接口调用的完整链路。

【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/10 3:17:26

Spring Boot苍穹外卖新增菜品实战：从表单到数据库的完整链路

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/9/10 3:15:50

Python调用ChatGPT中转API全指南：从入门到生产环境

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/9/10 3:13:15

2026年路由器选购指南：五款Wi-Fi 7路由器真实推荐

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华