Live Snapshot

Live Snapshot API captures still images from live streams and stores them in your Object Storage bucket. Use it for thumbnails, live previews, content-moderation samples, and compliance archives.

This guide explains how to configure snapshot behavior, automate capture for matching streams, start a capture session on demand, and retrieve the resulting task and file information.

Before you begin

• Prepare the Object Storage destination and callback endpoint that you want to use in the snapshot template.
• Create at least one snapshot parameter template before you create a rule or start a real-time capture session.
• For on-demand capture, have the delivery URL of an active live stream available.
• When querying tasks, use the service region that processes the snapshot task: cn, us, or sg.

How the APIs fit together

The snapshot workflow has four parts:

1. Snapshot parameter templates define how snapshots are captured and stored.
2. Snapshot rules automatically apply a template when a live stream matches the rule.
3. Real-time controls start or stop an on-demand capture session for an active stream.
4. Task queries find snapshot tasks, monitor their status, and return information about generated image files.

Templates are the foundation. Snapshot rules and real-time controls both require a templateId, so create and save a template before using either workflow.

Typical snapshot workflow

1. Create a snapshot parameter template and save its templateId.
2. Choose how capture starts:
   • Create a snapshot rule to capture automatically when a matching stream is live.
   • Call StartRealTimeSnapshot to start capture for an active stream on demand.
3. Save the persistentId returned for each capture session.
4. Use QuerySnapshotTaskIds to find tasks in a time range or retrieve a task’s persistentId.
5. Use QuerySnapshotTaskDetail with a persistentId to monitor the task and review the generated snapshot files.
6. If you started a real-time session and need to end it before the stream ends, call StopRealTimeSnapshot with the relevant persistentId.

Create and manage snapshot parameter templates

A snapshot parameter template controls how the service captures and stores images. It defines the image format, sampling interval, Object Storage destination, file-naming convention, and callback URL.

Important: You cannot delete a template while an active rule references it. Remove the template from all rules before deleting it.

Automate snapshots with rules

A snapshot rule associates a templateId with live streams so the service captures images automatically while matching streams are live.

You can target a rule at three levels of specificity:

• Domain: applies to streams under the specified domain.
• Application Name: applies to streams under one application.
• Stream Name: applies to one specific stream.

The system uses the longest-match rule. A rule that matches a specific stream takes precedence over a broader application-level rule, and an application-level rule takes precedence over a domain-level rule. Use a broad rule for a default capture policy and a more specific rule when one stream needs different settings.

Important: You cannot delete a rule while it is actively capturing snapshots. Wait for the stream to end or stop the capture session before deleting the rule.

Start and stop on-demand snapshots

Use real-time controls when you need to capture images from an active stream without relying on an automatic rule, such as for a moderation event, a user-triggered preview, or incident archiving.

1. Call StartRealTimeSnapshot with a templateId and up to five active stream delivery URLs.
2. Save the persistentId returned for each capture session.
3. Allow capture to end with the live stream, or call StopRealTimeSnapshot with the session’s persistentId to end it early.

Important: Store every returned persistentId. You need it to stop a specific real-time session and to retrieve the task details later.

Query snapshot tasks and files

Use the task query APIs after starting capture manually or when you need to verify automated capture. They let you find a task, check whether it completed, investigate failures, and locate the generated images.