对象存储获取媒资 AI 分析信息

接口描述
获取媒资 AI 分析信息，用于查询数据集内某个媒资文件（视频、图片）的完整 AI 分析结果。输入一个媒资文件的 URI，即可一次性获取该文件的文件基础信息，以及经 AI 分析得到的内容标签、语音识别、字幕文字识别、人脸识别、内容粗分类等结构化元数据。
例如，对一段已完成入库的视频调用本接口，即可获取到该视频的时长、分辨率等基础信息，以及内容标签、语音识别、文字识别、人脸识别、内容摘要等多维 AI 分析信息：
﻿
说明：
本接口返回的是媒资在入库时经 AI 分析并落库的元数据，因此调用前需先确保目标文件已完成 数据集创建。其中人脸识别信息（FaceInfo）的结构与 人脸查找媒资、人脸定位媒资片段 接口的返回保持一致。
授权说明
通过子账号使用时，需要在 授权策略 的 action 中添加 ci:GetAIMediaInfo 权限。数据万象支持的所有操作接口请参见 CI action。
服务开通
首次使用该功能时将默认为您开通数据万象，同时该存储桶将自动绑定数据万象，无需角色授权，即可直接使用。
注意：
数据万象绑定后，如果您手动对存储桶进行数据万象的解绑操作，将无法继续使用该功能。
当前如需获取图片/视频中的人脸相关信息需开通白名单，请 联系我们。
使用限制
使用前需要先完成 创建数据集，且待查询的媒资文件需已完成入库。
仅支持北京、上海、成都地域，即请求 Host 中的地域仅支持填写为 ap-beijing、ap-shanghai、ap-chengdu。
视频与图片返回的 AiData 字段范围不同：AsrInfo（语音识别）、AiRoughData（AI 粗分类）为视频独有；AiLabelInfo（AI 标签）、OcrInfo（文字识别）、FaceInfo（人脸识别）视频与图片均支持，但内部结构因是否包含时间片段而有所差异。
更多使用限制，详情请参见 使用限制。
费用说明
有关获取媒资 AI 分析信息的费用，请参见 智能检索费用。
说明：
获取媒资 AI 分析信息接口使用标量检索计费项，根据接口调用次数收费。
请求
请求示例
POST /datasetquery/getaimediainfo HTTP/1.1
Host: <AppId>.ci.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: Auth String
Accept: application/json
说明：
Authorization: Auth String，详情请参见 请求签名 文档。
请求头
此接口仅使用公共请求头部，详情请参见 公共请求头部 文档。
请求体
请求体示例：
{
	"DatasetName": "your-dataset-name-001",
	"URI": "cos://examplebucket-1250000000/test.mp4"
}
请求参数
参数名称
描述
类型
是否必选
DatasetName
数据集名称，同一个账户下唯一。命名规则：长度 1-32 字符，只能包含小写英文字母、数字、短划线（-），必须以英文字母或数字开头
String
是
URI
对象文件名，需包含 COS 完整路径。格式为 cos://<BucketName>/<Path>，例如 cos://examplebucket-1250000000/test.mp4
String
是
响应
响应头
此接口仅返回公共响应头部，详情请参见 公共响应头部 文档。
响应体
{
	"RequestId": "2FDE2411-DB8D-4A9A-875B-275798F14A5E",
	"MediaInfo": {
		"URI": "cos://examplebucket-1250000000/test.mp4",
		"CosTagging": {
			"business": "userDataTest",
			"type": "media",
			"channel": "test"
		},
		"CustomLabels": {
			"scene": "outdoor",
			"project": "demo"
		},
		"CosUserMeta": {
			"x-cos-meta-source": "upload",
			"x-cos-meta-author": "test-user"
		},
		"ModifiedTime": "2020-12-26T04:11:10Z",
		"FileInfo": {
			"FileBasicInfo": {
				"FileName": "example.mp4",
				"FileSize": 30611502,
				"FileUrl": "cos://examplebucket-1250000000/test.mp4",
				"Region": "ap-shanghai",
				"ModifiedTime": "2020-12-26T04:11:10Z",
				"FormatName": "mov,mp4,m4a,3gp,3g2,mj2",
				"Duration": 216.206667,
				"Bitrate": 1132.68,
				"Width": 960,
				"Height": 540
			},
			"AiData": {
				"AiLabelInfo": [
					{
						"From": 1.4,
						"To": 2.5,
						"Timestamp": 1.4,
						"LabelDetail": [
							{
								"Confidence": "high",
								"LabelInfos": {
									"Type": "物体",
									"Category": "交通工具",
									"Name": "车"
								}
							},
							{
								"Confidence": "medium",
								"LabelInfos": {
									"Type": "物体",
									"Category": "建筑",
									"Name": "写字楼"
								}
							}
						]
					}
				],
				"AsrInfo": [
					{
						"From": 1.4,
						"To": 2.5,
						"ClipId": "5FE19530C7A422197535FE74F5DB****",
						"Content": "欢迎观看本期节目",
						"Timestamp": 1.4
					}
				],
				"OcrInfo": [
					{
						"From": 1.4,
						"To": 2.5,
						"ClipId": "5FE19530C7A422197535FE74F5DB****",
						"Content": "城市交通",
						"BoxPosition": {
							"Left": 517,
							"Top": 409,
							"Width": 128,
							"Height": 168
						},
						"Score": 0.86,
						"Timestamp": 1.4
					}
				],
				"AiRoughData": {
					"AiCategory": "生活",
					"Description": "这是一段关于城市道路交通场景的视频"
				},
				"FaceInfo": [
					{
						"Score": 99.04,
						"LabelName": "张三",
						"Category": "custom",
						"OccurrencesInfos": [
							{
								"From": 61.066353,
								"To": 69.06635,
								"TrackData": [
									{
										"Timestamp": 62.03302,
										"BoxPosition": {
											"Left": 517,
											"Top": 409,
											"Width": 128,
											"Height": 168
										}
									}
								]
							}
						]
					}
				]
			}
		}
	}
}
﻿
响应包体具体数据内容如下：
参数名称
类型
描述
RequestId
String
请求 ID
MediaInfo
Container
媒资信息，详见下方 MediaInfo 节点说明
MediaInfo 节点内容：
参数名称
类型
描述
URI
String
被查询的媒资在相应系统中的地址
CosTagging
Container
COS 自定义标签。存储业务在 COS object 上的自定义标签键值对信息，可用于查询时作为筛选条件
CustomLabels
Container
文件自定义标签列表。存储业务自定义的键名、键值对信息，可用于查询时作为筛选条件
CosUserMeta
Container
COS 自定义头部。存储业务在 COS object 上的键名、键值对信息，可用于查询时作为筛选条件
ModifiedTime
String
媒资修改时间
FileInfo
Container
文件信息，详见下方 FileInfo 节点说明
FileInfo 节点内容：
参数名称
类型
描述
FileBasicInfo
Container
文件基础信息，详见下方 FileBasicInfo 节点说明
AiData
Container
AI 分析详细信息，详见下方 AiData 节点说明
FileBasicInfo 节点内容：
参数名称
类型
描述
适用范围
FileName
String
文件名
视频、图片
FileSize
Integer
文件大小，单位为字节
视频、图片
FileUrl
String
文件 COS 地址
视频、图片
Region
String
文件存储区域
视频、图片
ModifiedTime
String
文件修改时间
视频、图片
FormatName
String
视频封装格式名称，例如 mov,mp4,m4a,3gp,3g2,mj2
仅视频
Duration
Float
视频时长，单位为秒
仅视频
Bitrate
Float
视频码率，单位为 kbps
仅视频
Width
Integer
视频宽度，单位为像素
仅视频
Height
Integer
视频高度，单位为像素
仅视频
AiData 节点内容：
参数名称
类型
描述
适用范围
AiLabelInfo
Container Array
AI 标签信息列表，详见下方 AiLabelInfo 节点说明
视频、图片
AsrInfo
Container Array
语音识别信息列表，详见下方 AsrInfo 节点说明
仅视频
OcrInfo
Container Array
文字识别信息列表，详见下方 OcrInfo 节点说明
视频、图片
AiRoughData
Container
AI 粗分类信息，详见下方 AiRoughData 节点说明
仅视频
FaceInfo
Container Array
人脸识别信息列表，详见下方 FaceInfo 节点说明
视频、图片
说明：
AiData 中各字段仅在媒资存在对应分析结果时返回。其中 AsrInfo、AiRoughData 为视频独有；AiLabelInfo、OcrInfo、FaceInfo 视频与图片均可返回，但视频包含 From、To、Timestamp 等时间片段字段，图片则不包含时间维度。下文对存在结构差异的字段分「视频」「图片」两种情况分别说明。
AiLabelInfo 节点内容：
参数名称
类型
描述
适用范围
From
Double
片段起始时间，单位为秒
仅视频
To
Double
片段结束时间，单位为秒
仅视频
Timestamp
Double
片段时间戳，单位为秒
仅视频
LabelDetail
Container Array
标签详情列表，详见下方 LabelDetail 节点说明
视频、图片
LabelDetail 节点内容：
参数名称
类型
描述
LabelInfos
Map
标签信息，key 为标签名称（如 Type、Category、Name），value 为对应标签值，例如 {"Type": "物体", "Category": "交通工具", "Name": "车"}
Confidence
String
置信度，例如 high、medium
AsrInfo 节点内容（仅视频）：
参数名称
类型
描述
From
Double
片段起始时间，单位为秒
To
Double
片段结束时间，单位为秒
ClipId
String
片段 ID
Content
String
语音识别文本内容
Timestamp
Double
片段时间戳，单位为秒
OcrInfo 节点内容：
视频
图片
参数名称
类型
描述
From
Double
片段起始时间，单位为秒
To
Double
片段结束时间，单位为秒
ClipId
String
片段 ID
Content
String
文字识别文本内容
BoxPosition
Container
识别文本内容的坐标位置，详见下方 BoxPosition 节点说明
Score
Float
相似分数
Timestamp
Double
片段时间戳，单位为秒
参数名称
类型
描述
Content
String
文字识别文本内容
BoxPosition
Container
识别文本内容的坐标位置，详见下方 BoxPosition 节点说明
Score
Float
相似分数
AiRoughData 节点内容（仅视频）：
参数名称
类型
描述
AiCategory
String
AI 粗分类类别，例如 生活
Description
String
视频整体描述
FaceInfo 节点内容：
FaceInfo 按人物聚合，每个元素对应一个匹配到的人物。视频与图片的差异在于：视频通过 OccurrencesInfos 描述人物出现的多个时间片段，图片无时间片段概念，TrackData 直接挂载在人物元素下。
视频
图片
参数名称
类型
描述
Score
Float
人脸匹配得分，范围为 [0, 100]
LabelName
String
实体/人物名称
Category
String
人物类型，可选值：celebrity（名人）、sensitive（敏感人物）、politician（政治人物）、custom（自定义人物）、unknown（未知）
OccurrencesInfos
Container Array
人物片段聚类信息，详见下方 OccurrencesInfos 节点说明
OccurrencesInfos 节点内容：
参数名称
类型
描述
From
Float
片段起始时间，单位为秒
To
Float
片段结束时间，单位为秒
TrackData
Container Array
人脸单帧详细信息列表，详见下方 TrackData 节点说明
TrackData 节点内容：
参数名称
类型
描述
Timestamp
Float
人脸出现时间戳，单位为秒
BoxPosition
Container
人脸坐标框，详见下方 BoxPosition 节点说明
参数名称
类型
描述
Score
Float
人脸匹配得分，范围为 [0, 100]
LabelName
String
实体/人物名称
Category
String
人物类型，可选值：celebrity（名人）、sensitive（敏感人物）、politician（政治人物）、custom（自定义人物）、unknown（未知）
TrackData
Container Array
人脸单帧详细信息列表，详见下方 TrackData 节点说明
TrackData 节点内容：
参数名称
类型
描述
BoxPosition
Container
人脸坐标框，详见下方 BoxPosition 节点说明
BoxPosition 节点内容：
参数名称
类型
描述
Left
Integer
坐标框左上角横坐标，单位为像素
Top
Integer
坐标框左上角纵坐标，单位为像素
Width
Integer
坐标框宽度，单位为像素
Height
Integer
坐标框高度，单位为像素
实际案例
案例一：获取视频的 AI 分析信息
对一段城市道路视频调用本接口，可获取内容标签、语音识别、文字识别、人脸识别、内容摘要等分析结果（视频结果均带时间片段）：
﻿
请求：查询视频媒资
POST /datasetquery/getaimediainfo HTTP/1.1
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1497530202;1497610202&q-key-time=1497530202;1497610202&q-header-list=&q-url-param-list=&q-signature=****************************************
Host: 1234567890.ci.ap-beijing.myqcloud.com
Content-Length: 106
Content-Type: application/json
Accept: application/json
﻿
{
	"DatasetName": "your-dataset-name-001",
	"URI": "cos://examplebucket-1250000000/test.mp4"
}
响应
HTTP/1.1 200 OK
Content-Type: application/json
Connection: keep-alive
Date: Fri, 06 Feb 2026 15:23:12 GMT
Server: tencent-ci
x-ci-request-id: NjMxMDJhYTNfMThhYTk0MGFfYmU1OV8zZjc=
﻿
{
	"RequestId": "2FDE2411-DB8D-4A9A-875B-275798F14A5E",
	"MediaInfo": {
		"URI": "cos://examplebucket-1250000000/test.mp4",
		"CosTagging": {
			"business": "userDataTest",
			"type": "media",
			"channel": "test"
		},
		"CustomLabels": {
			"scene": "outdoor",
			"project": "demo"
		},
		"CosUserMeta": {
			"x-cos-meta-source": "upload",
			"x-cos-meta-author": "test-user"
		},
		"ModifiedTime": "2020-12-26T04:11:10Z",
		"FileInfo": {
			"FileBasicInfo": {
				"FileName": "example.mp4",
				"FileSize": 30611502,
				"FileUrl": "cos://examplebucket-1250000000/test.mp4",
				"Region": "ap-shanghai",
				"ModifiedTime": "2020-12-26T04:11:10Z",
				"FormatName": "mov,mp4,m4a,3gp,3g2,mj2",
				"Duration": 216.206667,
				"Bitrate": 1132.68,
				"Width": 960,
				"Height": 540
			},
			"AiData": {
				"AiLabelInfo": [
					{
						"From": 1.4,
						"To": 2.5,
						"Timestamp": 1.4,
						"LabelDetail": [
							{
								"Confidence": "high",
								"LabelInfos": {
									"Type": "物体",
									"Category": "交通工具",
									"Name": "车"
								}
							},
							{
								"Confidence": "medium",
								"LabelInfos": {
									"Type": "物体",
									"Category": "建筑",
									"Name": "写字楼"
								}
							}
						]
					}
				],
				"AsrInfo": [
					{
						"From": 1.4,
						"To": 2.5,
						"ClipId": "5FE19530C7A422197535FE74F5DB****",
						"Content": "欢迎观看本期节目",
						"Timestamp": 1.4
					}
				],
				"OcrInfo": [
					{
						"From": 1.4,
						"To": 2.5,
						"ClipId": "5FE19530C7A422197535FE74F5DB****",
						"Content": "城市交通",
						"BoxPosition": {
							"Left": 517,
							"Top": 409,
							"Width": 128,
							"Height": 168
						},
						"Score": 0.86,
						"Timestamp": 1.4
					}
				],
				"AiRoughData": {
					"AiCategory": "生活",
					"Description": "这是一段关于城市道路交通场景的视频"
				},
				"FaceInfo": [
					{
						"Score": 99.04,
						"LabelName": "张三",
						"Category": "custom",
						"OccurrencesInfos": [
							{
								"From": 61.066353,
								"To": 69.06635,
								"TrackData": [
									{
										"Timestamp": 62.03302,
										"BoxPosition": {
											"Left": 517,
											"Top": 409,
											"Width": 128,
											"Height": 168
										}
									}
								]
							}
						]
					}
				]
			}
		}
	}
}
案例二：获取图片的 AI 分析信息
对一张图片调用本接口，可获取内容标签、文字识别、人脸识别等分析结果。图片无时间片段概念，文字识别与人脸识别均以坐标框（BoxPosition）标注位置：
﻿
请求：查询图片媒资
POST /datasetquery/getaimediainfo HTTP/1.1
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1497530202;1497610202&q-key-time=1497530202;1497610202&q-header-list=&q-url-param-list=&q-signature=****************************************
Host: 1234567890.ci.ap-beijing.myqcloud.com
Content-Length: 106
Content-Type: application/json
Accept: application/json
﻿
{
	"DatasetName": "your-dataset-name-002",
	"URI": "cos://examplebucket-1250000000/test.png"
}
响应
HTTP/1.1 200 OK
Content-Type: application/json
Connection: keep-alive
Date: Fri, 06 Feb 2026 15:23:12 GMT
Server: tencent-ci
x-ci-request-id: NjMxMDJhYTNfMThhYTk0MGFfYmU1OV8zZjc=
﻿
{
	"RequestId": "2FDE2411-DB8D-4A9A-875B-275798F14A5E",
	"MediaInfo": {
		"URI": "cos://examplebucket-1250000000/test.png",
		"CosTagging": {
			"business": "userDataTest",
			"type": "media",
			"channel": "test"
		},
		"CustomLabels": {
			"scene": "outdoor",
			"project": "demo"
		},
		"CosUserMeta": {
			"x-cos-meta-source": "upload",
			"x-cos-meta-author": "test-user"
		},
		"ModifiedTime": "2020-12-26T04:11:10Z",
		"FileInfo": {
			"FileBasicInfo": {
				"FileName": "test.png",
				"FileSize": 30611502,
				"FileUrl": "cos://examplebucket-1250000000/test.png",
				"Region": "ap-shanghai",
				"ModifiedTime": "2020-12-26T04:11:10Z"
			},
			"AiData": {
				"AiLabelInfo": [
					{
						"LabelDetail": [
							{
								"Confidence": "high",
								"LabelInfos": {
									"Type": "物体",
									"Category": "交通工具",
									"Name": "车"
								}
							}
						]
					}
				],
				"OcrInfo": [
					{
						"Content": "营业执照",
						"BoxPosition": {
							"Left": 100,
							"Top": 200,
							"Width": 300,
							"Height": 50
						},
						"Score": 0.95
					}
				],
				"FaceInfo": [
					{
						"Score": 99.04,
						"LabelName": "张三",
						"Category": "custom",
						"TrackData": [
							{
								"BoxPosition": {
									"Left": 517,
									"Top": 409,
									"Width": 128,
									"Height": 168
								}
							}
						]
					}
				]
			}
		}
	}
}
错误码
该请求操作无特殊错误信息，常见的错误信息请参见 错误码 文档。
﻿
参数名称	描述	类型	是否必选
DatasetName	数据集名称，同一个账户下唯一。命名规则：长度 1-32 字符，只能包含小写英文字母、数字、短划线（-），必须以英文字母或数字开头	String	是
URI	对象文件名，需包含 COS 完整路径。格式为 `cos://<BucketName>/<Path>`，例如 `cos://examplebucket-1250000000/test.mp4`	String	是
获取媒资 AI 分析信息

本页目录：

接口描述

授权说明

服务开通

使用限制

费用说明

请求

请求示例

请求头

请求体

请求参数

响应

响应头

响应体

实际案例

案例一：获取视频的 AI 分析信息

请求：查询视频媒资

响应

案例二：获取图片的 AI 分析信息

请求：查询图片媒资

响应

错误码
