当前位置：首页 > news >正文

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

news 2026/7/13 10:26:31

适用场景与业务价值

在出行实名核验、酒店/机构入住登记、跨境业务证件录入等场景中，常需要从护照图片中提取结构化的关键信息。中国护照识别 API 提供了针对中国护照的专用 OCR 能力，能够一次性返回护照号码、中英文姓名、出生日期、有效期至和签发地点共 6 个字段，无需开发者自行训练模型或处理复杂的光学字符识别流程。

接口能力边界

支持类型：仅限中国护照（包括普通护照、公务护照等，以封面和内容格式为准）
输入方式：支持公网图片 URL 或 Base64 编码字符串
输出字段：6 个必含字段（护照号码、中文姓名、英文姓名、出生日期、有效期至、签发地点）
并发限制：QPS 为 2，即每秒最多 2 次请求
鉴权要求：仅限已登录用户调用，需要携带有效的 API Key（通过 Bearer Token 方式）
不支持的场景：港澳通行证、台湾地区证件、其他国家的护照、模糊或严重倾斜的图片可能无法正确识别

鉴权与请求头

每次调用 API 都需要在 HTTP Header 中传入Authorization字段，格式为：

Authorization: Bearer <你的 API Key>

API Key 需要从开发者平台获取（后续在“参考文档”中可找到申请入口，本文不赘述）。此外，Content-Type通常设置为application/json。

Header 参数表

参数名	是否必填	类型	说明
Authorization	是	string	Bearer 开头 + API Key
Content-Type	否（建议填写）	string	推荐 application/json

请求体结构

请求方式为POST，请求地址：https://v1.apizero.cn/api/ocr-cn-passport。请求体为 JSON 对象，包含两个字段：

字段名	类型	必填	说明
input_type	string	是	图片传输方式，支持`url`或`base64`
input_data	string	是	图片内容，`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,前缀）。

接入示例：Python（requests 库）

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, headers=headers, json=payload) 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": "上海" } }

字段说明

字段	类型	含义	示例值
code	int	业务状态码，0 表示成功	0
msg	string	状态描述	"成功"
request_id	string	请求唯一标识，用于日志追踪	"req_abc123"
passport_number	string	护照号码（含字母和数字）	"E12345678"
full_name_cn	string	中文姓名	"张三"
full_name_en	string	英文姓名（大写）	"ZHANG SAN"
date_of_birth	string	出生日期，格式 YYYY-MM-DD	"1990-01-01"
date_of_expiry	string	有效期至，格式 YYYY-MM-DD	"2034-12-31"
place_of_issue	string	签发地点	"上海"

注意：如果图片质量太差或非护照正面，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，确保字符串长度正确（建议先解码验证图片）。