参数说明 表1 结构格式说明表 名称 类型 说明 age Integer 年龄。 dress List of strings 包含glass和hat两个属性结果。 glass String 是否戴眼镜： yes：戴眼镜 none：未戴眼镜 unknown：未知 hat String 是否戴帽子： yes：戴帽子 none：未戴帽子 unknown：未知 mask String 是否戴口罩： yes：戴口罩 none：未戴口罩 unknown：未知 hair String 发型： long：长发 short：短发 unknown：未知 beard String 胡须： yes：有胡须 none：无胡须 unknown：未知 phototype String 图片类型： idcard：证件照 monitor：摄像头监控 internet photo：网络图片 smile String 笑脸。 quality FaceQuality 图片中人脸的遮挡度、模糊度、光照强度、姿态角度。 expression FaceExpression 人脸表情，包括中性、高兴、害怕、惊讶、伤心、生气、厌恶。 face_angle Integer 人脸图片旋转角（顺时针偏转角度），支持0°、90°、180°和270°图片旋转。 dress List of strings 包含glass和hat两个属性结果。 glass String 是否戴眼镜： yes：戴眼镜 dark：戴墨镜 none：未戴眼镜 unknown：未知 hat String 是否戴帽子： yes：戴帽子 none：未戴帽子 unknown：未知 headpose List of doubles 人脸轮廓坐标值。 pitch_angle Double 围绕X轴旋转，俯仰角，范围[-180,180]。 roll_angle Double 围绕Z轴旋转，翻滚角，范围[-180,180]。 yaw_angle Double 围绕Y轴旋转，偏航角，范围[-180,180]。

参数说明 表1 结构格式说明表 名称 类型 说明 nose_contour List [Point] 鼻子轮廓，Point为轮廓坐标值。 mouth_contour List [Point] 嘴巴轮廓，Point为轮廓坐标值。 eyebrow_contour List [Point] 眉毛轮廓，Point为轮廓坐标值。 eyes_contour List [Point] 眼睛轮廓，Point为轮廓坐标值。 face_contour List [Point] 人脸轮廓，Point为轮廓坐标值。

语法逻辑 "external_fields"以JSON形式定义，名称和类型对应。 Request Body:{ "face_set_name": "test", "face_set_capacity": "100000", "external_fields": { "location": { "type": "long" }, "timestamp": { "type": "integer" }, "male": { "type": "boolean" }, "title": { "type": "string" }, "weight": { "type": "double" }, "score": { "type": "float" } }}

申请步骤 登录 人脸识别 管理控制台。 根据业务需求，选择服务部署区域，开通所需服务（例如：人脸检测），单击右侧的“开通服务”。 香港、曼谷区域API也可以使用中国站账号进行开通；如您需要使用国际站账号开通香港、曼谷区域API，请联系客服获取开通支持。 图1 开通服务 由于应用可能需要使用 对象存储服务 （OBS）中的数据， 人脸识别服务 需要您授权可以操作对象存储服务。单击左侧“委托授权”，完成OBS授权，已授权过的服务，该页面提示“已授权”。 OBS授权时，如果提示委托已达上限，则需要您登录到 统一身份认证 服务，对委托进行删除或创建新的委托。 服务状态显示“已开通”时，即可调用服务的API。 图2 服务授权

数据类型 支持String，Integer，Float，Double，Boolean，Long。 external_image_id，bounding_box，similarity，face_id，create_time，vector，_id，_all，_source为内置字段，自定义字段避免使用。 自定义字段总个数不能超过10个，key的长度范围为[1,36]，可以由数字、字母、下划线和中划线组成。 String类型的value长度范围为[1,256]，可以由数字、字母、下划线和中划线组成。 字段重复定义会被覆盖。 不支持数值类型添加后缀的输入方式，如1.0f，100L，1.0d等。

sort语法 json array形式，排序只支持数值类型，字段重复定义会被覆盖。 例1：单个排序字段 "sort":[ { "location": "desc" }] 例2：多个排序字段 "sort": [ { "timestamp": "desc" }, { "rowkey": "asc" }] 父主题： 公共数据结构

