FindSimilarFaces 相似人脸搜索
描述
从媒体集 Set 中,搜索与指定图片或人脸 ID 最相似的前 N 张图片,并返回其人脸 ID 及边界框。结果按相似度降序排列。
该接口有两种使用方法,一种是传入一个媒体集 Set 内的人脸 ID FaceId
进行搜索。可以通过 ListImages 或 GetImage 等接口来获取该值。
注意,该方法调用时,返回值中
Faces
字段的首个元素一定是传入的FaceId
本身,IMM 不会对结果进行过滤。
另一种是直接传入图片的 OSS URI ,将以图片中的人脸作为输入值,从 Set 中搜索与其相似的人脸。
若您使用的是旧版返回值(即 ResponseFormat
为空或 v1
),则此时以图片中 最大 人脸作为输入值。建议尽快切换到 v2
版本。
注意,该方法调用时,若传入的
ImageUri
在 Set 内存在,则返回值中Faces
字段的首个元素一定是传入的ImageUri
内的同一个人脸,IMM 不会对结果进行过滤。相似度 Similarity > 0.8 时,两个人脸基本可以判断为同一人物。
搜索结果依赖索引的建立,返回结果与实际值可能有数秒的数据延迟。
请求参数
Parameter | Type | Required | Comment |
---|---|---|---|
Project | string | Y | Project 名称。 |
SetId | string | Y | 媒体集 Set 的唯一标识,将从该 Set 中进行搜索。 |
FaceId | string | Y | Set 中已存在的人脸 ID FaceId |
ResponseFormat | string | N | 返回值格式版本,留空为旧版本。强烈推荐传入值 v2 ,参考 V2 版本返回值 |
Limit | int | N | 返回结果的最大数量,1~100,默认10 |
MinSimilarity | float | N | 返回结果中过滤相似度低于该值的结果。 |
或
Parameter | Type | Required | Comment |
---|---|---|---|
Project | string | Y | Project 名称。 |
SetId | string | Y | 媒体集 Set 的唯一标识,将从该 Set 中进行搜索。 |
ImageUri | string | Y | 图片 OSS URI,如 oss://imm-test/testcases/face.jpg OSS 地址规则为: oss://bucket/object ,其中 bucket 为和当前 Project 在同一区域的 OSS 桶名, object 为文件路径。 |
ResponseFormat | string | N | 返回值格式版本,留空为旧版本。强烈推荐传入值 v2 ,参考 V2 版本返回值 |
Limit | int | N | 返回结果的最大数量,1~100,默认10 |
MinSimilarity | float | N | 返回结果中过滤相似度低于该值的结果。 |
V2 版本返回值
该版本支持返回输入图的人脸框,并且在以图搜脸的场景下支持检测输入图的全部人脸,功能更强大,建议老用户尽快切换到该版本。
返回参数
Parameter | Type | Comment |
---|---|---|
RequestId | string | 该次请求的唯一识别码。 |
Faces | []Faces | 原图人脸的列表。若以 FaceId 搜索,则列表只有一个元素。若以 FaceUri 搜索,则可能有多个元素。 |
数据类型 Faces
Parameter | Type | Comment |
---|---|---|
FaceId | string | 用于唯一标识该人脸。 |
SimilarFaces | SimilarFace | 该人脸的相似人脸列表 |
FaceAttributes | FaceAttributes | 人脸属性 |
数据类型 SimilarFace
Parameter | Type | Comment |
---|---|---|
FaceId | string | 用于唯一标识该人脸。 |
Similarity | float | 该人脸与目标人脸的相似度,0~1。 |
ImageUri | string | 该人脸所属图片的 OSS URI。 |
ExternalId | string | 该人脸所属图片 ExternalId。 |
FaceAttributes | FaceAttributes | 人脸属性 |
数据类型 FaceAttributes
Parameter | Type | Comment |
---|---|---|
FaceBoundary | Boundary | 人脸位置框。 |
V1 版本返回值
返回参数
Parameter | Type | Comment |
---|---|---|
RequestId | string | 该次请求的唯一识别码。 |
Similarity | float | 相似度,0~1 |
Faces | []FaceSimilarity | 相似人脸的列表 |
数据类型 FaceSimilarity
Parameter | Type | Comment |
---|---|---|
FaceId | string | 用于唯一标识该人脸。 |
Similarity | float | 该人脸与目标人脸的相似度,0~1。 |
ImageUri | string | 该人脸所属图片的 OSS URI。 |
ExternalId | string | 该人脸所属图片 ExternalId。 |
FaceAttributes | FaceAttributes | 人脸属性 |
示例
请求示例
POST https://imm.cn-shanghai.aliyuncs.com
?Action=FindSimilarFaces
&Project=test-project
&SetId=test-set
&ImageUri=oss://imm-test/testcases/face.jpg
...
此处的示例,目的是展示关键参数,还需要其他的公共参数才能正常调用,推荐使用 SDK 来发送 API。
成功返回示例 V2 新版本
{
"RequestId": "CA76409F-94F3-4A26-8DD7-D8B602A4DE24",
"Faces": [
{
"SimilarFaces": [
{
"Similarity": 0.9996657967567444,
"FaceId": "5f27a00a86563e75a6f6c6718292621eed8a07a870d39bcbe8f69d37cbaa7271",
"FaceAttributes": {
"FaceBoundary": {
"Top": 66,
"Height": 90,
"Width": 90,
"Left": 50
}
},
"ImageUri": "oss://imm-test/testcases/face1.jpg"
},
{
"Similarity": 0.9543278217315674,
"FaceId": "9a3c05cecd79ef3864f803ce7a21276eb0213ba36f3a4c7145a38e0ea3bda041",
"FaceAttributes": {
"FaceBoundary": {
"Top": 128,
"Height": 177,
"Width": 177,
"Left": 226
}
},
"ImageUri": "oss://imm-test/testcases/face2.jpg"
}
],
"FaceId": "ad1589086acd44b1312014987696233419d67cff533c535c5e70a07d7b2c590d",
"FaceAttributes": {
"FaceBoundary": {
"Top": 140,
"Height": 98,
"Width": 111,
"Left": 222
}
}
},
{
"SimilarFaces": [
{
"Similarity": 0.999872088432312,
"FaceId": "f0682734b743b1665ee801256c660702510e95c069f6a95e8a9ef8c4d7db97df",
"FaceAttributes": {
"FaceBoundary": {
"Top": 66,
"Height": 90,
"Width": 90,
"Left": 50
}
},
"ImageUri": "oss://imm-test/testcases/face1.jpg"
},
{
"Similarity": 0.31966283917427063,
"FaceId": "0e543ac1c43cbe51f9fd735a800e78e2d63e376850eeb7fbacb3f1f6cec9471b",
"FaceAttributes": {
"FaceBoundary": {
"Top": 3592,
"Height": 93,
"Width": 93,
"Left": 1541
}
},
"ImageUri": "oss://imm-test/testcases/face2.jpg"
}
],
"FaceId": "4e5c5ac4aa5e5764ce5b3ed3a84cf68b93f5a5cb8e671bcddd4ca655c2831f03",
"FaceAttributes": {
"FaceBoundary": {
"Top": 65,
"Height": 98,
"Width": 99,
"Left": 55
}
}
}
]
}
成功返回示例 V1 老版本
{
"RequestId": "1A88ACDC-EF09-41F9-A198-719947594517",
"Faces": [
{
"Similarity": 0.86537508219480515,
"FaceId": "f0682734b743b1665ee801256c660702510e95c069f6a95e8a9ef8c4d7db97df",
"FaceAttributes": {
"FaceBoundary": {
"Top": 66,
"Height": 90,
"Width": 90,
"Left": 50
}
},
"ImageUri": "oss://imm-test/testcases/face1.jpg"
},
{
"Similarity": 0.123883696645498276,
"FaceId": "ca3f64d0bbb6309a57cece6fc9a956a9196bcd53be213b74e4968e8f555ad3ad",
"FaceAttributes": {
"FaceBoundary": {
"Top": 3591,
"Height": 93,
"Width": 93,
"Left": 1541
}
},
"ImageUri": "oss://imm-test/testcases/face2.jpg"
},
{
"Similarity": 0.0001236423721313,
"FaceId": "5f27a00a86563e75a6f6c6718292621eed8a07a870d39bcbe8f69d37cbaa7271",
"FaceAttributes": {
"FaceBoundary": {
"Top": 136,
"Height": 94,
"Width": 95,
"Left": 219
}
},
"ImageUri": "oss://imm-test/testcases/face3.jpg"
}
]
}
版权声明
本文仅代表作者观点,不代表本站立场。
本文系作者授权发表,未经许可,不得转载。
评论