人像质检(算法编码：8000110035)

接口信息

API Path
/aipaas/living/v1/portrait/detectionQuality

请求协议
HTTPS

请求方法
POST

请求头部 ：

头部标签	必填	说明	类型	数据字典	限制	头部内容	示例
Content-Type	是	内容类型				application/json	application/json
X-APP-ID	是	控制台--应用管理--创建应用--AppID
Device-Uuid	是	设备管理-设备uuid
Authorization	是	鉴权信息

请求参数 Json
Object

参数名	说明	必填	类型	数据字典	限制	示例
code	请求状态码，固定1025	是	[int]		0	1025
data	算法参数	是	[object]		0
data>>task_id	算法任务id【调用traceId，需要保证唯一，生成UUID传入就可以】	是	[string]		0	0d04322bee08401a9c15a5ef8643e64f
data>>camera_id	设备编码【调用设备编码，如果为视频流抽帧后的算法可以传入对应设备编码，如果没有可以传入任意值】	是	[string]		0	A15414521025
data>>algo_tasks	算法参数数组	是	[array]		0
data>>algo_tasks>>image	图片Base64	否	[string]		0	iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAMAAADXqc3KAAAAFVBMVEX////7ODj+z8/9eHj9m5v9s7P7TEwZgBMVAAAACXBIWXMAAAsTAAALEwEAmpwYAAAATklEQVQokd2NQQqAQAzEMjNd//9kUXEXFw8eBMEcCiUlha9p8lspC6ukwDZHeBcBNcvUJICkAjwVheV2k4pUkMvzWo5U307kLiSNkz+wAvF5AMTthEMUAAAAAElFTkSuQmCC
data>>algo_tasks>>algo_config	单个参数信息	是	[object]		0
data>>algo_tasks>>algo_config>>version	参数版本号	否	[string]		0	1.0.0
data>>algo_tasks>>algo_config>>algo_roi	roi区域配置【如果算法不支持roi，忽略此参数解析】	是	[object]		0
data>>algo_tasks>>algo_config>>algo_roi>>roi_type	roi坐标类型，1-绝对坐标，2-相对坐标	是	[int]	1:绝对坐标,2:相对坐标	0	1
data>>algo_tasks>>algo_config>>algo_roi>>roi_list	设定区域坐标列表【如果is_full_region为true，则传入空数组，否则只检测坐标区域内的信息(最多支持5个区域)】	否	[array]		0
data>>algo_tasks>>algo_config>>algo_roi>>roi_list>>name	区域id【可随意生成，保证全局唯一即可】	是	[string]		0	head
data>>algo_tasks>>algo_config>>algo_roi>>roi_list>>point_list	区域坐标点集【最小3个点，最大支持11个点】	是	[array]		0
data>>algo_tasks>>algo_config>>algo_roi>>roi_list>>point_list>>x	X轴坐标	是	[float]		0	0.0
data>>algo_tasks>>algo_config>>algo_roi>>roi_list>>point_list>>y	Y轴坐标	是	[float]		0	1.0
data>>algo_tasks>>algo_config>>algo_roi>>roi_list>>extra_params	区域扩展参数	否	[array]		0
data>>algo_tasks>>algo_config>>algo_roi>>roi_list>>extra_params>>key	参数名	是	[string]		0	type
data>>algo_tasks>>algo_config>>algo_roi>>roi_list>>extra_params>>value	参数值	是	[string]		0	1
data>>algo_tasks>>algo_config>>algo_roi>>is_full_region	是否全景图【true-是，false-否】	是	[boolean]	true:是,false:否	0	true
data>>algo_tasks>>algo_config>>algo_roi>>region_mode	区域模式【固定为1】	是	[int]	1:检测框中心点在区域内即代表检测目标在区域内,2:检测框脚点在区域内即代表检测目标在区域内,3:检测框中心点与脚点同时在区域内即代表检测目标在区域内,4:检测框中心点或脚点在区域内即代表检测目标在区域内	0	1
data>>algo_tasks>>algo_config>>extra_params	算法定制化参数	否	[array]		0	[{"key":"algo_type","value":"7009"},{"key":"threshold","value":"0.65"},{"key":"warningCount","value":"2"}]
data>>algo_tasks>>algo_config>>extra_params>>key	参数名	是	[string]		0	algo_type
data>>algo_tasks>>algo_config>>extra_params>>value	参数值	是	[string]		0	示例： 0.8
data>>extra_params	算法全局定制化参数	是	[array]		0
data>>extra_params>>key	参数名	是	[string]		0
data>>extra_params>>value	参数值	是	[string]		0

响应内容 ：

返回结果

