实时音视频
实时音视频
文档指南
请输入
- 文档首页
实时音视频实时音视频服务端 API 参考音频切片开启音频切片 StartSegment
复制全文
下载 pdf开启音频切片 StartSegment
文档反馈
问问助手调用 StartSegment 接口，对房间内的音频流进行切片处理，并将切片文件存储至指定的云存储平台（火山 TOS 或第三方云存储），可用于内容审核等场景。支持对单路或多路音频流进行切片。
使用说明
- 使用前提：
- 调用该接口前，必须先在控制台上开启音频切片服务。
- 准备好云存储平台信息，所需信息可参见字段 StorageConfig。
- 获取切片任务结果：可通过回调实时获取切片结果。具体操作请参见回调地址，回调事件，请参见 SegmentRealTimeData。
- 自动切片：你可以在控制台上开启自动切片功能，开启该功能后，若未设置业务标识，默认对房间内每个用户都进行全程切片。
- 费用说明：调用本接口会额外产生音频切片费用和音频切片机器人通话费用。详情参见音频切片计费。
注意事项
请求频率：QPS 不得超过 60。
请求说明
- 请求方式：POST
- 请求地址：https://rtc.volcengineapi.com?Action=StartSegment&Version=2023-11-01
调试
API Explorer
您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。
请求参数
Query
Action String 必选 示例值：StartSegment
接口名称。当前 API 的名称为 StartSegment。
Version String 必选 示例值：2023-11-01
接口版本。当前 API 的版本为 2023-11-01。
Body
AppId String 必选 示例值：66****3cf
BusinessId String 可选 示例值：B****3
RoomId String 必选 示例值：Room1
需要音频切片的房间 ID。由客户端生成或指定。
TaskId String 必选 示例值：Task1
切片任务 ID。
由您自定义，用于标识和管理（更新、停止）截图任务。
- 命名规范：符合正则表达式 [a-zA-Z0-9_@\-\.]{1,128}。
- 唯一性规则：在同一个 AppId 和 RoomId 组合下，TaskId 必须唯一。
任务运行中，使用相同 TaskId 重复调用该接口，系统将返回提示而非报错。
MaxIdleTime Integer 可选 示例值：180
任务的空闲超时时间，单位为秒。
任务启动后，系统会自动分配一个后端机器人订阅目标流。如果机器人在房间内始终没有订阅到目标流（例如目标用户不在房间或指定的流停止发布），任务就会处于“空闲状态”。空闲时间超过设定值，任务就会自动结束。
- 取值范围为 [10, 86400]。
- 默认值为 180。
TargetStreams Object 可选 示例值：-
房间内需要切片的音频流。如果参数为空，默认对房间内所有发布的音频流进行切片。最多 17 路音频流。
如果在开启音频切片时指定了多路流，那么，切片时会针对屏幕流在内的每一路流进行切片。
如果切片时，对应流的发布者关闭了麦克风，会产生静音文件，但若开启了切片对齐或忽略静音文件功能，则不会产生静音文件。
StreamList Object[] 可选 示例值：-
目标流列表。
Index Integer 可选 示例值：0
流的唯一索引，用于在自定义布局中标识该流。在 Layout.regions.StreamIndex 中会引用此 Index 来配置对应流的布局。默认为 0。
在一个 StreamList 中，Stream.Index 不能重复。
UserId String 必选 示例值：user1
目标流所属的用户 ID。在客户端定义的。
StreamType Integer 可选 示例值：0
流的类型：
- 0（默认值）：普通音视频流。
- 1：屏幕共享流。
Duration Integer 可选 示例值：20
每个音频切片的时长。取值范围为 [1, 600]，单位为秒，默认值为 20。
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）。
FileNameConfig Object 可选 示例值：-
截图文件的命名与路径规则设置。
文件最终的生成路径与名称结构为：{Prefix} + {Pattern} + 随机数。
示例：
Prefix 设为dir1/dir2/，Pattern 设为 {TaskId}_{RoomId}，若文件的 TaskId = task1、RoomId = 1234 且生成的随机数为 c4694fa1，则生成的文件名为：dir1/dir2/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 开启版本控制，允许文件名重复，防止被覆盖的情况发生。
Control Object 可选 示例值：-
切片高级配置。
Align Boolean 可选 示例值：false
是否开启切片对齐功能，你可以使用该功能，对齐各个用户音频切片的开始和结束时刻。
- false：关闭音频切片对齐。在某个切片周期中，如果用户有发送音频流的行为，即生成音频切片。如果用户在切片的周期中，有部分时间未发布音频，返回的音频切片时长会小于切片周期。各个用户音频切片开始时间不一定一致。
- true：开启音频切片对齐。在某个切片周期中，如果用户有发送音频流的行为，即生成音频切片。切片长度和切片周期相等，且各个用户音频切片开始的时间一致。如果用户在切片的周期中，有部分时间未发布音频，切片长度不变，这段时间呈现静音帧。如果用户在某个切片周期中始终没有发布音频，则不生成音频切片。
默认值为false。
Mixed Boolean 可选 示例值：false
是否开启合流切片功能。
- False：只会对 TargetStreams 中指定的音频流分别切片。
- True：除了会对 TargetStreams 中指定的音频流分别切片，还会对指定的音频流进行混音，生成合流切片，合流切片对应的用户名为 mixed。此时，任务创建后，不管是否有人上麦，会持续回调混音切片。
默认值为 false。
本地麦克风录制和远端所有用户混音后的音频数据回调：
IgnoreSilence Boolean 可选 示例值：false
是否忽略静音文件。
- true：忽略。
- false：不忽略。
默认值为 false
RedundantDuration Integer 可选 示例值：2
冗余切片时长，单位为毫秒。
当前 RTC 按照传入的Duration值进行固定时长切片,可能存在敏感词被截断，未被识别的情况。此时你可以添加冗余切片，即上一段切片的末尾指定时长，来避免此情况，此时切片的时长变为RedundantDuration + Duration。
例如：当 Duration = 20，redundantDuration = 3 时，最终输出的前三个文件时长为：[0-20], [17-40], [37-60]。
VadConfig Object 可选 示例值：-
VAD（Voice Activity Detection）人声活动检测配置。
Enable Boolean 可选 示例值：false
是否开启 VAD 人声活动检测功能。
- true：开启。系统将对音频切片进行人声检测，未检测到人声的切片将被过滤，不进行存储或回调，以节省存储成本和下游处理资源。
- false（默认值）：关闭。所有音频切片均正常存储和回调，不进行人声检测过滤。
Mode Integer 可选 示例值：2
VAD 检测的严格程度。取值范围为 [0, 3]，值越大，检测越严格，越倾向于将模糊的音频判断为非人声。
- 0：最宽松。召回率最高，不容易漏掉人声，但可能将噪声误判为人声。
- 1：较宽松。
- 2（默认值）：均衡模式。在召回率和准确率之间取得较好的平衡。
- 3：最严格。准确率最高，误判最少，但可能会漏掉较弱的人声。
注意
该字段仅在 Enable 为 true时生效。
SpeechRatioThreshold Float 可选 示例值：0.15
语音帧占比阈值。即一个音频切片被判定为"有人声"所需的最小语音时长占比。当 VAD 检测到的语音帧数占总帧数的比例达到或超过此阈值时，该切片才会被判定为包含人声。
- 取值范围：(0.0, 1.0]。值越小检测更灵敏，更容易将切片判定为有人声；值越大检测更保守，需要更明显的语音活动才能将切片判定为有人声。
- 默认值：0.15。
注意
该字段仅在 Enable 为 true时生效。
Identifier String 可选 示例值：Identifier1
自定义文件前缀。
切片文件名由 Identifier + UserId + 时间戳 + 序号组成。默认情况下 Identifier 为 随机生成的 UUID。在自定义文件名时，Identifier 的命名规则符合正则表达式：[a-zA-Z0-9_@\-\.]{1,128}。
在自定义文件名时，你需确保 Identifier 命名全局唯一，否则在 TOS 平台会因文件名重复被覆盖。
Handle Boolean 可选 示例值：false
是否在开启音视频切片时，立刻开始切片。
- true：在开启音视频切片时，立刻开启切片。
- false ：在开启音视频切片时，不开始切片，热启动任务。
默认值为 true。
返回参数
其中返回值 Result 仅在请求成功时返回 ok，失败时为空。
请求示例
POST https://rtc.volcengineapi.com?Action=StartSegment&Version=2023-11-01
{
"AppId": "66****3cf",
"BusinessId": "B****3",
"RoomId": "Room1",
"TaskId": "Task1",
"MaxIdleTime": 200,
"TargetStreams": {
"StreamList": [
{
"UserId": "user1",
"StreamType": 0
},
{
"UserId": "user1",
"StreamType": 1
}
]
},
"Duration": 20,
"StorageConfig": {
"Type": 2,
"CustomConfig": {
"Vendor": 0,
"Region": 0,
"Bucket": "tos-vod-cn-v-16fd9e8343******",
"AccessKey": "AKL****jU",
"SecretKey": "TV****="
},
"Control": {
"Align": true,
"Mixed": true,
"RedundantDuration": 2,
"IgnoreSilence": true
}
}
}
返回示例
{
"Result": "ok",
"ResponseMetadata": {
"RequestId": "20230604110420",
"Action": "StartSegment",
"Version": "2023-11-01",
"Service": "rtc",
"Region": "cn-north-1"
}
}
错误码
最近更新时间：2026.07.27 21:14:36
这个页面对您有帮助吗？
有用
有用
无用
无用