终端节点 终端节点（Endpoint）即调用API的请求地址，不同服务不同区域的终端节点不同，您可以从地区和终端节点中查询所有服务的终端节点。 人脸识别服务的终端节点如表1所示，请您根据业务需要选择对应区域的终端节点。 表1 人脸识别服务终端节点 区 域名 称 区域 终端节点（Endpoint） 协议类型 部署的服务 华北-北京四 cn-north-4 face.cn-north-4.myhuaweicloud.com HTTPS 人脸检测，人脸比对，人脸搜索，静默活体检测，动作活体检测 华东-上海一 cn-east-3 face.cn-east-3.myhuaweicloud.com HTTPS 人脸检测，人脸比对，人脸搜索 华南-广州 cn-south-1 face.cn-south-1.myhuaweicloud.com HTTPS 人脸检测，人脸比对，人脸搜索，动作活体检测 中国-香港 ap-southeast-1 face.ap-southeast-1.myhuaweicloud.com HTTPS 人脸检测、人脸比对、人脸搜索 亚太-曼谷 ap-southeast-2 face.ap-southeast-2.myhuaweicloud.com HTTPS 人脸检测、人脸比对、人脸搜索 父主题： 使用前必读

人脸检测/比对/搜索 人脸比对输入的两张图片总大小小于8MB。 图片大小小于8MB，由于图片过大会导致图片在网络传输过程中耗时较长，建议小于1MB。 图片分辨率小于4096*4096，图片中人脸像素大于80*80，建议120*120以上。 为保证识别效果，人脸图片建议要求如下： 光照大于200lux、无反光强光阴影现象。 人脸无遮挡、整体清晰无拖尾抖动等运动模糊。 侧脸不超过30°、俯仰角小于15°、偏转角小于15°、图片中人脸保持竖置正脸。

动作活体检测 目前支持检测视频文件，或视频的Base64编码，不支持直接检测视频流，需要用户客户端自己获取视频流并保存成文件，然后调用活体检测接口。 视频文件大小不超过8MB，建议客户端压缩到200KB~2MB。 限制视频时长1～15秒。 建议帧率10fps～30fps。 封装格式：mp4、avi、flv、webm、asf、mov。 视频编码格式：h261、h263、h264、hevc、vc1、vp8、vp9、wmv3。

响应消息体 响应消息体通常以结构化格式返回，与响应消息头中Content-type对应，传递除响应消息头之外的内容。 对于人脸检测接口，返回如下消息体。 { "faces": [ { "bounding_box": { "width": 174, "top_left_y": 37, "top_left_x": 22, "height": 174 }, "attributes": { "age": 35, "quality": { "total_score": 0.5869140625, "blur": 0.385498046875, "pose": 0.3349609375, "occlusion": 0.392333984375, "illumination": 0.3408203125 }, "expression": { "type": "happy", "probability": 0.74 } } } ]} 当接口调用出错时，会返回错误码及错误信息说明，错误响应的Body体格式如下所示。 { "error_code": "FRS.0019", "error_msg": "The service has not been subscribed."} 其中，error_code表示错误码，error_msg表示错误描述信息，具体请参见错误码。

参数说明 表1 结构格式说明表 名称 类型 说明 bounding_box BoundingBox object 人脸在图像中的位置。 BoundingBox结构见BoundingBox。 face_id String 人脸ID，由系统内部生成的唯一ID。 external_image_id String 人脸所在的外部图片ID。 similarity Double 人脸搜索时用于被检索的相似度。 external_fields Json 用户添加的额外自定义字段。

响应消息头 对应请求消息头，响应同样也有消息头，如“Content-type”。 表1 公共响应消息头 消息头名称 说明 是否必选 Content-Type 用于指明发送给接收者的实体正文的媒体类型。 类型：字符串。 默认值：application/json; charset=UTF-8 是 X-request-id 此字段携带请求ID号，以便任务跟踪。 类型：字符串。request_id-timestamp-hostname（request_id在服务器端生成UUID， timestamp为当前时间戳，hostname为处理当前接口的服务器名称）。 默认值：无。 否 X-ratelimit 此字段携带总计流控请求数。 类型：整型。 默认值：无。 否 X-ratelimit-used 此字段携带剩下请求数。 类型：整型。 默认值：无。 否 X-ratelimit-window 此字段携带流控单位。 类型：字符串。单位按照分钟、小时、天。 默认值：小时。 否

参数说明 表1 结构格式说明表 名称 类型 说明 alive Boolean 是否是活体。 picture String 检测出最大人脸的图片base64。 actions List 动作列表。详细参数请参见表 字段要素说明。 表2 actions字段要素说明 名称 类型 说明 action Integer 动作编号，取值范围：[1,2,3,4]，其中： 1：左摇头 2：右摇头 3：点头 4：嘴部动作 confidence Double 系统对检测对象是否为活体的判定置信程度，取值范围为0到1。置信度越高，表示系统越确定检测对象是一个真实的活体。可结合alive参数进行判断，alive返回true表示为活体。

