Large Face List - Add Face From Url

服务:

Azure AI Services

API 版本:

1.0

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

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

配额：

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

POST {Endpoint}/face/v1.0/largefacelists/{largeFaceListId}/persistedfaces

具有可选参数:

POST {Endpoint}/face/v1.0/largefacelists/{largeFaceListId}/persistedfaces?userData={userData}&targetFace={targetFace}&detectionModel={detectionModel}

URI 参数

名称	在	必需	类型	说明
Endpoint	path	True	string	支持的认知服务终结点（协议和主机名，例如：https://westus.api.cognitive.microsoft.com）。
largeFaceListId	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。

请求头

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

请求正文

名称	必需	类型	说明
url	True	string	图像的可公开访问 URL

响应

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

安全性

Ocp-Apim-Subscription-Key

类型: apiKey
在: header

示例

Create large face list face example

示例请求

HTTP

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


{
  "url": "{Image Url here}"
}

示例响应

状态代码:

200

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

定义

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

APIError

Object

API 返回的错误信息

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

DetectionModel

枚举

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

值	说明
detection_01
detection_02
detection_03

Error

Object

错误正文。

名称	类型	说明
code	string
message	string

ImageUrl

Object

名称	类型	说明
url	string	图像的可公开访问 URL

PersistedFace

Object

PersonFace 对象。

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