人脸检测与分析

最近更新时间:2020-08-28 17:56:20

调用方式

请求结构

服务地址

AI开放服务API的服务接入地址为:http://kcr.api.ksyun.com

通信协议

支持通过HTTP或HTTPS协议进行请求通信。为保证您的服务安全性,请使用HTTPS协议进行通信。

请求方式

支持GET方法发送请求,注意参数需要进行urlencode。

公共参数

公共请求header

参数名 必选 类型 说明
Authorization string 必要的请求验证信息
X-Amz-Date string 当前请求的时间戳,例如:20171129T114852Z
Host string kcr.api.ksyun.com

签名参数

Region:金山云机房信息,目前仅支持cn-beijing-6

Service:固定为kcr

返回结果

接口统一返回json格式数据,满足以下格式:

{
    "header":{
      "err_no":200,
      "err_msg":"success"
    },
    "cost":0.11,
    "request_id": "d679e27b-9f1b-44bf-b134-49a6d9f0adff",
    "request_time": 1234567890123,
    "body":{}
}

调用成功,err_no返回200,msg为success,否则返回对应错误码及错误信息。

cost为服务端耗时,单位秒。

每此请求会返回唯一的请求表示request_id,调用失败时提供request_id给金山云客服,方便定位问题。

request_time为每次请求时的服务器时间。

签名机制

[详见金山云签名机制文档]

人脸检测接口

输入:

GET参数部分

参数名 必选 类型 说明
Action=DetectFace string 固定此值
Version=2019-12-13 string API版本号,固定此值

POST请求示例

{
    "image_url":"xxxxx"
}

POST参数说明

参数 必选 类型 说明
image_url string 图片url (image_url和image_data二选一)
image_data string 图片内容的BASE64编码,不能超过1MB (image_url和image_data二选一)
need_attributes string 是否检测人体属性,默认不检测

接口返回:

{
    "header": {
        "err_no": 200,
        "err_msg": "success"
    },
    "request_id": "2216eaa9-52d2-4e0f-a690-e79b10a2c2fe",
    "cost": 0.495,
    "face_num": 2,
    "face_info": [
        {
            "attributes": {
                "headwear": {
                    "rate": 0.323924720287323,
                    "name": "未戴帽子"
                },
                "gender": {
                    "rate": 0.8240132331848145,
                    "name": "女性"
                },
                "age": {
                    "rate": 0.9495382308959961,
                    "name": "青年"
                },
                "glasses": {
                    "rate": 0.9292197823524475,
                    "name": "普通眼镜"
                },
                "mask": {
                    "rate": 0.7128473520278931,
                    "name": "戴口罩"
                },
                "race": {
                    "rate": 0.4870010614395142,
                    "name": "维族"
                }
            },
            "location": {
                "top_left_x": 0.16029005560994847,
                "top_left_y": 0.2177239403843063,
                "bottom_right_y": 0.3159262808263047,
                "bottom_right_x": 0.20467229934001807,
                "rate": 0.9999997615814209
            }
        }
    ]
}

接口输出字段解释:

字段 类型 是否必须 说明
header.err_no int 错误码,请求成功为200
header.err_msg string 错误信息,请求成功为success
request_id string 请求唯一标识
cost double 请求耗时,单位:秒
face_num int 图像中人脸个数
face_info.location object 图像中人脸位置信息
face_info.location.top_left_x double 人脸左上坐标的x值
face_info.location.top_left_y double 人脸左上坐标的y值
face_info.location.bottom_right_x double 人脸右下坐标的x值
face_info.location.bottom_right_y double 人脸右下坐标的y值
face_info.location.rate double 人脸置信度
face_info.attributes object 人脸属性信息
face_info.attributes.gender object 人脸性别
face_info.attributes.gender.name string 男性、女性
face_info.attributes.gender.rate double 置信度
face_info.attributes.age object 人脸年龄
face_info.attributes.age.name string 儿童、少年、青年、中年、老年
face_info.attributes.age.rate double 置信度
face_info.attributes.headwear object 戴帽子
face_info.attributes.headwear.name string 未戴帽子、戴头盔、戴帽子
face_info.attributes.headwear.rate double 置信度
face_info.attributes.glasses object 人脸戴眼镜
face_info.attributes.glasses.name string 普通眼镜、太阳镜、未戴眼镜
face_info.attributes.glasses.rate double 置信度
face_info.attributes.mask object 人脸戴口罩
face_info.attributes.mask.name string 戴口罩、无口罩
face_info.attributes.respirator.rate double 置信度
face_info.attributes.race object 民族
face_info.attributes.race.name string 维族、非维族
face_info.attributes.race.rate double 置信度

