Person Directories - Add Face
添加新面孔。
POST {endpoint}/contentunderstanding/personDirectories/{personDirectoryId}/faces?api-version=2025-05-01-previewURI 参数
| 名称 | 在 | 必需 | 类型 | 说明 |
|---|---|---|---|---|
|
endpoint
|
path | True |
string (uri) |
内容理解服务终结点。 |
|
person
|
path | True |
string |
人员目录的唯一标识符。 |
|
api-version
|
query | True |
string minLength: 1 |
要用于此操作的 API 版本。 |
请求头
| 名称 | 必需 | 类型 | 说明 |
|---|---|---|---|
| x-ms-client-request-id |
string (uuid) |
请求的不透明、全局唯一的客户端生成的字符串标识符。 |
请求正文
| 名称 | 必需 | 类型 | 说明 |
|---|---|---|---|
| faceSource | True |
人脸的源。 |
|
| personId |
string |
要与人脸关联的人员标识符。 |
|
| qualityThreshold |
人脸质量阈值，低于该阈值则不会添加人脸。 默认值为 medium。 |
响应
| 名称 | 类型 | 说明 |
|---|---|---|
| 201 Created |
请求已成功，因此创建了一个新资源。 标头
|
|
| Other Status Codes |
意外的错误响应。 标头 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 |
示例
Add Face to Person Directory
示例请求
POST {endpoint}/contentunderstanding/personDirectories/myDirectory/faces?api-version=2025-05-01-preview
{
"faceSource": {
"url": "https://mystorageaccount.blob.core.windows.net/images/faces/face1.jpg",
"targetBoundingBox": {
"left": 0,
"top": 0,
"width": 640,
"height": 480
},
"imageReferenceId": "face1.jpg"
},
"qualityThreshold": "medium",
"personId": "4f66b612-e57d-4d17-9ef7-b951aea2cf0f"
}
示例响应
{
"faceId": "7a87f162-8dd5-4aea-8810-373e36b96b38",
"personId": "4f66b612-e57d-4d17-9ef7-b951aea2cf0f",
"boundingBox": {
"left": 33,
"top": 73,
"width": 262,
"height": 324
},
"imageReferenceId": "face1.jpg"
}定义
| 名称 | 说明 |
|---|---|
|
Add |
添加 face 参数。 |
|
Azure. |
错误对象。 |
|
Azure. |
包含错误详细信息的响应。 |
|
Azure. |
包含有关错误的更具体信息的对象。 根据 Azure REST API 准则 - https://aka.ms/AzureRestApiGuidelines#handling-errors。 |
|
Bounding |
图像中的边界框。 |
|
Face |
输入面源，具有可选的目标边界框。 如果未指定，将使用最大的人脸。 |
|
Person |
人员目录中的人脸。 |
|
Quality |
人脸质量阈值，低于该阈值则不会添加人脸。 默认值为 medium。 |
AddFaceParameters
添加 face 参数。
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| faceSource |
人脸的源。 |
||
| personId |
string |
要与人脸关联的人员标识符。 |
|
| qualityThreshold | medium |
人脸质量阈值，低于该阈值则不会添加人脸。 默认值为 medium。 |
Azure.Core.Foundations.Error
错误对象。
| 名称 | 类型 | 说明 |
|---|---|---|
| code |
string |
服务器定义的错误代码集之一。 |
| details |
导致此报告错误的特定错误的详细信息数组。 |
|
| innererror |
包含与当前对象有关错误的更具体信息的对象。 |
|
| message |
string |
有关错误的可读的表示形式。 |
| target |
string |
错误的目标。 |
Azure.Core.Foundations.ErrorResponse
包含错误详细信息的响应。
| 名称 | 类型 | 说明 |
|---|---|---|
| error |
错误对象。 |
Azure.Core.Foundations.InnerError
包含有关错误的更具体信息的对象。 根据 Azure REST API 准则 - https://aka.ms/AzureRestApiGuidelines#handling-errors。
| 名称 | 类型 | 说明 |
|---|---|---|
| code |
string |
服务器定义的错误代码集之一。 |
| innererror |
内部错误。 |
BoundingBox
图像中的边界框。
| 名称 | 类型 | 说明 |
|---|---|---|
| height |
integer (int32) |
边界框的高度。 |
| left |
integer (int32) |
边界框的左坐标。 |
| top |
integer (int32) |
边界框的 Top 坐标。 |
| width |
integer (int32) |
边界框的宽度。 |
FaceSource
输入面源，具有可选的目标边界框。 如果未指定，将使用最大的人脸。
| 名称 | 类型 | 说明 |
|---|---|---|
| data |
string (byte) |
Base64 编码的图像数据。 只应指定 url 或 data 中的一个。 |
| imageReferenceId |
string |
用户为源图像提供的标识符。 |
| targetBoundingBox |
指定感兴趣区域的边界框。 |
|
| url |
string (uri) |
图像 URL。 只应指定 url 或 data 中的一个。 |
PersonDirectoryFace
人员目录中的人脸。
| 名称 | 类型 | 说明 |
|---|---|---|
| boundingBox |
源图像中人脸的边界框。 |
|
| faceId |
string pattern: ^[a-zA-Z0-9._-]{1,64}$ |
人脸的唯一标识符。 |
| imageReferenceId |
string |
用户为源图像提供的标识符。 |
| personId |
string |
与人脸关联的人员（如果有）。 |
QualityForRecognition
人脸质量阈值，低于该阈值则不会添加人脸。 默认值为 medium。
| 值 | 说明 |
|---|---|
| low |
质量低。 |
| medium |
中等质量。 |
| high |
高质量。 |