适用场景通用OCR文字识别接口可用于从图片中提取任意文字涵盖中文、英文、数字、符号及手写体。典型场景包括截图转文本将屏幕截图发送给API返回可编辑的文本行。名片/身份证录入识别卡片上的字段并结构化存储。字幕提取从视频帧中提取字幕字符串。笔记OCR将手写笔记拍照后转为电子文本。若需处理专用票据如发票请使用对应专用接口如/api/invoice通用接口对于非标准排版同样有效。接口能力边界在开始编写代码前需要了解该接口的几个关键限制维度说明QPS2次/秒超过会返回限流错误图片输入方式URL公网可访问或 base64最大6MB缓存相同图片内容在1小时内返回缓存结果不重复消耗配额鉴权可选 Authorization头Bearer sk_live_xxx匿名调用每日5次返回值逐行文本列表 完整拼接文本 行数缓存机制对开发调试非常友好重复发送同一图片只会消耗一次上游配额适合批量重试场景。鉴权与请求头身份验证接口支持两种模式匿名调用无需任何鉴权头每日5次调用次数限制适合快速原型验证。认证调用在请求头中添加Authorization: Bearer sk_live_xxxxxxxxxxxxxx获得更高配额。注意事实卡中 curl 示例使用了X-API-Key头但官方最新文档推荐使用Authorization: Bearer格式。以下示例采用标准 Bearer 方案两种方式均可工作请以官方文档为准。Content-Type虽然文档中有时出现application/x-www-form-urlencoded但实际可运行的生产请求多采用 JSON 格式。本示例使用application/json这是业界通用的做法。请求参数详解接口使用 POST 方法请求地址固定为https://v1.apizero.cn/api/ocr-text。请求体是一个 JSON 对象包含两个必填字段input_type类型string必填是可选值url或base64含义指定input_data的格式。url表示传入一张公网可访问的图片链接http/httpsbase64表示传入图片的 base64 编码字符串。input_data类型string必填是当input_typeurl时传入完整的图片 URL例如https://example.com/image.png。当input_typebase64时传入 base64 编码后的字符串最大6MB。支持data:image/jpeg;base64,前缀API 会自动剥离。如果自己拼接建议去除前缀以节省体积。最小可运行示例curl 匿名调用以下是一条无需任何鉴权、可直接运行的 curl 命令使用了一张虚拟测试图片包含文字“Hello World”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执行结果示例{ code: 0, data: { full_text: Hello World, input_type: url, text_count: 1, text_list: [Hello World] }, msg: 成功, request_id: abc123def456 }注意dummyimage.com生成的图片可能包含随机文字实际返回内容可能与示例不同但结构一致。使用认证调用Bearer Token将sk_live_xxxxxxxxxxxxxx替换为真实的密钥curl -sS -X POST \ -H Authorization: Bearer sk_live_xxxxxxxxxxxxxx \ -H Content-Type: application/json \ -d {input_type:url,input_data:https://example.com/screenshot.png} \ https://v1.apizero.cn/api/ocr-textbase64 输入示例假设图片已经转换为 base64 字符串存储为变量IMG_B64直接传入IMG_B64$(base64 -w0 /path/to/image.png) curl -sS -X POST \ -H Content-Type: application/json \ -d {\input_type\:\base64\,\input_data\:\$IMG_B64\} \ https://v1.apizero.cn/api/ocr-text代码接入Python 示例使用requests库适配 python3import requests import json API_URL https://v1.apizero.cn/api/ocr-text def ocr_image(image_url: str, api_key: str ) - dict: 调用 OCR 接口返回 JSON 响应。 :param image_url: 图片公网 URL :param api_key: Bearer token匿名时传空字符串 :return: 响应 dict headers {Content-Type: application/json} if api_key: headers[Authorization] fBearer {api_key} payload { input_type: url, input_data: image_url } resp requests.post(API_URL, headersheaders, jsonpayload) resp.raise_for_status() return resp.json() # 最小示例匿名调用 if __name__ __main__: test_url https://dummyimage.com/400x100/000/fff.pngtextHelloWorld result ocr_image(test_url) print(json.dumps(result, indent2, ensure_asciiFalse))运行后输出结构如前所示。若需处理本地图片可先用 base64 编码import base64 with open(local_image.png, rb) as f: b64_data base64.b64encode(f.read()).decode(utf-8) payload { input_type: base64, input_data: b64_data }响应字段解读成功响应的 JSON 结构如下字段类型说明codeint0 表示成功非 0 表示错误msgstring状态描述信息request_idstring本次请求的唯一标识可用于问题排查data.input_typestring回显请求中的输入类型data.text_listarray[string]按图片原始顺序排列的文本行列表data.full_textstring所有文本行以\n拼接后的完整字符串data.text_countint识别到的文本行数典型错误响应{ code: 1001, msg: 参数错误input_type 只能为 url 或 base64, request_id: req-xxx }常见错误码及含义code含义排查方向1001参数非法检查 input_type、input_data 是否缺失或格式不对1002图片无法访问 / base64解码失败对于 url确认链接可公网下载对于 base64检查原始数据是否完整1003图片过大超过6MB压缩图片或减少 base64 数据长度1004请求频率超限降低请求速度间隔至少 500ms1005认证失败检查 Authorization 头格式或密钥有效性9999内部错误联系技术支持或稍后重试工程化注意事项1. 缓存机制利用同图在1小时内重复调用会直接命中缓存text_list、full_text均相同。因此无需自己缓存结果只需保证短时间内不发送不同图片即可。但对于高频场景建议在应用层也做一次 MD5 去重减少网络开销。2. QPS 控制接口限制 2 次/秒单次请求耗时约 200-800ms。若需批量处理应使用令牌桶或简单的time.sleep(0.5)控制速率。例如import time for url in image_urls: time.sleep(0.6) # 保证低于 2 QPS resp ocr_image(url)3. 图片预处理对于真实场景图片质量直接影响识别率。建议将图片转为 PNG 或 JPEG分辨率不低于 300x100文字清晰、无倾斜。若使用 base64注意去掉data:image/...;base64,前缀API 会自动处理但建议清理以减少传输量。图片体积过大时可先用PIL或opencv缩小尺寸同时控制边长不超过 4096 像素。4. 错误重试策略对于网络超时、服务器错误code9999等可重试的暂时性错误建议重试 2~3 次间隔指数退避1s, 2s, 4s。对于参数错误code1001、认证错误1005不应重试应直接修复请求。5. 安全事项不要在客户端代码中硬编码 API Key。推荐使用环境变量或云密钥管理服务。若使用匿名调用注意每日限额 5 次生产环境必须携带认证。图片中的敏感信息如身份证号、密码请谨慎处理建议在传输前进行脱敏或授权验证。6. 测试技巧使用dummyimage.com生成带文字的测试图片https://dummyimage.com/400x100/000/fff.pngtext测试。注意某些域名可能被墙可换成via.placeholder.com。对于 base64 测试可直接用在线图片转 base64 工具生成或使用 Python 脚本。参考文档官方文档页含完整参数说明https://apizero.cn/aidocs/ocr-text原始 Markdown 文档https://apizero.cn/aidocs/ocr-text/raw.md以上内容覆盖了从认知接口到生产集成的完整链路核心要点是“最小可运行”——只需一条 curl 命令即可获得识别结果。建议读者在真实项目中先使用匿名调用验证图片是否符合预期再切换认证模式进行正式部署。