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

Face List Operations - Add Face List Face From Url

Service:

Azure AI Services

API Version:

v1.1-preview.1

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

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

• • 人脸图像质量越高，识别精度就越高。 请考虑高质量的人脸：正面、清晰、人脸大小为 200x200 像素 (100 像素，眼睛) 或更大。
  • 每人参赛最多可以容纳 248 张人脸。
  • 支持 JPEG、PNG、GIF (第一帧) 和 BMP 格式。 允许的图像文件大小为 1KB 到 6MB。
  • “targetFace”矩形应包含一个面。 零张或多张人脸将被视为错误。 如果提供的“targetFace”矩形未从“Detect”返回，则不能保证成功检测和添加人脸。
  • 超过可检测的人脸大小 (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

With optional parameters:

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。 Regex pattern: ^[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	意外的错误响应。 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 FaceList from Url

Sample Request

HTTP

POST {endpoint}/face/v1.1-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"
}

Sample Response

Status code:

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	错误对象。