文档首页> 园区智能体 CampusGo> API参考> 云上服务API> 云上人脸提取> 创建云上人脸提取作业

更新时间：2022-03-17 GMT+08:00

查看PDF

创建云上人脸提取作业

功能介绍

该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。

参数	类型	说明
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。

返回值

正常
 201

异常

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

父主题： 云上人脸提取

上一篇：云上人脸提取

下一篇：查询作业列表

意见反馈

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

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！您可在我的云声建议查看反馈及问题处理状态。

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消

如您有其它疑问，您也可以通过华为云社区问答频道来与我们联系探讨

智能客服提问云社区提问

创建云上人脸提取作业

功能介绍

调试

URI

请求

响应

提取结果

返回值

相关文档

相关产品

意见反馈

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

7*24

备案

专业服务

退订

建议反馈

售前咨询热线