成功 (200)
Json
Object

参数名	说明	必填	类型	数据字典	限制	示例
code	算法类型，固定1026	是	[int]		0	1026
data	算法调用结果	是	[object]		0
data>>error_code	错误码，值为APP_ERR_OK则为成功	是	[string]		0	APP_ERR_OK
data>>error_message	错误描述	是	[string]		0	正常状态
data>>camera_id	创建任务时传入的设备编码	是	[string]		0	A15414521025
data>>task_id	创建任务时传入的算法任务id	是	[string]		0	0d04322bee08401a9c15a5ef8643e64f
data>>frame_width	图片宽度像素	是	[string]		0	1920
data>>frame_height	图片高度像素	是	[string]		0	1080
data>>algo_outputs	算法处理结果数组	是	[array]		0
data>>algo_outputs>>roi_message	设定区域信息【全图解析默认返回全图区域】	是	[object]		0
data>>algo_outputs>>roi_message>>name	创建任务时传入的区域id【全图解析固定为position_0】	是	[string]		0	position_0
data>>algo_outputs>>roi_message>>point_list	创建任务时传入的区域坐标点集【全图解析固定为：[{"x": 0,"y": 0},{"x": 宽度像素,"y": 0},{"x": 宽度像素,"y": 高度像素},{"x": 0,"y": 高度像素}]】	是	[array]		0	[{"x": 0,"y": 0},{"x": 2560,"y": 0},{"x": 2560,"y": 1440},{"x": 0,"y": 1440}]
data>>algo_outputs>>roi_message>>point_list>>x	创建任务时传入的X轴坐标	是	[float]		0	0.0
data>>algo_outputs>>roi_message>>point_list>>y	创建任务时传入的Y轴坐标	是	[float]		0	1.0
data>>algo_outputs>>roi_message>>extra_params	创建任务时传入的区域其他参数【不存在参数时返回空数组】	否	[array]		0
data>>algo_outputs>>roi_message>>extra_params>>key	创建任务时传入的参数名【是否告警参数名固定为alarm】	是	[string]		0	alarm
data>>algo_outputs>>roi_message>>extra_params>>value	创建任务时传入的参数值【是否告警固定为1或者0】	是	[string]		0	1
data>>algo_outputs>>objectinfo	检测到的目标对象数组【未检测到目标时返回空数组】	是	[array]		0
data>>algo_outputs>>objectinfo>>class_name	目标类别名称【值必须为英文小写字母且遵循蛇形命名法(单词下划线分割)】	是	[string]		0	non_vehicle
data>>algo_outputs>>objectinfo>>class_id	目标类别id	是	[int]		0	1
data>>algo_outputs>>objectinfo>>rect	目标位置坐标	是	[object]		0
data>>algo_outputs>>objectinfo>>rect>>x0	左上X轴坐标	是	[float]		0	0.0
data>>algo_outputs>>objectinfo>>rect>>y0	左上Y轴坐标	是	[float]		0	0.0
data>>algo_outputs>>objectinfo>>rect>>x1	右下X轴坐标	是	[float]		0	100.0
data>>algo_outputs>>objectinfo>>rect>>y1	右下Y轴坐标	是	[float]		0	100.0
data>>algo_outputs>>objectinfo>>confidence	目标置信度(0~1)	是	[float]		0	0.99
data>>algo_outputs>>objectinfo>>track_id	目标追踪ID【不存在则固定返回空字符串】	是	[string]		0	1
data>>algo_outputs>>objectinfo>>score	目标得分(0~1)【不存在则固定返回-1】	是	[float]		0	0.99
data>>algo_outputs>>objectinfo>>extra_message	目标额外信息【不存在则固定返回空数组】	否	[array]		0
data>>algo_outputs>>objectinfo>>extra_message>>key	参数名	是	[string]		0	type
data>>algo_outputs>>objectinfo>>extra_message>>value	参数值	是	[string]		0	1
data>>algo_outputs>>objectinfo>>image_message	目标图片信息【不存在则固定返回空数组】	否	[array]		0
data>>algo_outputs>>objectinfo>>image_message>>key	图片名称	是	[string]		0	xxx.jpg
data>>algo_outputs>>objectinfo>>image_message>>value	图片Base64【jpeg格式base64编码】	是	[string]		0	iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAMAAADXqc3KAAAAFVBMVEX////7ODj+z8/9eHj9m5v9s7P7TEwZgBMVAAAACXBIWXMAAAsTAAALEwEAmpwYAAAATklEQVQokd2NQQqAQAzEMjNd//9kUXEXFw8eBMEcCiUlha9p8lspC6ukwDZHeBcBNcvUJICkAjwVheV2k4pUkMvzWo5U307kLiSNkz+wAvF5AMTthEMUAAAAAElFTkSuQmCC
data>>algo_outputs>>objectinfo>>feature	特征值，float数组【特征提取算法必返回】	否	[array]		0	[0.0620517209172249, 0.0471773408353329]
data>>algo_outputs>>objectinfo>>attribute	属性值数组【分类属性列表】	否	[array]		0
data>>algo_outputs>>objectinfo>>attribute>>key	属性名称	是	[string]		0	sex
data>>algo_outputs>>objectinfo>>attribute>>value	属性值	是	[string]		0	1
data>>algo_outputs>>objectinfo>>attribute>>score	属性置信度(0~1)【不存在则固定返回-1】	是	[float]		0	0.99
data>>extra_message	算法处理结果额外信息，透传给上层应用	否	[array]		0
data>>extra_message>>key	参数名【如果为多算法镜像，固定返回算法标识的key必须为algo_type】	是	[string]		0	algo_type
data>>extra_message>>value	参数值【如果为多算法镜像，值为具体算法标识】	是	[string]		0	7009

