首页
/ Umi-OCR HTTP 接口完全手册：图片 OCR、PDF 文档识别、二维码与 argv 接口的实战接入指南

Umi-OCR HTTP 接口完全手册：图片 OCR、PDF 文档识别、二维码与 argv 接口的实战接入指南

2026-09-05 11:21:27作者：江焘钦
Umi-OCR
OCR software, free and offline. 开源、免费的离线OCR软件。支持截屏/批量导入图片，PDF文档识别，排除水印/页眉页脚，扫描/生成二维码。内置多国语言库。
项目地址：https://gitcode.com/GitHub_Trending/um/Umi-OCR

Umi-OCR 除了图形界面，还提供了一套完整的 HTTP 接口，让其他程序能够直接把离线 OCR 能力当作"本地服务"来调用。本文基于仓库中的 HTTP 接口手册 及其关联的 图片 OCR 接口文档、文档识别接口文档、二维码接口文档、命令行接口文档 整理而成：先讲清服务开启与主机配置等前置条件，再逐一给出各接口的 URL、请求/响应格式、完整参数表和可直接运行的示例代码，最后覆盖 PDF 五步式识别流程和只允许本机调用的 argv 接口。读完后，你可以独立完成"上传图片 Base64 得到识别文本""上传 PDF 轮询任务并下载双层可搜索 PDF""扫码/生成二维码"等典型集成场景。

Umi-OCR 全局设置页，其中包含 HTTP 服务的开关与主机（仅本地/任何可用地址）选择

适用前提：本文档仅适用于 Umi-OCR 最新版本。旧版本的接口可能不同，请参考对应版本分支中的文档。文档识别（PDF 识别）相关接口需要 v2.1.4 及以上的版本才具备。

一、服务前提：开启 HTTP 服务与主机配置

使用任何 HTTP 接口的前提是软件内已允许 HTTP 服务，具体设置在全局设置页中：

  1. 必须勾选"允许 HTTP 服务"（默认开启）。该选项在勾选高级设置后才显示。
  2. 默认端口为 1224，可以在 Umi-OCR 全局设置中更改。下文所有示例均使用默认端口，例如 http://127.0.0.1:1224。
  3. 如果只需本机调用，主机选择"仅本地"即可；如果需要允许被局域网访问，请将主机切换到任何可用地址。

二、官方注意事项（必读）

HTTP 接口手册 中明确列出了三条注意事项，在集成时应提前知晓：

  1. 关闭软件时可能有残留连接：关闭 Umi-OCR 时，如果仍有用户未断开 HTTP 接口连接，可能导致 Umi-OCR 关闭不完全（UI 线程结束了，但负责网络的子线程未被关闭）。这时只能等待所有用户关闭连接，或者进任务管理器强制结束进程。
  2. 并发支持差：由于后端组件的性能限制，对并发支持较差，尽量不要并发调用。
  3. 长时间大批量调用可能出现瞬时网络报错：由于后端组件的性能限制，在长时间、大批量、连续调用时，有小几率出现 Error: connect ECONNREFUSED 之类的 HTTP 报错。此时重新发起请求即可。只要后台工作线程没有崩，这些小问题不会持续影响调用。

从接口设计上看，这套 HTTP 服务本质是把 GUI 主程序当作服务进程：命令行手册 也说明了 Umi-OCR 依赖 HTTP 接口进行跨进程通信，命令行指令正是通过本地环回传给后台处理进程的。因此做集成时建议按"串行调用 + 失败重试"的模式编写客户端。

三、接口总览

接口 方法 作用
/api/ocr/get_options GET 图片 OCR 参数查询（获取参数定义、默认值、可选值）
/api/ocr POST 图片 OCR：传入 Base64 图片，返回识别结果
/api/doc/get_options GET 文档识别参数查询
/api/doc/upload POST 上传待识别文档（PDF 等），获取任务 ID
/api/doc/result POST 通过任务 ID 轮询任务状态、获取识别文本
/api/doc/download POST 生成目标文件（双层 PDF/txt 等），获取下载链接
下载链接（上一步返回） GET 下载目标文件
/api/doc/clear/<id> GET 清理任务，释放服务器资源
/api/qrcode POST 二维码/条码 Base64 识别；也可用于从文本生成二维码图片
/argv POST 命令行参数跨进程传输（仅限 127.0.0.1）

