调用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对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用背景高亮的方式表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作	访问级别	资源类型	条件关键字	关联操作
imm:FindSimilarFaces		全部资源 ``	无	无

请求参数

名称	类型	必填	描述	示例值
Project	string	是	项目名称。	immimagetest
SetId	string	是	媒体集的唯一标识。	set001
ImageUri	string	是	图片的 OSS URI。 OSS 地址规则为`oss://bucket/object`，其中 bucket 为和当前项目处于同一区域的 OSS Bucket 名称，object 为文件路径。	oss://imm-test/testcases/face1.jpg
FaceId	string	否	媒体集中已存在的人脸 ID。	59edc040d0a8f4952b183d1b5044913a0ccd8739500ee2705ffe4965a0406a51
Limit	integer	否	返回最相似图片的最大个数，默认值为 10，取值范围为 1~100。	5
MinSimilarity	float	否	过滤返回结果中相似度低于该值的图片。	0.8
ResponseFormat	string	否	返回值的格式版本，不设置此参数则返回值的格式为旧版本，推荐设置此参数为 v2。	v2

返回参数

名称	类型	描述	示例值
	object
RequestId	string	当次请求的 Request ID。	31A201C4-6824-4A8F-81FE-E0659FDDF1D7
Faces	array<object>	人脸信息。
Faces	object
FaceId	string	人脸 ID。	59edc040d0a8f4952b183d1b5044913a0ccd8739500ee2705ffe4965a0406a51
ImageUri	string	图片的 OSS URI。	oss://imm-test/testcases/face1.jpg
ExternalId	string	外部 ID，用于和您的应用层的 ID（如果有）进行绑定。如果图片加入媒体集时未设置此参数，则返回值为空。	external001
FaceAttributes	object	人脸属性。
FaceBoundary	object	人脸位置框。
Top	integer	顶点 Y 坐标，距离顶端距离。	191
Width	integer	人脸位置框宽度。	269
Height	integer	人脸位置框高度。	252
Left	integer	顶点 X 坐标，距离左端距离。	95
Similarity	float	人脸相似度，该值越大则人脸相似度越高，取值范围为 0～1。	0.8609305739402771
SimilarFaces	array<object>	相似人脸信息。
SimilarFaces	object
FaceId	string	相似人脸 ID。	98ae3c032337161f997a92f8ab9ac9624113368b9e4f93f6143d54a16e51b623
ImageUri	string	图片的 OSS URI。	oss://imm-test/testcases/face3.jpg
ExternalId	string	外部 ID，用于和您的应用层的 ID（如果有）进行绑定。如果图片加入媒体集时未设置此参数，则返回值为空。	external003
FaceAttributes	object	相似人脸属性。
FaceBoundary	object	人脸位置框。
Top	integer	顶点 Y 坐标，距离顶端距离。	152
Width	integer	人脸位置框宽度。	139
Height	integer	人脸位置框高度。	141
Left	integer	顶点 X 坐标，距离左端距离。	267
Similarity	float	人脸相似度，该值越大则人脸相似度越高，取值范围为 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
        }
      ]
    }
  ]
}

错误码

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