适用场景与业务价值健康证从业人员预防性健康检查合格证明在餐饮、食品加工、商超零售、家政服务等行业中属于高频查验证件。传统人工登记方式需要逐项抄录持证人姓名、发证机关和有效期不仅效率低还容易出现肉眼核对疏漏。健康证识别 API 可以通过一张图片结构化输出姓名、发证机关、办证日期、发证日期、体检日期、有效日期共 6 个字段直接对接后续业务系统。典型的落地场景包括餐饮门店员工健康证到期前自动预警替换原本依赖人工台账的巡检方式HR 入职材料批量录入将纸质健康证拍照上传后自动提取关键信息外卖骑手、家政服务人员的资质核验登记信息后自动比对有效期。接口能力边界在接入之前需要明确该接口能做什么、不能做什么维度说明输入方式支持公网图片 URL 和 base64 字符串两种方式图片格式jpg / png输出字段name姓名、issued_by发证机关、date_of_handling办证日期、date_of_issue发证日期、date_of_medical_examination体检日期、valid_date有效日期请求方法POST接口地址https://v1.apizero.cn/api/ocr-health-cert默认 QPS2 / s接口只负责识别并返回结构化文本不做证件真伪核验也不返回证件照片或额外的置信度分数。图片中如果存在遮挡、反光、倾斜识别结果可能不完整需要在上传前做前置检查。请求参数详解鉴权方式调用接口时需要携带 API Key。事实卡中 curl 示例使用的是X-API-Key请求头而参数说明中给出的鉴权头是Authorization: Bearer 你的 API Key。两种方式以实际文档为准建议在项目中将 API Key 放入环境变量避免硬编码在代码仓库中。Header 参数参数名是否必填类型说明Authorization是stringBearer 后面拼接你的 API KeyContent-Type否string请求体格式通常设为application/jsonBody 参数请求体是一个 JSON 对象包含两个必填字段字段名类型是否必填说明input_typestring是图片传输方式url表示公网图片地址base64表示图片的 base64 编码input_datastring是图片内容。input_typeurl时填 http/https 链接input_typebase64时填 base64 字符串可以带data:image/xxx;base64,前缀注意 body 参数说明中展示的是数组结构[{...}]而 curl 示例中直接使用的是 JSON 对象。实际调用时以对象形式传参即可数组外层通常用于描述多组请求体的情况不是最终请求格式。零基础接入curl 快速验证下面通过 curl 发起一次真实请求。把脚本中的 API Key 换成你自己的密钥图片地址改为实际可访问的公网图片链接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如果服务端要求Authorization头则需要替换为curl -sS \ -X POST \ -H Authorization: Bearer $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-certcurl 的好处是可以在命令行快速验证接口连通性确认鉴权和参数无误后再进入代码编写阶段。Python 代码接入示例实际业务开发中更多场景需要把图片转换为 base64 后上传尤其是从移动端直接拍摄、图片尚未上传到公网的情况。下面给出一个完整的 Python 示例import base64 import os import requests def encode_image_to_base64(image_path: str) - str: 读取本地图片并转为 base64 字符串不含前缀 with open(image_path, rb) as f: return base64.b64encode(f.read()).decode(utf-8) def recognize_health_cert(image_path: str, api_key: str) - dict: api_url https://v1.apizero.cn/api/ocr-health-cert b64_data encode_image_to_base64(image_path) headers { Authorization: fBearer {api_key}, Content-Type: application/json, } payload { input_type: base64, input_data: b64_data, } resp requests.post(api_url, headersheaders, jsonpayload, timeout10) resp.raise_for_status() return resp.json() if __name__ __main__: key os.environ.get(APIZERO_API_KEY, ) result recognize_health_cert(./health_cert.jpg, key) print(result)这段代码做了三件事读取本地图片转 base64、构造请求体、解析 JSON 响应。实际项目中建议把requests.post封装成独立函数并补充超时重试逻辑。返回字段逐项解析成功时接口返回 HTTP 200响应体示例{ code: 0, 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 }, msg: 成功, request_id: req_abc123 }字段说明如下字段类型业务含义codeint业务状态码0 表示成功msgstring状态描述request_idstring本次请求唯一标识排查问题时可以提供给服务方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是使用频率最高的字段可用于到期提醒和资格校验。例如判断健康证是否在有效期内from datetime import date valid_date result[data][valid_date] today date.today().isoformat() is_valid valid_date today print(证件状态, 有效 if is_valid else 已过期)注意这里只做字符串格式的日期比较前提是接口返回的日期格式始终保持YYYY-MM-DD。如果返回了空字符串或null说明图片中对应区域未能识别成功。常见错误与排查思路1. HTTP 401 Unauthorized原因API Key 缺失、头部字段名不对或请求头格式错误。排查步骤检查请求头中是X-API-Key还是Authorization: Bearer以最新文档为准确认环境变量APIZERO_API_KEY已正确设置且未包含多余空格使用 curl 去掉-sS参数查看完整响应体。2. HTTP 400 Bad Request原因请求体 JSON 格式错误、缺少必填字段、图片链接不可访问。排查步骤使用 JSON 校验工具检查 payload 是否合法确认同时传入了input_type和input_data两个字段如果input_typeurl手动在浏览器中打开图片链接确认可以正常访问且未做防盗链限制如果input_typebase64确认字符串没有包含换行符且未误传文件路径。3. 返回 code 非 0原因可能是图片模糊、格式不支持或识别失败。排查步骤检查图片是否为 jpg 或 png 格式确认图片没有过度压缩建议图片短边不小于 500 像素尝试对图片做裁剪只保留健康证主体区域后重新调用把request_id记录下来向技术支持反馈时一并提供以便定位问题。4. 响应超时原因图片体积过大、网络波动或接口负载较高。排查步骤在代码中将请求超时时间设置为 10 到 30 秒base64 传输时图片文件大小建议控制在 5MB 以内在服务端对图片做等比压缩后再编码减少传输耗时。工程化注意事项图片预处理接口对图片质量有一定要求。真实场景中用户用手机拍摄的健康证经常存在以下问题背景杂乱证件区域占比小倾斜角度超过 30 度塑料封套反光导致文字区域发白闪光灯直射造成的过曝。建议在调用前做一个简单的质量检查证件区域面积占比不低于 40%亮度直方图中高光像素占比不要超过 20%。如果条件允许可以先用 OpenCV 做边缘检测和透视矫正再送入 OCR 接口。超时与重试策略接口默认 QPS 为 2/s意味着每秒最多处理 2 个请求。面对批量导入任务时不能直接并发请求否则容易触发限流。建议采用以下策略单次请求超时设置为 10 秒对返回 5xx 或网络异常的情况采用指数退避重试间隔分别为 1s、2s、4s最多重试 3 次批量处理时在两个请求之间加入 500ms 以上的间隔控制请求速率低于 QPS 上限。数据校验与人工兜底OCR 识别不可能保证 100% 准确尤其是手写体或盖章遮挡区域。生产环境中应当建立复审机制对valid_date缺失或格式异常的记录标记为高风险对关键字段如姓名做字符类型校验仅允许中文、· 和字母识别失败超过 2 次的图片转入人工审核队列不要静默丢弃。存储与合规健康证包含个人敏感信息接入时需要注意尽量减少原始图片的留存时间识别完成后在业务允许范围内删除记录调用日志时对request_id和识别结果做权限管控避免无关人员访问如果业务涉及大规模采集提前确认是否符合当地个人信息保护相关法规。参考文档接口文档https://apizero.cn/aidocs/ocr-health-cert原始文档https://apizero.cn/aidocs/ocr-health-cert/raw.md
健康证识别API零基础接入：参数、请求与返回字段解析
适用场景与业务价值健康证从业人员预防性健康检查合格证明在餐饮、食品加工、商超零售、家政服务等行业中属于高频查验证件。传统人工登记方式需要逐项抄录持证人姓名、发证机关和有效期不仅效率低还容易出现肉眼核对疏漏。健康证识别 API 可以通过一张图片结构化输出姓名、发证机关、办证日期、发证日期、体检日期、有效日期共 6 个字段直接对接后续业务系统。典型的落地场景包括餐饮门店员工健康证到期前自动预警替换原本依赖人工台账的巡检方式HR 入职材料批量录入将纸质健康证拍照上传后自动提取关键信息外卖骑手、家政服务人员的资质核验登记信息后自动比对有效期。接口能力边界在接入之前需要明确该接口能做什么、不能做什么维度说明输入方式支持公网图片 URL 和 base64 字符串两种方式图片格式jpg / png输出字段name姓名、issued_by发证机关、date_of_handling办证日期、date_of_issue发证日期、date_of_medical_examination体检日期、valid_date有效日期请求方法POST接口地址https://v1.apizero.cn/api/ocr-health-cert默认 QPS2 / s接口只负责识别并返回结构化文本不做证件真伪核验也不返回证件照片或额外的置信度分数。图片中如果存在遮挡、反光、倾斜识别结果可能不完整需要在上传前做前置检查。请求参数详解鉴权方式调用接口时需要携带 API Key。事实卡中 curl 示例使用的是X-API-Key请求头而参数说明中给出的鉴权头是Authorization: Bearer 你的 API Key。两种方式以实际文档为准建议在项目中将 API Key 放入环境变量避免硬编码在代码仓库中。Header 参数参数名是否必填类型说明Authorization是stringBearer 后面拼接你的 API KeyContent-Type否string请求体格式通常设为application/jsonBody 参数请求体是一个 JSON 对象包含两个必填字段字段名类型是否必填说明input_typestring是图片传输方式url表示公网图片地址base64表示图片的 base64 编码input_datastring是图片内容。input_typeurl时填 http/https 链接input_typebase64时填 base64 字符串可以带data:image/xxx;base64,前缀注意 body 参数说明中展示的是数组结构[{...}]而 curl 示例中直接使用的是 JSON 对象。实际调用时以对象形式传参即可数组外层通常用于描述多组请求体的情况不是最终请求格式。零基础接入curl 快速验证下面通过 curl 发起一次真实请求。把脚本中的 API Key 换成你自己的密钥图片地址改为实际可访问的公网图片链接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如果服务端要求Authorization头则需要替换为curl -sS \ -X POST \ -H Authorization: Bearer $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-certcurl 的好处是可以在命令行快速验证接口连通性确认鉴权和参数无误后再进入代码编写阶段。Python 代码接入示例实际业务开发中更多场景需要把图片转换为 base64 后上传尤其是从移动端直接拍摄、图片尚未上传到公网的情况。下面给出一个完整的 Python 示例import base64 import os import requests def encode_image_to_base64(image_path: str) - str: 读取本地图片并转为 base64 字符串不含前缀 with open(image_path, rb) as f: return base64.b64encode(f.read()).decode(utf-8) def recognize_health_cert(image_path: str, api_key: str) - dict: api_url https://v1.apizero.cn/api/ocr-health-cert b64_data encode_image_to_base64(image_path) headers { Authorization: fBearer {api_key}, Content-Type: application/json, } payload { input_type: base64, input_data: b64_data, } resp requests.post(api_url, headersheaders, jsonpayload, timeout10) resp.raise_for_status() return resp.json() if __name__ __main__: key os.environ.get(APIZERO_API_KEY, ) result recognize_health_cert(./health_cert.jpg, key) print(result)这段代码做了三件事读取本地图片转 base64、构造请求体、解析 JSON 响应。实际项目中建议把requests.post封装成独立函数并补充超时重试逻辑。返回字段逐项解析成功时接口返回 HTTP 200响应体示例{ code: 0, 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 }, msg: 成功, request_id: req_abc123 }字段说明如下字段类型业务含义codeint业务状态码0 表示成功msgstring状态描述request_idstring本次请求唯一标识排查问题时可以提供给服务方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是使用频率最高的字段可用于到期提醒和资格校验。例如判断健康证是否在有效期内from datetime import date valid_date result[data][valid_date] today date.today().isoformat() is_valid valid_date today print(证件状态, 有效 if is_valid else 已过期)注意这里只做字符串格式的日期比较前提是接口返回的日期格式始终保持YYYY-MM-DD。如果返回了空字符串或null说明图片中对应区域未能识别成功。常见错误与排查思路1. HTTP 401 Unauthorized原因API Key 缺失、头部字段名不对或请求头格式错误。排查步骤检查请求头中是X-API-Key还是Authorization: Bearer以最新文档为准确认环境变量APIZERO_API_KEY已正确设置且未包含多余空格使用 curl 去掉-sS参数查看完整响应体。2. HTTP 400 Bad Request原因请求体 JSON 格式错误、缺少必填字段、图片链接不可访问。排查步骤使用 JSON 校验工具检查 payload 是否合法确认同时传入了input_type和input_data两个字段如果input_typeurl手动在浏览器中打开图片链接确认可以正常访问且未做防盗链限制如果input_typebase64确认字符串没有包含换行符且未误传文件路径。3. 返回 code 非 0原因可能是图片模糊、格式不支持或识别失败。排查步骤检查图片是否为 jpg 或 png 格式确认图片没有过度压缩建议图片短边不小于 500 像素尝试对图片做裁剪只保留健康证主体区域后重新调用把request_id记录下来向技术支持反馈时一并提供以便定位问题。4. 响应超时原因图片体积过大、网络波动或接口负载较高。排查步骤在代码中将请求超时时间设置为 10 到 30 秒base64 传输时图片文件大小建议控制在 5MB 以内在服务端对图片做等比压缩后再编码减少传输耗时。工程化注意事项图片预处理接口对图片质量有一定要求。真实场景中用户用手机拍摄的健康证经常存在以下问题背景杂乱证件区域占比小倾斜角度超过 30 度塑料封套反光导致文字区域发白闪光灯直射造成的过曝。建议在调用前做一个简单的质量检查证件区域面积占比不低于 40%亮度直方图中高光像素占比不要超过 20%。如果条件允许可以先用 OpenCV 做边缘检测和透视矫正再送入 OCR 接口。超时与重试策略接口默认 QPS 为 2/s意味着每秒最多处理 2 个请求。面对批量导入任务时不能直接并发请求否则容易触发限流。建议采用以下策略单次请求超时设置为 10 秒对返回 5xx 或网络异常的情况采用指数退避重试间隔分别为 1s、2s、4s最多重试 3 次批量处理时在两个请求之间加入 500ms 以上的间隔控制请求速率低于 QPS 上限。数据校验与人工兜底OCR 识别不可能保证 100% 准确尤其是手写体或盖章遮挡区域。生产环境中应当建立复审机制对valid_date缺失或格式异常的记录标记为高风险对关键字段如姓名做字符类型校验仅允许中文、· 和字母识别失败超过 2 次的图片转入人工审核队列不要静默丢弃。存储与合规健康证包含个人敏感信息接入时需要注意尽量减少原始图片的留存时间识别完成后在业务允许范围内删除记录调用日志时对request_id和识别结果做权限管控避免无关人员访问如果业务涉及大规模采集提前确认是否符合当地个人信息保护相关法规。参考文档接口文档https://apizero.cn/aidocs/ocr-health-cert原始文档https://apizero.cn/aidocs/ocr-health-cert/raw.md
