# 人脸搜索服务API


**简介**:人脸搜索服务API


**HOST**:http://127.0.0.1:8080


**联系人**:


**Version**:2.0.0


**接口路径**:/v3/api-docs?group=2.0.0


[TOC]






# 01、集合(数据库)管理


## 1、创建一个集合(数据库)


**接口地址**:`/visual/collect/create`


**请求方式**:`POST`


**请求数据类型**:`application/x-www-form-urlencoded,application/json`


**响应数据类型**:`*/*`


**接口描述**:


**请求示例**:


```javascript
{
  "collectionComment": "",
  "collectionName": "",
  "faceColumns": [
    {
      "comment": "",
      "dataType": "",
      "name": ""
    }
  ],
  "namespace": "",
  "replicasNum": 0,
  "sampleColumns": [
    {
      "comment": "",
      "dataType": "",
      "name": ""
    }
  ],
  "shardsNum": 0,
  "storageEngine": "",
  "storageFaceInfo": false
}
```


**请求参数**:


| 参数名称 | 参数说明 | 请求类型    | 是否必须 | 数据类型 | schema |
| -------- | -------- | ----- | -------- | -------- | ------ |
|collectReqVo|集合信息|body|true|CollectReqVo|CollectReqVo|
|  collectionComment|集合描述：最大128个字符||false|string||
|  collectionName|集合名称：最大24个字符,支持小写字母、数字和下划线的组合||true|string||
|  faceColumns|自定义的人脸属性字段||false|array|FiledColumn|
|    comment|字段描述,最大64个字符||false|string||
|    dataType|字段类型，不能为UNDEFINED类型,可用值:BOOL,DOUBLE,FLOAT,INT,STRING,UNDEFINED||true|string||
|    name|字段名称,支持小写字母、数字和下划线的组合，最大32个字符||true|string||
|  namespace|命名空间：最大12个字符,支持小写字母、数字和下划线的组合||true|string||
|  replicasNum|数据分片中最大的文件个数，默认为0（不限制）,仅对Proxima引擎生效||false|integer(int64)||
|  sampleColumns|自定义的样本属性字段||false|array|FiledColumn|
|    comment|字段描述,最大64个字符||false|string||
|    dataType|字段类型，不能为UNDEFINED类型,可用值:BOOL,DOUBLE,FLOAT,INT,STRING,UNDEFINED||true|string||
|    name|字段名称,支持小写字母、数字和下划线的组合，最大32个字符||true|string||
|  shardsNum|要创建的集合的分片数，默认为0（即系统默认）,仅对Milvus引擎生效||false|integer(int32)||
|  storageEngine|保留图片及人脸信息的存储组件,可用值:ALI_OSS,CURR_DB,MIN_IO,TCE_COS||false|string||
|  storageFaceInfo|是否保留图片及人脸信息||false|boolean||


**响应状态**:


| 状态码 | 说明 | schema |
| -------- | -------- | ----- | 
|200|OK|ResponseInfo«boolean»|
|201|Created||
|401|Unauthorized||
|403|Forbidden||
|404|Not Found||


**响应参数**:


| 参数名称 | 参数说明 | 类型 | schema |
| -------- | -------- | ----- |----- | 
|code|返回代码|integer(int32)|integer(int32)|
|data|数据信息|boolean||
|message|返回信息|string||


**响应示例**:
```javascript
{
	"code": 0,
	"data": false,
	"message": ""
}
```


## 2、根据命名空间，集合名称删除集合


**接口地址**:`/visual/collect/delete`


**请求方式**:`GET`


**请求数据类型**:`application/x-www-form-urlencoded`


**响应数据类型**:`*/*`


**接口描述**:


**请求参数**:


| 参数名称 | 参数说明 | 请求类型    | 是否必须 | 数据类型 | schema |
| -------- | -------- | ----- | -------- | -------- | ------ |
|namespace|命名空间|query|true|string||
|collectionName|集合名称|query|true|string||


**响应状态**:


