Umi-OCR HTTP 二维码接口实战：Base64 识别与文本生成图片的完整调用指南

Umi-OCR HTTP 二维码接口实战：Base64 识别与文本生成图片的完整调用指南

【免费下载链接】Umi-OCROCR software, free and offline. 开源、免费的离线OCR软件。支持截屏/批量导入图片，PDF文档识别，排除水印/页眉页脚，扫描/生成二维码。内置多国语言库。项目地址: https://gitcode.com/GitHub_Trending/um/Umi-OCR

本文基于 Umi-OCR 仓库中 docs/http/api_qrcode.md 的官方接口说明，系统讲解 Umi-OCR 二维码 HTTP 接口的两类能力：将 Base64 图片解析为二维码/条形码文本，以及从文本反向生成二维码图片。读完后，你可以直接在自己的项目（前端脚本、后端服务或自动化流水线）中集成离线二维码识别与生成能力，并从源码层面理解接口背后的 zxingcpp 解析链、图像预处理参数和错误码设计。

一、前置准备：启动 HTTP 服务

Umi-OCR 的二维码接口属于其 HTTP 接口体系的一部分。调用接口前需要满足以下条件：

1. 开启 HTTP 服务：在 Umi-OCR 的全局设置页中勾选“高级”选项后，可以看到 HTTP 服务设置，默认处于开启状态。接口手册见 docs/http/README.md。
2. 确认监听端口：默认端口为1224，可从 UmiOCR-data/py_src/utils/pre_configs.py 中确认默认配置"server_port": 1224。若端口被占用，UmiOCR-data/py_src/server/web_server.py 中的服务逻辑会自动递增端口并记录实际端口，以启动日志中的Listening on http://...为准。
3. 访问地址：本机调用使用http://127.0.0.1:1224；如需被局域网访问，需将主机切换为“任何可用地址”。

从源码结构看，HTTP 服务基于 Bottle 框架构建，并在 UmiOCR-data/py_src/server/web_server.py 中为所有响应添加了Access-Control-Allow-Origin: *等跨域头，因此浏览器前端可以直接fetch调用；同时单次请求体上限被设置为 100 MB（BaseRequest.MEMFILE_MAX），大尺寸图片的 Base64 请求无需担心被截断。

官方手册还给出了三条运行注意事项（见 docs/http/README.md）：

• 关闭 Umi-OCR 时若仍有未断开的 HTTP 连接，可能导致进程关闭不完全，需等待连接释放或强制结束进程；
• 后端组件对并发支持较差，尽量不要并发调用；
• 长时间、大批量、连续调用时小概率出现ECONNREFUSED之类报错，重新发起请求即可。

二、接口总览：一个 URL，两种模式

二维码识别与二维码生成共用同一个 URL/api/qrcode（例：http://127.0.0.1:1224/api/qrcode），均为POST方法、JSON 字典参数。区分两种模式的关键在于请求体中携带的键：

• 请求体含base64键 → 走图片识别二维码分支；
• 请求体含text键 → 走文本生成二维码图片分支。

这一路由分派逻辑可以直接在 UmiOCR-data/py_src/server/qrcode_server.py 中确认：

# 路由函数 def init(UmiWeb): @UmiWeb.route("/api/qrcode", method="POST") def _qrcode(): try: data = request.json except Exception as e: return json.dumps({"code": 800, "data": f"请求无法解析为json。"}) if not data: return json.dumps({"code": 801, "data": f"请求为空。"}) if "base64" in data: return json.dumps(base2text(data)) elif "text" in data: return json.dumps(text2base(data)) return json.dumps({"code": 802, "data": '指令中不存在 "base64" 或 "text"'})

由此得到一组“请求级”错误码，在任何分支之前就会返回：

以下分两节详细讲解两种模式的请求/响应格式与调用示例。

三、模式一：Base64 识别二维码（/api/qrcode）

传入图片的 Base64 编码字符串，返回图中所有二维码/条形码的文本、格式、位置和方向。一张图片中可能包含多个码，接口会逐一返回。

3.1 请求格式

方法：POST，参数为 JSON 字典：

