开发必读：银行卡识别API参数详解与接入最佳实践

适用场景银行卡识别是移动支付、金融科技和身份验证场景中的高频能力。当用户需要快速录入银行卡号或有效期时手动输入容易出错且体验不佳。以下场景可以直接复用该接口在线开户用户上传银行卡照片后台自动提取卡号和有效期自动填入表单。支付绑卡APP中用户拍照或选择相册图片实时识别并绑定银行卡。卡号核对将识别结果与用户手输信息交叉验证降低人工审核维护复杂度。后台单据处理读取扫描件或截图中的银行卡信息用于记账或清结算。接口能力边界在开始对接参数之前需要了解该接口的约束条件以避免传参不当导致失败。属性说明接口地址POST https://v1.apizero.cn/api/ocr-bank-card请求方式POST图片格式jpg / png文件大小上限10 MB输入方式公网图片URL 或 Base64 编码字符串QPS 限制2 次/秒接口默认不返回银行卡发卡行、卡片类型等附带信息如有需要可参考官方文档了解是否支持扩展参数。鉴权与请求头API 请求需要通过请求头传递身份凭证。根据实际测试该接口支持两种鉴权方式任选其一即可方式一推荐Authorization: Bearer 你的API Key方式二X-API-Key: 你的API Key建议在工程中使用方式一符合 HTTP Bearer Token 标准通用性更强。请求头示例Content-Type: application/json Authorization: Bearer sk_xxxxxxxxxxxxxxxx注意Content-Type必须设置为application/json请求体以 JSON 格式传递。请求参数详解接口请求体是一个 JSON 对象包含两个必填字段。下面逐一说明每个字段的设计意图和最佳填法。input_typestring必填可选值url或base64作用指明input_data字段的编码格式。最佳实践如果图片已经存储于可访问的公网地址如对象存储、CDN使用url模式更简单不需要额外编码。如果图片来自客户端上传的二进制数据例如 multipart 接收后读取字节流优先使用base64模式避免中间环节存储临时文件。input_datastring必填作用承载图片的二进制数据或地址。约束input_typeurl时必须是可以直接通过 HTTP/HTTPS 访问的图片链接服务器会从该 URL 下载图片进行识别。图片大小不超过 10MB。input_typebase64时填入图片二进制数据的 Base64 编码字符串。支持携带data:image/xxx;base64,前缀也支持纯 Base64 内容。建议客户端拍完照后直接在前端用 FileReader 读取为 Base64后端无需额外处理。最佳实践URL 模式下的图片链接务必确保公网可达私有内网地址或需要鉴权的图片链接会被拒绝。Base64 字符串长度约为原始文件的 1.37 倍10MB 图片产生的 Base64 约 13.7MB需确保传输链路和 API 网关无大小限制。图片尺寸过长或过宽会影响识别效果建议保持卡面居中、无明显反光。可以拍摄时使用“辅助框”引导用户对齐。请求体完整示例{ input_type: url, input_data: https://storage.example.com/user_upload/bank_card_2025.jpg }请求示例curl Pythoncurl 请求可直接复制测试替换$API_KEYexport API_KEYyour-api-key-here curl -sS \ -X POST \ -H Authorization: Bearer $API_KEY \ -H Content-Type: application/json \ -d { input_type: url, input_data: https://example.com/bankcard.jpg } \ https://v1.apizero.cn/api/ocr-bank-card注意示例中的“https://example.com/bankcard.jpg”请替换为真实的可访问图片地址。若使用 Base64可以将input_type改为base64input_data填入编码后字符串。Python 请求示例使用requests库import requests API_URL https://v1.apizero.cn/api/ocr-bank-card API_KEY your-api-key-here headers { Authorization: fBearer {API_KEY}, Content-Type: application/json } def recognize_by_url(image_url: str) - dict: payload { input_type: url, input_data: image_url } resp requests.post(API_URL, headersheaders, jsonpayload) resp.raise_for_status() return resp.json() # 调用示例 result recognize_by_url(https://example.com/bankcard.jpg) print(result)响应字段解析成功响应的 HTTP 状态码为 200响应体为 JSON 格式顶层字段说明如下字段类型说明codeinteger业务状态码0 表示成功非 0 表示失败。msgstring对应 code 的可读消息成功时为“成功”。request_idstring单次请求的唯一标识符可用于日志追踪和问题反馈。dataobject识别结果仅在 code0 时存在。data内部字段字段类型示例说明card_numberstring6222 0202 0001 5920 8银行卡号可能带有空格便于人工阅读实际使用时建议去除空格。date_of_expirystring12/28卡片有效期格式为MM/YY如果没有有效期如借记卡可能返回空字符串。注意返回的card_number中的空格是文档示例格式实际接口可能返回纯数字或带空格请以实际响应为准。开发时应当通过replace( , )去掉所有空格。错误响应示例{ code: 401, msg: 无效的API密钥或权限不足, request_id: req_err_xxxx, data: null }错误处理与常见问题错误现象可能原因排查步骤401 UnauthorizedAPI Key 错误或未传递确认请求头中的Authorization或X-API-Key检查 Key 是否有效。400 Bad Request请求体JSON格式错误或缺少必填字段使用jq或在线 JSON 校验工具验证 payload。图片识别失败code≠0msg含“识别失败”图片过小、过模糊、卡面不全或格式不支持确保图片分辨率不低于 300x200 像素卡面占图片面积 70% 以上避免反光/遮挡。413 Request Entity Too Large图片超过 10MB压缩图片或限制上传文件大小。429 Too Many Requests超过 QPS 2次/秒加入本地队列或使用 token bucket 流控建议间隔 500ms 以上。耗时过长5秒图片太大或网络链路慢缩小图片宽高建议最长边 2048px 以内或改用 Base64 减少网络开销。工程化注意事项1. 并发控制与重试策略由于接口 QPS 限制为 2生产环境中建议使用信号量或令牌桶进行限流。对于失败请求如 5xx 或超时采用指数退避重试最大重试 3 次初始间隔 1s。import time import requests from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type retry( stopstop_after_attempt(3), waitwait_exponential(multiplier1, min1, max4), retryretry_if_exception_type((requests.ConnectionError, requests.Timeout)) ) def robust_recognize(image_url: str): # 调用 recognize_by_url 并处理非200状态码 resp requests.post(API_URL, headersheaders, json{ input_type: url, input_data: image_url }, timeout30) if resp.status_code 429: time.sleep(1) raise requests.exceptions.RequestException(rate limited) resp.raise_for_status() return resp.json()2. 图片预处理方向矫正接口对旋转后的图片鲁棒性一般建议在调用前自动检测图片 EXIF 方向并矫正。亮度对比度过暗或过亮图片可以先进行直方图均衡化。裁剪如果图片中包含多余背景使用轮廓检测找到银行卡区域裁剪后提交。3. Base64 传输优化客户端先压缩图片例如将最长边缩放到 1024pxJPEG 质量 80%再编码可以显著降低传输延迟和失败率。后端接收后无需二次处理直接透传。4. 缓存与幂等同一张图片的识别结果在短时间内不会变化除非更换卡面建议按图片 MD5 哈希建立当日缓存减少重复调用。注意有效期字段可能随批次不同而一致但卡号通常是固定的可缓存卡号。5. 日志与监控记录每次请求的request_id、input_type、耗时、结果code。对code ! 0的请求增加告警便于及时排查接口可用性。参考文档接口文档页https://apizero.cn/aidocs/ocr-bank-card原始 Markdown 文档https://apizero.cn/aidocs/ocr-bank-card/raw.md本文所有参数与请求示例均来自官方文档实际调用时请以最新版文档为准。