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

Face List - Add Face From Url

Service:

Cognitive Services - Face

API Version:

1.0

将最多 1,000 张人脸添加到指定的人脸列表。
若要处理包含多个人脸的图像，可以将输入人脸指定为具有 targetFace 矩形的图像。 它返回一个 persistedFaceId，表示添加的人脸。 不会存储任何图像。 在调用 FaceList - 删除 人脸或 FaceList - Delete 之前，只会将提取的人脸特征存储在服务器上。
请注意 persistedFaceId 不同于 Face - Detect 生成的 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

With optional parameters:

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

URI 参数

名称	在	必需	类型	说明
Endpoint	path	True	string	支持的认知服务终结点 (协议和主机名，例如： https://westus.api.cognitive.microsoft.com) 。
faceListId	path	True	string	引用特定人脸列表的 ID。 Regex pattern: ^[a-z0-9-_]+$
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	用户指定用于任何用途的人脸数据。 最大长度为 1KB。

请求头

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

请求正文

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

响应

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

安全性

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

示例

Create face list face example

Sample Request

HTTP

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


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

Sample Response

Status code:

200

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

定义

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

APIError

API 返回的错误信息

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

DetectionModel

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

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

Error

错误正文。

名称	类型	说明
code	string
message	string

ImageUrl

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

PersistedFace

PersonFace 对象。

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