更新时间:2023-04-25 GMT+08:00

查询人脸

功能介绍

查询指定人脸库中人脸信息。

前提条件:

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

URI

GET /v2/{project_id}/face-sets/{face_set_name}/faces?offset=xxx&limit=xxx

或者

GET /v2/{project_id}/face-sets/{face_set_name}/faces?face_id={face_id}

表1 路径参数

参数

是否必选

参数类型

描述

project_id

String

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

face_set_name

人脸库名称。

表2 Query参数

参数

是否必选

参数类型

描述

offset

否,与face_id二选一

Integer

从第几条数据读起,默认为0。

limit

否,与face_id二选一

Integer

读取多少条,默认为5。

face_id

否,与offset二选一

String

人脸ID。

offset+limit值不能超过10000。人脸识别系统非存储系统,暂时不支持数据遍历操作,用户可以自行保存face_id,根据face_id查询导入的人脸信息。

请求参数

表3 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

String

用户Token。

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

Content-Type

String

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

响应参数

状态码:200

表4 响应Body参数

参数

参数类型

描述

face_set_id

String

人脸库ID,随机生成的包含八个字符的字符串。 调用失败时无此字段。

face_set_name

String

人脸库名称。 调用失败时无此字段。

faces

Array of FaceSetFace objects

人脸库当中的人脸结构,详见FaceSetFace。 调用失败时无此字段。

表5 FaceSetFace

参数

参数类型

描述

bounding_box

BoundingBox object

人脸在图像中的位置。 BoundingBox结构见BoundingBox

external_fields

Object

用户添加的额外字段。

external_image_id

String

人脸所在的外部图片ID。

face_id

String

人脸ID,由系统内部生成的唯一ID。

表6 BoundingBox

参数

参数类型

描述

width

Integer

矩形框宽度。

top_left_y

Integer

矩形框左上角纵坐标。

top_left_x

Integer

矩形框左上角横坐标。

height

Integer

矩形框高度。

状态码: 400

表7 响应Body参数

参数

参数类型

描述

error_code

String

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

error_msg

String

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

请求示例

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

  • 请求样例
    GET https://{endpoint}/v2/{project_id}/face-sets/showFaceSet/faces?offset=0&limit=1
    Request Header:
    Content-Type: application/json
    X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...

响应示例

状态码: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": "aIzRAa58",
      "face_id": "cFydu4d2",
      "external_fields": {
        "number": 122,
        "id": "home",
        "timestamp": 12
      }
    }
  ]
}

状态码:400

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

状态码

状态码请参见状态码

错误码

错误码请参见错误码