全部产品
云市场

FindSimilarFaces 相似人脸搜索

更新时间:2019-08-08 11:05:34

描述

从媒体集 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。
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。
FaceAttributes FaceAttributes 人脸属性

示例

请求示例

  1. POST https://imm.cn-shanghai.aliyuncs.com
  2. ?Action=FindSimilarFaces
  3. &Project=test-project
  4. &SetId=test-set
  5. &ImageUri=oss://imm-test/testcases/face.jpg
  6. ...

此处的示例,目的是展示关键参数,还需要其他的公共参数才能正常调用,推荐使用 SDK 来发送 API

成功返回示例 V2 新版本

  1. {
  2. "RequestId": "CA76409F-94F3-4A26-8DD7-D8B602A4DE24",
  3. "Faces": [
  4. {
  5. "SimilarFaces": [
  6. {
  7. "Similarity": 0.9996657967567444,
  8. "FaceId": "5f27a00a86563e75a6f6c6718292621eed8a07a870d39bcbe8f69d37cbaa7271",
  9. "FaceAttributes": {
  10. "FaceBoundary": {
  11. "Top": 66,
  12. "Height": 90,
  13. "Width": 90,
  14. "Left": 50
  15. }
  16. },
  17. "ImageUri": "oss://imm-test/testcases/face1.jpg"
  18. },
  19. {
  20. "Similarity": 0.9543278217315674,
  21. "FaceId": "9a3c05cecd79ef3864f803ce7a21276eb0213ba36f3a4c7145a38e0ea3bda041",
  22. "FaceAttributes": {
  23. "FaceBoundary": {
  24. "Top": 128,
  25. "Height": 177,
  26. "Width": 177,
  27. "Left": 226
  28. }
  29. },
  30. "ImageUri": "oss://imm-test/testcases/face2.jpg"
  31. }
  32. ],
  33. "FaceId": "ad1589086acd44b1312014987696233419d67cff533c535c5e70a07d7b2c590d",
  34. "FaceAttributes": {
  35. "FaceBoundary": {
  36. "Top": 140,
  37. "Height": 98,
  38. "Width": 111,
  39. "Left": 222
  40. }
  41. }
  42. },
  43. {
  44. "SimilarFaces": [
  45. {
  46. "Similarity": 0.999872088432312,
  47. "FaceId": "f0682734b743b1665ee801256c660702510e95c069f6a95e8a9ef8c4d7db97df",
  48. "FaceAttributes": {
  49. "FaceBoundary": {
  50. "Top": 66,
  51. "Height": 90,
  52. "Width": 90,
  53. "Left": 50
  54. }
  55. },
  56. "ImageUri": "oss://imm-test/testcases/face1.jpg"
  57. },
  58. {
  59. "Similarity": 0.31966283917427063,
  60. "FaceId": "0e543ac1c43cbe51f9fd735a800e78e2d63e376850eeb7fbacb3f1f6cec9471b",
  61. "FaceAttributes": {
  62. "FaceBoundary": {
  63. "Top": 3592,
  64. "Height": 93,
  65. "Width": 93,
  66. "Left": 1541
  67. }
  68. },
  69. "ImageUri": "oss://imm-test/testcases/face2.jpg"
  70. }
  71. ],
  72. "FaceId": "4e5c5ac4aa5e5764ce5b3ed3a84cf68b93f5a5cb8e671bcddd4ca655c2831f03",
  73. "FaceAttributes": {
  74. "FaceBoundary": {
  75. "Top": 65,
  76. "Height": 98,
  77. "Width": 99,
  78. "Left": 55
  79. }
  80. }
  81. }
  82. ]
  83. }

成功返回示例 V1 老版本

  1. {
  2. "RequestId": "1A88ACDC-EF09-41F9-A198-719947594517",
  3. "Faces": [
  4. {
  5. "Similarity": 0.86537508219480515,
  6. "FaceId": "f0682734b743b1665ee801256c660702510e95c069f6a95e8a9ef8c4d7db97df",
  7. "FaceAttributes": {
  8. "FaceBoundary": {
  9. "Top": 66,
  10. "Height": 90,
  11. "Width": 90,
  12. "Left": 50
  13. }
  14. },
  15. "ImageUri": "oss://imm-test/testcases/face1.jpg"
  16. },
  17. {
  18. "Similarity": 0.123883696645498276,
  19. "FaceId": "ca3f64d0bbb6309a57cece6fc9a956a9196bcd53be213b74e4968e8f555ad3ad",
  20. "FaceAttributes": {
  21. "FaceBoundary": {
  22. "Top": 3591,
  23. "Height": 93,
  24. "Width": 93,
  25. "Left": 1541
  26. }
  27. },
  28. "ImageUri": "oss://imm-test/testcases/face2.jpg"
  29. },
  30. {
  31. "Similarity": 0.0001236423721313,
  32. "FaceId": "5f27a00a86563e75a6f6c6718292621eed8a07a870d39bcbe8f69d37cbaa7271",
  33. "FaceAttributes": {
  34. "FaceBoundary": {
  35. "Top": 136,
  36. "Height": 94,
  37. "Width": 95,
  38. "Left": 219
  39. }
  40. },
  41. "ImageUri": "oss://imm-test/testcases/face3.jpg"
  42. }
  43. ]
  44. }

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