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

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

提交视频异步检测任务

业务接口:/green/video/asyncscan

异步检测视频文件或视频流中是否包含敏感人脸信息,支持通过传入视频URL、本地视频文件、视频二进制流的方式进行检测。

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

该接口按照“视频的实际截帧数×视频敏感人脸识别(系统截帧)单价”计费。

异步检测结果需要通过调用结果查询接口(具体请参见查询视频异步检测结果)进行查询或者通过callback的方式进行接收,检测结果最多保留4个小时。

待检测视频需要满足以下要求:
  • 视频文件链接支持以下协议:HTTP和HTTPS。
  • 视频文件支持以下格式:AVI、FLV、MP4、MPG、ASF、WMV、MOV、WMA、RMVB、RM、FLASH、TS。
  • 视频大小限制:单个视频大小不超过200MB。如果您有特殊需求(大视频),可以提工单进行调整。
  • 视频流支持以下协议:RTMP、HLS、HTTP-FLV、RTSP。
  • 视频流时长限制:单个视频流检测任务最长支持24小时,超过24小时任务自动结束。
  • 视频检测的时间依赖于视频的下载时间。请保证被检测的视频文件所在的存储服务稳定可靠,建议您使用阿里云OSS存储服务存储视频文件。

请求参数

名称 类型 是否必须 描述
bizType 字符串 该字段用于标识业务场景。针对不同的业务场景,您可以配置不同的内容审核策略,以满足不同场景下不同的审核标准或算法策略的需求。您可以通过云盾内容安全控制台创建业务场景(bizType),或者通过工单联系我们帮助您创建业务场景。
scenes 字符串数组 指定视频检测的应用场景,取值:sface
live 布尔型 是否直播。默认为false,表示为普通视频检测;若为直播检测,该值必须传入true
offline 布尔型 是否近线检测模式。
  • 默认为false,表示实时检测模式,对于超过了并发路数限制的检测请求会直接拒绝。
  • 如果为true,会进入近线检测模式,提交的任务不保证实时处理,但是可以排队处理,在24小时内开始检测。
