Face List - Add Face From Stream

服务:

Azure AI Services

API 版本:

1.0

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

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

POST {Endpoint}/face/v1.0/facelists/{faceListId}/persistedfaces

具有可选参数:

POST {Endpoint}/face/v1.0/facelists/{faceListId}/persistedfaces?overload=stream&userData={userData}&targetFace={targetFace}&detectionModel={detectionModel}

URI 参数

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

请求头

Media Types: "application/octet-stream"

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

请求正文

Media Types: "application/octet-stream"

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

响应

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

安全性

Ocp-Apim-Subscription-Key

类型: apiKey
在: header

示例

Add face to face list from stream example

示例请求

HTTP

POST {Endpoint}/face/v1.0/facelists/sample_face_list/persistedfaces?overload=stream&userData={Customized user data}&targetFace=10,10,100,100&detectionModel=detection_01


"{Image stream in base 64 encoded format}"

示例响应

状态代码:

200

{
  "persistedFaceId": "B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA"
}

定义

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

APIError

Object

API 返回的错误信息

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

DetectionModel

枚举

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

值	说明
detection_01
detection_02
detection_03

Error

Object

错误正文。

名称	类型	说明
code	string
message	string

PersistedFace

Object

PersonFace 对象。

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