| 状态码 | 说明 | schema |
| -------- | -------- | ----- | 
|200|OK|ResponseInfo«boolean»|
|401|Unauthorized||
|403|Forbidden||
|404|Not Found||


**响应参数**:


| 参数名称 | 参数说明 | 类型 | schema |
| -------- | -------- | ----- |----- | 
|code|返回代码|integer(int32)|integer(int32)|
|data|数据信息|boolean||
|message|返回信息|string||


**响应示例**:
```javascript
{
	"code": 0,
	"data": false,
	"message": ""
}
```


## 3、根据命名空间，集合名称查看集合信息


**接口地址**:`/visual/collect/get`


**请求方式**:`GET`


**请求数据类型**:`application/x-www-form-urlencoded`


**响应数据类型**:`*/*`


**接口描述**:


**请求参数**:


| 参数名称 | 参数说明 | 请求类型    | 是否必须 | 数据类型 | schema |
| -------- | -------- | ----- | -------- | -------- | ------ |
|namespace|命名空间|query|true|string||
|collectionName|集合名称|query|true|string||


**响应状态**:


| 状态码 | 说明 | schema |
| -------- | -------- | ----- | 
|200|OK|ResponseInfo«CollectRepVo»|
|401|Unauthorized||
|403|Forbidden||
|404|Not Found||


**响应参数**:


| 参数名称 | 参数说明 | 类型 | schema |
| -------- | -------- | ----- |----- | 
|code|返回代码|integer(int32)|integer(int32)|
|data|数据信息|CollectRepVo|CollectRepVo|
|  collectionComment|集合描述：最大128个字符|string||
|  collectionName|集合名称：最大24个字符,支持小写字母、数字和下划线的组合|string||
|  faceColumns|自定义的人脸属性字段|array|FiledColumn|
|    comment|字段描述,最大64个字符|string||
|    dataType|字段类型，不能为UNDEFINED类型,可用值:BOOL,DOUBLE,FLOAT,INT,STRING,UNDEFINED|string||
|    name|字段名称,支持小写字母、数字和下划线的组合，最大32个字符|string||
|  namespace|命名空间：最大12个字符,支持小写字母、数字和下划线的组合|string||
|  replicasNum|数据分片中最大的文件个数，默认为0（不限制）,仅对Proxima引擎生效|integer(int64)||
|  sampleColumns|自定义的样本属性字段|array|FiledColumn|
|    comment|字段描述,最大64个字符|string||
|    dataType|字段类型，不能为UNDEFINED类型,可用值:BOOL,DOUBLE,FLOAT,INT,STRING,UNDEFINED|string||
|    name|字段名称,支持小写字母、数字和下划线的组合，最大32个字符|string||
|  shardsNum|要创建的集合的分片数，默认为0（即系统默认）,仅对Milvus引擎生效|integer(int32)||
|  storageEngine|保留图片及人脸信息的存储组件,可用值:ALI_OSS,CURR_DB,MIN_IO,TCE_COS|string||
|  storageFaceInfo|是否保留图片及人脸信息|boolean||
|message|返回信息|string||


**响应示例**:
```javascript
{
	"code": 0,
	"data": {
		"collectionComment": "",
		"collectionName": "",
		"faceColumns": [
			{
				"comment": "",
				"dataType": "",
				"name": ""
			}
		],
		"namespace": "",
		"replicasNum": 0,
		"sampleColumns": [
			{
				"comment": "",
				"dataType": "",
				"name": ""
			}
		],
		"shardsNum": 0,
		"storageEngine": "",
		"storageFaceInfo": false
	},
	"message": ""
}
```


## 4、根据命名空间查看集合列表


**接口地址**:`/visual/collect/list`


**请求方式**:`GET`


**请求数据类型**:`application/x-www-form-urlencoded`


**响应数据类型**:`*/*`


**接口描述**:


**请求参数**:


| 参数名称 | 参数说明 | 请求类型    | 是否必须 | 数据类型 | schema |
| -------- | -------- | ----- | -------- | -------- | ------ |
|namespace|命名空间|query|true|string||


