实时音视频
实时音视频
文档指南
请输入
- 文档首页
实时音视频实时音视频服务端 API 参考抽帧截图开启抽帧截图 StartSnapshot
复制全文
下载 pdf开启抽帧截图 StartSnapshot
文档反馈
问问助手调用 StartSnapshot 接口，对房间内的视频流进行周期性截图，并将图片存储到指定的云存储平台。支持对全部或指定用户的视频流进行截图，并可自定义图片格式、尺寸和截图间隔。
使用说明
- 使用前提：调用该接口前，必须先在控制台上开启抽帧截图服务。
- 如何获取截图结果：可通过回调实时获取截图结果。具体操作请参见回调地址，回调事件，请参见SnapshotRealTimeData。
注意事项
请求频率：QPS 不得超过 150。
请求说明
- 请求方式：POST
- 请求地址：https://rtc.volcengineapi.com?Action=StartSnapshot&Version=2023-11-01
调试
API Explorer
您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。
请求参数
Query
Action String 必选 示例值：StartSnapshot
接口名称。当前 API 的名称为 StartSnapshot。
Version String 必选 示例值：2023-11-01
接口版本。当前 API 的版本为 2023-11-01。
Body
AppId String 必选 示例值：66****3cf
BusinessId String 可选 示例值：B****3
RoomId String 必选 示例值：Room1
需要截图的 RTC 房间 ID。
TaskId String 必选 示例值：Task1
截图任务 ID。
由您自定义，用于标识和管理（更新、停止）截图任务。
- 命名规范：符合正则表达式 [a-zA-Z0-9_@\-\.]{1,128}。
- 唯一性规则：在同一个 AppId 和 RoomId 组合下，TaskId 必须唯一。
任务运行中，使用相同 TaskId 重复调用该接口，系统将返回提示而非报错。
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 可选 示例值：180
任务的空闲超时时间，单位为秒。
任务启动后，当任务订阅的所有流都停止推流后（例如目标用户不在房间或指定的流停止发布），任务就会处于“空闲状态”。若空闲时间超过此设定值，任务将自动停止。
- 取值范围：[10, 86400]。
- 默认值：180。
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 必选 示例值：-
存储平台设置。
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
ObjectMetadata Object 可选 示例值：-
设置上传到 TOS 的对象的元信息，如 HTTP 头、自定义元数据等，以实现如在线预览文件、缓存控制等功能。
注意
TOS 支持携带指定请求头来修改对象元数据，在下载对象或者 HEAD 对象时，这些值会设置到 HTTP 头域中，并返回给客户端。
AutoSetContentType Boolean 可选 示例值：true
默认值为 false（不开启）。
ContentDisposition String 可选 示例值：inline
- inline：在浏览器内直接在线显示（如预览图片、播放音频）。
- attachment：作为附件下载。
- 如果留空，则使用 TOS 的默认行为。
CacheControl String 可选 示例值：public, max-age=3600
设置 HTTP Cache-Control 头，用于控制 CDN 和浏览器的缓存行为。
- 传入格式和取值，参见 Cache-Control。
- 服务端会去除输入值首尾的空格。
Expires String 可选 示例值：2026-10-21T07:28:00Z
- 格式：RFC3339 格式的 UTC 时间字符串。
- 服务端会校验该时间必须晚于当前服务器时间，否则请求会失败。
- 若同时设置了 CacheControl，客户端通常会优先采用 CacheControl 的策略。
ContentEncoding String 可选 示例值：gzip
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 规范：服务端会按原始内容存储，不会做任何修改（包括不会去除空格）。
CustomConfig Object 可选 示例值：-
第三方存储平台配置。
注意
当 Type = 2 时，该字段为必填。
Vendor Integer 必选 示例值：0
第三方存储服务商：
- 0：Amazon S3
- 1：阿里云 OSS
- 2：华为云 OBS
- 3：腾讯云 COS
- 4：七牛云 Kodo
Region Integer 可选 示例值：0
Bucket String 必选 示例值：tos-vod-****-16f***43
存储桶的名称。
AccessKey String 必选 示例值：AKL*****jU
第三方存储平台账户的访问密钥（AccessKey）。
SecretKey String 必选 示例值：TVRjMl****aadf==
第三方存储平台账户的私有密钥（SecretKey）。
VeImageXConfig Object 可选 示例值：-
VeImageX 平台配置。
注意
当 Type = 3 时，该字段为必填。
AccountId String 必选 示例值：210****933
VeImageX 所属的火山引擎主账号 ID。
- 火山引擎平台账号 ID 查看路径参看查看和管理账号信息。
- 此账号 ID 为火山引擎主账号 ID。
- 若你调用 OpenAPI 鉴权过程中使用的 AK、SK 为子用户 AK、SK，账号 ID 也必须为火山引擎主账号 ID，不能使用子用户账号 ID。
ServiceId String 必选 示例值：oomo****adgcs
服务 ID。可在 VeImageX 控制台获取。
Region Integer 可选 示例值：0
FileNameConfig Object 可选
截图文件的命名与路径规则设置。
文件最终的生成路径与名称结构为：{Prefix} + {Pattern} + 随机数。
示例：
Prefix 设为dire1/dire2/，Pattern 设为 {TaskId}_{RoomId}，
若文件的 TaskId = task1、RoomId = 1234 且生成的随机数为 c4694fa1，则生成录制文件的文件名为：dire1/dire2/task1_1234_c4694fa1.mp4。
Prefix String[] 可选 示例值：["dir1","dir2"]
路径前缀，用于定义目录层级。例如，取值 ["dir1", "dir2"]，则会生成路径 dir1/dir2/。
总长度上限 128 字符，仅支持大小写字母和数字。
Pattern String 可选 示例值：{TaskId}_{RoomId}_{UserId}_{Type}_{StartTime}_{Duration}_{Random}
自定义文件名模版，支持通过变量定义。
- 支持的变量：
- 对单流切片：{TaskId}、{RoomId}、{UserId}、{Type}、{StartTime}、{Duration}。
- 对多流切片：{TaskId}、{RoomId}、{StartTime}、{Duration}。
- 限制：128 个字符；请勿在 Pattern 中包含文件后缀名（如 .mp4 或 .jpg）。
- 若此参数留空，系统将应用默认命名规则。默认命名规则及变量含义，参见自定义文件名。
注意
如果设置了 Pattern，需自行保证最终文件名的唯一性，否则在 TOS 或第三方存储平台上同名文件将被覆盖；你也可以给对应 bucket 开启版本控制，允许文件名重复，防止被覆盖的情况发生。
返回参数
其中返回值 Result 仅在请求成功时返回 ok，失败时为空。
请求示例
POST https://rtc.volcengineapi.com?Action=StartSnapshot&Version=2023-11-01
{
"AppId": "66****3cf",
"BusinessId": "B****3",
"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": "2100068990",
"Region": 0,
"ServiceId": "oomoeqhdadgcs"
}
}
}
返回示例
{
"Result": "ok",
"ResponseMetadata": {
"RequestId": "20230604110420",
"Action": "StartSnapshot",
"Version": "2023-11-01",
"Service": "rtc",
"Region": "cn-north-1"
}
}
错误码
最近更新时间：2026.08.21 14:52:13
这个页面对您有帮助吗？
有用
有用
无用
无用