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

Large Person Group Person - Add Face From Stream

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

  • 更高的人脸图像质量意味着更好的识别精度。 请考虑高质量的人脸:正面、清晰且人脸大小为 200x200 像素, (眼睛之间的 100 像素) 或更大。
  • 每个人的输入最多可以容纳 248 张人脸。
  • 支持 JPEG、PNG、GIF (第一帧) 和 BMP 格式。 允许的图像文件大小从 1KB 到 6MB。
  • “targetFace”矩形应包含一个人脸。 零张或多张人脸将被视为错误。 如果未从人脸返回提供的“targetFace”矩形 - 检测,则无法保证成功检测和添加人脸。
  • 无法检测到的人脸大小 (36x36 - 4096x4096 像素) 、大头部姿势或大遮挡将导致故障。
  • 将按顺序处理向/从同一个人添加/删除人脸。 向/从不同人员添加/删除人脸时,将并行处理人脸。
  • 最小可检测人脸大小在图像中不超过 1920x1080 像素的 36x36 像素。 尺寸大于 1920x1080 像素的图像将需要比例较大的最小人脸大小。
  • 可以提供不同的“detectionModel”值。 若要使用和比较不同的检测模型,请参阅 如何指定检测模型
POST {Endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces
POST {Endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces?overload=stream&userData={userData}&targetFace={targetFace}&detectionModel={detectionModel}

URI 参数

Name In Required Type Description
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

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

targetFace
query
  • array

一个人脸矩形,用于指定要添加到“targetFace=left,top,width,height”格式的人员。 例如“targetFace=10,10,100,100”。 如果图像中有多个人脸,则需要 targetFace 来指定要添加的人脸。 没有 targetFace 意味着整个图像中只检测到一个人脸。

userData
query
  • string

用户指定的人脸数据用于任何目的。 最大长度为 1KB。

请求头

Media Types: "application/octet-stream"

Name Required Type Description
Ocp-Apim-Subscription-Key True
  • string

请求正文

Media Types: "application/octet-stream"

Name Type Description
Image
  • object

图像流。

响应

Name Type Description
200 OK

成功的调用返回新的 persistedFaceId。

Other Status Codes

错误响应。

安全性

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

示例

Add face to person with stream example

Sample Request

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

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

定义

APIError

API 返回的错误信息

DetectionModel

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

Error

错误正文。

PersistedFace

PersonFace 对象。

APIError

API 返回的错误信息

Name Type Description
error

错误正文。

DetectionModel

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

Name Type Description
detection_01
  • string
detection_02
  • string
detection_03
  • string

Error

错误正文。

Name Type Description
code
  • string
message
  • string

PersistedFace

PersonFace 对象。

Name Type Description
persistedFaceId
  • string

目标人脸的 persistedFaceId(持久化且不会过期)。 与 Face - Detect 创建的 faceId 不同,检测将在检测调用后 faceIdTimeToLive 指定的时间过期。

userData
  • string

附加到人脸的用户提供的数据。 大小限制为 1KB。