实时音视频
实时音视频
文档指南
请输入
- 文档首页
实时音视频实时音视频服务端 API 参考音频切片查询音频切片任务状态 GetSegmentTask
复制全文
下载 pdf查询音频切片任务状态 GetSegmentTask
文档反馈
问问助手调用 GetSegmentTask 接口，查询指定音频切片任务的详细信息（含自动切片任务），包括任务状态、目标流、切片时长及高级配置等。支持查询 72 小时内启动的音频切片任务。
注意事项
请求频率：QPS 不得超过 60。
请求说明
- 请求方式：GET
- 请求地址：https://rtc.volcengineapi.com?Action=GetSegmentTask&Version=2023-11-01
调试
API Explorer
您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。
请求参数
Query
Action String 必选 示例值：GetSegmentTask
接口名称。当前 API 的名称为 GetSegmentTask。
Version String 必选 示例值：2023-11-01
接口版本。当前 API 的版本为 2023-11-01。
AppId String 必选 示例值：66****3cf
RoomId String 必选 示例值：Room1
房间 ID。
TaskId String 必选 示例值：Task1
要查询的音频切片任务 ID。自动切片任务下，该字段可传入用户 UserId。
返回参数
SegmentTask Object 示例值：-
音频切片任务信息。
StartTime Long 示例值：1677477732000
任务开始时间戳，Unix 时间，单位为毫秒。
EndTime Long 示例值：0
任务结束时间戳，Unix 时间，单位为毫秒。0 表示任务未结束。
Status Long 示例值：2
任务状态。
- 0：未知异常状态
- 1：未开始
- 2：运行中
- 3：已结束
- 4：任务运行失败
StopReason String 示例值：StopByAPI
任务停止的原因。
- 返回为空：表示任务未结束
- UnknownStopReason：未知停止原因
- StopByAPI：用户主动调用 服务端 OpenAPI 停止
- StartTaskFailed：任务启动失败
- IdleTimeOut：任务超过最大空闲时间
- UserDisconnect：自动切片任务中，切片任务对应的客户端用户主动退房。
MaxIdleTime Integer 示例值：600
任务最大的空闲超时时间。
TargetStreams Object 示例值：-
切片的音频流。
StreamList Object[] 示例值：-
目标视频流列表。
Index Integer 示例值：0
视频流的唯一索引，用于在自定义布局中标识该视频流。在 Layout.regions.StreamIndex 中会引用此 Index 来配置对应视频流的布局。
在一个 StreamList 中，Stream.Index 不能重复。
UserId String 示例值：user1
目标视频流所属的用户 ID。
StreamType Integer 示例值：0
流的类型：
- 0：普通音视频流。
- 1：屏幕共享流。
Duration Integer 示例值：40
每个音频切片的时长。
StorageConfig Object 示例值：-
存储平台设置。其中 AK、SK 字段不返回。
Type Integer 示例值：0
存储平台类型：
- 0：火山引擎对象存储 TOS
- 1：火山引擎视频点播 VOD
- 2：支持 S3 协议的第三方存储平台
- 3：VeImageX (当前仅支持抽帧截图功能)
TosConfig Object 示例值：-
TOS 平台配置。
AccountId String 示例值：210****990
TOS 所属的火山引擎主账号 ID。
Bucket String 示例值：tos-vod-****-16***43
存储桶（Bucket）的名称。
Region Integer 示例值：0
VodConfig Object 示例值：-
点播平台配置。
AccountId String 示例值：210****933
火山引擎平台账号 ID，例如：200000000。
- 火山引擎平台账号 ID 查看路径参看查看和管理账号信息。
- 此账号 ID 为火山引擎主账号 ID。
- 若你调用 OpenAPI 鉴权过程中使用的 AK、SK 为子用户 AK、SK，账号 ID 也必须为火山引擎主账号 ID，不能使用子用户账号 ID。
Region Integer 示例值：0
Space String 示例值：Storagespace
点播空间名称。
AutoSetFileExtension Boolean 示例值：false
- true：需要
- false：不需要
CustomConfig Object 示例值：-
第三方存储平台配置。
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 平台配置。
AccountId String 示例值：210****933
VeImageX 所属的火山引擎主账号 ID。
ServiceId String 示例值：oomo****adgcs
服务 ID。
Region Integer 示例值：0
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]。
Identifier String 示例值：getsegmenttask
自定义文件前缀。
Handle Boolean 示例值：true
是否在开启音视频切片时，立刻开始切片。
请求示例
GET https://rtc.volcengineapi.com?Action=GetSegmentTask&Version=2023-11-01&AppId=66****3cf&RoomId=Room1&TaskId=Task1
返回示例
{
"Result": {
"SegmentTask": {
"StartTime": 1677477732000,
"EndTime": 0,
"Status": 2,
"StopReason": "",
"TargetStreams": {
"StreamList": [
{
"Index": 0,
"UserId": "user0",
"StreamType": 0
},
{
"Index": 1,
"UserId": "user1",
"StreamType": 0
}
]
},
"Handle": true,
"Identifier": "getsegmenttask",
"MaxIdleTime": 600,
"Duration": 40,
"Control": {
"Align": true,
"Mixed": true,
"RedundantDuration": 3,
"IgnoreSilence": true
},
"StorageConfig": {
"Type": 0,
"TosConfig": {
"AccountId": "2100068990",
"Region": 0,
"Bucket": "tos-vod-cn-v-16fd9e8343******"
},
"VodConfig": {
"Region": 0
},
"VeImageXConfig": {
"Region": 0
},
"CustomConfig": {
"Vendor": 0,
"Region": 0
}
}
}
},
"ResponseMetadata": {
"RequestId": "20230604110420",
"Action": "GetSegmentTask",
"Version": "2023-11-01",
"Service": "rtc",
"Region": "cn-north-1"
}
}
错误码
最近更新时间：2026.07.18 23:50:58
这个页面对您有帮助吗？
有用
有用
无用
无用