图像理解

最近更新时间:2020-07-09 15:05:03

金山云内容理解图像API文档

目录

调用方式

请求结构

服务地址

金山云图像识别API的服务接入地址为:http://kir.api.ksyun.com

通信协议

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

请求方式

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

公共参数

公共请求header

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

签名参数

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

Service:固定为kir

返回结果

接口统一返回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为每次请求时的服务器时间

签名机制

详见金山云签名机制文档

Special识别接口

输入:

GET参数部分

参数名 必选 类型 说明
Action=ClassifyImage string 固定此值
Version=2017-11-07 string API版本号,固定此值

POST请求示例

{
    "business":["special"],
    "image_urls":[
        "http://xxx.jpg",
        "http://xxx.jpg",
        "....."
    ],
    "image_data":"base64 for image data"
}

POST参数说明

参数 必选 类型 说明
business array 业务类型(可同时识别多类型)
special特殊场景识别
image_urls array 图片url列表(最多10张图片)
image_data string 图片内容的BASE64编码

接口返回:

{
    "header": {
        "err_no": 200,
        "err_msg": "success"
    },
    "cost": 0.11,
    "request_id": "d679e27b-9f1b-44bf-b134-49a6d9f0adff",
    "request_time": 1234567890123,
    "body": [
        {
            "err_no": 400,//仅图片格式出现错误有此信息
            "err_msg": "图片格式错误",//仅图片格式出现错误有此信息
            "data_id": "3c029d154350f6e94a8be2398b296fd4",
            "image_url": "http://ip/xxx.jpg",
            "results": [
                {
                    "err_no": 500,//仅模型出现错误有此信息
                    "err_msg": "内部错误",//仅模型出现错误有此信息
                    "business": "special",
                    "label": "2",
                    "label_desc": "CCTV",
                    "rate": 0.99,
                    "review": 0,
                    "suggest": "normal"
                }
            ]
        }
    ]
}

接口输出字段解释:

字段 类型 是否必须 说明
business string 对应请求中的参数值
label string 分类标签ID
label_desc string 分类标签(string类型)
0其他,2:CCTV,3:CNN,4:BBC
image_url string 对应请求中的地址
data_id string 唯一标识该图片
suggest string confirm_reject:cnn,bbc,新唐人,美国之音标签下,确认状态;normal:其它标签状态

通用标签识别接口

输入:

GET参数部分

参数名 必选 类型 说明
Action=ClassifyImage string 固定此值
Version=2017-11-07 string API版本号,固定此值

POST请求示例

{
    "business":["general"],
   "image_urls":[
        "http://xxx.jpg",
       "http://xxx.jpg",
       "....."
    ],
    "image_data":"base64 for image data"
}

POST参数说明

参数 必选 类型 说明
business array 业务类型(可同时识别多类型)
general通用标签场景识别
image_urls array 图片url列表(最多10张图片)
image_data string 图片内容的BASE64编码

接口返回:

{
    "header": {
        "err_no": 200,
        "err_msg": "success"
    },
    "cost": 0.11,
    "request_id": "d679e27b-9f1b-44bf-b134-49a6d9f0adff",
    "request_time": 1234567890123,
    "body": [
        {
            "err_no": 400,//仅图片格式出现错误有此信息
            "err_msg": "图片格式错误",//仅图片格式出现错误有此信息
            "data_id": "3c029d154350f6e94a8be2398b296fd4",
            "image_url": "http://ip/xxx.jpg",
            "results": [
                {
                    "err_no": 500,//仅模型出现错误有此信息
                    "err_msg": "内部错误",//仅模型出现错误有此信息
                    "business": "general",
                    "label": "1",
                    "label_desc": "人体",
                    "rate": 0.9896137118339539,
                    "review": 0,
                    "task_id": "f9315ef8-8fbd-11e8-bce7-107b4445769f",
                    "label_details": [
                        {
                            "label": "1",
                            "label_desc":"人体",
                            "rate": 0.9896137118339539
                        },
                        {
                            "label": "5",
                            "label_desc": "穿着配饰",
                            "rate": 0.9821652770042419
                        },
                        {
                            "label":"20",
                            "label_desc": "体育建筑",
                            "rate": 0.5532062649726868
                        }
                    ]
                }
            ]
        }
    ]
}

接口输出字段解释:

字段 类型 是否必须 说明
business string 对应请求中的参数值
label string 置信度最高标签ID(string类型)
详见通用标签表
label_desc string 置信度最高标签结果
详见通用标签列表
rate double 标签置信度 [0, 1.0],值越大置信度越高
label_details object 通用标签详情(object类型)
包含所有匹配标签与其置信度
review int 结果是否需要人工复审
image_url string 对应请求中的地址
data_id string 唯一标识该图片
task_id string 标示该次检测任务

通用标签表:

