文档

FindSimilarFaces - 查找和指定人脸相似的人脸

更新时间:

从媒体集中搜索与指定图片或人脸ID最相似的前N张图片,并返回相应人脸ID及边界框,返回结果按照相似度降序排列。

接口说明

  • 此接口已不再维护,建议使用新版(2020-09-30 版本)接口 CreateFacesSearchingTask 。关于新版与旧版 API 的对比,请参见新旧版本使用指引中的新版与旧版 API 对应关系说明章节。

  • 您可以使用如下两种方式从媒体集中搜索与人脸最相似的前 N 张图片。

    • 通过传入媒体集中人脸 ID 进行搜索,具体步骤如下:

    说明 返回值中 Faces 的首个元素一定是传入的 FaceId,系统不会对结果进行过滤。
    1. 调用 CreateSet 接口创建媒体集。

    2. 调用 IndexImage 接口将图片索引到媒体集。

    3. 调用 ListImages 或 GetImage 接口获取需要进行搜索的人脸 ID。

    4. 使用媒体集中的人脸 ID,将人脸 ID 作为输入值,从媒体集中搜索与人脸 ID 对应人脸最相似的前 N 张图片。

    • 通过传入图片的 OSS URI 进行搜索,具体步骤如下:

    说明 当传入的 ImageUri 在媒体集中存在时,则返回值中 Faces 的首个元素一定是传入的 ImageUri 内的同一个人脸,系统不会对结果进行过滤。
    1. 将图片上传到 OSS。
    2. 使用图片的 OSS URI,将图片中的人脸作为输入值,从媒体集中搜索与图片中人脸最相似的前 N 张图片。
  • 当两个人脸的相似度 Similarity>0.8 时,两个人脸基本可以判断为同一人物。

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

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

授权信息

当前API暂无授权信息透出。

请求参数

名称类型必填描述示例值
Projectstring

项目名称。

immimagetest
SetIdstring

媒体集的唯一标识。

set001
ImageUristring

图片的 OSS URI。

OSS 地址规则为oss://bucket/object,其中 bucket 为和当前项目处于同一区域的 OSS Bucket 名称,object 为文件路径。

oss://imm-test/testcases/face1.jpg
FaceIdstring

媒体集中已存在的人脸 ID。

59edc040d0a8f4952b183d1b5044913a0ccd8739500ee2705ffe4965a0406a51
Limitinteger

返回最相似图片的最大个数,默认值为 10,取值范围为 1~100。

5
MinSimilarityfloat

过滤返回结果中相似度低于该值的图片。

0.8
ResponseFormatstring

返回值的格式版本,不设置此参数则返回值的格式为旧版本,推荐设置此参数为 v2。

v2

返回参数

名称类型描述示例值
object
RequestIdstring

当次请求的 Request ID。

31A201C4-6824-4A8F-81FE-E0659FDDF1D7
Facesobject []

人脸信息。

FaceIdstring

人脸 ID。

59edc040d0a8f4952b183d1b5044913a0ccd8739500ee2705ffe4965a0406a51
ImageUristring

图片的 OSS URI。

oss://imm-test/testcases/face1.jpg
ExternalIdstring

外部 ID,用于和您的应用层的 ID(如果有)进行绑定。

如果图片加入媒体集时未设置此参数,则返回值为空。

external001
FaceAttributesobject

人脸属性。

FaceBoundaryobject

人脸位置框。

Topinteger

顶点 Y 坐标,距离顶端距离。

191
Widthinteger

人脸位置框宽度。

269
Heightinteger

人脸位置框高度。

252
Leftinteger

顶点 X 坐标,距离左端距离。

95
Similarityfloat

人脸相似度,该值越大则人脸相似度越高,取值范围为 0~1。

0.8609305739402771
SimilarFacesobject []

相似人脸信息。

FaceIdstring

相似人脸 ID。

98ae3c032337161f997a92f8ab9ac9624113368b9e4f93f6143d54a16e51b623
ImageUristring

图片的 OSS URI。

oss://imm-test/testcases/face3.jpg
ExternalIdstring

外部 ID,用于和您的应用层的 ID(如果有)进行绑定。

如果图片加入媒体集时未设置此参数,则返回值为空。

external003
FaceAttributesobject

相似人脸属性。

FaceBoundaryobject

人脸位置框。

Topinteger

顶点 Y 坐标,距离顶端距离。

152
Widthinteger

人脸位置框宽度。

139
Heightinteger

人脸位置框高度。

141
Leftinteger

顶点 X 坐标,距离左端距离。

267
Similarityfloat

人脸相似度,该值越大则人脸相似度越高,取值范围为 0~1。

0.8609305739402771

示例

正常返回示例

JSON格式

{
  "RequestId": "31A201C4-6824-4A8F-81FE-E0659FDDF1D7",
  "Faces": [
    {
      "FaceId": "59edc040d0a8f4952b183d1b5044913a0ccd8739500ee2705ffe4965a0406a51",
      "ImageUri": "oss://imm-test/testcases/face1.jpg",
      "ExternalId": "external001",
      "FaceAttributes": {
        "FaceBoundary": {
          "Top": 191,
          "Width": 269,
          "Height": 252,
          "Left": 95
        }
      },
      "Similarity": 0.860930573940277,
      "SimilarFaces": [
        {
          "FaceId": "98ae3c032337161f997a92f8ab9ac9624113368b9e4f93f6143d54a16e51b623",
          "ImageUri": "oss://imm-test/testcases/face3.jpg",
          "ExternalId": "external003",
          "FaceAttributes": {
            "FaceBoundary": {
              "Top": 152,
              "Width": 139,
              "Height": 141,
              "Left": 267
            }
          },
          "Similarity": 0.860930573940277
        }
      ]
    }
  ]
}

错误码

访问错误中心查看更多错误码。

  • 本页导读 (1)
文档反馈