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

使用说明

业务接口:/green/video/syncscan,表示检测视频文件或视频流中是否包含敏感人脸信息,支持通过传入视频URL、本地视频文件、视频二进制流的方式进行检测。

如果您需要检测的敏感人脸不在识别结果中,请联系商务经理。

  • 计费信息

    该接口为收费接口。关于计费方式,请参见内容安全产品定价

  • 视频要求
    • 视频帧链接支持以下协议:HTTP和HTTPS。
    • 视频帧支持以下格式:PNG、JPG、JPEG、BMP、GIF、WEBP。
    • 视频帧大小限制为10 MB以内。
    • 视频帧像素建议不低于256*256(px),像素过低可能会影响识别效果。
    • 视频检测接口的响应时间依赖视频帧的下载时间。请保证被检测视频帧所在的存储服务稳定可靠,建议您使用阿里云OSS存储或者CDN缓存等。

QPS限制

本接口的单用户QPS限制为50次/秒。超过限制,API调用会被限流,这可能会影响您的业务,请合理调用。

请求参数

关于在请求中必须包含的公共请求参数,请参考公共参数

请求body是一个JSON对象,字段说明如下:

名称类型是否必选示例值描述
bizTypeStringdefault该字段用于标识您的业务场景。您可以通过内容安全控制台创建业务场景(具体操作,请参见自定义机审标准)。
scenesStringArray["sface"]指定视频检测的应用场景,唯一取值:sface
tasksJSONArray指定检测对象,JSON数组中的每个元素是一个检测任务结构体。最多支持100个元素,即每次提交100条内容进行检测,支持100个元素的前提是需要将并发任务调整到100个以上。关于每个元素的具体结构描述,请参见task
表 1. task
名称类型是否必选示例值描述
clientInfoJSONObject{"userId":"120234234","userNick":"Mike","userType":"others"}客户端信息,请参见公共参数中的公共查询参数。
服务器会把全局的clientInfo和此处独立的clientInfo合并。
说明 独立的clientInfo优先级更高。
dataIdStringuuid-xxxx-xxxx-1234检测对象对应的数据ID。

由大小写英文字母、数字、下划线(_)、短划线(-)、英文句号(.)组成,不超过128个字符,可以用于唯一标识您的业务数据。

framesJSONArray图片序列的截帧信息。frames中的每个元素是个结构体(Frame表),每个元素的具体结构,请参见frame
framePrefixString截帧地址的前缀。截帧的完整URL为:framePrefix + frame.url,请参见frame
表 2. frame
名称类型是否必选示例值描述
urlStringhttp://example.com/0B860000586C0A0300038A0460000
检测对象的URL。
  • 公网HTTP/HTTPS URL,且长度不超过2048个字符。
  • 阿里云OSS提供的文件路径。您需要先授权内容安全访问OSS存储空间,仅限相同区域的OSS空间。更多信息,请参见授权内容安全访问OSS存储空间

    文件路径格式:oss://<bucket-name>.<endpoint>/<object-name>

offsetInteger10该截帧距离片头的时间戳,单位为秒。

返回数据

返回结果说明,请参见返回结果

返回body中的Data字段是JSON数组,每一个元素包含如下字段:

名称类型示例值描述
codeInteger200错误码,和HTTP状态码一致。

更多信息,请参见公共错误码

msgStringOK返回参数的响应消息。
dataIdStringuuid-xxxx-xxxx-1234对应请求的dataId
taskIdStringimg4wlJcb7p4wH4lAP3111111-123456该检测任务的ID。
resultsArray返回结果,调用成功时(code=200),返回结果中包含一个或多个元素。每个元素是个结构体,具体结构描述,请参见result
表 3. result
名称类型示例值描述
sceneStringsface视频检测场景。
labelStringsface检测结果的分类,取值:
  • normal:正常视频,不包含敏感人脸。
  • sface:包含敏感人脸的视频。