所有接口均以 http://127.0.0.1:1224（默认端口）为基础地址。

四、图片 OCR 接口

图片识别分为两个接口：先用 参数查询接口 确认当前环境下可用的参数（不同的 OCR 引擎插件支持的参数不同），再调用 Base64 识别接口。

4.1 参数查询：GET /api/ocr/get_options

URL：/api/ocr/get_options，例：http://127.0.0.1:1224/api/ocr/get_options。

返回一个 json 字符串，记录图片 OCR 接口的参数定义。你可以在开发前手动调用它确认信息，也可以通过返回的字典自动化生成前端 UI（每个参数都带 title、toolTip、default、type 等元信息）。

以 PaddleOCR 引擎插件为例，返回值（格式化后）包含以下参数：

键 默认值 类型 说明
ocr.language "models/config_chinese.txt" 枚举，可选值："models/config_chinese.txt"、"models/config_en.txt"、"models/config_chinese_cht(v2).txt"、"models/config_japan.txt"、"models/config_korean.txt"、"models/config_cyrillic.txt" 语言/模型库：加载 ./UmiOCR-data/plugins/PaddleOCR-json/models 目录中的引擎配置文件，可切换不同语言的配置。注意，此参数仅适用于 PaddleOCR 引擎插件！其他 OCR 引擎请自行调用参数查询接口获取。
ocr.cls false 布尔，可选 true/false 纠正文本方向：填 true 时启用方向分类，识别倾斜或倒置的文本。可能降低识别速度。注意，仅适用于 PaddleOCR！
ocr.limit_side_len 960 枚举，可选值为整数：960、2880、4320、999999 限制图像边长：将边长大于该值的图片进行压缩。较低的限制值可以提高识别速度，较高的限制可以提高大图的识别精度。注意，仅适用于 PaddleOCR！
tbpu.parser "multi_para" 枚举，可选值："multi_para"、"multi_line"、"multi_none"、"single_para"、"single_line"、"single_none"、"single_code"、"none" 排版解析方案：按什么方式解析和排序图片中的文字块。可选值含义依次为：多栏-按自然段换行、多栏-总是换行、多栏-无换行、单栏-按自然段换行、单栏-总是换行、单栏-无换行、单栏-保留缩进、不做处理
tbpu.ignoreArea [] 嵌套整数列表 忽略区域：处于任意一个忽略区域内的 OCR 文本块将被舍弃。每个忽略区域用矩形坐标 [[左上角x,y],[右下角x,y]] 表示
data.format "dict" 枚举，可选值：dict、text 数据返回格式：返回值字典中 ["data"] 按什么格式表示 OCR 结果数据。dict 表示含位置等信息的原始字典，text 表示纯文本

返回值中每个参数的属性约定为：

  • title：参数名称；toolTip：参数说明；default：默认值；
  • type：参数值类型 —— enum（枚举，参数值必须为 optionsList 中某一项的 [0]）、boolean（布尔）、text（字符串）、number（数字，若 isInt==true 则必须为整数）、var（特殊类型，具体见 toolTip 说明）。
  • 所有参数都是可选的，任一参数不填时将被设为默认值。

忽略区域 tbpu.ignoreArea 示例：假设忽略区域包含 3 个矩形框，则格式类似：

[
    [[0,0],[100,50]],   // 第1个框，左上角(0,0)，右下角(100,50)
    [[0,60],[200,120]], // 第2个
    [[400,0],[500,30]]  // 第3个
]

注意：完全处于忽略区域框内部的整个文本块（而不是单个字符）会被忽略。

据此可以组装出这样的参数字典，供识别接口使用：

{
    "ocr.language": "models/config_chinese.txt",
    "ocr.cls": true,
    "ocr.limit_side_len": 4320,
    "tbpu.parser": "multi_none",
    "data.format": "text",
    "tbpu.ignoreArea": [[[0,0],[100,50]], [[0,60],[200,120]]]
}

