先聊边界，再聊参数
通常我们对 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_xxx |
| Content-Type | 是 | POST 请求体类型，文档标注为application/x-www-form-urlencoded |
但需要特别说明：官方给出的 curl 示例中实际使用X-API-Key: $APIZERO_API_KEY和Content-Type: application/json。也就是说文档页的 Header 描述与请求示例存在不一致。正式接入时以原始文档或控制台联调提示为准；调试中遇到鉴权报错，优先核对 Header 名和取值。
请求体参数
请求体只有两个必填字段：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| input_type | string | 是 | url或base64 |
| input_data | string | 是 | URL 模式下为图片完整地址；base64 模式下为编码字符串，最大 6MB，可带 data 前缀 |
一个典型的 JSON 请求体：
{ "input_type": "url", "input_data": "https://dummyimage.com/400x100/000/fff.png&text=Hello+World" }这段示例图片地址来自接口文档，可直接用于连通性测试。
curl 接入示例
先把 API Key 放入环境变量，避免把密钥写死在命令历史里：
export OCR_API_KEY="sk_live_xxxxxxxxxxxxxx"URL 模式请求：
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.png&text=Hello+World"}' \ "https://v1.apizero.cn/api/ocr-text"base64 模式请求，先用命令行工具编码本地图片：
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" }字段解读：
| 字段 | 类型 | 说明 |
|---|---|---|
| code | int | 0 表示成功，非 0 表示失败 |
| msg | string | 状态描述 |
| request_id | string | 请求唯一 ID，排查问题时反馈给服务方快速定位 |
| data.text_list | string[] | 按原图顺序排列的行文本数组 |
| data.full_text | string | 用换行符拼接的完整文本 |
| data.text_count | int | 识别到的文本行数 |
| data.input_type | string | 回显请求时使用的输入类型 |
注意：响应里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
