先聊边界再聊参数通常我们对 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