参数查询示例代码（来自 api_ocr.md）：

// JavaScript
const url = "http://127.0.0.1:1224/api/ocr/get_options";
fetch(url, {
        method: "GET",
        headers: { "Content-Type": "application/json" },
    })
    .then(response => response.json())
    .then(data => { console.log(data); })
    .catch(error => { console.error(error); });

# Python
import json, requests

response = requests.get("http://127.0.0.1:1224/api/ocr/get_options")
res_dict = json.loads(response.text)
print(json.dumps(res_dict, indent=4, ensure_ascii=False))

手动验证：确保 Umi-OCR 已在运行，浏览器访问 http://127.0.0.1:1224/api/ocr/get_options，即可看到完整 JSON。

4.2 Base64 识别：POST /api/ocr

传入一个 base64 编码的图片，返回 OCR 识别结果。

URL：/api/ocr，例：http://127.0.0.1:1224/api/ocr。

请求格式：方法 POST，参数为 json 字符串，内容为一个字典：

  • base64：必填。待识别图像的 Base64 编码字符串，无需 data:image/png;base64, 等前缀。
  • options：可选。参数字典，即上一节查询接口定义的参数。

POST 参数示例：

{
    "base64": "iVBORw0KGgoAAAAN……",
    "options": {
        "ocr.language": "models/config_chinese.txt",
        "ocr.cls": true,
        "ocr.limit_side_len": 4320,
        "tbpu.parser": "multi_none",
        "data.format": "text"
    }
}

响应格式：返回 json 字符串，内容为一个字典：

字段 类型 描述
code int 任务状态码。100 为成功，101 为无文本，其余为失败
data list/string 识别结果，格式见下
time double 识别耗时（秒）
timestamp double 任务开始时间戳（秒）

data 的格式：

  • 图片中无文本（code==101），或识别失败（code!=100 and code!=101）时：["data"] 为 string，内容为错误原因。例：{"code": 902, "data": "向识别器进程传入指令失败，疑似子进程已崩溃"}
  • 识别成功（code==100）且 data.format 为 dict（默认值）时，["data"] 为 list，每一项元素为 dict：
参数名 类型 描述
text string 文本
score double 置信度 (0~1)
box list 文本框顺时针四个角的 xy 坐标：[左上,右上,右下,左下]
end string 本行文字结尾的结束符，根据排版解析得出。可能为空、空格、换行 \n。拼接时按"本行文字+本行结束符+下一行文字+下一行结束符+……"的形式即可恢复段落结构

结果示例：

{
    "code": 100,
    "data": [
        {
            "text": "第一行的文本，",
            "score": 0.99800001,
            "box": [[x1,y1], [x2,y2], [x3,y3], [x4,y4]],
            "end": "\n"
        },
        {
            "text": "第二行的文本",
            "score": 0.97513333,
            "box": [[x1,y1], [x2,y2], [x3,y3], [x4,y4]],
            "end": ""
        }
    ]
}
  • 识别成功（code==100）且 data.format 为 text 时，["data"] 为 string，即所有 OCR 结果的拼接。例："data": "第一行的文本，\n第二行的文本"

返回 JSON 的两个兼容性细节（来自 api_ocr.md，实践中很容易踩坑）：

  1. 为了确保兼容性，返回值 json 字符串经过了转义，非英文字符被转换为 \uXXXX 形式的 Unicode 码点。使用任意编程语言的 json 库解析后，即可得到可读原文。
  2. 返回值 json 中可能存在转义后的换行符 \\n（即 \+n）来表达 OCR 段落结构。某些语言的 http 库可能会自动将请求结果字符串中的转义换行符转换为真实换行，导致后续 json 解析失败。如果遇到这种情况，可以先获取返回结果字符串，将其中所有真实换行 \n 替换为转义换行 \\n，确保整个字符串中不存在真实换行，再交给 json 解析。

调用接口示例代码（base64 为一张极小的测试图片）：

import requests
import json

