API文档 - Umi-OCR Web Demo

基础说明

本Web Demo通过代理转发的方式调用Umi-OCR的HTTP API服务。

📌 重要说明：

参数配置已本地化：参数选项从本地文件加载，无需Umi-OCR服务运行即可获取参数
配置文件位置：cache/ocr_options.json 和 cache/doc_options.json
首次使用：需要启动Umi-OCR服务一次，参数会自动保存到本地文件
后续使用：可直接使用本地配置文件，无需连接Umi-OCR服务（仅参数获取部分）

Umi-OCR服务地址：

http://127.0.0.1:1224

（仅OCR识别时需要）

Web Demo地址：

http://127.0.0.1:8000

缓存管理 API

刷新参数缓存

GET /api/cache/refresh

从Umi-OCR服务重新获取参数并更新本地缓存文件。

说明：

需要Umi-OCR服务正在运行
会重新获取OCR和文档OCR的参数
自动保存到本地文件

响应示例：

                        {
                        "code": 100,
                        "data": "缓存刷新成功，参数已保存到本地文件"
                        }
                    

图片OCR API

1. 获取OCR参数选项

GET /api/ocr/get_options

获取图片OCR识别的所有可用参数及其定义、默认值、可选值等信息。

💡 优先从本地文件加载，无需Umi-OCR服务运行即可获取参数。

请求示例：

GET /api/ocr/get_options

响应示例：

                        {
                        "ocr.language": {
                        "title": "语言/模型库",
                        "optionsList": [
                        ["简体中文", "简体中文"],
                        ["English", "English"]
                        ],
                        "type": "enum",
                        "default": "简体中文"
                        },
                        "ocr.cls": {
                        "title": "纠正文本方向",
                        "default": false,
                        "type": "boolean"
                        },
                        "tbpu.parser": {
                        "title": "排版解析方案",
                        "default": "multi_para",
                        "optionsList": [
                        ["multi_para", "多栏-按自然段换行"],
                        ["single_para", "单栏-按自然段换行"]
                        ],
                        "type": "enum"
                        }
                        }
                    

2. 图片OCR识别

POST /api/ocr

上传Base64编码的图片进行OCR识别。

⚠️ 需要Umi-OCR服务运行（实际识别功能）

请求体：

                        {
                        "base64": "iVBORw0KGgoAAAANSUhEUgAA...", // Base64编码的图片（不含前缀）
                        "options": { // 可选参数
                        "ocr.language": "简体中文",
                        "ocr.cls": true,
                        "tbpu.parser": "multi_para",
                        "data.format": "text"
                        }
                        }
                    

响应示例：

                        {
                        "code": 100, // 100=成功, 101=无文本, 其他=失败
                        "data": "识别出的文本内容", // 或详细的字典格式
                        "time": 1.234, // 识别耗时（秒）
                        "timestamp": 1234567890.123 // 任务开始时间戳
                        }
                    

JavaScript示例：

                        const response = await fetch('/api/ocr', {
                        method: 'POST',
                        headers: {
                        'Content-Type': 'application/json'
                        },
                        body: JSON.stringify({
                        base64: imageBase64,
                        options: {
                        'data.format': 'text'
                        }
                        })
                        });
                        const result = await response.json();
                    

Python示例：

                        import requests
                        import base64

                        with open('image.png', 'rb') as f:
                        image_base64 = base64.b64encode(f.read()).decode()

                        response = requests.post('http://127.0.0.1:8000/api/ocr', json={
                        'base64': image_base64,
                        'options': {
                        'data.format': 'text'
                        }
                        })
                        result = response.json()
                    

文档OCR API

1. 获取文档OCR参数选项

GET /api/doc/get_options

获取文档OCR识别的所有可用参数及其定义。

💡 优先从本地文件加载，无需Umi-OCR服务运行即可获取参数。

2. 上传文档

POST /api/doc/upload

上传文档文件（PDF等），启动识别任务，返回任务ID。

⚠️ 需要Umi-OCR服务运行（实际识别功能）

请求格式：

使用FormData格式：

file：必填，要上传的文件
json：可选，参数字典的JSON字符串

支持的文件类型：

PDF、XPS、EPUB、MOBI、FB2、CBZ

响应示例：

                        {
                        "code": 100,
                        "data": "cbe2f874-84a9-48b4-a6c0-9157245f7bae" // 任务ID
                        }
                    

JavaScript示例：

                        const formData = new FormData();
                        formData.append('file', fileInput.files[0]);
                        formData.append('json', JSON.stringify({
                        'doc.extractionMode': 'mixed'
                        }));

                        const response = await fetch('/api/doc/upload', {
                        method: 'POST',
                        body: formData
                        });
                        const result = await response.json();
                        const taskId = result.data;
                    

3. 查询任务状态

POST /api/doc/result

通过任务ID查询任务状态和识别结果。

