本文提供了调用图片异步检测任务进行图片标签识别的具体接口和参数说明,帮助您编写程序构建HTTP调用请求。

  • 关于如何构造HTTP请求,请参见请求结构
  • 您也可以直接选用已构造好的HTTP请求,具体请参见SDK 概览

提交图片异步检测任务

业务接口:/green/image/asyncscan

提交图片异步检测任务,识别并返回图片中的主体标签内容,识别到的标签将按照置信度由高到低返回Top N个结果。

说明 该接口为收费接口,具体计费方式请参见内容安全产品定价

同步、异步检测

同步检测允许的最长检测时间是6秒,如果检测在该时间限制内没有完成,系统会强制返回超时错误码。如果您对实时性要求不高,可以选择异步检测,其它情况下请选择同步检测,同步检测接口的调用相对简单些。对于同步检测接口的调用,建议您将超时时间设置为6秒。

异步检测任务不会实时返回检测结果,您需要通过轮询的方式或者callback的方式获取检测结果。检测结果最长保留一小时。

图片限制
  • 图片链接支持以下协议:HTTP和HTTPS。
  • 图片支持以下格式:PNG、JPG、JPEG、BMP、GIF、WEBP。
  • 图片大小限制为10MB以内(适用于同步和异步调用)。如您有特殊需求(大图片),可以提工单进行调整。
  • 图片下载时间限制为3秒内,如果下载时间超过3秒,返回下载超时。
  • 图片像素建议不低于256*256,像素过低可能会影响识别效果。
  • 图片检测接口响应时间依赖图片的下载时间。请保证被检测图片所在的存储服务稳定可靠,建议您使用阿里云OSS存储或者CDN缓存等。

请求参数

名称 类型 是否必须 描述
bizType 字符串 该字段用于标识业务场景。针对不同的业务场景,您可以配置不同的内容审核策略,以满足不同场景下不同的审核标准或算法策略的需求。您可以通过云盾内容安全控制台创建业务场景(bizType),或者通过工单联系我们帮助您创建业务场景。
scenes 字符串数组 指定图片检测的应用场景,取值:tag
callback 字符串 异步检测结果回调通知您的URL,支持HTTP/HTTPS。该字段为空时,您必须定时检索检测结果。
seed 字符串 随机字符串,该值用于回调通知请求中的签名。当使用callback时,该字段必须提供。
tasks JSON数组 检测对象,JSON数组中的每个元素是一个图片检测任务结构体(image表)。每个元素的具体结构描述请参见task
表 1. task
名称 类型 是否必须 描述
dataId 字符串 数据ID。需要保证在一次请求中所有的ID不重复。
url 字符串 待检测图像的URL。

结果回调通知

调用异步检测时,您可以在请求参数中传入回调通知参数(callback),即一个HTTP/HTTPS协议接口的URL,用来接收检测结果。callback接口必须支持POST方法、UTF-8编码的传输数据,以及表单参数checksumcontent。内容安全按照下表描述的生成规则和格式设置checksumcontent,调用您的callback接口返回检测结果。
说明 您的服务端callback接口收到内容安全推送的结果后,如果返回的HTTP状态码为200,则表示接收成功,其他的HTTP状态码均视为接收失败。接收失败时,内容安全将最多重复推送16次检测结果,直到接收成功。重复推送16次后仍未接收成功,则不再推送,建议您检查callback接口的状态。
名称 类型 描述
checksum String 用户uid + seed + content拼成字符串,通过SHA256算法生成。用户UID即阿里云账号ID,可以在阿里云控制台查询。为防篡改,您可以在获取到推送结果时,按上述算法生成字符串,与checksum做一次校验。
说明 用户UID必须是阿里云主账号UID,而非子账号UID。
content String JSON字符串格式,请自行解析反转成JSON对象。content结果的示例如下。
content结果示例
{
    "code": 200,
    "msg": "OK",
    "dataId": "imageId xxx",
    "taskId": "taskId xxx",
    "results": [
        {
            "label": "tag",
            "rate": 99.2,
            "scene": "tag",
            "suggestion": "review"
        }
    ]
}

返回参数

