先聊邊界再聊參數(shù)通常我們對 OCR 接口的預(yù)期是給一張圖吐出文字。但對工程來說真正決定是否能落地的不是識別精度而是接口的能力邊界輸入怎么傳、輸出怎么排、在什么限制下運(yùn)行。這篇筆記圍繞 OCR 文字識別接口把能力邊界、適用場景、參數(shù)與接入細(xì)節(jié)串起來講一遍。適用場景哪些需求可以交給它OCR 文字識別定位是通用文字提取輸出逐行文本和拼接后的完整文本。以下場景天然匹配這個設(shè)計截圖轉(zhuǎn)文字聊天記錄、控制臺報錯、網(wǎng)頁正文的截圖都能處理字幕識別從視頻截圖幀中提取字幕文本用于后續(xù)檢索或翻譯筆記與板書 OCR手寫體識別效果依賴圖片清晰度接口支持手寫體身份證 / 名片文字提取證件號、姓名、地址等字段會被逐行切出方便二次解析表格文字抽取能把表格單元格里的文字按行讀出但不會還原表格結(jié)構(gòu)反向思考以下場景不適合這個接口增值稅發(fā)票專用識別需要字段級結(jié)構(gòu)化結(jié)果應(yīng)改用專用接口處理復(fù)雜版面還原多欄排版、圖文混排時文字按視覺行切分順序不一定符合閱讀順序高精度手寫長文手寫內(nèi)容較多且字跡潦草時逐行準(zhǔn)確率會明顯下降一句話總結(jié)選型邏輯只要拿到按順序的文字就夠用的場景通用 OCR 可以直接接入需要嚴(yán)格結(jié)構(gòu)化字段的場景應(yīng)另尋專用接口。能力邊界解讀接口最值得關(guān)注的設(shè)計是雙輸入、三輸出。雙輸入是指圖片可以以兩種方式傳入input_type傳圖方式限制url傳入公網(wǎng)可訪問的圖片 URL服務(wù)端主動拉取需 http/https 可達(dá)base64傳入圖片的 base64 編碼字符串最大 6MB可帶data:image/jpeg;base64,前綴服務(wù)端自動剝離base64 模式對敏感圖片更友好——身份證、名片這類包含個人信息的圖片不會經(jīng)過第三方 URL 服務(wù)商的日志直接在請求體內(nèi)傳遞。前提是編碼后體積控制在 6MB 以內(nèi)。三路輸出是指返回體里同時給三個視圖text_list按原圖順序排列的逐行文本數(shù)組適合逐行業(yè)務(wù)處理full_text用\n拼接好的完整字符串適合直接存儲或全文搜索text_count識別到的文本行數(shù)適合做數(shù)量統(tǒng)計或空圖判斷工程上的價值在于調(diào)用方不需要再自行拼接文本或判斷是否為空圖接口已經(jīng)給了現(xiàn)成的元信息。另一個限制是 QPS 為 2 次每秒即平均每 500ms 允許一次請求。對于內(nèi)部工具類應(yīng)用這個量級足夠但若要支撐多用戶的實(shí)時識別需要在調(diào)用側(cè)限速。接口說明還提到同圖同結(jié)果會緩存 1 小時重復(fù)調(diào)用不消耗上游配額。這個特性在客戶端重試或消息重放時會幫你省掉一部分配額消耗。鑒權(quán)與請求頭按文檔說明請求頭有兩個字段Header必填說明Authorization否API Key 鑒權(quán)頭格式Bearer sk_live_xxxContent-Type是POST 請求體類型文檔標(biāo)注為application/x-www-form-urlencoded但需要特別說明官方給出的 curl 示例中實(shí)際使用X-API-Key: $APIZERO_API_KEY和Content-Type: application/json。也就是說文檔頁的 Header 描述與請求示例存在不一致。正式接入時以原始文檔或控制臺聯(lián)調(diào)提示為準(zhǔn)調(diào)試中遇到鑒權(quán)報錯優(yōu)先核對 Header 名和取值。請求體參數(shù)請求體只有兩個必填字段字段類型必填說明input_typestring是url或base64input_datastring是URL 模式下為圖片完整地址base64 模式下為編碼字符串最大 6MB可帶 data 前綴一個典型的 JSON 請求體{ input_type: url, input_data: https://dummyimage.com/400x100/000/fff.pngtextHelloWorld }這段示例圖片地址來自接口文檔可直接用于連通性測試。curl 接入示例先把 API Key 放入環(huán)境變量避免把密鑰寫死在命令歷史里export OCR_API_KEYsk_live_xxxxxxxxxxxxxxURL 模式請求curl -sS \ -X POST \ -H X-API-Key: ${OCR_API_KEY} \ -H Content-Type: application/json \ -d {input_type: url, input_data: https://dummyimage.com/400x100/000/fff.pngtextHelloWorld} \ https://v1.apizero.cn/api/ocr-textbase64 模式請求先用命令行工具編碼本地圖片IMG_B64$(base64 -w 0 ./demo.png) curl -sS \ -X POST \ -H X-API-Key: ${OCR_API_KEY} \ -H Content-Type: application/json \ -d {\input_type\: \base64\, \input_data\: \${IMG_B64}\} \ https://v1.apizero.cn/api/ocr-text這里-w 0讓 base64 編碼不換行避免整個 JSON 請求體被拆成多段是 base64 傳圖時最常見的坑。響應(yīng)字段解讀成功響應(yīng)示例{ code: 0, data: { full_text: 商品名稱無線藍(lán)牙耳機(jī)\n單價￥299.00\n數(shù)量2, input_type: url, text_count: 3, text_list: [ 商品名稱無線藍(lán)牙耳機(jī), 單價￥299.00, 數(shù)量2 ] }, msg: 成功, request_id: abc123def456 }字段解讀字段類型說明codeint0 表示成功非 0 表示失敗msgstring狀態(tài)描述request_idstring請求唯一 ID排查問題時反饋給服務(wù)方快速定位data.text_liststring[]按原圖順序排列的行文本數(shù)組data.full_textstring用換行符拼接的完整文本data.text_countint識別到的文本行數(shù)data.input_typestring回顯請求時使用的輸入類型注意響應(yīng)里full_text的\n在 JSON 傳輸中是被轉(zhuǎn)義的字符串。如果在 Python 里json.loads之后再打印會看到真實(shí)的換行如果在代碼里直接拼字符串請保留\n的語義。常見錯誤與排查路徑根據(jù)接口的行為特征常見四類問題第一類鑒權(quán)報錯?，F(xiàn)象是返回 401 或權(quán)限相關(guān)錯誤。優(yōu)先檢查 Header 名和取值是Authorization: Bearer sk_live_xxx還是X-API-Key: sk_live_xxx以文檔示例為準(zhǔn)別混用。第二類請求體格式錯誤。返回 400 時檢查 JSON 是否合法、字段名是否拼錯、input_type是否在枚舉范圍內(nèi)。第三類URL 模式無法拉圖。圖片地址必須是公網(wǎng)可訪問的 http/https 鏈接內(nèi)網(wǎng)地址、帶自簽證書的地址、需要登錄態(tài)的 CDN 都會導(dǎo)致服務(wù)端拉取失敗。第四類超過 QPS 限制或體積上限。base64 超過 6MB 會被拒絕需要壓縮圖片或改用 URL 模式并發(fā)太高時收到限流響應(yīng)需要在客戶端做間隔控制或退避重試。工程化注意事項(xiàng)結(jié)合接口能力落地時建議做以下四件事。請求側(cè)統(tǒng)一封裝。把輸入拼裝、鑒權(quán)頭、超時值、重試策略收斂到一個函數(shù)里避免每個調(diào)用點(diǎn)各寫一份 curl后續(xù)維護(hù)維護(hù)復(fù)雜度會高出很多。圖片預(yù)處理。識別前做統(tǒng)一處理轉(zhuǎn) RGB、壓縮到合理分辨率、必要時做方向矯正能顯著提高遮擋和模糊場景的識別穩(wěn)定性。這不是接口能力范圍內(nèi)的要求但直接影響最終效果?？蛻舳硕尉彺妗７?wù)端已經(jīng)緩存同圖結(jié)果 1 小時那是保護(hù)服務(wù)端配額用的業(yè)務(wù)側(cè)仍應(yīng)在圖片指紋不變 短時間窗口內(nèi)緩存識別結(jié)果減少網(wǎng)絡(luò)往返。處理隱私數(shù)據(jù)時優(yōu)先 base64。身份證、合同、名片類圖片不要走 URL 模式控制圖片只出現(xiàn)在請求體內(nèi)降低經(jīng)手日志泄露信息的風(fēng)險。參考文檔文檔頁https://apizero.cn/aidocs/ocr-text原始文檔https://apizero.cn/aidocs/ocr-text/raw.md