适用场景
台湾居民来往大陆通行证（台胞证）是台湾同胞在大陆进行身份核验的重要证件。实际业务中，以下场景通常需要从台胞证上自动化提取结构化信息：
- 实名认证系统：金融开户、网约车准备、电商实名等环节，需要录入中文姓名、英文姓名、证件号码、出生日期和有效期。
- 酒店入住登记：前台通过拍照直接获取证件信息，减少手动输入错误。
- 合同签署与KYC：线上签约时自动填充身份信息，提升用户体验。
- 边缘设备离线核验：部分场景需要将OCR结果与业务数据库比对。
该API专门针对台胞证设计，仅返回5个关键字段，避免冗余数据干扰下游处理。
接口能力边界
- 支持输入方式：公网图片URL或图片Base64编码（可含
data:image/xxx;base64,前缀）。 - 图片格式：JPEG、PNG。
- 输出字段：仅包含中文姓名、英文姓名、出生日期、证件号码、有效期共5个字段，不返回其他信息。
- 调用限制：QPS为2次/秒，超出后返回429状态码。
- 鉴权要求：仅限已登录用户调用，匿名访问不开放。
注意：该API不提供图片旋转校正、多证件检测等预处理功能，上传的证件图片需保证完整、清晰、无反光。
鉴权与请求头
调用前需获取有效的API Key（在管理控制台生成）。身份认证支持以下两种方式之一，本文示例均使用X-API-Key头：
| Header | 是否必须 | 类型 | 说明 |
|---|---|---|---|
X-API-Key | 是 | string | 填入你的API Key，示例：Bearer sk-xxxx可省略Bearer前缀 |
Content-Type | 否 | string | 请求体格式，默认为application/json，通常无需显式设置 |
若使用
Authorization: Bearer <API Key>方式，效果相同，请根据平台文档选择一种。
最小可运行示例：cURL
以下是一个完整可复制的cURL命令，只需替换$API_KEY和图片URL即可运行：
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/tw-permit.jpg"}' \ "https://v1.apizero.cn/api/ocr-tw-permit"参数解释
input_type（必填）：固定为"url"或"base64"。input_data（必填）：当input_type=url时，填写可公开访问的图片链接（支持HTTPS）；当input_type=base64时，填写图片文件的Base64编码字符串。
Base64方式示例：
curl -sS \ -X POST \ -H "X-API-Key: $YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"input_type": "base64", "input_data": "/9j/4AAQSkZJRg...（省略的base64内容）"}' \ "https://v1.apizero.cn/api/ocr-tw-permit"建议使用真实证件图片进行测试，注意保护隐私，仅用于技术验证。
Python代码示例（最小可运行）
使用requests库，同样保持最少依赖：
import requests # 配置参数 API_KEY = "你的API Key" URL = "https://v1.apizero.cn/api/ocr-tw-permit" # 请求体（以URL方式为例） payload = { "input_type": "url", "input_data": "https://example.com/tw-permit.jpg" } headers = { "X-API-Key": API_KEY, "Content-Type": "application/json" } # 发送请求 response = requests.post(URL, json=payload, headers=headers) # 打印结果 print(response.status_code) print(response.json())运行说明
- 安装
requests：pip install requests - 将
API_KEY替换为有效值。 - 运行脚本，若返回状态码200，且
code字段为0，则识别成功。
返回值解读
成功响应示例（HTTP 200）：
{ "code": 0, "msg": "成功", "request_id": "req_abc123", "data": { "full_name_cn": "张三", "full_name_en": "ZHANG SAN", "date_of_birth": "1990-01-01", "card_number": "12345678901234567", "date_of_expiry": "2029-12-31" } }| 字段 | 类型 | 说明 |
|---|---|---|
code | int | 业务码，0表示成功，非0表示错误 |
msg | string | 业务状态描述 |
request_id | string | 请求唯一标识，可用于排查日志 |
data.full_name_cn | string | 中文姓名 |
data.full_name_en | string | 英文姓名（大写） |
data.date_of_birth | string | 出生日期，格式yyyy-MM-dd |
data.card_number | string | 台胞证号码 |
data.date_of_expiry | string | 有效期截止日期，格式yyyy-MM-dd |
若证件图片模糊或字段缺失，API会尽力识别，但对应字段可能返回空字符串或错误值。建议在业务层增加人工校验环节。
常见错误与排查
| 错误现象 | 可能原因 | 解决措施 |
|---|---|---|
| HTTP 401 Unauthorized | API Key无效或未携带 | 检查X-API-KeyHeader是否正确，是否过期 |
| HTTP 400 Bad Request | 请求体JSON格式错误，或缺少必填字段input_type/input_data | 确认JSON语法完整，字段名拼写无误 |
| HTTP 403 Forbidden | 账户未登录或API Key无权限 | 登录控制台确认API Key状态，或重新生成 |
| HTTP 429 Too Many Requests | 超过QPS限制（2次/秒） | 增加调用间隔（至少500ms），或使用指数退避重试 |
code非0 | 图片无法解析（模糊、非台胞证、格式错误等） | 更换更清晰的证件图片，确保不反光、不倾斜 |
| 返回空数据 | 图片中未检测到有效台胞证 | 确认图片内容为台胞证正面，且未被遮挡 |
示例：错误响应体
{ "code": 1001, "msg": "图片识别失败，请检查图片质量或格式", "request_id": "req_def456" }具体错误码定义请参考官方文档，本文仅列举常见情况。
工程化注意事项
1. 图片预处理
- 确保图片分辨率不低于 300×300 像素，建议 500×500 以上。
- 避免倾斜、透视变形，可先用OpenCV进行矫正。
- 如果图片包含多个证件，先裁剪出台胞证区域。
2. Base64数据大小限制
官方文档未明确最大限制，建议控制Base64字符串在2MB以内（对应原图约1.5MB）。若图片过大，需先压缩再编码。
3. 并发与重试策略
- QPS上限2，不能简单用多线程并发。可以考虑增加1秒的排队队列。
- 遇到网络波动或HTTP 429时，采用指数退避重试（如等待 1s、2s、4s）。
- 记录每次调用的
request_id，便于后台定位问题。
4. 数据安全
- 证件图片包含个人隐私，建议传输过程中使用HTTPS（接口已强制）。
- 服务器端获取的数据应及时脱敏存储，避免明文日志。
- 定期轮换API Key。
5. 测试环境搭建
- 使用非真实证件图片进行开发和测试（可扫描虚构样本）。
- 在CI/CD中集成功能测试，确保接口可用性。
参考文档
- 接口文档页：https://apizero.cn/aidocs/ocr-tw-permit
- 原始Markdown：https://apizero.cn/aidocs/ocr-tw-permit/raw.md
文档中可能包含更详细的错误码列表、字段约束及更新记录，请以最新内容为准。