说明 该参数仅作用于视频文件检测,不支持流式检测。
callback 字符串 异步检测结果回调通知您的URL,支持HTTP、HTTPS。当该字段为空时,您必须定时检索检测结果。
seed 字符串 该值用于回调通知请求中的签名。当使用callback时,该字段必须提供。
tasks JSON数组 JSON数组中的每个元素是一个结构体(Video表)。每个元素的具体结构描述请参见task
表 1. task
名称 类型 是否必须 描述
clientInfo JSON结构体 客户端信息,请参见公共参数中的公共查询参数。
服务器会把全局的clientInfo和此处独立的clientInfo合并。
说明 独立的clientInfo优先级更高。
dataId 字符串 数据ID。需要保证在一次请求中所有的ID不重复。
url 字符串 视频地址,不能和frames同时为空,也不能和frames同时有值。
说明 传入本字段时按照传URL方式计费。
frames JSON数组 截帧信息。frames中的每个元素是个结构体(Frame表),每个元素的具体结构描述请参见frame
说明 传入本字段时按照传图片序列的方式计费。
framePrefix 字符串 frames存在时,截帧的完整URL为:framePrefix + frame.url
interval 整型 视频截帧间隔,单位为秒,取值范围为1~60。默认值为1秒。
maxFrames 整型 系统对本次检测的视频进行截帧的张数上限,取值范围为5~3600,默认为200张。如需调整到更大,请通过工单联系我们。
说明
  • 该参数仅在视频文件检测中生效(live=false)。如果是视频流检测(live=true),则该参数无效,视频流检测没有截帧数量上限。
  • 当使用OSS地址(以oss://开头)作为视频源地址,并且授权内容安全服务访问阿里云MTS服务后,最大可截取20,000张,该方式不会产生额外费用。关于授权内容安全访问阿里云MTS服务的方法,请参见授权访问MTS服务
表 2. frame
名称 类型 是否必须 描述
url 字符串 截帧地址。当framePrefix存在时,完整的截帧地址为:framePrefix + url
offset 整型 该截帧距离片头的时间戳,单位为秒。

结果回调通知

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

返回参数

名称 类型 是否必须 描述
taskId 字符串 该检测任务的ID。
dataId 字符串 检测对象对应的数据ID。
说明 如果在请求参数中传入了dataId,则此处返回对应的dataId

示例

请求示例
  • 视频截帧图片序列检测
    {
        "scenes": [
            "sface"
        ],
        "tasks": [
            {
                "dataId": "videoId xxx",
                "frames": [
                    {
                        "offset": 10,
                        "url": "http://g1.ykimg.com/0B860000586C0A0300038A0460000"
                    },
                    {
                        "offset": 20,
                        "url": "http://g1.ykimg.com/0B860000586C0A0300038A0460001"
                    },
                    {
                        "offset": 30,
                        "url": "http://g1.ykimg.com/0B860000586C0A0300038A0460002"
                    },
                    {
                        "offset": 40,
                        "url": "http://g1.ykimg.com/0B860000586C0A0300038A0460003"
                    },
                    {
                        "offset": 50,
                        "url": "http://g1.ykimg.com/0B860000586C0A0300038A0460003"
                    },
                    {
                        "offset": 60,
                        "url": "http://g1.ykimg.com/0B860000586C0A0300038A046000x"
                    }
                ]
            }
        ]
    }
  • 普通视频文件检测
    {
        "scenes": [
            "sface"
        ],
        "tasks": [
            {
                "dataId": "videoId xxx",
                "url": "http://www.foo.bak/a.mp4",
                "interval": 1,
                "maxFrames": 200
            }
        ]
    }
  • 视频直播流检测
    {
        "scenes": [
            "sface"
        ],
        "live": true,
        "tasks": [
            {
                "dataId": "videoId xxx",
                "url": "http://www.foo.bak/a.flv",
                "interval": 1,
                "maxFrames": 200
            }
        ]
    }
返回示例
{
    "code": 200,
    "msg": "OK",
    "requestId": "requestID xxx",
    "data": [
        {
            "dataId": "videoId xxx",
            "taskId": "taskId xxx"
        }
    ]
}

查询视频异步检测结果

业务接口:/green/video/results

查询视频异步检测的结果。建议您将查询间隔设置为30秒,最长不能超过4个小时,否则结果将会消失。

说明 该接口为免费接口。

请求参数

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

返回参数

名称 类型 是否必须 描述
code 整型 错误码,和HTTP的status code一致。
msg 字符串 错误描述信息。
dataId 字符串 检测对象对应的数据ID。
说明 如果在请求参数中传入了dataId,则此处返回对应的dataId
taskId 字符串 该检测任务的ID。
results 数组 返回结果,调用成功时(code=200),返回结果中包含一个或多个元素。每个元素是个结构体,具体结构描述请参见result
表 3. result
名称 类型 是否必须 描述
scene 字符串 视频检测场景,取值:sface
label 字符串 检测结果的分类,取值:
  • normal:正常视频,不包含敏感人脸
  • sface:包含敏感人脸的视频
suggestion 字符串 建议您执行的操作,取值:
  • pass:视频正常,无需进行其余操作
  • review:检测结果不确定,需要进行人工审核
  • block:视频违规,建议执行进一步操作(如直接删除或做限制处理)
rate 浮点数 结果为该分类的概率,取值范围为0.00~100.00。值越高,表示越有可能属于该分类。
frames JSON数组 判断为该分类的一些截帧检测结果(FrameScanResult),截帧检测结果表的具体结构描述请参见frame
extras JSON对象 附加信息。
sfaceData 数组 识别出来的人脸信息,具体结构描述请参见sfaceData
表 4. frame
名称 类型 是否必须 描述
url 字符串 截帧地址。
offset 整型 该截帧距离片头的时间戳,单位为秒。
label 字符串 该视频截帧的风险分类,取值范围:
  • normal:不包含敏感人脸
  • sface:包含敏感人脸
rate 浮点数 该视频截帧结果为label所述分类的概率,取值范围为0.00~100.00。值越高,表示越有可能属于该分类。
表 5. sfaceData
名称 类型 是否必须 描述
x 浮点数 以图片左上角为坐标原点,人脸区域左上角到y轴距离。
y 浮点数 以图片左上角为坐标原点,人脸区域左上角到x轴距离。
w 浮点数 人脸区域宽度。
h 浮点数 人脸区域高度。
age 浮点数 年龄。
smileRate 浮点数 微笑的概率。
gender 字符串 性别。
glasses 布尔 是否戴眼镜。
faces 数组 识别出的人脸信息,具体结构描述请参见face
表 6. face
名称 类型 是否必须 描述
name 字符串 相似人物的名称。
rate 浮点数 相似概率。
id 字符串 人脸Id。

示例

请求示例
[
    "taskId xxx"
]
返回示例
{
    "code": 200,
    "msg": "OK",
    "requestId": "requestID xxx",
    "data": [
        {
            "code": 200,
            "msg": "OK",
            "dataId": "videoId xxx",
            "taskId": "taskId xxx",
            "results": [
                {
                    "label": "sface",
                    "rate": 97.03,
                    "scene": "sface",
                    "sfaceData": [
                        {
                            "age": 52.2,
                            "faces": [
                                {
                                    "detail": "基地首领",
                                    "id": "AliFace_0018177",
                                    "name": "奥萨马.本.拉登",
                                    "rate": 97.03
                                }
                            ],
                            "gender": "Male",
                            "glasses": false,
                            "h": 467,
                            "smileRate": 0,
                            "w": 467,
                            "x": 444,
                            "y": 174,
                            "minority": false,
                            "asian": false
                        },
                        "frames": [
                            {
                                "offset": 50,
                                "url": "http://g1.ykimg.com/0B860000586C0A0300038A0460003",
                                "label": "sface",
                                "rate": 99.1
                            }
                        ]
                    }
                ]
            }
        ]
    }