创建应用

创建REST API人脸识别应用

1. 登录 习悦开发者平台,进入 控制台 页面,点击“创建应用”按钮,如图:

2. 填写应用相关信息,“应用服务”需要勾选人脸识别,以获得相关权限,否则在开发过程将提示缺少权限,勾选“REST API”应用平台,点击“提交应用”,如图:

3. 在我的应用模块可以查看已创建的应用及应用信息,如图:

REST API 开发

开发流程图


实体解释 userId:在习悦人脸识别服务中,userId可理解为应用中的用户,对应开发者的应用中账户体系,userId的唯一性由开发者进行维护;userId保证了用户(非开发者)数据的独立和安全。
FaceSet:人脸集合,是人脸样本管理单位,是人脸数据(Face)的集合,由开发者进行创建,在一个userId中FaceSet名称是不可重复的;人脸检索就是对FaceSet进行检索,检索集合里最相似的Face数据。
Face:人脸数据,是人脸识别服务中的最基本单位,基于人脸图片生成,服务将图片中的人脸进行识别,返回相应的Face数据作为人脸凭证,后续可添加到FaceSet,做人脸特征分析(年龄、性别),人脸对比和人脸检索。
集合样本:是FaceSet的基本单元,单位是Face,Face作为集合样本后,对集合进行检索时,将成为被检索的数据。

开始开发

1. 在我的应用模块,获取应用的API Key 与 API Secret;

2. 调用平台授权认证接口 /auth/token,分别填入apiKey和apiSecret,对应上图API Key 、API Secret,获取平台认证accessToken,用于其他请求的合法校验,否则平台将视为非法请求。

请求示例:

https://dev.zhthinkjoy.com/api/auth/token?apiKey=您的API Key&apiSecret=您的API Secret

响应示例:

{
  "resCode": "0",
  "resMsg": "SUCCESS",
  "resData": {
    "expireSecond": "1800",
    "accessToken": "7eb6cbc3bd6cd8707d4c98a7fc7bd42fce4ec461"
  }
}

注:accessToken具有时效,有效时间为expireSecond,单位:秒,开发者需要维护accessToken有效性,在失效时需要重新调用该接口获取有效的accessToken,以保证请求合法性。


3. 根据人脸识别接口进行对接,请求均为 POST 请求,参数放于 Body 中,采用 form-data 形式。

获取token

请求URL

https://dev.zhthinkjoy.com/api/auth/token

请求方式

POST

描述

accessToken是习悦开发者平台全局唯一接口调用凭据,开发者调用各接口时都需使用accessToken,开发者需要进行妥善保存;accessToken的有效时长根据返回值expireSecond设定,需定时刷新。

参数

参数名 参数类型 备注
必须 apiKey String 应用的API KEY
apiSecret String 应用的API SECRET

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
accessToken String 习悦开发者平台全局唯一接口调用凭据
expireSecond String accessToken的有效时长,单位:秒

示例

{
  "resCode": "0",
  "resMsg": "SUCCESS",
  "resData": {
    "expireSecond": "1800",
    "accessToken": "e36ae62735f2936ba6c95e272a3d03c93bcca751"
  }
}

错误码

错误码 说明 描述
1901 MISSING_ARGUMENTS 缺少参数,apiKey/apiSecret不能为空或者空字符串
1905 INVALID_ID 非法标识,应用不存在,apiKey/apiSecret错误

创建用户

请求URL

https://dev.zhthinkjoy.com/api/faceApp/userManger/createUser

请求方式

POST

描述

获取到accessToken后,首先需要创建一个userId,人脸识别服务都需要由userId进行操作,不同的userId的数据是独立的,不能被另外的userId进行操作和使用,以保障用户数据安全;一个应用可以多个userId,代表应用的用户; userId需要开发者自行进行存储和维护。

请求参数

参数名 参数类型 参数说明
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 开发者应用的用户ID(1-32位数字/字母)

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 请求消息唯一ID,用于向习悦开发者平台技术人员反馈和追查异常信息
userId String 添加成功的userId,原样返回

示例

{
  "resCode": "0",
  "resMsg": "SUCCESS",
  "resData": {
    "msgId": "cb8e7d65-d273-4733-b6e2-bce9df179046",
    "userId": "test"
  }
}

错误码

错误码 说明 描述
1101 DB_ADD_OP_ERROR userId添加错误,可能由服务异常导致
1901 MISSING_ARGUMENTS 缺少参数,userId不能为空或者空字符串
1902 INVALID_ARGUMENTS 非法参数,userId为1-32位数字/字母
1906 NAME_EXISTS 输入的userId在应用中已存在,不能重复创建
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效

人脸区域检测 (Image)

请求URL

https://dev.zhthinkjoy.com/api/faceApp/v2/detect

请求方式

POST

描述

检测图片中人脸的区域、人脸特征点、人脸年龄和人脸性别;检测出的faceId可用于后续操作,包括 添加到FaceSet作为集合样本,进行 Face人脸特征分析,进行 人脸相似度对比 等;如果对同一张图片进行多次人脸检测,同一个人脸得到的Face是不同的;区域检测产生的Face是无状态数据,如需要多次使用,开发者需要自行存储。

请求参数

参数名 参数类型 备注
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
file File 分辨率小于1920*1920带有人脸的JPG(JPEG)/PNG图片文件
选填 isAge Boolean true检测年龄特征, 默认是false
isGender Boolean true检测性别特征, 默认是false

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 请求消息唯一ID,用于向习悦开发者平台技术人员反馈和追查异常信息
faces List 图片中检测出的人脸数据数组,如果没有检测到人脸则无该字段
faceId String 人脸数据唯一标识,可用做 FaceSet样本特征分析人脸相似度对比 等操作。
注:faceId如果连续72小时没有存放在任意FaceSet中,则该faceId将会失效。
position List 人脸区域坐标数组
下标0:左上角纵坐标y1
下标1:左上角横坐标x1
下标2:右下角纵坐标y2
下标3:右下角横坐标x2
注:以上坐标有可能出现负值,请开发者注意处理。
landmark List 人脸关键点坐标数组
注:关键点坐标有可能出现负值,请开发者注意处理。
age Double 人脸年龄
gender List 人脸男女性别概率,下标0为女性概率,下标1为男性概率
imgId String 图片唯一标识

示例

{
	"resCode": "0",
	"resMsg": "SUCCESS",
	"resData": {
		"faces": [
			{
				"gender": [
					0.0024196989834308624,
					0.9975802898406982
				],
				"imgId": "84bc26716af14753b7116ba229347be6",
				"faceId": "6af78bd02dd0439fb611914fabc76cfa",
				"position": [
					44,
					42,
					210,
					159
				],
				"landmark": [
					{
						"x": 71,
						"y": 114
					},
					{
						"x": 126,
						"y": 111
					},
					{
						"x": 100,
						"y": 144
					},
					{
						"x": 80,
						"y": 175
					},
					{
						"x": 123,
						"y": 172
					}
				],
				"age": 22.36259651184082
			}
		],
		"msgId": "4495fcef-af79-47d9-b6fd-894d84610718"
	}
}

错误码

错误码 说明 描述
1901 MISSING_ARGUMENTS 缺少参数,accessToken/userId/file不能为空或者空字符串
1902 INVALID_ARGUMENTS 参数非法,userId/file格式不符合要求
1905 INVALID_ID 非法标识,userId未创建
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效

