AI Document Parsing with MinerU

Intelligent document extraction powered by AI — parse any document format into clean, structured output.

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 limits

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

1. Start fast (no token): mineru-open-api flash-extract <file> for quick Markdown conversion
2. 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
3. Web pages: mineru-open-api crawl <url> to convert web content
4. 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

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

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

Model comparison: vlm vs pipeline

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

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

Language family packs

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:

1. 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

2. 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

3. If unsure, prefer flash-extract — it's faster and requires no setup, but check file size first.

4. 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 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).

echo -n "https://arxiv.org/pdf/2509.22186" | md5sum | cut -c1-6

5. When the user asks to upgrade or update this skill, the agent MUST re-install the CLI binary:

npm install -g mineru-open-api@latest

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.

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.

Exit codes

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.

Reporting Issues

• Skill issues: Open an issue at https://github.com/opendatalab/MinerU-Ecosystem/tree/main/cli
• CLI issues: Open an issue at https://github.com/MinerU-Extract/mineru-ai