一、接口描述
人脸定位媒资片段与人脸查找媒资配合构成先找到人、再定位片段的两段式人脸检索链路：
·人脸查找媒资（MediaFaceSearch）：输入一张人脸图片，快速找出该人脸出现在数据集中的哪些媒资文件，返回 FaceId 与媒资文件列表（UriList）。
·人脸定位媒资片段（MediaFaceClipSearch）：输入人脸查找媒资返回的 FaceId 与其中一个媒资文件 URI，精确定位该人脸在这个文件中出现的时间片段与逐帧坐标框。
二、授权说明
通过子账号使用时，需要在 授权策略 的 action 中添加 ci:DatasetFaceSearch 权限。数据万象支持的所有操作接口请参见 CI action。
三、服务开通
首次使用该功能时将默认为你开通数据万象，同时该存储桶将自动绑定数据万象，无需角色授权，即可直接使用。
四、使用限制
·使用检索前需要先完成 创建数据集，并选择 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
注意：说明：
注意：Authorization: Auth String，详情请参见 请求签名 文档。
八、请求头
此接口仅使用公共请求头部，详情请参见 公共请求头部 文档。
九、请求体
{ "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"}
20、响应
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"}
21、错误码
该请求操作无特殊错误信息，常见的错误信息请参见 错误码 文档。