最小可运行示例：用curl快速验证中国护照OCR识别

适用场景

中国护照识别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头传递密钥。部分客户端也支持Authorization: Bearer <key>，但为统一，本示例全部采用X-API-Key。

请求体（Body）

请求体是一个JSON对象，包含两个必需字段：

使用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": "上海" } }

字段说明：

注意：如果护照图片年份久远或信息磨损，个别字段可能为空字符串，需业务侧做容错处理。

错误响应示例

{ "code": 1001, "msg": "图片未识别到信息", "request_id": "req_err456" }

此时data字段可能缺失或为null，应优先检查code值而非data。

常见错误码与排查

注意：错误码列表以最新文档为准，以上为常见错误码。

工程化注意事项

1. 图片预处理

• 建议在调用API前对图片进行90度旋转校正（例如使用OpenCV检测文本方向）。
• 护照上的文字通常水平，如果图片被旋转，识别率会大幅降低。
• 裁剪掉多余背景，让护照占图片主体的70%以上。

2. 错误重试策略

对于1003（频率超限）和500（服务内部错误），可实施指数退避重试：

import time import requests def call_ocr(url, api_key, max_retries=3): 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", headers=headers, json=data) 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 None

3. 数据校验与存储

• 返回的日期字段应做格式校验（正则\d{4}-\d{2}-\d{2}），防止空字符串导致的程序异常。
• 英文姓名应为大写字母加空格，可校验是否包含小写字母或数字。
• 护照号码通常包含字母和数字，但具体格式因国家而异，可做长度约束。

4. 敏感数据保护

护照信息属于个人敏感数据。生产环境中建议：

• 传输使用HTTPS（该API已强制要求）。
• 日志中打印时打码处理（passport_number: E12****78）。

5. 缓存与降级

如果业务QPS超过2，可在客户端加入简单缓存：同一图片URL短时间内（如10分钟）重复调用时直接返回上次结果。极端情况下可降级为人工录入。

参考文档

• 中国护照识别API文档
• 原始Markdown文档

以上为最小可运行示例的全部内容。你只需要一个curl命令，就能快速验证接口是否按预期工作。按此流程迁移到代码中，即可在数分钟内完成集成。