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

Large Person Group Person - Add Face From Stream

Service:

Cognitive Services - Face

API Version:

1.0

将某个人员的人脸添加到大型人员组以进行人脸识别或验证。 若要处理包含多个人脸的图像，可以将输入人脸指定为具有 targetFace 矩形的图像。 它返回一个 persistedFaceId，表示添加的人脸。 不会存储任何图像。 只有提取的人脸特征将存储在服务器上，直到调用 LargePersonGroup PersonFace - Delete、 LargePersonGroup Person - Delete 或 LargePersonGroup - Delete 。
注意 persistedFaceId 不同于 Face - Detect 生成的 faceId。

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

POST {Endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces

With optional parameters:

POST {Endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces?overload=stream&userData={userData}&targetFace={targetFace}&detectionModel={detectionModel}

URI 参数

名称	在	必需	类型	说明
Endpoint	path	True	string	支持的认知服务终结点 (协议和主机名，例如： https://westus.api.cognitive.microsoft.com) 。
largePersonGroupId	path	True	string	引用特定大型人员组的 ID。 Regex pattern: ^[a-z0-9-_]+$
personId	path	True	string uuid	引用特定人员的 ID。
detectionModel	query		DetectionModel	检测模型的名称。 检测模型用于检测提交图像中的人脸。 执行人脸 - 检测或 (大型) 人脸列表 - 添加人脸或 (大型) PersonGroup - 添加人脸时，可以提供检测模型名称。 默认值为“detection_01”，如果需要其他模型，请显式指定它。
targetFace	query		integer[]	一个人脸矩形，用于指定要以“targetFace=left，top，width，height”格式添加到人员的目标人脸。 例如“targetFace=10,10,100,100”。 如果图像中有多个人脸，则需要 targetFace 来指定要添加的人脸。 没有 targetFace 意味着在整个图像中只检测到一张人脸。
userData	query		string	用户指定用于任何目的的人脸数据。 最大长度为 1KB。

请求头

Media Types: "application/octet-stream"

名称	必需	类型	说明
Ocp-Apim-Subscription-Key	True	string

请求正文

Media Types: "application/octet-stream"

名称	类型	说明
Image	object	图像流。

响应

名称	类型	说明
200 OK	PersistedFace	成功调用将返回新的 persistedFaceId。
Other Status Codes	APIError	错误响应。

安全性

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

示例

Add face to person with stream example

Sample Request

HTTP

POST {Endpoint}/face/v1.0/largepersongroups/abc/persons/4caa25ee-3bc6-4e88-adf8-12455ce7aab0/persistedfaces?overload=stream&userData={customized User data}&targetFace=10,10,100,100&detectionModel=detection_01


"{Image stream in base 64 encoded format}"

Sample Response

Status code:

200

{
  "persistedFaceId": "6e04c175-219e-42a2-9d26-0e7b790e1ef4"
}

定义

名称	说明
APIError	API 返回的错误信息
DetectionModel	检测模型的名称。 检测模型用于检测提交图像中的人脸。 执行人脸 - 检测或 (大型) 人脸列表 - 添加人脸或 (大型) PersonGroup - 添加人脸时，可以提供检测模型名称。 默认值为“detection_01”，如果需要其他模型，请显式指定它。
Error	错误正文。
PersistedFace	PersonFace 对象。

APIError

API 返回的错误信息

名称	类型	说明
error	Error	错误正文。

DetectionModel

检测模型的名称。 检测模型用于检测提交图像中的人脸。 执行人脸 - 检测或 (大型) 人脸列表 - 添加人脸或 (大型) PersonGroup - 添加人脸时，可以提供检测模型名称。 默认值为“detection_01”，如果需要其他模型，请显式指定它。

名称	类型	说明
detection_01	string
detection_02	string
detection_03	string

Error

错误正文。

名称	类型	说明
code	string
message	string

PersistedFace

PersonFace 对象。

名称	类型	说明
persistedFaceId	string	目标人脸的 persistedFaceId，该持久化且不会过期。 不同于 Face - Detect 创建的 faceId，将在检测调用后 faceIdTimeToLive 指定的时间过期。
userData	string	用户提供的数据附加到人脸。 大小限制为 1KB。