健康证识别API参数详解与最佳实践

适用场景与接口价值健康证从业人员健康检查合格证在餐饮、食品、公共卫生等行业中属于必须核验的证件。传统的人工录入方式耗时费力且容易出错。通过OCR光学字符识别接口可以自动从证件图片中提取姓名、发证机关、办证日期、发证日期、体检日期、有效日期共6个关键字段大幅提升信息采集效率。典型的应用场景包括HR入职材料自动录入批量处理新员工健康证自动填入人事系统。餐饮门店证件管理定期核验员工健康证有效期避免证件过期。监管平台数据对接将纸质健康证数字化用于合规检查。接口能力边界本接口为健康证识别ocr-health-cert提供结构化信息提取不包含证书真伪验证如防伪水印、印章鉴别。接口QPS限制为2次/秒适合中小规模调用。支持两种图片输入方式URL方式传入公网可访问的图片直链jpg/png。Base64方式将图片文件转换为Base64编码字符串可含data:image/xxx;base64,前缀。图片格式仅支持JPEG和PNG建议图片分辨率不低于600x400像素证件区域完整且无反光、遮挡。鉴权与请求头所有请求均需携带Authorization头格式为Bearer 你的 API Key。API Key需在开发者后台获取。另外Content-Type建议显式设为application/json虽然接口默认接受JSON但明确声明可避免部分HTTP客户端自动猜测错误。请求参数详解请求体为JSON对象包含两个必填字段字段名类型必填说明input_typestring是图片传输方式可选url或base64input_datastring是图片内容input_typeurl时为完整图片链接input_typebase64时为图片的Base64编码字符串可含Data URI前缀参数细节注意事项input_type 错误如果传入非url/base64的值如image服务器会返回参数校验错误。URL不可访问使用URL方式时确保图片链接无需额外鉴权且指向图片资源本身非网页。若链接返回404或非图片内容接口会报错。Base64过大Base64编码会增大数据体积约1/3建议图片大小控制在2MB以内否则可能触发请求体超限。curl 调用示例以下示例使用URL方式识别健康证请替换YOUR_API_KEY为真实Keycurl -sS -X POST \ -H Authorization: Bearer YOUR_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若使用Base64方式先获取图片的Base64字符串例如通过base64 health.jpg命令然后构造JSON# 假设图片Base64字符串保存在变量 $B64_STR 中 curl -sS -X POST \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d {\input_type\: \base64\, \input_data\: \$B64_STR\} \ https://v1.apizero.cn/api/ocr-health-cert注意在命令行中嵌入Base64字符串时若字符串包含特殊字符如、/需使用双引号包裹并转义内部引号。建议将JSON写入文件然后用-d file.json方式发送。Python 代码接入示例使用requests库调用更便于集成到后端服务import requests import base64 API_URL https://v1.apizero.cn/api/ocr-health-cert API_KEY your_api_key_here # 方式一URL上传 def recognize_by_url(image_url): headers { Authorization: fBearer {API_KEY}, Content-Type: application/json } payload { input_type: url, input_data: image_url } resp requests.post(API_URL, jsonpayload, headersheaders) return resp.json() # 方式二Base64上传 def recognize_by_base64(image_path): with open(image_path, rb) as f: b64_str base64.b64encode(f.read()).decode(utf-8) # 不含 data:image 前缀 headers { Authorization: fBearer {API_KEY}, Content-Type: application/json } payload { input_type: base64, input_data: b64_str } resp requests.post(API_URL, jsonpayload, headersheaders) return resp.json() # 调用示例 result recognize_by_url(https://example.com/health-cert.jpg) print(result)说明Base64方式建议不添加data:image/jpeg;base64,前缀接口兼容两种形式但去掉前缀可减少传输体积。若图片较大例如超过1MB建议先压缩再转换为Base64避免请求超时。返回值解读成功时HTTP状态码为200响应体JSON结构如下{ 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提示信息request_idstring本次请求唯一标识可用于排查问题dataobject识别结果对象包含6个字段字段名均为英文data.namestring持证人姓名data.issued_bystring发证机关名称data.date_of_handlingstring办证日期格式 yyyy-MM-dddata.date_of_issuestring发证日期data.date_of_medical_examinationstring体检日期data.valid_datestring有效日期注意部分字段可能因图片质量或证件版式差异而缺失。例如老版健康证可能没有“有效日期”此时valid_date会返回空字符串或null。建议业务层做兼容处理。日期一致性校验正常逻辑下日期应满足体检日期 ≤ 办证日期 ≤ 发证日期 ≤ 有效日期。如果业务需要校验可在拿到返回值后自行比对。常见错误与状态码HTTP状态码code值含义排查方向2000成功-2001001图片解析失败非图片或损坏检查图片格式、完整性2001002图片中未识别到健康证确认图片是否包含完整证件尝试提高分辨率2001003参数校验失败检查input_type取值、input_data非空401-鉴权失败检查Authorization头格式及API Key有效性413-请求实体过大压缩图片或使用URL方式429-请求频率超过限制QPS 2/s加入重试退避逻辑5xx-服务端错误联系技术支持携带request_id特别说明业务错误码如1001、1002均通过200状态码返回需通过code字段判断。不要单纯依赖HTTP状态码。工程化注意事项1. 图片预处理裁剪与矫正如果原始图片包含过多背景先裁剪至证件区域或使用透视变换矫正倾斜。色彩增强健康证底色多为白色或浅色可适当提高对比度使文字更清晰。去噪对于扫描件先进行椒盐噪声滤波。2. 批量调用与限流QPS上限为2如果需并发处理大量图片建议使用信号量或队列控制并发数。例如Python中使用asyncio.Semaphore(2)或threading.Semaphore(2)。调用间隔至少500ms。3. 重试机制对于返回code非0或HTTP 429/5xx的情况建议采用指数退避重试如第一次等待1秒第二次2秒第三次4秒最多重试3次。注意区分可重试错误与不可重试错误如参数错误不应重试。4. 数据缓存同一张图片短时间内重复识别结果应一致可将request_id或图片哈希值作为缓存键避免重复调用缓解QPS压力。5. 隐私合规健康证包含个人姓名、体检信息属于敏感数据。使用Base64方式时确保图片数据不在传输过程中泄露如使用HTTPS。存储识别结果时需遵循相关数据保护法规如《个人信息保护法》。参考文档健康证识别API官方文档https://apizero.cn/aidocs/ocr-health-cert原始文档Markdownhttps://apizero.cn/aidocs/ocr-health-cert/raw.md