url = "http://127.0.0.1:1224/api/ocr"
data = {
    "base64": "iVBORw0KGgoAAAANSUhEUgAAAC4AAAAXCAIAAAD7ruoFAAAACXBIWXMAABnWAAAZ1gEY0crtAAAAEXRFWHRTb2Z0d2FyZQBTbmlwYXN0ZV0Xzt0AAAHjSURBVEiJ7ZYrcsMwEEBXnR7FLuj0BPIJHJOi0DAZ2qSsMCxEgjYrDQqJdALrBJ2ASndRgeNI8ledutOCLrLl1e7T/mRkjIG/IXe/DWBldRTNEoQSpgNURe5puiiaJehrMuJSXSTgbaby0A1WzLrCCQCmyn0FwoN0V06QONWAt1nUxfnjHYA8p65GjhDKxcjedVH6JOejBPwYh21eE0Wzfe0tqIsEkGXcVcpoMH4CRZ+P0lsQp/pWJ4ripf1XFDFe8GHSHlYcSo9Es31t60RdFlN1RUmrma5oTzTVB8ZUaeeYEC9GmL6kNkDw9BANAQYo3xTNdqUkvHq+rYhDKW0Bj3RSEIpmyWyBaZaMTCrCK+tJ5Jsa07fs3E7esE66HzralRLgJKp0/BD6fJRSxvmDsb6joqkcFXGqMVVFFEHDL2gTxwCAaTabnkFUWhDCHTd9iYrGcAL1ZnqIp5Vpiqh7bCfua7FA4qN0INMcN1+cgCzj+UFxtbmvwdZvGIrI41JiqhZBWhhF8WxorkYPpQwJiWYJeA3rXE4hzcwJ+B96F9zCFHC0FcVegghvFul7oeEE8PvHeJqC0w0AUbbFIT8JnEwGbPKcS2OxU3HMTqD0r4wgEIuiKJ7i4MS16+og8/+bPZRPLa+6Ld2DSzcAAAAASUVORK5CYII=",
    # 可选参数示例
    "options": {
        "data.format": "text",
    }
}
headers = {"Content-Type": "application/json"}
data_str = json.dumps(data)
response = requests.post(url, data=data_str, headers=headers)
response.raise_for_status()
res_dict = json.loads(response.text)
print(res_dict)

JavaScript 端等价实现为：

const url = 'http://127.0.0.1:1224/api/ocr';
const data = {
    base64: "<与上方 Python 示例相同的 base64 字符串>",
    // 可选参数示例
    "options": {
        "data.format": "text",
    }
};

fetch(url, {
        method: "POST", body: JSON.stringify(data),
        headers: {"Content-Type": "application/json"},
    })
    .then(response => response.json())
    .then(data => { console.log(data); })
    .catch(error => { console.error(error); });

五、文档识别（PDF 识别）：五步式任务流程

文档识别是异步任务模型，调用流程如下（详见 api_doc.md）：

  • 准备工作：查询确认参数 → GET /api/doc/get_options
  • 第1步：上传要识别的文件，获取任务 ID → POST /api/doc/upload
  • 第2步：通过 ID 轮询任务状态，直到 OCR 任务结束 → POST /api/doc/result
  • 第3步：生成目标文件（如双层可搜索 PDF），获取下载链接 → POST /api/doc/download
  • 第4步：下载目标文件（GET 下载链接，或直接用浏览器打开）
  • 第5步：清理任务 → GET /api/doc/clear/<id>

仓库提供了完整的可运行参考实现：

5.1 准备工作：GET /api/doc/get_options

返回 文档上传接口 的参数定义，每个参数的属性约定与图片 OCR 查询接口一致（title/toolTip/default/type，类型含 enum、boolean、text、number、var），所有参数均可选。完整参数表：

