适用场景简述OCR文字识别接口可将图片中的印刷体或手写体文字提取为可编辑文本适用于截图转文字、表格内容识别、身份证/名片信息提取、视频字幕识别、笔记数字化等通用场景。本文重点讨论该接口的调用限制与用量边界帮助开发者在集成时合理规划请求频率、数据大小及鉴权方式。接口能力边界请求速率限制QPS 2/s该接口的每秒查询数QPS上限为2。在稳定网络下客户端每秒最多只能成功发起 2 次请求。若 1 秒内超过 2 个请求第 3 个及之后的请求将返回 HTTP 429 Too Many Requests 或业务层限流错误码。建议客户端侧实现请求队列或令牌桶算法控制并发数例如使用semaphore限制最大并发为 2。输入数据限制接口支持两种输入模式URL 和 Base64。URL 模式input_typeurlinput_data为公网可访问的完整图片 URL。图片本身大小受源站和网络带宽影响若图片过大或下载超时可能导致请求失败。最佳实践是将图片压缩至 2MB 以下并确保 URL 在请求期间稳定可达。Base64 模式input_typebase64input_data为图片的 Base64 编码字符串。服务端限制该字符串最大不超过 6MB编码前原始图片数据约 4.5MB。若超出 6MB 将返回参数错误。编码时可带data:image/...;base64,前缀服务端会自动剥离但建议开发者提前去除以提高兼容性。缓存机制与配额节省该接口对同一张图片相同 URL 或相同 Base64 内容的 OCR 结果进行1 小时缓存。在缓存有效期内重复请求同一图片不会消耗上游配额即不会扣减匿名调用次数或计费额度。这一机制对于定时轮询同一截图如监控仪表盘非常有用可显著降低实际调用量同时提升响应速度。匿名调用限制未携带Authorization头的匿名调用每个来源基于 IP 或设备指纹具体以平台策略为准每日最多5 次。超过后接口将返回 401 鉴权错误。生产环境务必使用有效的 API Key 进行鉴权。鉴权与请求头Content-Type固定为application/json根据官方 curl 示例请求体采用 JSON 格式故推荐Content-Type: application/json。但 Header 参数说明中写的是application/x-www-form-urlencoded存在歧义。实际测试以文档页最新说明为准若强制要求 urlencoded则需将参数编码为input_typeurlinput_data...形式。本文示例采用 JSON 格式。Authorization格式为Bearer sk_live_xxxx匿名调用时不传或置空。curl 请求示例以下示例使用 API Key 鉴权并传入 JSON 格式请求体export OCR_API_KEYsk_live_your_key_here curl -sS -X POST https://v1.apizero.cn/api/ocr-text \ -H Authorization: Bearer $OCR_API_KEY \ -H Content-Type: application/json \ -d { input_type: url, input_data: https://dummyimage.com/400x100/000/fff.png?textHelloWorld }Base64 模式请求BASE64_DATA$(base64 -w0 ./test.png) curl -sS -X POST https://v1.apizero.cn/api/ocr-text \ -H Authorization: Bearer $OCR_API_KEY \ -H Content-Type: application/json \ -d {\input_type\: \base64\, \input_data\: \$BASE64_DATA\}匿名调用每日 5 次限制curl -sS -X POST https://v1.apizero.cn/api/ocr-text \ -H Content-Type: application/json \ -d { input_type: url, input_data: https://dummyimage.com/400x100/000/fff.png?textHelloWorld }返回字段解读成功响应HTTP 200示例{ 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业务状态码0 表示成功非 0 表示错误。msg描述信息用于调试。data主体数据。text_list按图片原始顺序排列的逐行文本数组。full_text用换行符拼接text_list得到的完整字符串。text_count识别出的文本行数。input_type回显请求中的输入类型。request_id该次请求的唯一标识排查问题时需提供。常见错误与处理HTTP 状态码业务 code可能原因处理建议200非 0OCR 识别失败图片模糊、无文字检查图片质量增加预处理灰度化、对比度增强400-参数错误input_type 无效、base64 超 6MB校验参数格式限制 base64 长度401-鉴权失败API Key 无效、匿名超限检查 Key 并重新填充若匿名超限添加 Key 重试429-超出 QPS 2/s 限制退避重试间隔 ≥ 500ms500-服务端内部错误重试若持续失败联系技术支持注意实际错误码可能更丰富建议严格读取code和msg字段进行逻辑判断而非仅依赖 HTTP 状态码。工程化注意事项1. 频率控制与重试策略使用令牌桶或信号量限制客户端并发请求数为 2。对 429 响应采用指数退避首次等待 1s第二次 2s最大 5s。监控平均响应时间若因网络抖动导致实际 QPS 低于 2可适当放宽并发。2. 利用缓存减少重复调用对同一图片 URL 或相同 Base64 数据尽量复用1 小时内相同图片结果会缓存重复请求不消耗配额且响应更快。可在客户端对 Base64 字符串做规范化去除换行和空白以确保缓存命中。3. 图片预处理优化压缩至合理大小建议最长边 2000pxJPEG 质量 80%避免超过 6MB Base64 限制。对于手写体识别保持 300 DPI 分辨率。去除不必要的色彩通道转灰度图可提升识别效率。4. 请求 ID 日志与监控每条响应包含request_id结合本地图片哈希记录日志便于排查识别质量或错误。建立调用量监控看板跟踪每日 QPS 峰值及总调用次数提前调整策略。5. 安全与鉴权API Key 应存储在环境变量或密钥管理服务中禁止硬编码。若需前端直接调用建议通过后端代理转发避免 Key 泄露。定期轮换 Key并监控异常调用行为。参考文档OCR 文字识别 API 文档原始技术规范正文完