MinerU API Skill

Overview

MinerU converts PDF, DOC, DOCX, PPT, PPTX, PNG, JPG, JPEG, HTML into machine-readable Markdown/JSON. Supports OCR (109 languages), formula/table recognition, cross-page table merging, and batch processing.

Two modes:

• Cloud API — https://mineru.net/api/v4 (no GPU required, token-based)
• Local API — mineru-api --port 8000 (self-hosted, requires GPU or CPU backend)

Authentication (Cloud API)

• Token file: ~/.config/mineru/token
• Header: Authorization: Bearer <token>
• Get token: https://mineru.net/apiManage/token

mkdir -p ~/.config/mineru
echo "YOUR_TOKEN" > ~/.config/mineru/token
chmod 600 ~/.config/mineru/token

Limits (Cloud API)

Model Versions

API Endpoints (Cloud)

Base URL: https://mineru.net/api/v4

1. Create Extraction Task (Single File)

POST /extract/task

Response:

{"code": 0, "data": {"task_id": "xxx"}, "msg": "ok"}

2. Get Task Results

GET /extract/task/{task_id}

States: pending → running → done / failed / converting

Done response: includes full_zip_url (download link)

3. Batch Upload Local Files

POST /file-urls/batch

Returns presigned upload URLs (valid 24h). System auto-submits extraction after upload.

4. Batch URL Extraction

POST /extract/task/batch

Submit multiple URLs at once, returns batch_id.

5. Batch Results

GET /extract-results/batch/{batch_id}

Local API (Self-Hosted)

Start Server

# FastAPI server
mineru-api --host 0.0.0.0 --port 8000

# Gradio WebUI
mineru-gradio --server-name 0.0.0.0 --server-port 7860

# OpenAI-compatible server (for remote VLM inference)
mineru-openai-server --port 30000

Environment Variables

Local API Docs

Access at http://127.0.0.1:8000/docs after starting.

Use CLI with Remote Server

mineru -p input.pdf -o output/ -b hybrid-http-client -u http://server:30000

Error Codes

Helper Script

~/.claude/skills/mineru/scripts/mineru-parse.sh — full-featured CLI wrapper.

# URL mode
mineru-parse.sh https://example.com/doc.pdf

# Local file with options
mineru-parse.sh /path/to/file.pdf --model vlm --ocr --output /tmp/result

# Extra formats
mineru-parse.sh doc.pdf --format docx --format latex

# Page ranges
mineru-parse.sh doc.pdf --pages "1-5,8" --output ./results

# Auto-extract markdown from zip
mineru-parse.sh doc.pdf --output ./results --extract

Quick Parse (Python)

import requests, time

TOKEN = open("~/.config/mineru/token").read().strip()
BASE = "https://mineru.net/api/v4"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

def parse_document(url, model="hybrid", ocr=False, extra_formats=None):
    """Parse a document from URL, return download link."""
    body = {
        "url": url, "model_version": model,
        "is_ocr": ocr, "enable_formula": True, "enable_table": True,
    }
    if extra_formats:
        body["extra_formats"] = extra_formats

    resp = requests.post(f"{BASE}/extract/task", headers=HEADERS, json=body)
    task_id = resp.json()["data"]["task_id"]

    while True:
        result = requests.get(f"{BASE}/extract/task/{task_id}", headers=HEADERS).json()
        state = result["data"]["state"]
        if state == "done":
            return result["data"]["full_zip_url"]
        elif state == "failed":
            raise Exception(f"Task failed: {result}")
        time.sleep(5)

Quick Parse (curl)

TOKEN=$(cat ~/.config/mineru/token)

# Submit
curl -s -X POST "https://mineru.net/api/v4/extract/task" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/doc.pdf","model_version":"hybrid"}'

# Check result
curl -s "https://mineru.net/api/v4/extract/task/{task_id}" \
  -H "Authorization: Bearer $TOKEN"

Installation (Local Mode)

pip install uv
uv pip install -U "mineru[all]"

Requirements: Python 3.10-3.13, 16GB+ RAM, 20GB+ SSD. GPU optional (Volta+ or Apple Silicon).