键 默认值 类型 说明
ocr.language "models/config_chinese.txt" 枚举，可选值同 4.1 节 语言/模型库。注意，此参数仅适用于 PaddleOCR 引擎插件！
ocr.cls false 布尔 纠正文本方向。仅适用于 PaddleOCR！
ocr.limit_side_len 960 枚举整数：960、2880、4320、999999 限制图像边长。仅适用于 PaddleOCR！
tbpu.parser "multi_para" 枚举，可选值同 4.1 节 排版解析方案
tbpu.ignoreArea [] 嵌套整数列表 忽略区域，每个忽略区域用矩形坐标 [[左上角x,y],[右下角x,y]] 表示，示例：[[[0,0],[100,50]], [[10,100],[110,150]]]
tbpu.ignoreRangeStart 1 整数 忽略区域生效的页数范围起始，从 1 开始
tbpu.ignoreRangeEnd -1 整数 忽略区域生效的页数范围结束，可以用负数 -X 表示倒数第 X 页
pageRangeStart 1 整数 OCR 的页数范围起始，从 1 开始
pageRangeEnd -1 整数 OCR 的页数范围结束，可以用负数 -X 表示倒数第 X 页
pageList [] 整数列表 页数列表：例 [1,2,5] 表示仅对第 1、2、5 页进行 OCR。如果与页数范围同时填写，则 pageList 优先
password "" 字符串 若要识别加密的文档，则需填写文档密码
doc.extractionMode "mixed" 枚举，可选值：mixed、fullPage、imageOnly、textOnly 内容提取模式：若一页文档既存在图片又存在文本，如何处理。含义依次为：混合 OCR/原文本、整页强制 OCR、仅 OCR 图片、仅拷贝原有文本

据此可以组装出如下设置字典，将在第 1 步上传时发送给服务器：

{
    "ocr.language": "models/config_chinese.txt",
    "ocr.cls": true,
    "ocr.limit_side_len": 4320,
    "tbpu.parser": "multi_none",
    "tbpu.ignoreArea": [[[0,0],[100,50]], [[10,100],[110,150]], [[200,50],[300,80]]],
    "pageRangeStart": 1,
    "pageRangeEnd": 10,
    "doc.extractionMode": "fullPage"
}

5.2 第1步：POST /api/doc/upload

上传一个文档文件（及配置参数），启动识别任务，返回任务 ID。

请求格式：方法 POST，参数为表单 formData，具有两个键值：

  • file：必填。要上传的文件。
  • json：可选。设置参数字典（json 字符串），详情见 5.1 的参数表。

JavaScript 组装示例：

const fileInput = document.getElementById('file_path').files[0]; // 文件对象
const missionOptions = { // 配置参数字典
    "doc.extractionMode": "mixed",
};
// 必须要将字典转换为json字符串
const missionOptionsJSON = JSON.stringify(missionOptions)
// 组装表单
const formData = new FormData();
formData.append('file', fileInput);
formData.append('json', missionOptionsJSON);

let response = await fetch("http://127.0.0.1:1224/api/doc/upload", {
    method: 'POST',
    body: formData
});

响应格式：返回 json 字典：

  • code：（int）任务状态码。100 为上传成功，其余为失败。
  • data：（string）如果上传成功，则为任务 ID；失败则为失败原因。

一个实战细节（见 api_doc_demo.py）：在部分 Linux 系统上，如果文件名包含非 ASCII 字符，可能出现 code == 101（服务器未收到上传文件）的报错，此时可以用一个纯 ASCII 的临时文件名重新构造上传请求来解决。

5.3 第2步：POST /api/doc/result

传入任务 ID，返回任务的当前执行状态（进行中/已完成）和识别文本。

请求格式：方法 POST，参数为 json 字符串：

  • id：必填，字符串。上传接口成功返回的任务 ID。
  • is_data：布尔值，非必填。true 返回值中包含识别结果；false（默认）只返回简略的任务状态信息。
  • is_unread：布尔值，非必填。true（默认）返回未读过的识别结果条目；false 返回全部条目。
  • format：字符串，非必填。"dict"（默认）以字典形式返回详细识别结果；"text" 以字符串形式返回识别文本。

响应格式：返回 json 字典：

  • code：（int）100 为查询成功，其余为失败。
  • data：（string）查询失败时为失败原因；成功且 is_data=true 时为识别内容；成功且 is_data=false 时为空数组。

