OCR图片转文字API适合把发票、合同、截图和扫描件转换为可检索文本。本文以轻语API的
POST /data/api/ocrRecognize为例，说明从上传图片到落库的完整接入链路。
一、先确定OCR接入方式
轻语OCR接口支持两种输入：用 file 上传本地文件，或用 url 传入图片地址。文件上传适合后台接收用户图片；URL模式适合图片已经存放在对象存储、CDN或业务媒体服务中的系统。两种方式都需要在服务端携带 apikey，不要把正式密钥写进浏览器代码。
| 方式 | 适合场景 | 注意点 |
|---|---|---|
| file | 上传控件、扫描件、移动端拍照 | 校验MIME与大小，使用multipart/form-data |
| url | 已有图片地址、批处理任务 | URL必须可从服务端访问，避免短时过期 |
| 结果 | 全文、逐行文本、坐标、置信度 | 按业务需要保存原图与识别版本 |
二、用文件上传调用OCR接口
最小请求只需要 apikey 和图片文件。前端可以选择文件，但真正的接口调用建议由自己的后端转发，这样既能保护密钥，也能统一做大小和格式校验。
curl -X POST 'https://5555api.com/data/api/ocrRecognize' \
-F 'apikey=YOUR_APIKEY' \
-F 'file=@invoice.jpg'const form = new FormData();
form.append('apikey', process.env.QINGYU_API_KEY);
form.append('file', imageFile);
const response = await fetch('https://5555api.com/data/api/ocrRecognize', {
method: 'POST',
body: form
});
const result = await response.json();
if (result.code !== 200) throw new Error(result.msg || 'OCR识别失败');
console.log(result.data.text);三、读取全文与逐行坐标
只做搜索或复制时使用全文字段即可；票据录入、合同定位和图片高亮则应读取逐行结果。建议保存接口原始响应，同时把业务字段与原图的文件ID关联，方便后续人工复核。
const text = result.data?.text || '';
const lines = result.data?.lines || [];
for (const line of lines) {
const value = line.text || '';
const confidence = Number(line.confidence || 0);
const box = line.boundingBox || line.box;
if (confidence < 0.8) console.warn('低置信度文本:', value, box);
}四、生产环境的四项校验
- 文件校验：只允许业务需要的图片类型，先检查大小和扩展名，再读取真实MIME。
- 可读性校验：图片过暗、倾斜或文字太小会影响识别；在上传前做压缩、旋转和清晰度提示。
- 超时与重试：网络错误可以重试1到2次，参数错误、余额不足和鉴权错误应直接返回。
- 数据安全：原图和OCR文本可能包含个人信息，设置最小保存周期，日志中不要打印图片内容和API Key。
五、适合落地的业务场景
OCR接口常见于发票录入、合同检索、快递面单识别、会议白板转文字和历史档案数字化。对于电子PDF，应优先使用文档解析与OCR实践中的文件类型分流策略；对于图片识别，可直接参考OCR图片识别API文档的字段说明。
六、常见问题
图片URL能直接传本地路径吗？
不能。URL模式要求服务端可以访问的HTTP或HTTPS地址；本地路径需要改用file上传，或先上传到自己的对象存储。
为什么识别结果为空？
常见原因是图片没有文字、文字尺寸过小、图片地址失效或请求字段名错误。先保存原始响应，再从图片可读性、请求参数和鉴权三层排查。
常见问题
OCR图片转文字API支持哪些上传方式？
轻语OCR接口支持multipart/form-data上传file，也支持传入可访问的图片URL。文件方式适合用户上传，URL方式适合已有对象存储或图片地址的系统。
OCR返回结果如何保留版面信息？
接口返回全文以及逐行的文字、置信度和坐标信息。业务侧可以直接展示全文，也可以按坐标绘制高亮框或做字段定位。
OCR识别失败应该怎么处理？
先检查apikey、文件类型、文件大小和图片URL可访问性；对临时网络错误进行有限次数重试，对参数或余额错误直接提示用户，不要无限重试。
结语
一套稳定的OCR图片转文字API接入，不只是发出一次请求，还要处理输入校验、低置信度结果、隐私保护和失败重试。完成后可以在文档解析/OCR在线工具中快速验证样例，再把同样的字段映射到业务系统。