**响应状态**:


| 状态码 | 说明 | schema |
| -------- | -------- | ----- | 
|200|OK|ResponseInfo«List«CollectRepVo»»|
|401|Unauthorized||
|403|Forbidden||
|404|Not Found||


**响应参数**:


| 参数名称 | 参数说明 | 类型 | schema |
| -------- | -------- | ----- |----- | 
|code|返回代码|integer(int32)|integer(int32)|
|data|数据信息|array|CollectRepVo|
|  collectionComment|集合描述：最大128个字符|string||
|  collectionName|集合名称：最大24个字符,支持小写字母、数字和下划线的组合|string||
|  faceColumns|自定义的人脸属性字段|array|FiledColumn|
|    comment|字段描述,最大64个字符|string||
|    dataType|字段类型，不能为UNDEFINED类型,可用值:BOOL,DOUBLE,FLOAT,INT,STRING,UNDEFINED|string||
|    name|字段名称,支持小写字母、数字和下划线的组合，最大32个字符|string||
|  namespace|命名空间：最大12个字符,支持小写字母、数字和下划线的组合|string||
|  replicasNum|数据分片中最大的文件个数，默认为0（不限制）,仅对Proxima引擎生效|integer(int64)||
|  sampleColumns|自定义的样本属性字段|array|FiledColumn|
|    comment|字段描述,最大64个字符|string||
|    dataType|字段类型，不能为UNDEFINED类型,可用值:BOOL,DOUBLE,FLOAT,INT,STRING,UNDEFINED|string||
|    name|字段名称,支持小写字母、数字和下划线的组合，最大32个字符|string||
|  shardsNum|要创建的集合的分片数，默认为0（即系统默认）,仅对Milvus引擎生效|integer(int32)||
|  storageEngine|保留图片及人脸信息的存储组件,可用值:ALI_OSS,CURR_DB,MIN_IO,TCE_COS|string||
|  storageFaceInfo|是否保留图片及人脸信息|boolean||
|message|返回信息|string||


**响应示例**:
```javascript
{
	"code": 0,
	"data": [
		{
			"collectionComment": "",
			"collectionName": "",
			"faceColumns": [
				{
					"comment": "",
					"dataType": "",
					"name": ""
				}
			],
			"namespace": "",
			"replicasNum": 0,
			"sampleColumns": [
				{
					"comment": "",
					"dataType": "",
					"name": ""
				}
			],
			"shardsNum": 0,
			"storageEngine": "",
			"storageFaceInfo": false
		}
	],
	"message": ""
}
```


# 02、人脸样本管理


## 1、创建一个样本


**接口地址**:`/visual/sample/create`


**请求方式**:`POST`


**请求数据类型**:`application/x-www-form-urlencoded,application/json`


**响应数据类型**:`*/*`


**接口描述**:


**请求示例**:


```javascript
{
  "collectionName": "",
  "namespace": "",
  "sampleData": [
    {
      "key": "",
      "value": {}
    }
  ],
  "sampleId": ""
}
```


**请求参数**:


| 参数名称 | 参数说明 | 请求类型    | 是否必须 | 数据类型 | schema |
| -------- | -------- | ----- | -------- | -------- | ------ |
|sampleDataReqVo|样本信息|body|true|SampleDataReqVo|SampleDataReqVo|
|  collectionName|集合名称：最大24个字符,支持小写字母、数字和下划线的组合||true|string||
|  namespace|命名空间：最大12个字符,支持小写字母、数字和下划线的组合||true|string||
|  sampleData|扩展字段||false|array|FieldKeyValue|
|    key|字段名，与创建集合时给定的字段名一致||true|string||
|    value|字段值，与创建集合时给定的类型一致，若为字符串，最大为512个字符||false|object||
|  sampleId|样本ID：最大32个字符,支持小写字母、数字和下划线的组合||true|string||


**响应状态**:


