直播截图

直播截图 API可从直播流中抓取静态图片，并将图片存储到您的对象存储桶中。您可以将其用于生成缩略图、直播预览、内容审核抽样和合规留档。

本文介绍如何配置截图行为、为符合条件的直播流自动截图、按需启动截图任务，以及查询任务和生成图片的信息。

开始前准备

• 准备要在截图参数模板中使用的对象存储目标和回调地址。
• 在创建截图规则或启动实时截图前，至少创建一个截图参数模板。
• 如需按需截图，请准备正在直播的流的播放 URL。
• 查询任务时，请使用处理该截图任务的服务区域：cn、us 或 sg。

API 之间如何协同

直播截图流程由四部分组成：

1. 截图参数模板定义如何抓取和存储截图。
2. 截图规则会在直播流匹配规则时，自动将指定模板应用于该流。
3. 实时控制 API用于为正在直播的流按需启动或停止截图任务。
4. 任务查询 API用于查找截图任务、跟踪任务状态，并获取生成图片的信息。

截图参数模板是整个流程的基础。截图规则和实时控制 API 都需要 templateId，因此请先创建模板并保存其 ID。

典型截图流程

1. 创建截图参数模板，并保存返回的 templateId。
2. 选择截图的启动方式：
   • 创建截图规则，在符合条件的直播流开始直播时自动截图。
   • 调用 StartRealTimeSnapshot，为正在直播的流按需启动截图。
3. 保存每个截图任务返回的 persistentId。
4. 使用 QuerySnapshotTaskIds 查询指定时间范围内的任务，或获取任务的 persistentId。
5. 使用 persistentId 调用 QuerySnapshotTaskDetail，查询任务状态和生成的截图文件。
6. 如果您启动了实时截图，并且需要在直播流结束前停止截图，请使用相应的 persistentId 调用 StopRealTimeSnapshot。

创建和管理截图参数模板

截图参数模板用于控制截图的抓取和存储方式。模板可以定义图片格式、采样间隔、对象存储目标、文件命名规则和回调地址。

重要： 当模板仍被生效中的规则引用时，无法删除该模板。删除前，请先解除模板与所有规则的关联。

使用规则实现自动截图

截图规则将 templateId 与直播流关联，使服务能够在符合条件的直播流处于直播状态时自动抓取图片。

您可以按以下三个层级设置规则的匹配范围：

• 域名：匹配指定域名下的直播流。
• 应用名称：匹配某个应用下的直播流。
• 流名称：仅匹配某一条特定直播流。

系统采用最长匹配原则。匹配到特定流的规则优先于应用级规则，应用级规则又优先于域名级规则。您可以先创建覆盖范围较广的默认规则，再为需要不同截图设置的单条流创建更具体的规则。

重要： 规则正在执行截图时无法删除。请等待直播流结束，或先停止截图任务，再删除规则。

启动和停止按需截图

如需为正在直播的流立即抓取图片，而不依赖自动截图规则，请使用实时控制 API。例如，您可以将其用于内容审核事件、用户触发的直播预览或事件留档。

1. 调用 StartRealTimeSnapshot，传入 templateId，并提供最多 5 个正在直播的播放 URL。
2. 保存每个截图任务返回的 persistentId。
3. 等待直播流结束以自然停止截图，或使用该任务的 persistentId 调用 StopRealTimeSnapshot 提前停止。

重要： 请保存所有返回的 persistentId。该 ID 用于停止指定的实时截图任务，也用于后续查询任务详情。

查询截图任务和截图文件

无论是手动启动截图，还是需要验证自动截图结果，都可以使用任务查询 API。通过这些 API，您可以查找任务、确认任务是否完成、排查失败原因，并定位生成的图片。