文档首页/人脸识别服务 FRS/API参考/API/人脸库资源管理/创建人脸库 - CreateFaceSet
更新时间：2025-12-04 GMT+08:00
查看PDF
分享

创建人脸库 - CreateFaceSet

功能介绍

创建用于存储人脸特征的人脸库。您最多可以创建10个人脸库，每个人脸库最大容量为10万个人脸特征。

前提条件：

请确保您已开通人脸识别服务，具体操作方法请参见申请服务。

application/json请求的body中，请使用标准Json格式。

URI

POST /v2/{project_id}/face-sets

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

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

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

是

String

用户Token。

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

Content-Type

是

String

发送的实体的MIME类型，参数值为“application/json”。

表3 请求Body参数

参数名

参数类型

是否必选

说明

face_set_name

String

是

人脸库的名称。

建议人脸库的名称不要以下划线“_”开头，否则云监控服务会无法采集人脸数量。

face_set_capacity

Integer

否

人脸库最大的容量，填写1万整数倍的数字，例如：30000。

默认为100000，最大值为100000。每个用户可使用10个人脸库，每个人脸库容量为10万个人脸特征。

external_fields

Map<String,TypeInfo>

否

用户自定义数据，自定义字段不能以vector、bounding_box、external_image_id、face_id、create_time、_id、_all、_source等字段命名，这些字段为内置字段，自定义字段避免使用。

自定义字段的key值长度范围为[1,36]，string类型的value长度范围为[1,256]，具体参见自定义字段。

如果在后续操作中，使用该自定义字段向人脸库中添加人脸，需要在创建人脸库时定义该字段。

表4 TypeInfo

参数

是否必选

参数类型

描述

type

否

String

数据类型支持string、integer、double、long等。

响应参数

状态码：200

表5 响应Body参数

参数

参数类型

描述

face_set_info

FaceSetInfo object

人脸库信息，详见FaceSetInfo。 调用失败时无此字段。

表6 FaceSetInfo

参数

参数类型

描述

face_number

Integer

人脸库中已有的人脸特征的数量。

external_fields

Object

用户的自定义字段。

face_set_id

String

人脸库ID，随机生成的包含八个字符的字符串。

face_set_name

String

人脸库名称。

create_date

String

创建时间。

face_set_capacity

Integer

人脸库最大的容量。创建人脸库时，请求参数如果不设置face_set_capacity参数，默认每个人脸库最大容量为10万个人脸特征。

状态码： 400

表7 响应Body参数

参数

参数类型

描述

error_code

String

调用失败时的错误码。 调用成功时无此字段。

error_msg

String

调用失败时的错误信息。 调用成功时无此字段。

请求示例

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

  • 请求样例 
    POST https://{endpoint}/v2/{project_id}/face-sets
Request Header:
Content-Type: application/json
X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...

Request Body:
{
  "face_set_name": "test", 
  "face_set_capacity": 100000,
  "external_fields" : {
    "timestamp" : {
      "type" : "long"
    },
    "id" : {
      "type" : "string"
    },
    "number" : {
      "type" : "integer"
    }
  }

}

响应示例

状态码：200

成功响应样例 
{
  "face_set_info": {
    "face_number": 0,
    "face_set_id": "WYYOFIGb",
    "face_set_name": "test",
    "create_date": "2018-05-28 02:19:00",
    "face_set_capacity": 100000,
    "external_fields": {
      "timestamp" : {
        "type" : "long"
      },
      "id" : {
        "type" : "string"
      },
      "number" : {
        "type" : "integer"
      }
    }
  }

}

状态码：400

失败响应样例 
{
  "error_code": "FRS.0002",
  "error_msg": "The authentication token is abnormal."
}

状态码

状态码请参见状态码。

错误码

错误码请参见错误码。