| 状态码 | 说明 | schema |
| -------- | -------- | ----- | 
|200|OK|ResponseInfo«boolean»|
|201|Created||
|401|Unauthorized||
|403|Forbidden||
|404|Not Found||


**响应参数**:


| 参数名称 | 参数说明 | 类型 | schema |
| -------- | -------- | ----- |----- | 
|code|返回代码|integer(int32)|integer(int32)|
|data|数据信息|boolean||
|message|返回信息|string||


**响应示例**:
```javascript
{
	"code": 0,
	"data": false,
	"message": ""
}
```


## 3、根据条件删除样本


**接口地址**:`/visual/sample/delete`


**请求方式**:`GET`


**请求数据类型**:`application/x-www-form-urlencoded`


**响应数据类型**:`*/*`


**接口描述**:


**请求参数**:


| 参数名称 | 参数说明 | 请求类型    | 是否必须 | 数据类型 | schema |
| -------- | -------- | ----- | -------- | -------- | ------ |
|namespace|命名空间|query|true|string||
|collectionName|集合名称|query|true|string||
|sampleId|样本ID|query|true|string||


**响应状态**:


| 状态码 | 说明 | schema |
| -------- | -------- | ----- | 
|200|OK|ResponseInfo«boolean»|
|401|Unauthorized||
|403|Forbidden||
|404|Not Found||


**响应参数**:


| 参数名称 | 参数说明 | 类型 | schema |
| -------- | -------- | ----- |----- | 
|code|返回代码|integer(int32)|integer(int32)|
|data|数据信息|boolean||
|message|返回信息|string||


**响应示例**:
```javascript
{
	"code": 0,
	"data": false,
	"message": ""
}
```


## 4、根据条件查看样本


**接口地址**:`/visual/sample/get`


**请求方式**:`GET`


**请求数据类型**:`application/x-www-form-urlencoded`


**响应数据类型**:`*/*`


**接口描述**:


**请求参数**:


| 参数名称 | 参数说明 | 请求类型    | 是否必须 | 数据类型 | schema |
| -------- | -------- | ----- | -------- | -------- | ------ |
|namespace|命名空间|query|true|string||
|collectionName|集合名称|query|true|string||
|sampleId|样本ID|query|true|string||


**响应状态**:


| 状态码 | 说明 | schema |
| -------- | -------- | ----- | 
|200|OK|ResponseInfo«SampleDataRepVo»|
|401|Unauthorized||
|403|Forbidden||
|404|Not Found||


**响应参数**:


| 参数名称 | 参数说明 | 类型 | schema |
| -------- | -------- | ----- |----- | 
|code|返回代码|integer(int32)|integer(int32)|
|data|数据信息|SampleDataRepVo|SampleDataRepVo|
|  collectionName|集合名称：最大24个字符,支持小写字母、数字和下划线的组合|string||
|  faces|人脸数据|array|SimpleFaceVo|
|    faceData|人脸扩展的额外数据|array|FieldKeyValue|
|      key|字段名，与创建集合时给定的字段名一致|string||
|      value|字段值，与创建集合时给定的类型一致，若为字符串，最大为512个字符|object||
|    faceId|人脸ID|string||
|    faceScore|人脸分数|number||
|  namespace|命名空间：最大12个字符,支持小写字母、数字和下划线的组合|string||
|  sampleData|扩展字段|array|FieldKeyValue|
|    key|字段名，与创建集合时给定的字段名一致|string||
|    value|字段值，与创建集合时给定的类型一致，若为字符串，最大为512个字符|object||
|  sampleId|样本ID：最大32个字符,支持小写字母、数字和下划线的组合|string||
|message|返回信息|string||


**响应示例**:
```javascript
{
	"code": 0,
	"data": {
		"collectionName": "",
		"faces": [
			{
				"faceData": [
					{
						"key": "",
						"value": {}
					}
				],
				"faceId": "",
				"faceScore": 0
			}
		],
		"namespace": "",
		"sampleData": [
			{
				"key": "",
				"value": {}
			}
		],
		"sampleId": ""
	},
	"message": ""
}
```


