人脸搜索

功能介绍

人脸搜索是指在已有的人脸库中，查询与目标人脸相似的一张或者多张人脸，并返回相应的置信度。如果图片中包含多个人脸，选取图片中检测到的最大尺寸人脸作为检索的输入。

支持传入图片或者faceID进行人脸搜索。

前提条件：

请确保您已开通人脸识别服务，具体操作方法请参见申请服务。

调试

您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。

URI

POST /v2/{project_id}/face-sets/{face_set_name}/search

请求参数

响应参数

状态码：200

状态码： 400

请求示例

X-Auth-Token值获取方法请参见快速入门。

• 在人脸库中，查询与目标人脸相似的一张或者多张人脸，目标人脸通过图片的base64编码传入

  POST https://{endpoint}/v2/{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}/v2/{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}/v2/{project_id}/face-sets/showFaceSet/search
  Request Header:
  Content-Type: application/json
  X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...
  
  Request Body:
  {
    "image_url":"https://<bucket-name>.<endpoint>/<object-name>",
    "sort" : [
      {
        "timestamp" : "asc"
      } 
    ],
    "return_fields" : ["timestamp", "id"],
    "filter" : "timestamp:12"
  }

• 在人脸库中，查询与目标人脸相似的一张或者多张人脸，目标人脸通过人脸ID传入

  POST https://{endpoint}/v2/{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语言在人脸库中，查询与目标人脸相似的一张或者多张人脸

  # -*- 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}/v2/{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语言在人脸库中，查询与目标人脸相似的一张或者多张人脸

  import com.huawei.trace.http.apache.httpclient.TraceApacheHttpClientBuilder;
  import org.apache.http.HttpEntity;
  import org.apache.http.HttpHeaders;
  import org.apache.http.HttpResponse;
  import org.apache.http.client.config.RequestConfig;
  import org.apache.http.client.methods.HttpPost;
  import org.apache.http.config.Registry;
  import org.apache.http.config.RegistryBuilder;
  import org.apache.http.conn.socket.ConnectionSocketFactory;
  import org.apache.http.conn.socket.PlainConnectionSocketFactory;
  import org.apache.http.conn.ssl.NoopHostnameVerifier;
  import org.apache.http.conn.ssl.SSLConnectionSocketFactory;
  import org.apache.http.entity.ContentType;
  import org.apache.http.entity.StringEntity;
  import org.apache.http.impl.client.CloseableHttpClient;
  import org.apache.http.impl.client.HttpClientBuilder;
  import org.apache.http.impl.conn.PoolingHttpClientConnectionManager;
  import org.apache.http.ssl.SSLContextBuilder;
  import org.apache.http.ssl.TrustStrategy;
  import org.apache.http.util.EntityUtils;
  import java.io.IOException;
  import java.nio.charset.StandardCharsets;
  import java.security.KeyManagementException;
  import java.security.KeyStoreException;
  import java.security.NoSuchAlgorithmException;
  import java.security.cert.CertificateException;
  import java.security.cert.X509Certificate;
  import java.util.concurrent.TimeUnit;
  import javax.net.ssl.HostnameVerifier;
  import javax.net.ssl.SSLContext;
  
  /**
   * 此demo仅供测试使用，强烈建议使用SDK
   * 使用前需已配置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;
                  }
              }).build();
          } catch (NoSuchAlgorithmException e) {
              throw new RuntimeException(e.getMessage());
          } catch (KeyManagementException e) {
              throw new RuntimeException(e.getMessage());
          } catch (KeyStoreException e) {
              throw new RuntimeException(e.getMessage());
          }
          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);
              }
          } catch (IOException e) {
              e.printStackTrace();
          }
          return result;
      }
  
      public static void main(String[] args) {
          CloseableHttpClient client = buildClient(TraceApacheHttpClientBuilder.create()).build();
          // endpoint,project_id和face_set_name需要替换成实际信息。
          String url = "https://{{endpoint}}/v2/{{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";
          String result = doPost(url, jsonStr, token, client);
          System.out.println(result);
      }
  }

响应示例

状态码：200

状态码

状态码请参见状态码。

错误码

错误码请参见错误码。