人脸区域检测 (Base64)

请求URL

https://dev.zhthinkjoy.com/api/faceApp/v2/detectBase64

请求方式

POST

描述

检测图片中人脸的区域、人脸特征点、人脸年龄和人脸性别;检测出的faceId可用于后续操作,包括 添加到FaceSet作为集合样本,进行 Face人脸特征分析,进行 人脸相似度对比 等;如果对同一张图片进行多次人脸检测,同一个人脸得到的Face是不同的;区域检测产生的Face是无状态数据,如果要多次使用,开发者需要自行存储。

请求参数

参数名 参数类型 备注
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
imageBase64 String 分辨率小于1920*1920带有人脸的JPG(JPEG)/PNG图片文件的Base64编码字符串
图片转Base64示例(仅供参考)>>
选填 isAge Boolean true检测年龄特征, 默认是false
isGender Boolean True检测性别特征, 默认是false

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 请求消息唯一ID,用于向习悦开发者平台技术人员反馈和追查异常信息
faces List 图片中检测出的人脸数据数组,如果没有检测到人脸则无该字段
faceId String 人脸数据唯一标识,可用做 FaceSet样本特征分析人脸相似度对比 等操作。
注:faceId如果连续72小时没有存放在任意FaceSet中,则该faceId将会失效。
position List 人脸区域坐标数组
下标0:左上角纵坐标y1
下标1:左上角横坐标x1
下标2:右下角纵坐标y2
下标3:右下角横坐标x2
注:以上坐标有可能出现负值,请开发者注意处理。
landmark List 人脸关键点坐标数组
注:关键点坐标有可能出现负值,请开发者注意处理。
age Double 人脸年龄
gender List 人脸男女性别概率,下标0为女性概率,下标1为男性概率
imgId String 图片唯一标识

示例

{
	"resCode": "0",
	"resMsg": "SUCCESS",
	"resData": {
		"faces": [
			{
				"gender": [
					0.0024196989834308624,
					0.9975802898406982
				],
				"imgId": "84bc26716af14753b7116ba229347be6",
				"faceId": "6af78bd02dd0439fb611914fabc76cfa",
				"position": [
					44,
					42,
					210,
					159
				],
				"landmark": [
					{
						"x": 71,
						"y": 114
					},
					{
						"x": 126,
						"y": 111
					},
					{
						"x": 100,
						"y": 144
					},
					{
						"x": 80,
						"y": 175
					},
					{
						"x": 123,
						"y": 172
					}
				],
				"age": 22.36259651184082
			}
		],
		"msgId": "4495fcef-af79-47d9-b6fd-894d84610718"
	}
}

错误码

错误码 说明 描述
1901 MISSING_ARGUMENTS 缺少参数,accessToken/userId/ imageBase64不能为空或者空字符串
1902 INVALID_ARGUMENTS 参数非法,userId/ imageBase64格式不符合要求
1905 INVALID_ID 非法标识,userId未创建
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效

人脸区域检测 (URL)

请求URL

https://dev.zhthinkjoy.com/api/faceApp/v2/detectURL

请求方式

POST

描述

检测图片中人脸的区域、人脸特征点、人脸年龄和人脸性别;检测出的faceId可用于后续操作,包括 添加到FaceSet作为集合样本,进行 Face人脸特征分析,进行 人脸相似度对比 等;如果对同一张图片进行多次人脸检测,同一个人脸得到的Face是不同的;区域检测产生的Face是无状态数据,如果要多次使用,开发者需要自行存储。

请求参数

参数名 参数类型 备注
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
imageURL String 分辨率小于1920*1920带有人脸的JPG(JPEG)/PNG图片文件的URL链接
选填 isAge Boolean true检测年龄特征, 默认是false
isGender Boolean True检测性别特征, 默认是false

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 请求消息唯一ID,用于向习悦开发者平台技术人员反馈和追查异常信息
faces List 图片中检测出的人脸数据数组,如果没有检测到人脸则无该字段
faceId String 人脸数据唯一标识,可用做 FaceSet样本特征分析人脸相似度对比 等操作。
注:faceId如果连续72小时没有存放在任意FaceSet中,则该faceId将会失效。
position List 人脸区域坐标数组
下标0:左上角纵坐标y1
下标1:左上角横坐标x1
下标2:右下角纵坐标y2
下标3:右下角横坐标x2
注:以上坐标有可能出现负值,请开发者注意处理。
landmark List 人脸关键点坐标数组
注:关键点坐标有可能出现负值,请开发者注意处理。
age Double 人脸年龄
gender List 人脸男女性别概率,下标0为女性概率,下标1为男性概率
imgId String 图片唯一标识

示例

{
	"resCode": "0",
	"resMsg": "SUCCESS",
	"resData": {
		"faces": [
			{
				"gender": [
					0.0024196989834308624,
					0.9975802898406982
				],
				"imgId": "84bc26716af14753b7116ba229347be6",
				"faceId": "6af78bd02dd0439fb611914fabc76cfa",
				"position": [
					44,
					42,
					210,
					159
				],
				"landmark": [
					{
						"x": 71,
						"y": 114
					},
					{
						"x": 126,
						"y": 111
					},
					{
						"x": 100,
						"y": 144
					},
					{
						"x": 80,
						"y": 175
					},
					{
						"x": 123,
						"y": 172
					}
				],
				"age": 22.36259651184082
			}
		],
		"msgId": "4495fcef-af79-47d9-b6fd-894d84610718"
	}
}

错误码

错误码 说明 描述
1901 MISSING_ARGUMENTS 缺少参数,accessToken/userId/imageURL不能为空或者空字符串
1902 INVALID_ARGUMENTS 参数非法,userId/imageURL格式不符合要求
1905 INVALID_ID 非法标识,userId未创建
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效
1956 GET_IMAGE_ERROR 获取图片异常,图片链接无效

创建人脸集合

请求URL

https://dev.zhthinkjoy.com/api/faceApp/faceSetManger/createFaceSet

请求方式

POST

描述

创建一个人脸集合FaceSet;同一userId下facesetName不能重复,且需满足参数说明中的对应格式,一个userId可以拥有多个FaceSet;同时FaceSet可以添加自定义标签(tag)进行分组,以便后续条件查询。

参数

参数名 参数类型 备注
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
facesetName String 人脸集合名称,一个userId下facesetName不能重复
选填 tag String 自定义标签,用来对FaceSet分组,可用于查询不同tag的FaceSet
userParam String 自定义用户信息

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 请求唯一标识,用于向习悦开发者平台技术人员反馈和追查异常信息
facesetId String 人脸集合唯一标识,后续用于FaceSet管理的操作参数
facesetName String 人脸集合名称,原样返回
tag String 自定义标签,原样返回
userparam String 自定义用户信息,原样返回

示例

{
	"resCode": "0",
	"resMsg": "SUCCESS",
	"resData": {
		"userparam": "userParam",
		"msgId": "4eaacf70-c4ac-49fd-a638-792717f96cde",
		"tag": "tag",
		"facesetId": "fb3f4c58d1234b8984c7922ac630c69f",
		"facesetName": "company"
  	}
}

错误码