## 5、根据查询信息查看样本列表


**接口地址**:`/visual/sample/list`


**请求方式**:`GET`


**请求数据类型**:`application/x-www-form-urlencoded`


**响应数据类型**:`*/*`


**接口描述**:


**请求参数**:


| 参数名称 | 参数说明 | 请求类型    | 是否必须 | 数据类型 | schema |
| -------- | -------- | ----- | -------- | -------- | ------ |
|namespace|命名空间|query|true|string||
|collectionName|集合名称|query|true|string||
|offset|起始记录:默认0|query|true|integer(int32)||
|limit|样本数目：默认10|query|true|integer(int32)||
|order|排列方式：默认asc，包括asc（升序）和desc（降序）|query|true|string||


**响应状态**:


| 状态码 | 说明 | schema |
| -------- | -------- | ----- | 
|200|OK|ResponseInfo«List«SampleDataRepVo»»|
|401|Unauthorized||
|403|Forbidden||
|404|Not Found||


**响应参数**:


| 参数名称 | 参数说明 | 类型 | schema |
| -------- | -------- | ----- |----- | 
|code|返回代码|integer(int32)|integer(int32)|
|data|数据信息|array|SampleDataRepVo|
|  collectionName|集合名称：最大24个字符,支持小写字母、数字和下划线的组合|string||
|  faces|人脸数据|array|SimpleFaceVo|
|    faceData|人脸扩展的额外数据|array|FieldKeyValue|
|      key|字段名，与创建集合时给定的字段名一致|string||
|      value|字段值，与创建集合时给定的类型一致，若为字符串，最大为512个字符|object||
|    faceId|人脸ID|string||
|    faceScore|人脸分数|number||
|  namespace|命名空间：最大12个字符,支持小写字母、数字和下划线的组合|string||
|  sampleData|扩展字段|array|FieldKeyValue|
|    key|字段名，与创建集合时给定的字段名一致|string||
|    value|字段值，与创建集合时给定的类型一致，若为字符串，最大为512个字符|object||
|  sampleId|样本ID：最大32个字符,支持小写字母、数字和下划线的组合|string||
|message|返回信息|string||


**响应示例**:
```javascript
{
	"code": 0,
	"data": [
		{
			"collectionName": "",
			"faces": [
				{
					"faceData": [
						{
							"key": "",
							"value": {}
						}
					],
					"faceId": "",
					"faceScore": 0
				}
			],
			"namespace": "",
			"sampleData": [
				{
					"key": "",
					"value": {}
				}
			],
			"sampleId": ""
		}
	],
	"message": ""
}
```


## 2、更新一个样本


**接口地址**:`/visual/sample/update`


**请求方式**:`POST`


**请求数据类型**:`application/x-www-form-urlencoded,application/json`


**响应数据类型**:`*/*`


**接口描述**:


**请求示例**:


```javascript
{
  "collectionName": "",
  "namespace": "",
  "sampleData": [
    {
      "key": "",
      "value": {}
    }
  ],
  "sampleId": ""
}
```


**请求参数**:


| 参数名称 | 参数说明 | 请求类型    | 是否必须 | 数据类型 | schema |
| -------- | -------- | ----- | -------- | -------- | ------ |
|sampleDataReqVo|样本信息|body|true|SampleDataReqVo|SampleDataReqVo|
|  collectionName|集合名称：最大24个字符,支持小写字母、数字和下划线的组合||true|string||
|  namespace|命名空间：最大12个字符,支持小写字母、数字和下划线的组合||true|string||
|  sampleData|扩展字段||false|array|FieldKeyValue|
|    key|字段名，与创建集合时给定的字段名一致||true|string||
|    value|字段值，与创建集合时给定的类型一致，若为字符串，最大为512个字符||false|object||
|  sampleId|样本ID：最大32个字符,支持小写字母、数字和下划线的组合||true|string||


**响应状态**:


| 状态码 | 说明 | schema |
| -------- | -------- | ----- | 
|200|OK|ResponseInfo«boolean»|
|201|Created||
|401|Unauthorized||
|403|Forbidden||
|404|Not Found||


**响应参数**:


| 参数名称 | 参数说明 | 类型 | schema |
| -------- | -------- | ----- |----- | 
|code|返回代码|integer(int32)|integer(int32)|
|data|数据信息|boolean||
|message|返回信息|string||


**响应示例**:
```javascript
{
	"code": 0,
	"data": false,
	"message": ""
}
```


# 03、人脸数据管理


## 1、创建一个人脸数据


**接口地址**:`/visual/face/create`


**请求方式**:`POST`


**请求数据类型**:`application/x-www-form-urlencoded,application/json`


**响应数据类型**:`*/*`


**接口描述**:


**请求示例**:


```javascript
{
  "collectionName": "",
  "faceData": [
    {
      "key": "",
      "value": {}
    }
  ],
  "faceScoreThreshold": 0,
  "imageBase64": "",
  "maxConfidenceThresholdWithOtherSample": 0,
  "minConfidenceThresholdWithThisSample": 0,
  "namespace": "",
  "sampleId": ""
}
```


**请求参数**:


| 参数名称 | 参数说明 | 请求类型    | 是否必须 | 数据类型 | schema |
| -------- | -------- | ----- | -------- | -------- | ------ |
|faceDataReqVo|FaceDataReqVo|body|true|FaceDataReqVo|FaceDataReqVo|
|  collectionName|集合名称：最大24个字符,支持小写字母、数字和下划线的组合||true|string||
|  faceData|扩展字段||false|array|FieldKeyValue|
|    key|字段名，与创建集合时给定的字段名一致||true|string||
|    value|字段值，与创建集合时给定的类型一致，若为字符串，最大为512个字符||false|object||
|  faceScoreThreshold|人脸质量分数阈值,范围：[0,100]：默认0。当设置为0时，会默认使用当前模型的默认值，该方法为推荐使用方式||false|number(float)||
|  imageBase64|图像Base64编码值||true|string||
|  maxConfidenceThresholdWithOtherSample|当前样本与其他样本的人脸相似度的最大阈值,范围：[0,100]：默认0。当设置为0时，表示不做类间相似度判断逻辑,开启后对效率有较大影响||false|number(float)||
|  minConfidenceThresholdWithThisSample|当前样本的人脸相似度的最小阈值,范围：[0,100]：默认0。当设置为0时，表示不做类间相似度判断逻辑,开启后对效率有较大影响||false|number(float)||
|  namespace|命名空间：最大12个字符,支持小写字母、数字和下划线的组合||true|string||
|  sampleId|样本ID：最大32个字符,支持小写字母、数字和下划线的组合||true|string||


**响应状态**:


| 状态码 | 说明 | schema |
| -------- | -------- | ----- | 
|200|OK|ResponseInfo«FaceDataRepVo»|
|201|Created||
|401|Unauthorized||
|403|Forbidden||
|404|Not Found||


**响应参数**:


| 参数名称 | 参数说明 | 类型 | schema |
| -------- | -------- | ----- |----- | 
|code|返回代码|integer(int32)|integer(int32)|
|data|数据信息|FaceDataRepVo|FaceDataRepVo|
|  collectionName|集合名称：最大24个字符,支持小写字母、数字和下划线的组合|string||
|  faceData|扩展字段|array|FieldKeyValue|
|    key|字段名，与创建集合时给定的字段名一致|string||
|    value|字段值，与创建集合时给定的类型一致，若为字符串，最大为512个字符|object||
|  faceId|人脸ID|string||
|  faceScore|人脸人数质量|number(float)||
|  namespace|命名空间：最大12个字符,支持小写字母、数字和下划线的组合|string||
|  sampleId|样本ID：最大32个字符,支持小写字母、数字和下划线的组合|string||
|message|返回信息|string||


