创建边缘人脸提取作业_园区智能体 CampusGo

功能介绍

该API用于分析检测视频流中的人脸并输出图片。

支持H264、H265编码格式的RTSP视频流。
视频中人脸大小不低于90*90像素。
通过DIS通道输出原图时，请使用DIS高级通道，以免因通道带宽过小而丢失原图数据。
作业运行中请勿改变视频分辨率；若确有需要，请重新下发作业。
如果输出方式选择Localpath，在创建边缘运行池时需填写主机挂载路径。该路径要求真实存在于边缘节点，路径需与算法作业Localpath输出方式的挂载源路径一致。

调试

您可以在API Explorer中调试该接口。

URI

URI格式

POST /v2/{project_id}/services/c-face-edge/tasks

参数说明

参数	是否必选	类型	说明
project_id	是	String	服务所在区域对应的项目ID，获取方法请参见获取项目ID。

请求

请求样例（摄像头输入+DIS/Localpath/Webhook输出）

POST /v2/6204a5bd270343b5885144cf9c8c158d/services/c-face-edge/tasks  
{
    "name":"face_edge",
    "description":"face detection task test",
    "service_version":"3.0",
    "input":{
        "type":"edgecamera",
        "data":[
            {
                "index":0,
                "id":"6233039b-698f-4347-8ced-ef0d14605c0b"
            }
        ]
    },
    "output":{
        "dis":{
            "stream_name":"dis-face",
            "data_category":[
                "FaceImage",
                "OriginImage"
            ]
        },
        "localpath":{
            "mount_source_path":"/tmp/",
            "data_category":[
                "FaceImage",
                "OriginImage"
            ]
        },
        "webhook":{
            "url":"https://apigw.xx.com/api/mqs/sit",
            "headers":{
                "content-type":"application/json"
            },
            "data_category":[
                "FaceImage",
                "OriginImage"
            ]
        }
    },
    "edge_pool_id":"e9bf9ebe497d4c9bb2e65d1f99fe1ff9",
    "resource_order_id": "840a5cf90d4a4bbaa71f251dfe8fe64e",
    "service_config":{
        "common":{
            "detection_max_size":800,
            "detection_min_size":120,
            "origin_image_send_sw":0,
            "face_first_send_threshold":0,
            "face_must_send_sw":0,
            "face_repeat_send_sw":1,
            "face_repeat_send_mode":"PERIOD",
            "face_repeat_send_step":1,
            "face_repeat_send_interval":1,
            "image_compression_ratio":90,
            "target_roi": "{\"polygons\":[{\"data\":[[100,100],[1800,100],[1800,1000],[100,1000]]}]}"
        }
    }
}

请求样例2（edgerestful输入+DIS/Webhook输出）

POST /v2/6204a5bd270343b5885144cf9c8c158d/services/c-face-edge/tasks  
{ 
    "name": "face_edge", 
    "description": "face detection task test",
    "input": {
        "type": "edgerestful",
        "data": [
            {
                "index": 0,
                "url":"https://100.127.134.69:554/test/data",
                "certificate_check": false,
                "rtsp_path_in_response": "data/url"
            }
        ]
    },
    "output": {
        "dis": {
            "stream_name": "face-edge", 
            "data_category":[
                "FaceImage",
                "OriginImage"
            ]
        },
        "webhook": {
            "url": "https://apigw.huawei.com/api/mqs/message/sit",
            "headers": {
                "content-type": "application/json"
            }, 
            "data_category":[
                "FaceImage",
                "OriginImage"
            ]
        }
    },
    "service_version": "3.0",
    "resource_order_id": "840a5cf90d4a4bbaa71f251dfe8fe64e",
    "edge_pool_id": "8dcf5ec7bc4d4a26aa1d3e1bb5ed2b5a",
    "service_config": {
        "common": {
            "detection_max_size": 800, 
            "detection_min_size": 120, 
            "origin_image_send_sw": 0,
            "image_compression_ratio": 90,
            "frame_skip_number": 0,
            "local_file_save_time": 1, 
            "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]]}]}"
        }
   }
}

请求样例3（VCN输入+DIS/Webhook输出）

