一、接口描述
人脸查找媒资（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.1Host: <AppId>.ci.<Region>.myqcloud.comDate: <GMT Date>Authorization: Auth StringAccept: 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.1Authorization: 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.comContent-Length: 106Content-Type: application/jsonAccept: application/json{ "DatasetName": "your-dataset-name-001", "URI": "cos://examplebucket-1250000000/face_query.jpg"}
十三、响应
HTTP/1.1 200 OKContent-Type: application/jsonContent-Length: 320Connection: keep-aliveDate: Fri, 06 Feb 2026 15:23:12 GMTServer: tencent-cix-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" ] } ]}
十四、错误码
该请求操作无特殊错误信息，常见的错误信息请参见 错误码 文档。