• base64：必填。待识别图像的 Base64 编码字符串，无需data:image/png;base64,等前缀。
• options：可选。参数字典，支持以下图像预处理选项：

参数示例：

{ "base64": "iVBORw0KGgoAAAAN……", "options": { "preprocessing.sharpness_factor": 1.0, "preprocessing.contrast_factor": 1.0, "preprocessing.grayscale": false, "preprocessing.threshold": false } }

3.2 响应格式

返回 JSON，顶层结构与 OCR 结果非常相似：

code==100时，data为列表，记录图片中每个码的结果，每项包含：

支持的码格式format取值：

"Aztec"、"Codabar"、"Code128"、"Code39"、"Code93"、"DataBar"、"DataBarExpanded"、"DataMatrix"、"EAN13"、"EAN8"、"ITF"、"LinearCodes"、"MatrixCodes"、"MaxiCode"、"MicroQRCode"、"PDF417"、"QRCode"、"UPCA"、"UPCE"

识别成功的结果示例：

{ "code": 100, "data": [ { "orientation": 0, "box": [[4,4],[25,4],[25,25],[4,25]], "score": 1, "format": "QRCode", "text": "abc" } ], "time": 0, "timestamp": 1711521012.625574 }

识别失败（含code==101无码、其他错误码）时，data为字符串错误原因，例如：

{"code": 204, "data": "【Error】zxingcpp 二维码解析失败。\n[Error] zxingcpp read_barcodes failed。……"}

3.3 调用示例（JavaScript）

以下示例摘自官方文档，可直接用于浏览器或 Node 环境：

const url = "http://127.0.0.1:1224/api/qrcode"; const base64 = "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/...（此处为完整 Base64，原文见 docs/http/api_qrcode.md）"; const data = { "base64": base64 }; fetch(url, { method: "POST", headers: {"Content-Type": "application/json"}, body: JSON.stringify(data) }) .then(response => response.json()) .then(data => { if(data.code === 100) { console.log("QRCode count:", data.data.length); for (let d of data.data) { console.log(" text: ", d.text); console.log(" format: ", d.format); console.log(" orientation: ", d.orientation); console.log(" ===="); } } else { console.log("Error! Code", data.code, " Msg: ", data.data); } }) .catch(error => console.error(error));

3.4 源码解析：识别链路与错误码

识别二维码的实际执行逻辑位于 UmiOCR-data/py_src/mission/mission_qrcode.py。HTTP 层base2text取出base64与options后，通过MissionQRCode.addMissionWait(opt, [{"base64": base64}])提交任务并同步等待结果，核心处理在msnTask方法中，链路为：读图 → 预处理 → zxingcpp 解析 → 结果转字典，各环节都有独立错误码：

几个值得注意的实现细节（均见 UmiOCR-data/py_src/mission/mission_qrcode.py）：

1. box 坐标顺序：_zxingcpp2dict按top_left → top_right → bottom_right → bottom_left组装四个角，与文档“顺时针四角”的描述一致。
2. 非文本内容的处理：当码的content_type不是Text时（如 GS1、二进制内容），源码会先尝试按 UTF-8 解码bytes；解码失败则在文本前加[Base64]标记并以 Base64 字符串输出。也就是说text字段在极少数情况下可能是“type: Binary+ Base64”的混合内容，调用方需留意。
3. 预处理参数与文档的对应关系：_preprocessing方法（mission_qrcode.py）中，中值滤波使用 PIL 的MedianFilter(size=s)且要求奇数；锐度、对比度使用ImageEnhance；二值化逻辑为灰度值 > threshold → 255，否则 → 0，且仅在grayscale=true时执行——这解释了为什么文档强调threshold只在灰度模式下生效。
4. score 恒为 1：源码中d["score"] = 1有注释“置信度，兼容OCR格式，无意义”，与文档描述吻合。

四、模式二：从文本生成二维码图片（/api/qrcode）

传入文本，根据文本生成二维码图片，返回图片的 Base64 字符串（JPEG 编码）。URL 与识别接口一致，仅请求参数不同。

4.1 请求格式

方法：POST，参数为 JSON 字典：