以下内容只有 code==100 时才存在：

  • processed_count：（int）已经识别完的页数。
  • pages_count：（int）总页数。
  • is_done：（boolean）true 表示任务已结束（state 可能为 success 或 failure），false 表示任务仍在进行中。
  • state：（string）任务状态：waiting 任务排队中、running 任务进行中、success 任务成功、failure 任务失败。
  • message：（string）只有 state=="failure" 才存在，表示任务失败的原因。注意，就算任务失败，仍可能通过 data 获取已完成的部分任务结果。

轮询写法参考 api_doc_demo.py：每秒请求一次 /api/doc/result，打印 processed_count/pages_count 进度，直到 is_done 为真再断言 state == "success"。

5.4 第3步：POST /api/doc/download

必须在任务成功结束后才能调用，即第 2 步查询得知 is_done==true && state=="success"。传入任务 ID 和目标文件类型，生成目标文件，返回下载链接。

请求格式：方法 POST，参数为 json 字符串：

  • id：必填，字符串。任务 ID。
  • file_types：数组，每一项为字符串。只填写一个值时，返回单个文件的下载链接；填写多个值时，返回单个 zip 压缩包下载链接，其中打包了多个文件。可选值：
    • "pdfLayered"（默认）：双层可搜索 PDF。
    • "pdfOneLayer"：单层纯文本 PDF。
    • "txt"：带页数等信息的 txt 文件。
    • "txtPlain"：只含识别文本的 txt 文件。
    • "jsonl"：与 result 接口 format="dict" 的格式类似，每行为一个 json 对象。
    • "csv"：表格，每行为一页的识别文本。
  • ignore_blank：布尔值，是否忽略空页（没有文字的页数）。true（默认）在 txt、csv 等文件中跳过空页；false 不跳过空页，空页内容记为空字符串。

注：Umi-OCR v2.1.4 及以前的版本该参数存在拼写问题（实际参数名为 ingore_blank），api_doc_demo.py 中对此有专门注释：旧版本请使用错误拼写，最新构建版本请使用 ignore_blank。

响应格式：返回 json 字典：

  • code：（int）100 为成功生成目标文件，其余为无法生成。
  • data：（string）成功时为下载链接，失败时为失败原因。
  • name：（string）只有成功时才存在，下载链接对应的文件名。

5.5 第4步：下载结果文件

第 3 步获取的下载链接，可通过 GET 请求下载，或者直接用浏览器打开。注意：链接中类似 id 的部分不是任务 ID，不能通过任务 ID 拼接出下载链接。

5.6 第5步：GET /api/doc/clear/<id> 任务清理

在 URL 中拼接任务 ID，清理对应的任务。例：http://127.0.0.1:1224/api/doc/clear/cbe2f874-84a9-48b4-a6c0-9157245f7bae。方法 GET。

响应：

  • code：（int）100 为清理成功，其余为清理失败（或者不存在对应任务）。
  • data：（string）原因。

关于清理的说明：

  • 任务清理将删除此任务存放在服务器上的所有临时文件（包括上传的文件）。如果任务进行中时执行清理，将强制终止任务。一个任务被清理后，无法再获取任务状态、访问下载链接。
  • 建议调用者在每次完成任务后手动清理任务，以便及时释放服务器资源。如果不手动清理，任务会在 24 小时后自动清理：任务上传后一直在进行的最长持续运行 24 小时；任务已完成的从完成时起最长保留 24 小时。
  • 如果 Umi-OCR 被意外关闭，那么重新启动时会自动清理上次遗留的所有任务。

六、二维码接口

二维码接口文档见 api_qrcode.md，包含"识别"和"生成"两个方向，二者共用同一个 URL：/api/qrcode（例：http://127.0.0.1:1224/api/qrcode），只是请求参数不同。

6.1 Base64 识别：POST /api/qrcode

