Precision Document Extraction with mineru-open-api

Full-featured document extraction with table/formula recognition, OCR, multi-format output, batch processing, and web crawling.

Why use extract?

• Table recognition — accurately extracts tables from PDFs and images
• Formula recognition — preserves mathematical formulas as LaTeX
• Multi-format output — Markdown, HTML, LaTeX, DOCX, JSON
• Model selection — choose vlm for highest accuracy or pipeline for zero-hallucination
• Batch processing — process hundreds of files in one command
• Web crawling — convert web pages to structured Markdown
• All file formats — PDF, images, DOC, DOCX, PPT, PPTX, HTML
• Higher limits — much larger file size and page count than quick mode
• 80+ languages — full language coverage across all script families

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

Authentication

Create a token at https://mineru.net/apiManage/token, then configure:

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.

Quick start

mineru-open-api extract report.pdf                         # Markdown to stdout
mineru-open-api extract report.pdf -o ./out/               # Save to directory
mineru-open-api extract report.pdf -f md,html,docx -o ./   # Multi-format
mineru-open-api extract report.pdf --model vlm -o ./out/   # High-accuracy mode
mineru-open-api extract *.pdf -o ./results/                # Batch extract
mineru-open-api crawl https://example.com/article          # Web page → Markdown

Supported input formats

Commands

extract — Precision extraction

mineru-open-api extract <file-or-url> [...] [flags]

Examples

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 report.pdf -f latex -o ./out/      # LaTeX output
mineru-open-api extract report.pdf --model vlm -o ./out/   # High-accuracy mode
mineru-open-api extract report.pdf --ocr -o ./out/         # OCR for scanned docs
mineru-open-api extract report.pdf --language en -o ./out/ # Specify language
mineru-open-api extract report.pdf --pages "1-10" -o ./out/  # Page range
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

Fetch web pages and convert to structured 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

Values are organized by script/language family — each value covers all languages in its group.

Standalone language packs

Language family packs

Global flags

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): requires -o to specify output directory
• Binary formats (docx): cannot output to stdout, must use -o
• Markdown output includes extracted images saved alongside the .md file

Agent guidelines

When using this skill on behalf of the user:

• Quote file paths that contain spaces or special characters with double quotes. Example: mineru-open-api extract "report 01.pdf".
• Don't run commands blindly on errors — explain the exit code and troubleshooting steps.
• Installation questions ("mineru 怎么安装") should be answered with the install instructions above.
• For stdout mode (no -o), only one text format can be output at a time. If the user wants multiple formats, suggest adding -o.
• If the user hasn't authenticated yet, guide them to create a token at https://mineru.net/apiManage/token and run mineru-open-api auth.

Default output directory

When the user does NOT specify -o, generate a default output directory:

~/MinerU-Skill/<name>_<hash>/

• <name>: derived from the source, then sanitized (replace spaces and shell-unsafe characters with _, collapse consecutive _).
  • 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)
• <hash>: first 6 characters of MD5 hash of the full original source.

echo -n "source" | md5sum | cut -c1-6   # Linux
echo -n "source" | md5 | cut -c1-6      # macOS

When the user specifies -o: use the user's path as-is.

Skill upgrade = CLI upgrade

When the user asks to upgrade this skill, re-install the CLI first:

npm install -g mineru-open-api@latest

Exit codes

Troubleshooting

• "no API token found": Run mineru-open-api auth or set MINERU_TOKEN env variable. Create token at https://mineru.net/apiManage/token.
• Timeout on large files: Increase with --timeout 1600
• 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 --model vlm for complex layouts, or --ocr for scanned documents
• Tables not extracted correctly: Try --model vlm for better table recognition

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-document-extractor