名称 类型 是否必须 描述
code 整型 错误码,和HTTP的status code一致。
msg 字符串 错误描述信息。
dataId 字符串 对应请求中的dataId
taskId 字符串 该检测任务的ID。
url 字符串 对应请求中的URL。

示例

请求示例
{
    "scenes": [
        "tag"
    ],
    "tasks": [
        {
            "dataId": "test4lNSMdggA0c56MMvfYoh4e-1mwxpx",
            "url": "https://img.alicdn.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
        }
    ]
}
返回示例
{
    "code": 200,
    "msg": "OK",
    "requestId": "95AD868A-F5D2-4AEA-96D4-E0273B8E074C",
    "data": [
        {
            "code": 200,
            "msg": "OK",
            "dataId": "test4lNSMdggA0c56MMvfYoh4e-1mwxpx",
            "taskId": "fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695",
            "url": "https://img.alicdn.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
        }
    ]
}

查询异步检测结果

业务接口:/green/image/results

查询图片异步检测结果。建议您将查询间隔设置为30秒,最长不能超出一个小时,否则结果将会丢失。

说明 该接口为免费接口。

请求参数

名称 类型 是否必须 描述
body JSON数组 要查询的taskId列表。最大长度不超过1,000。

返回参数

名称 类型 是否必须 描述
code 整型 错误码,和HTTP的status code一致。
msg 字符串 错误描述信息。
dataId 字符串 对应的请求中的dataId
taskId 字符串 该检测任务的ID。
url 字符串 对应的请求中的URL。
results 数组 返回结果。调用成功时(code=200),返回结果中包含一个或多个元素。每个元素是个结构体,具体结构描述请参见result
extras Map 额外调用参数。
说明 该参数可能会被调整,目前请勿依赖该参数的返回值。
表 2. result
名称 类型 是否必须 描述
scene 字符串 图片检测场景,取值:tag
label 字符串 检测结果的分类,取值:
  • normal:正常图片,无标签
  • tag:含标签的图片
suggestion 字符串 建议用户执行的操作,取值:
  • pass:图片不含标签,无需进行其余操作
  • review:图片含标签,建议执行后续操作
rate 浮点数 结果为该分类的概率,取值范围为[0.00-100.00]。值越高,表示越有可能属于该分类。
tagData 结构体 标签识别发现标签时(label=tag),返回的标签数据信息。具体结构描述请参见tagData
表 3. tagData
名称 类型 是否必须 描述
summary 数组 标签概要信息。具体结构描述请参见summary
表 4. summary
名称 类型 是否必须 描述
tgCnName 字符串 标签中文名。
tgEnName 字符串 标签英文名。
cnCategory 字符串 标签所属的分类中文名称。
enCategory 字符串 标签所属的分类英文名称。
rate 浮点数 结果为标签的概率,取值范围[0,100]。取值越大,则越有可能属于标签。

示例

请求示例
[
    "fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695"
]
返回示例
{
    "msg": "OK",
    "code": 200,
    "data": [
        {
            "msg": "OK",
            "code": 200,
            "dataId": "95e64d58-ad64-4864-8347-aa06490db5ad",
            "extras": {

            },
            "results": [
                {
                    "tagData": {
                        "summary": [
                            {
                                "cnCategory": "实体",
                                "rate": 73.28,
                                "enCategory": "entities",
                                "tagEnName": "impala",
                                "tagCnName": "高角羚"
                            },
                            {
                                "cnCategory": "实体",
                                "rate": 25.18,
                                "enCategory": "entities",
                                "tagEnName": "gazelle",
                                "tagCnName": "瞪羚"
                            }
                        ]
                    },
                    "rate": 99.91,
                    "suggestion": "review",
                    "label": "tag",
                    "scene": "tag"
                }
            ],
            "taskId": "img1@tuPWwLrLK57ZYTmMuhoh-1q9x$w",
            "url": "https://timgsa.baidu.com/timg?image&quality=80&size=b9999_10000&sec=1548756832083&di=4606b21665c25e54aab07ba0ab383442&imgtype=0&src=http%3A%2F%2Fimg000.hc360.cn%2Fm5%2FM02%2F3F%2FE2%2FwKhQ6lTGChiEUT_jAAAAAHEFcAI198.jpg"
        }
    ],
    "requestId": "D62E3A2B-A432-4A84-813E-ECA5BC9D720C"
}