请求格式：方法 POST，参数为 json 字典：

  • base64：必填。待识别图像的 Base64 编码字符串，无需 data:image/png;base64, 等前缀。
  • options：可选。参数字典，可选项为：
    • preprocessing.median_filter_size：中值滤波器的大小。取值范围：1~9 的奇数。默认不进行滤波。
    • preprocessing.sharpness_factor：锐度增强因子。取值范围：0.1~10.0。默认不调整锐度。
    • preprocessing.contrast_factor：对比度增强因子。取值范围：0.1~10.0。大于 1 增强对比度，小于 1 但大于 0 减少对比度，1 保持原样。默认不调整对比度。
    • preprocessing.grayscale：是否将图像转换为灰度图像。true 为转换，false 为不转换。默认为 false。
    • preprocessing.threshold：二值化阈值，用于灰度图像的二值化处理。取值范围：0~255 整数。只有当 preprocessing.grayscale=true 时此参数才生效。

参数示例：

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

响应格式：与 OCR 结果的格式非常相似。

字段 类型 描述
code int 任务状态码。100 为成功，101 为无文本，其余为失败
data list 识别结果，格式见下
time double 识别耗时（秒）
timestamp double 任务开始时间戳（秒）

data 格式：

  • 无文本（code==101）或识别失败（code!=100 and code!=101）时：["data"] 为 string，内容为错误原因。例：{"code": 204, "data": "【Error】zxingcpp 二维码解析失败。\n[Error] zxingcpp read_bar……"}
  • 识别成功（code==100）时：["data"] 为 list，记录图片中每个二维码的结果（一张图片可能含多个码）。每项结果的子元素为：
参数名 类型 描述
text string 二维码文本
format string 二维码格式，如 "QRCode" 等，见下
box list 文本框顺时针四个角的 xy 坐标：[左上,右上,右下,左下]
orientation int 二维码方向。0 为正上
score int 为了与 OCR 格式兼容而设，永远为 1，无意义

支持的二维码/条码格式 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
}

调用示例（JavaScript，可遍历多个码）：

const url = "http://127.0.0.1:1224/api/qrcode";
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); });

6.2 从文本生成图片：POST /api/qrcode

传入文本，根据文本生成二维码图片，返回图片 base64。URL 与识别接口一致（/api/qrcode），只是参数不同。

请求格式：方法 POST，参数为 json 字典：

  • text：必填。要写入二维码的文本。
  • options：可选。参数字典，可选项为：
    • format：二维码码格式，可选值见 6.1 节的格式列表，默认为 "QRCode"。
    • w：生成图像宽度，整数。默认 0 为自动设为最小宽度。
    • h：生成图像高度，整数。默认 0 为自动设为最小高度。
    • quiet_zone：二维码四周的空白边缘宽度，整数。默认 -1 为自动调节。
    • ec_level：纠错等级，整数。默认 -1。可选值：-1 自动、1 7%、0 15%、3 25%、2 30%。仅在 Aztec、PDF417、QRCode 格式下生效。

参数示例：

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

响应格式：

字段名 类型 描述
code int 任务状态。100 成功，其余为失败
data string 生成结果。成功时为图片的 base64 字符串（图片编码为 jpeg）；失败时为错误信息字符串

调用示例：

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); });

七、命令行接口：POST /argv

该接口用于命令行参数的跨进程传输，一般由程序内部自动调用，开发者也可手动调用（详见 argv.md）。

URL：/argv，例：http://127.0.0.1:1224/argv。

安全限制：由于此接口较敏感（如允许访问本机图片、关闭软件等），故只允许本地环回 127.0.0.1 调用，局域网或外网无法访问此接口。

请求格式：方法 POST，参数为 json 列表。传入一个列表，列表中记录命令行参数。例如命令行调用 Umi-OCR.exe --path "D:/xxx.png" 等价于向 argv 接口发送 ["--path", "D:/xxx.png"]。具体命令行参数规则请见 README_CLI.md（如 --show 弹出主窗口、--hide 隐藏主窗口、--quit 关闭软件、--screenshot 鼠标截屏、--path 指定路径识别等，获取全部说明可执行 umi-ocr --help）。

调用示例（等价于命令行指令 Umi-OCR --screenshot）：

const url = "http://127.0.0.1:1224/argv";
// 等价于命令行指令 Umi-OCR --screenshot
const data = ["--screenshot"];
fetch(url, {
        method: "POST",
        headers: {"Content-Type": "application/json"},
        body: JSON.stringify(data)
    })
    .then(response => response.text()) // 返回值是字符串
    .then(data => {
        console.log("screenshot text:\n", data)
    })
    .catch(error => {
        console.error(error);
    });

