为帮助大家在证件照上传、制作、审核和交付环节更高效地判断照片是否符合目标规格要求，现已发布「证件照合规性检测」接口。该接口可根据指定规格或自定义检测参数，对证件照尺寸、背景、构图、人像姿态、画质光照、遮挡表情、服装饰品等项目进行检测，并返回总检测结果及逐项检测明细。
适用场景
存量照片检测：对用户线下拍摄、历史留存或其他平台制作的证件照进行检测，判断是否满足目标规格要求。
批量照片审核：学校、机构等场景中，可对学生或其他人员集中提交的照片进行批量检测，减少人工逐张审核。
严格规格照片预检：证件照回执、考试报名照等审核要求较严格的照片，可在提交前先调用接口检测，提前发现尺寸、背景、人像比例、画质等不合规问题。
自有制作能力补充：已自建证件照制作功能的业务系统，可接入检测接口进行预检或复核，补充尺寸、背景、人像姿态、遮挡、画质等检测能力。
检测能力
接口支持通过 规格 ID 调用平台规格库，也支持传入宽高、DPI、文件大小、背景色、人像比例等自定义参数，满足不同业务系统的检测需求。
| 检测维度 | 主要检测内容 |
|---|---|
| 规格参数 | 照片宽高、DPI、文件大小、文件格式、背景色、纯色背景等。 |
| 人像构图 / 位置比例 | 人脸宽度、头部高度、双眼间距、头顶距离、眼睛到下边缘距离等比例检测。 |
| 姿态与完整性 | 头部缺失、上半身、肩膀水平、低头抬头、左右转头、歪头倾斜等检测。 |
| 画质与光照 | 阴阳脸、面部清晰度、面部亮度、面部曝光、美颜精修等检测。 |
| 遮挡与表情 | 头发遮挡肩膀、头发遮挡眉毛、口罩、面部遮挡、闭眼或未直视镜头、耳朵、张嘴等检测。 |
| 服装与饰品 | 着装、衣着暴露、浅色衣服、帽子、眼镜、耳机、项链、耳饰、头饰等检测。 |
接入方式
接口名称 证件照合规性检测
请求地址 POST https://api.zjzapi.com/idphoto/check
请求类型 application/x-www-form-urlencoded
返回格式 JSON
接口费用 检测成功扣除 0.012 元调用接口时需传入应用 key 和 base64 后的图片内容。图片大小不超过 3M，尺寸小于 2000×2000。
| 参数类型 | 参数名称 | 说明 |
|---|---|---|
| 基础参数 | key | 应用的 key，必填。 |
| 基础参数 | image | base64 后的图片内容，必填。 |
| 规格参数 | item_id | 规格 ID。若提供规格 ID，宽高、DPI、文件大小、背景色等规格参数可省略。 |
| 自定义参数 | width_px、height_px、dpi、file_format 等 | 用于按自定义规则检测照片宽高、分辨率、格式、文件大小和背景色等要求。 |
| 检测开关 / 阈值 | face_pose_yaw、face_clarity、face_mask 等 | 用于控制人像姿态、清晰度、遮挡、服装饰品等检测项。 |
返回结果
接口返回 JSON 格式数据。检测成功时，返回结果中包含总检测结果 passed_status，以及各检测项的逐项结果 passed_list。接入方可根据逐项结果中的检测项 key、是否通过、提示信息和实际检测值，在业务系统中展示更明确的错误原因或处理建议。
| 返回字段 | 说明 |
|---|---|
| code | 状态码，0 表示成功，-1 表示错误。 |
| msg | 错误提示或检测提示。 |
| passed_status | 总检测结果，1 表示通过，0 表示不通过。 |
| passed_list | 各检测项结果，包含检测项 key、是否通过、提示信息和检测详情。 |
接入建议
建议根据自身业务流程选择检测节点：如面向用户的上传页面，可在上传后立即调用接口并展示不合规原因；如面向后台审核系统，可在订单进入审核前进行自动检测，并将检测结果作为审核辅助信息。
如业务已接入证件照规格库，建议优先使用 item_id 进行检测，以减少规格参数维护成本；如存在自定义照片要求，可按接口文档传入对应检测参数。
完整接口文档：https://zjzapi.com/doc/check.html
