人脸比对
更新时间 2025-09-23 10:33:24
最近更新时间: 2025-09-23 10:33:24
接口描述
⽤于检测输⼊的两张图像中的⼈脸相似度，并返回相似度分数、两个⼈脸的坐标信息和两个⼈脸的五官关键点坐标信息，关键点包括眼睛2点、⿐⼦1点、嘴巴2点。
请求方法
POST
接口要求
- 图⽚⼤⼩限制：图⽚单张⼤⼩⼩于2MB。
- 图⽚格式限制：图⽚格式⽀持jpg/jpeg/png/bmp格式。
URI
/v1/aiop/api/2f7awxekgvls/face/compare/PERSON/person/compareFromBase64
请求参数
请求头header参数
| 参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
|---|---|---|---|---|---|
| Content-Type | 是 | String | json格式 | application/json | |
| appkey | 是 | String | 平台应用appkey | 562b89493b1a40e1b97ea05e50dd8170 | |
| ctyun-eop-request-id | 是 | String | 用户请求 id，由用户构造，用户可以通过 uuid 等方法自行生成唯一字符串，用于日志请求追踪。 详见文档：Python3调用示例 |
33dfa732-b27b-464f-b15a-21ed6845afd5 | |
| eop-date | 是 | String | 请求时间，由用户构造，形如 yyyymmddTHHMMSSZ。 详见文档：Python3调用示例 |
20211221T163014Z | |
| host | 是 | String | 终端节点域名，固定字段 | ai-global.ctapi.ctyun.cn | |
| version | 是 | String | 固定值v2 | v2 | |
| Eop-Authorization | 是 | String | 由天翼云官网 accessKey 和 securityKey 经签名后生成，参与签名生成的字段包括天翼云官网 accessKey 、securityKey、平台应用的appkey（非必须），用户请求id（非必须），请求时间，终端节点域名（非必须）以及请求体内容。 签名逻辑详见文档：认证鉴权和Python3调用示例 |
请求体body参数
| 参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
|---|---|---|---|---|---|
| img1Base64 | 是 | String | 人脸比对的第一张图片，图片使用常规的base64编码方式，编码后，不包含前缀，剔除前缀例如” data:image/jpeg;base64,” | - | |
| img2Base64 | 是 | String | 人脸比对的第二张图片，图片使用常规的base64编码方式，编码后，不包含前缀，剔除前缀例如” data:image/jpeg;base64,” | - |
请求代码示例
Curl -X POST "https://ai-global.ctapi.ctyun.cn/v1/aiop/api/2f7awxekgvls/fac
e/compare/PERSON/person/compareFromBase64"
-H "Content-Type: application/json"
-H "ctyun-eop-request-id:33dfa732-b27b-464f-b15a-21ed6845afd5"
-H "appkey:XXX"
-H "version:v2"
-H "Eop-Authorization:XXX"
-H "eop-date:20211109T104641Z"
-H "host:ai-global.ctapi.ctyun.cn"
--data '{"img1Base64":"AAAAAAAAA....","img2Base64":"BBBBBBBBBB...."}'
返回值说明
1.请求成功返回响应参数
| 参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
|---|---|---|---|---|---|
| statusCode | 是 | Int | 返回状态，返回 0 表示成功，返回错误代码参考下面的错误代码列表。 | 0 | |
| message | 是 | String | 如果 code 为 0，返回 success；如果 code 非 0，则返回对应的可读错误信息。 | success | |
| returnObj | 是 | Object | 返回的结果数据内容 | returnObj |
2.表returnObj
| 参数 | 参数类型 | 说明 | 示例 | 下级对象 |
|---|---|---|---|---|
| Score | Float | 两张图片中的中心人脸属于同一个人的置信度，取值范围[0, 1]。 | 0.8642 | |
| RectAList | Array | 图片1的人脸位置信息。 中心人脸的位置信息 box = [left, top, width, height]。 | [106,61,86,112] | |
| RectBList | Array | 图片2的人脸位置信息。 中心人脸的位置信息 box = [left, top, width, height]。 | [771, 118, 222, 303] | |
| LandmarkA | Array | 图片1的中心人脸5个人脸关键点位置信息。表示方式为[x1, y1, x2, y2, x3, y3, x4, y4, x5, y5]，数组的维度为 1 x 10。 | [106, 112, 146, 113, 130, 137, 106, 154, 143, 155] | |
| LandmarkB | Array | 图片2的中心人脸5个人脸关键点位置信息。表示方式为[x1, y1, x2, y2, x3, y3, x4, y4, x5, y5]，数组的维度为 1 x 10。 | [103, 108, 147, 116, 120, 142, 99, 147, 139, 155] |
3.请求失败返回响应参数
| 参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
|---|---|---|---|---|---|
| statusCode | 是 | Int | 错误码，放置API对应的错误码 | 500001 | |
| message | 是 | String | 返回对应的错误信息 | 请求内容错误 | |
| details | 是 | String | 返回对应的错误描述 | 传入内容为空，或者传入的参数名错误 | |
| error | 是 | String | 返回对应的错误码 | AI_OP_500001 |
返回值示例
1.请求成功返回值示例
{
"statusCode": 0,
"message": "success",
"returnObj": {
"LandmarkA": [104, 109, 146, 112, 122, 137, 102, 146, 145, 148],
"LandmarkB": [103, 108, 147, 116, 120, 142, 99, 147, 139, 155],
"RectAList": [80, 67, 94, 116],
"RectBList": [75, 62, 104, 118],
"Score": 0.6841
}
}
2.请求失败返回值示例
{
"code": 400005,
"message": "请求体类型错误",
"details": "请求体需为字典，不能为其他类型",
"statusCode": 400005,
"error": "AI_OP_400005"
}
状态码
| http状态码 | 描述 |
|---|---|
| 200 | 表示请求成功 |
错误码说明
v2版本错误码：6位错误码，4 开头为业务错误码，5开头为服务错误码。
| 错误码 | 错误信息 | 错误描述 |
|---|---|---|
| CTAPI_10000 | API Not Found | |
| CTAPI_0009 | 无效json的body参数 | |
| AI_OP_400005 | 请求体类型错误 | 请求体需为字典，不能为其他类型 |
| AI_OP_400006 | 必传的参数未传 | 必传的参数（img1Base64或img2Base64）未传 |
| AI_OP_400008 | 请求体的参数字段类型错误 | img1Base64、img2Base64字段应该是string类型 |
| AI_OP_400009 | 请求体的参数字段值为空 | img1Base64、img2Base64字段值为空字符 |
| AI_OP_400011 | base64数据处理异常 | img1Base64 或 img2Base64 字段的 base64 字符串转换字节码异常 |
| AI_OP_400012 | 文件格式不合法 | 仅支持 jpeg/png/jpg/bmp 格式 |
| AI_OP_400013 | 文件大小不符合要求 | 该文件大小不符合要求，图片一/图片二要求小于2M |
| AI_OP_410001 | 图片一/图片二解码错误 | 字节码解码为图片错误 |
| AI_OP_500001 | 服务接口异常，请联系管理员 | 需要联系管理员处理 |
| AI_OP_601002 | 图片一/图片二未检测到人脸 | 上传图片一/图片二不包含人脸 |
base64 编码规则：使用常规的 safe base64 编码方式
- python 中推荐使用 base64.urlsafe_b64encode() 函数进行编码。
- java 中推荐使用 BASE64.getUrlEncoder().encodeToString() 函数进行编码。