错误码 说明 描述
1101 DB_ADD_OP_ERROR 人脸集合添加错误,可能由服务异常导致
1901 MISSING_ARGUMENTS 缺少必要参数
1902 INVALID_ARGUMENTS 参数非法,facesetName/userId格式非法
1905 INVALID_ID 非法标识,userId未创建
1906 NAME_EXISTS 输入的facesetName在userId中已存在,不能重复创建
1908 NO_FACE_DETECTED 图片中未检测到人脸
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效

条件查询集合

请求URL

https://dev.zhthinkjoy.com/api/faceApp/faceSetManger/getFaceSet

请求方式

POST

描述

根据faceSet的标签tag查询userId下的FaceSet;start参数控制从第几个开始返回。

请求参数

参数名 参数类型 参数说明
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
选填 tag String FaceSet的自定义标签
start Integer 从列表中第几个FaceSet开始返回,默认为0

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 请求唯一标识,用于向习悦开发者平台技术人员反馈和追查异常信息
facesets List 人脸集合数据数组
facesetId String 人脸集合唯一标识,后续用于FaceSet管理的操作参数
facesetName String 人脸集合名称
tag String 自定义标签信息
userparam String 自定义用户信息

示例

{
	"resCode": "0",
	"resMsg": "SUCCESS",
	"resData": {
		"msgId": "af8629da-36eb-4f09-b7d3-cca0faaf08ac",
		"facesets": [
      		{
				"userparam": "userparam",
				"tag": "createByJohn",
				"facesetId": "2eb42b93a9f740b08a161bdeaea40762",
				"facesetName": "thinkjoy"
      		},
      		{
				"userparam": "userParam",
				"tag": "tag",
				"facesetId": "fb3f4c58d1234b8984c7922ac630c69f",
				"facesetName": "company"
      		}
    	]
  	}
}

错误码

错误码 说明 描述
1104 DB_QUE_OP_ERROR 数据库查询异常,可能由服务异常导致
1901 MISSING_ARGUMENTS 缺少必要参数
1902 INVALID_ARGUMENTS 参数非法,tag/star/userId格式非法
1905 INVALID_ID 非法标识,userId未创建
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效

查询集合详情

请求URL

https://dev.zhthinkjoy.com/api/faceApp/faceSetManger/getDetail

请求方式

POST

描述

根据facesetId获取FaceSet详情;facesetId与userId存在对应关系,facesetId对应的FaceSet必须是由该userId生成,否则会报错。

参数

参数名 参数类型 参数说明
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
facesetId String 人脸集合唯一标识,由创建人脸集合(createFaceSet)接口返回的facesetId

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 请求唯一标识,用于向习悦开发者平台技术人员反馈和追查异常信息
facesetId String 人脸集合唯一标识,后续用于FaceSet管理的操作参数
facesetName String 人脸集合名称
tag String 自定义标签
userparam String 自定义用户信息
face_count Integer FaceSet存储的Face总数
faceId List FaceSet中存储的Face唯一标识

示例

{
	"resCode": "0",
	"resMsg": "SUCCESS",
	"resData": {
		"userparam": "userparam",
		"face_count": 3,
		"msgId": "db99659b-ab20-45a1-8013-c8aff453fbe5",
		"tag": "createByJohn",
		"faceId": [
			"a1c711af0e9b41359ecf8c1876064f98",
			"a856a6c773334edaa57b151cef096238",
			"b1c96fb17b8f4eefa4dd1d891a32267c"
    	],
		"facesetId": "2eb42b93a9f740b08a161bdeaea40762",
		"facesetName": "thinkjoy"
  	}
}

错误码

错误码 说明 描述
1104 DB_QUE_OP_ERROR 数据库查询异常,可能由服务异常导致
1901 MISSING_ARGUMENTS 缺少必要参数
1902 INVALID_ARGUMENTS 参数非法,userId/facesetId格式非法
1905 INVALID_ID 非法标识,userId/facesetId未创建
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效

修改人脸集合

请求URL

https://dev.zhthinkjoy.com/api/faceApp/faceSetManger/updateFaceSet

请求方式

POST

描述

根据facesetId对FaceSet中的自定义标签信息(tag)和自定义用户信息(userparam)进行修改;facesetId对应的FaceSet必须是由该userId创建,否则将会报错。

参数

参数名 参数类型 备注
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
facesetId String 人脸集合唯一标识,由创建人脸集合(createFaceSet)接口返回的facesetId
选填 tag String 自定义标签
userparam String 自定义用户信息B

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 请求唯一标识,用于向习悦开发者平台技术人员反馈和追查异常信息
facesetId String 人脸集合唯一标识,后续用于FaceSet管理的操作参数
facesetName String 人脸集合名称
tag String 自定义标签
userparam String 自定义用户信息

示例

{
	"resCode": "0",
	"resMsg": "SUCCESS",
	"resData": {
		"userparam": "userparam",
		"msgId": "02cf6724-babc-4308-a382-a50d960b10e0",
		"tag": "createByJohn",
		"facesetId": "2eb42b93a9f740b08a161bdeaea40762",
		"facesetName": "thinkjoy"
  	}
}

错误码

错误码 说明 描述
1102 DB_UP_OP_ERROR 修改人脸集合错误,可能由服务异常导致
1901 MISSING_ARGUMENTS 缺少参数,userId/facesetId不能为空或者空字符串
1902 INVALID_ARGUMENTS 参数非法,userId/facesetId/tag/userparam格式非法
1905 INVALID_ID 非法标识,userId /facesetId未创建
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效

添加样本 (Image)

请求URL

https://dev.zhthinkjoy.com/api/faceApp/faceSetManger/addFaceByImage

请求方式

POST

描述

根据facesetId对FaceSet进行添加人脸样本,图片参数类型为File。

注意:调用该接口后,需要调用 刷新集合信息 接口,在集合检索中才能生效。
建议:批量操作后调用一次刷新集合数据接口即可。

请求参数

参数名 参数类型 备注
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
facesetId String 人脸集合唯一标识,由创建人脸集合(createFaceSet)接口返回的facesetId
file File 分辨率小于1920*1920带有人脸的JPG(JPEG)/PNG图片文件
选填 personId String 人员标签,可以理解为样本人员的名字,可重复,由开发者自定义

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 请求唯一标识,用于向习悦开发者平台技术人员反馈和追查异常信息
face_added Integer 成功添加Face数量
face_count Integer FaceSet中包含的Face数量
facesetId String 人脸集合唯一标识,后续用于FaceSet管理的操作参数
facesetName String 人脸集合名名称
personInfo List 图片中的人脸数据数组
imgId String 图片唯一标识
faceId String 人脸数据唯一标识,可用做 FaceSet样本特征分析人脸相似度对比 等操作
position List 人脸区域坐标数组
下标0:左上角纵坐标y1
下标1:左上角横坐标x1
下标2:右下角纵坐标y2
下标3:右下角横坐标x2
注:以上坐标有可能出现负值,请开发者注意处理。
landmark List 人脸特征点坐标
注:特征点坐标有可能出现负值,请开发者注意处理。

示例

