适用场景通用OCR光学字符识别是许多业务系统的刚需。以下场景中一个稳定、易接入的OCR API可以直接降低开发维护复杂度截图转文本用户提交全屏或区域截图提取其中的文字用于搜索、翻译或存档。证件/名片信息录入自动识别身份证号、姓名、公司名、电话等字段减少人工录入。字幕/弹幕提取从视频帧中提取字幕文字用于多语言翻译或内容审核。笔记OCR手写或印刷笔记拍照后转成可编辑文本。本文以/api/ocr-text接口为例从最小的可运行调用出发逐步拆解每个参数的含义与返回值结构让新手也能快速上手。接口能力边界在写代码之前需要先了解接口的能力与限制避免在集成阶段踩坑。维度说明支持语言中文、英文、数字、符号、常见手写体输入模式url公网图片URL或base64图片base64字符串输入限制base64模式字符串 ≤ 6MB解码后约6MB图片。URL模式图片地址须公网可访问输出内容逐行文本列表、完整拼接文本、文本行数QPS2请求/秒超过将返回限流错误缓存策略相同图片在1小时内重复调用时命中缓存不消耗上游配额鉴权可选使用API KeyBearer sk_live_xxx或匿名调用每日5次特别说明对于专用发票识别该接口不保证精准请使用/api/invoice专用接口。请求参数与鉴权接口地址https://v1.apizero.cn/api/ocr-text请求方法POSTContent-Typeapplication/x-www-form-urlencoded在curl中以JSON格式传递时实际HTTP body为JSON字符串但Content-Type固定为application/x-www-form-urlencoded这是部分API网关的特性请以文档为准Header 参数参数名必须类型说明Authorization否stringAPI 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是stringurl或base64input_data是string当input_typeurl时传入图片的完整HTTP/HTTPS URL当input_typebase64时传入图片的base64编码字符串最大6MB支持data:image/...;base64,前缀SDK会自动剥离完整请求体示例{ input_type: url, input_data: https://dummyimage.com/400x100/000/fff.pngtextHelloWorld }最小可运行示例curl以下是最简单的调用方式使用匿名模式不带Authorization。请替换图片URL为你的实际公网图片地址。curl -sS -X POST \ -H Content-Type: application/json \ -d {input_type: url, input_data: https://dummyimage.com/400x100/000/fff.pngtextHelloWorld} \ 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.pngtextHelloWorld} \ https://v1.apizero.cn/api/ocr-textPython 接入示例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.pngtextHelloWorld } response requests.post(url, headersheaders, datajson.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结构如下字段类型说明codeint业务状态码0表示成功非零值表示错误msgstring响应信息成功时为成功失败时包含错误描述request_idstring本次请求的唯一标识用于追踪日志dataobject核心数据对象├──input_typestring回传请求中的input_type├──text_countint识别到的文本行数├──text_liststring[]按原图文字顺序排列的逐行文本数组└──full_textstring所有行以换行符\n拼接而成的完整文本例如一张包含“商品名称无线蓝牙耳机\n单价¥299.00\n数量2”的图片返回的text_list依次为[ 商品名称无线蓝牙耳机, 单价¥299.00, 数量2 ]full_text则为商品名称无线蓝牙耳机\n单价¥299.00\n数量2若图片中没有可识别文字空白图text_count为0text_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往往不够健壮以下建议可供参考异步与重试机制使用asyncioaiohttp或线程池发起请求并设置指数退避重试策略如5xx、限流429时重试最多3次。缓存设计同一图片在1小时内重复调用会命中API端缓存但在客户端也可根据图片MD5做本地缓存避免重复网络请求。图片预处理OCR识别率高度依赖图片质量。建议在调用前进行灰度化、降噪、二值化、旋转校正等预处理尤其对于手机拍摄的图片。可使用OpenCV或Pillow库。并发控制QPS限制为2可在客户端维护一个令牌桶每秒发放2个令牌确保不超限。也可将多个识别任务排队。监控与日志记录每次调用的request_id、耗时、返回码便于排查。若发现大量“未能识别文字”的失败检查图片预处理流程。安全性避免将API Key硬编码在客户端代码中应通过环境变量或配置中心注入。匿名调用有每日次数限制生产环境务必配置正式Key。参考文档官方文档页https://apizero.cn/aidocs/ocr-text原始文档Markdown格式https://apizero.cn/aidocs/ocr-text/raw.md本文仅作技术参考接口参数以官方最新文档为准。