响应参数 状态码：200 表4 响应Body参数 参数 参数类型 描述 face_set_id String 人脸库ID。 调用失败时无此字段。 face_set_name String 人脸库名称。 调用失败时无此字段。 faces Array of FaceSetFace objects 人脸库当中的人脸结构，详见FaceSetFace。 调用失败时无此字段。 表5 FaceSetFace 参数 参数类型 描述 bounding_box BoundingBox object 人脸在图像中的位置。 BoundingBox结构见BoundingBox。 external_fields Object 用户添加的额外字段。 external_image_id String 人脸所在的外部图片ID。 face_id String 人脸ID，由系统内部生成的唯一ID。 表6 BoundingBox 参数 参数类型 描述 width Integer 矩形框宽度。 top_left_y Integer 矩形框左上角纵坐标。 top_left_x Integer 矩形框左上角横坐标。 height Integer 矩形框高度。 状态码： 400 表7 响应Body参数 参数 参数类型 描述 error_code String 调用失败时的错误码，具体请参考错误码。 调用成功时无此字段。 error_msg String 调用失败时的错误信息。 调用成功时无此字段。

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

请求参数 表2 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 是 String 用户Token。 用于获取操作API的权限。获取方法请参见认证鉴权。 Content-Type 是 String 发送的实体的MIME类型，参数值为“application/json”。 Enterprise-Project-Id 否 String 企业项目ID。FRS支持通过企业项目管理（EPS）对不同用户组和用户的资源使用，进行分账，当前仅支持按需计费模式。 获取方法：进入“企业项目管理”页面，单击企业项目名称，在企业项目详情页获取Enterprise-Project-Id（企业项目ID）。 说明： 创建企业项目后，在传参时，有以下三类场景。 携带正确的ID，正常使用FRS服务，账单的企业项目会被分类到企业ID对应的企业项目中。 携带格式正确但不存在的ID，正常使用FRS服务，账单的企业项目会显示对应不存在的企业项目ID。 不携带ID或格式错误ID（包含特殊字符等），正常使用FRS服务，账单的企业项目会被分类到"default"中。 表3 请求Body参数 参数名 参数类型 是否必选 说明 image_url String 与image_file、image_base64三选一 图片的URL路径，目前仅支持华为云上OBS的URL，使用时只需保证FRS有权限读取该OBS桶的数据。开通读取权限的操作请参见服务授权。 image_file File 与image_url、image_base64三选一 本地图片文件，图片不能超过8MB，建议小于1MB。上传文件时，请求格式为multipart。 image_base64 String 与image_file、image_url三选一 图像数据，Base64编码，要求： Base64编码后大小不超过8MB，建议小于1MB。 图片为JPG/JPEG/BMP/PNG格式。 external_image_id String 否 用户指定的图片外部ID，与当前图像绑定。用户没提供，系统会生成一个。 该ID长度范围为1～36位，可以包含字母、数字、中划线或者下划线，不包含其他的特殊字符。 external_fields Object 否 根据用户自定义数据类型，填入相应的数值。 需在创建人脸库时定义external_fields字段，才可以在添加人脸时使用该字段，参考自定义字段。 single boolean 否 是否将图片中的最大人脸添加至人脸库。可选值包括： true：传入的单张图片中如果包含多张人脸，则只将最大人脸添加到人脸库中。 false：默认为false。传入的单张图片中如果包含多张人脸，则将所有人脸添加至人脸库中。

响应参数 状态码：200 表4 响应Body参数 参数 参数类型 描述 video-result video-result object 活体检测结果，video-result数据结构请见VideoDetectResult。 调用失败时无此字段。 warning-list Array of WarningList objects 警告信息列表，warning-list数据结构请见WarningList。 调用失败时无此字段。 表5 video-result 参数 参数类型 描述 alive Boolean 是否是活体。 actions Array of ActionsList objects 动作列表。 picture String 返回检测出最大人脸图片的base64编码。 其中，图片格式为jpg，分辨率与视频分辨率相等。 表6 ActionsList 参数 参数类型 描述 confidence Double 置信度，取值范围0～1。 action Integer 动作编号，取值范围：[1,2,3,4,5]. 1：左摇头 2：右摇头 3：点头 4：嘴部动作 5：眨眼 表7 WarningList 参数 参数类型 描述 warningCode Integer 警告ID。 warningMsg String 告警消息。 状态码： 400 表8 响应Body参数 参数 参数类型 描述 error_code String 调用失败时的错误码，具体请参考错误码。 调用成功时无此字段。 error_msg String 调用失败时的错误信息。 调用成功时无此字段。

