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