AKStream.Next · 文档中心

Periodic channel snapshots: view, download, and short-lived access

Periodic channel snapshots: view, download, and short-lived access

Periodic snapshots let users inspect a channel's recent image without opening a live player, for example before choosing a video source. Each image is a scheduled JPEG, not the current video frame or a recording.

Enable capture and check the result

  1. Open Asset details → select a channel → Channel overview → Periodic snapshots.
  2. Enable background capture, set the interval and retention count, and save. Capture is off by default; the default interval is 10 seconds and retention is two rotating images.
  3. Once the channel is online, wait one interval and check the image and capture time. The server processes only online channels with capture enabled.

Setting the interval or retention count to zero stops new captures; existing images remain readable. The page displays retained images in grayscale when the channel is offline, without changing the original color JPEG. Each channel retains no more than its configured count, overwriting old slots in a ring.

Query settings and images

Release 1.0.0.158 provides GET /api/v2/channels/{channelId}/snapshots. It returns settings.enabled, settings.intervalSeconds, settings.keepCount, online, each image's slot, UTC capturedAt, version, and available view/download URLs. Use GET /api/v2/channels/{channelId}/snapshots/{slot} to read JPEG. Query/read require streams.play; settings PUT /api/v2/channels/{channelId}/snapshots/settings requires channels.manage. The older 1.0.0.157 lacked scoped image tickets and URL fields.

The short-lived ticket and image URL fields below are available from 1.0.0.158; check the actually installed server version.

Issue a short-lived ticket to a client

Your backend first decides whether the business user may see the channel. It then uses a platform session or API token with streams.play to issue a ticket:

POST /api/v2/channels/{channelId}/snapshots/access
Authorization: Bearer <platform session or business API token>
Content-Type: application/json

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

Allowed actions are view and download; omitting them grants only view. The default lifetime is 120 seconds, constrained to 30–600 seconds. The response contains token, channelId, actions, and expiresAtUtc. Never deliver a long-lived API token to a browser or mobile client.

Query snapshots with Authorization: Bearer <short-lived ticket>. Each frames[] entry also returns relative url and downloadUrl values containing the short-lived image ticket. downloadUrl serves a JPEG with an attachment filename, and is null when the ticket lacks download.

The ticket is bound to one channel and its current media source. Reauthorize when it expires, the source session/API token is revoked, playback permission is removed, or the channel changes source. A URL for an overwritten ring slot returns 404. Do not publish or cache credential-bearing image URLs. Viewing already transfers JPEG bytes to the viewer; the download action controls the dedicated download URL and response, not a viewer's ability to save an image they can see.

If images are missing

  • Offline channel: inspect retained images and their capture times, then wait for the channel to return online.
  • Enabled but no images: wait one interval and check that the channel has playable video and that the page reports no capture error.
  • HTTP 401 or 403: check ticket expiry, the source credential, and current streams.play permission.
  • HTTP 404 for an image URL: the ring slot may have been overwritten; query the list again for a fresh URL.