{
  	"resCode": "0",
  	"resMsg": "SUCCESS",
  	"resData": {
    	"face_added": 1,
    	"face_count": 16,
    	"msgId": "dee16ca0-6fab-4bed-8c3d-29bc730da3a8",
    	"facesetId": "4fd7b943a74d42458066de8d899602b2",
    	"personInfo": [
      		{
        		"imgId": "9ffd75c5f48d4a60a2632bb5d74bf7e9",
        		"faceId": "a54b3748095e43b4814eae15f984c967",
        		"position": [
          			45,
          			137,
          			375,
          			370
        		],
        		"landmark": [
          			{
            			"x": 193,
            			"y": 172
          			},
          			{
            			"x": 304,
            			"y": 185
          			},
          			{
            			"x": 231,
            			"y": 257
          			},
          			{
            			"x": 194,
            			"y": 295
          			},
          			{
            			"x": 279,
            			"y": 306
          			}
        		]
      		}
    	],
    	"facesetName": "测试"
  	}
}

错误码

错误码 说明 描述
1101 DB_UP_OP_ERROR 添加人脸样本错误,可能由服务异常导致
1901 MISSING_ARGUMENTS 缺少参数,userId/facesetId/file不能为空或者空字符串
1902 INVALID_ARGUMENTS 参数非法,userId /facesetId/file格式非法
1905 INVALID_ID 非法标识,userId /facesetId未创建
1908 NO_FACE_DETECTED 图片中检测不到人脸
1909 TOO_MANY_FACES_IN_PIC 图片中检测到多个人脸
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效

添加样本 (Base64)

请求URL

https://dev.zhthinkjoy.com/api/faceApp/faceSetManger/addFaceByBase64

请求方式

POST

描述

根据facesetId对FaceSet进行添加人脸样本,图片参数类型为Base64编码字符串。

注意:调用该接口后,需要调用 刷新集合信息 接口,在集合检索中才能生效。
建议:批量操作后调用一次刷新集合数据接口即可。

请求参数

参数名 参数类型 备注
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
facesetId String 人脸集合唯一标识,由创建人脸集合(createFaceSet)接口返回的facesetId
imageBase64 String 分辨率小于1920*1920带有人脸的JPG(JPEG)/PNG图片文件的Base64编码字符串
图片转Base64示例(仅供参考)>>
选填 personId String 人员标签,可以理解为样本人员的名字,可重复,由开发者自定义

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 请求唯一标识,用于向习悦开发者平台技术人员反馈和追查异常信息
face_added Integer 成功添加Face的数量
face_count Integer FaceSet中包含Face的数量
facesetId String 人脸集合唯一标识,后续用于FaceSet管理的操作参数
facesetName String 人脸集合名名称
personInfo List 图片中的人脸数据数组
imgId String 图片的唯一标识
faceId String 人脸数据唯一标识,可用做 FaceSet样本特征分析人脸相似度对比 等操作
position List 人脸区域坐标数组
下标0:左上角纵坐标y1
下标1:左上角横坐标x1
下标2:右下角纵坐标y2
下标3:右下角横坐标x2
注:以上坐标有可能出现负值,请开发者注意处理。
landmark List 人脸特征点坐标
注:特征点坐标有可能出现负值,请开发者注意处理。

示例

{
  	"resCode": "0",
  	"resMsg": "SUCCESS",
  	"resData": {
    	"face_added": 1,
    	"face_count": 16,
    	"msgId": "dee16ca0-6fab-4bed-8c3d-29bc730da3a8",
    	"facesetId": "4fd7b943a74d42458066de8d899602b2",
    	"personInfo": [
      		{
        		"imgId": "9ffd75c5f48d4a60a2632bb5d74bf7e9",
        		"faceId": "a54b3748095e43b4814eae15f984c967",
        		"position": [
          			45,
          			137,
          			375,
          			370
        		],
        		"landmark": [
          			{
            			"x": 193,
            			"y": 172
          			},
          			{
            			"x": 304,
            			"y": 185
          			},
          			{
            			"x": 231,
            			"y": 257
          			},
          			{
            			"x": 194,
            			"y": 295
          			},
          			{
            			"x": 279,
            			"y": 306
          			}
        		]
      		}
    	],
    	"facesetName": "测试"
  	}
}

错误码

错误码 说明 描述
1101 DB_ADD_OP_ERROR 添加人脸样本错误,可能由服务异常导致
1901 MISSING_ARGUMENTS 缺少参数,userId/facesetId/imageBase64不能为空或者空字符串
1902 INVALID_ARGUMENTS 参数非法,userId /facesetId/imageBase64格式非法
1905 INVALID_ID 非法标识,userId /facesetId未创建
1908 NO_FACE_DETECTED 图片中检测不到人脸
1909 TOO_MANY_FACES_IN_PIC 图片中检测到多个人脸
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效

添加样本 (URL)

请求URL

https://dev.zhthinkjoy.com/api/faceApp/faceSetManger/addFaceByURL

请求方式

POST

描述

根据facesetId对FaceSet进行添加人脸样本。

注意:调用该接口后,需要调用 刷新集合信息 接口,在集合检索中才能生效。
建议:批量操作后调用一次刷新集合数据接口即可。

请求参数

参数名 参数类型 备注
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
facesetId String 人脸集合唯一标识,由创建人脸集合(createFaceSet)接口返回的facesetId
imageURL String 分辨率小于1920*1920带有人脸的JPG(JPEG)/PNG图片文件的URL链接
选填 personId String 人员标签,可以理解为样本人员的名字,可重复,由开发者自定义

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 请求唯一标识,用于向习悦开发者平台技术人员反馈和追查异常信息
face_added Integer 成功添加Face的数量
face_count Integer FaceSet中包含Face的数量
facesetId String 人脸集合唯一标识,后续用于FaceSet管理的操作参数
facesetName String 人脸集合名名称
personInfo List 图片中的人脸数据数组
imgId String 图片的唯一标识
faceId String 人脸数据唯一标识,可用做 FaceSet样本特征分析人脸相似度对比 等操作
position List 人脸区域坐标数组
下标0:左上角纵坐标y1
下标1:左上角横坐标x1
下标2:右下角纵坐标y2
下标3:右下角横坐标x2
注:以上坐标有可能出现负值,请开发者注意处理。
landmark List 人脸特征点坐标
注:特征点坐标有可能出现负值,请开发者注意处理。

示例

{
  	"resCode": "0",
  	"resMsg": "SUCCESS",
  	"resData": {
    	"face_added": 1,
    	"face_count": 16,
    	"msgId": "dee16ca0-6fab-4bed-8c3d-29bc730da3a8",
    	"facesetId": "4fd7b943a74d42458066de8d899602b2",
    	"personInfo": [
      		{
        		"imgId": "9ffd75c5f48d4a60a2632bb5d74bf7e9",
        		"faceId": "a54b3748095e43b4814eae15f984c967",
        		"position": [
          			45,
          			137,
          			375,
          			370
        		],
        		"landmark": [
          			{
            			"x": 193,
            			"y": 172
          			},
          			{
            			"x": 304,
            			"y": 185
          			},
          			{
            			"x": 231,
            			"y": 257
          			},
          			{
            			"x": 194,
            			"y": 295
          			},
          			{
            			"x": 279,
            			"y": 306
          			}
        		]
      		}
    	],
    	"facesetName": "测试"
  	}
}

错误码

