最小可运行示例：OCR文字识别API接入与参数详解-平芜编程栈

适用场景

通用OCR（光学字符识别）是许多业务系统的刚需。以下场景中，一个稳定、易接入的OCR API可以直接降低开发维护复杂度：

截图转文本：用户提交全屏或区域截图，提取其中的文字用于搜索、翻译或存档。
证件/名片信息录入：自动识别身份证号、姓名、公司名、电话等字段，减少人工录入。
字幕/弹幕提取：从视频帧中提取字幕文字，用于多语言翻译或内容审核。
笔记OCR：手写或印刷笔记拍照后转成可编辑文本。

本文以/api/ocr-text接口为例，从最小的可运行调用出发，逐步拆解每个参数的含义与返回值结构，让新手也能快速上手。

接口能力边界

在写代码之前，需要先了解接口的能力与限制，避免在集成阶段踩坑。

维度	说明
支持语言	中文、英文、数字、符号、常见手写体
输入模式	`url`（公网图片URL）或`base64`（图片base64字符串）
输入限制	base64模式：字符串 ≤ 6MB（解码后约6MB图片）。URL模式：图片地址须公网可访问
输出内容	逐行文本列表、完整拼接文本、文本行数
QPS	2请求/秒（超过将返回限流错误）
缓存策略	相同图片在1小时内重复调用时命中缓存，不消耗上游配额
鉴权	可选：使用API Key（`Bearer sk_live_xxx`）或匿名调用（每日5次）

特别说明：对于专用发票识别，该接口不保证精准，请使用/api/invoice专用接口。

请求参数与鉴权

接口地址：https://v1.apizero.cn/api/ocr-text
请求方法：POST
Content-Type：application/x-www-form-urlencoded（在curl中以JSON格式传递时，实际HTTP body为JSON字符串，但Content-Type固定为application/x-www-form-urlencoded，这是部分API网关的特性，请以文档为准）

Header 参数

参数名	必须	类型	说明
`Authorization`	否	string	API Key鉴权。格式：`Bearer sk_live_xxxxxxxxxxxxxx`。匿名调用可省略（每日5次）
`Content-Type`	是	string	固定值`application/x-www-form-urlencoded`或`application/json`？根据curl示例和文档，使用`application/json`也可正常工作。但官网Header要求为`application/x-www-form-urlencoded`。这里以官方文档为准，但实际测试时多数实现使用`application/json`也能正确响应。建议优先遵循文档。

Body 参数（JSON对象）

参数名	必须	类型	说明
`input_type`	是	string	`url`或`base64`
`input_data`	是	string	当`input_type=url`时，传入图片的完整HTTP/HTTPS URL；当`input_type=base64`时，传入图片的base64编码字符串（最大6MB，支持`data:image/...;base64,`前缀，SDK会自动剥离）

完整请求体示例：

{ "input_type": "url", "input_data": "https://dummyimage.com/400x100/000/fff.png&text=Hello+World" }

最小可运行示例：curl

以下是最简单的调用方式，使用匿名模式（不带Authorization）。请替换图片URL为你的实际公网图片地址。

curl -sS -X POST \ -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"

若你已申请API Key（格式sk_live_xxx），可以增加鉴权头：

curl -sS -X POST \ -H "Authorization: Bearer sk_live_your_api_key_here" \ -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"

Python 接入示例

import requests import json url = "https://v1.apizero.cn/api/ocr-text" headers = { "Content-Type": "application/json", # "Authorization": "Bearer sk_live_your_api_key_here" # 可选 } payload = { "input_type": "url", "input_data": "https://dummyimage.com/400x100/000/fff.png&text=Hello+World" } response = requests.post(url, headers=headers, data=json.dumps(payload)) print(response.json())

输出示例（成功时）：

{ "code": 0, "msg": "成功", "request_id": "abc123def456", "data": { "input_type": "url", "text_count": 1, "text_list": ["Hello World"], "full_text": "Hello World" } }

返回值解读

成功响应（HTTP 200）的JSON结构如下：

字段	类型	说明
`code`	int	业务状态码，`0`表示成功，非零值表示错误
`msg`	string	响应信息，成功时为`"成功"`，失败时包含错误描述
`request_id`	string	本次请求的唯一标识，用于追踪日志
`data`	object	核心数据对象
├──`input_type`	string	回传请求中的`input_type`
├──`text_count`	int	识别到的文本行数
├──`text_list`	string[]	按原图文字顺序排列的逐行文本数组
└──`full_text`	string	所有行以换行符`\n`拼接而成的完整文本

例如，一张包含“商品名称：无线蓝牙耳机\n单价：¥299.00\n数量：2”的图片，返回的text_list依次为：

[ "商品名称：无线蓝牙耳机", "单价：¥299.00", "数量：2" ]

full_text则为：

商品名称：无线蓝牙耳机\n单价：¥299.00\n数量：2

若图片中没有可识别文字（空白图），text_count为0，text_list和full_text为空字符串或空数组（具体以实际响应为准）。

常见错误与排查

错误描述（`msg`字段）	可能原因	解决方式
"参数缺失：input_type"	请求体中缺少`input_type`或值为空	检查JSON字段拼写，确保必填字段存在
"图片URL无法访问"	`input_data`指定的URL不可达（404/403/超时）	确认图片公网可访问，或使用`base64`模式
"base64数据过大"	base64字符串解码后超过6MB	压缩图片至合理大小（建议宽度≤2048px），或使用URL模式
"QPS超出限制"	每秒请求超过2次	加入客户端限流（令牌桶或延时队列），或降低并发
"鉴权失败"	Authorization 格式错误或Key已失效	检查`Bearer`前缀，确认API Key有效
"未能识别有效文字"	图片太模糊、翻转、文字太小	调整图片质量，确保文字清晰

若收到code非0且msg为中文提示，可直接按提示修正。若遇到HTTP 429响应，检查是否触发QPS限制。

工程化注意事项

生产环境中直接裸调用API往往不够健壮，以下建议可供参考：

异步与重试机制：使用asyncio+aiohttp或线程池发起请求，并设置指数退避重试策略（如5xx、限流429时重试最多3次）。
缓存设计：同一图片在1小时内重复调用会命中API端缓存，但在客户端也可根据图片MD5做本地缓存，避免重复网络请求。
图片预处理：OCR识别率高度依赖图片质量。建议在调用前进行灰度化、降噪、二值化、旋转校正等预处理，尤其对于手机拍摄的图片。可使用OpenCV或Pillow库。
并发控制：QPS限制为2，可在客户端维护一个令牌桶，每秒发放2个令牌，确保不超限。也可将多个识别任务排队。
监控与日志：记录每次调用的request_id、耗时、返回码，便于排查。若发现大量“未能识别文字”的失败，检查图片预处理流程。
安全性：避免将API Key硬编码在客户端代码中，应通过环境变量或配置中心注入。匿名调用有每日次数限制，生产环境务必配置正式Key。