通过

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

Person Directories - Find Similar Faces

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

查找相似的面孔。

POST {endpoint}/contentunderstanding/personDirectories/{personDirectoryId}/faces:find?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

FaceSource

人脸的源。
maxSimilarFaces

integer (int32)

要返回的相似面的最大数量（最多 1000 个）。

响应

名称 类型 说明
200 OK

FindSimilarFacesResult

请求已成功。

标头

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

示例

Find Similar Faces

示例请求

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

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

示例响应

状态代码:
200 
{
  "detectedFace": {
    "boundingBox": {
      "left": 67,
      "top": 13,
      "width": 273,
      "height": 313
    }
  },
  "similarFaces": [
    {
      "faceId": "7a87f162-8dd5-4aea-8810-373e36b96b38",
      "boundingBox": {
        "left": 33,
        "top": 73,
        "width": 262,
        "height": 324
      },
      "imageReferenceId": "face1.jpg",
      "confidence": 0.99
    },
    {
      "faceId": "f28b3cda-4005-44b6-8518-6fcddef108cb",
      "boundingBox": {
        "left": 87,
        "top": 96,
        "width": 235,
        "height": 345
      },
      "imageReferenceId": "face2.jpg",
      "confidence": 0.98
    }
  ]
}

定义

名称 说明
Azure.Core.Foundations.Error

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

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

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

图像中的边界框。
DetectedBoundingBox

检测到对象的边界框。
FaceSource

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

查找相似面参数。
FindSimilarFacesResult

查找相似的人脸响应。
SimilarFace

在 person 目录中找到类似的面孔。

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 中的一个。

FindSimilarFacesParameters

Object

查找相似面参数。

名称 类型 默认值 说明
faceSource

FaceSource

人脸的源。
maxSimilarFaces

integer (int32)

1000

要返回的相似面的最大数量（最多 1000 个）。

FindSimilarFacesResult

Object

查找相似的人脸响应。

名称 类型 说明
detectedFace

DetectedBoundingBox

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

SimilarFace[]

相似面的列表。

SimilarFace

Object

在 person 目录中找到类似的面孔。

名称 类型 说明
boundingBox

BoundingBox

源图像中人脸的边界框。
confidence

number (float)

此人脸与输入人脸匹配的置信度。
faceId

string

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

人脸的唯一标识符。
imageReferenceId

string

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

string

与人脸关联的人员（如果有）。