**响应示例**:
```javascript
{
	"code": 0,
	"data": {
		"collectionName": "",
		"faceData": [
			{
				"key": "",
				"value": {}
			}
		],
		"faceId": "",
		"faceScore": 0,
		"namespace": "",
		"sampleId": ""
	},
	"message": ""
}
```


## 2、根据条件删除人脸数据


**接口地址**:`/visual/face/delete`


**请求方式**:`GET`


**请求数据类型**:`application/x-www-form-urlencoded`


**响应数据类型**:`*/*`


**接口描述**:


**请求参数**:


| 参数名称 | 参数说明 | 请求类型    | 是否必须 | 数据类型 | schema |
| -------- | -------- | ----- | -------- | -------- | ------ |
|namespace|命名空间|query|true|string||
|collectionName|集合名称|query|true|string||
|sampleId|样本ID|query|true|string||
|faceId|人脸ID|query|true|string||


**响应状态**:


| 状态码 | 说明 | schema |
| -------- | -------- | ----- | 
|200|OK|ResponseInfo«boolean»|
|401|Unauthorized||
|403|Forbidden||
|404|Not Found||


**响应参数**:


| 参数名称 | 参数说明 | 类型 | schema |
| -------- | -------- | ----- |----- | 
|code|返回代码|integer(int32)|integer(int32)|
|data|数据信息|boolean||
|message|返回信息|string||


**响应示例**:
```javascript
{
	"code": 0,
	"data": false,
	"message": ""
}
```


# 04、人脸搜索服务


## 1、人脸搜索M:N


**接口地址**:`/visual/search/do`


**请求方式**:`POST`


**请求数据类型**:`application/x-www-form-urlencoded,application/json`


**响应数据类型**:`*/*`


**接口描述**:


**请求示例**:


```javascript
{
  "collectionName": "",
  "confidenceThreshold": 0,
  "faceScoreThreshold": 0,
  "imageBase64": "",
  "limit": 0,
  "maxFaceNum": 0,
  "namespace": ""
}
```


**请求参数**:


| 参数名称 | 参数说明 | 请求类型    | 是否必须 | 数据类型 | schema |
| -------- | -------- | ----- | -------- | -------- | ------ |
|faceSearchReqVo|人脸搜索参数|body|true|FaceSearchReqVo|FaceSearchReqVo|
|  collectionName|集合名称||true|string||
|  confidenceThreshold|人脸匹配分数阈值，范围：[-100,100]：默认0||false|number(float)||
|  faceScoreThreshold|人脸质量分数阈值,范围：[0,100]：默认0。当设置为0时，会默认使用当前模型的默认值，该方法为推荐使用方式||false|number(float)||
|  imageBase64|图像Base64编码值||true|string||
|  limit|最大搜索条数：默认5||false|integer(int32)||
|  maxFaceNum|对输入图像中多少个人脸进行检索比对：默认5||false|integer(int32)||
|  namespace|命名空间||true|string||


**响应状态**:


| 状态码 | 说明 | schema |
| -------- | -------- | ----- | 
|200|OK|ResponseInfo«List«FaceSearchRepVo»»|
|201|Created||
|401|Unauthorized||
|403|Forbidden||
|404|Not Found||


**响应参数**:


| 参数名称 | 参数说明 | 类型 | schema |
| -------- | -------- | ----- |----- | 
|code|返回代码|integer(int32)|integer(int32)|
|data|数据信息|array|FaceSearchRepVo|
|  faceScore|人脸分数:[0,100]|number(float)||
|  location|人脸位置信息|FaceLocation|FaceLocation|
|    h|人脸高度|integer||
|    w|人脸宽度|integer||
|    x|左上角x坐标|integer||
|    y|左上角y坐标|integer||
|  match|匹配的人脸列表|array|SampleFaceVo|
|    confidence|转换后的置信度:[-100,100]，值越大，相似度越高。|number||
|    faceData|人脸扩展的额外数据|array|FieldKeyValue|
|      key|字段名，与创建集合时给定的字段名一致|string||
|      value|字段值，与创建集合时给定的类型一致，若为字符串，最大为512个字符|object||
|    faceId|人脸ID|string||
|    faceScore|人脸分数:[0,100]|number||
|    sampleData|样本扩展的额外数据|array|FieldKeyValue|
|      key|字段名，与创建集合时给定的字段名一致|string||
|      value|字段值，与创建集合时给定的类型一致，若为字符串，最大为512个字符|object||
|    sampleId|样本ID|string||
|message|返回信息|string||


