AI 助理
备案控制台
文档
输入文档关键字查找
首页 视觉智能开放平台 开发参考 API参考 人脸人体 人脸识别 人脸搜索1:N 批量添加人脸数据

批量添加人脸数据

更新时间：
产品详情
我的收藏

本文介绍人脸人体（facebody）类目下的批量添加人脸数据BatchAddFaces的语法及示例。

功能描述

批量添加人脸数据能力可以为已创建好的人脸样本中批量添加人脸数据，每个人脸样本最多可以添加5张人脸照片，所以批量添加最多一次添加5张人脸照片。

说明
  • 您可以进入在线咨询获取在线人工帮助。
  • 阿里云视觉智能开放平台视觉AI能力API接入、接口使用或问题咨询等，请通过钉钉群（23109592）加入阿里云视觉智能开放平台咨询群联系我们。

接入指引

1. 注册阿里云账号：打开阿里云官网，在阿里云官网右上角，单击立即注册，按照操作提示完成账号注册。

2. 开通能力：请确保您已开通人脸人体服务，若未开通服务请立即开通。

重要

本能力支持企业或个人认证用户开通。更多实名认证操作信息，请参见实名认证。

3. 创建AccessKey：请确保您已创建AccessKey，如果您使用的是子账号AccessKey，您需要给子账号赋予AliyunVIAPIFullAccess权限，具体操作，请参见RAM授权。

4. 在线调试（可选）：您可以通过OpenAPI Explorer在线调试能力，查看完整的调用示例代码及SDK依赖信息，也可以下载完整的工程。

5. 开发接入步骤：

  • 在SDK总览中选择您要接入使用的SDK语言。
  • 在对应语言的SDK文档中找到AI类目为人脸人体（facebody）的SDK包进行安装。
  • 参考文档中提供的示例代码进行适当修改后调用。

6. 客户端直接调用：该能力常用的客户端调用方式包括以下几种。

输入限制

  • 图像格式：JPG、JPEG、PNG、BMP。
  • 图像大小：不超过5 MB。
  • 图像分辨率：大于32×32像素，小于4096×4096像素。人脸占比不低于64×64像素。
  • URL地址中不能包含中文字符。
说明 当图像分辨率超过最大限制时，请先将图片进行缩放，调整图片大小，具体请参见图片缩放。

限制说明

批量添加人脸数据接口提交任务并发默认为2QPS。

计费说明

批量添加人脸数据能力可免费调用。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称

类型

是否必选

示例值

描述
Action String 是 BatchAddFaces

系统规定参数。取值：BatchAddFaces。
DbName String 是 default

数据库名称。支持小写字母、数字、下划线的组合，长度1~64。
EntityId String 是 U1

实体ID，用来标识用户的唯一性，如用户ID、员工ID等。每个实体可包含多张人脸图片。支持大小写字母、数字、下划线、减号的组合，长度为2~64字符。
SimilarityScoreThresholdInEntity Float 否 50.0

类内相似度阈值。将新增人脸图片与EntityId内已有人脸进行相似比对，小于该阈值则表示与其他人脸图片差异较大，添加失败.；若EntityId内没有人脸存在，则添加成功。取值范围[0.0,100.0]。0.0或空则表示不做类内相似度判断逻辑。参考值见人脸比对1:1接口的返回结果字段Thresholds。
SimilarityScoreThresholdBetweenEntity Float 否 50.0

类间相似度阈值。将新增人脸图片与其他所有EntityId内已有人脸进行相似比对，大于等于该阈值则表示其他EntityId内存在相似人脸，出现重复，添加失败。取值范围[0.0,100.0]。0.0或空则表示不做类间相似度判断逻辑。参考值见人脸比对1:1接口的返回结果字段Thresholds。

说明 类间相似度阈值检查仅适用于每个EntityId下首次上传的第一张人脸图片。
Faces Array 是

人脸信息。
ExtraData String 否 王小二

自定义信息。支持字母、数字、标点符号和汉字。不超过512个字符。
ImageURL String 是 https://viapi-test.oss-cn-shanghai.aliyuncs.com/test/imgsearch/demo/1.png

人脸图像URL地址。人脸必须是正面无遮挡单人人脸。推荐使用上海地域的OSS链接，对于文件在本地或者非上海地域OSS链接的情况，请参见文件URL处理。
QualityScoreThreshold Float 否 50.0

