}
响应示例
状态码：200 成功响应样例
{ "image1_face": { "bounding_box": { "width": 174, "top_left_y": 37, "top_left_x": 22, "height": 174 }
}, "similarity": 0.4078676104545593, "image2_face": {
"bounding_box": { "width": 118, "top_left_y": 28, "top_left_x": 94, "height": 118 }
}}
状态码：400 失败响应样例
{ "error_code": "FRS.0501",
"error_msg": "Detect no face, check out your picture."
}
状态码
状态码请参见状态码。
错误码
错误码请参见错误码。
7.4 人脸搜索(V1)
功能介绍
人脸搜索是指在已有的人脸库中，查询与目标人脸相似的一张或者多张人脸，并返回 相应的置信度。V1版本接口已经停售，该接口仅老用户可用，新用户推荐使用V2版本 API。
支持传入图片或者faceID进行人脸搜索，如果图片中包含多个人脸，选取图片中检测 到的最大尺寸人脸作为检索的输入。
前提条件：
请确保您已开通人脸识别服务，具体操作方法请参见申请服务。
约束限制：
● 只支持识别JPG、PNG、JPEG、BMP格式的图片。
● application/json请求的body中，请使用标准Json格式。
● Base64编码中请勿使用回车换行。
● 系统不保存用户图片。
● 图片大小小于8MB，由于过大图片会导致时延较长，并且图片信息量不大，建议 小于1MB。
● 图片分辨率小于4096*4096，图片中人脸像素大于80*80，建议120*120以上。
● 为保证识别效果，人脸图片建议要求如下：
a. 光照大于200lux、无反光强光阴影现象。
b. 人脸无遮挡、整体清晰无拖尾抖动等运动模糊。
c. 侧脸不超过30°、俯仰角小于15°、偏转角小于15°、图片中人脸保持竖置正 脸。
● 其他的约束限制信息请参见约束与限制章节。
建议：
● 由于过大图片对识别算法精度无明显提升，同时会导致时延较长，建议传入图片 小于1MB，一般500KB左右足够。
● OBS上存储的图片也建议小于1MB。
● 图片中人脸像素建议120*120以上。
URI
POST /v1/{project_id}/face-sets/{face_set_name}/search
表7-13 路径参数
参数 是否必选 参数类型 描述
project_id 是 String 项目ID，获取方法请参见获取项
目ID/账号名/AK/SK。
face_set_nam
e String 是 人脸库名称。
请求参数
表7-14 请求 Header 参数
参数 是否必选 参数类型 描述
X-Auth-Token 是 String 用户Token。
Token认证就是在调用API的时
image_url String 与
image_file、
image_file File 与
image_url、
image_base64 String 与
image_file、
face_id String 与
image_file、
top_n Integer 否 返回查询到的最相似的N张人脸，
N默认为10。
threshold Double 否 人脸相似度阈值，低于这个阈值 则不返回，取值范围0~1，一般情 况下建议取值0.93，默认为0。
sort JsonArray 否 支持字段排序，参考sort语法。
filter String 否 过滤条件，参考filter语法。
参数名 参数类型 是否必选 说明
return_fields JsonArray 否 指定返回的自定义字段。
响应参数
状态码：200
表7-16 响应 Body 参数
参数名 参数类型 说明
faces List 查找的人脸集合，详见
SearchFace。
调用失败时无此字段。
error_code String 调用失败时的错误码，具体请 参考错误码。
调用成功时无此字段。
error_msg String 调用失败时的错误信息。
调用成功时无此字段。
请求示例
● 请求样例（方式一：使用图片的BASE64编码）
POST https://{endpoint}/v1/{project_id}/face-sets/showFaceSet/search Request Header:
Content-Type: application/json
X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...
Request Body:
{ "image_base64": "/9j/4AAQSkZJRgABAgEASABIAAD", "sort" : [
{
"timestamp" : "asc"
}
], "return_fields" : ["timestamp", "id"], "filter" : "timestamp:12"
}
● 请求样例（方式二：使用图片文件）
POST https://{endpoint}/v1/{project_id}/face-sets/showFaceSet/search Request Header:
X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...
Request Body:
image_file: File(图片文件) return_fields: ["timestamp","id"]
filter: timestamp:12
● 请求样例（方式三：使用图片URL）
POST https://{endpoint}/v1/{project_id}/face-sets/showFaceSet/search Request Header:
Content-Type: application/json
X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...
Request Body:
{ "image_url":"/BucketName/ObjectName", "sort" : [
{
"timestamp" : "asc"
}
], "return_fields" : ["timestamp", "id"], "filter" : "timestamp:12"
}
● 请求样例（方式四：使用人脸编号）
POST https://{endpoint}/v1/{project_id}/face-sets/showFaceSet/search Request Header:
Content-Type: application/json
X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...
Request Body:
{ "face_id":"6KLB1Ktu", "sort" : [
{
"timestamp" : "asc"
} ],
"return_fields" : ["timestamp", "id"], "filter" : "timestamp:12"
}
● Python3语言请求代码示例（其他语言参照下列示例编写或使用FRS SDK）
# coding:utf-8 -*-import requests import base64
endpoint = '开通服务所在region的人脸识别服务域名' project_id = '开通服务所在region的用户项目ID' token = '用户获取得到的实际token值'
headers = {'Content-Type': 'application/json', 'X-Auth-Token': token}
face_set_name = 'showFaceSet'
url = "https://{endpoint}/v1/{project_id}/face-sets/{face_set_name}/search".format(
endpoint=endpoint,project_id=project_id,face_set_name=face_set_name) image_file_path = r'./data/face-demo.png'
with open(image_file_path, "rb") as bin_data:
image_data = bin_data.read()
image_base64 = base64.b64encode(image_data).decode("utf-8")
body = {"image_base64": image_base64, "sort": [{"timestamp": "asc"}], "return_fields": ["timestamp",
"id"], "filter": "timestamp:12"}
response = requests.post(url, headers=headers, json=body, verify=False) print(response.text)
● Java语言请求代码示例（其他语言参照下列示例编写或使用FRS SDK）
import com.huawei.trace.http.apache.httpclient.TraceApacheHttpClientBuilder;
import org.apache.http.impl.client.CloseableHttpClient;
* 使用前需已配置HttpClient jar包。jar包可通过下载SDK获取 */
public class FaceSearch {
protected static HttpClientBuilder buildClient(HttpClientBuilder httpClientBuilder) { SSLContext sslContext = null;
try {
sslContext = new SSLContextBuilder().loadTrustMaterial(null, new TrustStrategy() {
public boolean isTrusted(X509Certificate[] arg0, String arg1) throws CertificateException { return true;
httpClientBuilder.setSSLContext(sslContext);
httpClientBuilder.setConnectionTimeToLive(30, TimeUnit.SECONDS);
HostnameVerifier hostnameVerifier = NoopHostnameVerifier.INSTANCE;
SSLConnectionSocketFactory sslSocketFactory = new SSLConnectionSocketFactory(sslContext, hostnameVerifier);
Registry<ConnectionSocketFactory> socketFactoryRegistry
= RegistryBuilder.<ConnectionSocketFactory>create().register("http",
PlainConnectionSocketFactory.getSocketFactory()).register("https", sslSocketFactory).build();
PoolingHttpClientConnectionManager connMgr = new PoolingHttpClientConnectionManager(socketFactoryRegistry);
connMgr.setMaxTotal(200);
connMgr.setDefaultMaxPerRoute(100);
httpClientBuilder.setConnectionManager(connMgr);
return httpClientBuilder;
}
public static String doPost(String url, String jsonStr, String token, CloseableHttpClient client) { HttpPost post = new HttpPost(url);
StringEntity entity = new StringEntity(jsonStr, ContentType.APPLICATION_JSON);
post.setEntity(entity);
post.setHeader(HttpHeaders.CONTENT_TYPE, "application/json");
//time unit is milliseconds RequestConfig requestConfig =
RequestConfig.custom().setConnectTimeout(3000).setSocketTimeout(3000).build();
post.setConfig(requestConfig);
post.setHeader("X-Auth-Token", token);
HttpResponse response = null;
String result = "";
try {
response = client.execute(post);
HttpEntity responseBody = response.getEntity();
if (responseBody == null) {
System.out.println("the response body is null.");
return result;
} else {
byte[] byteStream = EntityUtils.toByteArray(responseBody);
System.arraycopy(byteStream, 0, new byte[byteStream.length], 0, byteStream.length);
result = new String(byteStream, StandardCharsets.UTF_8);
public static void main(String[] args) {
CloseableHttpClient client = buildClient(TraceApacheHttpClientBuilder.create()).build();
// endpoint,project_id和face_set_name需要替换成实际信息。
String url = "https://{{endpoint}}/v1/{{project_id}}/face-sets/{{face_set_name}}/search";
String jsonStr = "{\"image_base64\": \"/9j/4AAQSkZJRgABAgEASABIAAD...\", \"sort\":
[{\"timestamp\": \"asc\"}], \"return_fields\": [\"timestamp\", \"id\"], \"filter\": \"timestamp:12\"}";
String token = "对应region的token"; "external_image_id": "123", "external_fields": { "external_image_id": "12", "external_fields": {
{ "error_code": "FRS.0018",
"error_msg": "The service inner error."
}
状态码
状态码请参见状态码。
错误码
错误码请参见错误码。