适用场景与接口定位在涉及台湾居民实名认证、酒店入住登记、银行开户、人社业务等场景时需要快速、准确从台胞证图像中提取关键字段。人工录入效率低且易出错因此需要一个稳定、结构化的 API 来完成自动识别。本文介绍的「台胞证识别」接口路径/api/ocr-tw-permit专门用于从证件图片中提取以下 5 个字段中文姓名full_name_cn英文姓名full_name_en出生日期date_of_birth证件号码card_number有效期date_of_expiry适用场景包括但不限于在线实名认证用户上传台胞证照片后台自动填充信息酒店 PMS 系统入住时快速录入证件信息政务办事大厅自助终端扫描证件减少人工核对接口能力边界输入方式支持两种图片提交方式URL 方式传递一张公网可访问的图片链接接口自动下载并识别Base64 方式将图片文件进行 Base64 编码后传入适用于无法提供公网链接的场景如小程序前端直传图片格式要求支持jpg、png格式建议证件图片完整、清晰避免光照不均、遮挡、倾斜过大不要求图片尺寸严格统一但建议宽度不低于 800px调用限制QPS2 次/秒每秒最多 2 个并发请求认证需要有效的 API Key通过 HTTP HeaderAuthorization: Bearer 你的 API Key传递用户登录限制该接口仅限已登录用户调用匿名访问不开放需先从平台获取 API Key从零开始调用的最小示例以下是一个完整的curl命令你只需替换$YOUR_API_KEY和图片 URL 即可运行。curl -sS \ -X POST \ -H Authorization: Bearer $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说明-sS表示静默模式但显示错误-H添加请求头-d指定 JSON 请求体。图片地址请替换为实际公网可访问的台胞证图片 URL。如果你本地有一张图片也可以先将其转为 Base64 编码。下面给出一个使用base64命令Linux/macOS生成并请求的示例# 将本地图片转换为 Base64 字符串去掉换行 B64$(base64 -w0 /path/to/tw-permit.jpg) # 调用接口 curl -sS -X POST \ -H Authorization: Bearer $YOUR_API_KEY \ -H Content-Type: application/json \ -d {\input_type\:\base64\,\input_data\:\$B64\} \ https://v1.apizero.cn/api/ocr-tw-permit注意在 Windows PowerShell 中Base64 编码命令不同且 JSON 字符串转义复杂建议使用 Postman 或编写脚本。请求参数详解请求体是一个 JSON 对象包含两个必填字段参数名类型必填说明示例input_typestring是图片传输方式url或base64urlinput_datastring是图片内容URL 或 Base64 字符串https://example.com/tw-permit.jpg额外说明当input_typeurl时input_data必须是完整的http://或https://开头的公网链接。当input_typebase64时input_data可以是纯 Base64 字符串也可以包含data:image/jpeg;base64,前缀接口会自动去除前缀。响应结构解读成功响应的 HTTP 状态码为 200Body 为 JSON 格式结构如下{ 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 } }字段含义字段类型说明codeint业务状态码0表示成功非0请参考下节错误处理msgstring提示信息如“成功”或错误描述request_idstring本次请求的唯一标识可用于日志追踪和排查问题dataobject包含 5 个识别字段-full_name_cnstring中文姓名如“张三”-full_name_enstring英文姓名大写如“ZHANG SAN”-date_of_birthstring出生日期格式YYYY-MM-DD-card_numberstring证件号码共 17 位通常以“8”开头-date_of_expirystring有效期截止日期格式YYYY-MM-DD注意如果图片质量太差导致某些字段无法识别对应字段可能为空字符串或 null以实际返回为准。常见错误与排查1. 鉴权失败401 Unauthorized错误示例{ code: 401, msg: Authorization header missing or invalid, request_id: req_err_xxx, data: null }原因与解决未在 Header 中传递Authorization: Bearer 你的 API KeyAPI Key 写错了或已过期请检查控制台获取正确的 Key使用了X-API-Key头旧版本兼容建议统一使用Authorization: Bearer2. 图片无法访问或格式错误400 Bad Request常见返回{ code: 400, msg: invalid image url or base64 data, request_id: req_xxx }排查思路对于 URL 方式确认图片链接是公网可访问的不含本地内网地址如localhost、10.x.x.x。可以在浏览器中直接打开验证。对于 Base64 方式确认编码是否正确不含多余空格或换行。注意base64 -w0或base64 | tr -d \n确保无换行。图片格式仅支持 jpg/png其他格式如 bmp、webp会被拒绝。3. 图片不清晰导致识别失败code 1100 左右返回示例{ code: 1101, msg: no text found in image, request_id: req_xxx }原因图片太模糊、光照不足、证件未充满画面。建议使用高分辨率扫描件300 DPI 以上确保证件四个角都在画面内无明显反光避免手写遮挡或覆盖条形码区域4. 请求频率超限429 Too Many Requests返回状态码 429Body 中msg类似rate limit exceeded。解决控制并发请求在 2 QPS 以内。可增加本地队列或退避重试策略。工程化注意事项1. 图片预处理实际业务中用户上传的图片往往不是标准证件照。建议在上传前做以下处理自动裁剪基于轮廓检测保留证件区域去除背景增强对比度使用 OpenCV 的直方图均衡化或 CLAHE 算法矫正倾斜检测证件矩形边界并透视变换压缩至合理大小图片文件不宜超过 5MB但宽度建议保留 800~2000px 以保留细节2. 请求重试与幂等OCR 接口可能因网络抖动或服务端偶发错误返回 5xx如 502、503建议实现指数退避重试例如 1s、2s、4s 后重试最多 3 次。注意同一个请求重复调用可能会产生不同的request_id但不会重复计费假设接口是幂等的。以文档实际说明为准。3. 结果校验与人工兜底识别结果并非 100% 准确。建议对关键字段如证件号码进行长度校验台胞证号码通常为 17 位数字对中文姓名进行是否包含非法字符的检查将识别结果展示给用户确认支持手动修改后再提交入库4. Base64 传递的内存优化如果图片较大例如 3MBBase64 字符串长度会增加约 33%网络传输耗时更长。建议优先使用 URL 方式让服务端下载客户端减少上传流量若必须用 Base64可在前端压缩图片后再编码例如压缩到 500KB 以内参考文档台胞证识别 API 文档原始 Markdown 文档本文中所有接口参数、请求地址、返回字段均以官方文档为准如有变动请查阅最新文档。