通过

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

Person Directories - Identify Person

服务:
Azure AI Services
API 版本:
2025-05-01-preview

从人脸中识别人员。

POST {endpoint}/contentunderstanding/personDirectories/{personDirectoryId}/persons:identify?api-version=2025-05-01-preview

URI 参数

名称 在 必需 类型 说明
endpoint
 path True

string (uri)

内容理解服务终结点。
personDirectoryId
 path True

string

pattern: ^[a-zA-Z0-9._-]{1,64}$

人员目录的唯一标识符。
api-version
 query True

string

minLength: 1

要用于此操作的 API 版本。

请求头

名称 必需 类型 说明
x-ms-client-request-id

string (uuid)

请求的不透明、全局唯一的客户端生成的字符串标识符。

请求正文

名称 必需 类型 说明
faceSource True

FaceSource

人脸的源。
maxPersonCandidates

integer (int32)

要返回的最大候选项人数（最多 10 人）。

响应

名称 类型 说明
200 OK

IdentifyPersonResult

请求已成功。

标头

x-ms-client-request-id: string
Other Status Codes

Azure.Core.Foundations.ErrorResponse

意外的错误响应。

标头

x-ms-error-code: string

安全性

Ocp-Apim-Subscription-Key

类型: apiKey
在: header

OAuth2Auth

类型: oauth2
流向: accessCode
授权 URL: https://login.microsoftonline.com/common/oauth2/authorize
令牌 URL: https://login.microsoftonline.com/common/oauth2/token

作用域

名称 说明
https://cognitiveservices.azure.com/.default

示例

Identify the Person from a Face

示例请求

POST {endpoint}/contentunderstanding/personDirectories/myDirectory/persons:identify?api-version=2025-05-01-preview

{
  "faceSource": {
    "url": "https://mystorageaccount.blob.core.windows.net/images/faces/face1.jpg"
  },
  "maxPersonCandidates": 5
}

示例响应

状态代码:
200 
{
  "detectedFace": {
    "boundingBox": {
      "left": 33,
      "top": 73,
      "width": 262,
      "height": 324
    }
  },
  "personCandidates": [
    {
      "personId": "4f66b612-e57d-4d17-9ef7-b951aea2cf0f",
      "tags": {
        "name": "Paul",
        "age": "1"
      },
      "confidence": 0.92
    },
    {
      "personId": "19323b77-2012-487b-b131-09c318dc23df",
      "tags": {
        "name": "John",
        "age": "2"
      },
      "confidence": 0.65
    }
  ]
}

定义

名称 说明
Azure.Core.Foundations.Error

错误对象。
Azure.Core.Foundations.ErrorResponse

包含错误详细信息的响应。
Azure.Core.Foundations.InnerError

包含有关错误的更具体信息的对象。 根据 Azure REST API 准则 - https://aka.ms/AzureRestApiGuidelines#handling-errors。
BoundingBox

图像中的边界框。
DetectedBoundingBox

检测到对象的边界框。
FaceSource

输入面源，具有可选的目标边界框。 如果未指定，将使用最大的人脸。
IdentifyPersonParameters

确定人员参数。
IdentifyPersonResult

识别人员响应。
PersonCandidate

已确定的候选人。

Azure.Core.Foundations.Error

Object

错误对象。

名称 类型 说明
code

string

服务器定义的错误代码集之一。
details

Azure.Core.Foundations.Error[]

导致此报告错误的特定错误的详细信息数组。
innererror

Azure.Core.Foundations.InnerError

包含与当前对象有关错误的更具体信息的对象。
message

string

有关错误的可读的表示形式。
target

string

错误的目标。

Azure.Core.Foundations.ErrorResponse

Object

包含错误详细信息的响应。

名称 类型 说明
error

Azure.Core.Foundations.Error

错误对象。

Azure.Core.Foundations.InnerError

Object

包含有关错误的更具体信息的对象。 根据 Azure REST API 准则 - https://aka.ms/AzureRestApiGuidelines#handling-errors。

名称 类型 说明
code

string

服务器定义的错误代码集之一。
innererror

Azure.Core.Foundations.InnerError

内部错误。

BoundingBox

Object

图像中的边界框。

名称 类型 说明
height

integer (int32)

边界框的高度。
left

integer (int32)

边界框的左坐标。
top

integer (int32)

边界框的 Top 坐标。
width

integer (int32)

边界框的宽度。

DetectedBoundingBox

Object

检测到对象的边界框。

名称 类型 说明
boundingBox

BoundingBox

检测到的人脸的边界框。

FaceSource

Object

输入面源，具有可选的目标边界框。 如果未指定，将使用最大的人脸。

名称 类型 说明
data

string (byte)

Base64 编码的图像数据。 只应指定 url 或 data 中的一个。
imageReferenceId

string

用户为源图像提供的标识符。
targetBoundingBox

BoundingBox

指定感兴趣区域的边界框。
url

string (uri)

图像 URL。 只应指定 url 或 data 中的一个。

IdentifyPersonParameters

Object

确定人员参数。

名称 类型 默认值 说明
faceSource

FaceSource

人脸的源。
maxPersonCandidates

integer (int32)

1

要返回的最大候选项人数（最多 10 人）。

IdentifyPersonResult

Object

识别人员响应。

名称 类型 说明
detectedFace

DetectedBoundingBox

检测到的人脸的详细信息。
personCandidates

PersonCandidate[]

与输入人脸匹配的候选项列表。

PersonCandidate

Object

已确定的候选人。

名称 类型 说明
confidence

number (float)

与输入人脸匹配的人员的置信度分数。
personId

string

pattern: ^[a-zA-Z0-9._-]{1,64}$

人员的唯一标识符。
tags

object

与人员关联的标记。