错误码 说明 描述
1101 DB_ADD_OP_ERROR 添加人脸样本错误,可能由服务异常导致
1901 MISSING_ARGUMENTS 缺少参数,userId/facesetId/imageURL不能为空或者空字符串
1902 INVALID_ARGUMENTS 参数非法,userId /facesetId/imageURL格式非法
1905 INVALID_ID 非法标识,userId /facesetId未创建
1908 NO_FACE_DETECTED 图片中检测不到人脸
1909 TOO_MANY_FACES_IN_PIC 图片中检测到多个人脸
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效
1956 GET_IMAGE_ERROR 获取图片异常,图片链接无效

添加样本 (FaceId)

请求URL

https://dev.zhthinkjoy.com/api/faceApp/faceSetManger/addFaceByFaceId

请求方式

POST

描述

根据facesetId和faceId对FaceSet进行添加人脸样本;faceId通过 人脸区域检测人脸对比 获得,同一个faceId可以添加给多个FaceSet;facesetId和faceId必须都由userId所生成。

注意:调用该接口后,需要调用 刷新集合信息 接口,在集合检索中才能生效。
建议:批量操作后调用一次刷新集合数据接口即可。

请求参数

参数名 参数类型 备注
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
facesetId String 人脸集合唯一标识,由创建人脸集合(createFaceSet)接口返回的facesetId
faceIds String 人脸数据(Face)唯一标识,多个时使用英文逗号(,)分隔

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 请求唯一标识,用于向习悦开发者平台技术人员反馈和追查异常信息
face_added Integer 成功添加Face数量
face_count Integer FaceSet中包含的Face数量
facesetId String 人脸集合唯一标识,后续用于FaceSet管理的操作参数
facesetName String 人脸集合名名称

示例

{
  	"resCode": "0",
  	"resMsg": "SUCCESS",
  	"resData": {
    	"face_added": 1,
    	"face_count": 16,
    	"msgId": "dee16ca0-6fab-4bed-8c3d-29bc730da3a8",
    	"facesetId": "4fd7b943a74d42458066de8d899602b2",
    	"facesetName": "测试"
  	}
}

错误码

错误码 说明 描述
1101 DB_ADD_OP_ERROR 添加人脸样本错误,可能由服务异常导致
1901 MISSING_ARGUMENTS 缺少参数,userId/facesetId/faceIds不能为空或者空字符串
1902 INVALID_ARGUMENTS 参数非法,userId /facesetId/faceIds格式非法
1905 INVALID_ID 非法标识,userId /facesetId/faceIds未创建
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效

条件查询样本

请求URL

https://dev.zhthinkjoy.com/api/faceApp/faceSetManger/getFaceIdByPersonId

请求方式

POST

描述

根据facesetId和人脸标签personId为条件查询人脸列表;facesetId对应的FaceSet必须是由该userId创建,否则会报错。

请求参数

参数名 参数类型 备注
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
facesetId String 由创建人脸集合(createFaceSet)接口返回的faceSetId
选填 personId String 人员标签,personId为空,则返回该FaceSet中所有Face

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 请求唯一标识,用于向习悦开发者平台技术人员反馈和追查异常信息
faceIds List FaceSet中的Face数组

示例

{
	"resCode": "0",
	"resMsg": "SUCCESS",
	"resData": {
		"msgId": "975e068b-10b2-4e01-8281-bf435cf8d051",
		"faceIds": [
			"b1c96fb17b8f4eefa4dd1d891a32267c",
			"0b5815e7028546c6889f68987b14d348"
    	]
  	}
}

错误码

错误码 说明 描述
1104 DB_QUE_OP_ERROR 数据库查询异常,可能由服务异常导致
1901 MISSING_ARGUMENTS 缺少必要参数
1902 INVALID_ARGUMENTS 参数非法,userId/facesetId /personId格式非法
1905 INVALID_ID 非法标识,userId/facesetId未创建
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效

删除样本

请求URL

https://dev.zhthinkjoy.com/api/faceApp/faceSetManger/removeFace

请求方式

POST

描述

根据facesetId和faceId将Face从FaceSet中删除,该Face需要属于该FaceSet,并且FaceSet要属于该userId;该操作不会将Face从系统中删除,该Face依旧可用于其他操作。

参数

参数名 参数类型 备注
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
facesetId String 人脸集合唯一标识,由创建人脸集合(createFaceSet)接口返回的facesetId
faceId String 人脸标识faceId组成的字符串,可以是一个或者多个,用逗号分隔。

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 请求唯一标识,用于向习悦开发者平台技术人员反馈和追查异常信息
face_removed Integer 成功删除的faceId数量
face_count Integer FaceSet中剩余faceId的数量
facesetId String 人脸集合唯一标识,后续用于FaceSet管理的操作参数
facesetName String 人脸集合名称

示例

{
	"resCode": "0",
	"resMsg": "SUCCESS",
	"resData": {
		"msgId": "3e6e005b-e77e-483a-bee0-bc6a7adeca1d",
		"face_count": 3,
		"facesetId": "2eb42b93a9f740b08a161bdeaea40762",
		"facesetName": "thinkjoy",
		"face_removed": 1
  	}
}

错误码

错误码 说明 描述
1901 MISSING_ARGUMENTS 缺少参数,userId/facesetId/faceId不能为空或者空字符串
1902 INVALID_ARGUMENTS 参数非法,userId/facesetId/faceId格式非法
1905 INVALID_ID 非法ID,userId/facesetId/faceId未创建
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效

刷新集合信息

请求URL

https://dev.zhthinkjoy.com/api/faceApp/faceSetManger/refreshFaceSet

请求方式

POST

描述

根据facesetId对FaceSet中的人脸数据进行刷新,将修改人脸数据加入到检索缓存中,提高检索速度和准确度。

注:只对FaceSet进行增加Face或删除Face操作后,需要调用该接口进行数据刷新,其他操作不需要进行刷新;
此接口非必要操作,系统每隔10分钟会自动刷新缓存。

请求参数

参数名 参数类型 参数说明
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
facesetId String 人脸集合唯一标识,由创建人脸集合(createFaceSet)接口返回的facesetId

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 请求唯一标识,用于向习悦开发者平台技术人员反馈和追查异常信息
SUCCESS Boolean true表示刷新成功,false表示刷新失败

示例

{
"resCode": "0",
"resMsg": "SUCCESS",
"resData": {
    "msgId": "3fe83892-60fb-42cf-9c79-a38363f4462e",
    "SUCCESS": true
}
}

错误码

错误码 说明 描述
1901 MISSING_ARGUMENTS 缺少参数,userId/facesetId不能为空或者空字符串
1902 INVALID_ARGUMENTS 参数非法,userId /facesetId格式非法
1905 INVALID_ID 非法标识,userId /facesetId未创建
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效

删除人脸集合

请求URL

https://dev.zhthinkjoy.com/api/faceApp/faceSetManger/deleteFaceSet

请求方式

POST

描述

根据facesetId删除FaceSet,删除前可以检测该FaceSet下是否存在Face,如选择检测且该FaceSet下存在Face,则不删除该FaceSet;不检测就会直接删除该FaceSet;facesetId对应的FaceSet必须是由该userId创建,否则会报错。

请求参数

