use-mineru-cloud
When (self-trigger)
- A PDF / image / DOCX / PPTX / XLSX file appears and needs reading, summarizing, extracting, or indexing.
- "Convert this PDF to markdown", "parse this document", "extract the text", "make this readable".
- Scanned PDF or image-heavy document needs OCR (109 languages).
- The device is lightweight (phone/tablet) — local heavy parsing is not an option.
- Batch conversion of many documents.
- Academic papers, reports, contracts, slides → markdown for RAG/knowledge base.
What it does
Turns documents into high-quality Markdown using MinerU's cloud compute
(mineru.net). Output includes the markdown file, extracted images, and a
content-list JSON; optionally DOCX/HTML/LaTeX exports. No local model, no
heavy dependencies — only the official SDK (httpx-only) and network.
Auth — secrets policy
- Precision modes read the token from the
MINERU_TOKEN environment variable.
- The skill and its scripts NEVER write, print, or store the token. Do not put
it in files, task descriptions, or configs (this repo is public).
- Flash mode needs no token at all.
mineru-cloud auth verifies a token cheaply without consuming quota.
Usage — convert.py (scripts/convert.py)
Run with any Python ≥ 3.10. Install the SDK once:
python3 -m pip install mineru-open-sdk
| Subcommand |
Purpose |
Token |
auth |
verify token (no quota cost) |
yes |
convert <source> -o <out> |
single file or URL → <out>/<stem>.md + images/ + <stem>_content_list.json |
yes |
batch <s1> <s2> ... -o <out> |
many files/URLs → <out>/<stem>/<stem>.md each (chunked ≤50) |
yes |
flash <source> -o <out> |
no-auth quick mode (≤10MB / ≤20 pages, markdown only) |
no |
crawl <url> -o <out> |
web page → markdown (html model) |
yes |
Common flags: --language en (default en; ch for Chinese), --model vlm|pipeline|html, --ocr, --no-formula, --no-table, --pages 1-20,
--format docx html latex, --timeout N, --stdout (print markdown, save
nothing).
Examples:
export MINERU_TOKEN=...
python3 scripts/convert.py convert paper.pdf -o ./out --language en
python3 scripts/convert.py flash scanned.pdf -o ./out # no token needed
python3 scripts/convert.py batch a.pdf b.pptx c.jpg -o ./out
python3 scripts/convert.py convert paper.pdf --stdout # inline reading
Workflow for the agent
- Classify the input: scanned/image-heavy →
--ocr; formulas → keep
--formula (default on); Chinese → --language ch.
- Choose mode: quick preview or tiny file →
flash; full assets, big
files, or local-file upload → convert.
- Foreign URLs (github, aws, etc.) time out on the MinerU side — for such
files download them locally first, then convert the local path (the script
uploads via presigned URLs automatically).
- Output: read
<out>/<stem>.md; use images/ for figure references;
content_list.json for structured content when needed.
- Batch large sets: the script chunks at 50 files/min (rate limit). Poll
results via
--timeout (default 300s single / 1800s batch).
- Failure:
state=failed prints err_msg. Typed errors (auth, too-large,
page-limit, quota) map to clear messages — fix the input, don't retry blindly.
Boundaries
- Precision: ≤200MB / ≤200 pages per file. Flash: ≤10MB / ≤20 pages.
- Rate limits: 50 files/min submit, 5,000/day (100 HTML), 1,000 req/min polling.
- 1,000 pages/day high-priority quota per account; beyond → slower queue.
- Local parsing (no network, own GPU) is a different skill (
use-mineru-local,
deferred) — do not fake it with this skill.
- The skill is a generic capability: no domain-specific rules (workspace ids,
academic tags, course names) belong here.
References
references/api.md — full verified API contract (endpoints, options,
limits, states, errors, SDK surface, gotchas). Read it when behavior is
unclear or the API seems to have changed.
1---2name: use-mineru-cloud3description: Convert PDFs, images, DOCX, PPTX, and XLSX documents into clean Markdown via the MinerU cloud API (mineru.net) — headers/footers stripped, reading-order text, tables→HTML, formulas→LaTeX, OCR for scanned pages, images extracted alongside. Use when the user hands you a PDF (or document/image) to read, summarize, extract, or feed into a knowledge base; when they say "convert this PDF to markdown", "parse this document", "extract this paper", "make this readable"; when OCR of a scanned PDF is needed; when running on a lightweight device (phone/tablet) where local heavy parsing is impossible; or when batch-converting many documents at once. Two modes: flash (no token, fast, ≤10MB / ≤20 pages) and precision (Bearer token, full assets, ≤200MB / ≤200 pages, local-file upload). Never stores secrets — the token is read from the MINERU_TOKEN environment variable only.4---56# use-mineru-cloud78## When (self-trigger)910- A PDF / image / DOCX / PPTX / XLSX file appears and needs reading, summarizing, extracting, or indexing.11- "Convert this PDF to markdown", "parse this document", "extract the text", "make this readable".12- Scanned PDF or image-heavy document needs OCR (109 languages).13- The device is lightweight (phone/tablet) — local heavy parsing is not an option.14- Batch conversion of many documents.15- Academic papers, reports, contracts, slides → markdown for RAG/knowledge base.1617## What it does1819Turns documents into high-quality Markdown using MinerU's cloud compute20(mineru.net). Output includes the markdown file, extracted images, and a21content-list JSON; optionally DOCX/HTML/LaTeX exports. No local model, no22heavy dependencies — only the official SDK (httpx-only) and network.2324## Auth — secrets policy2526- Precision modes read the token from the **`MINERU_TOKEN` environment variable**.27- The skill and its scripts NEVER write, print, or store the token. Do not put28 it in files, task descriptions, or configs (this repo is public).29- Flash mode needs no token at all.30- `mineru-cloud auth` verifies a token cheaply without consuming quota.3132## Usage — `convert.py` (scripts/convert.py)3334Run with any Python ≥ 3.10. Install the SDK once:35`python3 -m pip install mineru-open-sdk`3637| Subcommand | Purpose | Token |38|---|---|---|39| `auth` | verify token (no quota cost) | yes |40| `convert <source> -o <out>` | single file or URL → `<out>/<stem>.md` + `images/` + `<stem>_content_list.json` | yes |41| `batch <s1> <s2> ... -o <out>` | many files/URLs → `<out>/<stem>/<stem>.md` each (chunked ≤50) | yes |42| `flash <source> -o <out>` | no-auth quick mode (≤10MB / ≤20 pages, markdown only) | no |43| `crawl <url> -o <out>` | web page → markdown (html model) | yes |4445Common flags: `--language en` (default en; `ch` for Chinese), `--model46vlm|pipeline|html`, `--ocr`, `--no-formula`, `--no-table`, `--pages 1-20`,47`--format docx html latex`, `--timeout N`, `--stdout` (print markdown, save48nothing).4950Examples:51```52export MINERU_TOKEN=...53python3 scripts/convert.py convert paper.pdf -o ./out --language en54python3 scripts/convert.py flash scanned.pdf -o ./out # no token needed55python3 scripts/convert.py batch a.pdf b.pptx c.jpg -o ./out56python3 scripts/convert.py convert paper.pdf --stdout # inline reading57```5859## Workflow for the agent60611. **Classify** the input: scanned/image-heavy → `--ocr`; formulas → keep62 `--formula` (default on); Chinese → `--language ch`.632. **Choose mode**: quick preview or tiny file → `flash`; full assets, big64 files, or local-file upload → `convert`.653. **Foreign URLs** (github, aws, etc.) time out on the MinerU side — for such66 files download them locally first, then convert the local path (the script67 uploads via presigned URLs automatically).684. **Output**: read `<out>/<stem>.md`; use `images/` for figure references;69 `content_list.json` for structured content when needed.705. **Batch** large sets: the script chunks at 50 files/min (rate limit). Poll71 results via `--timeout` (default 300s single / 1800s batch).726. **Failure**: `state=failed` prints `err_msg`. Typed errors (auth, too-large,73 page-limit, quota) map to clear messages — fix the input, don't retry blindly.7475## Boundaries7677- Precision: ≤200MB / ≤200 pages per file. Flash: ≤10MB / ≤20 pages.78- Rate limits: 50 files/min submit, 5,000/day (100 HTML), 1,000 req/min polling.79- 1,000 pages/day high-priority quota per account; beyond → slower queue.80- Local parsing (no network, own GPU) is a different skill (`use-mineru-local`,81 deferred) — do not fake it with this skill.82- The skill is a generic capability: no domain-specific rules (workspace ids,83 academic tags, course names) belong here.8485## References8687- `references/api.md` — full verified API contract (endpoints, options,88 limits, states, errors, SDK surface, gotchas). Read it when behavior is89 unclear or the API seems to have changed.
arendon1