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

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

2026-09-09 18:08:02作者：姚月梅Lane
insightface
State-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

公开的就绪探针，无参数。当启动完成且 SQLite quick_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（布尔）、原始 cosine similarity、生效的 threshold、选中的人脸摘要、processing_ms 与 request_id。错误：未知 Collection 404、尺寸 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、未知 Collection 404、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：limit 1–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 非法或图片过多）、404 Collection、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：limit 1–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。可重复的 multipart images；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 创建一致，另加 404 Person。

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

分页读取 FaceSample 元数据。Query：limit 1–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 认证。该响应没有 JSON request_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。错误：404 Collection、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、404 Collection、409 monitor_exists、429 monitor_limit_exceeded。

GET /v1/monitors

分页列出持久化配置与紧凑运行摘要。Query：limit 1–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：limit 1–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-replace JPEG 帧，客户端用 /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（部署指南）阅读，可以覆盖从容器启动、模型校验到全部接口调用的完整链路。

insightface
State-of-the-art 2D and 3D Face Analysis Project
项目地址：https://gitcode.com/GitHub_Trending/in/insightface
登录后查看全文

相关内容推荐

1 InsightFace Server：自托管人脸识别服务的 Docker 部署、INT8 高速搜索与 REST API 实战2 InsightFace Server 0.2.0 实战指南：单容器自托管人脸识别服务与 INT8 GPU 精确搜索3 InsightFace Server 0.2.0：单容器自托管人脸识别服务与 INT8 精确 GPU 检索实战4 InsightFace Server 实战指南：自托管人脸识别服务的 GPU INT8 精确搜索、Docker 部署与配置详解5 InsightFace Server 部署实战：单容器自托管人脸识别服务与 INT8 向量检索详解6 InsightFace Server 技术详解：单卡 GPU 实现千万级人脸检索的自托管识别服务7 InsightFace Server 实战指南：单卡 GPU 承载 50M+ 人脸向量的自托管人脸识别服务8 InsightFace Server 用户指南：从零部署人脸检测、注册与 1:N 检索的完整实战9 InsightFace Server Python SDK 实战指南：自托管人脸服务 REST API 的轻量级客户端10 InsightFace Server：自托管人脸识别服务（v0.2.0）的部署、INT8 精确搜索与源码级剖析
热门项目推荐
相关项目推荐

热门内容推荐

1 编程实践项目探索指南：从零构建技术能力体系2 技术解构式学习：从0到1构建你的编程知识体系3 构建自己的技术世界：build-your-own-x项目的实践探索指南4 解锁编程技能的实践之旅：从零构建你的技术世界5 技术实践探索：从零开始构建核心系统的实践指南6 亲手锻造技术引擎：从0到1构建核心系统的实践指南

最新内容推荐

HyperFrames v0.6.83 发布解析：媒体播放速率时长修复、Producer 时间轴代理重构与发布标签守卫expo-media-library 完全指南：在 Expo 与 React Native 中访问用户媒体库的安装、权限配置与 API 实战agno AgentOS 如何用 JWT 认证加 RBAC scope 保护 REST 端点？Composio 文档站 API Reference 定制指南：fumadocs-openapi 渲染改造与 v3.0/v3.1 双版本架构光谱与分析化学数据格式的 EDA 安全边界：scientific-agent-skills 探索性数据分析技能实战指南在 Storybook 中使用自定义 MDX 模板替换 Autodocs 默认文档页Nginx Proxy Manager 如何把管理界面端口从 81 改为自定义端口？NPM_ADMIN_PORT 配置PostHog 仪表盘查询、缓存与规模化设计：从刷新契约到可观测性的完整工程指南HyperFrames v0.8.9 发布解析：音频效果系统文档化与渲染自检可靠性修复如何把已有的 LangGraph 与 Claude Agent SDK 程序迁入 agno AgentOS 统一提供服务？

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.14 K
2.76 K
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
860
1.35 K
docsdocs
暂无描述
Markdown
899
5.83 K
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
925
1.85 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.84 K
1.02 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
533
601
cann-learning-hubcann-learning-hub
CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
1.03 K
525
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
1.37 K
1.46 K
AscendNPU-IRAscendNPU-IR
AscendNPU-IR是基于MLIR（Multi-Level Intermediate Representation）构建的，面向昇腾亲和算子编译时使用的中间表示，提供昇腾完备表达能力，通过编译优化提升昇腾AI处理器计算效率，支持通过生态框架使能昇腾AI处理器与深度调优
C++
548
395