本文档 API 接口为最新版本接口，后续相关功能的新增都会在此更新，推荐使用最新版本接口。旧版接口文档请参考历史版本。
注意
在使用抽帧截图功能前，你必须已经在控制台上开启抽帧截图服务。
在实时音视频通话场景中，为了存证或鉴别非法信息等目的，你可能会需要对房间内的实时互动进行定期截图，你可通过调用此接口实现。
通过调用此接口，你可以设定应用标志、房间 ID、截图任务 ID 及目标视频流等信息，来指定截图的具体配置，包括截图格式、尺寸、间隔时间以及存储平台等。截图结果将上传至你指定的存储平台，并通过你在控制台设置的回调地址接收元数据回调。
你也可以在控制台上开启自动抽帧功能，开启该功能后，若未设置业务标识，默认对房间内每个用户都进行全程抽帧截图。抽帧切片结果会上传到你选择的存储平台上。
请求频率：QPS 不得超过 150。
下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。
参数 | 类型 | 是否必选 | 示例值 | 描述 |
|---|---|---|---|---|
Action | String | 是 | StartSnapshot | 接口名称。当前 API 的名称为 StartSnapshot。 |
Version | String | 是 | 2023-11-01 | 接口版本。当前 API 的版本为 2023-11-01。 |
参数 | 类型 | 是否必选 | 示例值 | 描述 |
|---|---|---|---|---|
AppId | String | 是 | 661e****543cf | 你的音视频应用的唯一标志，参看获取 AppId。 |
BusinessId | String | 否 | B****23 | 业务标识 |
RoomId | String | 是 | Room1 | 房间 ID，是房间的唯一标志 |
TaskId | String | 是 | Task1 | 截图任务 ID。你可以自行设定
关于 TaskId 及以上 Id 字段的命名规则符合正则表达式： TaskId 重复调用开始接口不会导致请求失败，BaseResponse.Result 会提示 The task has been started. Please do not call the startup task interface repeatedly。 |
TargetStreams | Object | 否 | - | 你可以通过本参数设定需要截图的视频流。如果参数为空，默认对房间内所有人进行截图。最多17路视频流。 |
StreamList | Object[] | 否 | - | 音视频流列表，由 Stream组成，可以为空。为空时，表示订阅房间内所有流。在一个 StreamList 中，Stream.Index 不能重复。 |
Index | Integer | 否 | 0 | 在自定义布局中，使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中，你需要使用 Index 指定对应流的布局设置。 |
UserId | String | 是 | user1 | 用户 ID，表示这个流所属的用户。 |
StreamType | Integer | 否 | 0 | 流的类型。支持取值及含义如下：
0。 |
MaxIdleTime | Integer | 否 | 180 | 任务最大的空闲超时时间。如果抽帧截图任务订阅的所有流都已停止发布，那么任务会在空闲时间超过设定值后自动停止。值的范围为 [1, 86400] ，单位为秒，默认值为 180。 |
ImageConfig | Object | 否 | - | 图片的相关配置：图片格式，尺寸和截图间隔时间。 如果截图时，对应流的尺寸（长宽）和设置的截图尺寸（长宽）不一致，那么，视频流原始截图会按比例缩放为指定的尺寸。 |
Format | Integer | 否 | 0 | 图片的格式。支持取值及含义如下：
0。 |
Width | Integer | 否 | 0 | 实际使用视频帧的宽度，取值范围为 [0, 1920]，单位为像素。默认值为 0，表示和视频流的实际宽度相同。 |
Height | Integer | 否 | 0 | 实际使用视频帧的高度，取值范围为 [0, 1920]，单位为像素，默认值为 0，此时，和视频流的实际高度相同。 |
Interval | Integer | 否 | 2 | 相邻截图之间的间隔时间，取值范围为 [1, 600]，单位为秒，默认值为 2。 |
StorageConfig | Object | 是 | - | 存储平台设置。当前截图功能仅支持存储到火山引擎对象存储TOS 、veImageX和 Amazon S3、 阿里云 OSS、华为云 OBS、腾讯云 COS 或七牛云 Kodo第三方存储平台]，即 Type只可取值 0，2或3。 |
Type | Integer | 否 | 0 | 存储平台类型
|
TosConfig | Object | 否 | - | Tos 平台设置。当 Type = 0 时，需正确设置 TosConfig 的值，否则请求会报错 |
AccountId | String | 是 | 210****990 | 火山引擎平台账号 ID，例如：
|
Region | Integer | 否 | 0 | 不同存储平台支持的 Region 不同，具体参看 Region对照表 默认值为0。 |
Bucket | String | 是 | tos-vod-c****16fd9e8343 | 存储桶的名称。 |
CustomConfig | Object | 否 | - | 第三方存储平台设置。当 Type = 2时，需正确设置 CustomConfig 的值，否则请求会报错 |
Vendor | Integer | 否 | 0 | 第三方云存储平台。支持取值及含义如下：
0。 |
Region | Integer | 否 | 0 | 不同存储平台支持的 Region 不同，具体参看 Region对照表 默认值为0。 |
Bucket | String | 是 | tos-vod-c****16fd9e8343 | 存储桶的名称。 |
AccessKey | String | 是 | AKLTMzV****NDcyNjU | 第三方存储平台账号的密钥。需确保此账号对存储桶有写权限。不建议开启读权限 |
SecretKey | String | 是 | TVRjMl****aadf== | 第三方存储平台账号的密钥 |
VeImageXConfig | Object | 否 | - | VeImageX 平台设置。当 Type = 3时，需正确设置 VeImageXConfig 的值，否则请求会报错 |
AccountId | String | 是 | 210****933 | 火山引擎平台账号 ID，例如：
|
Region | Integer | 否 | 0 | 不同存储平台支持的 Region 不同，具体参看 Region对照表 默认值为0。 |
ServiceId | String | 是 | oomo****adgcs |
本接口无特有的返回参数。公共返回参数请见返回结构。
其中返回值 Result 仅在请求成功时返回 ok,失败时为空。
POST https://rtc.volcengineapi.com?Action=StartSnapshot&Version=2023-11-01 { "AppId": "661e****543cf", "BusinessId": "B****23", "RoomId": "Room1", "TaskId": "Task1", "TargetStreams": { "StreamList": [ { "UserId": "user1", "StreamType": 0 }, { "UserId": "user2", "StreamType": 0 } ] }, "MaxIdleTime": 180, "ImageConfig": { "Format": 0, "Width": 800, "Height": 800, "Interval": 2 }, "StorageConfig": { "Type": 3, "VeImageXConfig": { "AccountId": "210****990", "Region": 0, "ServiceId": "oomo****adgcs" } } }
{ "Result": "ok", "ResponseMetadata": { "RequestId": "20230****10420", "Action": "StartSnapshot", "Version": "2023-11-01", "Service": "rtc", "Region": "cn-north-1" } }
您可访问公共错误码，获取更多错误码信息。