质量分阈值。对新增人脸图片进行质量分析判断，得到的质量分小于该阈值则表示新增人脸图片质量不符合要求，添加失败。取值范围[0.0,100.0]。0.0或空则表示不做质量分判断逻辑。

返回数据

名称

类型

示例值

描述
RequestId String C46A46D0-3263-181A-A1EE-0901E4595390

请求ID。
Data Object

返回的结果数据内容。
InsertedFaces Array of insertedFaces

添加成功的记录结果。
ImageURL String https://viapi-test.oss-cn-shanghai.aliyuncs.com/test/imgsearch/demo/xxxx.png

人脸图像地址，与输入的ImageUrl相同，用来标记图像记录。
FaceId String 16350536

输出人脸ID。
QualitieScore Float 99.79581

输入图像中的人脸质量分。
FailedFaces Array of failedFaces

添加失败的记录结果。
ImageURL String https://viapi-test.oss-cn-shanghai.aliyuncs.com/test/imgsearch/demo/xxxx.png

人脸图像地址，与输入的ImageUrl相同，用来标记图像记录。
Code String ClientError.IllegalArgument

错误码。
Message String not found the db=test

错误信息。

SDK参考

阿里云视觉AI人脸人体类目下的批量添加人脸数据能力推荐使用SDK调用，支持多种编程语言，调用时请选择AI类目为人脸人体（facebody）的SDK包，文件参数通过SDK调用可支持本地文件及任意URL，具体可参见SDK总览。

示例

请求示例

http(s)://facebody.cn-shanghai.aliyuncs.com/?Action=BatchAddFaces      //更多关于访问域名（Endpoint）信息，请参见：https://help.aliyun.com/document_detail/143103.html
&DbName=default
&EntityId=U1
&SimilarityScoreThresholdInEntity=50.0
&SimilarityScoreThresholdBetweenEntity=50.0
&Faces=[{"ExtraData":"王小二","ImageURL":"https://viapi-test.oss-cn-shanghai.aliyuncs.com/test/imgsearch/demo/1.png"}]
&QualityScoreThreshold=50.0
&公共请求参数

正常返回示例

XML格式

HTTP/1.1 200 OK
Content-Type:application/xml

<BatchAddFacesResponse>
    <RequestId>C46A46D0-3263-181A-A1EE-0901E4595390</RequestId>
    <Data>
        <InsertedFaces>
            <ImageURL>https://viapi-test.oss-cn-shanghai.aliyuncs.com/test/imgsearch/demo/xxxx.png</ImageURL>
            <FaceId>16350536</FaceId>
            <QualitieScore>99.79581</QualitieScore>
        </InsertedFaces>
        <FailedFaces>
            <ImageURL>https://viapi-test.oss-cn-shanghai.aliyuncs.com/test/imgsearch/demo/xxxx.png</ImageURL>
            <Code>ClientError.IllegalArgument</Code>
            <Message>not found the db=test</Message>
        </FailedFaces>
    </Data>
</BatchAddFacesResponse>

JSON格式

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "C46A46D0-3263-181A-A1EE-0901E4595390",
  "Data" : {
    "InsertedFaces" : [ {
      "ImageURL" : "https://viapi-test.oss-cn-shanghai.aliyuncs.com/test/imgsearch/demo/xxxx.png",
      "FaceId" : "16350536",
      "QualitieScore" : 99.79581
    } ],
    "FailedFaces" : [ {
      "ImageURL" : "https://viapi-test.oss-cn-shanghai.aliyuncs.com/test/imgsearch/demo/xxxx.png",
      "Code" : "ClientError.IllegalArgument",
      "Message" : "not found the db=test"
    } ]
  }
}

错误码

关于批量添加人脸数据的错误码，详情请参见常见错误码。

安全声明

  • 请确保上传的图片或文件来源符合相应的法律法规。
  • 通过体验调试上传的临时文件有效期为1小时，在24小时后会被系统自动清理删除。
  • 平台不存储用户在使用服务过程中涉及的原始人脸图片或文件信息。
  • 平台针对超过6个月及以上没有API服务调用的用户的人脸特征向量数据进行冻结，确保无服务调用的客户信息安全。如需解冻，请通过钉钉群（23109592）联系我们。

上一篇：添加人脸数据下一篇：删除人脸
文档推荐