更新时间:2022-04-15 GMT+08:00
分享

人脸检测(V1)

功能介绍

人脸检测是对输入图片进行人脸检测和分析,输出人脸在图像中的位置、人脸关键点位置和人脸关键属性。V1版本接口已经停售,该接口仅老用户可用,新用户推荐使用V2版本API。

前提条件:

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

约束限制:
  • 只支持识别JPG、PNG、JPEG、BMP格式的图片。
  • application/json请求的body中,请使用标准Json格式。
  • Base64编码中请勿使用回车换行。
  • 系统不保存用户图片。
  • 图片大小小于8MB,由于过大图片会导致时延较长,并且图片信息量不大,建议小于1MB
  • 图片分辨率小于4096*4096,图片中人脸像素大于80*80,建议120*120以上。
  • 为保证识别效果,人脸图片建议要求如下:
    1. 光照大于200lux、无反光强光阴影现象。
    2. 人脸无遮挡、整体清晰无拖尾抖动等运动模糊。
    3. 侧脸不超过30°、俯仰角小于15°、偏转角小于15°、图片中人脸保持竖置正脸。
  • 其他的约束限制信息请参见约束与限制章节。
建议:
  • 由于过大图片对识别算法精度无明显提升,同时会导致时延较长,建议传入图片小于1MB,一般500KB左右足够。
  • OBS上存储的图片也建议小于1MB
  • 图片中人脸像素建议120*120以上。

URI

POST /v1/{project_id}/face-detect

表1 路径参数

参数

是否必选

参数类型

描述

project_id

String

项目ID,获取方法请参见获取项目ID/账号名/AK/SK

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

String

用户Token。

Token认证就是在调用API的时候将Token加到请求消息头,从而通过身份认证,获得操作API的权限,响应消息头中X-Subject-Token的值即为Token。

表3 请求Body参数

参数名

是否必选

参数类型

说明

image_url

与image_file、image_base64三选一

String

图片的URL路径,目前仅支持华为云上OBS的URL,同时需保证人脸识别服务有权限读取该OBS桶的数据。开通读取权限的操作请参见服务授权

image_file

与image_url、image_base64三选一

File

本地图片文件,图片不能超过8MB,建议小于1MB。上传文件时,请求格式为multipart。

image_base64

与image_file、image_url三选一

String

图像数据,Base64编码,要求:
  • Base64编码后大小不超过8MB,建议小于1MB
  • 图片为JPG/JPEG/BMP/PNG格式。

attributes

String

是否返回人脸属性,希望获取的属性列表,多个属性间使用逗号(,)隔开。目前支持的属性有:
  • 0:人脸姿态
  • 2:年龄
  • 3:人脸关键点
  • 4:装束(帽子、眼镜)
  • 5:笑脸

响应参数

表4 响应Body参数

参数名

参数类型

说明

faces

List

检测到的人脸,DetectFace结构见DetectFace

调用失败时无此字段。

error_code

String

调用失败时的错误码,具体请参考错误码

调用成功时无此字段。

error_msg

String

调用失败时的错误信息。

调用成功时无此字段。

请求示例

  • 请求样例(方式一:使用图片的BASE64编码)
    POST https://{endpoint}/v1/{project_id}/face-detect
    Request Header:
    Content-Type: application/json
    X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...
    
    Request Body:
    {
        "image_base64": "/9j/4AAQSkZJRgABAgEASABIAAD",
        "attributes": "0,2,3,4,5"
    }
  • 请求样例(方式二:使用图片文件)
    POST https://{endpoint}/v1/{project_id}/face-detect
    Request Header:
    X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...
    
    Request Body:
      image_file: File(图片文件)
      attributes: 0,2,3,4,5
  • 请求样例(方式三:使用图片URL)
    POST https://{endpoint}/v1/{project_id}/face-detect
    Request Header:
    Content-Type: application/json
    X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...
    
    Request Body:
    {
        "image_url": "/BucketName/ObjectName",
        "attributes": "0,2,3,4,5"
    }
  • 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}
    
    url = "https://{endpoint}/v1/{project_id}/face-detect".format(endpoint=endpoint, project_id=project_id)
    imagepath = r'./data/face-demo.png'
    with open(imagepath, "rb") as bin_data:
        image_data = bin_data.read()
    image_base64 = base64.b64encode(image_data).decode("utf-8")  # 使用图片的base64编码
    body = {"image_base64": image_base64, "attributes": "0,2,3,4,5"}
    
    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.HttpHeaders;
    import org.apache.http.client.config.RequestConfig;
    import org.apache.http.client.methods.HttpPost;
    import org.apache.http.HttpEntity;
    import org.apache.http.HttpResponse;
    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 FaceDetect {
        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需要替换成实际信息。
            String url = "https://{{endpoint}}/v1/{{project_id}}/face-detect";
            // image_base64需要替换成实际的值
            String jsonStr = "{ \"image_base64\": \"/9j/4AAQSkZJRgABAgEASABIAAD...\"}";
            String token = "对应region的token";
            String result = doPost(url, jsonStr, token, client);
            System.out.println(result);
        }
    }

响应示例

状态码:200

