适用场景从人工录入到自动化证件识别在日常业务中涉及台湾居民身份核验的环节常依赖人工扫描或手工录入台胞证信息效率低且易出错。台胞证识别API通过OCR技术将证件图片中的5个关键字段中文姓名、英文姓名、出生日期、证件号码、有效期结构化输出适用于以下典型场景台湾居民实名认证电商、金融、社交平台在准备或敏感操作时需核验用户身份将上传的台胞证图片经API识别后与用户填写信息比对降低欺诈风险。酒店入住登记前文台胞入住酒店时系统对接API自动提取证件信息填入入住登记表减少前台操作时间。证件信息自动录入企业内部管理系统如HR、访客系统批量处理台胞证档案通过API将纸质或电子版图片转换为结构化数据供后续归档。接口能力边界输入、输出与性能限制理解能力边界是正确集成的前提。该API的设计围绕轻量、高精度的证件级OCR存在以下限制1. 输入方式与格式限制参数允许值说明input_typeurl/base64URL需指向公网可访问的图片base64字符串建议小于10MB否则可能超时图片格式仅jpg/png不支持gif、bmp、pdf等若只有pdf需提前转码图片质量建议完整、清晰、无反光倾斜超过15度或遮挡关键字段会导致识别失败或字段缺失需要注意的是input_typebase64时可以选择包含data:image/jpg;base64,前缀但兼容性更好的是传入纯base64编码。前端若使用FileReader生成base64直接传入即可。2. 输出字段及可靠性边界API返回的data对象严格限定为以下5个字段full_name_cn中文姓名如“张三”若证件上无中文名则返回空字符串full_name_en英文姓名如“ZHANG SAN”通常为大写拼音card_number证件号码共18位前8位10位数字date_of_birth出生日期格式YYYY-MM-Dddate_of_expiry有效期截止日期格式YYYY-MM-Dd能力边界API不提供证件图片的二次裁剪、人像提取或防伪检测也不会返回任何置信度分数。若返回字段为空或明显错误如出生日期为2099年需在业务层做二次校验不应完全信任OCR结果。3. 性能与并发限制QPS2请求/秒超过会返回限流错误HTTP 429或自定义错误码。超时单次请求默认超时30秒上传大图片或网络不稳定可能提前断开。鉴权仅已登录用户可调用匿名访问不开放。需在请求头携带Authorization: Bearer API Key。参数详解与鉴权方式根据接口文档请求采用POST方法Content-Type为application/json。Header参数参数名必填类型示例Authorization是stringBearer sk-xxxxxxxxxxxxxxxxContent-Type否stringapplication/json推荐显式指定注意部分历史版本的文档曾使用X-API-Key头当前推荐统一使用Authorization。调用前请以官方文档页https://apizero.cn/aidocs/ocr-tw-permit为准。请求体结构{ input_type: url, input_data: https://example.com/tw-permit.jpg }两个字段均为必填input_data的值必须与input_type匹配。curl 接入示例可复制测试以下示例使用Authorization头请将$API_KEY替换为你的真实密钥curl -sS -X POST \ -H Authorization: Bearer $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若使用 base64可以这样构造请求体# 先获取图片的base64Linux/Mac BASE64$(base64 -w0 /path/to/tw-permit.jpg) curl -sS -X POST \ -H Authorization: Bearer $API_KEY \ -H Content-Type: application/json \ -d {\input_type\: \base64\, \input_data\: \$BASE64\} \ https://v1.apizero.cn/api/ocr-tw-permit注意在bash中构造JSON体时请确保双引号正确转义或使用jq等工具构建更安全的请求。返回值解读与错误处理成功响应HTTP 200{ code: 0, msg: 成功, request_id: req_abc123, data: { card_number: 12345678901234567, date_of_birth: 1990-01-01, date_of_expiry: 2029-12-31, full_name_cn: 张三, full_name_en: ZHANG SAN } }code0 表示成功非零请参考msg说明。request_id建议随日志记录便于向平台反馈问题。常见错误码错误码说明排查方向1001参数缺失或格式错误检查input_type/input_data是否存在且类型正确1002图片下载失败或base64解码失败URL不可达、图片损坏或base64编码异常1003图片格式不支持确保为jpg/png且文件未损坏1004图片中未识别到台胞证图片不完整、反光严重或非台胞证1010鉴权失败检查API Key是否正确、是否过期或请求头是否为Authorization1020频率超限QPS 2降低并发或引入本地队列缓冲注意响应状态码可能为200但code非0务必以code字段而非HTTP状态码判断业务成功与否。工程化注意事项1. 图片预处理裁剪在传图前建议用前端库如opencv.js自动检测证件四角并裁剪减少背景干扰。修正倾斜若图片倾斜超过10度可进行仿射变换修正后再传。去反光与增强对比度对低对比度图片使用直方图均衡化可提升识别率。2. 并发与重试策略由于QPS2若业务需要批量处理应使用令牌桶或滑动窗口限流避免触发429。对于失败请求网络错误或返回code非0采用指数退避重试初始1秒最大3次。注意不要对同一张图片无限重试防止累积限流。3. 数据校验与异常处理对返回的日期字段进行格式校验如正则^\d{4}-\d{2}-\d{2}$防止无效值入库。当full_name_cn为空时可降级使用英文名辅以人工确认但要注意英文名也可能为空。保留原始图片的hash或存储路径便于后续人工复核异常案例。4. 安全与隐私图片中可能包含个人敏感信息传输过程务必使用HTTPS服务端收到后不应长期缓存原始图片。API Key 应保存在服务端环境变量中避免前端暴露。参考文档台胞证识别 API 官方文档原始 Markdown 文档接口地址POST https://v1.apizero.cn/api/ocr-tw-permit