Umi-OCR HTTP 图片识别接口指南参数查询与 Base64 识别实战【免费下载链接】Umi-OCROCR software, free and offline. 开源、免费的离线OCR软件。支持截屏/批量导入图片PDF文档识别排除水印/页眉页脚扫描/生成二维码。内置多国语言库。项目地址: https://gitcode.com/GitHub_Trending/um/Umi-OCRUmi-OCR 是一款开源、免费的离线 OCR 软件除图形界面外还内置了基于本地 HTTP 服务的接口层允许外部程序直接调用其识别能力。本文以 HTTP 接口手册中的图片 OCR 文档 为核心完整讲解GET /api/ocr/get_options参数查询接口与POST /api/ocrBase64 识别接口的请求/响应格式、全部可选参数的含义与默认值并结合 HTTP 手册总览 补充服务启用前提、并发限制等工程注意事项帮助读者把 Umi-OCR 稳定集成到自动化脚本与前端应用中。一、启用前提HTTP 服务与默认端口图片识别接口依赖 Umi-OCR 主程序在后台启动的 HTTP 服务。根据 HTTP 接口手册服务默认开启必须在全局设置页中允许 HTTP 服务才能使用 HTTP 接口。默认端口为1224可在 Umi-OCR 全局设置中更改。如果希望被局域网访问需将主机切换到任何可用地址仅本机调用时保持仅本地即可。手册同时列出了三条与调用方直接相关的注意事项退出行为关闭 Umi-OCR 时如果仍有客户端未断开 HTTP 连接可能导致进程关闭不完全UI 线程结束但负责网络的子线程未关闭只能等待所有客户端关闭连接或强制结束进程。调用方应主动及时释放连接。并发能力有限由于后端组件的性能限制对并发支持较差尽量不要并发调用建议串行发起请求。长时批量调用的偶发报错长时间、大批量、连续调用时有小几率出现Error: connect ECONNREFUSED之类的 HTTP 报错。此时重新发起请求即可只要后台工作线程没有崩溃这类问题不会持续影响调用。二、参数查询接口GET /api/ocr/get_options2.1 为什么需要参数查询接口在不同的情况下比如使用不同的 OCR 引擎插件图片识别接口可以传入不同的参数。通过参数查询接口可以获取所有参数的定义、默认值、可选值等信息。文档给出了两种典型用法手动调用查询接口来确认当前引擎支持的参数用查询接口返回的字典自动化生成前端 UI如下拉框、开关、输入框避免前端硬编码参数。URL 与示例URL/api/ocr/get_options例http://127.0.0.1:1224/api/ocr/get_options2.2 请求与响应格式请求方法为GET无参数。响应是一个 json 字符串记录图片 OCR 接口的参数定义。以 PaddleOCR 引擎插件为例返回值格式化后为{ ocr.language: { title: 语言/模型库, optionsList: [ [models/config_chinese.txt,简体中文], [models/config_en.txt,English], [models/config_chinese_cht(v2).txt,繁體中文], [models/config_japan.txt,日本語], [models/config_korean.txt,한국어], [models/config_cyrillic.txt,Русский] ], type: enum, default: models/config_chinese.txt }, ocr.cls: { title: 纠正文本方向, default: false, toolTip: 启用方向分类识别倾斜或倒置的文本。可能降低识别速度。, type: boolean }, ocr.limit_side_len: { title: 限制图像边长, optionsList: [ [960,960 默认], [2880,2880], [4320,4320], [999999,无限制] ], toolTip: 将边长大于该值的图片进行压缩可以提高识别速度。可能降低识别精度。, type: enum, default: 960 }, tbpu.parser: { title: 排版解析方案, toolTip: 按什么方式解析和排序图片中的文字块, default: multi_para, optionsList: [ [multi_para,多栏-按自然段换行], [multi_line,多栏-总是换行], [multi_none,多栏-无换行], [single_para,单栏-按自然段换行], [single_line,单栏-总是换行], [single_none,单栏-无换行], [single_code,单栏-保留缩进], [none,不做处理] ], type: enum }, tbpu.ignoreArea: { title: 忽略区域, toolTip: 数组每一项为[[左上角x,y],[右下角x,y]]。, default: [], type: var }, data.format: { title: 数据返回格式, toolTip: 返回值字典中[\data\] 按什么格式表示OCR结果数据, default: dict, optionsList: [ [dict,含有位置等信息的原始字典], [text,纯文本] ], type: enum } }返回值中每个参数有这些属性title参数名称toolTip参数说明default默认值type参数值的类型具体如下enum枚举。参数值必须为optionsList中某一项的[0]boolean布尔。参数值必须为true/falsetext字符串number数字。如果属性isInttrue那么必须为整数var特殊类型具体见toolTip的说明。所有参数都是可选的任一参数不填时将被设为默认值。这正是识别接口options字段可以部分填写的原因。2.3 参数完整解释对上述参数的完整解释如下原文档全表键默认值类型说明ocr.languagemodels/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.clsfalse布尔可选true/false纠正文本方向填true时启用方向分类识别倾斜或倒置的文本。可能降低识别速度。注意仅适用于 PaddleOCRocr.limit_side_len960枚举可选值为整数960、2880、4320、999999限制图像边长将边长大于该值的图片进行压缩。较低的限制值可以提高识别速度较高的限制可以提高大图的识别精度。注意仅适用于 PaddleOCRtbpu.parsermulti_para枚举可选值为字符串multi_para、multi_line、multi_none、single_para、single_line、single_none、single_code、none排版解析方案按什么方式解析和排序图片中的文字块。各可选值的含义见上方tbpu.parser块的optionsListmulti_*为多栏解析single_*为单栏解析_para按自然段换行、_line总是换行、_none无换行、single_code保留缩进、none不做处理。tbpu.ignoreArea[]嵌套整数列表忽略区域处于任意一个忽略区域内的 OCR 文本块将被舍弃。每个忽略区域用矩形坐标[[左上角x,y],[右下角x,y]]表示详见下节。data.formatdict枚举可选值为字符串dict、text数据返回格式返回值字典中[data]按什么格式表示 OCR 结果数据。dict表示含有位置等信息的详细字典text表示仅返回识别文本。2.4 忽略区域tbpu.ignoreArea的格式与语义假设忽略区域包含 3 个矩形框那么tbpu.ignoreArea的格式类似[ [[0,0],[100,50]], // 第1个框左上角(0,0)右下角(100,50) [[0,60],[200,120]], // 第2个 [[400,0],[500,30]] // 第3个 ]注意过滤粒度是文本块而不是单个字符完全处于忽略区域框内部的整个文本块会被忽略而部分落在框内、大部分在框外的文本块会保留。文档给出的例子中黄色边框的深色矩形是一个忽略区域位于其中的key_mouse文本块会被忽略而pubsub_connector.py、pubsub_service.py这两个文本块得以保留。这一机制正对应 Umi-OCR 界面中“排除水印/页眉页脚”的能力。2.5 组装参数字典基于上面的参数定义可以组装出这样的参数字典后续将作为识别接口请求体中的options{ 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]]] }2.6 参数查询示例代码JavaScriptconst 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); });Pythonimport 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, indent4, ensure_asciiFalse))手动调用确保 Umi-OCR 已在运行浏览器访问http://127.0.0.1:1224/api/ocr/get_options复制全部内容后交给任意 JSON 解析工具或本文示例代码中的json.loads转换为可读文本即可。三、图片 OCR 识别接口POST /api/ocr传入一个 Base64 编码的图片返回 OCR 识别结果。URL/api/ocr例http://127.0.0.1:1224/api/ocr3.1 请求格式方法POST。参数是一个 json 字符串内容为一个字典键值为base64必填。待识别图像的 Base64 编码字符串无需data:image/png;base64,等前缀。options可选。参数字典见 2.3 节的参数表。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 } }3.2 响应格式返回 json 字符串内容为一个字典键值为字段类型描述codeint任务状态码。100为成功101为无文本其余为失败datalist/string识别结果格式见下timedouble识别耗时秒timestampdouble任务开始时间戳秒3.3data字段的三种形态1图片中无文本code101或识别失败code!100 and code!101时[data]为 string内容为错误原因。例{code: 902, data: 向识别器进程传入指令失败疑似子进程已崩溃}2识别成功code100且data.format为dict默认值时[data]为 list每一项元素为 dict包含以下子元素参数名类型描述textstring文本scoredouble置信度 (0~1)boxlist文本框顺时针四个角的 xy 坐标[左上,右上,右下,左下]endstring表示本行文字结尾的结束符根据排版解析得出。可能为空、空格 、换行\n。将所有 OCR 文本块拼接为完整段落时按照本行文字本行结束符下一行文字下一行结束符……的形式就能恢复段落结构。结果示例{ 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: } ] }3识别成功code100且data.format为text时[data]为 string即所有 OCR 结果的拼接例data: 第一行的文本\n第二行的文本从end字段的设计可以看出text模式本质上就是服务端按排版解析方案tbpu.parser对每个文本块计算结束符后依次拼接的结果因此切换tbpu.parser的值text模式的输出段落结构也会随之变化。3.4 返回 JSON 的转义说明易踩坑点原文档特别强调了两点兼容性问题为了确保兼容性返回值 json 字符串经过了转义非英文字符被转换为\uXXXX形式的 Unicode 码点。使用任意编程语言的 json 库将其解析后即可得到可读原文——切勿对响应做逐字符手工拼接。返回值 json 字符串中可能存在转义后的换行符\\n即\n来表达 OCR 段落结构。在某些语言的 HTTP 库中可能会自动将请求结果字符串中的转义换行符转换为真实换行这会导致后续 json 解析失败。如果遇到这种情况可以先获取返回结果字符串将其中所有真实换行\n替换为转义换行\\n确保整个字符串中不存在真实换行再交给 json 解析。3.5 调用示例代码JavaScriptbase64字段替换为你自己的图片编码即可const url http://127.0.0.1:1224/api/ocr; const data { base64: iVBORw0KGgoAAAANSUhEUgAAAC4AAAAXCAIAAAD7ruoFAAAACXBIWXMAABnWAAAZ1gEY0crtAAAAEXRFWHRTb2Z0d2FyZQBTbmlwYXN0ZV0Xzt0AAAHjSURBVEiJ7ZYrcsMwEEBXnR7FLuj0BPIJHJOi0DAZ2qSsMCxEgjYrDQqJdALrBJ2ASndRgeNI8ledutOCLrLl1e7T/mRkjIG/IXe/DWBldRTNEoQSpgNURe5puiiaJehrMuJSXSTgbaby0A1WzLrCCQCmyn0FwoN0V06QONWAt1nUxfnjHYA8p65GjhDKxcjedVH6JOejBPwYh21eE0Wzfe0tqIsEkGXcVcpoMH4CRZP0lsQp/pWJ4ripf1XFDFe8GHSHlYcSo9Es31t60RdFlN1RUmrma5oTzTVB8ZUaeeYEC9GmL6kNkDw9BANAQYo3xTNdqUkvHqrYhDKW0Bj3RSEIpmyWyBaZaMTCrCKtJ5Jsa07fs3E7esE66HzralRLgJKp0/BD6fJRSxvmDsb6joqkcFXGqMVVFFEHDL2gTxwCAaTabnkFUWhDCHTd9iYrGcAL1ZnqIp5Vpiqh7bCfua7FA4qN0INMcN1cgCzjUFxtbmvwdZvGIrI41JiqhZBWhhF8WxorkYPpQwJiWYJeA3rXE4hzcwJB96F9zCFHC0FcVegghvFul7oeEE8PvHeJqC0w0AUbbFIT8JnEwGbPKcS2OxU3HMTqD0r4wgEIuiKJ7i4MS16og8/bPZRPLa6Ld2DSzcAAAAASUVORK5CYII, // 可选参数示例 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); });Pythonimport requests import json url http://127.0.0.1:1224/api/ocr data { base64: iVBORw0KGgoAAAANSUhEUgAAAC4AAAAXCAIAAAD7ruoFAAAACXBIWXMAABnWAAAZ1gEY0crtAAAAEXRFWHRTb2Z0d2FyZQBTbmlwYXN0ZV0Xzt0AAAHjSURBVEiJ7ZYrcsMwEEBXnR7FLuj0BPIJHJOi0DAZ2qSsMCxEgjYrDQqJdALrBJ2ASndRgeNI8ledutOCLrLl1e7T/mRkjIG/IXe/DWBldRTNEoQSpgNURe5puiiaJehrMuJSXSTgbaby0A1WzLrCCQCmyn0FwoN0V06QONWAt1nUxfnjHYA8p65GjhDKxcjedVH6JOejBPwYh21eE0Wzfe0tqIsEkGXcVcpoMH4CRZP0lsQp/pWJ4ripf1XFDFe8GHSHlYcSo9Es31t60RdFlN1RUmrma5oTzTVB8ZUaeeYEC9GmL6kNkDw9BANAQYo3xTNdqUkvHqrYhDKW0Bj3RSEIpmyWyBaZaMTCrCKtJ5Jsa07fs3E7esE66HzralRLgJKp0/BD6fJRSxvmDsb6joqkcFXGqMVVFFEHDL2gTxwCAaTabnkFUWhDCHTd9iYrGcAL1ZnqIp5Vpiqh7bCfua7FA4qN0INMcN1cgCzjUFxtbmvwdZvGIrI41JiqhZBWhhF8WxorkYPpQwJiWYJeA3rXE4hzcwJB96F9zCFHC0FcVegghvFul7oeEE8PvHeJqC0w0AUbbFIT8JnEwGbPKcS2OxU3HMTqD0r4wgEIuiKJ7i4MS16og8/bPZRPLa6Ld2DSzcAAAAASUVORK5CYII, # 可选参数示例 options: { data.format: text, } } headers {Content-Type: application/json} data_str json.dumps(data) response requests.post(url, datadata_str, headersheaders) response.raise_for_status() res_dict json.loads(response.text) print(res_dict)四、与其余 HTTP 接口的关系图片识别只是 Umi-OCR HTTP 接口的一部分手册总览 将全部接口划分为四类读者可按需跳转文档识别PDF 识别文档识别流程 采用“上传 → 轮询状态 → 获取下载链接 → 下载 → 清理”的异步任务五步流程/api/doc/upload、/api/doc/result、/api/doc/download、/api/doc/clear/id及参数查询/api/doc/get_options并支持生成双层可搜索 PDF、txt、csv 等目标文件。官方提供了完整的 Python 演示脚本 api_doc_demo.py 与网页版演示 api_doc_demo.html其中演示脚本还处理了 Linux 下文件名含非 ASCII 字符导致上传失败code101的降级方案。注意文档识别功能自v2.1.4起提供。二维码识别api_qrcode.md 提供/api/qrcode的 Base64 识别含中值滤波、锐度、对比度等预处理参数与从文本生成二维码图片两个能力响应格式与图片 OCR 结果高度相似。命令行接口argv.md 的POST /argv用于命令行参数的跨进程传输只允许本地环回127.0.0.1调用如发送[--screenshot]等价于命令行执行Umi-OCR --screenshot更完整的命令行规则见 命令行手册。从文档组织方式看图片 OCR 接口是同步模型一次请求拿到结果而文档识别是异步任务模型二者共同构成了“轻量图片走同步接口、重文档走任务轮询”的调用策略。五、调用要点小结先查参数再调识别调用前先GET /api/ocr/get_options确认当前引擎插件支持的参数集合与默认值不要跨引擎硬编码参数名ocr.language、ocr.cls、ocr.limit_side_len仅适用于 PaddleOCR 引擎插件。参数全部可选options中未填写的键一律回落到默认值可以只传{data.format: text}这样最小组合。状态码语义code100成功、code101无文本其余为失败且data中携带错误原因code101不是错误属于正常空结果分支应在业务逻辑中单独处理。串行调用受后端组件性能限制避免并发遇到偶发ECONNREFUSED直接重试即可。按 JSON 解析响应响应含\uXXXX转义与转义换行\\n务必整体交给 json 库解析必要时先把真实换行替换回\\n。及时断开连接保持长连接会阻塞 Umi-OCR 正常退出调用结束后应关闭 HTTP 会话。至此/api/ocr/get_options与/api/ocr两个接口的参数、格式、示例与坑点已完整覆盖如需 PDF 识别、二维码或命令行操控可继续参考 docs/http 目录下的配套文档。【免费下载链接】Umi-OCROCR software, free and offline. 开源、免费的离线OCR软件。支持截屏/批量导入图片PDF文档识别排除水印/页眉页脚扫描/生成二维码。内置多国语言库。项目地址: https://gitcode.com/GitHub_Trending/um/Umi-OCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Umi-OCR HTTP 图片识别接口指南：参数查询与 Base64 识别实战
Umi-OCR HTTP 图片识别接口指南参数查询与 Base64 识别实战【免费下载链接】Umi-OCROCR software, free and offline. 开源、免费的离线OCR软件。支持截屏/批量导入图片PDF文档识别排除水印/页眉页脚扫描/生成二维码。内置多国语言库。项目地址: https://gitcode.com/GitHub_Trending/um/Umi-OCRUmi-OCR 是一款开源、免费的离线 OCR 软件除图形界面外还内置了基于本地 HTTP 服务的接口层允许外部程序直接调用其识别能力。本文以 HTTP 接口手册中的图片 OCR 文档 为核心完整讲解GET /api/ocr/get_options参数查询接口与POST /api/ocrBase64 识别接口的请求/响应格式、全部可选参数的含义与默认值并结合 HTTP 手册总览 补充服务启用前提、并发限制等工程注意事项帮助读者把 Umi-OCR 稳定集成到自动化脚本与前端应用中。一、启用前提HTTP 服务与默认端口图片识别接口依赖 Umi-OCR 主程序在后台启动的 HTTP 服务。根据 HTTP 接口手册服务默认开启必须在全局设置页中允许 HTTP 服务才能使用 HTTP 接口。默认端口为1224可在 Umi-OCR 全局设置中更改。如果希望被局域网访问需将主机切换到任何可用地址仅本机调用时保持仅本地即可。手册同时列出了三条与调用方直接相关的注意事项退出行为关闭 Umi-OCR 时如果仍有客户端未断开 HTTP 连接可能导致进程关闭不完全UI 线程结束但负责网络的子线程未关闭只能等待所有客户端关闭连接或强制结束进程。调用方应主动及时释放连接。并发能力有限由于后端组件的性能限制对并发支持较差尽量不要并发调用建议串行发起请求。长时批量调用的偶发报错长时间、大批量、连续调用时有小几率出现Error: connect ECONNREFUSED之类的 HTTP 报错。此时重新发起请求即可只要后台工作线程没有崩溃这类问题不会持续影响调用。二、参数查询接口GET /api/ocr/get_options2.1 为什么需要参数查询接口在不同的情况下比如使用不同的 OCR 引擎插件图片识别接口可以传入不同的参数。通过参数查询接口可以获取所有参数的定义、默认值、可选值等信息。文档给出了两种典型用法手动调用查询接口来确认当前引擎支持的参数用查询接口返回的字典自动化生成前端 UI如下拉框、开关、输入框避免前端硬编码参数。URL 与示例URL/api/ocr/get_options例http://127.0.0.1:1224/api/ocr/get_options2.2 请求与响应格式请求方法为GET无参数。响应是一个 json 字符串记录图片 OCR 接口的参数定义。以 PaddleOCR 引擎插件为例返回值格式化后为{ ocr.language: { title: 语言/模型库, optionsList: [ [models/config_chinese.txt,简体中文], [models/config_en.txt,English], [models/config_chinese_cht(v2).txt,繁體中文], [models/config_japan.txt,日本語], [models/config_korean.txt,한국어], [models/config_cyrillic.txt,Русский] ], type: enum, default: models/config_chinese.txt }, ocr.cls: { title: 纠正文本方向, default: false, toolTip: 启用方向分类识别倾斜或倒置的文本。可能降低识别速度。, type: boolean }, ocr.limit_side_len: { title: 限制图像边长, optionsList: [ [960,960 默认], [2880,2880], [4320,4320], [999999,无限制] ], toolTip: 将边长大于该值的图片进行压缩可以提高识别速度。可能降低识别精度。, type: enum, default: 960 }, tbpu.parser: { title: 排版解析方案, toolTip: 按什么方式解析和排序图片中的文字块, default: multi_para, optionsList: [ [multi_para,多栏-按自然段换行], [multi_line,多栏-总是换行], [multi_none,多栏-无换行], [single_para,单栏-按自然段换行], [single_line,单栏-总是换行], [single_none,单栏-无换行], [single_code,单栏-保留缩进], [none,不做处理] ], type: enum }, tbpu.ignoreArea: { title: 忽略区域, toolTip: 数组每一项为[[左上角x,y],[右下角x,y]]。, default: [], type: var }, data.format: { title: 数据返回格式, toolTip: 返回值字典中[\data\] 按什么格式表示OCR结果数据, default: dict, optionsList: [ [dict,含有位置等信息的原始字典], [text,纯文本] ], type: enum } }返回值中每个参数有这些属性title参数名称toolTip参数说明default默认值type参数值的类型具体如下enum枚举。参数值必须为optionsList中某一项的[0]boolean布尔。参数值必须为true/falsetext字符串number数字。如果属性isInttrue那么必须为整数var特殊类型具体见toolTip的说明。所有参数都是可选的任一参数不填时将被设为默认值。这正是识别接口options字段可以部分填写的原因。2.3 参数完整解释对上述参数的完整解释如下原文档全表键默认值类型说明ocr.languagemodels/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.clsfalse布尔可选true/false纠正文本方向填true时启用方向分类识别倾斜或倒置的文本。可能降低识别速度。注意仅适用于 PaddleOCRocr.limit_side_len960枚举可选值为整数960、2880、4320、999999限制图像边长将边长大于该值的图片进行压缩。较低的限制值可以提高识别速度较高的限制可以提高大图的识别精度。注意仅适用于 PaddleOCRtbpu.parsermulti_para枚举可选值为字符串multi_para、multi_line、multi_none、single_para、single_line、single_none、single_code、none排版解析方案按什么方式解析和排序图片中的文字块。各可选值的含义见上方tbpu.parser块的optionsListmulti_*为多栏解析single_*为单栏解析_para按自然段换行、_line总是换行、_none无换行、single_code保留缩进、none不做处理。tbpu.ignoreArea[]嵌套整数列表忽略区域处于任意一个忽略区域内的 OCR 文本块将被舍弃。每个忽略区域用矩形坐标[[左上角x,y],[右下角x,y]]表示详见下节。data.formatdict枚举可选值为字符串dict、text数据返回格式返回值字典中[data]按什么格式表示 OCR 结果数据。dict表示含有位置等信息的详细字典text表示仅返回识别文本。2.4 忽略区域tbpu.ignoreArea的格式与语义假设忽略区域包含 3 个矩形框那么tbpu.ignoreArea的格式类似[ [[0,0],[100,50]], // 第1个框左上角(0,0)右下角(100,50) [[0,60],[200,120]], // 第2个 [[400,0],[500,30]] // 第3个 ]注意过滤粒度是文本块而不是单个字符完全处于忽略区域框内部的整个文本块会被忽略而部分落在框内、大部分在框外的文本块会保留。文档给出的例子中黄色边框的深色矩形是一个忽略区域位于其中的key_mouse文本块会被忽略而pubsub_connector.py、pubsub_service.py这两个文本块得以保留。这一机制正对应 Umi-OCR 界面中“排除水印/页眉页脚”的能力。2.5 组装参数字典基于上面的参数定义可以组装出这样的参数字典后续将作为识别接口请求体中的options{ 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]]] }2.6 参数查询示例代码JavaScriptconst 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); });Pythonimport 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, indent4, ensure_asciiFalse))手动调用确保 Umi-OCR 已在运行浏览器访问http://127.0.0.1:1224/api/ocr/get_options复制全部内容后交给任意 JSON 解析工具或本文示例代码中的json.loads转换为可读文本即可。三、图片 OCR 识别接口POST /api/ocr传入一个 Base64 编码的图片返回 OCR 识别结果。URL/api/ocr例http://127.0.0.1:1224/api/ocr3.1 请求格式方法POST。参数是一个 json 字符串内容为一个字典键值为base64必填。待识别图像的 Base64 编码字符串无需data:image/png;base64,等前缀。options可选。参数字典见 2.3 节的参数表。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 } }3.2 响应格式返回 json 字符串内容为一个字典键值为字段类型描述codeint任务状态码。100为成功101为无文本其余为失败datalist/string识别结果格式见下timedouble识别耗时秒timestampdouble任务开始时间戳秒3.3data字段的三种形态1图片中无文本code101或识别失败code!100 and code!101时[data]为 string内容为错误原因。例{code: 902, data: 向识别器进程传入指令失败疑似子进程已崩溃}2识别成功code100且data.format为dict默认值时[data]为 list每一项元素为 dict包含以下子元素参数名类型描述textstring文本scoredouble置信度 (0~1)boxlist文本框顺时针四个角的 xy 坐标[左上,右上,右下,左下]endstring表示本行文字结尾的结束符根据排版解析得出。可能为空、空格 、换行\n。将所有 OCR 文本块拼接为完整段落时按照本行文字本行结束符下一行文字下一行结束符……的形式就能恢复段落结构。结果示例{ 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: } ] }3识别成功code100且data.format为text时[data]为 string即所有 OCR 结果的拼接例data: 第一行的文本\n第二行的文本从end字段的设计可以看出text模式本质上就是服务端按排版解析方案tbpu.parser对每个文本块计算结束符后依次拼接的结果因此切换tbpu.parser的值text模式的输出段落结构也会随之变化。3.4 返回 JSON 的转义说明易踩坑点原文档特别强调了两点兼容性问题为了确保兼容性返回值 json 字符串经过了转义非英文字符被转换为\uXXXX形式的 Unicode 码点。使用任意编程语言的 json 库将其解析后即可得到可读原文——切勿对响应做逐字符手工拼接。返回值 json 字符串中可能存在转义后的换行符\\n即\n来表达 OCR 段落结构。在某些语言的 HTTP 库中可能会自动将请求结果字符串中的转义换行符转换为真实换行这会导致后续 json 解析失败。如果遇到这种情况可以先获取返回结果字符串将其中所有真实换行\n替换为转义换行\\n确保整个字符串中不存在真实换行再交给 json 解析。3.5 调用示例代码JavaScriptbase64字段替换为你自己的图片编码即可const url http://127.0.0.1:1224/api/ocr; const data { base64: iVBORw0KGgoAAAANSUhEUgAAAC4AAAAXCAIAAAD7ruoFAAAACXBIWXMAABnWAAAZ1gEY0crtAAAAEXRFWHRTb2Z0d2FyZQBTbmlwYXN0ZV0Xzt0AAAHjSURBVEiJ7ZYrcsMwEEBXnR7FLuj0BPIJHJOi0DAZ2qSsMCxEgjYrDQqJdALrBJ2ASndRgeNI8ledutOCLrLl1e7T/mRkjIG/IXe/DWBldRTNEoQSpgNURe5puiiaJehrMuJSXSTgbaby0A1WzLrCCQCmyn0FwoN0V06QONWAt1nUxfnjHYA8p65GjhDKxcjedVH6JOejBPwYh21eE0Wzfe0tqIsEkGXcVcpoMH4CRZP0lsQp/pWJ4ripf1XFDFe8GHSHlYcSo9Es31t60RdFlN1RUmrma5oTzTVB8ZUaeeYEC9GmL6kNkDw9BANAQYo3xTNdqUkvHqrYhDKW0Bj3RSEIpmyWyBaZaMTCrCKtJ5Jsa07fs3E7esE66HzralRLgJKp0/BD6fJRSxvmDsb6joqkcFXGqMVVFFEHDL2gTxwCAaTabnkFUWhDCHTd9iYrGcAL1ZnqIp5Vpiqh7bCfua7FA4qN0INMcN1cgCzjUFxtbmvwdZvGIrI41JiqhZBWhhF8WxorkYPpQwJiWYJeA3rXE4hzcwJB96F9zCFHC0FcVegghvFul7oeEE8PvHeJqC0w0AUbbFIT8JnEwGbPKcS2OxU3HMTqD0r4wgEIuiKJ7i4MS16og8/bPZRPLa6Ld2DSzcAAAAASUVORK5CYII, // 可选参数示例 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); });Pythonimport requests import json url http://127.0.0.1:1224/api/ocr data { base64: iVBORw0KGgoAAAANSUhEUgAAAC4AAAAXCAIAAAD7ruoFAAAACXBIWXMAABnWAAAZ1gEY0crtAAAAEXRFWHRTb2Z0d2FyZQBTbmlwYXN0ZV0Xzt0AAAHjSURBVEiJ7ZYrcsMwEEBXnR7FLuj0BPIJHJOi0DAZ2qSsMCxEgjYrDQqJdALrBJ2ASndRgeNI8ledutOCLrLl1e7T/mRkjIG/IXe/DWBldRTNEoQSpgNURe5puiiaJehrMuJSXSTgbaby0A1WzLrCCQCmyn0FwoN0V06QONWAt1nUxfnjHYA8p65GjhDKxcjedVH6JOejBPwYh21eE0Wzfe0tqIsEkGXcVcpoMH4CRZP0lsQp/pWJ4ripf1XFDFe8GHSHlYcSo9Es31t60RdFlN1RUmrma5oTzTVB8ZUaeeYEC9GmL6kNkDw9BANAQYo3xTNdqUkvHqrYhDKW0Bj3RSEIpmyWyBaZaMTCrCKtJ5Jsa07fs3E7esE66HzralRLgJKp0/BD6fJRSxvmDsb6joqkcFXGqMVVFFEHDL2gTxwCAaTabnkFUWhDCHTd9iYrGcAL1ZnqIp5Vpiqh7bCfua7FA4qN0INMcN1cgCzjUFxtbmvwdZvGIrI41JiqhZBWhhF8WxorkYPpQwJiWYJeA3rXE4hzcwJB96F9zCFHC0FcVegghvFul7oeEE8PvHeJqC0w0AUbbFIT8JnEwGbPKcS2OxU3HMTqD0r4wgEIuiKJ7i4MS16og8/bPZRPLa6Ld2DSzcAAAAASUVORK5CYII, # 可选参数示例 options: { data.format: text, } } headers {Content-Type: application/json} data_str json.dumps(data) response requests.post(url, datadata_str, headersheaders) response.raise_for_status() res_dict json.loads(response.text) print(res_dict)四、与其余 HTTP 接口的关系图片识别只是 Umi-OCR HTTP 接口的一部分手册总览 将全部接口划分为四类读者可按需跳转文档识别PDF 识别文档识别流程 采用“上传 → 轮询状态 → 获取下载链接 → 下载 → 清理”的异步任务五步流程/api/doc/upload、/api/doc/result、/api/doc/download、/api/doc/clear/id及参数查询/api/doc/get_options并支持生成双层可搜索 PDF、txt、csv 等目标文件。官方提供了完整的 Python 演示脚本 api_doc_demo.py 与网页版演示 api_doc_demo.html其中演示脚本还处理了 Linux 下文件名含非 ASCII 字符导致上传失败code101的降级方案。注意文档识别功能自v2.1.4起提供。二维码识别api_qrcode.md 提供/api/qrcode的 Base64 识别含中值滤波、锐度、对比度等预处理参数与从文本生成二维码图片两个能力响应格式与图片 OCR 结果高度相似。命令行接口argv.md 的POST /argv用于命令行参数的跨进程传输只允许本地环回127.0.0.1调用如发送[--screenshot]等价于命令行执行Umi-OCR --screenshot更完整的命令行规则见 命令行手册。从文档组织方式看图片 OCR 接口是同步模型一次请求拿到结果而文档识别是异步任务模型二者共同构成了“轻量图片走同步接口、重文档走任务轮询”的调用策略。五、调用要点小结先查参数再调识别调用前先GET /api/ocr/get_options确认当前引擎插件支持的参数集合与默认值不要跨引擎硬编码参数名ocr.language、ocr.cls、ocr.limit_side_len仅适用于 PaddleOCR 引擎插件。参数全部可选options中未填写的键一律回落到默认值可以只传{data.format: text}这样最小组合。状态码语义code100成功、code101无文本其余为失败且data中携带错误原因code101不是错误属于正常空结果分支应在业务逻辑中单独处理。串行调用受后端组件性能限制避免并发遇到偶发ECONNREFUSED直接重试即可。按 JSON 解析响应响应含\uXXXX转义与转义换行\\n务必整体交给 json 库解析必要时先把真实换行替换回\\n。及时断开连接保持长连接会阻塞 Umi-OCR 正常退出调用结束后应关闭 HTTP 会话。至此/api/ocr/get_options与/api/ocr两个接口的参数、格式、示例与坑点已完整覆盖如需 PDF 识别、二维码或命令行操控可继续参考 docs/http 目录下的配套文档。【免费下载链接】Umi-OCROCR software, free and offline. 开源、免费的离线OCR软件。支持截屏/批量导入图片PDF文档识别排除水印/页眉页脚扫描/生成二维码。内置多国语言库。项目地址: https://gitcode.com/GitHub_Trending/um/Umi-OCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考