A practical wrapper around MinerU's asynchronous APIs, upgraded for production-style usage.

What it handles for you:

• local file upload via MinerU signed URLs
• remote URL submission
• async polling until completion
• Agent Lightweight API and Precision API
• HTML routing to MinerU-HTML for precision mode
• optional markdown download for Agent tasks
• precision result zip download + auto-unzip
• easy access to full.md, full.html, layout.json, content/model JSON paths
• callback checksum generation and verification helpers

pip install mineru-python-client

Or from source:

git clone https://github.com/JimEverest/mineru-python-client.git
cd mineru-python-client
pip install -e .

• mineru_client.py — main client implementation
• run_mineru_demo.py — CLI-style example runner
• tests/test_mineru_client.py — unit tests using a fake HTTP session

from mineru_client import MinerUClient

client = MinerUClient(token='YOUR_TOKEN', poll_interval=5, timeout=600, request_timeout=60)
result = client.precision_parse_local_files(
    ['/path/to/document.pdf'],
    extra_formats=['html'],
)
print(result[0].full_zip_url)

This is the easiest production-style path for local files because it:

• uploads
• waits for completion
• downloads the zip
• extracts it
• gives you direct file paths

from mineru_client import MinerUClient

client = MinerUClient(token='YOUR_TOKEN', poll_interval=5, timeout=600)
bundle = client.precision_parse_local_bundle(
    '/path/to/document.pdf',
    output_dir='./mineru_output',
    extra_formats=['html'],
)

print(bundle.zip_path)
print(bundle.extract_dir)
print(bundle.markdown_path)
print(bundle.html_path)
print(bundle.layout_path)

This scans a directory, finds supported MinerU files, batches HTML and non-HTML files separately as needed, uploads them, waits for completion, and downloads/extracts every result.

from mineru_client import MinerUClient

client = MinerUClient(token='YOUR_TOKEN', poll_interval=5, timeout=600)
bundles = client.precision_parse_local_directory_bundles(
    './docs',
    output_dir='./mineru_batches',
)

for bundle in bundles:
    print(bundle.task.file_name, bundle.markdown_path, bundle.html_path)

from mineru_client import build_callback_checksum, verify_callback_signature

checksum = build_callback_checksum(uid, seed, content)
assert verify_callback_signature(uid, seed, content, checksum)

Precision local file:

MINERU_TOKEN=*** python3 run_mineru_demo.py \
  --mode precision-local \
  --input '/path/to/document.pdf' \
  --poll-interval 5 \
  --timeout 600 \
  --request-timeout 60 \
  --extra-format html

Precision local bundle download + unzip:

MINERU_TOKEN=*** python3 run_mineru_demo.py \
  --mode precision-local-bundle \
  --input '/path/to/document.pdf' \
  --bundle-output-dir './mineru_output' \
  --poll-interval 5 \
  --timeout 600 \
  --extra-format html

Precision directory batch scan + bundle download:

MINERU_TOKEN=*** python3 run_mineru_demo.py \
  --mode precision-directory-bundles \
  --input './docs' \
  --bundle-output-dir './mineru_batches' \
  --poll-interval 5 \
  --timeout 600 \
  --extra-format html

Agent local file:

python3 run_mineru_demo.py \
  --mode agent-local \
  --input '/path/to/small.pdf' \
  --download-markdown

• Precision API requires a token.
• Agent API does not require a token, but is limited to small single files and does not support HTML.
• MinerU parsing is asynchronous; this wrapper uploads/submits first, then polls until done or failed.
• Precision local uploads use /api/v4/file-urls/batch even for a single file.
• Directory batch mode scans supported extensions only: pdf, doc, docx, ppt, pptx, png, jpg, jpeg, jp2, webp, gif, bmp, html, htm.
• Agent local uploads use /api/v1/agent/parse/file and then PUT the file to the returned signed URL.
• The wrapper validates local files before creating remote tasks.
• The wrapper requires HTTPS for signed upload URLs and result URLs.
• Duplicate local basenames are automatically assigned unique data_id values.