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

Face List Operations - Add Face List Face From Url

服务:

Azure AI Services

API 版本:

v1.2-preview.1

将人脸添加到指定的人脸列表，最多 1,000 张人脸。
若要处理包含多个人脸的图像，可以将输入人脸指定为具有 targetFace 矩形的图像。 它返回一个持久化FaceId，表示添加的人脸。 不会存储任何图像。 只有提取的人脸功能存储在服务器上，直到调用“删除人脸列表”或“删除人脸列表”。

请注意，persistedFaceId 不同于“Detect”生成的 faceId。

• • 更高的人脸图像质量意味着更好的识别精度。 请考虑高质量的人脸：正面、清晰和人脸大小为 200x200 像素（眼睛之间的 100 像素）或更大。
  • 每个人的输入最多可以容纳 248 张人脸。
  • 支持 JPEG、PNG、GIF（第一帧）和 BMP 格式。 允许的图像文件大小从 1KB 到 6MB。
  • “targetFace”矩形应包含一个人脸。 零张或多张人脸将被视为错误。 如果未从“检测”返回提供的“targetFace”矩形，则无法成功检测和添加人脸。
  • 无法检测到的人脸大小（36x36 - 4096x4096 像素）、大头部姿势或大遮挡将导致故障。
  • 最小可检测人脸大小在图像中不超过 1920x1080 像素的 36x36 像素。 尺寸高于 1920x1080 像素的图像将需要比例更大的最小人脸大小。
  • 可以提供不同的“detectionModel”值。 若要使用和比较不同的检测模型，请参阅 https://learn.microsoft.com/azure/ai-services/computer-vision/how-to/specify-detection-model

POST {endpoint}/face/{apiVersion}/facelists/{faceListId}/persistedfaces

具有可选参数:

POST {endpoint}/face/{apiVersion}/facelists/{faceListId}/persistedfaces?targetFace={targetFace}&detectionModel={detectionModel}&userData={userData}

URI 参数

名称	在	必需	类型	说明
apiVersion	path	True	string	API 版本
endpoint	path	True	string uri	支持的认知服务终结点（协议和主机名，例如：https://{resource-name}.cognitiveservices.azure.com）。
faceListId	path	True	string	有效字符是小写字母或数字或“-”或“_”，最大长度为 64。 正则表达式模式: ^[a-z0-9-_]+$
detectionModel	query		DetectionModel	与检测到的 faceId 关联的“detectionModel”。 支持的“detectionModel”值包括“detection_01”、“detection_02”和“detection_03”。 默认值为“detection_01”。
targetFace	query		integer[]	一个人脸矩形，用于指定要添加到人员的目标人脸，格式为“targetFace=left，top，width，height”。
userData	query		string	附加到人脸的用户提供的数据。 大小限制为 1K。

请求正文

名称	必需	类型	说明
url	True	string	输入图像的 URL。

响应

名称	类型	说明
200 OK	AddFaceResult	成功的调用返回新的 persistedFaceId。
Other Status Codes	FaceErrorResponse	意外的错误响应。 标头 x-ms-error-code: string

安全性

Ocp-Apim-Subscription-Key

Azure AI 人脸订阅的密钥。

类型: apiKey
在: header

AADToken

Azure Active Directory OAuth2 流

类型: oauth2
流向: accessCode
授权 URL: https://api.example.com/oauth2/authorize
令牌 URL: https://api.example.com/oauth2/token

作用域

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

示例

Add Face to FaceList from Url

示例请求

HTTP

POST {endpoint}/face/v1.2-preview.1/facelists/your_face_list_id/persistedfaces?targetFace=10,10,100,100&detectionModel=detection_01&userData=your_user_data

{
  "url": "https://microsoft.com/example.jpg"
}

示例响应

状态代码:

200

{
  "persistedFaceId": "43897a75-8d6f-42cf-885e-74832febb055"
}

定义

名称	说明
AddFaceResult	用于添加人脸的响应正文。
DetectionModel	与检测到的 faceId 关联的“detectionModel”。 支持的“detectionModel”值包括“detection_01”、“detection_02”和“detection_03”。 默认值为“detection_01”。
FaceError	错误对象。 有关人脸服务返回的错误代码和消息的综合详细信息，请参阅以下链接：https://aka.ms/face-error-codes-and-messages。
FaceErrorResponse	包含错误详细信息的响应。

AddFaceResult

用于添加人脸的响应正文。

名称	类型	说明
persistedFaceId	string	已添加人脸的持久化人脸 ID，该 ID 持久化且不会过期。 不同于在“检测”中创建的 faceId，将在检测调用后 24 小时内过期。

DetectionModel

与检测到的 faceId 关联的“detectionModel”。 支持的“detectionModel”值包括“detection_01”、“detection_02”和“detection_03”。 默认值为“detection_01”。

名称	类型	说明
detection_01	string	默认检测模型。 建议用于近正面人脸检测。 对于具有异常大角度（头部姿势）人脸、遮挡人脸或错误图像方向的方案，可能无法检测到此类情况下的人脸。
detection_02	string	检测模型于 2019 年 5 月发布，提高了准确性，尤其是在小面和模糊的脸上。
detection_03	string	2021 年 2 月发布的检测模型，提高了准确性，尤其是在小脸上。

FaceError

错误对象。 有关人脸服务返回的错误代码和消息的综合详细信息，请参阅以下链接：https://aka.ms/face-error-codes-and-messages。

名称	类型	说明
code	string	服务器定义的错误代码集之一。
message	string	错误的人工可读表示形式。

FaceErrorResponse

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

名称	类型	说明
error	FaceError	错误对象。