请求体：

                        {
                        "id": "任务ID",
                        "is_data": true, // 是否返回识别结果
                        "format": "text", // 返回格式: "dict" 或 "text"
                        "is_unread": true // 是否只返回未读结果
                        }
                    

响应示例：

                        {
                        "code": 100,
                        "data": "识别结果文本",
                        "processed_count": 5, // 已处理页数
                        "pages_count": 10, // 总页数
                        "is_done": false, // 是否完成
                        "state": "running" // waiting/running/success/failure
                        }
                    

4. 保存识别结果到本地

POST /api/doc/download

将识别结果生成并保存到服务器本地目录（任务完成后调用）。

请求体：

                        {
                        "id": "任务ID",
                        "file_types": ["pdfLayered", "txt"], // 想要保存的文件类型列表
                        "output_dir": "D:/MyResults", // 可选：指定保存目录的绝对路径，如果不传则使用默认 output 目录
                        "ignore_blank": true // 是否忽略空页
                        }
                    

文件类型选项：

pdfLayered：双层可搜索PDF（默认）
pdfOneLayer：单层纯文本PDF
txt：带页数信息的TXT
txtPlain：纯文本TXT
jsonl：JSONL格式
csv：CSV表格

响应示例：

                        {
                        "code": 100,
                        "data": [
                        "E:\\Python_test\\Umi-OCR\\webdemo\\output\\[OCR]_result.layered.pdf",
                        "E:\\Python_test\\Umi-OCR\\webdemo\\output\\[OCR]_result.txt"
                        ],
                        "save_dir": "E:\\Python_test\\Umi-OCR\\webdemo\\output"
                        }
                    

提示：该接口不再返回网络下载链接，返回的是服务器本地的文件绝对路径。

5. 清理任务

GET /api/doc/clear/{task_id}

清理指定任务的内存占用和临时上传文件（不影响已保存到输出目录的结果文件）。

完整流程示例

文档OCR完整流程（Python - 保存到本地）

                    import requests
                    import time
                    import json
                    from pathlib import Path

                    base_url = "http://127.0.0.1:8000"

                    # 1. 上传文档
                    with open('document.pdf', 'rb') as f:
                    files = {'file': f}
                    data = {'json': json.dumps({'doc.extractionMode': 'mixed'})}
                    response = requests.post(f'{base_url}/api/doc/upload', files=files, data=data)
                    result = response.json()
                    task_id = result['data']

                    # 2. 轮询任务状态
                    while True:
                    response = requests.post(f'{base_url}/api/doc/result', json={
                    'id': task_id,
                    'is_data': True,
                    'format': 'text'
                    })
                    result = response.json()
                    print(f"进度: {result['processed_count']}/{result['pages_count']}")

                    if result['is_done']:
                    if result['state'] == 'success':
                    print("识别分析完成！")
                    break
                    else:
                    print(f"任务失败: {result.get('message', '未知错误')}")
                    sys.exit(1)
                    time.sleep(1)

                    # 3. 请求将结果保存到本地文件夹
                    save_response = requests.post(f'{base_url}/api/doc/download', json={
                    'id': task_id,
                    'file_types': ['pdfLayered', 'txt'],
                    'output_dir': 'D:/OCR_Results' # 自定义保存路径
                    })
                    save_result = save_response.json()

                    if save_result['code'] == 100:
                    print(f"文件已成功保存到: {save_result['save_dir']}")
                    for file_path in save_result['data']:
                    print(f" - {file_path}")

                    # 4. 清理任务残留
                    requests.get(f'{base_url}/api/doc/clear/{task_id}')
                

常用参数说明

参数名	类型	默认值	说明
`ocr.language`	enum	简体中文	语言/模型库
`ocr.cls`	boolean	false	纠正文本方向
`ocr.limit_side_len`	enum	960	限制图像边长
`tbpu.parser`	enum	multi_para	排版解析方案
`tbpu.ignoreArea`	var	[]	忽略区域（数组格式）
`data.format`	enum	dict	返回格式：dict 或 text
`doc.extractionMode`	enum	mixed	内容提取模式（文档OCR）
`pageRangeStart`	number	1	OCR页数起始（文档OCR）
`pageRangeEnd`	number	-1	OCR页数结束（文档OCR，-1表示最后一页）

注意事项

参数配置：参数选项已本地化，从 cache/ocr_options.json 和 cache/doc_options.json 加载，无需Umi-OCR服务运行即可获取参数
OCR识别：实际的OCR识别功能仍需要Umi-OCR服务运行（默认端口1224）
文档OCR：文档OCR是异步任务，需要轮询查询状态
任务清理：任务完成后建议及时清理，释放服务器资源
自动清理：任务会在24小时后自动清理
并发限制：Web Demo限制了最大并发请求数为3，以适配Umi-OCR的性能限制
文件大小：文件上传大小限制为100MB
文件类型：文档OCR仅支持 PDF、XPS、EPUB、MOBI、FB2、CBZ 格式