MinerU Cloud API Toolkit

PDF → Markdown + JSON，基于 MinerU 云端 API 的开箱即用工具包。

功能

• ✅ 远程 URL / 本地文件 → Markdown + JSON + 图片
• ✅ 单文件 & 批量处理
• ✅ SSL/连接错误自动重试（指数退避）
• ✅ 自动禁用系统代理，避免干扰
• ✅ 命令行 + Python import 双模式

---

快速开始

1. 获取 API Key

前往 mineru.net 注册并获取 API Key。

2. 设置环境变量

export MINERU_API_KEY="your_api_key_here"

3. 安装依赖

pip install requests

4. 使用

命令行：

# 解析远程 PDF
python mineru_api.py https://arxiv.org/pdf/2310.06825

# 解析本地 PDF
python mineru_api.py /path/to/paper.pdf

# 指定输出目录
python mineru_api.py paper.pdf --output ./my_output

Python：

from mineru_tool import parse_url, parse_local_file

result = parse_url("https://arxiv.org/pdf/2310.06825", save_dir="./output")
print(result["markdown"][:200])

---

核心流程

MinerU 云端 API 采用 预签名上传 + 异步轮询 模式，共 3 步：

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Step 1      │     │  Step 2      │     │  Step 3      │
│  获取上传 URL │────▶│  PUT 上传文件 │────▶│  轮询 + 下载  │
│  POST batch  │     │  预签名 OSS  │     │  GET results │
└──────────────┘     └──────────────┘     └──────────────┘
      ↓                    ↓                    ↓
  batch_id +           200 OK             state: done
  预签名 URL                              → full_zip_url
                                          → ZIP(md+json+images)

Step 1：申请预签名上传 URL

POST https://mineru.net/api/v4/file-urls/batch
Authorization: Bearer <API_KEY>
Content-Type: application/json

{
  "files": [{
    "name": "paper.pdf",
    "is_ocr": false,
    "data_id": "doc_001",
    "enable_formula": true,
    "enable_table": true,
    "language": "ch"
  }]
}

返回 batch_id + 预签名 OSS 上传 URL。

Step 2：PUT 上传文件到 OSS

PUT <预签名 URL>
Body: <原始 PDF 二进制内容>

⚠️ 不能加任何额外 Header（见踩坑记录）。

Step 3：轮询解析结果

GET https://mineru.net/api/v4/extract-results/batch/{batch_id}
Authorization: Bearer <API_KEY>

状态流转：waiting-file → pending → processing → done

done 时 ZIP 内含：

文件	说明
full.md	Markdown 全文
*_content_list.json	结构化元素索引
images/	提取的图片
layout.json	版面布局信息

---

使用方式

命令行入口：mineru_api.py

最简单的用法，一个命令完成全流程：

# 远程 URL
python mineru_api.py https://arxiv.org/pdf/2310.06825

# 本地文件
python mineru_api.py /path/to/paper.pdf

# 自定义输出目录
python mineru_api.py paper.pdf --output ./my_output

工具库：mineru_tool.py

适合集成到自己的项目中：

from mineru_tool import parse_url, parse_local_file, parse_batch_urls, parse_batch_local

# 单文件（URL）
result = parse_url("https://example.com/paper.pdf", save_dir="./output")

# 单文件（本地）
result = parse_local_file("paper.pdf", save_dir="./output")

# 批量
results = parse_batch_urls(["url1", "url2"], save_dir="./output")
results = parse_batch_local(["a.pdf", "b.pdf"], save_dir="./output")

返回结构：

{
    "task_id": "xxx",
    "state": "success",
    "markdown": "完整 Markdown 文本",
    "json_data": [...],
    "files": {
        "save_dir": "保存路径",
        "markdown_file": ".md 文件路径",
        "json_file": ".json 文件路径",
        "all_files": ["所有文件列表"],
    },
    "raw": {...},
}

高级参数

result = parse_url(
    url="https://example.com/paper.pdf",
    save_dir="./output",
    is_ocr=True,              # 启用 OCR（默认 True）
    enable_formula=True,       # 公式识别（默认 True）
    enable_table=True,         # 表格识别（默认 True）
    extra_formats=["docx"],    # 额外输出 docx/html/latex
    model_version="vlm",       # vlm（高精度）或 pipeline
    timeout=300,               # 最大等待秒数
    poll_interval=5,           # 轮询间隔
)

---

踩坑记录

1. 字段名必须是 files 不是 file_urls

# ❌ 错误
- { "file_urls": [{ "name": "paper.pdf" }] }

# ✅ 正确
+ { "files": [{ "name": "paper.pdf" }] }

每个 file item 必须包含 name 字段，否则 API 返回错误。

2. PUT 到 OSS 不能加 Content-Type Header

预签名 URL 的签名不包含 Content-Type，加了会导致 403 SignatureDoesNotMatch。

# ❌ 会 403
requests.put(upload_url, data=content, headers={"Content-Type": "application/pdf"})

# ✅ 正确 — 不加任何额外 Header
requests.put(upload_url, data=content)

3. 系统代理会干扰 API 请求

如果本机运行了代理软件（Clash / V2Ray 等），requests 可能走代理导致连接失败。必须显式禁用：

session = requests.Session()
session.proxies = {"http": None, "https": None}
session.trust_env = False  # 不读取系统代理环境变量

本工具包的两个脚本均已内置此处理。

4. SSL EOF / 连接超时

Python 高版本（3.12+）与 mineru.net 之间偶发 SSL EOF 错误。mineru_tool.py 已内置指数退避重试（3s → 6s → 12s → 24s），通常重试 1-2 次即可恢复。

5. 文件大小限制

单文件最大 200MB。超过需先分割 PDF。

---

支持格式

输入格式	默认输出	可选额外输出
PDF	Markdown + JSON + 图片	docx, html, latex
DOC/DOCX	Markdown + JSON	docx, html, latex
PPT/PPTX	Markdown + JSON	docx, html, latex
图片	Markdown + JSON	—

---

文件说明

文件	用途
mineru_api.py	命令行入口脚本，支持 URL 和本地文件
mineru_tool.py	Python 工具库，可 import 使用，含批量接口和 SSL 重试
.env.example	环境变量模板

---

FAQ

Q: MinerU 是什么？ A: OpenDataLab 开源的 PDF → 结构化数据转换工具（AGPL-3.0），诞生于 InternLM 大模型预训练过程。

Q: 云端 API 免费吗？ A: 有免费额度，具体见 mineru.net 账户页面。

Q: 转换要多久？ A: 通常 1-2 分钟，最大超时 300 秒（可配置）。

Q: 能不能纯本地跑？ A: 可以。MinerU 支持本地部署（pip install mineru[core]），但需要下载约 20GB 模型文件，且 VLM 模式需要 NVIDIA GPU（8GB+ VRAM）。纯 CPU 可用 pipeline 后端，精度略低。

Q: 和本地部署比有什么优势？ A: 云端 API 使用 VLM 模型（精度 90+），无需 GPU 和大量磁盘空间；本地 pipeline 模式精度 82+，需要 20GB+ 磁盘。

---

License

MIT