用 API 查询和下载通道截图

如果业务页面需要在选视频源前展示最近画面，先由业务后端确认用户可以观看该通道。平台只对已经启用截图且在线的通道定时生成 JPEG；请求接口不会临时启动一条摄像机流。

**版本边界：**1.0.0.158 已包含短时客户端票据和每帧的 url/downloadUrl；旧 1.0.0.157 只提供设置、槽位查询和 JPEG 读取。客户端和服务端须用对应版本。

查询设置与图片

GET /api/v2/channels/{channelId}/snapshots
Authorization: Bearer <具有 streams.play 权限的平台凭据>

响应包含 settings.enabled/intervalSeconds/keepCount、online 和按时间倒序的 frames[]，每项有 slot/capturedAt/version。GET /api/v2/channels/{channelId}/snapshots/{slot} 返回 JPEG。关闭截图或通道离线不会自动删除已保留的图片。设置由 PUT /snapshots/settings 修改，需要 channels.manage。

为客户端签短时票据

业务后端持有有 streams.play 权限的平台会话或 API Token，按通道签票：

POST /api/v2/channels/{channelId}/snapshots/access
Authorization: Bearer <后端平台凭据>
Content-Type: application/json

{"actions":["view","download"],"lifetimeSeconds":120}

返回 token/channelId/actions/expiresAtUtc。省略动作时只给 view；有效期 30–600 秒。客户端用返回的短时票据作为 Bearer 再调查询接口，frames[] 增加含短时票据的站内相对 url 与 downloadUrl。缺少 download 动作时 downloadUrl 为 null。图片地址可直接打开或下载，但可能因票据过期或循环槽位被覆盖而失效，应重新查询。

票据仅绑定当前通道和当前媒体源；原凭据撤销、权限收回或换源会使它失效。短时查询票据只允许读取图片，不能改设置或再次签票。预览同样传输图片字节，所以“仅 view”不可能阻止查看者另存图片。

页面操作与离线灰度效果见周期截图功能指南。