状态码 表1 状态码 状态码 编码 说明 100 Continue 继续请求。 这个临时响应用来通知客户端，它的部分请求已经被服务器接收，且仍未被拒绝。 101 Switching Protocols 切换协议。只能切换到更高级的协议。 例如，切换到HTTP的新版本协议。 200 OK 服务器已成功处理了请求。 201 Created 创建类的请求完全成功。 202 Accepted 已经接受请求，但未处理完成。 203 Non-Authoritative Information 非授权信息，请求成功。 204 NoContent 请求完全成功，同时HTTP响应不包含响应体。 在响应OPTIONS方法的HTTP请求时返回此状态码。 205 Reset Content 重置内容，服务器处理成功。 206 Partial Content 服务器成功处理了部分GET请求。 300 Multiple Choices 多种选择。请求的资源可包括多个位置，相应可返回一个资源特征与地址的列表用于用户终端（例如：浏览器）选择。 301 Moved Permanently 永久移动，请求的资源已被永久的移动到新的URI，返回信息会包括新的URI。 302 Found 资源被临时移动。 303 See Other 查看其它地址。 使用GET和POST请求查看。 304 Not Modified 所请求的资源未修改，服务器返回此状态码时，不会返回任何资源。 305 Use Proxy 所请求的资源必须通过代理访问。 306 Unused 已经被废弃的HTTP状态码。 400 BadRequest 非法请求。 建议直接修改该请求，不要重试该请求。 401 Unauthorized 在客户端提供认证信息后，返回该状态码，表明服务端指出客户端所提供的认证信息不正确或非法。 402 Payment Required 保留请求。 403 Forbidden 请求被拒绝访问。 返回该状态码，表明请求能够到达服务端，且服务端能够理解用户请求，但是拒绝做更多的事情，因为该请求被设置为拒绝访问，建议直接修改该请求，不要重试该请求。 404 NotFound 所请求的资源不存在。 建议直接修改该请求，不要重试该请求。 405 MethodNotAllowed 请求中带有该资源不支持的方法。 建议直接修改该请求，不要重试该请求。 406 Not Acceptable 服务器无法根据客户端请求的内容特性完成请求。 407 Proxy Authentication Required 请求要求代理的身份认证，与401类似，但请求者应当使用代理进行授权。 408 Request Time-out 服务器等候请求时发生超时。 客户端可以随时再次提交该请求而无需进行任何更改。 409 Conflict 服务器在完成请求时发生冲突。 返回该状态码，表明客户端尝试创建的资源已经存在，或者由于冲突请求的更新操作不能被完成。 410 Gone 客户端请求的资源已经不存在。 返回该状态码，表明请求的资源已被永久删除。 411 Length Required 服务器无法处理客户端发送的不带Content-Length的请求信息。 412 Precondition Failed 未满足前提条件，服务器未满足请求者在请求中设置的其中一个前提条件。 413 Request Entity Too Large 由于请求的实体过大，服务器无法处理，因此拒绝请求。为防止客户端的连续请求，服务器可能会关闭连接。如果只是服务器暂时无法处理，则会包含一个Retry-After的响应信息。 414 Request-URI Too Large 请求的URI过长（URI通常为网址），服务器无法处理。 415 Unsupported Media Type 服务器无法处理请求附带的媒体格式。 416 Requested range not satisfiable 客户端请求的范围无效。 417 Expectation Failed 服务器无法满足Expect的请求头信息。 422 UnprocessableEntity 请求格式正确，但是由于含有语义错误，无法响应。 429 TooManyRequests 表明请求超出了客户端访问频率的限制或者服务端接收到多于它能处理的请求。建议客户端读取相应的Retry-After首部，然后等待该首部指出的时间后再重试。 500 InternalServerError 表明服务端能被请求访问到，但是不能理解用户的请求。 501 Not Implemented 服务器不支持请求的功能，无法完成请求。 502 Bad Gateway 充当网关或代理的服务器，从远端服务器接收到了一个无效的请求。 503 ServiceUnavailable 被请求的服务无效。 建议直接修改该请求，不要重试该请求。 504 ServerTimeout 请求在给定的时间内无法完成。客户端仅在为请求指定超时（Timeout）参数时会得到该响应。 505 HTTP Version not supported 服务器不支持请求的HTTP协议的版本，无法完成处理。 父主题： 附录

