你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Face - Identify

参考

服务:: Azure AI Services

API 版本:: 1.0

一对多的识别，用于在人员组或大型人员组中查找与特定查询人脸最接近的匹配项。
对于 faceIds 数组中的每个人脸，人脸识别将计算查询人脸与人员组（由 personGroupId 给出）或大型人员组（由 largePersonGroupId 给出）中的所有人脸之间的相似性，并返回该人脸的相似性置信度排名。应训练人员组/大型人员组，使其做好识别准备。有关详细信息，请参阅 PersonGroup - 训练和 LargePersonGroup - 训练。

备注：

该算法允许在同一请求中独立识别多个人脸，但不超过 10 张人脸。
人员组/大型人员组中的每个人可以有多个人脸，但不超过 248 张人脸。
更高的人脸图像质量意味着更好的识别精度。请考虑高质量的人脸：正面、清晰和人脸大小为 200x200 像素（眼睛之间的 100 像素）或更大。
返回的候选项数受 maxNumOfCandidatesReturned 和 confidenceThreshold 的限制。如果未识别任何人员，则返回的候选项将为空数组。
尝试人脸 - 当你需要从人脸列表/大型人脸列表而不是人员组/大型人员组查找相似人脸时，请查找类似的。
与查询人脸关联的“recognitionModel”faceId 应与目标人员组或大型人员组使用的“recognitionModel”相同。

POST {Endpoint}/face/v1.0/identify

URI 参数

名称	在	必需	类型	说明
Endpoint	path	True	string	支持的认知服务终结点（协议和主机名，例如：https://westus.api.cognitive.microsoft.com）。

请求头

名称	必需	类型	说明
Ocp-Apim-Subscription-Key	True	string

请求正文

名称	必需	类型	说明
faceIds	True	string[] (uuid)	由人脸 - 检测创建的查询人脸 faceId 的数组。每个人脸都是独立识别的。 faceId 的有效数目介于 [1， 10] 之间。
confidenceThreshold		number minimum: 0 maximum: 1	识别的置信度阈值，用于判断一张人脸是否属于一个人。 confidenceThreshold 的范围为 [0， 1] （默认由算法指定）。
largePersonGroupId		string maxLength: 64 pattern: ^[a-z0-9-_]+$	由 LargePersonGroup - Create 创建的目标大型人员组的 LargePersonGroupId。不应同时提供参数 personGroupId 和 largePersonGroupId。
maxNumOfCandidatesReturned		integer minimum: 1 maximum: 100	maxNumOfCandidatesReturned 的范围介于 1 和 100 之间（默认值为 1）。
personGroupId		string maxLength: 64 pattern: ^[a-z0-9-_]+$	由 PersonGroup 创建的目标人员组的 PersonGroupId - 创建。不应同时提供参数 personGroupId 和 largePersonGroupId。

响应

名称	类型	说明
200 OK	IdentifyResult[]	成功的调用返回每个查询人脸的已识别候选人员。
Other Status Codes	APIError	错误响应。

安全性

Ocp-Apim-Subscription-Key

类型: apiKey
在: header

示例

Identify example

示例请求

HTTP

POST {Endpoint}/face/v1.0/identify


{
  "largePersonGroupId": "sample_group",
  "faceIds": [
    "c5c24a82-6845-4031-9d5d-978df9175426",
    "65d083d4-9447-47d1-af30-b626144bf0fb"
  ],
  "maxNumOfCandidatesReturned": 1,
  "confidenceThreshold": 0.5
}

示例响应

状态代码:: 200

[
  {
    "faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
    "candidates": [
      {
        "personId": "25985303-c537-4467-b41d-bdb45cd95ca1",
        "confidence": 0.92
      }
    ]
  },
  {
    "faceId": "65d083d4-9447-47d1-af30-b626144bf0fb",
    "candidates": [
      {
        "personId": "2ae4935b-9659-44c3-977f-61fac20d0538",
        "confidence": 0.89
      }
    ]
  }
]

定义

名称	说明
APIError	API 返回的错误信息
Error	错误正文。
IdentifyCandidate	所有可能符合资格的人脸。
IdentifyRequest	用于标识人脸作的请求正文。
IdentifyResult	用于标识人脸作的响应正文。

APIError

Object

API 返回的错误信息

名称	类型	说明
error	Error	错误正文。

Error

Object

错误正文。

名称	类型	说明
code	string
message	string

IdentifyCandidate

Object

所有可能符合资格的人脸。

名称	类型	说明
confidence	number minimum: 0 maximum: 1	识别的置信度阈值，用于判断一张人脸是否属于一个人。 confidenceThreshold 的范围为 [0， 1] （默认由算法指定）。
personId	string (uuid)	候选项的 ID

IdentifyRequest

Object

用于标识人脸作的请求正文。

名称	类型	默认值	说明
confidenceThreshold	number minimum: 0 maximum: 1		识别的置信度阈值，用于判断一张人脸是否属于一个人。 confidenceThreshold 的范围为 [0， 1] （默认由算法指定）。
faceIds	string[] (uuid)		由人脸 - 检测创建的查询人脸 faceId 的数组。每个人脸都是独立识别的。 faceId 的有效数目介于 [1， 10] 之间。
largePersonGroupId	string maxLength: 64 pattern: ^[a-z0-9-_]+$		由 LargePersonGroup - Create 创建的目标大型人员组的 LargePersonGroupId。不应同时提供参数 personGroupId 和 largePersonGroupId。
maxNumOfCandidatesReturned	integer minimum: 1 maximum: 100	1	maxNumOfCandidatesReturned 的范围介于 1 和 100 之间（默认值为 1）。
personGroupId	string maxLength: 64 pattern: ^[a-z0-9-_]+$		由 PersonGroup 创建的目标人员组的 PersonGroupId - 创建。不应同时提供参数 personGroupId 和 largePersonGroupId。

IdentifyResult

Object

用于标识人脸作的响应正文。

名称	类型	说明
candidates	IdentifyCandidate[]	确定该人脸的候选人（按信心排名）。数组大小不应大于输入 maxNumOfCandidatesReturned。如果未识别任何人员，则返回空数组。
faceId	string (uuid)	查询人脸的 FaceId

通过

Face - Identify

URI 参数

请求头

请求正文

响应

安全性

Ocp-Apim-Subscription-Key

示例

Identify example

示例请求

示例响应

定义

APIError

Error

IdentifyCandidate

IdentifyRequest

IdentifyResult