适用场景健康证从业人员健康检查合格证明是餐饮、食品、公共场所等行业必备的证件。实际业务中经常需要批量核验健康证信息例如HR 在入职环节自动录入员工姓名、证件有效期餐饮管理平台定期检查员工健康证是否过期监管机构线上核验电子健康证真实性。通过 OCR 技术结构化识别健康证可以将人工录入效率提升 80% 以上同时降低误填风险。接口能力边界本接口slug:ocr-health-cert专注识别中国大陆地区健康证支持提取以下 6 个字段字段中文含义示例值name姓名张三issued_by发证机关XX市卫生健康委员会date_of_handling办证日期2024-01-15date_of_issue发证日期2024-01-20date_of_medical_examination体检日期2024-01-10valid_date有效日期2025-01-19输入限制图片格式JPG 或 PNG输入方式公网图片 URL 或图片 Base64 编码建议证件图片完整、清晰、无反光、无遮挡QPS2 次/秒超过会返回限流错误。接口鉴权与请求头调用该接口需要携带有效的 API Key。鉴权方式有两种二选一使用Authorization头Authorization: Bearer 你的 API Key使用X-API-Key头X-API-Key: 你的 API Key本文示例采用此方式此外Content-Type必须设为application/json。请求体参数请求体为 JSON Object包含两个必填字段参数名类型必填说明input_typestring是url或base64input_datastring是当input_typeurl时填图片的完整 http/https 链接当input_typebase64时填图片的 Base64 字符串可包含data:image/xxx;base64,前缀引擎会自动去除请求示例{ input_type: url, input_data: https://example.com/health-cert.jpg }curl 请求示例以下命令使用环境变量APIZERO_API_KEY存储你的 API Key请确保已设置export APIZERO_API_KEYyour_api_key_here curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {input_type: url, input_data: https://example.com/health-cert.jpg} \ https://v1.apizero.cn/api/ocr-health-cert执行后将直接输出 JSON 格式的响应。如果图片是本地文件可以先转为 Base64 再传输# 先获取图片 base64不带换行 BASE64$(base64 -w0 /path/to/health-cert.jpg) curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {input_type: base64, input_data: $BASE64} \ https://v1.apizero.cn/api/ocr-health-certPython 代码示例使用requests库代码简洁易读import requests import base64 API_URL https://v1.apizero.cn/api/ocr-health-cert API_KEY your_api_key_here # 替换为真实 Key def recognize_health_cert_from_url(image_url: str) - dict: 通过图片 URL 识别健康证 headers { X-API-Key: API_KEY, Content-Type: application/json } payload { input_type: url, input_data: image_url } resp requests.post(API_URL, jsonpayload, headersheaders, timeout15) resp.raise_for_status() return resp.json() def recognize_health_cert_from_base64(image_path: str) - dict: 通过本地图片文件 Base64 识别 with open(image_path, rb) as f: img_b64 base64.b64encode(f.read()).decode(utf-8) headers { X-API-Key: API_KEY, Content-Type: application/json } payload { input_type: base64, input_data: img_b64 } resp requests.post(API_URL, jsonpayload, headersheaders, timeout20) resp.raise_for_status() return resp.json() # 使用示例 result recognize_health_cert_from_url(https://example.com/health-cert.jpg) print(result)响应字段解读成功响应的状态码为200code为0。示例{ code: 0, msg: 成功, request_id: req_abc123, data: { name: 张三, issued_by: XX市卫生健康委员会, date_of_handling: 2024-01-15, date_of_issue: 2024-01-20, date_of_medical_examination: 2024-01-10, valid_date: 2025-01-19 } }字段说明字段类型含义codeint业务状态码0 表示成功非 0 表示出错见错误处理msgstring与code对应的提示信息request_idstring本次请求的唯一标识可用于排查问题data.namestring持证人姓名data.issued_bystring发证机关全称data.date_of_handlingstring办证日期YYYY-MM-DDdata.date_of_issuestring发证日期YYYY-MM-DDdata.date_of_medical_examinationstring体检日期YYYY-MM-DDdata.valid_datestring有效截止日期YYYY-MM-DD注意当图片质量非常差或非健康证时data中部分字段可能为空字符串业务侧需要做兜底处理。常见错误码与排查codemsg常见值原因与解决1001参数错误请求体缺少input_type或input_data或类型不匹配1002授权失败API Key 无效、过期或未携带1003图片下载失败input_typeurl时提供的图片地址无法访问超时、404 等1004图片解析失败图片非 JPG/PNG 或 Base64 编码错误1005未识别到健康证图片内容不是健康证或证件关键区域模糊1006QPS 超限请求频率超过 2 次/秒降低并发或增加间隔1007服务器内部错误临时故障可稍后重试错误响应示例{ code: 1001, msg: 参数错误input_type 必须为 url 或 base64, request_id: req_error_001 }工程化注意事项图片预处理建议在上传前将图片压缩至 2MB 以内宽度 2000px 左右即可过大的图片会增加传输耗时且识别速度无明显提升。Base64 去前缀如果客户端已经携带data:image/jpeg;base64,前缀引擎会智能去除但建议统一使用纯 Base64 字符串以减小请求体。超时设置网络请求建议设置 15~30 秒超时避免因图片下载过慢导致连接挂起。错误重试对于code1007服务端错误或code1003图片下载失败可能是网络抖动可实现指数退避重试策略最多 3 次。QPS 控制如果并发量超过 2 QPS可引入本地限流如令牌桶或排队机制避免触发限流错误。字段校验返回的日期字段建议做合法性二次校验如是否在合理时间范围内因为 OCR 可能识别出不合理日期如 2099 年。安全建议API Key 不要硬编码在客户端代码中应通过环境变量或配置中心注入生产环境建议使用 HTTPS 传输。参考文档健康证识别 API 官方文档