中国护照结构化识别 API 实战：从请求到字段解析的完整流程

适用场景在出行实名核验、酒店/机构入住登记、跨境业务证件录入等场景中需要快速从中国护照中提取结构化字段。传统的OCR全量识别方案会输出大量无关文本且无法直接映射到业务字段。本文介绍的API专为此类场景设计能直接返回护照号码、中英文姓名、出生日期、有效期至和签发地点共六个关键字段便于业务系统直接消费。接口能力与边界该接口基于深度学习OCR模型对中国护照第二版及新版进行结构化识别。输入支持图片URL或Base64编码输出为JSON格式。接口QPS限制为2次/秒适合中低频业务场景如后台异步处理或人工审核辅助。需要注意护照属于高敏感度身份证件接口仅限已登录用户调用匿名访问不开放调用方必须在请求头中携带有效的API Key鉴权。请求鉴权与参数说明鉴权方式接口使用Bearer Token鉴权。在HTTP请求头中传入Authorization字段格式为Bearer 你的API Key。API Key需从服务商后台获取并妥善保管不要硬编码在客户端代码中。请求体参数请求方法为POST请求体为JSON对象包含以下两个必填字段字段名类型必填说明input_typestring是图片传输方式可选值url公网图片地址或base64图片的Base64编码input_datastring是图片内容当input_typeurl时填写HTTP/HTTPS图片链接当input_typebase64时填写Base64编码字符串可含data:image/xxx;base64,前缀例如使用图片URL时请求体为{ input_type: url, input_data: https://example.com/passport.jpg }代码接入curl 与 Pythoncurl 命令以下示例使用curl发起请求请将YOUR_API_KEY替换为真实的API Key将图片链接替换为实际护照图片URL。curl -sS \ -X POST \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d {input_type: url, input_data: https://example.com/passport.jpg} \ https://v1.apizero.cn/api/ocr-cn-passport若使用Base64编码图片则请求体改为{ input_type: base64, input_data: data:image/jpeg;base64,/9j/4AAQ... }Python 示例使用requests库的示例代码适合集成到后端服务中。import requests import json API_URL https://v1.apizero.cn/api/ocr-cn-passport API_KEY YOUR_API_KEY # 请替换为真实密钥 def recognize_passport(image_source, source_typeurl): 识别护照 :param image_source: 图片URL或Base64字符串 :param source_type: url 或 base64 :return: 字典格式的响应结果 headers { Authorization: fBearer {API_KEY}, Content-Type: application/json } payload { input_type: source_type, input_data: image_source } response requests.post(API_URL, headersheaders, jsonpayload) response.raise_for_status() # 检查HTTP错误 return response.json() # 使用示例 if __name__ __main__: result recognize_passport(https://example.com/passport.jpg, url) print(json.dumps(result, indent2, ensure_asciiFalse))注意生产环境中应将API Key配置为环境变量避免泄露。返回字段解读成功时HTTP状态码为200返回JSON结构如下{ code: 0, data: { passport_number: E12345678, full_name_cn: 张三, full_name_en: ZHANG SAN, date_of_birth: 1990-01-01, date_of_expiry: 2034-12-31, place_of_issue: 上海 }, msg: 成功, request_id: req_abc123 }各字段含义字段类型说明codeint业务状态码0表示成功非0表示错误msgstring状态描述信息request_idstring本次请求的唯一标识可用于问题排查data.passport_numberstring护照号码data.full_name_cnstring中文姓名data.full_name_enstring英文姓名大写data.date_of_birthstring出生日期格式 YYYY-MM-DDdata.date_of_expirystring有效期至格式 YYYY-MM-DDdata.place_of_issuestring签发地点如果识别失败或图片质量不佳data可能返回空字段或部分字段缺失此时需结合code和msg判断。常见错误与排查错误现象可能原因解决措施HTTP 401API Key无效或未携带检查请求头是否包含正确的Authorization: Bearer keyHTTP 400请求体格式错误或缺少必填字段确认JSON结构正确input_type和input_data均已提供code为40001图片无法下载url模式检查URL是否可公开访问图片大小是否超限以文档为准code为40002图片解码失败base64模式确认Base64字符串正确图片格式为常见格式JPEG/PNGcode为40003护照区域未检测到图片可能非护照或角度偏差过大建议调整拍摄角度后重试QPS超限请求频率超过2次/秒增加调用间隔或使用请求队列注意所有错误详情均以文档为最终依据此处仅列出常见情形。工程化注意事项图片质量要求建议护照图片分辨率不低于800×600像素文字区域清晰无遮挡避免反光或阴影。证件应占据图片主体的80%以上。Base64编码长度限制Base64字符串对应原始图片大小建议控制在5MB以内过大的图片会增加传输时间和内存消耗。可以在上传前对图片进行压缩。异步处理由于QPS限制如果需要批量处理应将识别请求放入任务队列如Celery控制并发数避免触发限流。字段校验返回的护照号码、日期等字段应进行二次校验例如护照号码正则匹配、日期格式验证等以防范OCR误识别。敏感数据保护护照图片和识别结果属于个人隐私传输时务必使用HTTPS数据库存储时应加密日志中不应记录原始图片或完整字段。重试策略针对网络抖动或临时性错误建议采用指数退避的重试策略最多重试3次。缓存设计对于同一护照号码的重复查询可以设计本地缓存如Redis避免重复请求API。缓存过期时间根据业务需求设定。参考文档接口文档页https://apizero.cn/aidocs/ocr-cn-passport原始文档Markdown格式https://apizero.cn/aidocs/ocr-cn-passport/raw.md