文档首页 > > API参考> 人脸识别API(V1)> 人脸资源管理>

添加人脸

添加人脸

分享
更新时间:2021/04/19 GMT+08:00

功能介绍

添加人脸到人脸库中,检测到传入的单张图片中存在多少张人脸,则增加多少张人脸到人脸库当中。

前提条件:

约束限制:
  • 只支持识别JPG、PNG、JPEG、BMP格式的图片。
  • application/json请求的body中,请使用标准Json格式。
  • Base64编码中请勿使用回车换行。
  • 系统不保存用户图片。
  • 图片大小小于8MB,由于过大图片会导致时延较长,并且图片信息量不大,建议小于1MB
  • 图片分辨率小于4096*2160,图片中人脸像素大于80*80,建议120*120以上。
  • 为保证识别效果,人脸图片建议要求如下:
    1. 光照大于200lux、无反光强光阴影现象。
    2. 人脸无遮挡、整体清晰无拖尾抖动等运动模糊。
    3. 侧脸不超过30°、俯仰角小于15°、偏转角小于15°、图片中人脸保持竖置正脸。
  • 其他的约束限制信息请参见约束与限制章节。
建议:
  • 由于过大图片对识别算法精度无明显提升,同时会导致时延较长,建议传入图片小于1MB,一般500KB左右足够。
  • OBS上存储的图片也建议小于1MB
  • 图片中人脸像素建议120*120以上。

URI

POST /v1/{project_id}/face-sets/{face_set_name}/faces

表1 路径参数

参数

是否必选

参数类型

描述

project_id

String

项目ID,获取方法请参见获取项目ID/账号名/AK/SK

face_set_name

String

人脸库名称。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

String

用户Token。

Token认证就是在调用API的时候将Token加到请求消息头,从而通过身份认证,获得操作API的权限,响应消息头中X-Subject-Token的值即为Token。

表3 请求Body参数

参数名

参数类型

是否必选

说明

image_url

String

与image_file、image_base64三选一

图片的URL路径,目前仅支持华为云上OBS的URL,且人脸识别服务有权限读取该OBS桶的数据。开通读取权限的操作请参见服务授权

image_file

File

与image_url、image_base64三选一

本地图片文件,图片不能超过8MB,建议小于1MB。上传文件时,请求格式为multipart。

image_base64

String

与image_file、image_url三选一

图像数据,Base64编码,要求:
  • Base64编码后大小不超过8MB,建议小于1MB
  • 图片为JPG/JPEG/BMP/PNG格式。

external_image_id

String

用户指定的图片外部ID,与当前图像绑定。用户没提供,系统会生成一个。

该ID长度范围为1~36位,可以包含字母、数字、中划线或者下划线,不包含其他的特殊字符。

external_fields

Json

根据用户自定义数据类型,填入相应的数值。

需在创建人脸库时定义external_fields字段,才可以在添加人脸时使用该字段,Json字符串不校验重复性,参考自定义字段

响应参数

状态码:200

表4 响应Body参数

参数名

参数类型

说明

face_set_name

String

人脸库名称。

调用失败时无此字段。

face_set_id

String

人脸库ID。

调用失败时无此字段。

faces

List

人脸库当中的人脸结构,详见FaceSetFace

调用失败时无此字段。

error_code

String

调用失败时的错误码,具体请参考错误码

调用成功时无此字段。

error_msg

String

调用失败时的错误信息。

调用成功时无此字段。

请求示例

X-Auth-Token值获取方法请参见认证鉴权

  • 请求样例(方式一:使用图片的BASE64编码)
    POST https://{endpoint}/v1/{project_id}/face-sets/showFaceSet/faces
    Request Header:
    Content-Type: application/json
    X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...
    
    Request Body:
    {
      "image_base64": "/9j/4AAQSkZJRgABAgEASABIAAD",
      "external_image_id": "imageID",
      "external_fields": {
         "timestamp": 12,
         "id": "home"
      }
    }
  • 请求样例(方式二:使用图片文件)
    POST https://{endpoint}/v1/{project_id}/face-sets/showFaceSet/faces
    Request Header:
    X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...
    
    Request Body:
    image_file: File(图片文件)
    external_image_id: imageID
    external_fields: {"timestamp" : 12,"id" : "home"}
  • 请求样例(方式三:使用图片URL)
    POST https://{endpoint}/v1/{project_id}/face-sets/showFaceSet/faces
    Request Header:
    Content-Type: application/json
    X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...
    
    Request Body:
    {
      "image_url":"/BucketName/ObjectName",
      "external_image_id":"imageID",
      "external_fields" : {
         "timestamp": 12,
         "id": "home"
      } 
    }
  • Python3语言请求代码示例(其他语言参照下列示例编写或使用FRS SDK)
    # -*- coding:utf-8 -*-
    
    import requests
    import base64
    
    endpoint = '开通服务所在region的人脸识别服务域名'
    project_id = '开通服务所在region的用户项目ID'
    token = '用户获取得到的实际token值'
    headers = {'Content-Type': 'application/json', 'X-Auth-Token': token}
    
    face_set_name = 'showFaceSet'
    url = "https://{endpoint}/v1/{project_id}/face-sets/{face_set_name}/faces".format(
        endpoint=endpoint,project_id=project_id,face_set_name=face_set_name)
    imagepath = r'./data/face-demo.png'
    with open(imagepath, "rb") as bin_data:
        image_data = bin_data.read()
    image_base64 = base64.b64encode(image_data).decode("utf-8")
    body = {
            "image_base64": image_base64,
            "external_image_id": "imageID",
            "external_fields": {
                "timestamp": 12,
                "id": "home"
            }
    	}
    response = requests.post(url, headers=headers, json=body, verify=False)
    print(response.text) 
    

响应示例

状态码:200

成功响应样例
{
  "face_set_id": "T785tx1N",
  "face_set_name": "showFaceSet",
  "faces": [
    {
      "bounding_box": {
        "width": 63,
        "top_left_y": 100,
        "top_left_x": 221,
        "height": 63
      },
      "external_image_id": "Xr0phyap",
      "external_fields" : {
        "timestamp": 12,
        "id": "home"
      },
      "face_id": "JLa9hYLl"
    }
  ]
}

状态码:400

失败响应样例
{
  "error_code": "FRS.0404",
  "error_msg": "Detect no face, can not add it to face set."
}

状态码

状态码请参见状态码

错误码

错误码请参见错误码

分享:

    相关文档

    相关产品

文档是否有解决您的问题?

提交成功!非常感谢您的反馈,我们会继续努力做到更好!
反馈提交失败,请稍后再试!

*必选

请至少选择或填写一项反馈信息

字符长度不能超过200

提交反馈 取消

如您有其它疑问,您也可以通过华为云社区论坛频道来与我们联系探讨

智能客服提问云社区提问