尧图网站建设 
InsightFace Server REST API 完全指南人脸检测、识别检索与 RTSP 监控接口实战【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightfaceInsightFace Server 是 insightface 项目内置的多人脸识别服务端所有公共接口统一挂载在/v1路径下以 JSONsnake_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 根路径为/v1JSON 字段使用snake_case图片以 JPEG/PNG/WebP 的 multipart 形式上传解码前会应用 EXIF 方向矫正该 API 不是 AWS Rekognition 或 CompreFace 的兼容契约见 api.md。认证规则仓库自带的 Compose 文件默认关闭认证仅用于隔离环境评估。当运维人员开启认证后除GET /v1/health之外的所有端点都要求Authorization: Bearer api_keyGET /v1/health保持公开供容器编排器和 Web UI 探测就绪状态以及判断 API 认证是否开启。关闭认证时不要发送空的Authorization头应完全省略。请求 ID 与限流每个响应都带x-request-idUUID 头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 MiBcursor是不透明令牌必须原样回传给同一端点、同一 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_URLhttp://127.0.0.1:18097 AUTH_HEADERAuthorization: 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报告不可变的系统级检测 profilesafe_config.max_detected_faces报告检测数量安全上限系统 profile 没有运行时修改端点。safe_config.inference_max_concurrency报告进程级模型推理预算CPU 默认 4CUDA 默认 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–100collection_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 imagegroup.jpg \ -F max_faces10 \ -F collection_idemployees成功返回 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.4collection_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 sourcesource.jpg \ -F targettarget.jpg \ -F threshold0.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 imageportrait.jpg -F collection_idemployees成功返回 200faces中仅一个元素含 L2 归一化 embedding、model、processing_ms与request_id。该受认证端点故意不用于普通注册/检索流程——embedding 是敏感的生物特征模板不会写入日志。错误废弃face_selection参数触发400、未知 Collection404、413、422invalid_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_THRESHOLDsearch.profile仅接受fp32_v1、fp16_v1、bf16_v1、int8_x736_v1、int8_x1000_v1没有隐式重排rerankprofile默认/推荐的 INT8 缩放为 736Collection 整体默认仍是 FP32。其余默认值为 10 万行容量、每人 20 个 FaceSample、懒加载_default在未提供加载策略时使用 eager 加载CPU 原生后端支持 FP32/BF16/INT8FP16 仅 CUDA 支持CUDA 后端支持全部五个 profile。持久化的 profile 若不被当前后端支持会显式失败绝不静默降级到其他 profile 或 ProviderCUDA 下 BF16 还要求 SM80 及以上设备创建时绑定模型 ID、版本、bundle 摘要、embedding 维度与预处理版本这些字段不可 PATCH每个 Collection 响应还暴露稳定的不透明embedding_contract_id外部可信注册时必须复制该 ID 而非自行构造single_face_selection接受largest与center_largestcenter_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。Querylimit1–100默认 50、可选cursor。curl -sS ${BASE_URL}/v1/collections?limit50 -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 时才用forcetrue重试。curl -sS -X DELETE ${BASE_URL}/v1/collections/employees?forcetrue \ -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可选省略时生成 UUIDname、external_id可选metadata可选JSON 对象编码为 multipart 字符串默认{}review_modeoff/standard/strict默认offembedding_modeserver/external_trusted默认serverexternal_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 idemployee-001 \ -F nameAlice \ -F external_idHR-1001 \ -F metadata{department:sales} \ -F review_modestandard \ -F imagesalice1.jpg \ -F imagesalice2.jpg审核模式语义所有模式都要求有效图片中至少检测到一张脸且 embedding 有限、尺寸正确、L2 归一化。off使用 Collection 的单脸策略并跳过可配置的质量阈值standard与strict要求恰好一张脸standard额外应用最小人脸尺寸、检测分数、质量与姿态规则strict在standard基础上要求候选人与自己 Person 现有样本的最大相似度严格大于其与其他所有 Person的最大相似度使用 Collection 固定的搜索 profile 计算平局即拒绝。Person 无现有样本时第一个 standard 质量候选直接引导该 Person 并跳过相似度比较同一 multipart 请求中的后续候选以先前已接受的候选作为类内参照。批次可以部分成功。外部可信向量embedding_modeexternal_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。错误400ID/metadata 非法或图片过多、404Collection、409Person/external-ID、embedding 契约、容量或每人上限冲突、413、422 registration_failed、503 search_index_unavailable。若 503 带write_committed: true不要盲目重试——先读取该 Person。GET /v1/collections/{collection_id}/personsQuerylimit1–100默认 50、不透明cursor、可选search最长 200 字符匹配 Person ID、name 或 external_id。curl -sS ${BASE_URL}/v1/collections/employees/persons?limit50searchalice \ -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。可重复的 multipartimagesreview_mode、embedding_mode、external_embeddings、embedding_contract_id与 Person 创建语义完全一致。curl -sS ${BASE_URL}/v1/collections/employees/persons/alice/faces \ -H ${AUTH_HEADER} -F review_modestandard \ -F imagesalice-2.jpg -F imagesalice-3.webp成功返回 201含faces与rejected_images允许部分成功。错误与 Person 创建一致另加404Person。GET /v1/collections/{collection_id}/persons/{person_id}/faces分页读取 FaceSample 元数据。Querylimit1–100默认 50、cursor。不返回存储的 embedding 与裁剪图字节仅当存在存储裁剪图时该项has_crop: true。curl -sS ${BASE_URL}/v1/collections/employees/persons/alice/faces?limit50 \ -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错误404FaceSample 或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默认 5threshold可选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 imageunknown.jpg \ -F limit5匹配示例{ 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:secretcamera.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 只返回打码后的 sourcematch_threshold: null继承 Collection 阈值event_buffer_size范围为 10–10000Web 预览默认关闭识别与事件收集不依赖任何观看者。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分页列出持久化配置与紧凑运行摘要。Querylimit1–100默认 50、不透明cursor。curl -sS ${BASE_URL}/v1/monitors?limit50 -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}部分更新 Monitorid不可变event_policy本身支持部分更新。仅在轮换 RTSP URL 或凭据时发送新sourcematch_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拉取近期进入/离开/错误/恢复事件无需长连接。Querylimit1–1000默认 100下次轮询时回传上次的next_cursor。游标是包含内部流纪元与序号的不透明签名串。首次无游标调用返回最新事件至多limit条后续调用返回之后的事件。truncated: true表示客户端落后于有界环形缓冲区stream_reset: true表示任务已重启、旧游标属于另一纪元。事件不可持久化进程重启即丢失。curl -sS ${BASE_URL}/v1/monitors/front-gate/events?limit100 \ -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已存人脸端点返回 JPEGMJPEG 是流式响应。源码佐证与进一步阅读API 端点集中实现在 app.py含/v1/health路由与请求校验响应模型与 Schema 定义在 api/responses.py 与 api/schemas.py检测/推理与并发预算 config.py 与 inference多分辨率 SCRFD 检测与全局 NMS 的配置见 server.toml搜索后端与索引同步 search含原生后端与同步删除逻辑注册、图片处理与 RTSP 任务的服务层 servicesAPI 契约测试 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），仅供参考 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/insightfaceInsightFace Server 是 insightface 项目内置的多人脸识别服务端所有公共接口统一挂载在/v1路径下以 JSONsnake_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 根路径为/v1JSON 字段使用snake_case图片以 JPEG/PNG/WebP 的 multipart 形式上传解码前会应用 EXIF 方向矫正该 API 不是 AWS Rekognition 或 CompreFace 的兼容契约见 api.md。认证规则仓库自带的 Compose 文件默认关闭认证仅用于隔离环境评估。当运维人员开启认证后除GET /v1/health之外的所有端点都要求Authorization: Bearer api_keyGET /v1/health保持公开供容器编排器和 Web UI 探测就绪状态以及判断 API 认证是否开启。关闭认证时不要发送空的Authorization头应完全省略。请求 ID 与限流每个响应都带x-request-idUUID 头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 MiBcursor是不透明令牌必须原样回传给同一端点、同一 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_URLhttp://127.0.0.1:18097 AUTH_HEADERAuthorization: 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报告不可变的系统级检测 profilesafe_config.max_detected_faces报告检测数量安全上限系统 profile 没有运行时修改端点。safe_config.inference_max_concurrency报告进程级模型推理预算CPU 默认 4CUDA 默认 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–100collection_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 imagegroup.jpg \ -F max_faces10 \ -F collection_idemployees成功返回 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.4collection_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 sourcesource.jpg \ -F targettarget.jpg \ -F threshold0.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 imageportrait.jpg -F collection_idemployees成功返回 200faces中仅一个元素含 L2 归一化 embedding、model、processing_ms与request_id。该受认证端点故意不用于普通注册/检索流程——embedding 是敏感的生物特征模板不会写入日志。错误废弃face_selection参数触发400、未知 Collection404、413、422invalid_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_THRESHOLDsearch.profile仅接受fp32_v1、fp16_v1、bf16_v1、int8_x736_v1、int8_x1000_v1没有隐式重排rerankprofile默认/推荐的 INT8 缩放为 736Collection 整体默认仍是 FP32。其余默认值为 10 万行容量、每人 20 个 FaceSample、懒加载_default在未提供加载策略时使用 eager 加载CPU 原生后端支持 FP32/BF16/INT8FP16 仅 CUDA 支持CUDA 后端支持全部五个 profile。持久化的 profile 若不被当前后端支持会显式失败绝不静默降级到其他 profile 或 ProviderCUDA 下 BF16 还要求 SM80 及以上设备创建时绑定模型 ID、版本、bundle 摘要、embedding 维度与预处理版本这些字段不可 PATCH每个 Collection 响应还暴露稳定的不透明embedding_contract_id外部可信注册时必须复制该 ID 而非自行构造single_face_selection接受largest与center_largestcenter_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。Querylimit1–100默认 50、可选cursor。curl -sS ${BASE_URL}/v1/collections?limit50 -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 时才用forcetrue重试。curl -sS -X DELETE ${BASE_URL}/v1/collections/employees?forcetrue \ -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可选省略时生成 UUIDname、external_id可选metadata可选JSON 对象编码为 multipart 字符串默认{}review_modeoff/standard/strict默认offembedding_modeserver/external_trusted默认serverexternal_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 idemployee-001 \ -F nameAlice \ -F external_idHR-1001 \ -F metadata{department:sales} \ -F review_modestandard \ -F imagesalice1.jpg \ -F imagesalice2.jpg审核模式语义所有模式都要求有效图片中至少检测到一张脸且 embedding 有限、尺寸正确、L2 归一化。off使用 Collection 的单脸策略并跳过可配置的质量阈值standard与strict要求恰好一张脸standard额外应用最小人脸尺寸、检测分数、质量与姿态规则strict在standard基础上要求候选人与自己 Person 现有样本的最大相似度严格大于其与其他所有 Person的最大相似度使用 Collection 固定的搜索 profile 计算平局即拒绝。Person 无现有样本时第一个 standard 质量候选直接引导该 Person 并跳过相似度比较同一 multipart 请求中的后续候选以先前已接受的候选作为类内参照。批次可以部分成功。外部可信向量embedding_modeexternal_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。错误400ID/metadata 非法或图片过多、404Collection、409Person/external-ID、embedding 契约、容量或每人上限冲突、413、422 registration_failed、503 search_index_unavailable。若 503 带write_committed: true不要盲目重试——先读取该 Person。GET /v1/collections/{collection_id}/personsQuerylimit1–100默认 50、不透明cursor、可选search最长 200 字符匹配 Person ID、name 或 external_id。curl -sS ${BASE_URL}/v1/collections/employees/persons?limit50searchalice \ -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。可重复的 multipartimagesreview_mode、embedding_mode、external_embeddings、embedding_contract_id与 Person 创建语义完全一致。curl -sS ${BASE_URL}/v1/collections/employees/persons/alice/faces \ -H ${AUTH_HEADER} -F review_modestandard \ -F imagesalice-2.jpg -F imagesalice-3.webp成功返回 201含faces与rejected_images允许部分成功。错误与 Person 创建一致另加404Person。GET /v1/collections/{collection_id}/persons/{person_id}/faces分页读取 FaceSample 元数据。Querylimit1–100默认 50、cursor。不返回存储的 embedding 与裁剪图字节仅当存在存储裁剪图时该项has_crop: true。curl -sS ${BASE_URL}/v1/collections/employees/persons/alice/faces?limit50 \ -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错误404FaceSample 或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默认 5threshold可选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 imageunknown.jpg \ -F limit5匹配示例{ 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:secretcamera.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 只返回打码后的 sourcematch_threshold: null继承 Collection 阈值event_buffer_size范围为 10–10000Web 预览默认关闭识别与事件收集不依赖任何观看者。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分页列出持久化配置与紧凑运行摘要。Querylimit1–100默认 50、不透明cursor。curl -sS ${BASE_URL}/v1/monitors?limit50 -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}部分更新 Monitorid不可变event_policy本身支持部分更新。仅在轮换 RTSP URL 或凭据时发送新sourcematch_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拉取近期进入/离开/错误/恢复事件无需长连接。Querylimit1–1000默认 100下次轮询时回传上次的next_cursor。游标是包含内部流纪元与序号的不透明签名串。首次无游标调用返回最新事件至多limit条后续调用返回之后的事件。truncated: true表示客户端落后于有界环形缓冲区stream_reset: true表示任务已重启、旧游标属于另一纪元。事件不可持久化进程重启即丢失。curl -sS ${BASE_URL}/v1/monitors/front-gate/events?limit100 \ -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已存人脸端点返回 JPEGMJPEG 是流式响应。源码佐证与进一步阅读API 端点集中实现在 app.py含/v1/health路由与请求校验响应模型与 Schema 定义在 api/responses.py 与 api/schemas.py检测/推理与并发预算 config.py 与 inference多分辨率 SCRFD 检测与全局 NMS 的配置见 server.toml搜索后端与索引同步 search含原生后端与同步删除逻辑注册、图片处理与 RTSP 任务的服务层 servicesAPI 契约测试 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），仅供参考