成功响应样例
{
  "faces": [
    {
      "bounding_box": {
        "width": 174,
        "top_left_y": 37,
        "top_left_x": 22,
        "height": 174
      },
      "attributes": {
        "age": 35,
        "smile": "yes",
        "dress": {
          "glass": "none",
          "hat": "none"
        },
        "headpose": {
          "pitch_angle": -3.8639126,
          "roll_angle": -3.988193,
          "yaw_angle": -1.0292832
        }
      },
      "landmark": {
      "eyebrow_contour": {
        "point": [
          {
            "x": 158.78517,
            "y": 90.02418
          },
          {
            "x": 150.86162,
            "y": 82.432076
          },
          {
            "x": 131.3591,
            "y": 80.78191
          },
          {
            "x": 121.39423,
            "y": 87.62841
          },
          {
            "x": 132.25839,
            "y": 88.44499
          },
          {
            "x": 149.63844,
            "y": 89.3718
          },
          {
            "x": 59.65225,
            "y": 99.64757
          },
          {
            "x": 65.96038,
            "y": 88.92635
          },
          {
            "x": 85.72037,
            "y": 85.07116
          },
          {
            "x": 97.09234,
            "y": 89.34221
          },
          {
            "x": 86.07851,
            "y": 92.297516
          },
          {
            "x": 67.51544,
            "y": 95.58905
          }
        ]
      },
      "eyes_contour": {
        "point": [
          {
            "x": 69.22003,
            "y": 105.52183
          },
          {
            "x": 81.599174,
            "y": 98.70017
          },
          {
            "x": 94.22879,
            "y": 103.18641
          },
          {
            "x": 82.32345,
            "y": 107.02255
          },
          {
            "x": 150.97876,
            "y": 99.29232
          },
          {
            "x": 137.91818,
            "y": 93.49849
          },
          {
            "x": 125.78866,
            "y": 100.8499
          },
          {
            "x": 138.81555,
            "y": 102.29028
          },
          {
            "x": 75.16096,
            "y": 100.01521
          },
          {
            "x": 75.6541,
            "y": 107.08471
          },
          {
            "x": 89.18221,
            "y": 106.11414
          },
          {
            "x": 88.87559,
            "y": 98.87617
          },
          {
            "x": 130.7761,
            "y": 95.49036
          },
          {
            "x": 131.64914,
            "y": 102.47154
          },
          {
            "x": 145.64833,
            "y": 101.04822
          },
          {
            "x": 145.52222,
            "y": 94.39164
          }
        ]
      },
      "face_contour": {
        "point": [
          {
            "x": 50.049454,
            "y": 104.4499
          },
          {
            "x": 52.502007,
            "y": 123.68245
          },
          {
            "x": 55.028637,
            "y": 143.12273
          },
          {
            "x": 59.972454,
            "y": 163.16571
          },
          {
            "x": 69.73235,
            "y": 180.53296
          },
          {
            "x": 81.76993,
            "y": 195.74933
          },
          {
            "x": 96.15602,
            "y": 210.08699
          },
          {
            "x": 115.32445,
            "y": 215.14973
          },
          {
            "x": 134.04883,
            "y": 209.08778
          },
          {
            "x": 147.96034,
            "y": 194.2003
          },
          {
            "x": 158.3112,
            "y": 178.27126
          },
          {
            "x": 165.62479,
            "y": 159.71454
          },
          {
            "x": 168.95554,
            "y": 139.12373
          },
          {
            "x": 169.59795,
            "y": 119.938416
          },
          {
            "x": 169.9221,
            "y": 99.658844
          }
        ]
      },
      "mouth_contour": {
        "point": [
          {
            "x": 82.56091,
            "y": 160.6078
          },
          {
            "x": 91.546906,
            "y": 154.97893
          },
          {
            "x": 101.45366,
            "y": 152.51962
          },
          {
            "x": 111.45223,
            "y": 153.75433
          },
          {
            "x": 122.52581,
            "y": 152.07089
          },
          {
            "x": 133.3687,
            "y": 152.31891
          },
          {
            "x": 142.48122,
            "y": 154.72552
          },
          {
            "x": 136.62144,
            "y": 167.81747
          },
          {
            "x": 126.79148,
            "y": 175.79927
          },
          {
            "x": 113.959526,
            "y": 179.32193
          },
          {
            "x": 99.90567,
            "y": 178.14986
          },
          {
            "x": 88.95302,
            "y": 172.11215
          },
          {
            "x": 95.30528,
            "y": 168.83522
          },
          {
            "x": 112.094025,
            "y": 170.73698
          },
          {
            "x": 129.00156,
            "y": 166.50134
          },
          {
            "x": 128.46986,
            "y": 156.3436
          },
          {
            "x": 111.70824,
            "y": 158.2964
          },
          {
            "x": 96.44703,
            "y": 158.49106
          },
          {
            "x": 111.8587,
            "y": 164.61029
          }
        ]
      },
      "nose_contour": {
        "point": [
          {
            "x": 100.12734,
            "y": 103.06376
          },
          {
            "x": 99.64418,
            "y": 121.0322
          },
          {
            "x": 92.39153,
            "y": 134.87288
          },
          {
            "x": 95.70406,
            "y": 140.70796
          },
          {
            "x": 113.04284,
            "y": 143.04053
          },
          {
            "x": 129.63658,
            "y": 138.64207
          },
          {
            "x": 131.6913,
            "y": 131.54257
          },
          {
            "x": 122.73644,
            "y": 119.520386
          },
          {
            "x": 119.106,
            "y": 102.450005
          },
          {
            "x": 102.1847,
            "y": 138.2676
          },
          {
            "x": 122.21693,
            "y": 137.64107
          },
          {
            "x": 112.65759,
            "y": 131.8112
          }
        ]
      }
    }
    }
  ]
}

状态码:400

失败响应样例
{
  "error_code": "FRS.0019",
  "error_msg": "The service has not been subscribed."
}

状态码

状态码请参见状态码

错误码

错误码请参见错误码

分享:

    相关文档

    相关产品

close