调用 GetSnapshotTask 接口，查询指定抽帧截图任务的详细信息，包括任务状态、目标流、截图间隔及存储配置等。支持查询最近 72 小时内启动的截图任务（包括自动抽帧截图任务）。

注意事项

请求频率：QPS 不得超过 60。

请求说明

请求方式：GET

请求地址：https://rtc.volcengineapi.com?Action=GetSnapshotTask&Version=2023-11-01

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Query

Action String 必选示例值：GetSnapshotTask

接口名称。当前 API 的名称为 GetSnapshotTask。

Version String 必选示例值：2023-11-01

接口版本。当前 API 的版本为 2023-11-01。

AppId String 必选示例值：66****3cf

实时音视频应用的 AppId。可在控制台获取。

RoomId String 必选示例值：Room1

RTC 房间 ID。

TaskId String 必选示例值：Task1

要查询的抽帧截图任务 ID。与开启抽帧截图 StartSnapshot 时设置的保持一致。

自动抽帧任务下，该字段可传入用户 UserId。

返回参数

下表仅列出本接口特有的返回参数，公共返回参数请参见返回结构。

SnapshotTask Object 示例值：-

抽帧截图任务信息。

StartTime Long 示例值：1677227309000

任务开始时间戳，Unix 时间，单位为毫秒。

EndTime Long 示例值：1677227511000

任务结束时间戳，Unix 时间，单位为毫秒。0 表示任务未结束。

Status Long 示例值：3

任务状态。

0：未知异常状态

1：未开始

2：运行中

3：已结束

4：任务运行失败

StopReason String 示例值：IdleTimeOut

任务停止的原因：

返回为空：任务未结束

UnknownStopReason：未知停止原因

StopByAPI：用户主动调用服务端 OpenAPI 停止

StartTaskFailed：任务启动失败

IdleTimeOut：任务超过最大空闲时间

UserDisconnect：自动截图任务中，截图任务对应的客户端用户主动退房。

TargetStreams Object 示例值：-

截图的视频流。

StreamList Object[] 示例值：-

目标流列表。

Index Integer 示例值：0

流的唯一索引，用于在自定义布局中标识该流。在 Layout.regions.StreamIndex 中会引用此 Index 来配置对应流的布局。默认为 0。

在一个 StreamList 中，Stream.Index 不能重复。

UserId String 示例值：user1

目标流所属的用户 ID。在客户端定义的。

StreamType Integer 示例值：0

流的类型：

0（默认值）：普通音视频流。

1：屏幕共享流。

MaxIdleTime Integer 示例值：200

任务最大的空闲超时时间。单位秒。

ImageConfig Object 示例值：-

图片的相关配置：图片格式，尺寸和截图间隔时间。

Format Integer 示例值：0

图片的格式：

0（默认值）：JPEG

1：PNG

Width Integer 示例值：0

截图的宽度，单位为像素。取值范围：[0,1920]，默认值为 0，表示和视频流的实际宽度相同。

Height Integer 示例值：0

截图的高度，单位为像素。取值范围：[0,1080]，默认值为 0，表示和视频流的实际高度相同。

Interval Float 示例值：2.0

相邻两次截图之间的间隔时间，单位为秒，支持传入浮点数，精度为毫秒（0.001s）。

取值范围：[0.1, 600]。

默认值：2.0。

传入值如果超过 3 位小数，会被截断。

StorageConfig Object 示例值：-

存储平台设置。其中 AK、SK 字段不返回。

Type Integer 示例值：0

存储平台类型：

0：火山引擎对象存储 TOS

1：火山引擎视频点播 VOD

2：支持 S3 协议的第三方存储平台

3：VeImageX (当前仅支持抽帧截图功能)

TosConfig Object 示例值：-

TOS 平台配置。

注意

当 Type = 0 （即默认值）时，该字段为必填。

AccountId String 示例值：21****90

TOS 所属的火山引擎主账号 ID。

火山引擎平台账号 ID 查看路径参看查看和管理账号信息。

此账号 ID 为火山引擎主账号 ID。

若你调用 OpenAPI 鉴权过程中使用的 AK、SK 为子用户 AK、SK，账号 ID 也必须为火山引擎主账号 ID，不能使用子用户账号 ID。

Bucket String 示例值：tos-vod-****-16***43

存储桶（Bucket）的名称。在 TOS 控制台获取。

Region Integer 示例值：0

存储桶所在的地域。具体可参见 Region对照表。默认为 0。

ObjectMetadata Object 示例值：-

设置上传到 TOS 的对象的元信息，如 HTTP 头、自定义元数据等，以实现如在线预览文件、缓存控制等功能。

注意

