通过

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

Faces - Compare

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

比较两张面之间的相似性。

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

URI 参数

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

string (uri)

内容理解服务终结点。
api-version
 query True

string

minLength: 1

要用于此操作的 API 版本。

请求头

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

string (uuid)

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

请求正文

名称 必需 类型 说明
faceSource1 True

FaceSource

要比较的第一个面。
faceSource2 True

FaceSource

要比较的第二个面。

响应

名称 类型 说明
200 OK

CompareFacesResult

请求已成功。
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

示例

Compare the Similarity Between Two Faces

示例请求

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

{
  "faceSource1": {
    "url": "https://mystorageaccount.blob.core.windows.net/images/faces/face1.jpg",
    "targetBoundingBox": {
      "left": 33,
      "top": 73,
      "width": 262,
      "height": 324
    }
  },
  "faceSource2": {
    "data": "RXhhbXBsZSBGaWxl"
  }
}

示例响应

状态代码:
200 
{
  "detectedFace1": {
    "boundingBox": {
      "left": 33,
      "top": 73,
      "width": 262,
      "height": 324
    }
  },
  "detectedFace2": {
    "boundingBox": {
      "left": 87,
      "top": 96,
      "width": 235,
      "height": 345
    }
  },
  "confidence": 0.95
}

定义

名称 说明
Azure.Core.Foundations.Error

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

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

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

图像中的边界框。
CompareFacesParameters

比较面参数。
CompareFacesResult

比较人脸响应。
DetectedBoundingBox

检测到对象的边界框。
FaceSource

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

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)

边界框的宽度。

CompareFacesParameters

Object

比较面参数。

名称 类型 说明
faceSource1

FaceSource

要比较的第一个面。
faceSource2

FaceSource

要比较的第二个面。

CompareFacesResult

Object

比较人脸响应。

名称 类型 说明
confidence

number (float)

人脸比较的置信度分数。
detectedFace1

DetectedBoundingBox

检测到的第一个人脸的详细信息。
detectedFace2

DetectedBoundingBox

检测到的第二张人脸的详细信息。

DetectedBoundingBox

Object

检测到对象的边界框。

名称 类型 说明
boundingBox

BoundingBox

检测到的人脸的边界框。

FaceSource

Object

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

名称 类型 说明
data

string (byte)

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

string

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

BoundingBox

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

string (uri)

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