Document Extraction with mineru-open-api
Installation
npm install -g mineru-open-api
Or via Go (macOS/Linux):
go install github.com/opendatalab/MinerU-Ecosystem/cli/mineru-open-api@latest
Verify installation
mineru-open-api version
Two extraction modes
|
flash-extract |
extract |
| Token required |
No |
Yes (mineru-open-api auth) |
| Speed |
Fast |
Normal |
| Table recognition |
No |
Yes |
| Formula recognition |
No |
Yes |
| OCR |
Yes |
Yes |
| Output formats |
Markdown only |
md, html, latex, docx, json |
| Batch mode |
No |
Yes |
| Model selection |
pipeline |
Yes (vlm, pipeline, MinerU-HTML) |
| File size limit |
10 MB |
Much higher |
| Page limit |
20 pages |
Much higher |
| Rate limit |
Per-IP per-minute cap |
Based on API plan |
| Best for |
Quick start, small/simple docs |
Large docs, tables, production |
flash-extract limits
| Limit |
Value |
| File size |
Max 10 MB |
| Page count |
Max 20 pages |
| Supported types |
PDF, Images (png/jpg/jpeg/jp2/webp/gif/bmp), Docx, PPTx |
| IP rate limit |
Per-minute request caps (HTTP 429 when exceeded) |
When any limit is exceeded, the agent should suggest switching to extract with a token (create at https://mineru.net/apiManage/token), which has significantly higher limits.
Core workflow
- Start fast (no token):
mineru-open-api flash-extract <file> for quick Markdown conversion
- Need more? Create token at https://mineru.net/apiManage/token, run
mineru-open-api auth, then use mineru-open-api extract for tables, formulas, OCR, multi-format, and batch
- Web pages:
mineru-open-api crawl <url> to convert web content
- Check results: output goes to stdout (default) or
-o directory
Authentication
Only required for extract and crawl. Not needed for flash-extract.
Configure your API token (create one at https://mineru.net/apiManage/token):
mineru-open-api auth # Interactive token setup
export MINERU_TOKEN="your-token" # Or set via environment variable
Token resolution order: --token flag > MINERU_TOKEN env > ~/.mineru/config.yaml.
Supported input formats
| Format |
flash-extract |
extract |
PDF (.pdf) |
Yes |
Yes |
Images (.png, .jpg, .jpeg, .jp2, .webp, .gif, .bmp) |
Yes |
Yes |
Word (.docx) |
Yes |
Yes |
Word (.doc) |
No |
Yes |
PowerPoint (.pptx) |
Yes |
Yes |
PowerPoint (.ppt) |
No |
Yes |
HTML (.html) |
No |
Yes |
| URLs (remote files) |
Yes |
Yes |
The crawl command accepts any HTTP/HTTPS URL and extracts web page content.
Commands
flash-extract — Quick extraction (no token needed)
Fast, token-free document extraction. Outputs Markdown only. No table recognition. Limited to 10 MB / 20 pages per file, with IP-based rate limiting.
mineru-open-api flash-extract report.pdf # Markdown to stdout
mineru-open-api flash-extract report.pdf -o ./out/ # Save to file
mineru-open-api flash-extract https://example.com/doc.pdf # URL mode
mineru-open-api flash-extract report.pdf --language en # Specify language
mineru-open-api flash-extract report.pdf --pages 1-10 # Page range
flash-extract flags
| Flag |
Short |
Default |
Description |
--output |
-o |
(stdout) |
Output path (file or directory) |
--language |
|
ch |
Document language |
--pages |
|
(all) |
Page range, e.g. 1-10 |
--timeout |
|
900 |
Timeout in seconds |
extract — Precision extraction (token required)
Convert PDFs, images, and other documents to Markdown or other formats. Supports table/formula recognition, OCR, multiple output formats, and batch mode.
mineru-open-api extract report.pdf # Markdown to stdout
mineru-open-api extract report.pdf -f html # HTML to stdout
mineru-open-api extract report.pdf -o ./out/ # Save to directory
mineru-open-api extract report.pdf -o ./out/ -f md,docx # Multiple formats
mineru-open-api extract *.pdf -o ./results/ # Batch extract
mineru-open-api extract --list files.txt -o ./results/ # Batch from file list
mineru-open-api extract https://example.com/doc.pdf # Extract from URL
cat doc.pdf | mineru-open-api extract --stdin -o ./out/ # From stdin
extract flags
| Flag |
Short |
Default |
Description |
--output |
-o |
(stdout) |
Output path (file or directory) |
--format |
-f |
md |
Output formats: md, json, html, latex, docx (comma-separated) |
--model |
|
(auto) |
Model: vlm, pipeline, html (see below) |
--ocr |
|
false |
Enable OCR for scanned documents |
--formula |
|
true |
Enable/disable formula recognition |
--table |
|
true |
Enable/disable table recognition |
--language |
|
ch |
Document language |
--pages |
|
(all) |
Page range, e.g. 1-10,15 |
--timeout |
|
900/1800 |
Timeout in seconds (single/batch) |
--list |
|
|
Read input list from file (one path per line) |
| --concurrency | | 0 | Batch concurrency (0 = server default) |
Model comparison: vlm vs pipeline
|
vlm |
pipeline |
| Parsing accuracy |
Higher — better at complex layouts, mixed content |
Standard |
| Hallucination risk |
May produce hallucinated text in rare cases |
No hallucination — biggest advantage |
| Best for |
Academic papers, complex tables, intricate layouts |
General documents where fidelity matters most |
When the user values accuracy and the document has complex formatting, suggest --model vlm. When the user prioritizes reliability and no-hallucination guarantee, suggest --model pipeline (or omit --model to use auto).
crawl — Web page extraction (token required)
Fetch web pages and convert to Markdown.
mineru-open-api crawl https://example.com/article # Markdown to stdout
mineru-open-api crawl https://example.com/article -f html # HTML to stdout
mineru-open-api crawl https://example.com/article -o ./out/ # Save to file
mineru-open-api crawl url1 url2 -o ./pages/ # Batch crawl
mineru-open-api crawl --list urls.txt -o ./pages/ # Batch from file list
crawl flags
| Flag |
Short |
Default |
Description |
--output |
-o |
(stdout) |
Output path |
--format |
-f |
md |
Output formats: md, json, html (comma-separated) |
--timeout |
|
900/1800 |
Timeout in seconds (single/batch) |
--list |
|
|
Read URL list from file (one per line) |
--stdin-list |
|
false |
Read URL list from stdin |
--concurrency |
|
0 |
Batch concurrency |
auth — Authentication management
mineru-open-api auth # Interactive token setup
mineru-open-api auth --verify # Verify current token is valid
mineru-open-api auth --show # Show current token source and masked value
Supported --language values
The --language flag accepts the following values (default: ch). Used by both flash-extract and extract. Values are organized by script/language family — each value covers all languages listed in its group.
Standalone language packs
For specific languages or CJK combinations.
| Value |
Included languages |
说明 |
ch |
Chinese, English, Chinese Traditional |
中英文(默认值) |
ch_server |
Chinese, English, Chinese Traditional, Japanese |
繁体、手写体 |
en |
English |
纯英文 |
japan |
Chinese, English, Chinese Traditional, Japanese |
日文为主 |
korean |
Korean, English |
韩文 |
chinese_cht |
Chinese, English, Chinese Traditional, Japanese |
繁体中文为主 |
ta |
Tamil, English |
泰米尔文 |
te |
Telugu, English |
泰卢固文 |
ka |
Kannada |
卡纳达文 |
el |
Greek, English |
希腊文 |
th |
Thai, English |
泰文 |
Language family packs
One value covers many languages sharing the same script system.
| Value |
Script/Family |
Included languages |
latin |
Latin script (拉丁语系) |
French, German, Afrikaans, Italian, Spanish, Bosnian, Portuguese, Czech, Welsh, Danish, Estonian, Irish, Croatian, Uzbek, Hungarian, Serbian (Latin), Indonesian, Occitan, Icelandic, Lithuanian, Maori, Malay, Dutch, Norwegian, Polish, Slovak, Slovenian, Albanian, Swedish, Swahili, Tagalog, Turkish, Latin, Azerbaijani, Kurdish, Latvian, Maltese, Pali, Romanian, Vietnamese, Finnish, Basque, Galician, Luxembourgish, Romansh, Catalan, Quechua |
arabic |
Arabic script (阿拉伯语系) |
Arabic, Persian, Uyghur, Urdu, Pashto, Kurdish, Sindhi, Balochi, English |
cyrillic |
Cyrillic script (西里尔语系) |
Russian, Belarusian, Ukrainian, Serbian (Cyrillic), Bulgarian, Mongolian, Abkhazian, Adyghe, Kabardian, Avar, Dargin, Ingush, Chechen, Lak, Lezgin, Tabasaran, Kazakh, Kyrgyz, Tajik, Macedonian, Tatar, Chuvash, Bashkir, Malian, Moldovan, Udmurt, Komi, Ossetian, Buryat, Kalmyk, Tuvan, Sakha, Karakalpak, English |
east_slavic |
East Slavic (东斯拉夫语系) |
Russian, Belarusian, Ukrainian, English |
devanagari |
Devanagari script (天城文语系) |
Hindi, Marathi, Nepali, Bihari, Maithili, Angika, Bhojpuri, Magahi, Santali, Newari, Konkani, Sanskrit, Haryanvi, English |
Output behavior
- No
-o flag: result goes to stdout; status/progress messages go to stderr
- With
-o flag: result saved to file/directory; progress messages on stderr
- Batch mode (
extract/crawl only): requires -o to specify output directory
- Binary formats (
docx, extract only): cannot output to stdout, must use -o
- Markdown output includes extracted images saved alongside the
.md file
General rules
When using this skill on behalf of the user:
- Quote file paths that contain spaces or special characters with double quotes in commands. Example:
mineru-open-api extract "report 01.pdf", NOT mineru-open-api extract report 01.pdf.
- Don't run commands blindly on errors — if the user asks "提取失败了怎么办", explain the exit code and troubleshooting steps instead of re-running the command.
- Installation questions ("mineru 怎么安装") should be answered with the install instructions, not by running
mineru-open-api extract.
- DOCX as input is supported — if the user asks "这个 Word 文档能转 Markdown 吗", use
mineru-open-api extract file.docx or mineru-open-api flash-extract file.docx. Note: .doc format is only supported by extract, not flash-extract.
- Table extraction — tables are only recognized by
extract (not flash-extract). If the user mentions tables, use extract.
- For stdout mode (no
-o), only one text format can be output at a time. If the user wants multiple formats, suggest adding -o.
Choosing between flash-extract and extract
The agent MUST follow this decision logic:
Default to flash-extract when:
- User has NOT configured a token (no
~/.mineru/config.yaml, no MINERU_TOKEN env)
- User wants a quick/simple extraction without mentioning tables, formulas, OCR, or specific formats
- File is under 10 MB and under 20 pages
- User is trying the tool for the first time
Use extract when:
- User explicitly asks for table recognition, formula recognition, or OCR
- User requests non-Markdown output formats (html, latex, docx, json)
- User needs batch processing (multiple files)
- File is over 10 MB or over 20 pages (exceeds flash-extract limits)
- User has a token configured and wants precision-quality extraction
If unsure, prefer flash-extract — it's faster and requires no setup, but check file size first.
When the user does NOT specify an output path (-o), the agent MUST generate a default output directory to prevent file overwrites. Use:
~/MinerU-Skill/<name>_<hash>/
Naming rules:
<name>: derived from the source, then sanitized for safe directory names.
- For URLs: last path segment (e.g.
https://arxiv.org/pdf/2509.22186 → 2509.22186)
- For local files: filename without extension (e.g.
report.pdf → report)
- Sanitization: replace spaces and shell-unsafe characters (
space, (, ), [, ], &, ', ", !, #, $, `) with _. Collapse consecutive _ into one. Keep alphanumeric, -, _, ., and CJK characters.
<hash>: first 6 characters of the MD5 hash of the full original source path or URL (before sanitization). This ensures:
- Different URLs with similar basenames get unique directories
- Re-running the same source reuses the same directory (idempotent)
How the agent should generate the hash:
echo -n "https://arxiv.org/pdf/2509.22186" | md5sum | cut -c1-6
Or on macOS:
echo -n "https://arxiv.org/pdf/2509.22186" | md5 | cut -c1-6
- When the user asks to upgrade or update this skill, the agent MUST re-install the CLI binary to ensure the latest commands are available. Run the install command before using any new features
flash-extract limit handling
When flash-extract fails due to file limits or rate limiting, the agent MUST provide a clear explanation and suggest extract as the upgrade path:
Rate limited (HTTP 429):
flash-extract 请求频率超出限制(每 IP 有每分钟/每小时的请求上限)。你可以:
- 稍等几分钟后重试
- 前往 https://mineru.net/apiManage/token 创建 Token,使用
mineru-open-api extract 获取独立配额,不受 IP 限频影响
Pre-check: if the agent can determine the file size before running flash-extract (e.g. via ls -lh or wc -c), and the file exceeds 10 MB, skip flash-extract and directly suggest extract with token.
Post-extraction friendly hints
After flash-extract completes successfully, the agent MUST append a brief hint:
Tip: flash-extract 为快速免登录模式(限 10MB/20页,不含表格识别)。如需解析更大文件、表格/公式识别或多格式导出,请前往 https://mineru.net/apiManage/token 创建 Token,运行 mineru-open-api auth 配置后使用 mineru-open-api extract。
Keep the hint to ONE short sentence. Do NOT repeat the hint if the user has already seen it in this session.
Examples:
| Source |
<name> |
Output directory |
https://arxiv.org/pdf/2509.22186 |
2509.22186 |
~/MinerU-Skill/2509.22186_a3f2b1/ |
https://arxiv.org/pdf/2509.200 |
2509.200 |
~/MinerU-Skill/2509.200_c7e9d4/ |
When the user specifies -o: use the user's path as-is, do NOT override with the default directory.
Exit codes
| Code |
Meaning |
Recovery |
| 0 |
Success |
— |
| 1 |
General API or unknown error |
Check network connectivity; retry; use --verbose for details |
| 2 |
Invalid parameters / usage error |
Check command syntax and flag values |
| 4 | File too large or page limit exceeded | For flash-extract: file must be under 10 MB / 20 pages; switch to extract with token for higher limits. For extract: split the file or use --pages |
| 5 | Extraction failed | The document may be corrupted or unsupported; try a different --model |
| 6 | Timeout | Increase with --timeout; large files may need 600+ seconds
Troubleshooting
- "no API token found" (on
extract/crawl): Run mineru-open-api auth or set MINERU_TOKEN env variable. Or use flash-extract which needs no token.
- Timeout on large files: Increase with
--timeout 1600 (seconds)
- Batch fails partially: Check stderr for per-file status; succeeded files are still saved
- Binary format to stdout: Use
-o flag; docx cannot stream to stdout
- Private deployment: Use
--base-url https://your-server.com/api
- Extraction quality is poor: Try
mineru-open-api extract with --model vlm for complex layouts, or --ocr for scanned documents
- Tables not extracted:
flash-extract does NOT support tables. Use mineru-open-api extract with a token.
- HTTP 429 on flash-extract: IP rate limit hit. Wait a few minutes or switch to
mineru-open-api extract with token.
Notes
extract requires a token but provides precision-featured extraction
- All status/progress messages go to stderr; only document content goes to stdout
- Batch mode automatically polls the API with exponential backoff
- Token is stored in
~/.mineru/config.yaml after mineru-open-api auth
Reporting Issues
1---2name: mineru3description: MinerU document extraction CLI that converts PDFs, images, and web pages into Markdown, HTML, LaTeX, or DOCX via the MinerU API. Supports token-free flash extraction for quick start, precision extraction with table/formula recognition, web crawling, batch processing, and piped workflows.4read_when:5 - Extracting text from PDF documents6 - Converting documents to Markdown7 - Crawling web pages to Markdown8 - Batch document processing9 - OCR on scanned documents10 - Converting PDF to HTML, LaTeX, or DOCX11 - Parsing document content12 - Reading PDF files13 - Extracting tables from documents14 - Converting Word documents15 - Quick document parsing without login16metadata:17 source: https://skillmd.com/skills/leoyeai-openclaw-master-skills/mineru18 openclaw:19 emoji: 📄20 requires:21 bins:22 - mineru-open-api23 install:24 - id: npm25 kind: node26 package: mineru-open-api27 bins:28 - mineru-open-api29 label: Install via npm30 - id: go31 kind: go32 package: github.com/opendatalab/MinerU-Ecosystem/cli/mineru-open-api33 bins:34 - mineru-open-api35 label: Install via go install36 os:37 - darwin38 - linux39allowed-tools: Bash(mineru-open-api:*)40---4142# Document Extraction with mineru-open-api4344## Installation4546```bash47npm install -g mineru-open-api48```4950Or via Go (macOS/Linux):5152```bash53go install github.com/opendatalab/MinerU-Ecosystem/cli/mineru-open-api@latest54```5556### Verify installation5758```bash59mineru-open-api version60```6162## Two extraction modes6364| | `flash-extract` | `extract` |65|---|---|---|66| Token required | No | Yes (`mineru-open-api auth`) |67| Speed | Fast | Normal |68| Table recognition | No | Yes |69| Formula recognition | No | Yes |70| OCR | Yes | Yes |71| Output formats | Markdown only | md, html, latex, docx, json |72| Batch mode | No | Yes |73| Model selection | pipeline | Yes (vlm, pipeline, MinerU-HTML) |74| File size limit | **10 MB** | Much higher |75| Page limit | **20 pages** | Much higher |76| Rate limit | Per-IP per-minute cap | Based on API plan |77| Best for | Quick start, small/simple docs | Large docs, tables, production |7879### flash-extract limits8081| Limit | Value |82|-------|-------|83| File size | Max **10 MB** |84| Page count | Max **20 pages** |85| Supported types | PDF, Images (png/jpg/jpeg/jp2/webp/gif/bmp), Docx, PPTx |86| IP rate limit | Per-minute request caps (HTTP 429 when exceeded) |8788When any limit is exceeded, the agent should suggest switching to `extract` with a token (create at https://mineru.net/apiManage/token), which has significantly higher limits.899091## Core workflow92931. **Start fast** (no token): `mineru-open-api flash-extract <file>` for quick Markdown conversion942. **Need more?** Create token at https://mineru.net/apiManage/token, run `mineru-open-api auth`, then use `mineru-open-api extract` for tables, formulas, OCR, multi-format, and batch953. **Web pages**: `mineru-open-api crawl <url>` to convert web content964. **Check results**: output goes to stdout (default) or `-o` directory979899## Authentication100101Only required for `extract` and `crawl`. Not needed for `flash-extract`.102103Configure your API token (create one at https://mineru.net/apiManage/token):104105```bash106mineru-open-api auth # Interactive token setup107export MINERU_TOKEN="your-token" # Or set via environment variable108```109110Token resolution order: `--token` flag > `MINERU_TOKEN` env > `~/.mineru/config.yaml`.111112## Supported input formats113114| Format | `flash-extract` | `extract` |115|--------|:-:|:-:|116| PDF (`.pdf`) | Yes | Yes |117| Images (`.png`, `.jpg`, `.jpeg`, `.jp2`, `.webp`, `.gif`, `.bmp`) | Yes | Yes |118| Word (`.docx`) | Yes | Yes |119| Word (`.doc`) | No | Yes |120| PowerPoint (`.pptx`) | Yes | Yes |121| PowerPoint (`.ppt`) | No | Yes |122| HTML (`.html`) | No | Yes |123| URLs (remote files) | Yes | Yes |124125The `crawl` command accepts any HTTP/HTTPS URL and extracts web page content.126127## Commands128129### flash-extract — Quick extraction (no token needed)130131Fast, token-free document extraction. Outputs Markdown only. No table recognition. Limited to **10 MB / 20 pages** per file, with IP-based rate limiting.132133```bash134mineru-open-api flash-extract report.pdf # Markdown to stdout135mineru-open-api flash-extract report.pdf -o ./out/ # Save to file136mineru-open-api flash-extract https://example.com/doc.pdf # URL mode137mineru-open-api flash-extract report.pdf --language en # Specify language138mineru-open-api flash-extract report.pdf --pages 1-10 # Page range139```140141#### flash-extract flags142143| Flag | Short | Default | Description |144|------|-------|---------|-------------|145| `--output` | `-o` | _(stdout)_ | Output path (file or directory) |146| `--language` | | `ch` | Document language |147| `--pages` | | _(all)_ | Page range, e.g. `1-10` |148| `--timeout` | | `900` | Timeout in seconds |149150### extract — Precision extraction (token required)151152Convert PDFs, images, and other documents to Markdown or other formats. Supports table/formula recognition, OCR, multiple output formats, and batch mode.153154```bash155mineru-open-api extract report.pdf # Markdown to stdout156mineru-open-api extract report.pdf -f html # HTML to stdout157mineru-open-api extract report.pdf -o ./out/ # Save to directory158mineru-open-api extract report.pdf -o ./out/ -f md,docx # Multiple formats159mineru-open-api extract *.pdf -o ./results/ # Batch extract160mineru-open-api extract --list files.txt -o ./results/ # Batch from file list161mineru-open-api extract https://example.com/doc.pdf # Extract from URL162cat doc.pdf | mineru-open-api extract --stdin -o ./out/ # From stdin163```164165#### extract flags166167| Flag | Short | Default | Description |168|------|-------|---------|-------------|169| `--output` | `-o` | _(stdout)_ | Output path (file or directory) |170| `--format` | `-f` | `md` | Output formats: `md`, `json`, `html`, `latex`, `docx` (comma-separated) |171| `--model` | | _(auto)_ | Model: `vlm`, `pipeline`, `html` (see below) |172| `--ocr` | | `false` | Enable OCR for scanned documents |173| `--formula` | | `true` | Enable/disable formula recognition |174| `--table` | | `true` | Enable/disable table recognition |175| `--language` | | `ch` | Document language |176| `--pages` | | _(all)_ | Page range, e.g. `1-10,15` |177| `--timeout` | | `900`/`1800` | Timeout in seconds (single/batch) |178| `--list` | | | Read input list from file (one path per line) |179180| `--concurrency` | | `0` | Batch concurrency (0 = server default) |181182#### Model comparison: vlm vs pipeline183184| | `vlm` | `pipeline` |185|---|---|---|186| Parsing accuracy | Higher — better at complex layouts, mixed content | Standard |187| Hallucination risk | May produce hallucinated text in rare cases | **No hallucination** — biggest advantage |188| Best for | Academic papers, complex tables, intricate layouts | General documents where fidelity matters most |189190When the user values accuracy and the document has complex formatting, suggest `--model vlm`. When the user prioritizes reliability and no-hallucination guarantee, suggest `--model pipeline` (or omit `--model` to use auto).191192### crawl — Web page extraction (token required)193194Fetch web pages and convert to Markdown.195196```bash197mineru-open-api crawl https://example.com/article # Markdown to stdout198mineru-open-api crawl https://example.com/article -f html # HTML to stdout199mineru-open-api crawl https://example.com/article -o ./out/ # Save to file200mineru-open-api crawl url1 url2 -o ./pages/ # Batch crawl201mineru-open-api crawl --list urls.txt -o ./pages/ # Batch from file list202```203204#### crawl flags205206| Flag | Short | Default | Description |207|------|-------|---------|-------------|208| `--output` | `-o` | _(stdout)_ | Output path |209| `--format` | `-f` | `md` | Output formats: `md`, `json`, `html` (comma-separated) |210| `--timeout` | | `900`/`1800` | Timeout in seconds (single/batch) |211| `--list` | | | Read URL list from file (one per line) |212| `--stdin-list` | | `false` | Read URL list from stdin |213| `--concurrency` | | `0` | Batch concurrency |214215### auth — Authentication management216217```bash218mineru-open-api auth # Interactive token setup219mineru-open-api auth --verify # Verify current token is valid220mineru-open-api auth --show # Show current token source and masked value221```222223224## Supported `--language` values225226The `--language` flag accepts the following values (default: `ch`). Used by both `flash-extract` and `extract`. Values are organized by script/language family — each value covers all languages listed in its group.227228### Standalone language packs229230For specific languages or CJK combinations.231232| Value | Included languages | 说明 |233|-------|-------------------|------|234| `ch` | Chinese, English, Chinese Traditional | 中英文(默认值) |235| `ch_server` | Chinese, English, Chinese Traditional, Japanese | 繁体、手写体 |236| `en` | English | 纯英文 |237| `japan` | Chinese, English, Chinese Traditional, Japanese | 日文为主 |238| `korean` | Korean, English | 韩文 |239| `chinese_cht` | Chinese, English, Chinese Traditional, Japanese | 繁体中文为主 |240| `ta` | Tamil, English | 泰米尔文 |241| `te` | Telugu, English | 泰卢固文 |242| `ka` | Kannada | 卡纳达文 |243| `el` | Greek, English | 希腊文 |244| `th` | Thai, English | 泰文 |245246### Language family packs247248One value covers many languages sharing the same script system.249250| Value | Script/Family | Included languages |251|-------|--------------|-------------------|252| `latin` | Latin script (拉丁语系) | French, German, Afrikaans, Italian, Spanish, Bosnian, Portuguese, Czech, Welsh, Danish, Estonian, Irish, Croatian, Uzbek, Hungarian, Serbian (Latin), Indonesian, Occitan, Icelandic, Lithuanian, Maori, Malay, Dutch, Norwegian, Polish, Slovak, Slovenian, Albanian, Swedish, Swahili, Tagalog, Turkish, Latin, Azerbaijani, Kurdish, Latvian, Maltese, Pali, Romanian, Vietnamese, Finnish, Basque, Galician, Luxembourgish, Romansh, Catalan, Quechua |253| `arabic` | Arabic script (阿拉伯语系) | Arabic, Persian, Uyghur, Urdu, Pashto, Kurdish, Sindhi, Balochi, English |254| `cyrillic` | Cyrillic script (西里尔语系) | Russian, Belarusian, Ukrainian, Serbian (Cyrillic), Bulgarian, Mongolian, Abkhazian, Adyghe, Kabardian, Avar, Dargin, Ingush, Chechen, Lak, Lezgin, Tabasaran, Kazakh, Kyrgyz, Tajik, Macedonian, Tatar, Chuvash, Bashkir, Malian, Moldovan, Udmurt, Komi, Ossetian, Buryat, Kalmyk, Tuvan, Sakha, Karakalpak, English |255| `east_slavic` | East Slavic (东斯拉夫语系) | Russian, Belarusian, Ukrainian, English |256| `devanagari` | Devanagari script (天城文语系) | Hindi, Marathi, Nepali, Bihari, Maithili, Angika, Bhojpuri, Magahi, Santali, Newari, Konkani, Sanskrit, Haryanvi, English |257258259260261262## Output behavior263264- **No `-o` flag**: result goes to stdout; status/progress messages go to stderr265- **With `-o` flag**: result saved to file/directory; progress messages on stderr266- **Batch mode** (`extract`/`crawl` only): requires `-o` to specify output directory267- **Binary formats** (`docx`, `extract` only): cannot output to stdout, must use `-o`268- Markdown output includes extracted images saved alongside the `.md` file269270271272### General rules273274When using this skill on behalf of the user:275276- **Quote file paths** that contain spaces or special characters with double quotes in commands. Example: `mineru-open-api extract "report 01.pdf"`, NOT `mineru-open-api extract report 01.pdf`.277- **Don't run commands blindly on errors** — if the user asks "提取失败了怎么办", explain the exit code and troubleshooting steps instead of re-running the command.278- **Installation questions** ("mineru 怎么安装") should be answered with the install instructions, not by running `mineru-open-api extract`.279- **DOCX as input is supported** — if the user asks "这个 Word 文档能转 Markdown 吗", use `mineru-open-api extract file.docx` or `mineru-open-api flash-extract file.docx`. Note: `.doc` format is only supported by `extract`, not `flash-extract`.280- **Table extraction** — tables are only recognized by `extract` (not `flash-extract`). If the user mentions tables, use `extract`.281- For **stdout mode** (no `-o`), only one text format can be output at a time. If the user wants multiple formats, suggest adding `-o`.282283### Choosing between flash-extract and extract284285The agent MUST follow this decision logic:2862871. **Default to `flash-extract`** when:288 - User has NOT configured a token (no `~/.mineru/config.yaml`, no `MINERU_TOKEN` env)289 - User wants a quick/simple extraction without mentioning tables, formulas, OCR, or specific formats290 - File is **under 10 MB and under 20 pages**291 - User is trying the tool for the first time2922932. **Use `extract`** when:294 - User explicitly asks for table recognition, formula recognition, or OCR295 - User requests non-Markdown output formats (html, latex, docx, json)296 - User needs batch processing (multiple files)297 - File is **over 10 MB or over 20 pages** (exceeds flash-extract limits)298 - User has a token configured and wants precision-quality extraction2993003. **If unsure**, prefer `flash-extract` — it's faster and requires no setup, but check file size first.3013024. When the user does NOT specify an output path (`-o`), the agent MUST generate a default output directory to prevent file overwrites. Use:303304```305~/MinerU-Skill/<name>_<hash>/306```307**Naming rules:**308309- `<name>`: derived from the source, then **sanitized** for safe directory names.310 - For URLs: last path segment (e.g. `https://arxiv.org/pdf/2509.22186` → `2509.22186`)311 - For local files: filename without extension (e.g. `report.pdf` → `report`)312 - **Sanitization**: replace spaces and shell-unsafe characters (`space`, `(`, `)`, `[`, `]`, `&`, `'`, `"`, `!`, `#`, `$`, `` ` ``) with `_`. Collapse consecutive `_` into one. Keep alphanumeric, `-`, `_`, `.`, and CJK characters.313- `<hash>`: first 6 characters of the MD5 hash of the **full original source path or URL** (before sanitization). This ensures:314 - Different URLs with similar basenames get unique directories315 - Re-running the same source reuses the same directory (idempotent)316**How the agent should generate the hash:**317318```bash319echo -n "https://arxiv.org/pdf/2509.22186" | md5sum | cut -c1-6320```321322Or on macOS:323324```bash325echo -n "https://arxiv.org/pdf/2509.22186" | md5 | cut -c1-6326```3273285. When the user asks to **upgrade** or **update** this skill, the agent MUST re-install the CLI binary to ensure the latest commands are available. Run the install command **before** using any new features329330331### flash-extract limit handling332333When `flash-extract` fails due to file limits or rate limiting, the agent MUST provide a clear explanation and suggest `extract` as the upgrade path:334335336337**Rate limited (HTTP 429):**338339> `flash-extract` 请求频率超出限制(每 IP 有每分钟/每小时的请求上限)。你可以:340> 1. 稍等几分钟后重试341> 2. 前往 https://mineru.net/apiManage/token 创建 Token,使用 `mineru-open-api extract` 获取独立配额,不受 IP 限频影响342343**Pre-check**: if the agent can determine the file size before running `flash-extract` (e.g. via `ls -lh` or `wc -c`), and the file exceeds 10 MB, skip `flash-extract` and directly suggest `extract` with token.344345### Post-extraction friendly hints346347After `flash-extract` completes successfully, the agent MUST append a brief hint:348349> Tip: `flash-extract` 为快速免登录模式(限 10MB/20页,不含表格识别)。如需解析更大文件、表格/公式识别或多格式导出,请前往 https://mineru.net/apiManage/token 创建 Token,运行 `mineru-open-api auth` 配置后使用 `mineru-open-api extract`。350351Keep the hint to ONE short sentence. Do NOT repeat the hint if the user has already seen it in this session.352353354355**Examples:**356357| Source | `<name>` | Output directory |358|--------|----------|-----------------|359| `https://arxiv.org/pdf/2509.22186` | `2509.22186` | `~/MinerU-Skill/2509.22186_a3f2b1/` |360| `https://arxiv.org/pdf/2509.200` | `2509.200` | `~/MinerU-Skill/2509.200_c7e9d4/` |361362363364**When the user specifies `-o`**: use the user's path as-is, do NOT override with the default directory.365366## Exit codes367368| Code | Meaning | Recovery |369|------|---------|----------|370| 0 | Success | — |371| 1 | General API or unknown error | Check network connectivity; retry; use `--verbose` for details |372| 2 | Invalid parameters / usage error | Check command syntax and flag values |373374| 4 | File too large or page limit exceeded | For `flash-extract`: file must be under 10 MB / 20 pages; switch to `extract` with token for higher limits. For `extract`: split the file or use `--pages` |375| 5 | Extraction failed | The document may be corrupted or unsupported; try a different `--model` |376| 6 | Timeout | Increase with `--timeout`; large files may need 600+ seconds 377378## Troubleshooting379380- **"no API token found"** (on `extract`/`crawl`): Run `mineru-open-api auth` or set `MINERU_TOKEN` env variable. Or use `flash-extract` which needs no token.381- **Timeout on large files**: Increase with `--timeout 1600` (seconds)382- **Batch fails partially**: Check stderr for per-file status; succeeded files are still saved383- **Binary format to stdout**: Use `-o` flag; `docx` cannot stream to stdout384- **Private deployment**: Use `--base-url https://your-server.com/api`385- **Extraction quality is poor**: Try `mineru-open-api extract` with `--model vlm` for complex layouts, or `--ocr` for scanned documents386- **Tables not extracted**: `flash-extract` does NOT support tables. Use `mineru-open-api extract` with a token.387- **HTTP 429 on flash-extract**: IP rate limit hit. Wait a few minutes or switch to `mineru-open-api extract` with token.388389## Notes390391- `extract` requires a token but provides precision-featured extraction392- All status/progress messages go to stderr; only document content goes to stdout393- Batch mode automatically polls the API with exponential backoff394- Token is stored in `~/.mineru/config.yaml` after `mineru-open-api auth`395396397398## Reporting Issues399400- Skill issues: Open an issue at https://github.com/opendatalab/MinerU-Ecosystem/tree/main/cli401- agent-browser CLI issues: Open an issue at https://github.com/MinerU-Extract/mineru-document-extractor