适用场景中国护照识别API用于结构化提取护照上的关键信息适用于以下场景出行实名核验航空、铁路等出行平台自动录入护照信息减少人工输入错误。酒店/机构入住登记前台拍照上传系统自动填充姓名、证件号、有效期等字段。跨境业务证件录入签证申请、金融开户等需要快速准确提取护照数据的流程。这些场景的共同特点是要求高精度、低延迟且能处理不同质量的护照照片包括扫描件、手机拍照、复印件等。该API专注于返回6个核心字段不涉及头像或机读码的额外识别保证了响应速度。接口能力与边界在开始编码前明确以下几点能力支持输入图片URL或Base64编码返回护照号码、中文姓名、英文姓名、出生日期、有效期至、签发地点共6个字段。限制QPS为2次/秒超出限制会返回频率控制错误。仅限已登录用户调用匿名访问不开放因此必须携带有效的API Key。图片要求建议图片清晰、文字端正若图片倾斜或模糊识别准确率会下降。图片格式不限JPEG、PNG等均可大小建议不超过10MB。返回字段所有字段均为字符串类型日期格式固定为YYYY-MM-DD。若某个字段在图片中缺失对应的返回值可能为空字符串。该接口适合作为证件信息录入的前置步骤但不适用于需要实时视频流或高吞吐的业务可通过增加客户端缓存或异步队列来平滑QPS限制。最小可运行示例curl 一行命令这是最能体现“最小可运行”的方式——你只需要一个终端和一个有效的API Key就能在几秒内拿到护照的结构化数据。curl -sS -X POST \ -H X-API-Key: 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使用前请替换YOUR_API_KEY从API管理后台获取的密钥。https://example.com/passport.jpg替换为一张真实的护照图片URL注意请确保你有合法的使用权限本文仅做技术演示。执行成功后你会看到类似下面的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: 上海 } }注意实际返回的字段顺序可能不一致但结构固定。请求参数详解请求方式与地址方法POST地址https://v1.apizero.cn/api/ocr-cn-passport请求头Headers参数名是否必填类型说明X-API-Key是string你的API密钥格式为纯文本字符串Content-Type否string默认为application/json通常无需额外指定认证方式官方文档推荐使用X-API-Key头传递密钥。部分客户端也支持Authorization: Bearer key但为统一本示例全部采用X-API-Key。请求体Body请求体是一个JSON对象包含两个必需字段字段类型是否必填说明input_typestring是图片传输方式可选url公网图片链接或base64图片的Base64编码input_datastring是图片内容url时填http/https链接base64时填完整的Base64字符串可含data:image/xxx;base64,前缀使用Base64传输示例{ input_type: base64, input_data: data:image/jpeg;base64,/9j/4AAQSkZJRg...省略 }Base64编码可以消除图片上传的网络延迟如果图片已在前端处理但会增加请求体大小。建议图片大小在2MB以内时使用Base64较大图片使用URL方式。鉴权方式说明API Key是调用该接口的唯一凭证。获取方式登录API管理后台在“我的应用”中创建应用并复制Key。安全注意Key不应硬编码在客户端代码如前端JavaScript中而是存储在服务端环境变量中。失效处理如果收到401错误请检查Key是否已过期或未正确放置在请求头中。响应数据解读成功响应HTTP 200{ 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表示成功msgstring状态描述成功时为“成功”request_idstring唯一请求ID可用于问题排查data.passport_numberstring护照号码例如E12345678data.full_name_cnstring中文姓名例如张三data.full_name_enstring英文姓名大写例如ZHANG SANdata.date_of_birthstring出生日期格式YYYY-MM-DDdata.date_of_expirystring有效期至格式YYYY-MM-DDdata.place_of_issuestring签发地点例如上海注意如果护照图片年份久远或信息磨损个别字段可能为空字符串需业务侧做容错处理。错误响应示例{ code: 1001, msg: 图片未识别到信息, request_id: req_err456 }此时data字段可能缺失或为null应优先检查code值而非data。常见错误码与排查错误码含义排查方法0成功正常1001图片未识别到信息检查图片是否包含护照人像页图片是否过暗/模糊或方向错误1002图片格式不支持或损坏确认图片为常见格式JPG/PNG且未被截断1003请求频率超限QPS限制为2/s加入重试逻辑或减慢请求速度1004未授权的API Key检查Header中Key是否正确、是否过期或未传递1005请求参数缺失或格式错误确保input_type和input_data都存在且类型正确500服务内部错误稍后重试如果持续检查request_id并联系技术支持注意错误码列表以最新文档为准以上为常见错误码。工程化注意事项1. 图片预处理建议在调用API前对图片进行90度旋转校正例如使用OpenCV检测文本方向。护照上的文字通常水平如果图片被旋转识别率会大幅降低。裁剪掉多余背景让护照占图片主体的70%以上。2. 错误重试策略对于1003频率超限和500服务内部错误可实施指数退避重试import time import requests def call_ocr(url, api_key, max_retries3): headers {X-API-Key: api_key, Content-Type: application/json} data {input_type: url, input_data: url} for attempt in range(max_retries): resp requests.post(https://v1.apizero.cn/api/ocr-cn-passport, headersheaders, jsondata) if resp.status_code 200: body resp.json() if body.get(code) 1003: time.sleep(1) # 简单等待后重试 continue return body else: time.sleep(0.5) return None3. 数据校验与存储返回的日期字段应做格式校验正则\d{4}-\d{2}-\d{2}防止空字符串导致的程序异常。英文姓名应为大写字母加空格可校验是否包含小写字母或数字。护照号码通常包含字母和数字但具体格式因国家而异可做长度约束。4. 敏感数据保护护照信息属于个人敏感数据。生产环境中建议传输使用HTTPS该API已强制要求。日志中打印时打码处理passport_number: E12****78。5. 缓存与降级如果业务QPS超过2可在客户端加入简单缓存同一图片URL短时间内如10分钟重复调用时直接返回上次结果。极端情况下可降级为人工录入。参考文档中国护照识别API文档原始Markdown文档以上为最小可运行示例的全部内容。你只需要一个curl命令就能快速验证接口是否按预期工作。按此流程迁移到代码中即可在数分钟内完成集成。