注:为保证图片缩放后坐标点不变,此处返回坐标值均为相对图片长宽的百分比。

签名错误码

错误代码(Code) 错误消息(Message) 状态码 说明
IncompleteSignature Date must be in ISO-8601 'basic format'. Got '%s'. See http://en.wikipedia.org/wiki/ISO_8601. 400 Date必须符合ISO_8601基本格式,参考:http://en.wikipedia.org/wiki/ISO_8601
IncompleteSignature KSC query-string parameters must include %s. Re-examine the query-string parameters. 400 查询条件中缺少签署信息,查询条件中必须包含”X-Amz-Algorithm“、”X-Amz-Credential“、”X-Amz-SignedHeaders“、”X-Amz-Date“信息
IncompleteSignature Unsupported ksc 'algorithm': %s. 400 只支持如下签名算法:AWS4-HMAC-SHA256
IncompleteSignature Authorization header requires 'Credential' parameter. Authorization=%s. 400 请求Authorization header中需要包含“Credential”参数
IncompleteSignature Credential must have exactly 5 slash-delimited elements, e.g. accesskeyid/date/region/service/aws4_request, got: %s. 400 请求Authorization header中中“Credential”至少包含5项以斜杠分隔的元素,如:keyid/date/region/service/aws4_request
IncompleteSignature Authorization header format error. 400 请求Authorization header的格式错误
IncompleteSignature Authorization header requires existence of either a 'X-Amz-Date' or a 'Date' header, Authorization=%s 400 请求中缺少“X-Amz-Date”或者“Date” header信息
IncompleteSignature Authorization header requires 'Signature' parameter. Authorization=%s 400 请求Authorization header中缺少“Signature”信息
IncompleteSignature Authorization header requires 'SignedHeaders' parameter. Authorization=%s 400 请求Authorization header中缺少“SignedHeaders”信息
MissingAuthenticationToken Request is missing 'Host' header. 403 请求header中缺少Host
MissingAuthenticationToken Request is missing Authentication Token. 403 请求header中缺少认证token
MissingAuthenticationToken %s not in Http Header. 403 %s不在Http header中
SignatureDoesNotMatch Host' must be a 'SignedHeader' in the Authorization. 403 请求的SignedHeader中必须包含Host
SignatureDoesNotMatch Credential should be scoped with a valid terminator: 'aws4_request', not: %s. 403 请求Authorization header中的“Credential”末尾必须是“aws4_request”
SignatureDoesNotMatch Credential should be scoped to a valid region, not:%s. 403 请求Authorization header中的“Credential”中的Region信息无效
SignatureDoesNotMatch Credential should be scoped to correct service: %s. 403 请求Authorization header中的“Credential”中的Service信息无效
SignatureDoesNotMatch The request signature we calculated does not match the signature you provided. 403 请求中提供的签名与实际计算结果不匹配
SignatureDoesNotMatch Signature expired:%s. 403 签名已过期
SignatureDoesNotMatch Date in Credential scope does not match YYYYMMDD from ISO-8601 version of date from HTTP. 403 请求Authorization header中的“Credential”中的Date应该是ISO8601基本格式,形如”YYYYMMDD“
InvalidClientTokenId The security token included in the request is invalid. 403 请求中提供的AccessKeyId无效

业务层级错误码

err_msg err_no 说明
未开通相应的服务 411 账号未开通服务权限
请求太频繁 510 QPS达到限制

其他说明

图片大小限制为5M,长宽像素不大于5000,图片下载时间限制为2.5s内,如果下载时间超过2.5s返回下载超时;

图片像素建议不小于256*256,太小可能会影响识别效果;

图片检测接口响应时间依赖图片的下载时间,请保证所检测图片所在的存储服务的稳定,图片建议使用金山云对象存储或者cdn做缓存等;

接口regionId仅支持cn-beijing-6;

金山云,开启您的云计算之旅

免费注册