Live Screenshot

Capture still-image snapshots from your live streams and deliver them straight to your object storage — on a schedule, on every stream, or on demand. The Live Screenshot API powers common workflows like video thumbnails, live previews, content moderation sampling, and compliance archiving.

The API is organized into three composable layers:

1. Templates — Define how screenshots are captured — format, storage, segmentation, callbacks.
2. Rules — Define when capture happens — bind a template to domains, apps, or streams.
3. Real-Time Controls — Trigger ad-hoc capture on any active stream.

Templates are the foundation. Both Rules and Real-Time Controls reference a template by its templateId, so your first API call will always be creating a template.

All Screenshot APIs share a combined rate limit of 300 requests per 5 minutes, per user.

Create Screenshot Templates (Template APIs)

A Screenshot Parameter Template tells how capture should behave: the output image format (JPG, PNG, BMP), the sampling interval, the Object Storage destination, file-naming conventions, and the callback URL that receives completion notifications.

Because every screenshot — automated or on-demand — requires a templateId, templates are always step one.

Warning: A template cannot be deleted while it is referenced by any active rule. Remove the template from all rules first, then delete it.

Set Up Automated Screenshot Rules (Rule APIs)

Once a template exists, Screenshot Rules automate its application. A rule binds a templateId to one or more live streams so that capture begins the moment those streams go live — no manual intervention required.

You can target streams at three levels of specificity:

• Delivery Domain — applies to every stream under the domain.
• Application Name — applies to every stream under a specific application path.
• Stream Name — applies to a single, specific stream.

The system applies rules using the longest match principle: a rule targeting a specific stream name takes precedence over a broader domain-level rule. This lets you set wide defaults and override behavior for individual streams when needed.

Warning: A rule cannot be deleted while it is actively capturing screenshots. Either wait for the stream to end or stop the capture session first.

Trigger Screenshots On Demand (Real-Time Control APIs)

For capture outside of any automated rule — moderation events, user-triggered previews, incident archiving — the Real-Time Control APIs start and stop sessions manually.

How the workflow connects:

1. Call StartRealTimeSnapshot with a templateId and up to 5 stream delivery URLs.
2. The API returns a persistentId, which uniquely identifies that capture session.
3. Capture runs until the stream ends naturally, or until you call StopRealTimeSnapshot with the same persistentId.

Always store the persistentId returned by the Start API. It is the only way to stop a specific session early.