参数名 参数类型 备注
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
facesetId String 人脸集合唯一标识,由创建人脸集合(createFaceSet)接口返回的facesetId
选填 checkEmpty Boolean true:删除前检测FaceSet是否包含face,检测到存在face不删除;
false:删除前不检测,直接删除;
默认为false;

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 请求唯一标识,用于向习悦开发者平台技术人员反馈和追查异常信息
facesetId String 人脸集合唯一标识
facesetName String 人脸集合名称
tag String 自定义标签
userparam String 自定义用户信息

示例

{
	"resCode": "0",
	"resMsg": "SUCCESS",
	"resData": {
		"facesetId": "5548c7fecabe4dbab26dc23942d2c3d8",
		"msgId": "582aaebb-1437-49de-a020-a0565e2df503",
		"facesetName": "dev_api"
  	}
}

错误码

错误码 说明 描述
1103 DB_DEL_OP_ERROR 删除人脸集合错误,可能由服务异常导致
1901 MISSING_ARGUMENTS 缺少参数,userId/facesetId不能为空或者空字符串
1902 INVALID_ARGUMENTS 参数非法,userId /facesetId/checkEmpty格式非法
1905 INVALID_ID 非法标识,userId /facesetId未创建
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效

查询人脸详情

请求URL

https://dev.zhthinkjoy.com/api/faceApp/faceManger/getDetail

请求方式

POST

描述

根据faceId获取人脸数据的详细信息,包括源图片ID、人脸图片URL、归属FaceSet、人脸特征等信息;faceId对应的Face必须是由该userId人脸检测所产生,否则会报错。

参数

参数名 参数类型 参数说明
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
faceId String 人脸数据唯一标识,由 人脸区域检测人脸对比 接口所返回
选填 isGetUrl Boolean 是否返回人脸图片链接,
true返回链接;
false不返回链接;
默认为false

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 请求唯一标识,用于向习悦开发者平台技术人员反馈和追查异常信息
faces Object 人脸数据体
faceId String 人脸数据唯一标识,可用做 FaceSet样本特征分析人脸相似度对比 等操作
personId String 人员标签
facesets List Face被添加到的FaceSet数组
position List 人脸区域坐标数组
下标0:左上角纵坐标y1
下标1:左上角横坐标x1
下标2:右下角纵坐标y2
下标3:右下角横坐标x2
注:以上坐标有可能出现负值,请开发者注意处理。
tag String 人脸自定义标签
age Double 人脸年龄
注:已做年龄分析(区域检测特征分析)则返回,反之则无。
gender List 人脸男女性别概率,下标0为女性概率,下标1为男性概率
注:已做性别分析(区域检测特征分析)则返回,反之则无。
imgId String 图片唯一标识
url String 人脸的图片URL
注:有效时间为60秒

示例

{
	"resCode": "0",
	"resMsg": "SUCCESS",
	"resData": {
		"faces": [
      		{
				"facesets": [
					"2eb42b93a9f740b08a161bdeaea40762"
        		],
				"personId": "",
				"faceId": "a856a6c773334edaa57b151cef096238",
				"position": [
          			44,
          			40,
          			212,
          			159
        		],
			"imgId": "7b6816eb759846309d115100f71f9fc7",
				"tag": "",
				"url": "http://125.89.66.90:8088/group1/M00/05/EB/wKhk0lilWZGATNmzAAAb9bPWmZA038.jpg?
                                 un=a0f2ea466a3ed82561c2f851b3a6d9fd&t=MTQ4NzI5OTkxNjA2OQ==&
                                 nun=b190e5ae3ef4d8f88dd7b1126ad5ce87"
      		}
    	],
		"msgId": "d97f2844-c1cd-49f7-91e2-927fa6413c32"
  	}
}

错误码

错误码 说明 描述
1104 MISSING_ARGUMENTS 数据库查询异常,可能由服务异常导致
1901 MISSING_ARGUMENTS 缺少必要参数
1902 INVALID_ARGUMENTS 参数非法,userId/ faceId/ isGetUrl格式非法
1905 INVALID_ID 非法标识,userId/ faceId未创建
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效

修改人脸信息

请求URL

https://dev.zhthinkjoy.com/api/faceApp/faceManger/updateFaceInfo

请求方式

POST

描述

通过faceId修改人员标识和人脸自定义标签;faceId对应的Face必须是由该userId人脸检测所产生,否则会报错。

参数

参数名 参数类型 参数说明
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
faceId String 人脸数据唯一标识,由 人脸区域检测人脸对比 所返回
选填 personId String 人员标签
tag String 人脸自定义标签

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 请求唯一标识,用于向习悦开发者平台技术人员反馈和追查异常信息
faceId String 人脸数据唯一标识,可用做 FaceSet样本特征分析人脸相似度对比 等操作
personId String 人员标签
tag String 人脸自定义标签

示例

{
	"resCode": "0",
	"resMsg": "SUCCESS",
	"resData": {
		"msgId": "f53fa0b2-7e51-4754-bd63-148fbdd141a5",
		"personId": "John",
		"faceId": "a1c711af0e9b41359ecf8c1876064f98",
		"tag": "tag"
  	}
}

错误码

错误码 说明 描述
1102 DB_UP_OP_ERROR 数据库修改异常,可能由服务异常导致
1901 MISSING_ARGUMENTS 缺少必要参数
1902 INVALID_ARGUMENTS 参数非法,userId/faceId/personId/tag格式非法
1905 INVALID_ID 非法标识,userId/faceId未创建
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效

人脸特征分析

请求URL

https://dev.zhthinkjoy.com/api/faceApp/faceManger/analyze

请求方式

POST

描述

对已有的faceId进行年龄和性别特征分析,faceId由 人脸区域检测人脸对比 接口获得,且faceId对应的Face必须是由该userId人脸检测所产生,否则会报错;分析完的年龄和性别特征会保存到人脸详情中。

请求参数

参数名 参数类型 参数说明
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
faceId String 人脸数据唯一标识,由 人脸区域检测人脸对比 接口获得

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 习悦开发者平台全局唯一接口调用凭据
faces List 人脸数据体数组
faceId String 人脸数据唯一标识,可用做 FaceSet样本特征分析人脸相似度对比 等操作
age Integer 人脸年龄
gender List 人脸男女性别概率,下标0为女性概率,下标1为男性概率

示例

{
  "resCode": "0",
  "resMsg": "SUCCESS",
  "resData": {
    	"faces": [
      		{
        		"gender": [
          			0.9893562197685242,
          			0.01064376439899206
        		],
        	"faceId": "6a78e405ebaa40319d05f5ee455ec333",
        	"age": 20.29852676391602
      	}
    ],
    "msgId": "67b424fa-05a8-472d-9663-b2499fa2982e"
  	}
}

错误码

错误码 说明 描述
1901 MISSING_ARGUMENTS 缺少必要参数
1902 INVALID_ARGUMENTS 非法参数,userId/faceId格式非法
1905 INVALID_ID 非法标识,userId/faceId无效
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效

人脸检索 (Image)

请求URL

https://dev.zhthinkjoy.com/api/faceApp/v2/searchByImage

请求方式

POST

描述

使用图片从FaceSet中检索出最相似的Face数据;当图片上存在多张人脸时,只取识别度最高的人脸进行对比;facesetId对应的FaceSet必须是由该userId产生,否则会报错。

请求参数