错误码 调用API出错后，将不会返回结果数据。调用方可根据每个API对应的错误码来定位错误原因。当调用出错时，HTTP请求返回一个4xx或5xx的HTTP状态码。返回的消息体中是具体的错误代码及错误信息。在调用方找不到错误原因时，可以联系客服，并提供错误码，以便我们尽快帮您解决问题。 异常响应样例 { "error_code": "FRS.0202", "error_msg": " The service has been freeze." } 参数说明 参数 是否必选 类型 说明 error_code 否 String 错误码。 error_msg 否 String 错误消息。 错误码说明 错误码类别 状态码 错误码 说明 处理措施 服务类公共错误 （错误码区间：1～99） 403 FRS.0002 鉴权token失败，用户token错误或者已过期。 请参考认证鉴权章节，重新获取您的token信息，并使用获取的token来调用人脸识别服务的接口。 400 FRS.0010 缺少请求头或者请求头为空。 请参考构造请求章节，检查公共消息头是否配置。 400 FRS.0011 缺少参数。 请检查请求参数必填参数是否遗漏。 400 FRS.0012 请求参数格式不正确。 请检查参数输入的格式是否合法。 检查必填参数是否填写完整。 检查输入数据规格是否符合约束限制。 400 FRS.0013 输入的人脸图片尺寸过大或过小。 请上传符合规范的人脸图片。 人脸图片分辨率需小于4096*4096，图片中人脸像素大于80*80，建议120*120以上。 400 FRS.0014 输入的不是json格式。 请检查body体的json格式是否合法。 400 FRS.0015 图片base64解析错误。 使用Base64图像数据时，注意编码格式要与API文档中的请求示例保持一致。图片转base64方法可参考如何获取图片的base64编码 使用本地图片文件时，请检查文件是否为图片，且图片类型满足约束。 使用图片URL地址时，请检查URL是否为OBS地址，且地址为图片文件的路径。 400 FRS.0016 上传的文件格式不支持。 请参考约束与限制章节，上传支持识别的文件格式。 400 FRS.0017 上传的body体超出允许的范围。 上传的body体超出允许的范围，请检查图片和分辨率的大小是否在允许的范围内。 请参考约束与限制章节，使用符合规定的图片。 500 FRS.0018 服务内部错误。 请联系客服提供支持。 400 FRS.0019 服务未开通。 请登录人脸识别管理控制台，根据业务需求，选择需要开通的服务。 400 FRS.0020 子服务未开通。 请登录人脸识别管理控制台，根据业务需求，选择需要开通的子服务。 如已开通服务，请检查开通服务的区域（或账号）与调用服务的区域（或账号）是否一致；若一致请检查API的URL是否拼写正确。 400 FRS.0021 无效OBS的url。 请参考请求样例，检查OBS的url是否正确。 400 FRS.0023 OBS上的文件大小超出范围。 请参考约束与限制章节，检查OBS中文件的大小是否符合接口要求 400 FRS.0024 OBS上的文件不存在。 请检查OBS上的文件是否存在。 400 FRS.0027 OBS未授权。 请登录人脸识别管理控制台，点击右上角“服务授权”，完成OBS授权。 403 FRS.0028 Project ID跟Token不匹配。 请检查 获取Token 的Project ID是否和请求url上的Project ID一致。 400 FRS.0032 排序字段以及类型不支持，只支持数字类型。 排序字段以及类型不支持，只支持数字类型。请参考sort语法章节查看示例。 429 FRS.0033 当前请求数太多，超过流控限制。 建议控制请求策略或者进行重试，建议扩容以增加QPS配额。 400 FRS.0035 下载地址不合法。 请参考请求样例，检查OBS的url是否正确。 400 FRS.0036 从url获取文件失败。 请使用OBS提供的url上传图片，并检查url是否正确。 服务管理错误 （错误码区间：201～300） 400 FRS.0201 此用户已经注册了。 此用户已经注册了。 400 FRS.0202 服务已经被冻结。 请联系客服提供支持。 400 FRS.0203 更新用户信息失败。 请检查输入的用户信息。 人脸库资源错误 （错误码区间：301～400） 400 FRS.0301 无法创建已经存在的人脸库。 请检查输入的人脸库名称，创建的人脸库已存在，请更换人脸库名称后重新创建。 400 FRS.0302 人脸库不存在。 请检查输入的人脸库是否存在。 400 FRS.0304 未检测到人脸，无法搜索。 请参考约束与限制章节，上传符合规范的人脸图片。 400 FRS.0305 超过最大的人脸库数量，无法创建新的人脸库。 请检查人脸库数量是否超出限制联系客服提供支持。 403 FRS.0306 超过人脸库容量限制，无法增加更多的人脸。 请新增人脸库，重新添加人脸到新的人脸库中。 人脸资源错误 （错误码区间：401～500） 400 FRS.0401 找不到对应类型的值，无法删除。 请参考人脸资源管理接口说明。 400 FRS.0402 输入的字段不存在。 请参考人脸资源管理接口说明。 400 FRS.0403 Face ID不存在。 请检查输入的Face ID是否存在。 400 FRS.0404 未检测到人脸，无法添加。 请参考约束与限制章节，上传符合规范的人脸图片。 400 FRS.0405 未定义的自定义字段，无法添加。 请检查添加的自定义字段是否存在，创建自定义字段后再进行添加。 400 FRS.0406 导入的数据类型与定义不匹配。 请检查导入的数据类型是否与定义的数据类型一致。 400 FRS.0407 批量删除未找到匹配数据。 请检查需要删除的数据信息是否存在。 人脸比对错误 （错误码区间：501～600） 400 FRS.0501 照片未检测到人脸。 请参考约束与限制章节，上传符合规范的人脸图片。 人脸搜索错误码 （错误码区间：29～31） 400 FRS.0029 过滤格式错误。 请参考人脸搜索请求参数章节，检查输入格式是否合法。 400 FRS.0030 返回字段未定义。 请参考人脸搜索请求参数章节，检查return_fields是否定义。 400 FRS.0031 排序字段不在返回字段中。 请参考人脸搜素请求参数章节，检查排序字段是否定义。 活体检测错误 （错误码区间：701～800） 400 FRS.0701 视频解析错误。 请检查视频是否有损坏。 400 FRS.0702 不支持的动作。 请参考动作活体检测的请求参数，检查输入的动作是否存在。 400 FRS.0703 Action time非法。 请检查输入是否合法。 400 FRS.0704 传入的action数量超过10个。 传入的action数量超过10个。 400 FRS.0705 匹配模式不支持。 请参考约束与限制章节，检查输入是否合法。 400 FRS.0706 视频时长不支持，限制[1-15]秒。 视频时长超过限制[1-15]秒，请使用符合时长要求的视频。 400 FRS.0707 照片未检测到人脸。 请参考约束与限制章节，检查照片中是否有人脸或者人脸是否满足约束限制。 400 FRS.0708 检查输入的人脸图片质量是否满足要求。 请参考约束与限制章节，检查输入的人脸图片质量是否满足要求。 400 FRS.0751 视频数据解析失败。 请参考约束与限制章节，检查输入的视频是否满足要求。 400 FRS.0709 检查输入的人脸图片包含多张人脸。 请检查输入的人脸图片是否包含多张人脸，静默活体检测仅支持单人脸照片。 网关错误码 错误码类别 状态码 错误码 说明 处理措施 网关类错误 （错误码区间：1～400） 404 APIG.0101 访问的API不存在或尚未在环境中发布。 请检查API的URL是否拼写正确，例如，URL中是否缺少project_id。 检查URI中的区域信息是否和调用服务配置的区域是否对应。 HTTP请求方法（POST，GET等）是否正确。 具体的URI信息请在各接口的API页面查看。 413/504 APIG.0201 请求体超过范围或者后端超时。 请检查请求的大小是否合法，请联系客服检查后端服务是否运行正常。 401 APIG.0301 IAM 身份验证信息不正确： decrypt token fail：token解析失败。 token expires：token过期。 verify aksk signature fail：AK/SK认证失败。 token解析失败，请检查获取token的方法，请求体信息是否填写正确，token是否正确；检查获取token的环境与调用的环境是否一致。 token超时（token expires） ，请重新获取token，使用不过期的token。 请检查AK/SK是否正确（AK对应的SK错误，不匹配；AK/SK中多填了空格）。 AK/SK频繁出现鉴权出错，连续错误5次以上，被锁定5分钟（5分钟内，则一直认为其是异常的鉴权请求），5分钟后解锁重新认证。 检查账号权限，是否欠费，被冻结等。 401 APIG.0307 Token需要更新 Token有效期为24小时，请使用重新获取Token调用API。 检查接口URL中的终端节点是否填写正确。部署在不同区域间的服务，不可以跨区域调用。如果调用了不同区域的接口，导致判断为Token失效，显示APIG.0307错误码。 当您调用API时，如果遇到“APIGW”开头的错误码，请参见API网关错误码进行处理。 父主题： 附录