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

Face List Operations - Add Large Face List Face From Url

Service:

Azure AI Services

API Version:

v1.1-preview.1

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

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

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

注意

• • 免费层订阅配额：每个大型人脸列表 1,000 张人脸。
  • S0 层订阅配额：每个大型人脸列表 1,000,000 张人脸。

POST {endpoint}/face/{apiVersion}/largefacelists/{largeFaceListId}/persistedfaces

With optional parameters:

POST {endpoint}/face/{apiVersion}/largefacelists/{largeFaceListId}/persistedfaces?targetFace={targetFace}&detectionModel={detectionModel}&userData={userData}

URI 参数

名称	在	必需	类型	说明
apiVersion	path	True	string	API 版本
endpoint	path	True	string uri	支持的认知服务终结点 (协议和主机名，例如：https://{resource-name}.cognitiveservices.azure.com) 。
largeFaceListId	path	True	string	有效字符是小写字母、数字或“-”或“_”，最大长度为 64。 Regex pattern: ^[a-z0-9-_]+$
detectionModel	query		DetectionModel	与检测到的 faceIds 关联的“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	意外的错误响应。 Headers x-ms-error-code: string

安全性

Ocp-Apim-Subscription-Key

Azure AI 人脸订阅的密钥。

Type: apiKey
In: header

AADToken

Azure Active Directory OAuth2 流

Type: oauth2
Flow: accessCode
Authorization URL: https://api.example.com/oauth2/authorize
Token URL: https://api.example.com/oauth2/token

Scopes

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

示例

Add Face to LargeFaceList from Url

Sample Request

HTTP

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

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

Sample Response

Status code:

200

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

定义

名称	说明
AddFaceResult	用于添加人脸的响应正文。
DetectionModel	与检测到的 faceIds 关联的“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

与检测到的 faceIds 关联的“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	错误对象。