TOS 支持携带指定请求头来修改对象元数据，在下载对象或者 HEAD 对象时，这些值会设置到 HTTP 头域中，并返回给客户端。

AutoSetContentType Boolean 示例值：true

是否根据文件扩展名自动推断并设置 Content-Type。开启后，系统会基于对象名称的后缀（如 .mp4、.jpg、.m3u8）自动设置 MIME 类型。如果无法识别后缀，则不设置该字段。

默认值为 false（不开启）。

ContentDisposition String 示例值：inline

设置 HTTP Content-Disposition 头，用于控制浏览器处理文件的方式。

inline：在浏览器内直接在线显示（如预览图片、播放音频）。

attachment：作为附件下载。

如果留空，则使用 TOS 的默认行为。

CacheControl String 示例值：public, max-age=3600

设置 HTTP Cache-Control 头，用于控制 CDN 和浏览器的缓存行为。

传入格式和取值，参见 Cache-Control。

服务端会去除输入值首尾的空格。

Expires String 示例值：2026-10-21T07:28:00Z

设置 HTTP Expires 头，用于设置资源过期时间。

格式：RFC3339 格式的 UTC 时间字符串。

服务端会校验该时间必须晚于当前服务器时间，否则请求会失败。

若同时设置了 CacheControl，客户端通常会优先采用 CacheControl 的策略。

ContentEncoding String 示例值：gzip

设置 HTTP Content-Encoding 头，用于指示客户端解码方式（如 gzip）。支持的取值，参见 Content-Encoding。

ContentLanguage String 示例值：zh-CN

设置 HTTP Content-Language 头，用于指定内容的语言。

支持的取值，参见 Content-Language。

服务端会去除输入值首尾的空格。

Metadata JSONMap 示例值：{"user-id": "12345"}

自定义元数据，映射到对象存储的自定义 header（如 x-amz-meta-* / x-tos-meta-*）。

Key 规范：

不能为空，且长度不能超过 256 字节。

服务端会自动去除首尾空格并转换为小写。建议使用小写字母和 - 分隔符（例如 user-id）。

Value 规范：服务端会按原始内容存储，不会做任何修改（包括不会去除空格）。

VodConfig Object 示例值：-

点播平台配置。

AccountId String 示例值：210****933

火山引擎平台账号 ID，例如：200000000。

火山引擎平台账号 ID 查看路径参看查看和管理账号信息。

此账号 ID 为火山引擎主账号 ID。

若你调用 OpenAPI 鉴权过程中使用的 AK、SK 为子用户 AK、SK，账号 ID 也必须为火山引擎主账号 ID，不能使用子用户账号 ID。

Region Integer 示例值：0

不同存储平台支持的 Region 不同，具体参看 Region对照表。

Space String 示例值：Storagespace

点播空间名称。

StorageClass Integer 示例值：1

上传到视频点播平台时文件的存储类型：

1：标准存储。

2：归档存储。

3：低频存储。

关于存储类型的详细说明，参看媒资存储存储类型

AutoSetFileExtension Boolean 示例值：false

上传到视频点播平台时, 是否需要根据文件后缀自动设置 FileExtension。关于 FileExtension 的详细说明，参看 FileExtension。

true：需要

false：不需要

CustomConfig Object 示例值：-

第三方存储平台配置。

注意

当 Type = 2 时，该字段为必填。

Vendor Integer 示例值：0

第三方存储服务商：

0：Amazon S3

1：阿里云 OSS

2：华为云 OBS

3：腾讯云 COS

4：七牛云 Kodo

Region Integer 示例值：0

存储桶所在的地域。具体可参见 Region对照表。

Bucket String 示例值：tos-vod-****-16f***43

存储桶的名称。

AccessKey String 示例值：AKL*****jU

第三方存储平台账户的访问密钥（AccessKey）。

SecretKey String 示例值：TVRjMl****aadf==

第三方存储平台账户的私有密钥（SecretKey）。

VeImageXConfig Object 示例值：-

VeImageX 平台配置。

AccountId String 示例值：210****933

VeImageX 所属的火山引擎主账号 ID。

火山引擎平台账号 ID 查看路径参看查看和管理账号信息。

此账号 ID 为火山引擎主账号 ID。

若你调用 OpenAPI 鉴权过程中使用的 AK、SK 为子用户 AK、SK，账号 ID 也必须为火山引擎主账号 ID，不能使用子用户账号 ID。

ServiceId String 示例值：oomo****adgcs

服务 ID。

Region Integer 示例值：0

VeImageX 所属地域。具体可参见 Region对照表。

请求示例

返回示例

错误码

您可访问公共错误码，获取更多错误码信息。