mang30/myskills/pdf-to-md-mineru

PDF to Markdown via MinerU API

Convert PDF documents (especially academic papers) to high-quality Markdown using MinerU's cloud parsing API. MinerU excels at recognizing complex layouts, mathematical formulas, tables, and figures commonly found in research papers.

Prerequisites

• Python 3 with requests and zipfile available
• Network access to https://mineru.net (the MinerU API endpoint)
• For the Precise API: a MinerU API Token (apply at https://mineru.net/apiManage)
• For the Agent Lightweight API: no token needed (IP rate-limited)

Quick Decision: Which API to Use

If the user has not specified a preference and the file is small, default to the Agent Lightweight API for zero-friction usage. Ask the user if they have a MinerU token only when the file exceeds lightweight limits.

Workflow

Step 1: Determine the input source

The PDF can come from:

1. A URL — the user provides a direct link to the PDF
2. A local file — the user uploads a PDF to /mnt/user-data/uploads/

If the PDF is a local file, you need to upload it to get it parsed. The approach differs by API:

• Precise API: Use the batch file upload endpoint to get a presigned URL, then PUT the file
• Agent Lightweight API: Use the /api/v1/agent/parse/file endpoint to get a signed upload URL, then PUT the file

If the PDF is a URL, you can submit it directly.

Step 2: Check for token

Look for a MinerU token. The user may provide it directly, or it may be stored in an environment variable. Common locations:

• Environment variable: MINERU_API_TOKEN
• The user states it in conversation

If no token is found and the file fits within lightweight limits (≤ 10MB, ≤ 20 pages), use the Agent Lightweight API without asking. If the file exceeds limits, ask the user to provide a token.

Step 3: Run the conversion script

Execute the conversion using the bundled script:

python /path/to/skill/scripts/mineru_pdf_to_md.py \
  --input <pdf_path_or_url> \
  --output <output_dir> \
  [--token <token>] \
  [--model vlm|pipeline] \
  [--language ch] \
  [--enable-ocr] \
  [--timeout 600] \
  [--api precise|agent]

Key arguments:

• --input: PDF file path or URL
• --output: Directory to save the resulting .md file (defaults to current directory)
• --token: MinerU API token (required for Precise API, omit for Agent API)
• --model: vlm (recommended, better accuracy) or pipeline (faster). Default: vlm. Only for Precise API
• --language: Document language, default ch (Chinese+English). Use en for English-only papers
• --enable-ocr: Enable OCR for scanned PDFs
• --api: Force precise or agent API. Auto-detected if omitted
• --timeout: Max seconds to wait for parsing, default 600

Step 4: Deliver the output

After the script completes:

1. The .md file will be in the output directory
2. Copy it to /mnt/user-data/outputs/ for the user to download
3. Optionally show a preview of the first ~50 lines

If the Precise API was used, the script also downloads and extracts the full zip (containing images, JSON, etc.) into a subfolder. The main markdown file is full.md inside the zip.

Error Handling

Tips for Academic Papers

• Use --model vlm for papers with complex layouts, multi-column text, or heavy math — vlm model gives significantly better results on academic content
• For papers in English only, set --language en for slightly better OCR accuracy
• If the paper has scanned pages or image-based text, add --enable-ocr
• The resulting markdown preserves LaTeX math notation (inline $...$ and display $$...$$), which is ideal for further processing or reading in markdown renderers that support math