直播截图

可从您的直播流中捕获静态图像快照，并直接传输到您的对象存储中——支持定时或按需进行截图，直播截图API可以为您提供支持。

该API分为三个可组合的层级：

1. 模板 — 定义截图的方式——如格式、存储、分段、回调等配置。
2. 规则 — 定义何时进行截图——可将模板绑定到域名、发布点或流名。
3. 实时控制 — 可对任意正在直播的流进行截图。

模板是基础。 规则和实时控制均通过其 templateId 引用模板，因此创建模板将是您调用API的第一个步骤。

所有 Screenshot API 共用的速率限制为每位用户每 5 分钟 300 次请求。

创建 Screenshot 模板（Template API）

一个 Screenshot 参数模板 用于指定截图行为，比如输出图片格式（JPG、PNG、BMP）、采样间隔、对象存储目标、文件命名规范，以及用于接收完成通知的回调 URL。

由于每次截图操作（无论是自动还是按需）都需要 templateId。以下为模板相关的API列表。

若模板仍被任何截图规则引用，或者正在用于正在直播的流，则该模板无法删除。请先将模板从所有规则中移除，再进行删除操作。

设置自动截图规则（规则API）

模板创建后，截图规则可实现自动应用。规则将 templateId 绑定至一个或多个直播流，实现直播流上线即自动截图，无需人工干预。

您可以按以下三种粒度对流（Stream）进行定向：

• 域名 — 适用于该域名下的所有流。
• 发布点 — 适用于某一特定应用路径下的所有流。
• 流名 — 仅适用于某一个特定流。

系统采用最长匹配原则应用规则：针对特定流名称的规则优先于域名级规则。这样，您可以灵活设置通用默认值，并在需要时为单个流覆盖相关行为。

如规则正在进行截图，则规则无法被删除。请等待直播结束，截图任务结束后再删除该规则。

按需触发截图（实时控制API）

某些情况下，您也可通过实时控制API手动开始和停止截图。

如何使用：

1. 调用 StartRealTimeSnapshot，传入 templateId 和最多5个直播拉流URL。
2. API 会返回一个 persistentId，用于唯一标识此次截图任务。
3. 截图任务会持续到流自然结束，或你使用相同 persistentId 调用 StopRealTimeSnapshot 进行停止。

请务必保存 Start API 返回的 persistentId，它是提前终止指定会话的唯一方式。