suggestionStringblock建议用户执行的操作,取值范围:
  • pass:视频正常,无需进行其余操作。
  • review:检测结果不确定,需要进行人工审核。
  • block:视频违规,建议执行进一步操作(如直接删除或做限制处理)。
rateFloat97.03结果为该分类的概率,取值范围为0~100。值越高,表示越有可能属于该分类。
framesJSONArray判断为该分类的一些截帧检测结果(FrameScanResult)。关于截帧检测结果表的具体结构描述,请参见frame
extrasJSONObjectxxx附加信息。
sfaceDataArray识别出来的人脸信息列表.。关于具体结构的具体描述,请参见sfaceData
表 4. frame
名称类型示例值描述
urlStringhttp://example.com/0B860000586C0A0300038A0460003
检测对象的URL。
  • 公网HTTP/HTTPS URL,且长度不超过2048个字符。
  • 阿里云OSS提供的文件路径。您需要先授权内容安全访问OSS存储空间,仅限相同区域的OSS空间。更多信息,请参见授权内容安全访问OSS存储空间

    文件路径格式:oss://<bucket-name>.<endpoint>/<object-name>

offsetInteger50该截帧距离片头的时间戳,单位为秒。
labelStringsface该视频截帧的风险分类。
rateFloat99.1该视频截帧结果为label所述分类的概率,取值范围:0~100。值越高,表示越有可能属于该分类。
表 5. sfaceData
名称类型示例值描述
xFloat444以图片左上角为坐标原点,人脸区域左上角到y轴距离。
yFloat174以图片左上角为坐标原点,人脸区域左上角到x轴距离。
wFloat467人脸区域宽度。
hFloat467人脸区域高度。
smileRateFloat0微笑的概率。
glassesBooleanfalse是否戴眼镜。取值:
  • false:表示未佩戴眼镜。
  • true:表示佩戴眼镜。
facesArray识别出的人脸信息。关于结构的具体描述,请参见face
表 6. face
名称类型示例值描述
nameStringxxxx相似人物的名称。
rateFloat97.03相似概率。
idStringAliFace_0018177人脸id。

示例

请求示例
http(s)://[Endpoint]/green/video/syncscan
&<公共请求参数>
{
"scenes":["sface"],
"tasks":[
  {
    "dataId":"uuid-xxxx-xxxx-1234",
    "frames":[
      {
        "offset":10,
        "url":"http://example.com/0B860000586C0A0300038A0460000"
      },
      {
        "offset":20,
        "url":"http://example.com/0B860000586C0A0300038A0460001"
      },
      {
        "offset":30,
        "url":"http://example.com/0B860000586C0A0300038A0460002"
      },
      {
        "offset":40,
        "url":"http://example.com/0B860000586C0A0300038A0460003"
      },
      {
        "offset":50,
        "url":"http://example.com/0B860000586C0A0300038A0460003"
      },
      {
        "offset":60,
        "url":"http://example.com/0B860000586C0A0300038A046000x"
      }
    ]
  }
]
}
返回示例
{
    "code":200,
    "msg":"OK",
    "requestId":"requestID xxx",
    "data":[
        {
            "code":200,
            "msg":"OK",
            "dataId":"uuid-xxxx-xxxx-1234",
            "taskId":"img4wlJcb7p4wH4lAP3111111-123456",
            "results":[
                {
                    "label":"sface",
                    "rate":97.03,
                    "scene":"sface",
                    "sfaceData":[
                        {
                            "faces":[
                                {
                                    "id":"AliFace_0018177",
                                    "name":"xxxx",
                                    "rate":97.03
                                }
                            ],
                            "glasses":false,
                            "h":467,
                            "smileRate":0,
                            "w":467,
                            "x":444,
                            "y":174
                        }
                    ],
                    "frames":[
                        {
                            "offset":50,
                            "url":"http://example.com/0B860000586C0A0300038A0460003",
                            "label":"sface",
                            "rate":99.1
                        }
                    ]
                }
            ]
        }
    ]
}