成功示例

{
    "code": 1020,
    "data": {
        "error_code": "APP_ERR_OK",
        "error_message": "",
        "camera_id": "222",
        "task_id": "111",
        "frame_id": "0",
        "frame_width": "2560",
        "frame_height": "1440",
        "send_pts_ms": "1718245892700",
        "pull_pts_ms": "0",
        "display_image": "",
        "algo_outputs": [{
            "roi_message": {
                "name": "position_0",
                "point_list": [{
                        "x": 0,
                        "y": 0
                    },
                    {
                        "x": 2560,
                        "y": 0
                    },
                    {
                        "x": 2560,
                        "y": 1440
                    },
                    {
                        "x": 0,
                        "y": 1440
                    }
                ],
                "extra_params": []
            },
            "objectinfo": [{
                "class_name": "face",
                "class_id": 1,
                "rect": {
                    "x0": 2311,
                    "y0": 881,
                    "x1": 2426,
                    "y1": 1119
                },
                "confidence": -1,
                "track_id": "",
                "score": -1,
                "extra_message": [{
                        "key": "is_bigpose",
                        "value": "1"
                    }, {
                        "key": "is_blur",
                        "value": "1"
                    }, {
                        "key": "is_close_eyes",
                        "value": "1"
                    }, {
                        "key": "is_face_complete",
                        "value": "1"
                    }, {
                        "key": "is_hatless",
                        "value": "1"
                    }, {
                        "key": "is_occlusion",
                        "value": "1"
                    }, {
                        "key": "is_open_mouth",
                        "value": "1"
                    },
                    {
                        "key": "is_sideface",
                        "value": "0"
                    },
                    {
                        "key": "is_glasses",
                        "value": "0"
                    }, {
                        "key": "lighting",
                        "value": "1"
                    }, {
                        "key": "landmark",
                        "value": "[260, 276, 259, 306, 261, 334, 263, 361, 266, 387, 269, 413, 273, 438, 280, 461, 289, 481, 300, 498, 313, 512, 328, 524, 343, 535, 357, 546, 372, 556, 388, 563, 405, 565, 423, 563, 439, 556, 455, 546, 470, 535, 485, 524, 500, 512, 514, 498, 527, 481, 537, 461, 545, 439, 551, 414, 555, 388, 559, 361, 562, 334, 564, 306, 564, 275, 286, 293, 294, 284, 304, 278, 329, 275, 355, 278, 377, 293, 352, 294, 328, 291, 306, 291, 463, 280, 491, 277, 518, 282, 528, 289, 536, 299, 515, 295, 491, 293, 466, 296, 441, 296, 310, 333, 324, 324, 342, 321, 359, 328, 369, 343, 354, 344, 339, 345, 323, 341, 344, 332, 344, 332, 448, 345, 459, 330, 477, 323, 495, 326, 510, 336, 496, 344, 480, 347, 464, 347, 477, 335, 477, 335, 410, 329, 409, 362, 408, 395, 407, 428, 389, 342, 376, 403, 369, 423, 381, 438, 394, 443, 407, 446, 420, 444, 434, 440, 447, 425, 440, 405, 430, 343, 351, 466, 370, 464, 389, 461, 410, 464, 432, 461, 451, 463, 471, 466, 456, 481, 440, 491, 410, 498, 381, 491, 365, 481, 356, 468, 384, 473, 410, 476, 437, 473, 465, 468, 437, 474, 410, 477, 384, 474]"
                    },
                    {
                        "key": "overall_score",
                        "value": "66"
                    }
                ],
                "image_message": [],
                "feature": [],
                "attribute": []
            }]
        }],
        "extra_message": []
    }
}