参数名 参数类型 备注
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
facesetId String 人脸集合唯一标识,由创建人脸集合(createFaceSet)接口返回的faceSetId
file File 分辨率小于1920*1920带有人脸的JPG(JPEG)/PNG图片文件

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 请求唯一标识,用于向习悦开发者平台技术人员反馈和追查异常信息
searchFace List 检索结果对象数组
注:如果传入图片但图片中未检测到人脸,则无法进行人脸搜索,本字段不返回。
faceId String 人脸数据唯一标识,可用做 FaceSet样本特征分析人脸相似度对比 等操作
confidence Double 两张人脸的相似度
personId String 人员标签
top_num Integer 实际检测结果数量
faces List 从图片中检测出的人脸数组,人脸检测数据。
注:如果没有检测出人脸则不返回该字段
faceId String 人脸数据唯一标识,可用做 FaceSet样本特征分析人脸相似度对比 等操作
position List 人脸区域坐标数组
下标0:左上角纵坐标y1
下标1:左上角横坐标x1
下标2:右下角纵坐标y2
下标3:右下角横坐标x2
注:以上坐标有可能出现负值,请开发者注意处理。

示例

{
	"resCode": "0",
	"resMsg": "SUCCESS",
	"resData": {
		"msgId": "a3f45bb1-1333-4319-8705-898b3bbd48ec",
		"imgId": "18a27221dedc460b9bdc0a2d21352299",
		"faces": [
      		{
				"faceId": "9ff402f862d34e71913987a38db2320a",
				"position": [
          			44,
         	 		40,
          			212,
          			159
        		]
      		}
    	],
		"searchFace": [
      		{
				"confidence": 1,
				"personId": "",
				"faceId": "a856a6c773334edaa57b151cef096238"
      		}
    	],
		"top_num": 1
  	}
}

错误码

错误码 说明 描述
1901 MISSING_ARGUMENTS 缺少参数,userId/facesetId/file不能为空或者空字符串
1902 INVALID_ARGUMENTS 参数非法,userId/facesetId/file格式非法
1905 INVALID_ID 非法标识,userId/facesetId未创建
1908 NO_FACE_DETECTED 图片中未检测到人脸
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效

人脸检索 (Base64)

请求URL

https://dev.zhthinkjoy.com/api/faceApp/v2/searchByBase64

请求方式

POST

描述

使用图片从FaceSet中检索出最相似的Face数据;当图片上存在多张人脸时,只取识别度最高的人脸进行对比;facesetId对应的FaceSet必须是由该userId产生,否则会报错。

请求参数

参数名 参数类型 备注
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
facesetId String 人脸集合唯一标识,由创建人脸集合(createFaceSet)接口返回的faceSetId
imageBase64 String 分辨率小于1920*1920带有人脸的JPG(JPEG)/PNG图片文件的base64编码字符串
图片转Base64示例(仅供参考)>>

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 习悦开发者平台全局唯一接口调用凭据
searchFace List 检索结果对象数组
注:如果传入图片但图片中未检测到人脸,则无法进行人脸搜索,本字段不返回。
faceId String 人脸数据唯一标识,可用做 FaceSet样本特征分析人脸相似度对比 等操作
confidence Double 两张人脸的相似度
personId String 人员标签
top_num Integer 实际检测结果数量
faces List 从图片中检测出的人脸数组,人脸检测数据。
注:如果没有检测出人脸则不返回该字段
faceId String 人脸数据唯一标识,可用做 FaceSet样本特征分析人脸相似度对比 等操作
position List 人脸区域坐标数组
下标0:左上角纵坐标y1
下标1:左上角横坐标x1
下标2:右下角纵坐标y2
下标3:右下角横坐标x2
注:以上坐标有可能出现负值,请开发者注意处理。

示例

{
	"resCode": "0",
	"resMsg": "SUCCESS",
	"resData": {
		"msgId": "a3f45bb1-1333-4319-8705-898b3bbd48ec",
		"imgId": "18a27221dedc460b9bdc0a2d21352299",
		"faces": [
      		{
				"faceId": "9ff402f862d34e71913987a38db2320a",
				"position": [
          			44,
         	 		40,
          			212,
          			159
        		]
      		}
    	],
		"searchFace": [
      		{
				"confidence": 1,
				"personId": "",
				"faceId": "a856a6c773334edaa57b151cef096238"
      		}
    	],
		"top_num": 1
  	}
}

错误码

错误码 说明 描述
1901 MISSING_ARGUMENTS 缺少参数,userId/facesetId/imageBase64不能为空或者空字符串
1902 INVALID_ARGUMENTS 参数非法,userId/facesetId/imageBase64格式非法
1905 INVALID_ID 非法标识,userId/facesetId未创建
1908 NO_FACE_DETECTED 图片中未检测到人脸
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效

人脸检索 (URL)

请求URL

https://dev.zhthinkjoy.com/api/faceApp/v2/searchByURL

请求方式

POST

描述

使用图片从FaceSet中检索出最相似的Face数据;当图片上存在多张人脸时,只取识别度最高的人脸进行对比;facesetId对应的FaceSet必须是由该userId产生,否则会报错。

请求参数

参数名 参数类型 备注
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
facesetId String 人脸集合唯一标识,由创建人脸集合(createFaceSet)接口返回的faceSetId
imageURL String 分辨率小于1920*1920带有人脸的JPG(JPEG)/PNG图片文件的URL链接

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 习悦开发者平台全局唯一接口调用凭据
searchFace List 检索结果对象数组
注:如果传入图片但图片中未检测到人脸,则无法进行人脸搜索,本字段不返回。
faceId String 人脸数据唯一标识,可用做 FaceSet样本特征分析人脸相似度对比 等操作
confidence Double 两张人脸的相似度
personId String 人员标签
top_num Integer 实际检测结果数量
faces List 从图片中检测出的人脸数组,人脸检测数据。
注:如果没有检测出人脸则不返回该字段
faceId String 人脸数据唯一标识,可用做 FaceSet样本特征分析人脸相似度对比 等操作
position List 人脸区域坐标数组
下标0:左上角纵坐标y1
下标1:左上角横坐标x1
下标2:右下角纵坐标y2
下标3:右下角横坐标x2
注:以上坐标有可能出现负值,请开发者注意处理。

示例

{
	"resCode": "0",
	"resMsg": "SUCCESS",
	"resData": {
		"msgId": "a3f45bb1-1333-4319-8705-898b3bbd48ec",
		"imgId": "18a27221dedc460b9bdc0a2d21352299",
		"faces": [
      		{
				"faceId": "9ff402f862d34e71913987a38db2320a",
				"position": [
          			44,
         	 		40,
          			212,
          			159
        		]
      		}
    	],
		"searchFace": [
      		{
				"confidence": 1,
				"personId": "",
				"faceId": "a856a6c773334edaa57b151cef096238"
      		}
    	],
		"top_num": 1
  	}
}

错误码

错误码 说明 描述
1901 MISSING_ARGUMENTS 缺少参数,userId/facesetId/imageURL不能为空或者空字符串
1902 INVALID_ARGUMENTS 参数非法,userId/facesetId/imageURL格式非法
1905 INVALID_ID 非法标识,userId/facesetId未创建
1908 NO_FACE_DETECTED 图片中未检测到人脸
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效
1956 GET_IMAGE_ERROR 获取图片异常,图片链接无效

人脸检索 (FaceId)

请求URL

https://dev.zhthinkjoy.com/api/faceApp/v2/searchByFaceId

