数据万象人脸查找媒资

接口描述
本接口对数据集内的媒资文件进行人脸查找。支持输入一张外部人脸图片，在指定数据集中查找出包含该人脸的媒资文件（图片、视频），并返回系统为每张人脸分配的人脸 ID（FaceId）及其所归属的媒资文件列表。通过该接口，可以快速定位指定人脸出现在哪些媒资文件中。
人脸查找媒资（MediaFaceSearch）用于定位"人脸出现在哪些媒资文件中"。若需进一步定位该人脸在某个视频中出现的具体时间片段、单帧坐标框及人物分类等详细信息，可结合 人脸定位媒资片段（MediaFaceClipSearch）接口使用：先通过本接口拿到人脸 ID 与命中的媒资文件列表，再对目标文件调用人脸定位媒资片段接口进行精确定位。两者配合，即可完成从"找到人"到"定位到片段"的完整链路。
例如，上传一张人物照片作为检索输入，即可从海量媒资库中查找出包含该人物的所有图片与视频，并按匹配相关度返回：
﻿
授权说明
通过子账号使用时，需要在 授权策略 的 action 中添加 ci:DatasetFaceSearch 权限。数据万象支持的所有操作接口请参见 CI action。
服务开通
首次使用该功能时将默认为您开通数据万象，同时该存储桶将自动绑定数据万象，无需角色授权，即可直接使用。
注意：
数据万象绑定后，如果您手动对存储桶进行数据万象的解绑操作，将无法继续使用该功能。
当前如需使用该能力需开通白名单，请 联系我们。
使用限制
使用检索前需要先完成 创建数据集，且数据集需开启 VideoSearch（视频检索）或 ImageSearch（图片检索，需开白）模板，并完成媒资入库。
仅支持北京、上海、成都地域，即请求 Host 中的地域仅支持填写为 ap-beijing、ap-shanghai、ap-chengdu。
单次查询最多返回 20 个人脸 ID（FaceId），每个人脸 ID 对应的媒资文件列表（UriList）最多包含 500 个 URI。
更多使用限制，详情请参见 使用限制。
费用说明
有关人脸查找媒资接口的费用，请参见 智能检索费用 中的人脸检索。
请求
请求示例
POST /datasetquery/mediafacesearch 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/face_query.jpg"
}
请求参数
参数名称
描述
类型
是否必选
DatasetName
数据集名称，同一个账户下唯一。命名规则：长度1 - 32字符，只能包含小写英文字母、数字、短划线（-），必须以英文字母或数字开头
String
是
URI
需要进行人脸精确定位的媒资文件地址，取值为人脸粗搜（MediaFaceSearch）返回的 UriList 中的某一内部 URI，需包含完整的 COS 路径
String
是
响应
响应头
此接口仅返回公共响应头部，详情请参见 公共响应头部 文档。
响应体
响应体示例：
{
	"RequestId": "7CA7D615-CFB1-5437-9A12-2D185C3EE6CB",
	"MediaInfoList": [
		{
			"FaceId": "face_20260206_0001",
			"UriList": [
				"cos://examplebucket-1250000000/photo_001.jpg",
				"cos://examplebucket-1250000000/photo_002.jpg"
			]
		},
		{
			"FaceId": "face_20260206_0002",
			"UriList": [
				"cos://examplebucket-1250000000/photo_003.jpg",
				"cos://examplebucket-1250000000/photo_004.jpg"
			]
		}
	]
}
响应包体具体数据内容如下：
参数名称
类型
描述
RequestId
String
请求 ID
MediaInfoList
Container Array
人脸匹配信息列表，最多返回20个人脸 ID（FaceId）
MediaInfoList 节点内容：
参数名称
类型
描述
FaceId
String
人脸 ID，系统为每张匹配到的人脸分配的唯一标识
UriList
String Array
包含该人脸的媒资文件 URI 列表，表示该人脸出现在哪些媒资文件中。每个 FaceId 对应的 UriList 最多包含500个 URI
返回结果按人脸聚合：每个 FaceId 对应一个人，其 UriList 即为包含该人脸的全部媒资文件（图片或视频）地址，如下所示：
﻿
实际案例
请求：输入一张人脸图片进行查找
POST /datasetquery/mediafacesearch 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/face_query.jpg"
}
响应
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 320
Connection: keep-alive
Date: Fri, 06 Feb 2026 15:23:12 GMT
Server: tencent-ci
x-ci-request-id: NjMxMDJhYTNfMThhYTk0MGFfYmU1OV8zZjc=
﻿
{
	"RequestId": "7CA7D615-CFB1-5437-9A12-2D185C3EE6CB",
	"MediaInfoList": [
		{
			"FaceId": "face_20260206_0001",
			"UriList": [
				"cos://examplebucket-1250000000/photo_001.jpg",
				"cos://examplebucket-1250000000/photo_002.jpg"
			]
		},
		{
			"FaceId": "face_20260206_0002",
			"UriList": [
				"cos://examplebucket-1250000000/photo_003.jpg",
				"cos://examplebucket-1250000000/photo_004.jpg"
			]
		}
	]
}
错误码
该请求操作无特殊错误信息，常见的错误信息请参见 错误码 文档。
﻿

参数名称	描述	类型	是否必选
DatasetName	数据集名称，同一个账户下唯一。命名规则：长度1 - 32字符，只能包含小写英文字母、数字、短划线（-），必须以英文字母或数字开头	String	是
URI	需要进行人脸精确定位的媒资文件地址，取值为人脸粗搜（MediaFaceSearch）返回的 UriList 中的某一内部 URI，需包含完整的 COS 路径	String	是

人脸查找媒资

本页目录：

接口描述

授权说明

服务开通

使用限制

费用说明

请求

请求示例

请求头

请求体

请求参数

响应

响应头

响应体

实际案例

请求：输入一张人脸图片进行查找

响应

错误码