SentryShot v0.3.11 HTTP API 使用详解

本文整理 SentryShot v0.3.11 对外 HTTP API 的用法，全部示例在 Docker Compose 部署的实测环境（服务地址 http://127.0.0.1:8247，账号 admin/q1w2e3r4）中执行并逐行照抄回显（2026-10-30）。未提供 API Key 机制，程序化调用走 Basic 认证。

一、认证机制：Basic Auth + CSRF Token

读请求（GET）：带 HTTP Basic 认证即可；
写请求（PUT/POST/PATCH/DELETE）：额外需要 X-CSRF-TOKEN 请求头，token 通过 GET /api/account/my-token 获取，32 位字符串。

TOKEN=$(curl -s -u admin:q1w2e3r4 http://127.0.0.1:8247/api/account/my-token)
echo $TOKEN

hPz1e6tElJUsE4ymzFN7ubn2Y603eA38

token 每次请求返回值不同，可随时重新获取；会话内复用即可。

认证矩阵实测（GET /live）：

请求	结果
不带认证	`401`
`-u admin:q1w2e3r4`	`200`
Basic 认证但写请求缺 `X-CSRF-TOKEN`	`401`，响应体 `Invalid CSRF-token`

部署时若临时启用了 auth_none 插件，接口完全免认证、CSRF 校验同样不生效；生产环境务必启用 auth_basic（配置说明见《SentryShot v0.3.11 配置参数详解》）。

二、账号管理 API

创建账号（PUT /api/account）

curl -s -w '\nHTTP %{http_code}\n' -X PUT http://127.0.0.1:8247/api/account \
  -H "Content-Type: application/json" \
  -H "X-CSRF-TOKEN: $TOKEN" \
  -d '{"id":"a2b3c4d5e6f7g8h9","username":"admin","isAdmin":true,"plainPassword":"q1w2e3r4"}'


HTTP 201

成功返回 201、响应体为空。账号 ID 规则：16 位、字符集为小写字母与数字 2-9（不含 0/1/i/l/o）。两类失败实测：

# 长度不足
curl -s -w '\nHTTP %{http_code}\n' -X PUT http://127.0.0.1:8247/api/account \
  -H "Content-Type: application/json" -H "X-CSRF-TOKEN: $TOKEN" \
  -d '{"id":"zzzz","username":"x","isAdmin":true,"plainPassword":"q1w2e3r4"}'

Failed to deserialize the JSON body into the target type: id: expected length 16, got 4 at line 1 column 12
HTTP 422

# 含字符集外的字符
curl -s -w '\nHTTP %{http_code}\n' -X PUT http://127.0.0.1:8247/api/account \
  -H "Content-Type: application/json" -H "X-CSRF-TOKEN: $TOKEN" \
  -d '{"id":"a1b2c3d4e5f60718","username":"t","isAdmin":false,"plainPassword":"q1w2e3r4"}'

Failed to deserialize the JSON body into the target type: id: invalid character: '1' at line 1 column 24
HTTP 422

对已存在的 ID 再次 PUT 是覆盖更新（改用户名/密码用同一接口），返回 200。

查询与删除

curl -s -u admin:q1w2e3r4 http://127.0.0.1:8247/api/accounts

{"a2b3c4d5e6f7g8h9":{"id":"a2b3c4d5e6f7g8h9","username":"admin","isAdmin":true}}

curl -s -w '\nHTTP %{http_code}\n' -u admin:q1w2e3r4 \
  -X DELETE "http://127.0.0.1:8247/api/account?id=<账号ID>" -H "X-CSRF-TOKEN: $TOKEN"

删除成功返回 200（响应体为空）。

三、摄像头管理 API

查询全部摄像头（GET /api/monitors）

curl -s -u admin:q1w2e3r4 http://127.0.0.1:8247/api/monitors

返回以摄像头 ID 为键的对象（节选）：

{"cam2":{"alwaysRecord":true,"enable":true,"id":"cam2","motion":{"duration":10,"enable":true,"feedRate":2,"zones":[...]},"name":"cam2","source":"rtsp","sourcertsp":{"mainStream":"rtsp://mediamtx:8554/cam1","protocol":"tcp"},"videoLength":1}}

添加 / 更新（PUT /api/monitor）

curl -s -w '\nHTTP %{http_code}\n' -u admin:q1w2e3r4 -X PUT http://127.0.0.1:8247/api/monitor \
  -H "Content-Type: application/json" \
  -H "X-CSRF-TOKEN: $TOKEN" \
  -d '{"id":"cam2","name":"cam2","enable":true,"alwaysRecord":true,"videoLength":1,"source":"rtsp","sourcertsp":{"protocol":"tcp","mainStream":"rtsp://mediamtx:8554/cam1"}}'


HTTP 200

要点（均实测）：

新建返回 201、更新返回 200；同一 ID 重复 PUT 不报错（upsert 语义）；
全量覆盖：请求体漏掉 motion 段会把已配置的移动侦测清空，务必先 GET 全量再改；
PUT 后需调用 restart 才生效（见下）。

应用配置（POST /api/monitor/restart）

curl -s -w ' [%{http_code}]\n' -u admin:q1w2e3r4 \
  -X POST "http://127.0.0.1:8247/api/monitor/restart?id=cam2" -H "X-CSRF-TOKEN: $TOKEN"

 [200]

成功返回 200、响应体为空。不重启则新配置不会应用到取流与录制（实测 videoLength 改动后分段粒度不变）。

开关移动侦测 / 目标检测（PATCH）

curl -s -w ' [%{http_code}]\n' -u admin:q1w2e3r4 \
  -X PATCH http://127.0.0.1:8247/api/monitor/cam2/motion/disable -H "X-CSRF-TOKEN: $TOKEN"

 [200]

路径格式 PATCH /api/monitor/<id>/<motion|object-detection>/<enable|disable>，响应体为空。

四、直播 API

Web 页面 /live 的播放器即走以下两个接口（MSE 方式拉取 fMP4 流）：

1. 建立会话（session-id 为调用方自拟的会话标识）：

curl -s -u admin:q1w2e3r4 \
  -X POST "http://127.0.0.1:8247/api/streamer/start-session?session-id=12345&monitor-id=cam2&sub-stream=false"

{"startTimeNs":1793323924496633333,"codecs":"avc1.64001F"}

codecs 返回 H.264 的 codec 标记，sub-stream=true 走子码流。

2. 拉流（长连接，持续输出 fMP4 数据）：

curl -s -u admin:q1w2e3r4 --max-time 3 -o /tmp/play_sample.bin -w '%{http_code} %{size_download} %{content_type}\n' \
  "http://127.0.0.1:8247/api/streamer/play?session-id=12345&monitor-id=cam2&sub-stream=false"

200 2479958 video/mp4

（实测 3 秒内收到约 2.4 MB 数据，内容为 fMP4 分段。）简单直播页可直接访问 http://服务器IP:8247/live。

五、录像 API

查询录像段落（GET /api/recording/query）

curl -s -u admin:q1w2e3r4 \
  "http://127.0.0.1:8247/api/recording/query?recording-id=2099-01-01_00-00-00_x&limit=3&reverse=false&include-data=true"

[{"state":"active","id":"2026-10-30_01-08-23_cam2","data":{"start":1793322503575455555,"end":1793322514575455555,"events":[]}},{"state":"finalized","id":"2026-10-30_01-07-21_cam2","data":{"start":1793322441575455555,"end":1793322503575455555,"events":[]}},{"state":"finalized","id":"2026-10-30_01-06-19_cam2","data":{"start":1793322379575455555,"end":1793322441575455555,"events":[]}}]

参数说明：

参数	说明
`recording-id`	查询起点，格式 `YYYY-MM-DD_HH-MM-SS_<monitor-id>`；传未来时间（如 2099-01-01）表示从头查
`limit` / `reverse`	条数与排序方向
`include-data`	必传，缺失时返回 400

段落 state：active（正在写入）/ finalized（已完成）；start/end 为纳秒时间戳。

下载整段录像（GET /api/recording/video/<录像ID>）

curl -s -u admin:q1w2e3r4 -o /dev/null -w '%{http_code} %{size_download}\n' \
  "http://127.0.0.1:8247/api/recording/video/2026-10-30_00-41-06_cam2"

200 32354736

录像 ID 即存储目录中的文件名主体。返回完整 MP4（实测 1 分钟段落约 32 MB）。

缩略图（GET /api/recording/thumbnail/<录像ID>）

curl -s -u admin:q1w2e3r4 -o /dev/null -w '%{http_code} %{size_download}\n' \
  "http://127.0.0.1:8247/api/recording/thumbnail/2026-10-30_00-41-06_cam2"

200 52694

拼接时间段下载（GET /vod/vod.mp4）

curl -s -u admin:q1w2e3r4 -o /dev/null -w '%{http_code} %{size_download}\n' \
  "http://127.0.0.1:8247/vod/vod.mp4?monitor-id=cam2&start=1793322379575455555&end=1793322441575455555&cache-id=1"

200 28959349

start/end 传纳秒时间戳（与 query 返回的值一致），多段录像自动拼接为单个 MP4；cache-id 为缓存键，自拟即可。

六、日志查询 API（GET /api/log/query）

curl -s -u admin:q1w2e3r4 \
  "http://127.0.0.1:8247/api/log/query?levels=warning,error&sources=app&time=1793322362000000&limit=3"

[]

参数：levels 逗号分隔（debug/info/warning/error）、sources=app、limit、time 为查询起点的 Unix 时间戳。

时间戳粒度坑（实测）：time 接受微秒时间戳；若按纳秒传入（如 1793322362000000000）会直接报错：
invalid time [400]
与录像接口用的纳秒时间戳（start/end）粒度不同，注意区分。

七、状态码与错误速查（全部实测）

场景	状态码	响应体
未认证访问	401	空
写请求缺 `X-CSRF-TOKEN`	401	`Invalid CSRF-token`
账号 ID 长度/字符不合法	422	`Failed to deserialize the JSON body into the target type: id: ...`
`recording/query` 缺 `include-data`	400	`invalid parameters`
`log/query` 传纳秒时间戳	400	`invalid time`
PUT 已存在的账号/摄像头	200/201	空（upsert，不报错）
访问不存在的 API 路径	404	空

响应体为空的 4xx/5xx 需结合服务端日志页（/logs）排查。

SentryShot v0.3.11 HTTP API 使用详解

SentryShot v0.3.11 HTTP API 使用详解

一、认证机制：Basic Auth + CSRF Token

二、账号管理 API

创建账号（PUT /api/account）

查询与删除

三、摄像头管理 API

查询全部摄像头（GET /api/monitors）

添加 / 更新（PUT /api/monitor）

应用配置（POST /api/monitor/restart）

开关移动侦测 / 目标检测（PATCH）

四、直播 API

五、录像 API

查询录像段落（GET /api/recording/query）

下载整段录像（GET /api/recording/video/<录像ID>）

缩略图（GET /api/recording/thumbnail/<录像ID>）

拼接时间段下载（GET /vod/vod.mp4）

六、日志查询 API（GET /api/log/query）

七、状态码与错误速查（全部实测）

八、参考链接