全部文档
当前文档

暂无内容

如果没有找到您期望的内容,请尝试其他搜索词

文档中心

视频信息提取

最近更新时间: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

  • 类型:String

是

x-kss-process

操作类型。固定取值:video/info,表示获取媒体信息。

  • 类型:String

是

请求头

该接口仅使用公共请求头。

请求体

该接口不使用请求体。

响应

响应头

该接口仅返回公共响应头。

响应体

响应体返回为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

  • 请求不合法。URL 格式错误、请求协议异常等。

  • 请求 URL 中重复填写同一请求参数。

400 Bad Request

InvalidArgument

参数异常。必选参数缺失、参数类型错误、参数值为空。

403 Forbidden

InvalidObjectState

文件为未完成解冻的归档 (未开启归档直读)或冷归档存储类型。

400 Bad Request

FileTooLarge

源文件大小超出50GB。

400 Bad Request

DurationExceeded

源视频时长超出10小时。

费用

视频信息提取当前邀测期间暂不收费,邀测结束后开始根据请求次数收费。

文档导读
纯净模式常规模式

纯净模式

点击可全屏预览文档内容
文档反馈