在線開戶、支付綁卡這類流程里讓用戶手動(dòng)輸入一長串卡號(hào)既慢又容易出錯(cuò)。銀行卡識(shí)別接口可以從圖片中識(shí)別卡號(hào)與有效期輔助錄入和核對(duì)。本文從第一次調(diào)用寫起要準(zhǔn)備什么、最小請(qǐng)求怎么發(fā)、返回值怎么看。一、適用場景在線開戶用戶上傳銀行卡照片后自動(dòng)填入卡號(hào)減少手輸錯(cuò)誤。支付綁卡輔助錄入識(shí)別后由用戶確認(rèn)再進(jìn)入后續(xù)流程?？ㄌ?hào)核對(duì)用戶提交的卡號(hào)與圖片識(shí)別結(jié)果做一致性比對(duì)。客服工單用戶上傳卡面截圖時(shí)輔助提取關(guān)鍵信息。注意識(shí)別結(jié)果是“輔助錄入”用的最終仍應(yīng)讓用戶確認(rèn)不要直接跳過人工確認(rèn)環(huán)節(jié)。二、接口能力邊界項(xiàng)目說明請(qǐng)求方法POST參數(shù)input_type、input_data識(shí)別內(nèi)容銀行卡號(hào)、有效期輸入方式URL、Base64 兩種圖片格式j(luò)pg、png文件大小不超過 10MB識(shí)別效果圖片清晰、卡面完整時(shí)效果更好需要明確接口只識(shí)別卡號(hào)與有效期不校驗(yàn)卡號(hào)真實(shí)性也不做銀行歸屬查詢。識(shí)別成功不等于卡號(hào)有效業(yè)務(wù)上仍需走各自的校驗(yàn)流程。三、請(qǐng)求參數(shù)與鑒權(quán)參數(shù)共兩個(gè)參數(shù)說明input_type輸入類型區(qū)分 URL 與 Base64具體取值以文檔為準(zhǔn)input_data輸入數(shù)據(jù)與input_type對(duì)應(yīng)鑒權(quán)方式、請(qǐng)求頭字段名與請(qǐng)求體編碼素材未給出以文檔為準(zhǔn)。接入前請(qǐng)先在文檔中確認(rèn) API Key 的傳遞位置。調(diào)用前先做本地校驗(yàn)文件格式是否為 jpg/png、大小是否在 10MB 以內(nèi)、卡面是否完整。這三項(xiàng)能過濾掉大部分失敗請(qǐng)求。四、最小請(qǐng)求示例下面是一個(gè)可復(fù)制的 curl 模板YOUR_API_KEY、input_type取值與input_data內(nèi)容均為占位請(qǐng)按文檔替換。curl -X POST https://v1.apizero.cn/api/ocr-bank-card \ -H Content-Type: application/json \ -H Authorization: YOUR_API_KEY \ -d { input_type: 按文檔填寫區(qū)分 URL 與 Base64, input_data: 圖片 URL 或 Base64 字符串 }對(duì)應(yīng)的 Python 調(diào)用示例用本地圖片轉(zhuǎn) 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換成可公網(wǎng)訪問的圖片地址input_type按文檔對(duì)應(yīng)取值。五、返回值解讀素材說明返回“卡號(hào)與有效期”具體字段名以文檔為準(zhǔn)。接入時(shí)建議按以下方式處理讀取卡號(hào)字段去掉識(shí)別結(jié)果中的空格再做長度與數(shù)字格式校驗(yàn)。讀取有效期字段格式如 MM/YY 或 MM/YY 以外的形式以文檔為準(zhǔn)展示前統(tǒng)一格式化。任一字段缺失時(shí)按“識(shí)別不完整”處理引導(dǎo)用戶重拍或手動(dòng)輸入。一個(gè)防御式解析示例字段名請(qǐng)?zhí)鎿Q為文檔中的實(shí)際名稱def parse_card(payload: dict) - dict: data payload.get(data) or {} number (data.get(number) or ).replace( , ) # 字段名以文檔為準(zhǔn) expiry data.get(expiry) or # 字段名以文檔為準(zhǔn) ok number.isdigit() and 12 len(number) 19 return {number: number, expiry: expiry, complete: ok}卡號(hào)長度按行業(yè)常見范圍做寬松校驗(yàn)即可不要用固定 16 位硬卡避免誤殺其他卡種。六、常見錯(cuò)誤與排查現(xiàn)象可能原因排查方向鑒權(quán)失敗Key 缺失或位置錯(cuò)誤核對(duì)請(qǐng)求頭以文檔為準(zhǔn)參數(shù)錯(cuò)誤input_type與input_data不匹配按文檔確認(rèn)取值與數(shù)據(jù)形式文件過大圖片超過 10MB上傳前壓縮或裁剪格式不支持非 jpg/png轉(zhuǎn)碼后再提交識(shí)別為空卡面模糊、傾斜、遮擋提示用戶重拍保證卡面完整超時(shí)圖片過大或網(wǎng)絡(luò)抖動(dòng)設(shè)置超時(shí)壓縮圖片后重試識(shí)別為空通常是圖片質(zhì)量問題不是接口故障。把它映射為“請(qǐng)重試拍攝”的提示比直接報(bào)錯(cuò)更友好。七、工程化注意事項(xiàng)前端預(yù)校驗(yàn)在客戶端就限制格式與大小減少無效請(qǐng)求。用戶確認(rèn)識(shí)別結(jié)果填入表單后仍需用戶確認(rèn)不要自動(dòng)提交。敏感數(shù)據(jù)卡號(hào)屬于敏感信息日志中必須脫敏Base64 圖片不要落盤。傳輸安全Base64 會(huì)放大體積大圖優(yōu)先用 URL 方式避免請(qǐng)求體過大。重試策略只對(duì)超時(shí)和 5xx 做有限次重試識(shí)別為空不重試。有效期展示統(tǒng)一格式化后再展示避免不同來源格式不一致。參考文檔接口文檔