最近更新时间:2026-11-18 14:05:03
操作名称:video/info
视频信息提取功能可获取媒体文件的封装与音视频流信息,包括:
视频分辨率(宽度和高度)
帧率
音视频编码器类型
是否包含字幕流
视频时长
视频拍摄时间
文件大小
码率
封装格式
1. 使用该功能的客户必须具有ks3:GetObject权限。
2. 视频信息提取单个UID QPS建议不超50,如有更大需求,请联系商务或提交工单申请。
3. 当前仅支持北京区域。
4. 源文件大小建议不超25GB,视频时长建议不超5小时。
视频监控:提取视频元数据用于内容识别和异常检测。
视频搜索:通过视频特征(分辨率、编码格式等)实现内容检索。
视频编辑:根据视频参数自动识别关键帧进行后续编辑剪辑。
视频管理:根据元数据(分辨率、码率、帧率、编码标准)对视频进行分类管理。
GET /{ObjectKey}?x-kss-process=video/info HTTP/1.1
Host: {BucketName}.{endpoint}
Authorization: {SignatureValue}参数名称 | 描述 | 是否必选 |
|---|---|---|
ObjectKey | 对象文件名。示例值:test.mp4
| 是 |
x-kss-process | 操作类型。固定取值:video/info,表示获取媒体信息。
| 是 |
该接口仅使用公共请求头。
该接口不使用请求体。
该接口仅返回公共响应头。
响应体返回为JSON 格式,包含完整节点数据的内容展示如下:
{
"requestId": "a1b2c3d4e5f6g7h8",
"size": 12345678,
"duration": 120.5,
"bitrate": 2000,
"videoWidth": 1920,
"videoHeight": 1080,
"formatName": "mp4",
"formatLongName": "QuickTime / MOV",
"produceTime": "2024-01-15T08:30:00Z",
"streamCount": 3,
"videoStreams": [
{
"index": 0,
"codecName": "h264",
"codecLongName": "H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10",
"codecType": "video",
"codecTag": "0x0000",
"codecTagString": "[0][0][0][0]",
"width": 1920,
"height": 1080,
"frameRate": "50/1",
"bitrate": 1800,
"profile": "High",
"level": 40,
"sampleAspectRatio": "1:1",
"colorSpace": "bt709",
"startTime": 0.044,
"colorRange": "tv",
"bitDepth": 8,
"displayAspectRatio": "16:9",
"hasBFrames": 1,
"averageFrameRate": "50/1",
"colorPrimaries": "bt709",
"pixelFormat": "yuv420p",
"timeBase": "1/1000"
}
],
"audioStreams": [
{
"index": 1,
"codecName": "aac",
"codecLongName": "AAC (Advanced Audio Coding)",
"codecType": "audio",
"codecTag": "0x0000",
"codecTagString": "[0][0][0][0]",
"sampleRate": 44100,
"channels": 2,
"channelLayout": "stereo",
"bitrate": 128,
"timeBase": "1/1000",
"sampleFormat": "fltp"
}
],
"subtitles": [
{
"index": 2,
"codecName": "mov_text",
"codecLongName": "SubRip subtitle",
"codecType": "subtitle",
"codecTag": "0x0000",
"codecTagString": "[0][0][0][0]",
"duration": 75.669,
"language": "chi"
}
]
}响应体的具体参数描述如下所示:
文件基本信息参数
参数名称 | 描述 |
|---|---|
requestId | 请求的唯一标识ID,用于问题排查和工单追踪。 |
size | 文件大小,单位为字节。 |
duration | 视频总时长,单位为秒。 0表示无法识别时长的非视频文件。 |
bitrate | 文件整体码率,单位为bps(比特每秒)。码率越高画质越好但文件越大。 常见范围:标清500K-2Mbps、高清2-8Mbps、4K 10-50Mbps。 |
videoWidth | 视频画面的宽度,单位为像素(px)。 常见值:1920(1080p)、2560(2K)、3840(4K)。 |
videoHeight | 视频画面的高度,单位为像素(px)。 |
formatName | 封装格式的简称标识符。 |
formatLongName | 封装格式的完整人类可读名称。 |
produceTime | 视频生产/创建时间,采用 ISO 8601 标准格式的 UTC 时间字符串。 |
streamCount | 媒体流的总数量。一个文件可包含多个视频流、音频流、字幕流。 |
视频流详情参数(VideoStreams)
参数名称 | 描述 |
|---|---|
index | 该流的编号。 |
codecName | 视频编码格式简称。 |
codecLongName | 视频编码格式的完整标准名称,包含所有别名和归属标准组织信息。 |
codecType | 流的类型,对于视频流固定为"video"。 |
codecTag | 编码标签的四进制标识,用于特定容器内的编解码器识别。 0x0000表示未指定或通用标签。 |
codecTagString | CodecTag的可读字符串形式。 |
width | 该视频流的实际渲染宽度(像素)。与VideoWidth一致,但在多视频流场景下每个流可能有不同分辨率。 |
height | 该视频流的实际渲染高度(像素)。与VideoHeight一致。 |
frameRate | 标称帧率(每秒播放多少帧画面),表示每秒显示的画面帧数,帧率越高画面越流畅但码率越大。 |
bitrate | 比特率(码率),单位为 kbps,反应视频画质。 |
profile | 编码档次/级别配置。 |
level | 编码等级,约束最大分辨率、帧率和码率的组合。数值越大支持的能力越强。 |
sampleAspectRatio | 采样宽高比(SAR),格式为"宽:高"。 |
colorSpace | 色彩空间标准。 |
startTime | 该视频流的时间偏移起始点,单位为秒。 |
colorRange | 色彩取值范围。 |
bitDepth | 色彩位深(色深),单位为bit。表示每个颜色通道的数据位数。 |
displayAspectRatio | 显示宽高比(DAR),格式为"宽:高"。最终播放时的画面比例。 |
hasBFrames | 是否使用B帧(双向预测帧)。0=不使用,1=使用。 |
averageFrameRate | 实际平均帧率,考虑了VFR(可变帧率)后的真实平均值。 |
colorPrimaries | 色彩原色/三原色定义标准。 |
pixelFormat | 像素格式/色彩采样方式。 |
timeBase | 时间基准,格式为"分子/分母"。用于将时间戳(pts/dts)转换为实际秒数,1/1000表示时间戳单位为毫秒。 |
音频流详情参数(AudioStreams)
参数名称 | 描述 |
|---|---|
index | 该音频流在文件中的索引序号,从0开始递增。 |
codecName | 音频编码格式简称。 |
codecLongName | 音频编码格式的完整标准名称。 |
codecType | 流的类型,对于音频流固定为"audio"。 |
codecTag | 音频编码标签标识。 |
codecTagString | CodecTag的可读字符串形式。 |
sampleRate | 音频采样率,单位为Hz(赫兹)。 |
channels | 音频声道数量。1=单声道(Mono),2=立体声(Stereo),5.1=环绕声(6声道),7.1=全景声(8声道)。 |
channelLayout | 声道布局的人类可读描述。常见值:mono(单声道)、stereo(立体声)、5.1(side)(5.1环绕声)、7.1(全景声)。 |
bitrate | 比特率,单位 kbps。 |
timeBase | 时间基准。 |
sampleFormat | 采样数据的存储格式。 fltp(32位浮点型,最常用且精度高)、s16(16位有符号整数)、s32(32位有符号整数)、u8(8位无符号整数)。 |
字幕流详情参数(Subtitles)
参数名称 | 描述 |
|---|---|
index | 该字幕流在文件中的索引序号。 |
codecName | 字幕编码格式简称。 |
codecLongName | 字幕编码格式的完整标准名称。 |
codecType | 流的类型,对于字幕流固定为"subtitle"。 |
codecTag | 字幕编码标签标识。 |
codecTagString | CodecTag的可读字符串形式。 |
duration | 该字幕流的有效持续时长,单位为秒。 |
language | 语言,und 表示无查询结果。 如"chi"(中文)、"eng"(英文)。 |
GET /objectname?x-kss-process=video/info HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Authorization: authorization string{
"requestId": "a1b2c3d4e5f6g7h8",
"size": 12345678,
"duration": 120.5,
"bitrate": 2000,
"videoWidth": 1920,
"videoHeight": 1080,
"formatName": "mp4",
"formatLongName": "QuickTime / MP4",
"produceTime": "2024-01-15T08:30:00Z",
"streamCount": 3,
"videoStreams": [
{
"index": 0,
"codecName": "h264",
"codecLongName": "H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10",
"codecType": "video",
"codecTag": "0x0000",
"codecTagString": "[0][0][0][0]",
"width": 1920,
"height": 1080,
"frameRate": "50/1",
"bitrate": 1800,
"profile": "High",
"level": 40,
"sampleAspectRatio": "1:1",
"colorSpace": "bt709",
"startTime": 0.044,
"colorRange": "tv",
"bitDepth": 8,
"displayAspectRatio": "16:9",
"hasBFrames": 1,
"averageFrameRate": "50/1",
"colorPrimaries": "bt709",
"pixelFormat": "yuv420p",
"timeBase": "1/1000"
}
],
"audioStreams": [
{
"index": 1,
"codecName": "aac",
"codecLongName": "AAC (Advanced Audio Coding)",
"codecType": "audio",
"codecTag": "0x0000",
"codecTagString": "[0][0][0][0]",
"sampleRate": 44100,
"channels": 2,
"channelLayout": "stereo",
"bitrate": 128,
"timeBase": "1/1000",
"sampleFormat": "fltp"
}
],
"subtitles": [
{
"index": 2,
"codecName": "mov_text",
"codecLongName": "SubRip subtitle",
"codecType": "subtitle",
"codecTag": "0x0000",
"codecTagString": "[0][0][0][0]",
"duration": 75.669,
"language": "chi"
}
]
}HTTP 状态码 | 错误码 | 描述 |
|---|---|---|
400 Bad Request | MediaParseFailed |
|
400 Bad Request | NoMediaStream | 文件内未检测到视频流 / 音频流,无有效元数据可返回。 |
404 Not Found | NoSuchBucket | 存储桶不存在。 |
404 Not Found | NoSuchKey | 文件不存在。 |
403 Forbidden | AccessDenied | 权限不足。 |
400 Bad Request | InvalidRequest |
|
400 Bad Request | InvalidArgument | 参数异常。必选参数缺失、参数类型错误、参数值为空。 |
403 Forbidden | InvalidObjectState | 文件为未完成解冻的归档 (未开启归档直读)或冷归档存储类型。 |
400 Bad Request | FileTooLarge | 源文件大小超出50GB。 |
400 Bad Request | DurationExceeded | 源视频时长超出10小时。 |
视频信息提取当前邀测期间暂不收费,邀测结束后开始根据请求次数收费。
纯净模式