功能介绍 动作活体检测是通过判断视频中的人物动作与传入动作列表是否一致来识别视频中人物是否为活体，进行实人检测。如果有多张人脸出现，则选取最大的人脸进行判定。新老用户均可用该接口。 前提条件： 请确保您已开通 人脸识别服务 ，具体操作方法请参见申请服务。 约束限制： 目前支持检测视频文件，或视频的Base64编码，不支持直接检测视频流，需要用户客户端自己获取视频流并保存成文件，然后调用活体检测接口。 视频文件大小不超过8MB，建议客户端压缩到200KB~2MB。 application/json请求的body中，请使用标准Json格式。 Base64编码中请勿使用回车换行。 系统不保存用户视频。 具体的约束限制信息请参见约束与限制章节。 建议： 建议帧率10fps～30fps。 视频文件的大小建议客户端压缩到200KB~2MB。

请求参数 表2 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 是 String 用户Token。 用于获取操作API的权限。获取方法请参见认证鉴权。 Content-Type 是 String 发送的实体的MIME类型，参数值为“application/json”。 Enterprise-Project-Id 否 String 企业项目ID。FRS支持通过企业项目管理（EPS）对不同用户组和用户的资源使用，进行分账，当前仅支持按需计费模式。 获取方法：进入“企业项目管理”页面，单击企业项目名称，在企业项目详情页获取Enterprise-Project-Id（企业项目ID）。 说明： 创建企业项目后，在传参时，有以下三类场景。 携带正确的ID，正常使用FRS服务，账单归到企业ID对应的企业项目中。 携带错误的ID，正常使用FRS服务，账单的企业项目会被分类为“未归集”。 不携带ID，正常使用FRS服务，账单的企业项目会被分类为“default”。 表3 请求Body参数 参数名 是否必选 参数类型 说明 video_url 与video_file、video_base64三选一 String 视频的URL路径，目前仅支持华为云上OBS的URL，使用时只需保证FRS有权限读取该OBS桶的数据。开通读取权限的操作请参见服务授权。 视频要求： 视频Base64编码后大小不超过8MB，建议客户端压缩到200KB~2MB。 限制视频时长1～15秒。 建议帧率10fps～30fps。 封装格式：mp4、avi、flv、webm、asf、mov。 视频编码格式： h261、h263、h264、hevc、vc1、vp8、vp9、wmv3。 video_file 与video_url、video_base64三选一 File 本地视频文件。上传文件时，请求格式为multipart。视频要求： 视频文件大小不超过8MB，建议客户端压缩到200KB~2MB。 限制视频时长1～15秒。 建议帧率10fps～30fps。 封装格式：mp4、avi、flv、webm、asf、mov。 视频编码格式： h261、h263、h264、hevc、vc1、vp8、vp9、wmv3。 video_base64 与video_file、video_url三选一 String 视频数据，Base64编码，要求： Base64编码后大小不超过8MB，建议客户端压缩到200KB~2MB。 限制视频时长1～15秒。 建议帧率10fps～30fps。 封装格式：mp4、avi、flv、webm、asf、mov。 视频编码格式： h261、h263、h264、hevc、vc1、vp8、vp9、wmv3。 actions 是 String 动作代码顺序列表，英文逗号（,）分隔。建议单动作，目前支持的动作有： 1：左摇头 2：右摇头 3：点头 4：嘴部动作 5：眨眼 说明： 仅当actions的传参顺序和视频中的动作顺序一致时返回true。例如，视频中人物动作顺序为点头、嘴部动作，传参顺序需为3,4。 左右摇头动作建议角度15-30度，嘴部动作建议张嘴距离大于3厘米。 action_time 否 String 该参数为动作时间数组拼接的字符串，数组的长度和actions的数量一致，每一项代表了对应次序动作的起始时间和结束时间，单位为距视频开始的毫秒数。 nod_threshold 否 double 该参数为点头动作幅度的判断门限,取值范围:[1,90],默认为10,单位为度。该值设置越大,则越难判断为点头。

参数说明 表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为轮廓坐标值。

参数说明 表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]。

数据类型 支持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" }] 父主题： 公共数据结构

语法逻辑 "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 服务授权

终端节点 终端节点（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。