**响应示例**:
```javascript
{
	"code": 0,
	"data": [
		{
			"faceScore": 0,
			"location": {
				"h": 0,
				"w": 0,
				"x": 0,
				"y": 0
			},
			"match": [
				{
					"confidence": 0,
					"faceData": [
						{
							"key": "",
							"value": {}
						}
					],
					"faceId": "",
					"faceScore": 0,
					"sampleData": [
						{
							"key": "",
							"value": {}
						}
					],
					"sampleId": ""
				}
			]
		}
	],
	"message": ""
}
```


# 05、人脸比对服务


## 1、人脸比对1:1


**接口地址**:`/visual/compare/do`


**请求方式**:`POST`


**请求数据类型**:`application/x-www-form-urlencoded,application/json`


**响应数据类型**:`*/*`


**接口描述**:


**请求示例**:


```javascript
{
  "faceScoreThreshold": 0,
  "imageBase64A": "",
  "imageBase64B": "",
  "needFaceInfo": false
}
```


**请求参数**:


| 参数名称 | 参数说明 | 请求类型    | 是否必须 | 数据类型 | schema |
| -------- | -------- | ----- | -------- | -------- | ------ |
|faceCompareReqVo|FaceCompareReqVo|body|true|FaceCompareReqVo|FaceCompareReqVo|
|  faceScoreThreshold|人脸质量分数阈值,范围：[0,100]：默认0。当设置为0时，会默认使用当前模型的默认值，该方法为推荐使用方式||false|number(float)||
|  imageBase64A|图像A的Base64编码值||true|string||
|  imageBase64B|图像B的Base64编码值||true|string||
|  needFaceInfo|是否需要人脸信息,默认为:true||false|boolean||


**响应状态**:


| 状态码 | 说明 | schema |
| -------- | -------- | ----- | 
|200|OK|ResponseInfo«FaceCompareRepVo»|
|201|Created||
|401|Unauthorized||
|403|Forbidden||
|404|Not Found||


**响应参数**:


| 参数名称 | 参数说明 | 类型 | schema |
| -------- | -------- | ----- |----- | 
|code|返回代码|integer(int32)|integer(int32)|
|data|数据信息|FaceCompareRepVo|FaceCompareRepVo|
|  confidence|余弦距离转换后的置信度:[-100,100]，值越大，相似度越高。|number(float)||
|  distance|向量欧式距离:>=0|number(float)||
|  faceInfo|人脸信息,参数needFaceInfo=false时，值为null|CompareFace|CompareFace|
|    faceScoreA|A图片人脸分数:[0,100]|number||
|    faceScoreB|B图片人脸分数:[0,100]|number||
|    locationA|A图片人脸位置信息|FaceLocation|FaceLocation|
|      h|人脸高度|integer||
|      w|人脸宽度|integer||
|      x|左上角x坐标|integer||
|      y|左上角y坐标|integer||
|    locationB|B图片人脸位置信息|FaceLocation|FaceLocation|
|      h|人脸高度|integer||
|      w|人脸宽度|integer||
|      x|左上角x坐标|integer||
|      y|左上角y坐标|integer||
|message|返回信息|string||


**响应示例**:
```javascript
{
	"code": 0,
	"data": {
		"confidence": 0,
		"distance": 0,
		"faceInfo": {
			"faceScoreA": 0,
			"faceScoreB": 0,
			"locationA": {
				"h": 0,
				"w": 0,
				"x": 0,
				"y": 0
			},
			"locationB": {
				"h": 0,
				"w": 0,
				"x": 0,
				"y": 0
			}
		}
	},
	"message": ""
}
```