在线开户、支付绑卡时手动输入卡号既慢又易错。银行卡识别接口能从图片中提取卡号与有效期用于辅助录入和核对。本文从第一次调用写起讲清要准备什么、最小请求怎么发、返回值怎么看。一、适用场景在线开户用户上传卡面照自动填入卡号减少手输。支付绑卡辅助录入识别后由用户确认再提交。卡号核对比对用户填写内容与图片识别结果。客服工单从用户上传的截图中提取关键信息。识别结果是辅助录入用的最终仍需用户确认不建议跳过确认环节直接提交。二、接口能力边界项目说明请求方法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}, timeout15, ) 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 有限重试识别为空不重试。展示格式有效期统一格式化后再展示避免不同来源格式不一。参考文档接口文档