接口描述
本接口对数据集内已入库的媒资文件进行人脸精确定位。在通过 人脸查找媒资 得到人脸 ID（
FaceId）与其所在的媒资文件（URI）后，本接口可在指定媒资文件内进行人脸精确匹配，返回该人脸在文件中的详细出现信息，包括出现的时间片段（OccurrencesInfos）、逐帧的人脸坐标框（BoxPosition）以及人物分类（Category）等，实现精确定位某个人在某个视频中出现的所有片段及位置。人脸定位媒资片段与人脸查找媒资配合构成先找到人、再定位片段的两段式人脸检索链路：
人脸查找媒资（MediaFaceSearch）：输入一张人脸图片，快速找出该人脸出现在数据集中的哪些媒资文件，返回
FaceId 与媒资文件列表（UriList）。人脸定位媒资片段（MediaFaceClipSearch）：输入人脸查找媒资返回的
FaceId 与其中一个媒资文件 URI，精确定位该人脸在这个文件中出现的时间片段与逐帧坐标框。
授权说明
服务开通
首次使用该功能时将默认为您开通数据万象，同时该存储桶将自动绑定数据万象，无需角色授权，即可直接使用。
使用限制
使用检索前需要先完成 创建数据集，并选择
VideoSearch（或已开通白名单的 ImageSearch）模板完成媒资入库。仅支持北京、上海、成都地域，即请求 Host 中
Region 仅支持填写为 ap-beijing、ap-shanghai、ap-chengdu。本接口的入参
FaceId 与 URI 需来自人脸查找媒资（MediaFaceSearch）的返回结果：URI 必须为人脸查找媒资返回的 UriList 中的某一内部 URI，FaceId 必须为人脸查找媒资返回的人脸 ID。更多使用限制，详情请参见 使用限制。
费用说明
请求
请求示例
POST /datasetquery/mediafaceclipsearch HTTP/1.1Host: <AppId>.ci.<Region>.myqcloud.comAuthorization: Auth StringContent-Length: xxxContent-Type: application/jsonAccept: application/json
说明：
请求头
请求体
{"DatasetName": "your-dataset-name-001","URI": "cos://examplebucket-1250000000/videos/interview_001.mp4","FaceId": "face_20260206_0001"}
请求参数
参数名称 | 描述 | 类型 | 是否必选 |
DatasetName | 数据集名称，同一个账户下唯一。命名规则：长度1 - 32字符，只能包含小写英文字母、数字、短划线（-），必须以英文字母或数字开头 | String | 是 |
URI | 需要进行人脸精确定位的媒资文件地址，取值为人脸粗搜（MediaFaceSearch）返回的 UriList 中的某一内部 URI，需包含完整的 COS 路径 | String | 是 |
FaceId | 人脸 ID，取值为人脸粗搜（MediaFaceSearch）返回的人脸 ID，用于在指定 URI 内部进行精确匹配 | String | 是 |
响应
响应头
响应体
响应体示例：视频媒资人脸定位返回结果
{"MediaClipList": [{"Score": 99.04,"LabelName": "张三","Category": "celebrity","OccurrencesInfos": [{"From": 61.066353,"To": 69.06635,"TrackData": [{"Timestamp": 62.03302,"BoxPosition": {"Left": 517,"Top": 409,"Width": 128,"Height": 168}}, {"Timestamp": 63.5,"BoxPosition": {"Left": 520,"Top": 412,"Width": 130,"Height": 170}}]}, {"From": 120.5,"To": 135.8,"TrackData": [{"Timestamp": 121.03302,"BoxPosition": {"Left": 300,"Top": 250,"Width": 140,"Height": 180}}]}]}],"RequestId": "E44FFACD-9E90-555A-A09A-6FD3B7335E39"}
响应包体具体数据内容如下：
参数名称 | 类型 | 描述 |
RequestId | String | 请求 ID |
MediaClipList | Container Array | 匹配到的媒资片段集合，按人物聚合，每个元素对应一个匹配到的人物 |
MediaClipList 节点内容：
参数名称 | 类型 | 描述 |
Score | Float | 匹配得分，取值范围 [0, 100]，数值越高表示相关性越强 |
LabelName | String | 实体/人物名称 |
Category | String | 人物类型，可选值：celebrity（名人）、sensitive（敏感人物）、politician（政治人物）、custom（自定义人物）、unknown（未知） |
OccurrencesInfos | Container Array | 人物片段聚类信息（仅视频媒资返回），描述该人物在媒资文件中出现的各个时间片段 |
OccurrencesInfos 节点内容：
参数名称 | 类型 | 描述 |
From | Float | 片段起始时间，单位为秒 |
To | Float | 片段结束时间，单位为秒 |
TrackData | Container Array | 人脸单帧详细信息列表，逐帧给出该人脸在片段内的时间戳与坐标框 |
TrackData 节点内容：
参数名称 | 类型 | 描述 |
Timestamp | Float | 人脸出现的时间戳，单位为秒（图片媒资无此字段） |
BoxPosition | Container | 人脸坐标框，标识该帧中人脸在画面中的位置 |
BoxPosition 节点内容：
参数名称 | 类型 | 描述 |
Left | Integer | 人脸框左上角横坐标，单位为像素 |
Top | Integer | 人脸框左上角纵坐标，单位为像素 |
Width | Integer | 人脸框宽度，单位为像素 |
Height | Integer | 人脸框高度，单位为像素 |
坐标框（BoxPosition）与时间片段（OccurrencesInfos）的含义如下图所示：
Left/Top 定位人脸框在画面中的左上角，Width/Height 描述人脸框大小；时间轴上高亮的多个区间即该人物出现的各个片段（From/To）。
实际案例
案例一：定位人脸在视频中的出现片段
在视频媒资中，先通过人脸粗搜得到
FaceId 与包含该人脸的视频 URI，再调用本接口定位该人脸在这个视频中的所有出现片段。返回结果中 Category=celebrity 表示人物分类为名人，OccurrencesInfos 给出多个时间片段，TrackData 逐帧提供 BoxPosition 坐标框。请求
POST /datasetquery/mediafaceclipsearch 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: 166Content-Type: application/jsonAccept: application/json{"DatasetName": "your-dataset-name-001","URI": "cos://examplebucket-1250000000/videos/interview_001.mp4","FaceId": "face_20260206_0001"}
响应
HTTP/1.1 200 OKContent-Type: application/jsonConnection: keep-aliveDate: Mon, 28 Jun 2022 15:23:12 GMTServer: tencent-cix-ci-request-id: NmExZDJiNzhfMjYyOTVhMTVfMTYyYzk0XzIxODg={"MediaClipList": [{"Score": 96,"LabelName": "张三","Category": "celebrity","OccurrencesInfos": [{"From": 58,"To": 62.115,"TrackData": [{"Timestamp": 60,"BoxPosition": {"Left": 618,"Top": 133,"Width": 146,"Height": 183}}]}, {"From": 70,"To": 75.769,"TrackData": [{"Timestamp": 73,"BoxPosition": {"Left": 646,"Top": 177,"Width": 175,"Height": 221}}]}, {"From": 131,"To": 138,"TrackData": [{"Timestamp": 134,"BoxPosition": {"Left": 662,"Top": 223,"Width": 177,"Height": 235}}]}, {"From": 197,"To": 200,"TrackData": [{"Timestamp": 198,"BoxPosition": {"Left": 707,"Top": 208,"Width": 159,"Height": 205}}]}]}],"RequestId": "NmExZDJiNzhfMjYyOTVhMTVfMTYyYzk0XzIxODg="}
案例二：定位人脸在图片中的位置
在图片媒资（
ImageSearch 模板，需开白）中，本接口返回该人脸在图片中的坐标框。由于图片无时间片段概念，OccurrencesInfos 中的 From/To/Timestamp 均为 0，属于预期行为。请求
POST /datasetquery/mediafaceclipsearch 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: 150Content-Type: application/jsonAccept: application/json{"DatasetName": "your-dataset-name-002","URI": "cos://examplebucket-1250000000/images/portrait_002.jpg","FaceId": "face_20260206_0002"}
响应
HTTP/1.1 200 OKContent-Type: application/jsonConnection: keep-aliveDate: Mon, 28 Jun 2022 15:23:12 GMTServer: tencent-cix-ci-request-id: NmExZDJiNzhfMjYyOTVhMTVfMTYyYzk0XzIxODg={"MediaClipList": [{"Score": 94,"LabelName": "李四","Category": "custom","OccurrencesInfos": [{"From": 0,"To": 0,"TrackData": [{"Timestamp": 0,"BoxPosition": {"Left": 220,"Top": 56,"Width": 184,"Height": 261}}]}]}],"RequestId": "NjYwYzEwYjhfNGQ2ODk0MGJfMjcxxxx"}