• text：必填。要写入二维码的文本。
• options：可选。参数字典：

参数示例：

{ "text": "要写入二维码的文本", "options": { "format": "QRCode", "w": 0, "h": 0, "quiet_zone": -1, "ec_level": -1 } }

4.2 响应格式

4.3 调用示例（JavaScript）

const url = "http://127.0.0.1:1224/api/qrcode"; const data = { "text": "test abc 123 !!!", // "options": { // "format": "QRCode", // "w": 0, // "h": 0, // "quiet_zone": -1, // "ec_level": -1, // } }; fetch(url, { method: "POST", headers: {"Content-Type": "application/json"}, body: JSON.stringify(data) }) .then(response => response.json()) .then(data => { if(data.code === 100) { console.log("Image base64: \n", data.data); } else { console.log("Error! Code", data.code, " Msg: ", data.data); } }) .catch(error => console.error(error));

拿到 Base64 后，前端可直接拼成<img src="data:image/jpeg;base64,...">展示，后端则可解码写盘。

4.4 源码解析：生成链路

生成分支的服务端实现为 UmiOCR-data/py_src/server/qrcode_server.py 中的text2base：它从options中取出format（默认QRCode）、w/h（默认0）、quiet_zone（默认-1）、ec_level（默认-1），调用MissionQRCode.createImage得到 PIL 图像，再以JPEG格式写入BytesIO并 Base64 编码返回——这与文档“返回图片编码为 jpeg”的描述一致；异常时返回{"code": 200, "data": "[Error] ..."}。

真正的编码动作在 UmiOCR-data/py_src/mission/mission_qrcode.py 的createImage中：

• 先通过getattr(zxingcpp.BarcodeFormat, format, None)校验格式名是否合法，非法格式直接返回[Error] format {format} not in zxingcpp.BarcodeFormat!；
• 调用zxingcpp.write_barcode(bFormat, text, w, h, quiet_zone, ec_level)生成位图，再经Image.fromarray(bit, "L")转为灰度 PIL 图像；
• 源码注释明确了纠错等级映射：-1自动、1对应 L(7%)、0对应 M(15%)、3对应 Q(25%)、2对应 H(30%)，且纠错等级仅用于Aztec、PDF417和QRCode——与文档表格一致。

五、错误码速查与常见问题

把请求级与分支级错误码汇总如下，方便排障：

实践建议：

1. 先验连通性：浏览器访问http://127.0.0.1:1224/应返回 Umi-OCR 的名称标识（见 web_server.py 的根路由），可用于确认服务已启动。
2. 小图失败时加预处理：对模糊、有噪点的截图，可组合median_filter_size（奇数）+contrast_factor（>1）+ 灰度/二值化重试，参数含义见 3.1 节表格。
3. 避免并发：官方手册明确后端并发支持较差，批量业务请串行调用；偶发ECONNREFUSED时重试即可。
4. 注意score字段：该字段仅用于格式兼容，不要将其当作置信度使用。

六、相关文档与延伸阅读

二维码接口并非孤立存在，Umi-OCR 的 HTTP 接口手册中还包含可组合使用的其他能力：

• HTTP接口手册总览：服务开启、局域网访问与注意事项；
• 图片OCR接口：Base64 图片文字识别，其响应格式（box/score/end）与二维码接口刻意保持兼容；
• 文档识别（PDF）流程：上传 → 轮询 → 下载 → 清理的完整任务流，配套 Python 示例 与 Web 示例；
• 命令行接口：/argv接口等价于命令行传参，仅允许127.0.0.1调用，可参考 README_CLI.md 了解全部命令行参数；
• CHANGE_LOG.md 记录了二维码功能演进：二维码解析库改用 zxingcpp、新增二维码识别页与生成功能、HTTP 二维码接口支持图像预处理参数等，可作为版本能力确认依据。

【免费下载链接】Umi-OCROCR software, free and offline. 开源、免费的离线OCR软件。支持截屏/批量导入图片，PDF文档识别，排除水印/页眉页脚，扫描/生成二维码。内置多国语言库。项目地址: https://gitcode.com/GitHub_Trending/um/Umi-OCR