最小可运行示例：用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 | 是 | string | 你的API密钥，格式为纯文本字符串 |
| Content-Type | 否 | string | 默认为application/json，通常无需额外指定 |
认证方式：官方文档推荐使用X-API-Key头传递密钥。部分客户端也支持Authorization: Bearer <key>，但为统一，本示例全部采用X-API-Key。
请求体（Body）
请求体是一个JSON对象，包含两个必需字段：
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| input_type | string | 是 | 图片传输方式，可选url（公网图片链接）或base64（图片的Base64编码） |
| input_data | string | 是 | 图片内容：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": "上海" } }字段说明：
| 字段 | 类型 | 说明 |
|---|---|---|
| code | int | 业务状态码，0表示成功 |
| msg | string | 状态描述，成功时为“成功” |
| request_id | string | 唯一请求ID，可用于问题排查 |
| data.passport_number | string | 护照号码（例如：E12345678） |
| data.full_name_cn | string | 中文姓名（例如：张三） |
| data.full_name_en | string | 英文姓名（大写，例如：ZHANG SAN） |
| data.date_of_birth | string | 出生日期（格式：YYYY-MM-DD） |
| data.date_of_expiry | string | 有效期至（格式：YYYY-MM-DD） |
| data.place_of_issue | string | 签发地点（例如：上海） |
注意：如果护照图片年份久远或信息磨损，个别字段可能为空字符串，需业务侧做容错处理。
错误响应示例
{ "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_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 None3. 数据校验与存储
- 返回的日期字段应做格式校验（正则
\d{4}-\d{2}-\d{2}），防止空字符串导致的程序异常。 - 英文姓名应为大写字母加空格，可校验是否包含小写字母或数字。
- 护照号码通常包含字母和数字，但具体格式因国家而异，可做长度约束。
4. 敏感数据保护
护照信息属于个人敏感数据。生产环境中建议：
- 传输使用HTTPS（该API已强制要求）。
- 日志中打印时打码处理（
passport_number: E12****78）。
5. 缓存与降级
如果业务QPS超过2，可在客户端加入简单缓存：同一图片URL短时间内（如10分钟）重复调用时直接返回上次结果。极端情况下可降级为人工录入。
参考文档
- 中国护照识别API文档
- 原始Markdown文档
以上为最小可运行示例的全部内容。你只需要一个curl命令，就能快速验证接口是否按预期工作。按此流程迁移到代码中，即可在数分钟内完成集成。