在线开户、支付绑卡这类流程里让用户手动输入一长串卡号既慢又容易出错。银行卡识别接口可以从图片中识别卡号与有效期辅助录入和核对。本文从第一次调用写起要准备什么、最小请求怎么发、返回值怎么看。一、适用场景在线开户用户上传银行卡照片后自动填入卡号减少手输错误。支付绑卡辅助录入识别后由用户确认再进入后续流程。卡号核对用户提交的卡号与图片识别结果做一致性比对。客服工单用户上传卡面截图时辅助提取关键信息。注意识别结果是“辅助录入”用的最终仍应让用户确认不要直接跳过人工确认环节。二、接口能力边界项目说明请求方法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按文档对应取值。五、返回值解读素材说明返回“卡号与有效期”具体字段名以文档为准。接入时建议按以下方式处理读取卡号字段去掉识别结果中的空格再做长度与数字格式校验。读取有效期字段格式如 MM/YY 或 MM/YY 以外的形式以文档为准展示前统一格式化。任一字段缺失时按“识别不完整”处理引导用户重拍或手动输入。一个防御式解析示例字段名请替换为文档中的实际名称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 做有限次重试识别为空不重试。有效期展示统一格式化后再展示避免不同来源格式不一致。参考文档接口文档
