录像智能检索 API

第三方服务器使用现有 API Token 调用 /api/v2/recording/search/*。Token 需要 recordings.play 权限；管理员手工补救需要 recordings.manage。调用时还会检查录像智能检索模块授权、总开关、通道参与状态和原录像文件状态。请从服务端保存 Token，不要放入网页、URL 或日志。

以文字搜索

POST /api/v2/recording/search/text，请求体为 JSON：

curl -X POST 'https://example.invalid/api/v2/recording/search/text' \
  -H 'Authorization: Bearer ak_pat_<TOKEN>' \
  -H 'Content-Type: application/json' \
  --data '{"text":"有人穿黄色外套进入大门","channelIds":["channel-1"],"fromUtc":"2026-09-30T00:00:00Z","toUtc":"2026-10-01T00:00:00Z","minSimilarity":0.45,"maxSegments":5}'

text 必填，1–500 字符；channelIds 省略时搜索所有已参与通道；时间使用 ISO 8601 带时区格式。minSimilarity 范围为 0–1，默认 0.45；maxSegments 范围为 1–50，默认 5；超出范围返回 HTTP 400。结果按请求阈值和数量限制返回。开始时间不得晚于结束时间。空通道范围返回空 segments。

minSimilarity:0.60 表示模型余弦相似度至少 0.60，不是画面含有目标的 60% 识别置信度。实际分数随模型与查询语句变化；阈值太高可能没有结果。RK3588 上一次 RN50 实测中，“男人”的前排分数约 0.42，“出风口”约 0.48，因此页面初始值采用 0.45 / Top 5，并允许用户现场调整。

以图片搜索

POST /api/v2/recording/search/image，请求体为 multipart/form-data，恰好包含一张 JPEG/PNG 图片和可选的 query JSON 筛选对象。图片上限 5 MiB，请求上限 6 MiB；不要传服务器路径或外部图片 URL。

curl -X POST 'https://example.invalid/api/v2/recording/search/image' \
  -H 'Authorization: Bearer ak_pat_<TOKEN>' \
  -F 'image=@./reference.jpg' \
  -F 'query={"channelIds":["channel-1"],"minSimilarity":0.45,"maxSegments":5}'

读取结果并播放

两个搜索接口返回同样的结构。以下值只展示字段形状，文件 ID、时间和相似度均以实际响应为准：

{
  "modelSpaceId": "chinese-clip-rn50-official-v1",
  "effectiveBackend": "Cpu",
  "coverage": "Unverified",
  "segments": [{
    "recordFileId": "00000000-0000-0000-0000-000000000001",
    "channelId": "channel-1",
    "channelName": "入口摄像机",
    "deviceId": "device-1",
    "nodeId": "node-1",
    "mediaServerId": "media-1",
    "vhost": "__defaultVhost__",
    "app": "live",
    "streamId": "stream-1",
    "fileName": "record.mp4",
    "hitAtUtc": "2026-09-30T01:02:03Z",
    "hitOffsetMs": 42000,
    "segmentStartMs": 40000,
    "segmentEndMs": 47000,
    "similarity": 0.82,
    "mediaUrl": "/api/v2/recording/files/00000000-0000-0000-0000-000000000001/media",
    "playableOnCurrentNode": true
  }]
}

mediaUrl 是受保护的相对地址，不是匿名公开视频。服务端客户端可附带同一 Bearer Token 并用 HTTP Range 播放；浏览器 <video> 不能自行设置 Authorization 头时，先使用第三方录像短时播放地址接口 POST /api/v2/third-party/recordings/{fileId}/playback-link，再把命中偏移换成播放器的 seek 时间。该播放地址仍受原文件和权限状态约束。

运行状态与人工补救

GET /api/v2/recording/search/status 返回授权、模型、向量服务和任务状态。GET /api/v2/recording/search/hardware 与 /capabilities 要求 system.config.view，供运维检测后端；不要把“运行时可见”当作“模型已验收”。

管理员临时打开配置 FileRecoveryEnabled 后，可用 POST /api/v2/recording/search/index-jobs 提交明确文件：

{"recordFileIds":["00000000-0000-0000-0000-000000000001"]}

每次须提交 1–100 个 ID。返回 HTTP 202 及 requested、accepted、skipped；只表示排队，不表示向量已生成。该接口需要 recordings.manage 和相同模块授权。关闭补救开关不会删除已经存在的检索结果。

错误处理

HTTP	code	处理
400	`invalid_query`、`invalid_image`、`invalid_filter`、`invalid_file_ids`	修正文字、图片或筛选条件，不原样重试
401	`authentication_required`	提供有效 Bearer API Token
403	`permission_denied` 或授权拒绝	检查 Token 权限及高级模块授权
503	`recording_search_disabled`、`recording_search_unavailable`、`file_recovery_disabled`	查看模块状态、模型、Qdrant 与补救开关，退避后重试

coverage: "Unverified" 表示索引可能不完整。录像文件被删后，客户端必须丢弃以前缓存的播放地址和搜索结果。