一、接口能做什么中国护照识别接口是一个面向护照图片的结构化识别服务。调用方把一张护照的正面照片传上去接口会返回 6 个固定字段护照号码passport_number、中文姓名full_name_cn、英文姓名full_name_en、出生日期date_of_birth、有效期至date_of_expiry、签发地点place_of_issue。这些字段的键名和含义固定方便下游业务系统直接映射到数据库或表单。接口的基本信息如下请求方法POST请求地址https://v1.apizero.cn/api/ocr-cn-passport接口分类文档识别调用限制QPS 2 次/秒值得注意的是护照属于高敏感度身份证件该接口只对已登录用户开放匿名访问不开放。也就是说接入前必须先准备有效的 API Key并妥善保管。二、适用场景凡是依赖“人工录入护照信息”的业务都可以考虑接入该接口出行实名核验在线值机、签证申请、海关申报等场景用户拍照上传护照后自动回填姓名、号码和有效期减少手输错误。酒店与机构入住登记前台或自助终端读取护照图像将结构化字段直接写入入住系统PMS提高办理效率。跨境业务证件录入银行开户、保险投保、设备租赁等业务需要留存储备证件信息时可用接口完成初步识别再由人工复核。这些场景的共同特点是证件格式相对统一、字段固定、业务链条长若不借助 OCR 接口人工录入维护复杂度高且容易出错。三、接入前准备与鉴权接入前需要准备两样东西API Key在平台完成登录后获取作为每次请求的凭证。待识别的护照图片可以是公网可访问的图片 URL也可以是图片文件的 base64 编码。调用时需要设置请求头。以本文 curl 示例为准使用 X-API-Key 头传递 API Key参数文档中记录的 Authorization 头Bearer 方式也有效实际接入时请以文档页最新说明选择其中一种不要混用或同时携带两种头。X-API-Key: 你的 API Key Content-Type: application/json四、请求参数说明请求体是一个 JSON 对象包含两个必填字段字段名类型必填说明input_typestring是图片传输方式取值为 url公网图片地址或 base64图片 base64 编码input_datastring是图片内容。input_typeurl 时填写 http/https 图片链接input_typebase64 时填写 base64 字符串关于 base64 传输接口兼容带 data:image/xxx;base64, 前缀和纯 base64 两种写法。建议统一携带标准前缀减少后续解析时的歧义。一次请求只处理一张图片不支持批量。如果需要识别多张护照请逐张请求并控制请求频率在 QPS 限制内。五、接入示例5.1 curl 示例在终端中先设置环境变量再发起请求export APIZERO_API_KEY你的APIKey curl -sS \ -X POST \ -H X-API-Key: $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响应示例{ code: 0, data: { date_of_birth: 1990-01-01, date_of_expiry: 2034-12-31, full_name_cn: 张三, full_name_en: ZHANG SAN, passport_number: E12345678, place_of_issue: 上海 }, msg: 成功, request_id: req_abc123 }5.2 Python 示例使用 requests 库发送相同请求import os import requests API_URL https://v1.apizero.cn/api/ocr-cn-passport API_KEY os.environ.get(APIZERO_API_KEY, 你的APIKey) headers { X-API-Key: API_KEY, Content-Type: application/json, } payload { input_type: url, input_data: https://example.com/passport.jpg, } resp requests.post(API_URL, headersheaders, jsonpayload, timeout10) resp.raise_for_status() print(resp.json())六、返回字段解读成功时 HTTP 状态码为 200响应体为一个 JSON 对象外层字段固定字段类型说明codenumber业务状态码0 表示成功msgstring提示信息request_idstring单次请求的唯一标识排查问题时需要提供给支持人员dataobject识别结果对象data 对象中包含 6 个字段字段名含义示例passport_number护照号码E12345678full_name_cn中文姓名张三full_name_en英文姓名ZHANG SANdate_of_birth出生日期YYYY-MM-DD1990-01-01date_of_expiry有效期至2034-12-31place_of_issue签发地点上海识别结果是 OCR 引擎基于图像内容给出的“尽力而为”的结果不保证 100% 正确。尤其当图片存在反光、模糊、倾斜或遮挡时个别字段可能缺失或识别错误。业务侧建议对关键字段比如护照号码、有效期做二次人工校验。七、常见错误排查以下排查思路基于 HTTP 语义和接口特性具体错误码请以文档页为准。现象可能原因处理建议401 UnauthorizedAPI Key 缺失、错误或鉴权头写法与文档不一致检查 X-API-Key / Authorization 头的名称和值确认没有多余空格400 Bad Requestinput_type 或 input_data 为空input_type 取值不在 url/base64 中按接口要求检查请求体 JSON 结构404 Not Found请求地址拼写错误核对 URL 路径确认没有多余的斜杠或大小写差异429 Too Many Requests请求频率超过 QPS 2 次/秒在调用侧加限流或退避重试机制5xx服务端异常等待一段时间后重试建议设置重试上限八、工程化注意事项控制并发QPS 限制为 2 次/秒建议在网关或客户端做本地限流避免触发 429。挑选图片质量使用正面、光线均匀、无反光、无遮挡的护照照片识别准确率会比随意拍摄的照片好很多。超时与重试建议设置 10 秒左右的连接超时。重试时采用指数退避例如在第 1、2、4 秒后重试最多 3 次避免连续重试占满额度。日志脱敏护照号码、姓名、出生日期属于敏感信息。不要将完整的识别请求体和响应体打到普通日志里建议脱敏后再存储如果业务强制要求留存日志应做好访问控制和加密。结果校验将接口返回的 date_of_expiry 等字段与业务规则结合例如有效期校验、证件持有人与当前用户一致性校验不能只依赖 OCR 结果。文档版本接口参数与返回结构可能调整以文档页实时内容为准。参考文档中国护照识别接口文档https://apizero.cn/aidocs/ocr-cn-passport原始接口文档Markdownhttps://apizero.cn/aidocs/ocr-cn-passport/raw.md