八、集成时的通用要点小结

结合 HTTP 接口手册 与各接口文档，做客户端集成时建议遵循以下要点：

  1. 先查参数再调用：无论图片 OCR 还是文档识别，都应先调用对应的 get_options 接口确认当前 OCR 引擎插件支持的参数、默认值与可选值，避免写死仅适用于 PaddleOCR 的参数（如 ocr.language、ocr.cls、ocr.limit_side_len）。
  2. 状态码语义统一：100 成功；图片/二维码接口中 101 表示"无文本"；文档接口的 result 用 is_done + state（waiting/running/success/failure）表达任务生命周期，且任务失败时仍可通过 data 拿到已完成部分的结果。
  3. 控制调用节奏：后端并发支持差，长时间大批量连续调用可能出现 ECONNREFUSED 之类的瞬时报错，客户端应做重试；PDF 任务用"轮询 result → 成功后 download → 最后 clear"的顺序，不要并发推进多个任务。
  4. 及时清理任务：完成任务后主动调用 /api/doc/clear/<id> 释放临时文件；不手动清理则 24 小时后自动清理，程序异常退出后的遗留任务会在下次启动时自动清理。
  5. JSON 转义细节：响应中的非 ASCII 字符以 \uXXXX 转义，段落换行以 \\n 表达，个别 http 库会把它们变成真实换行导致解析失败，必要时先做一次 \n → \\n 的替换。
  6. 接口安全边界：/argv 仅限 127.0.0.1 访问；若把 OCR 服务暴露到局域网（主机选"任何可用地址"），应自行评估 /api/ocr、/api/doc、/api/qrcode 等只读/文件类接口的网络暴露风险。

各接口的完整字段定义与示例代码，可进一步对照仓库中的 图片 OCR 接口、文档识别接口、二维码接口、命令行接口 以及 Python 示例脚本、Web 示例页面 深入阅读。

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

相关内容推荐

1 Umi-OCR 命令行手册详解：从截屏 OCR、二维码到高级模块调用的完整实战指南2 Umi-OCR 开源离线OCR软件使用指南：界面操作、文本后处理与命令行/HTTP集成3 告别低效文档处理！Umi-OCR内容提取模式全解析4 Umi-OCR HTTP 图片识别接口指南：参数查询与 Base64 识别实战5 Umi-OCR HTTP 二维码接口实战：Base64 识别与文本生成图片的完整调用指南6 Umi-OCR 开源离线 OCR 软件实战指南：从截图/批量识别到命令行与 HTTP 接口调用7 Umi-OCR命令行调用手册：自动化OCR任务的完整指南8 零代码实现本地化部署全功能OCR：从集成到落地的实战指南9 10倍提升效率的Umi-OCR实战指南：从入门到精通的使用技巧与配置优化10 Umi-OCR 实践手册：从零搭建离线 OCR 环境的完整指南
热门项目推荐
相关项目推荐

热门内容推荐

1 编程实践项目探索指南：从零构建技术能力体系2 技术解构式学习：从0到1构建你的编程知识体系3 构建自己的技术世界：build-your-own-x项目的实践探索指南4 解锁编程技能的实践之旅：从零构建你的技术世界5 技术实践探索：从零开始构建核心系统的实践指南6 亲手锻造技术引擎：从0到1构建核心系统的实践指南

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.12 K
2.72 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
528
588
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
906
1.82 K
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
854
1.34 K
docsdocs
暂无描述
Markdown
891
5.78 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.53 K
1.01 K
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
1.34 K
1.45 K
cann-learning-hubcann-learning-hub
CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
987
504
AscendNPU-IRAscendNPU-IR
AscendNPU-IR是基于MLIR（Multi-Level Intermediate Representation）构建的，面向昇腾亲和算子编译时使用的中间表示，提供昇腾完备表达能力，通过编译优化提升昇腾AI处理器计算效率，支持通过生态框架使能昇腾AI处理器与深度调优
C++
540
384