POST /v2/6204a5bd270343b5885144cf9c8c158d/services/c-face-edge/tasks  
 { 
    "name": "face_edge", 
    "description": "face detection task test",
    "input": {
        "type": "vcn",
        "vcn":{
                "ip":"172.100.119.6",
                "password":"CQeNfcRLwyMvH77AkDBaPS+BKXdFu/1bAXtIMNTx3QPbVewjipNq06nNodxWI28I1lCUsvv2+wB1joepzynLVW3g2nz0k9vaCRDoK6=",
                "port":"4675",
                "username":"testname"
        },
        "data": [
            {
                "index": 0,
                "stream_type": 1,
                "device_id":"07211540881586160101#f7964493ff764bbf9294d58b22e63de6"
            }
        ]
    },
    "output": {
        "dis": {
            "stream_name": "face-edge", 
            "data_category":[
                "FaceImage",
                "OriginImage"
            ]
        },
        "webhook": {
            "url": "https://apigw.huawei.com/api/mqs/message/sit",
            "headers": {
                "content-type": "application/json"
            }, 
            "data_category":[ 
                "FaceImage",
                "OriginImage"
            ]
        }
    },
    "service_version": "3.0",
    "resource_order_id": "840a5cf90d4a4bbaa71f251dfe8fe64e",
    "edge_pool_id": "8dcf5ec7bc4d4a26aa1d3e1bb5ed2b5a",
    "service_config": {
        "common": {
            "detection_max_size": 800, 
            "detection_min_size": 120, 
            "origin_image_send_sw": 0,
            "image_compression_ratio": 90,
            "frame_skip_number": 0,
            "local_file_save_time": 1, 
            "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	视频数据输入列表，支持从指定的边缘摄像头读取数据，即输入类型为“edgecamera”，“edgerestful”，“VCN”。详细参数定义参见task.input（任务输入参数）。
service_version	是	String	功能版本号，版本号为3.0。边缘算法版本支持的显卡硬件为T4和华为自研Davinci芯片。
resource_order_id	是	String	购买的算法能力包ID，在服务界面购买算法能力包获取。
edge_pool_id	是	String	边缘运行池ID，获取方法参见创建边缘运行池。
output	是	Object	结果数据的输出列表，目前支持以下输出类型： DIS：将结果输出到您指定的DIS通道，输出JSON格式信息，包括提取的人脸图和原始图片的Base64编码。 Webhook：将结果输出到Webhook URL，输出JSON格式信息，包括提取的人脸图和原始图片。Webhook URL地址为用户指定的URL地址，例如用户指定URL地址为：“https://www.face.com”，则算法服务会把提取的人脸图和原始图以POST请求的方式发送到上述URL。 Localpath：将作业的运行结果保存在边缘节点本地（节点必须为linux系统），必须为linux路径，例如“/opt/cloud/”，输出人脸图片和JSON结构化信息。详细参数定义见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。该参数值越大，算法的性能消耗就越低，但会影响人脸提取的效果。
local_file_save_time	否	Int	对应控制台的界面参数“本地存储时间”。表示本地文件保存时间，单位为天，超期会被自动删除。输出类型为Localpath（即将作业的运行结果保存在边缘节点本地）时生效，取值范围[1, 180]，默认值为1（天）。
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": "fd66974ae7334649a37257242c5fa4c3"
  }
]

返回作业ID列表

参数	类型	说明
id	String	作业ID。

提取结果

输出的JSON字符串主要包含两类信息：人脸图和原始图。
- 输出类型支持配置data_category参数，取值范围为[FaceImage,OriginImage]，分别表示是否发送人脸图和原始图（发送原始图片前，需要将origin_image_send_sw参数设置为1）。
- 支持输出JSON字符串到指定的DIS。
- 支持输出JSON字符串和图片到localpath（边缘节点本地路径），具体请参见存储路径的创建规则。
- 支持输出JSON字符串到用户填写的webhook请求头指定的URL。

输出结果示例：

人脸图的JSON示例

输出人脸图的JSON字符串到DIS：

{ 
    "event_type": 65536,
    "task_id": "a066974ae7334649a37257242c5fa4c3",
    "stream_id": "001", 
    "timestamp": 1527603463,
    "message_id": "E87B6D7C-4FFD-11EA-AD9D-34B354BC6688",
    "data": {
        "node_id": "8a188f57-1ac4-4ded-a485-972830ef8c97",
        "face_id": "0DD1BEA6-634B-11E8-8B0B-407D0FAD9217",
        "detection_id": "0DD1BEA6-634B-11E8-8B0B-407D0FAD9218",
        "origin_image_id": "0DD1BF0A-634B-11E8-8B0B-407D0FAD9218",
        "origin_image_path":"001/originimage/20181121/pic/2.jpg", 
        "origin_json_path":"001/originimage/20181121/json/2.txt",
        "bounding_box": { 
            "x": 32, 
            "y": 379, 
            "w": 49, 
            "h": 65 
        }
    },
    "image_base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQE..." 
}

输出人脸图的JSON字符串到localpath:

{ 
    "event_type": 65536,
    "task_id": "a066974ae7334649a37257242c5fa4c3",
    "stream_id": "001", 
    "timestamp": 1527603463,
    "message_id": "E87B6D7C-4FFD-11EA-AD9D-34B354BC6688",
    "data": {
        "node_id": "8a188f57-1ac4-4ded-a485-972830ef8c97",
        "face_id": "0DD1BEA6-634B-11E8-8B0B-407D0FAD9217",
        "detection_id": "0DD1BEA6-634B-11E8-8B0B-407D0FAD9218",
        "image_path": "001/faceimage/20181121/pic/1.jpg",
        "origin_image_id": "0DD1BF0A-634B-11E8-8B0B-407D0FAD9218",
        "origin_image_path":"001/originimage/20181121/pic/2.jpg", 
        "origin_json_path":"001/originimage/20181121/json/2.txt",
        "bounding_box": { 
            "x": 32, 
            "y": 379, 
            "w": 49, 
            "h": 65 
        }
    }
}

输出人脸图的JSON字符串到webhook指定的URL：

{
    "event_type": 65536,
    "task_id": "a066974ae7334649a37257242c5fa4c3",
    "stream_id": "001", 
    "timestamp": 1527603463,
    "message_id": "E87B6D7C-4FFD-11EA-AD9D-34B354BC6688",
    "data": {
        "node_id": "8a188f57-1ac4-4ded-a485-972830ef8c97",
        "face_id": "0DD1BEA6-634B-11E8-8B0B-407D0FAD9217",
        "detection_id": "0DD1BEA6-634B-11E8-8B0B-407D0FAD9218",
        "origin_image_id": "0DD1BF0A-634B-11E8-8B0B-407D0FAD9218",
        "origin_image_path":"001/originimage/20181121/pic/2.jpg", 
        "origin_json_path":"001/originimage/20181121/json/2.txt",
        "bounding_box": { 
            "x": 32, 
            "y": 379, 
            "w": 49, 
            "h": 65 
        }
    },
    "image_base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQE..."
}

原始图的JSON示例

输出原始图的JSON到DIS：

{ 
    "event_type": 65537,
    "task_id": "a066974ae7334649a37257242c5fa4c3",
    "stream_id": "001", 
    "timestamp": 1527603463,
    "message_id": "E87B6D7C-4FFD-11EA-AD9D-34B354BC6688",
    "data": {
        "node_id": "8a188f57-1ac4-4ded-a485-972830ef8c97",
        "origin_image_id": "0DD1BF0A-634B-11E8-8B0B-407D0FAD9218",
    },
    "image_base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQE..."
}

输出原始图的JSON到localpath：

{ 
    "event_type": 65537,
    "task_id": "a066974ae7334649a37257242c5fa4c3",
    "stream_id": "001", 
    "timestamp": 1527603463,
    "message_id": "E87B6D7C-4FFD-11EA-AD9D-34B354BC6688",
    "data": {
        "node_id": "8a188f57-1ac4-4ded-a485-972830ef8c97",
        "origin_image_id": "0DD1BF0A-634B-11E8-8B0B-407D0FAD9218",
        "image_path": "001/originimage/20181121/pic/1.jpg"
    }
}

输出原始图的JSON到webhook指定的URL：

{ 
    "event_type": 65537,
    "task_id": "a066974ae7334649a37257242c5fa4c3",
    "stream_id": "001", 
    "timestamp": 1527603463,
    "message_id": "E87B6D7C-4FFD-11EA-AD9D-34B354BC6688",
    "data": {
        "node_id": "8a188f57-1ac4-4ded-a485-972830ef8c97",
        "origin_image_id": "0DD1BF0A-634B-11E8-8B0B-407D0FAD9218",
    },
    "image_base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQE..."
}

人脸图的JSON字段说明：

JSON格式说明

字段	类型	说明
stream_id	String	摄像头ID。
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参数格式说明

字段	类型	说明
node_id	String	边缘节点编号。
face_id	String	人脸图UUID。
detection_id	String	人脸的检测ID，相同的detection_id表示同一个人脸。由于遮挡等原因，会存在人的跟踪路线丢失而ID发生变化的情况，所以该字段不建议作为检测自然人的唯一标识，仅作为辅助手段使用。
image_path	String	人脸图本地存储路径，仅当输出类型为LOCALPATH时携带此字段。该路径（image_path）生成规则为“{stream_id}/faceimage/{当前日期}/pic/*.jpg”，文件名从“1.jpg”开始依次编号。人脸图片绝对路径={用户输入的挂载路径}+{image_path}。
origin_image_id	String	人脸原始图UUID。如果“origin_image_send_sw”参数设为 0，即不输出原始图，则该字段为“00000000-0000-0000-0000-000000000000”。
origin_image_path	String	原始图本地存储路径。当原始图输出类型为Localpath并开启“发送原图开关”时，该字段才有信息，否则，字段内容为空。该路径（origin_image_path）生成规则为“{stream_id}/originimage/{当前日期}/pic/*.jpg”，文件名从“1.jpg”开始依次编号。原始图绝对路径={用户输入挂载路径}+{origin_image_path}。
origin_json_path	String	原始图JSON结构化信息本地存储路径。当原始图输出类型为Localpath并开启“发送原图开关”时，该字段才有信息，否则，字段内容为空。该路径（origin_json_path）生成规则为“{stream_id}/originimage/{当前日期}/json/*.txt”，文件名从“1.txt”开始依次编号。原始图JSON结构化信息绝对路径={用户输入挂载路径}+{origin_json_path}。
bounding_box	Object	人脸图在原始图中的位置信息。

bounding_box参数格式说明

字段	类型	说明
x	Int	矩形框左上角横坐标。
y	Int	矩形框左上角纵坐标。
w	Int	矩形框宽度。
h	Int	矩形框高度。

原始图的JSON字段说明：

JSON格式说明

字段	类型	说明
stream_id	String	摄像头编号。
event_type	Uint64	快速标识人脸提取算法的输出消息类型。原始图json消息固定为65537，对应16进制为 0x 0000 0000 0001 0001。
task_id	String	作业ID。
timestamp	Uint64	图片解码时间的时间戳。
message_id	String	本条数据的UUID。
image_base64	String	原始图Base64编码结果，输出类型为DIS、webhook时携带此字段。
data	Object	原始图业务输入内容。

data参数格式说明

字段

类型

说明

node_id

String

边缘节点编号。

origin_image_id

String

人脸原始图UUID。

image_path

String

原始图信息本地存储路径，仅当输出类型为LOCALPATH时携带此字段。

该路径（image_path）生成规则为“{stream_id}/originimage/{当前日期}/pic/*.jpg”，文件名从“1.jpg”开始依次编号。
原始图绝对路径={用户输入挂载路径}+{image_path}。

输出类型为LOCALPATH时，会根据用户的选择，将人脸图或者原始图存储在边缘节点上，图片和JSON结构化信息分开存储。具体存储路径按照如下规则创建：
- 人脸图JSON结构数据
   文件绝对路径={用户输入的挂载路径}/{stream_id}/faceimage/{当前日期}/json/*.txt
- 人脸图
   文件绝对路径={用户输入的挂载路径}/{stream_id}/faceimage/{当前日期}/pic/*.jpg
- 原始图JSON结构数据
   文件绝对路径={用户输入的挂载路径}/{stream_id}/originimage/{当前日期}/json/*.txt
- 原始图
   文件绝对路径={用户输入的挂载路径}/{stream_id}/originimage/{当前日期}/pic/*.jpg
- 文件名从1.txt或者1.jpg开始依次编号，人脸图或者原始图的JSON结构数据，与图片文件名相互对应。文件按照天存储，可以通过输入参数local_file_save_time对保存的天数进行控制，超期的文件将被自动删除。
- 当使用同一个摄像头下发多个视觉作业的时候，需要确保每一个作业的挂载路径不一样，否则不同任务的数据会写到同一个文件夹下，造成数据冲突。
- 当选择Localpath作为输出类型时，并且设置了发送原始图，挂载点路径需要有足够多的硬盘空间来保存原始图，否则会把挂载点的磁盘空间耗尽。

返回值

正常
 201

异常

返回值	说明
400 Bad Request	请求错误，具体返回错误码请参考错误码。
401 Unauthorized	鉴权失败。
403 Forbidden	没有操作权限。
404 Not Found	找不到资源。
500 Internal Server Error	服务内部错误。
503 Service Unavailable	服务不可用。

创建边缘人脸提取作业

功能介绍

调试

URI

请求

响应

提取结果

返回值

相关文档

意见反馈

文档内容是否对您有帮助？

7*24

备案

专业服务

退订

建议反馈

售前咨询热线