中国护照识别 API 接入指南：从零开始解析字段与错误处理

适用场景与业务价值在出行实名核验、酒店/机构入住登记、跨境业务证件录入等场景中常需要从护照图片中提取结构化的关键信息。中国护照识别 API 提供了针对中国护照的专用 OCR 能力能够一次性返回护照号码、中英文姓名、出生日期、有效期至和签发地点共 6 个字段无需开发者自行训练模型或处理复杂的光学字符识别流程。接口能力边界支持类型仅限中国护照包括普通护照、公务护照等以封面和内容格式为准输入方式支持公网图片 URL 或 Base64 编码字符串输出字段6 个必含字段护照号码、中文姓名、英文姓名、出生日期、有效期至、签发地点并发限制QPS 为 2即每秒最多 2 次请求鉴权要求仅限已登录用户调用需要携带有效的 API Key通过 Bearer Token 方式不支持的场景港澳通行证、台湾地区证件、其他国家的护照、模糊或严重倾斜的图片可能无法正确识别鉴权与请求头每次调用 API 都需要在 HTTP Header 中传入Authorization字段格式为Authorization: Bearer 你的 API KeyAPI Key 需要从开发者平台获取后续在“参考文档”中可找到申请入口本文不赘述。此外Content-Type通常设置为application/json。Header 参数表参数名是否必填类型说明Authorization是stringBearer 开头 API KeyContent-Type否建议填写string推荐 application/json请求体结构请求方式为POST请求地址https://v1.apizero.cn/api/ocr-cn-passport。请求体为 JSON 对象包含两个字段字段名类型必填说明input_typestring是图片传输方式支持url或base64input_datastring是图片内容url时为公网图片链接base64时为 Base64 编码字符串可含 data URI 前缀示例请求体{ input_type: url, input_data: https://example.com/passport.jpg }接入示例curl以下 curl 命令展示了如何发送请求。注意替换$APIZERO_API_KEY为你自己的 API Key以及图片地址。curl -sS \ -X POST \ -H Authorization: Bearer $APIZERO_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并传入 Base64 编码的字符串可带data:image/jpeg;base64,前缀。接入示例Pythonrequests 库import requests url https://v1.apizero.cn/api/ocr-cn-passport headers { Authorization: Bearer YOUR_API_KEY, Content-Type: application/json } payload { input_type: url, input_data: https://example.com/passport.jpg } response requests.post(url, headersheaders, jsonpayload) print(response.status_code) print(response.json())响应字段解读成功时 HTTP 状态码为 200响应体为 JSON 格式结构如下{ code: 0, msg: 成功, request_id: req_abc123, 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: 上海 } }字段说明字段类型含义示例值codeint业务状态码0 表示成功0msgstring状态描述成功request_idstring请求唯一标识用于日志追踪req_abc123passport_numberstring护照号码含字母和数字E12345678full_name_cnstring中文姓名张三full_name_enstring英文姓名大写ZHANG SANdate_of_birthstring出生日期格式 YYYY-MM-DD1990-01-01date_of_expirystring有效期至格式 YYYY-MM-DD2034-12-31place_of_issuestring签发地点上海注意如果图片质量太差或非护照正面API 可能返回空字符串或缺失字段。建议先做图片预处理。常见错误与排查1. 401 Unauthorized原因Authorization头缺失或 API Key 无效。解决检查 Header 中是否正确包含Bearer前缀并在开发者平台确认 API Key 状态。2. 400 Bad Request原因请求体 JSON 格式错误或input_type未填、input_data为空、图片无法访问。解决确保input_type为url或base64。若用 URL确保图片公网可访问非内网地址。若用 Base64确保字符串长度正确建议先解码验证图片。3. 429 Too Many Requests原因超过 QPS 限制2 次/秒。解决在客户端实现请求排队或限流例如每次请求间隔至少 500ms。4. 识别结果字段为空原因图片中护照信息不完整、模糊、反光或角度过大。解决使用高分辨率扫描件或清晰照片。确保护照占据图片主要区域建议 70%。避免强光、阴影、遮挡。工程化注意事项图片预处理裁剪如果图片包含背景、桌面等多余元素建议先裁剪至护照区域提高识别率。分辨率推荐图片最长边不低于 1000px文件大小控制在 10MB 以内。格式支持 JPG、PNG、BMP 等常见格式Base64 时注意编码完整性。请求重试与幂等由于 API 是 POST 且非幂等每次返回不同 request_id对于失败请求如网络超时、5xx 错误建议实现重试策略最大重试 3 次使用指数退避如 1s、2s、4s对 4xx 错误除 429 外不应重试而是检查参数并发控制QPS 为 2如果业务需要批量处理护照图片建议在客户端使用队列控制并发数例如 Python 中可使用asyncio.Semaphore或requests配合time.sleep。数据安全护照属于高度敏感身份证件传输和存储需遵循相关法规使用 HTTPS 加密通信。不要在客户端日志中打印完整图片 Base64 或护照号码。识别完成后如需保留图片应设置访问权限并定期清理。参考文档中国护照识别 API 官方文档原始 Markdown 文档