Query and download channel snapshots by API

If a business page needs a recent image before choosing a video source, your backend first checks that this user may view the channel. The server captures JPEGs only for online channels with periodic capture enabled. Calling the query does not start a camera stream on demand.

Version boundary: 1.0.0.158 includes scoped client tickets and per-frame url/downloadUrl; the older 1.0.0.157 has only settings/slot query and JPEG reads. Match client and server versions.

Query settings and images

GET /api/v2/channels/{channelId}/snapshots
Authorization: Bearer <platform credential with streams.play>

The response contains settings.enabled/intervalSeconds/keepCount, online, and newest-first frames[] with slot/capturedAt/version. GET /api/v2/channels/{channelId}/snapshots/{slot} returns JPEG. Turning capture off or taking the channel offline does not delete retained images. Changing settings through PUT /snapshots/settings requires channels.manage.

Issue a client ticket

Your backend uses a platform session or API token with streams.play:

POST /api/v2/channels/{channelId}/snapshots/access
Authorization: Bearer <backend platform credential>
Content-Type: application/json

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

The response gives token/channelId/actions/expiresAtUtc. Omitting actions grants only view; lifetime is 30–600 seconds. The client queries with the short-lived ticket as Bearer and receives relative url and downloadUrl values in frames[], carrying only a scoped image ticket. downloadUrl is null without download. URLs may expire or point to an overwritten ring slot; query again for fresh links.

Tickets bind to the channel and its current media source. Revoking the source credential, removing permission, or changing source invalidates them. A short-lived query ticket reads images only; it cannot change settings or issue more tickets. Viewing transfers image bytes, so a view-only user can still save a visible image.

For console behavior and offline grayscale presentation, read the snapshot feature guide.