银行卡识别接口零基础接入：参数、curl 示例与返回字段解读
在线开户、支付绑卡时，手动输入卡号既慢又易错。银行卡识别接口能从图片中提取卡号与有效期，用于辅助录入和核对。本文从第一次调用写起，讲清要准备什么、最小请求怎么发、返回值怎么看。
一、适用场景
- 在线开户：用户上传卡面照，自动填入卡号，减少手输。
- 支付绑卡辅助录入：识别后由用户确认再提交。
- 卡号核对：比对用户填写内容与图片识别结果。
- 客服工单：从用户上传的截图中提取关键信息。
识别结果是辅助录入用的，最终仍需用户确认，不建议跳过确认环节直接提交。
二、接口能力边界
| 项目 | 说明 |
|---|---|
| 请求方法 | POST |
| 参数 | input_type、input_data |
| 识别内容 | 银行卡号、有效期 |
| 输入方式 | URL、Base64 两种 |
| 图片格式 | jpg、png |
| 文件大小 | 不超过 10MB |
| 识别效果 | 图片清晰、卡面完整时效果更好 |
接口只识别卡号与有效期，不校验卡号真实性，也不返回银行归属信息。识别成功不等于卡号有效，业务侧仍需自行校验。
三、请求参数与鉴权
参数共两个：
| 参数 | 说明 |
|---|---|
input_type | 输入类型，区分 URL 与 Base64，取值以文档为准 |
input_data | 输入数据，与input_type对应 |
鉴权方式、请求头字段名与请求体编码，素材未给出，以文档为准。接入前请先在文档中确认 API Key 的传递位置。
调用前先做本地校验：格式是否为 jpg/png、大小是否在 10MB 以内、卡面是否完整。这三项能提前过滤大部分无效请求。
四、最小请求示例
下面是一个可复制的 curl 模板，YOUR_API_KEY、input_type取值与input_data均为占位，请按文档替换。
curl -X POST 'https://v1.apizero.cn/api/ocr-bank-card' \ -H 'Content-Type: application/json' \ -H 'Authorization: YOUR_API_KEY' \ -d '{ "input_type": "<按文档填写，区分 URL 与 Base64>", "input_data": "<图片 URL 或 Base64 字符串>" }'对应的 Python 示例，读取本地图片转 Base64 后提交：
import base64 import requests def read_bank_card(image_path: str, input_type: str, api_key: str) -> dict: with open(image_path, "rb") as f: raw = f.read() if len(raw) > 10 * 1024 * 1024: raise ValueError("图片超过 10MB") input_data = base64.b64encode(raw).decode("utf-8") resp = requests.post( "https://v1.apizero.cn/api/ocr-bank-card", headers={"Authorization": api_key}, json={"input_type": input_type, "input_data": input_data}, timeout=15, ) resp.raise_for_status() return resp.json()用 URL 方式时，把input_data换成可公网访问的图片地址，input_type取文档中对应值。
五、返回值解读
素材说明返回卡号与有效期，具体字段名以文档为准。建议这样处理：
- 取卡号字段，去掉空格后做数字与长度校验。
- 取有效期字段，展示前统一格式化。
- 任一字段缺失时按“识别不完整”处理，引导重拍或手动输入。
一个防御式解析示例（字段名请替换为文档实际名称）：
def parse_card(payload: dict) -> dict: data = payload.get("data") or {} number = (data.get("number") or "").replace(" ", "") # 字段名以文档为准 expiry = data.get("expiry") or "" # 字段名以文档为准 ok = number.isdigit() and 12 <= len(number) <= 19 return {"number": number, "expiry": expiry, "complete": ok}卡号长度用宽松范围校验即可，不要固定 16 位，避免误杀其他卡种。
六、常见错误与排查
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 鉴权失败 | Key 缺失或位置错误 | 核对请求头，以文档为准 |
| 参数错误 | input_type与input_data不匹配 | 按文档确认取值与数据形式 |
| 文件过大 | 图片超过 10MB | 上传前压缩或裁剪 |
| 格式不支持 | 非 jpg/png | 转码后再提交 |
| 识别为空 | 卡面模糊、倾斜、遮挡 | 提示重拍，保证卡面完整 |
| 超时 | 图片过大或网络抖动 | 设置超时，压缩后重试 |
识别为空多为图片质量问题，映射为“请重拍”提示比直接报错更友好。
七、工程化注意事项
- 前端预校验：客户端就限制格式与大小，减少无效请求。
- 用户确认：识别结果回填后需用户确认，不自动提交。
- 敏感数据：卡号属于敏感信息，日志必须脱敏，Base64 图片不落盘。
- 传输体积：Base64 会放大约三分之一，大图优先用 URL 方式。
- 重试边界：只对超时与 5xx 有限重试，识别为空不重试。
- 展示格式：有效期统一格式化后再展示，避免不同来源格式不一。
参考文档
- 接口文档