API 文档

SDK 文档

诚邀爱技术、爱分享的你,成为文档内容共建者> HOT

功能描述

人脸检测功能为同步请求方式,您可以通过本接口检测图片中的人脸位置。该接口属于 GET 请求。

费用说明

限制说明

  • 图片支持格式:PNG、JPG、JPEG、BMP。
  • 图片大小:所下载图片经 Base64 编码后不超过5MB
  • 图片像素:JPG 格式长边像素不可超过4000,其他格式图片长边像素不可超过2000
  • 调用接口需携带签名,具体规则请参见 请求签名 文档。

请求

请求示例

GET /<ObjectKey>?ci-process=DetectFace&max-face-num=<FaceNum> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>

说明:

  • Authorization: Auth String(详情请参见 请求签名 文档)。
  • 通过子账号使用时,需要授予相关的权限,详情请参见 授权粒度详情 文档。

请求参数

参数名称 描述 类型 是否必选
ObjectKey 对象文件名,例如:folder/document.jpg。 String
ci-process 数据万象处理能力,人脸特效固定为 DetectFace。 String
max-face-num 最多处理的人脸数目。默认值为1(仅检测图片中面积最大的那张人脸),最大值为120。此参数用于控制处理待检测图片中的人脸个数,值越小,处理速度越快。 Integer

请求头

此接口仅使用公共请求头部,详情请参见 公共请求头部 文档。

请求体

该请求的请求体为空。

响应

响应头

此接口仅返回公共响应头部,详情请参见 公共响应头部 文档。

响应体

该响应体返回为 application/xml 数据,包含完整节点数据的内容展示如下:

<Response>
    <ImageWidth>616</ImageWidth>
    <ImageHeight>442</ImageHeight>
    <FaceModelVersion>3.0</FaceModelVersion>
    <RequestId>NjEzZjBlZGRfOTBmYTUwNjRfZWUx****</RequestId>
    <FaceInfos>
        <X>312</X>
        <Y>-5</Y>
        <Width>117</Width>
        <Height>173</Height>
    </FaceInfos>
</Response>

具体的数据内容如下:

节点名称(关键字) 父节点 描述 类型
Response 保存结果的容器。 Container

Response 的内容:

节点名称(关键字) 父节点 描述 类型
ImageWidth Response 请求的图片宽度。 Integer
ImageHeight Response 请求的图片高度。 Integer
FaceModelVersion Response 人脸识别所用的算法模型版本。 String
RequestId Response 唯一请求 ID,每次请求都会返回。定位问题时需要提供该次请求的 RequestId。 String
FaceInfos Response 人脸信息列表。包含人脸坐标信息。 Container

FaceInfos 节点的内容:

节点名称(关键字) 父节点 描述 类型
X FaceInfos 人脸框左上角横坐标。人脸框包含人脸五官位置并在此基础上进行一定的扩展,若人脸框超出图片范围,会导致坐标负值。 Integer
Y FaceInfos 人脸框左上角纵坐标。人脸框包含人脸五官位置并在此基础上进行一定的扩展,若人脸框超出图片范围,会导致坐标负值。 Integer
Width FaceInfos 人脸框宽度。 Integer
Height FaceInfos 人脸框高度。 Integer

错误码

以下仅列出了接口业务逻辑相关的错误码,其他错误信息请参见 错误码 文档。

错误码 描述
FailedOperation.ConflictOperation 操作冲突,请勿同时操作相同的 Person。
FailedOperation.GroupInDeletedState 当前组正处于删除状态,请等待。
FailedOperation.GroupPersonMapExist 组中已包含对应的人员 ID。
FailedOperation.GroupPersonMapNotExist 组中不包含对应的人员 ID。
FailedOperation.ImageDecodeFailed 图片解码失败。
FailedOperation.ImageDownloadError 图片下载错误。
FailedOperation.ImageFacedetectFailed 人脸检测失败。
FailedOperation.ImageResolutionExceed 图片分辨率过大。
FailedOperation.ImageResolutionTooSmall 图片短边分辨率小于64。
FailedOperation.ImageSizeExceed base64编码后的图片数据大小不超过5MB。
FailedOperation.RequestLimitExceeded 请求频率超过限制。
FailedOperation.RequestTimeout 后端服务超时。
FailedOperation.ServerError 算法服务异常,请重试。
InternalError 内部错误。
InvalidParameter.InvalidParameter 参数不合法。
InvalidParameterValue.AccountFaceNumExceed 账号脸数量超出限制。
InvalidParameterValue.FaceModelVersionIllegal 算法模型版本不合法。
InvalidParameterValue.ImageEmpty 图片为空。
InvalidParameterValue.LimitExceed 返回数量超出限制。
InvalidParameterValue.NoFaceInPhoto 图片中没有人脸。
InvalidParameterValue.UrlIllegal URL 格式不合法。
LimitExceeded.ErrorFaceNumExceed 人脸个数超过限制。
MissingParameter.ErrorParameterEmpty 必选参数为空。
ResourceUnavailable.Freeze 帐号已被冻结。
ResourceUnavailable.InArrears 帐号已欠费。
ResourceUnavailable.LowBalance 余额不足。
ResourceUnavailable.StopUsing 帐号已停服。
ResourceUnavailable.UnknownStatus 计费状态未知。
ResourcesSoldOut.ChargeStatusException 计费状态异常。
UnsupportedOperation.UnknowMethod 未知方法名。

实际案例

请求

GET /test.jpg?max-face-num=1&ci-process=detect-face HTTP/1.1
Authorization: q-sign-algorithm=sha1&q-ak=AKIDZfbOAo7cllgPvF9cXFrJD0a1ICvR****&q-sign-time=1497530202;1497610202&q-key-time=1497530202;1497610202&q-header-list=&q-url-param-list=&q-signature=28e9a4986df11bed0255e97ff90500557e0e****
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com

响应

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 414641
Date: Thu, 15 Jun 2017 12:37:29 GMT
Server: tencent-image
x-ci-request-id: NTk0MjdmODlfMjQ4OGY3XzYzYzhf****

<Response>
    <ImageWidth>616</ImageWidth>
    <ImageHeight>442</ImageHeight>
    <FaceModelVersion>3.0</FaceModelVersion>
    <RequestId>NjEzZjBlZGRfOTBmYTUwNjRfZWUxXzE=</RequestId>
    <FaceInfos>
        <X>312</X>
        <Y>-5</Y>
        <Width>117</Width>
        <Height>173</Height>
    </FaceInfos>
    <FaceInfos>
        <X>600</X>
        <Y>-5</Y>
        <Width>117</Width>
        <Height>173</Height>
    </FaceInfos>
</Response>

目录