1、能力简介

基于图片对人像进行质检服务

2、修订历史

修订日期	算法版本号	修订内容
2026-01-21	V1.2.0	首版本发布

3、服务鉴权

服务接口调用时需要严格遵循服务鉴权规则，服务调用鉴权规则请参见：开发指南 - 接口签名认证。

4、请求参数说明

4.1、区域配置

不支持区域配置，请按全图模式传入，如果传入algo_config或algo_roi有问题，会返回报错，但是部分报错缺少描述信息，可通过错误码识别。algo_roi固定值为：

{
    "is_full_region": true,
    "roi_type": 1,
    "region_mode": 1,
    "roi_list": []
}

4.2、请求扩展参数说明

参数路径： data->algo_tasks->algo_config->extra_params

参数中文名	参数名称(key)	参数值(value)	必填	内部数据类型	备注

4.3、其他参数说明

5、响应结果说明

5.1、目标信息说明

5.1.1、目标类别

类别中文名	类别id(class_id)	类别编码(class_name)	类别说明	属性中文名	属性名称(attribute->key)	属性值(attribute->value)	属性内部数据类型	属性说明
人像	1	face

5.1.2、目标扩展参数

参数路径： data->algo_outputs->objectinfo->extra_message

类别中文名	类别编码(class_name)	参数中文名	参数名称(key)	参数值(value)	必填	内部数据类型	备注
关键点	landmark	关键点	landmark	value为一个包含212个数字的字符串，逗号间隔。[x0,y0,x1,y1.....]	否	string
是否遮挡	is_occlusion	是否遮挡	is_occlusion	value为"1"表示是，"0"表示否	否	string
是否模糊	is_blur	是否模糊	is_blur	value为"1"表示是，"0"表示否	否	string
是否免冠	is_hatless	是否免冠	is_hatless	value为"1"表示是，"0"表示否	否	string
是否闭眼	is_close_eyes	是否闭眼	is_close_eyes	value为"1"表示是，"0"表示否	否	string
亮度	lighting	亮度	lighting	value：0：过暗，1：正常 ，2：过亮	否	string
是否张嘴	is_open_mouth	是否张嘴	is_open_mouth	value为"1"表示是，"0"表示否	否	string
是否大角度	is_bigpose	是否大角度	is_bigpose	value为"1"表示是，"0"表示否	否	string	是否非正脸，is_bigpose的返回值可以用于非正脸判断，非正脸为1，正脸为0.
五官是否齐全	is_face_complete	五官是否齐全	is_face_complete	value为"1"表示是，"0"表示否	否	string
是否侧脸	is_sideface	是否侧脸	is_sideface	value为"1"表示是，"0"表示否	否	string
是否带眼镜	is_glasses	是否带眼镜	is_glasses	value为"1"表示是，"0"表示否	否	string
人像质检评分	overall_score	人像质检评分	overall_score	value为数字，整数	否	string

5.1.3、向量维度说明

参数路径： data->algo_outputs->objectinfo->feature

5.2、区域扩展参数说明

参数路径： data->algo_outputs->roi_message->extra_params

5.3、响应扩展参数说明

参数路径： data->extra_message

5.4、其他参数说明

• 全图模式，目标区域(data->algo_outputs->roi_message)固定返回全图坐标

6、请求示例

{
    "code": 1019,
    "data": {
        "camera_id": "cameraId",
        "task_id": "xxx",
        "algo_tasks": [
            {
                "algo_config": {
                    "algo_roi": {
                        "is_full_region": true,
                        "roi_type": 1,
                        "roi_list": []
                    },
                    "extra_params": []
                }
            }
        ],
        "image": ""
    }
}

7、状态码说明

