人脸特征提取API使用文档

本文档主要针对HTTP API调用者,创迹AI开放平台需注册后申请服务授权调用API。 本文以“人脸特征提取”能力为例,指引您开启开发之旅。

1、能力介绍

从给定的图片中进行人脸检测,并返回人脸面积最大的一张人脸特征。用于用户自建人脸库。

2、调用方式

该接口主要用于HTTP API调用,服务授权请参考[接入指南-API接入指南],根据指南进行服务授权,授权后进行API使用。

3、请求说明

HTTP方法:POST

接口请求域名:service.trial-power.com

请求URL:https://service.trial-power.com/aiop_oauth/oauth/service

Headers:

参数名称 必选 类型 描述
Content-Type String application/json
Authorization String 访问token:可通过控制台服务的appKey,secretkey和servicekey生成,具体方式请参考:“API token获取” 注意:有效期为30天,切记需要每30天进行定期更换,或者每次请求都拉取新token;

Query:

参数名称 必选 类型 描述
action String 公共参数,本接口取值:aiservice-facefeature
version String API版本号,当前版本号:1

Body:

参数名称 必选 类型 描述
image String 图片的base64数据,base64编码后大小不可超过5M。需要注意的是,图片的base64编码不包含图片头, 如data:image/jpg;base64,图片格式:现支持PNG、JPG、JPEG、BMP,不支持GIF图片。
例如:
{
  "image": "/9j/4AAQSkZJRgABAQAAAQABAAD/4gIoSUNDX1BST0ZJTEUAAQEAAAIYAAAAAAIQAABtbnRy
          iAAAAAAAAAAAAAAAABhY3NwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAA9tYAAQAAAAD
          AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAlkZXNjAAAA8A
          aAAABZAAAABRnWFlaAAABeAAAABRiWFlaAAABjAAAABRyVFJDAAABoAAAAChnVFJDAAABoAAAA
          ABoAAAACh3dHB0AAAByAAAABRjcHJ0AAAB3AAAADxtbHVjAAAAAAAAAAEAAAAMZW5VUwAAAFgA
          gBHAEIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
          AAAAAAAAAAAAAAAAAAAAAAAAAAAAAFh......"
}
        

4、返回结果

名称 说明
code 返回结果信息码
data 识别结果数据
msg 描述信息
status API状态

data详细:

名称 说明
faceFeature 图片中人脸面积最大的人脸特征值
featureID 人脸特征值对应的唯一值

例如:

{
    "code": 200,
    "data": {
        "faceFeature": "RKx0odRU4ki56i+gIiCwyZvW7xIwn13aqrzpOEG0Y8rCCGiyp5e19PPsXTu7
          8kr7wr+TGylzgglY1tKWm6WtKqv00mUkEC/A0SaevFhUoxS3CsFZxauIBu1bcazWCP1jjvW6IW
          Ex4X8mwNUXWiMLVr+1Af/ObvwZ5r8fH7UySbKX/dYFzbxCsxk/5g5EbO3Fe21c4+3ZZJ237liG
          MXY0nAHlcemfg/FDnrTa6+caBVzhmWfIFWXwIXCb1fkAVCCmZ4RUQ2zImUS6viz/y+TIfCRoTa
          rsIT+bovJZ0472ikq0s0IGcbNaiV5/DkVFYuXAOW1yNfuooXlzxrlKt59JK457DSRdYIC2JkOH
          apQe34nWRxDNSpio4zpQzDuTib9Zd7+YIa7F8S0SKJwbc1jO7zYMPGqUKkZcyozg5nmonILvSe
          FwglwbNN1JXdnz6cOTdmagruObtEoWs87I1jZ8vrFLff9bhbsvlMiRwIPo4xwj7n1QDSTPRJIH
          6HF2SazjQhDYwkWX1Y6nXnlUrVDcoNcoo8u9w4ZXRuwMetvzvvWVmy9A0I6yg1bY/CEoJJpsop
          yzBJuJoSOis3U3Aw1Nz/FsPHIAtYy+IG5+M/El7KGtQKlVljWDRpUVxRG2doZEf+8fIjuWNxcM
          JLvp2Ya/rl9AIjJxT8RqQGGePLxnaUWxIjIB3EMfToNoeooRJ0rXG6d+SCh1YZlZPqDoi7dpWl
          HUwRZtD3WLDmYbDCJZRozNNrQi0Wz7eNfYUDClhWMKRLkuq/zcERM117IBVyowiyZhGRGZ+yKq
          2/NI3qBpI0tbPliXEzxEdo0bsvV29WWKelT+QPPHBmrBYmwDwzhzohKOXbEVRKv+RPSeZCz/qv
          8IMzxwKDBYsMECj3jV2Lqf0ZnfImGQi7FyNLI23M/YUUekd1M/NazFcIVI8YqQcVgT80SXJFbu
          y+lD9YsQ6mRWFMP2S+5IM++zhbGMqMBMRyKPY8CLhz/YhOG2Aq6r95/jJF2KNqePLMVN6uYK/D
          A3yiyDHLR3MF8EnvGZrY9ge94LVu8KciShFEEera7TUN+eqGndUgQV8s1DeC6Tglkj/bNuea+f
          sz1ELwbz8dOCmzlPa4q7xpxMpzW9ANaFaLlhCsRTbuzxx3vcet4VLrG6N8FzxPGRRgqUk37g1B
          SSf5KOsWq1M1ngabuuR77E3FIL9iz2xN/uvGmySg+gcBXQja4pFoDfkJjt82ODFsf2elkbJjpX
          dP+06JFpI0f2uMA++OYgNZicdozVtYvYpiyHx2W6T654XRSFOJo2yBE0ItE8B+Gt62FbLGaILc
          A2HWEeXQ6vU8gqjZ+1/b2CxPOk2kXzdeGYKEKvkkTMtkwfLJjSQ6OxkKQ0ZK9EonY9baE=",
        "featureID": 1632444464204
    },
    "msg": "RequestId:5394f3a983c240d3bd90d69eef86edc4 Success",
    "status": 200
}

5、信息码

信息码 描述信息 描述 处理建议
100 nvalid appKey,secretkeyor servicekey Key 非法 控制台检查申请token时设定的key
101 Invalid Token 非法token 重新申请token,或确认token是否正确
102 Open api total request limit reached 访问超过限额 控制台确认购买的授权服务剩余次数
103 no permission to access data 未授权操作 控制台确认服务是否购买授权
104 Service Expiration token过期 重新申请token
105 Resource Unavailable 资源不可用 详细确认接口说明,确认action是否正确
106 Token Acquisition failed Token获取失败 检查设定的key,重新获取
107 Token Null Token为空 确认token是否添加
200 Success 成功  
201 Failed Operation 操作失败 确认请求参数或重新请求
300 param is null 必要参数未传入 检查必须的请求参数xx是否设定
301 param format error 参数格式错误 检查请求参数xx的数据格式,是否符合要求
-300 System busy 系统繁忙 稍后重新访问
501 Invalid face information 无人脸或非活体 确认提供的图片有人脸,并且为活体
502 Invalid image data 大小不可超过5M。图片格式:现支持PNG、JPG、JPEG、BMP,不支持GIF图片 大小不可超过5M。图片格式:现支持PNG、JPG、JPEG、BMP,不支持GIF图片
503 Invalid feature data 无效人脸库特征(特征有误) 提供的人脸List,特征需要完整,格式及字段名称需要准确;json格式为 “faceFeatureList”:[ { "faceFeature": 特征值,”featureID”:特征ID}]
509 Unknown face error 未知人脸异常 重新调用API