描述

从媒体集 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 时，两个人脸基本可以判断为同一人物。

搜索结果依赖索引的建立，返回结果与实际值可能有数秒的数据延迟。

请求参数

或

V2 版本返回值

该版本支持返回输入图的人脸框，并且在以图搜脸的场景下支持检测输入图的全部人脸，功能更强大，建议老用户尽快切换到该版本。

返回参数

数据类型 Faces

数据类型 SimilarFace

数据类型 FaceAttributes

V1 版本返回值

返回参数

数据类型 FaceSimilarity

示例

请求示例

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"
    }
  ]
}

若在使用中有疑问，请参考 FAQ，或者进入 钉钉用户群 实时交流。