创建云上人脸提取作业
功能介绍
该API用于分析视频流,检测其中的人脸并输出图片。
- 支持H264、H265编码格式的RTSP视频流。
- 视频中人脸分辨率不低于90*90。
- 通过DIS通道输出原图时,请使用DIS高级通道,以免因通道带宽过小而丢失原图数据。
- 作业运行中请勿改变视频分辨率;若确有需要,请重新下发作业。
调试
您可以在API Explorer中调试该接口。
URI
- URI格式
POST /v2/{project_id}/services/c-face-detection/tasks
- 参数说明
参数
是否必选
类型
说明
project_id
是
String
服务所在区域对应的项目ID,获取方法请参见获取项目ID。
请求
- 请求样例1(vis输入+dis输出)
POST /v2/6204a5bd270343b5885144cf9c8c158d/services/c-face-detection/tasks { "name":"face_cloud_0", "description":"face detection task test", "input":{ "type":"vis", "data":[ { "stream_name":"face", "index":0 } ] }, "output":{ "dis":{ "stream_name":"dis-face", "data_category":[ "FaceImage", "OriginImage" ] } }, "service_version":"3.0", "resource_order_id":"840a5cf90d4a4bbaa71f251dfe8fe64e", "service_config":{ "common":{ "detection_max_size":800, "detection_min_size":120, "origin_image_send_sw":0, "image_compression_ratio":90, "frame_skip_number":0, "face_first_send_threshold":0.5, "face_must_send_sw":0, "face_repeat_send_sw":0, "face_repeat_send_mode":"QUALITY_STEP", "face_repeat_send_step":1.2, "face_repeat_send_interval":1, "target_roi": "{\"polygons\":[{\"data\":[[100,100],[1800,100],[1800,1000],[100,1000]]}]}" } } }
- 参数说明
参数
是否必选
类型
说明
name
是
String
作业名称,只能由中文、字母(a~zA~Z)、数字(0~9)、中划线(-)、下划线(_)组成,长度范围为[1,100]。
description
否
String
作业描述信息,最大长度为500字符长度。
input
是
Object
视频数据输入列表,目前云上人脸提取支持以下输入类型:- vis:从视频接入服务中读取视频数据。
详细参数定义参见task.input(任务输入参数)。
service_version
是
String
功能版本号,版本号为3.0。
resource_order_id
是
String
购买的算法能力包ID,在服务界面购买算法能力包获取。
output
是
Object
结果数据的输出列表,目前云上人脸提取支持以下输出类型:
- dis:将结果输出到您指定的DIS通道,输出JSON格式信息,包括提取的人脸图和原始图片的Base64编码。
详细参数定义参见task.output(任务输出参数)。
service_config
否
Object
服务的算法配置,配置参数见service_config参数结构说明。
- service_config中common参数说明
字段
是否必选
类型
说明
detection_max_size
否
Int
对应控制台的界面参数“检测目标最大像素值”。
表示发送人脸图片长宽的最大像素,取值范围[90, 1000],默认值:800。
如果该参数设置得过小,人脸提取的准确率会受到影响。
detection_min_size
否
Int
对应控制台的界面参数“检测目标最小像素值”。
表示发送人脸图长宽的最小像素,取值范围[90, 1000],默认值:120。
如果该参数设置得过大,人脸提取的准确率会受到影响。
如果该参数设置得过小,则可能提取到分辨率较低的人脸图。
origin_image_send_sw
否
Int
对应控制台的界面参数“发送原图开关”。
表示是否发送人脸原始图,取值范围:
- 0:表示不发送原图。
- 1:表示发送原图。
默认值:0。
image_compression_ratio
否
Int
对应控制台的界面参数“原图压缩比”。
表示原始图的图片压缩比(人脸图不受影响),取值范围为[20,100]。数值越低,原始图越模糊。
默认值:90,表示图片压缩比为90%。
注意:该参数不对人脸图生效。
frame_skip_number
否
Int
对应控制台的界面参数“跳帧数”。
表示每分析视频1帧画面后,所跳过的帧数。例如设置为2,表示每处理1帧跳过2帧。取值范围[0, 10],默认值0。
本参数值越大,算法的性能消耗就越低,但会影响人脸提取的效果。
face_first_send_threshold
否
Float
对应控制台的界面参数“人脸首次发送时间”。
表示从检测出人脸到发送人脸图之间的计时,单位为s,取值范围[0, 360],默认值0。
从人脸被检测跟踪开始计时,至该参数所设置的时间结束,算法会选择期间满足发送条件且质量最好的人脸图进行发送。- 如果到达所设置的时间,目标都没有出现满足发送条件的人脸图,则时间顺延,直到出现满足发送条件的人脸图,或者直到目标消失,才停止计时。
- 如果目标在计时过程中(含顺延时间)消失,则从期间满足发送条件的提取结果中,选择质量最好的一张人脸图进行发送。
但如果该目标的全部提取结果均不满足发送条件,则根据“face_must_send_sw”参数的取值,分两种情况:
a. 如果“face_must_send_sw”设为 0,则不发送该目标的人脸图。
b. 如果“face_must_send_sw”设为 1,尽管该目标没有符合满足发送条件的人脸图,但还是会从提取结果中选择一张质量“相对较好”的人脸图进行发送。
face_must_send_sw
否
Int
对应控制台的界面参数“人脸必须发送开关”。
表示检测出行人后是否必须发送一张人脸:
- 0:表示非必须发送。
- 1:表示必须发送。
默认值0。
当本参数设为1时,即使行人在跟踪范围内都没有满足发送条件的人脸,也会发送一张人脸。
face_repeat_send_sw
否
Int
对应控制台的界面参数“人脸重复发送开关”。
表示是否重复发送同一位行人的多张人脸图。
- 0:表示不重复发送。
- 1:表示重复发送。
默认值0。
本参数设为1后,需配合“face_repeat_ send_mode”参数及“face_repeat_ send_step”/“face_repeat_send_interval”参数共同使用,从而选择以质量递增或者周期发送的模式,来发送同一个人的多张人脸图。
用户可通过输出结果中的“detection_id”来检测是否同一个人。
face_repeat_ send_mode
否
String
对应控制台的界面参数“人脸重复发送模式”。
表示对同一位行人多张脸图的发送模式,取值范围:
- QUALITY_STEP:按质量递增的模式发送,需配合“face_repeat_ send_step”参数使用。对同一位行人,当新检测到的脸图质量高于已发送脸图质量一定程度时,会再次发送。
- PERIOD:按时间周期的模式发送,需配合“face_repeat_send_interval”参数使用。对同一位行人,选取每个时间周期内质量最优人脸进行发送。
默认值为QUALITY_STEP。
face_repeat_ send_step
否
Float
对应控制台的界面参数“人脸重复发送质量倍数”。
表示人脸图重复发送的质量递增倍数。
对同一位行人,当新检测到的人脸图质量大于已发送人脸图一定程度时,触发再次发送一张人脸图,取值范围[1.0, 10.0]。
默认值为1.2,表示新人脸图的质量必须大于已发送人脸图质量的1.2倍时,才会再次发送。
face_repeat_send_interval
否
Int
对应控制台的界面参数“人脸重复发送周期”。
表示重复发送人脸图的周期时间。对同一位行人,在每个周期(该参数确定具体时间)结束时,选取该周期内质量最好的人脸图发送一次。单位为s,取值范围[0,360],默认值为1。
target_roi
否
String
对应控制台的界面参数“检测区域设置”。
表示检测区域,该字段为JSON格式的字符串,API调用时需要加转义符。详细JSON格式参见target_roi(目标区域)。
例如:
{"polygons":[{"data":[[84,389],[1840,349],[1824,526],[78,526]]}]}
参数没有携带时,默认区域为整个视频帧。
响应
- 响应样例
[ { "id": "cf9631594c9e48d7b04660da94a2bb94" } ]
- 返回作业ID列表
参数
类型
说明
id
String
作业ID。
提取结果
- 输出的JSON字符串主要包含两类信息:人脸图和原始图。
- 输出类型支持配置data_category参数,取值范围为[FaceImage,OriginImage],分别表示是否发送人脸图和原始图(发送原始图片前,需要将origin_image_send_sw参数设置为1)。
- 支持输出JSON字符串到指定的DIS。
- 输出结果示例:
- 人脸图输出JSON示例(VIS输入+DIS输出):
{ "stream_id": "facestream", "event_type": 65536, "task_id": "cf9631594c9e48d7b04660da94a2bb94", "timestamp": 1527603463, "message_id": "E87B6D7C-4FFD-11EA-AD9D-34B354BC6688", "data": { "face_id": "0DD1BEA6-634B-11E8-8B0B-407D0FAD9217", "detection_id": "0DD1BEA6-634B-11E8-8B0B-407D0FAD9218", "origin_image_id": "0DD1BF0A-634B-11E8-8B0B-407D0FAD9218", "bounding_box": { "x": 32, "y": 379, "w": 49, "h": 65 } }, "image_base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQE..." }
- 人脸图JSON格式说明
字段
类型
说明
stream_id
String
VIS输入为流名称。
event_type
Uint64
快速标识人脸提取算法的输出消息类型。人脸图json消息固定为65536, 对应16进制为 0x 0000 0000 0001 0000。
task_id
String
作业ID。
timestamp
Uint64
图片解码时间的时间戳。
message_id
String
本条数据的UUID。
image_base64
String
人脸图Base64编码结果,输出类型为DIS、webhook时携带此字段。
data
Object
人脸图业务输入内容。
- data参数格式说明
字段
类型
说明
face_id
String
人脸图UUID标识。
detection_id
String
人脸的检测ID,相同的detection_id表示同一个人脸。由于遮挡等原因,会存在人的跟踪路线丢失而ID发生变化的情况,所以该字段不建议作为检测自然人的唯一标识,仅作为辅助手段使用。
origin_image_id
String
人脸原始图UUID。如果“origin_image_send_sw”参数设为 0,即不输出原始图,则该字段为“00000000-0000-0000-0000-000000000000”。
bounding_box
Object
人脸图在原始图中的位置信息。
- bounding_box参数格式说明
字段
类型
说明
x
Int
矩形框左上角横坐标。
y
Int
矩形框左上角纵坐标。
w
Int
矩形框宽度。
h
Int
矩形框高度。
- 原始图输出JSON示例(VIS输入+DIS输出)
{ "stream_id": "facestream", "event_type": 65537, "task_id": "cf9631594c9e48d7b04660da94a2bb94", "timestamp": 1548211653, "message_id": "E87B6D7C-4FFD-11EA-AD9D-34B354BC6648", "data": { "origin_image_id": "3BEA08B4-1EB9-11E9-B012-0255AC100046", }, "image_base64": "/hdjhjGHGHAAAQABAAD/2wBDAAIBAQE..." }
- 原始图JSON格式
字段
类型
说明
stream_id
String
该字段为VIS视频流名称。
event_type
Uint64
快速标识人脸提取算法的输出消息类型。原始图json消息固定为65537, 对应16进制为 0x 0000 0000 0001 0001。
task_id
String
作业ID。
timestamp
Uint64
输入类型为VIS时,表示人脸图片解码时间的Unix时间戳。
message_id
String
本条数据的UUID。
image_base64
String
原始图Base64编码结果,输出类型为DIS、webhook时携带此字段。
data
Object
原始图业务输入内容。
- data参数格式说明
字段
类型
说明
origin_image_id
String
人脸原始图UUID。
- 人脸图输出JSON示例(VIS输入+DIS输出):
返回值
- 正常
- 异常
返回值
说明
400 Bad Request
请求错误,具体返回错误码请参考错误码。
401 Unauthorized
鉴权失败。
403 Forbidden
没有操作权限。
404 Not Found
找不到资源。
500 Internal Server Error
服务内部错误。
503 Service Unavailable
服务不可用。