适用场景当图片中的文字需要被程序读取在日常开发中经常遇到“把图片里的文字提取出来”的需求。以下三种场景尤其常见截图/图片转文本用户上传的截图如聊天记录、错误堆栈需要转为可搜索或可复制的字符串。印刷文档数字化将合同、发票、名片等拍照后的图片解析出其中的关键字段如发票号、姓名、金额再写入业务系统。视频字幕/字幕机翻抽取视频帧中的硬字幕图片识别后翻译或存档。这些场景的共同点图片是静态的但内容需要被下游程序进一步处理搜索、分析、录入。OCROptical Character RecognitionAPI 正是解决这一类问题的标准化接口。接口能力边界能做什么做不到什么在开始集成之前需要明确该接口的设计范围与约束支持的字符集中文简/繁、英文、数字、常见符号、部分手写体手写体识别准确率低于印刷体建议印刷体为主。输入方式支持两种模式——直接传入图片的公网URL需http/https可访问或传入图片的base64编码字符串最大6MB自动忽略 data:image/...;base64, 前缀。输出结构返回按原始图片顺序排列的逐行文本数组text_list、用换行符拼接的完整文本full_text以及总行数text_count。QPS限制2次/秒超过限制会返回429状态码需自行排队或重试。缓存机制对同一张图片相同URL或相同base64内容的识别结果缓存1小时重复调用不会消耗上游配额响应几乎即时。不为之事不适用于专用发票请使用专用发票识别API、不返回文本坐标如需位置信息需使用其他接口、无法识别超大图片超过6MB的base64或图片尺寸过大时可先压缩再调用。鉴权与请求参数鉴权方式该接口支持两种调用方式匿名调用不传Authorization头每日可调用5次用于开发测试。API Key鉴权在请求头中添加Authorization: Bearer sk_live_xxxxxxxxxxxxxx无调用次数限制受QPS约束。推荐在正式环境使用API Key方式避免测试配额用尽影响业务。请求头部参数参数名必填类型说明Authorization否匿名时省略string格式Bearer sk_live_...Content-Type是string固定值application/x-www-form-urlencoded注意curl示例中使用了json格式实际接口既支持json也支持form-urlencoded文档中示例使用json但Header注明的是form-urlencoded。在实际测试中两种都可为了稳妥curl示例使用jsonHeader也保持application/json。但根据原始文档节选官方curl示例用的是Content-Type: application/json所以我们按json构造注意素材中官方curl示例使用了-H Content-Type: application/json所以本文以下示例也采用json体。若使用form-urlencoded可相应调整。请求体参数JSON格式POST方法字段名必填类型说明input_type是string取值url或base64input_data是string当input_typeurl时为图片的完整http/https URL当input_typebase64时为图片的base64编码字符串最大6MB允许带data:img/png;base64,前缀接入示例用curl快速验证1. 准备条件获取API Key如已有或使用匿名测试。一张可公开访问的图片URL例如https://dummyimage.com/600x200/000/fff.pngtextHelloOCR。使用bash/终端环境执行curl命令。2. URL模式示例推荐用于在线图片# 替换 YOUR_API_KEY 为真实密钥或去掉 -H Authorization 行匿名调用 curl -sS -X POST \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d {input_type:url,input_data:https://dummyimage.com/600x200/000/fff.pngtextHelloWorld} \ https://v1.apizero.cn/api/ocr-text若匿名调用移除-H Authorization: Bearer...行即可。3. base64模式示例适用于本地图片先将图片转换为base64Linux/Mac可用命令# 生成base64去掉换行和数据URI前缀 BASE64$(base64 -w0 local_image.png)然后发起请求curl -sS -X POST \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d {\input_type\:\base64\,\input_data\:\$BASE64\} \ https://v1.apizero.cn/api/ocr-text注意如果base64字符串很大接近6MB需确保终端无大小限制建议在脚本中调用。返回值解读成功响应HTTP 200的JSON结构如下以URL模式为例{ code: 0, msg: 成功, request_id: abc123def456, data: { input_type: url, text_list: [ 商品名称无线蓝牙耳机, 单价¥299.00, 数量2 ], full_text: 商品名称无线蓝牙耳机\n单价¥299.00\n数量2, text_count: 3 } }字段说明字段类型说明codeinteger0 表示成功非0表示错误msgstring描述信息成功时为成功失败时包含错误提示request_idstring唯一请求标识可用于排查问题data.input_typestring回显请求时的输入模式data.text_listarray[string]按图片从上到下的顺序排列的文本行数组data.full_textstring将text_list用换行符\n拼接后的完整文本方便直接存入文本字段data.text_countinteger识别的文本行数可用于判断图片是否包含有效内容失败响应示例{ code: 40004, msg: 图片识别失败图片内容不清晰或无文字, request_id: err456xyz }此时data字段可能不存在或为空对象需根据code和msg处理。常见错误码与排查HTTP状态code含义处理建议2000成功正常解析data20040001参数错误如缺少必填字段检查input_type和input_data是否传递正确20040002图片URL无法访问或格式不支持确认URL公网可达且指向图片文件20040003base64数据过大超过6MB或格式错误压缩图片或检查base64字符串20040004OCR识别失败图片无文字或模糊调整图片质量确保有清晰文字40140101API Key无效或已过期检查Authorization头格式确认密钥状态42942900请求频率超过QPS限制2次/秒增加请求间隔或使用队列限流50050001服务端内部错误等待后重试若持续失败联系技术支持工程化注意事项1. 并发控制与QPS由于QPS仅为2在多线程/微服务场景下需要实现本地限流。推荐使用令牌桶或固定窗口算法确保每秒最多2次请求。超过的请求应当排队或丢弃可返回本地降级结果。2. 缓存利用接口本身已提供1小时缓存但业务层仍建议对同一张图片按URL或图片hash做本地缓存以避免重复调用占用配额。尤其是固定模板的图片如公司内部表单可进一步缩短响应时间。3. Base64前处理当采用base64模式时务必先检查字符串大小。对于大于5MB的图片建议先压缩如调整分辨率、降低质量再编码以避免6MB上限。自动剥离data:image/...;base64,前缀但如从FileReader读取的数据URI可直接传入无需手动去除。4. 超时设置网络请求应设置合理的超时时间建议15秒以上因为图片上传和OCR处理可能需要几秒。避免因临时波动导致连接超时。5. 文本行顺序的依赖text_list按照图片中文字的自然阅读顺序排列通常从上到下从左到右。但若图片有复杂排版多栏顺序可能不完美。如果业务依赖严格的左右顺序建议先用预处理将图片分割为独立区域。6. 错误重试策略对500和429错误可以重试建议使用指数退避如间隔1s, 2s, 4s。对400系列错误不应重试应修正参数。参考文档OCR文字识别API官方文档原始接口文档Markdown