通用标签ID 通用标签
1 人体
2 交通工具
3 基础设施
4 动物
5 穿着配饰
6 运动装备
7 餐具
8 食物
9 家具
10 植物
11 电子产品
12 家用电器
13 工具装饰
14 公共建筑
15 商业建筑
16 居住建筑
17 文教建筑
18 自然景观
19 体育建筑
20 医疗建筑
21 科研建筑
22 园林建筑
23 交通建筑

直播标签识别接口

输入:

GET参数部分

参数名 必选 类型 说明
Action=ClassifyImage string 固定此值
Version=2017-11-07 string API版本号,固定此值

POST请求示例

{
    "business":["llr"],
   "image_urls":[
        "http://xxx.jpg",
       "http://xxx.jpg",
       "....."
    ],
    "image_data":"base64 for image data"
}

POST参数说明

参数 必选 类型 说明
business array 业务类型(可同时识别多类型)
llr直播标签场景识别
image_urls array 图片url列表(最多10张图片)
image_data string 图片内容的BASE64编码

接口返回:

{
    "header": {
        "err_no": 200,
        "err_msg": "success"
    },
    "cost": 0.11,
    "request_id": "d679e27b-9f1b-44bf-b134-49a6d9f0adff",
    "request_time": 1536904935959,
    "body": [
        {
            "err_no": 400,//仅图片格式出现错误有此信息
            "err_msg": "图片格式错误",//仅图片格式出现错误有此信息
            "data_id": "05009b51d54de716ea5abd0ebe47488b",
            "image_url": "http://ip/xxx.jpg",
            "results": [
                {
                    "err_no": 500,//仅模型出现错误有此信息
                    "err_msg": "内部错误",//仅模型出现错误有此信息
                    "business": "llr",
                    "label": "25",
                    "label_desc": "性感",
                    "rate": 0.9603763818740845,
                    "review": 0,
                    "task_id": "a477fe1e-b702-11e8-ab07-107b4445769f",
                    "label_details": [
                        {
                            "label": "25",
                            "label_desc": "性感",
                            "rate": 0.9603763818740845
                        },
                        {
                            "label": "15",
                            "label_desc": "萌妹",
                            "rate": 0.8293153643608093
                        }
                    ]
                }
            ]
        }
    ]
}

接口输出字段解释:

字段 类型 是否必须 说明
business string 对应请求中的参数值
label string 置信度最高标签ID(string类型)
详见直播标签表
label_desc string 置信度最高标签结果
详见直播标签列表
rate double 标签置信度 [0, 1.0],值越大置信度越高
label_details object 直播标签详情(object类型)
包含所有匹配标签与其置信度
review int 结果是否需要人工复审
image_url string 对应请求中的地址
data_id string 唯一标识该图片
task_id string 标示该次检测任务

直播标签表:

直播标签ID 直播标签
1 家里
2 宿舍
3 教室
4 餐厅
5 办公室
6 娱乐场所
7 商场
8 直播间
9 健身房
10 交通工具内部
11 运动场
12 户外
13 素人
14 小鲜肉
15 萌妹
16 御姐
17 嘻哈
18 小清新
19 大叔
20 型男
21 运动服
22 职业制服
23 学院
24 民族
25 性感

错误码说明

调用接口失败时,返回的HTTP消息体将中包含具体的错误信息,下表为错误码的具体说明,找不到错误原因时,可以联系我们,并提供Response中的RequestId/request_id,以便尽快解决问题。

签名错误码

错误代码(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 说明
ImageURLInvalid 404 图片不可用
未开通鉴黄服务 405 未开通鉴黄服务
未开通鉴黄服务 405 未开通鉴黄服务
未开通暴恐服务 406 未开通暴恐服务
未开通敏感人物服务 407 未开通敏感人物服务
未知的业务类型 408 未知的业务类型
未开通游戏服务 409 未开通游戏服务
未开通OCR服务 410 未开通OCR服务
未开通图片预测服务 411 未开通图片预测服务
未开通特殊场景识别服务 412 未开通特殊场景识别服务
未开通人物分类场景识别服务 413 未开通人物分类场景识别服务
未开通通用标签识别服务 414 未开通通用标签识别服务
未开通直播标签识别服务 416 未开通直播标签识别服务
Service Internal Error 500 内部错误
调用图片预测服务失败. 500 openAPI服务暂不可用。
主站的账户id为空 501 主站的账户id为空。
主站的账户id格式不对 502 主站的账户id格式不对。
传入的参数不对 503 传入的参数有误,请修改无误后再次调用,具体请参见接口文档。
传入参数business中的值不对 504 传入的business参数有误,请修改无误后再次调用,具体请参见接口文档。
传入参数image_urls中的值不对 505 传入的image_urls参数有误,请修改无误后再次调用,具体请参见接口文档。
单次请求中图片数量超过十张 506 单次请求中图片数量超过十张,请减少图片数量。
请求太频繁 510 请求QPS超过限制。

其他说明

图片大小限制为5M,图片下载时间限制为3s内,如果下载时间超过3s返回下载超时;

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

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

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

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

免费注册