状态码	状态描述	英文描述	对应数字编码
APP_ERR_OK	正常状态	ok	0
APP_ERR_FAILURE	系统异常	error	-1
APP_PAGRAM_ERR_FAILURE	参数异常	Invalid parameter	10
APP_ERR_COMM_FAILURE	失败	General Failed	1001
APP_ERR_COMM_INNER	内部错误	Internal error	1002
APP_ERR_COMM_INVALID_POINTER	无效指针	Invalid Pointer	1003
APP_ERR_COMM_INVALID_PARAM	无效参数	Invalid parameter	1004
APP_ERR_COMM_UNREALIZED	未实现	Not implemented	1005
APP_ERR_COMM_OUT_OF_MEM	内存溢出	Out of memory	1006
APP_ERR_COMM_ALLOC_MEM	内存分配错误	memory allocation error	1007
APP_ERR_COMM_FREE_MEM	内存释放错误	free memory error	1008
APP_ERR_COMM_OUT_OF_RANGE	内存越界	out of range	1009
APP_ERR_COMM_NO_PERMISSION	无权限	NO Permission	1010
APP_ERR_COMM_TIMEOUT	超时	Timed out	1011
APP_ERR_COMM_NOT_INIT	未初始化	Not initialized	1012
APP_ERR_COMM_INIT_FAIL	初始化错误	initialize failed	1013
APP_ERR_COMM_INPROGRESS	操作正在进行中	Operation now in progress	1014
APP_ERR_COMM_EXIST	资源已存在	Object; file or other resource already exist	1015
APP_ERR_COMM_NO_EXIST	资源不存在	Object; file or other resource doesn't exist	1016
APP_ERR_COMM_BUSY	资源在使用中	Object; file or other resource is in use	1017
APP_ERR_COMM_FULL	无可用资源	No available Device or resource	1018
APP_ERR_COMM_OPEN_FAIL	文件或资源打开失败	Device; file or resource open failed	1019
APP_ERR_COMM_READ_FAIL	文件或资源读失败	Device; file or resource read failed	1020
APP_ERR_COMM_WRITE_FAIL	文件或资源写失败	Device; file or resource write failed	1021
APP_ERR_COMM_DESTORY_FAIL	文件或资源释放失败	Device; file or resource destory failed	1022
APP_ERR_COMM_EXIT	数据流结束，退出程序	End of data stream; stop the application	1023
APP_ERR_COMM_CONNECTION_CLOSE	连接断开	Out of connection; Communication shutdown	1024
APP_ERR_COMM_CONNECTION_FAILURE	连接失败	connection fail	1025
APP_ERR_COMM_STREAM_INVALID	无效流	ACL stream is null pointer	1026
APP_ERR_COMM_REGION_ERROR	区域校验失败	region error	1027
APP_ERR_COMM_DECODE_FAIL	图片解码失败	Image decode fail	1028
APP_ERR_COMM_MODELINIT_FAIL	模型初始化失败	Model init fail	1029
APP_ERR_COMM_MODELINFER_FAIL	模型推理失败	Model infer fail	1030
APP_ERR_COMM_PARAM_FAILURE	参数校验失败	param check fail	1031
APP_ERR_STREAMPULLER_BASE	拉流模块（视频流有效）	For StreamPuller	2000
APP_ERR_STREAMPULLER_OPEN_FAIL	流打开失败（视频流有效）（视频流有效）	Open input stream failed	2001
APP_ERR_STREAMPULLER_STREAMINFOFIND_FAIL	查找流信息失败（视频流有效）	Find stream information failed	2002
APP_ERR_STREAMPULLER_EOF	流结束（视频流有效）	Stream if EOF	2003
APP_ERR_STREAMPULLER_READFRAME_FAIL	读取帧失败（视频流有效）	Stream read error frame	2004
APP_ERR_STREAMPULLER_REOPEN_FAIL	重新打开流失败（视频流有效）	Reopen input stream failed	2005
APP_ERR_STREAMPULLER_STREAMFIND_FAIL	查找视频channel失败（视频流有效）	Find no video stream	2006
APP_ERR_STREAMPULLER_STREAMFORMAT_ERROR	不支持的视频格式（视频流有效）	Stream is unsupported video format	2007
APP_ERR_VIDEODECODER_BASE	解码模块（视频流有效）	For Videodecoder	2020
APP_ERR_VIDEODECODER_CREATE_FAIL	创建解码器失败（视频流有效）	Create MxBase::VideoDecoder Exception	2021
APP_ERR_VIDEODECODER_UNSUPPORT_FORMAT	不支持的视频格式（视频流有效）	Stream is unsupported video format	2022
APP_ERR_VIDEODECODER_DECODE_FAIL	视频解码失败（视频流有效）	decode fail	2023
APP_ERR_CONFIG_BASE	参数配置	For modulebase	2040
APP_ERR_CONFIG_ADD_FAIL	添加参数失败	Add new algo config failed	2041
APP_ERR_CONFIG_UPDATE_FAIL	更新参数失败	update config failed	2042
APP_ERR_CONFIG_DELETE_FAIL	删除参数失败	delete config failed	2043
APP_ERR_QUEUE_BASE	队列		5000
APP_ERR_QUEUE_EMPTY	队列为空	Queue: empty queue	5001
APP_ERR_QUEUE_STOPED	队列已停止	Queue: queue stoped	5002
APP_ERR_QUEUE_FULL	队列满	Queue: full queue	5003