请求方式

POST

描述

使用有效的faceId从FaceSet中检索出最相似的Face数据;faceId可以通过 人脸区域检测人脸对比 获得;facesetId和faceId必须是由该userId生成,否则将会报错。

参数

参数名 参数类型 备注
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
facesetId String 人脸集合唯一标识,由创建人脸集合(createFaceSet)接口返回的faceSetId
faceId String 人脸数据唯一标识,通过 人脸区域检测人脸对比 获得

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 习悦开发者平台全局唯一接口调用凭据
searchFace List 检索结果对象数组
注:如果传入图片但图片中未检测到人脸,则无法进行人脸搜索,本字段不返回。
faceId String 人脸数据唯一标识,可用做 FaceSet样本特征分析人脸相似度对比 等操作
confidence Double 两张人脸的相似度
personId String 人员标签
top_num Integer 实际检测结果数量

示例

{
	"resCode": "0",
	"resMsg": "SUCCESS",
	"resData": {
		"msgId": "a3f45bb1-1333-4319-8705-898b3bbd48ec",
		"imgId": "18a27221dedc460b9bdc0a2d21352299",
		"searchFace": [
      		{
				"confidence": 1,
				"personId": "",
				"faceId": "a856a6c773334edaa57b151cef096238"
      		}
    	],
		"top_num": 1
  	}
}

错误码

错误码 说明 描述
1901 MISSING_ARGUMENTS 缺少参数,userId/facesetId/faceId不能为空或者空字符串
1902 INVALID_ARGUMENTS 参数非法,userId/facesetId/faceId格式非法
1905 INVALID_ID 非法标识,userId/facesetId/faceId未创建
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效

人脸对比

请求URL

https://dev.zhthinkjoy.com/api/faceApp/v2/faceCompare

请求方式

POST

描述

对比两张的图片中人脸的相似度,当图片上有多张人脸时,只选取识别度最高的人脸进行对比;使用faceId进行相似度对比,faceId通过 人脸区域检测人脸对比 获得;faceId对应的Face必须是由该userId人脸检测所产生,否则会报错。

请求参数

参数名 参数类型 备注
必须 accessToken String 习悦开发者平台全局唯一接口调用凭据
userId String 创建用户( createUser )接口所返回的userId
四选一 file1 File 第一张图片,分辨率小于1920*1920带有人脸的JPG(JPEG)/PNG图片文件
image1 String 第一张图片,分辨率小于1920*1920带有人脸的JPG(JPEG)/PNG图片文件的base64编码字符串
图片转Base64示例(仅供参考)>>
imageURL1 String 分辨率小于1920*1920带有人脸的JPG(JPEG)/PNG图片文件的URL链接
faceId1 String 人脸唯一标识,通过 人脸区域检测人脸对比 获得
四选一 file2 File 第二张图片,分辨率小于1920*1920带有人脸的JPG(JPEG)/PNG图片文件
image2 String 第一张图片,分辨率小于1920*1920带有人脸的JPG(JPEG)/PNG图片文件的base64编码字符串
图片转Base64示例(仅供参考)>>
imageURL2 String 分辨率小于1920*1920带有人脸的JPG(JPEG)/PNG图片文件的URL链接
faceId2 String 人脸唯一标识,通过 人脸区域检测人脸对比 获得

返回值说明

字段 类型 描述
resCode String 0表示正常返回, 其他编码表示发生异常
resMsg String 成功操作返回SUCCESS, 否则返回错误提示信息
resData Object 业务数据体
msgId String 请求唯一标识,用于向习悦开发者平台技术人员反馈和追查异常信息
confidence Double 两张人脸的相似度
face1 Object 第一张图片中人脸数据体
faceId String 人脸数据唯一标识,可用做 FaceSet样本特征分析人脸相似度对比 等操作。
注:faceId如果连续72小时没有存放在任意FaceSet中,则该faceId将会失效。
position List 人脸区域坐标数组
下标0:左上角纵坐标y1
下标1:左上角横坐标x1
下标2:右下角纵坐标y2
下标3:右下角横坐标x2
注:以上坐标有可能出现负值,请开发者注意处理。
face2 Object 第二张图片中人脸数据体
faceId String 人脸数据唯一标识,可用做 FaceSet样本特征分析人脸相似度对比 等操作。
注:faceId如果连续72小时没有存放在任意FaceSet中,则该faceId将会失效。
position List 人脸区域坐标数组
下标0:左上角纵坐标y1
下标1:左上角横坐标x1
下标2:右下角纵坐标y2
下标3:右下角横坐标x2
注:以上坐标有可能出现负值,请开发者注意处理。
imgId1 String 第一张图片唯一标识
imgId2 String 第二张图片唯一标识

示例

{
	"resCode": "0",
	"resMsg": "SUCCESS",
	"resData": {
		"imgId2": "7f0dc45bd66c4dec906ec5a9a1a03918",
		"msgId": "6dd33d81-5b48-41b7-be3c-7291d5094c75",
		"face1": {
			"faceId": "f094521c53d44d71af0183eafda85155",
			"position": [
        		44,
       	 	        40,
        		212,
        		159
      		]
    	},
		"confidence": 0.4607951939105988,
		"face2": {
			"faceId": "28c55aa9236844daae481091a22f37c4",
			"position": [
        		-31,
        		-5,
        		158,
        		138
      		]
    	},
		"imgId1": "80cbf91f66ee45978f58610fd3eabc99"
  	}
}

错误码

错误码 说明 描述
1901 MISSING_ARGUMENTS 缺少参数,必填参数不能为空或者空字符串
1902 INVALID_ARGUMENTS 参数非法,参数格式非法
1905 INVALID_ID 非法标识,userId未创建
1908 NO_FACE_DETECTED 图片中未检测到人脸
1954 NOT_AUTH 错误的accessToken,或者accessToken已失效
1956 GET_IMAGE_ERROR 获取图片异常,图片链接无效

状态码

状态码 说明 描述
0 SUCCESS 成功
1101 DB_ADD_OP_ERROR 数据库添加操作异常
1102 DB_UPDATE_OP_ERROR 数据库更新操作异常
1103 DB_DELETE_OP_ERROR 数据库删除操作异常
1104 DB_QUERY_OP_ERROR 数据库查询操作异常
1800 HTTP_ERROR http链接错误
1900 API_ERROR 服务错误
1901 MISSING_ARGUMENTS 缺少必要参数
1902 INVALID_ARGUMENTS 参数非法
1903 WRONG_ARGUMENTS 参数解析错误
1904 API_NOT_FOUND 不支持的操作
1905 INVALID_ID 非法ID
1906 NAME_EXISTS Name已存在
1907 FACESET_NOT_EMPTY 人脸集合中存在人脸
1908 NO_FACE_DETECTED 图片中未检测到人脸
1909 MULTI_FACES_DETECTED 图片中检测到多张人脸
1910 FACESET_NO_FACE 集合中没有人脸样本
1951 INVALID_IMAGE_SIZE 图片像素分辨率超过限制(1920X1920)
1952 LARGE_SIZE 图片大小超过限制
1953 NOT_BINDING 用户未绑定
1954 NOT_AUTH 未授权
1955 NOT_UNPACK 图片无法解压
1956 GET_IMAGE_ERROR 获取图片异常
Q群
咨询