AKStream.Next · 文档中心

通道周期截图：查看、下载与短时授权

通道周期截图：查看、下载与短时授权

周期截图适合在不打开实时播放器时查看通道最近的画面，例如选择一个候选视频源。图片是定时生成的静态 JPEG，不代表当前帧，也不替代录像。

开启截图并核对结果

  1. 进入 资产详情 → 选择通道 → 通道概览 → 周期截图。
  2. 勾选“启用后台截图”，设置周期和保留数量，然后保存。默认关闭；周期默认 10 秒、循环保留 2 张。
  3. 通道在线后等待一个截图周期，核对图片和拍摄时间。后台只处理已启用截图的在线通道。

周期或保留数量设为 0 即停止生成；已有图片仍可查看。离线时页面以灰度显示已保留的图片，原始 JPEG 不会被改成灰度。每个通道最多保留设定数量的图片，旧槽位会被循环覆盖。

查询设置与图片

1.0.0.158 提供 GET /api/v2/channels/{channelId}/snapshots：返回 settings.enabled、settings.intervalSeconds、settings.keepCount、online，以及每张图片的 slot、UTC capturedAt、version 和可用时的预览/下载地址。调用 GET /api/v2/channels/{channelId}/snapshots/{slot} 读取对应 JPEG。查询和读取需要 streams.play 权限；修改设置的 PUT /api/v2/channels/{channelId}/snapshots/settings 需要 channels.manage。旧 1.0.0.157 没有短时图片票据和新增地址字段。

下述短时票据与图片 URL 字段从 1.0.0.158 开始提供；调用前核对服务端实际安装版本。

给第三方客户端签发短时票据

业务后端先判断业务用户是否有权查看该通道，再使用具备 streams.play 权限的平台会话或 API Token 签发票据：

POST /api/v2/channels/{channelId}/snapshots/access
Authorization: Bearer <平台会话或业务 API Token>
Content-Type: application/json

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

actions 只允许 view、download；省略时仅含 view。有效期默认 120 秒，可设 30–600 秒。响应包含 token、channelId、actions、expiresAtUtc。不要把长期 API Token 交给浏览器或移动端。

客户端使用 Authorization: Bearer <短时票据> 查询截图。每项 frames[] 另外返回站内相对的 url 和 downloadUrl，其中包含短时图片票据；点击 downloadUrl 会得到带附件文件名的 JPEG。票据没有 download 动作时，downloadUrl 为 null。

票据只适用于指定通道及当前视频源。到期、原会话/API Token 被撤销、观看权限被收回或通道换源后，需要重新授权。截图槽位被新图覆盖后，旧 version 的地址返回 404。地址中带有短时凭据，不要公开转发或长期缓存。图片预览已向查看者交付 JPEG 字节，因此 download 动作控制专用下载地址与附件响应，不能阻止查看者另存已看到的图片。

看不到图片时

  • 通道离线：显示已保留的旧图片和拍摄时间，等待通道上线后生成新图。
  • 已启用但没有图片：等待至少一个周期，再检查通道是否有可播放的视频流及页面提示的截图错误。
  • 返回 401 或 403：核对票据是否过期、原凭据和 streams.play 权限是否仍有效。
  • 图片地址返回 404：该槽位可能已循环覆盖；重新查询截图列表获取最新地址。