mineru-runpod

Serverless MinerU document parser on RunPod. MinerU 3.4.x runtime with the MinerU2.5-Pro-2605-1.2B VLM. Scales to zero; best-case warm parses measured about $0.0003 per page on a 24 GB serverless RTX 4090.

Docs · Get started on RunPod · Blog

⚠️ Not an official MinerU project. This is an independent wrapper that packages the open-source MinerU runtime as a RunPod Serverless worker. It is not affiliated with, endorsed by, or supported by OpenDataLab, who publish MinerU, or by RunPod. Parsing behavior belongs upstream; anything about this worker belongs here.

Parse a document

Python (mineru_client):

from mineru_client import MineruClient

client = MineruClient(endpoint_id="<your-endpoint-id>")
result = client.parse_document(file_url="https://example.com/report.pdf", end_page=4)
client.save_tarball(result, "./out/doc")
# → markdown + content_list + middle.json + images

curl (no SDK):

curl -X POST "https://api.runpod.ai/v2/<endpoint-id>/runsync" \
  -H "Authorization: Bearer $RUNPOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"file_url":"https://example.com/report.pdf","end_page":4,"transport":"inline"}}'

The response wraps each parsed file as an entry inside results: [...]. For a single document, the markdown sits at output.results[0].markdown — pipe it straight to a file: curl ... | jq -r '.output.results[0].markdown' > report.md.

Accepts PDF, image (PNG/JPEG/GIF/BMP/TIFF/WebP), DOCX, PPTX, XLSX. Two orthogonal knobs control output — transport (tarball_b64 / inline / s3) and formats — both covered in Output modes.

Why this exists

• MinerU produces structured Markdown/JSON for text, charts, tables, and math. MinerU 3.4 also provides script-family OCR models through its pipeline backend. See the paper, repo, and model card for the published evaluation scope.
• RunPod Serverless bills per-second and scales to zero. A 100-page document costs roughly $0.03 on a 24 GB serverless RTX 4090 instead of paying for an always-on GPU. See RunPod pricing for current rates.
• Wiring the two together is the part this repo does for you. Deploy from the RunPod Hub in one click, or fork the repo for full control.

Calling the endpoint

A. Quick start with MineruClient

A small Python wrapper that lives in this repo. Best for prototyping and single-user scripts — usage is the snippet above. Install it with:

# pip
pip install "mineru-client @ git+https://github.com/sergeyshmakov/mineru-runpod"

# or uv
uv pip install "mineru-client @ git+https://github.com/sergeyshmakov/mineru-runpod"

B. Production with RunPod SDK / HTTP

For high-throughput, async, or non-Python callers. Hit the endpoint directly using the documented JSON payload contract.

import runpod
runpod.api_key = "..."
endpoint = runpod.Endpoint("<endpoint-id>")
result = endpoint.run_sync({"input": {"file_url": "https://example.com/report.pdf"}})

C. Migrating from the official MinerU API

Already calling the MinerU cloud API (mineru.net/api/v4/...)? MineruApiClient mirrors its create_task / get_task surface over your own endpoint, so you can evaluate or migrate with a near-identical code path. See Migrate from the MinerU API.

Prototype with A; switch to B once you need async, retries, or multi-language callers. See Clients for the full comparison.

The API

Send {"input": {...}} to /runsync (or /run). The most-used fields:

Responses wrap each file in a results: [...] list alongside a top-level debug block; failures set ok=false with a top-level error. The full field list, per-transport response shapes, and validation rules live in the API reference (mirrored from the docstring atop handler.py).

Under that contract, this repo is the MinerU half: the engine, the input schema and the job envelope. Fetching the input, checking outbound targets, packing the response, structured logging and the model-cache probe come from runpod-doc-worker (docs), an engine-agnostic harness extracted from this worker. What this worker declares to it — its env prefix, input roots and output manifest — is one file, worker/harness.py.

Compared with other parsers

Parsing accuracy is MinerU's domain; their published OmniDocBench leaderboard puts the 1.2B VLM ahead of much larger general-purpose models:

_{Source: MinerU2.5-Pro-2605-1.2B model card and the MinerU 2.5 technical report.}

_{*The MinerU Open Source License is based on Apache 2.0, requires attribution for third-party online services, and requires a separate commercial license when consolidated monthly active users exceed 100 million or total monthly revenue exceeds USD 20 million. Review the current upstream license for your use case.}

_{**Marker's code is GPL-3.0; its OCR engine (Surya) ships under a modified RAIL-M licence whose §2(c) prohibits use by entities that "provide … any product or service that competes with … Licensor." Datalab's own README says Marker is free for "startups under $2M funding/revenue" — that carveout doesn't appear in the literal licence text, so the two read differently. Verify the current licence against your own usage with counsel before depending on Marker for a competing service. Datalab ships Chandra (the model behind their hosted API) under the same modified RAIL-M licence. See Surya MODEL_LICENSE and Chandra MODEL_LICENSE.}

The license row matters for production use. Marker pairs GPL-3.0 code with modified RAIL-M weights whose competitor clause warrants review. Nougat's model weights are CC-BY-NC 4.0. GROBID is Apache 2.0. MinerU uses its own Apache-based license with additional terms, so evaluate the current upstream text rather than treating any of these projects as interchangeable on licensing.

Documentation

The docs site covers the rest:

• Overview — what it is, who it's for, architecture
• Deploy — Hub one-click, fork-and-build, or BYO image
• Clients — Python MineruClient vs. direct RunPod SDK
• Migrate from the MinerU API — compatibility facade for evaluating a move from the cloud API
• Choosing a GPU — workload-to-pool map, when to bump VRAM
• API reference — JSON payload contract, response shapes, validation rules
• Blog — launch posts and project notes

Versioning

The major is reserved for the engine because that is the change that moves output quality and behaviour. A template-contract break ships on a minor, so read the release notes before upgrading a minor -- they lead with anything that needs action.

A change that breaks pip install mineru-client -- a raised Python floor, a dropped import path -- is also a minor, under Compatibility Changes. It is not a major: nothing range-pins a git-URL install, so the release notes are what reach you, and spending the major there would put it permanently out of step with MinerU.

The engine version is stated in the docs compatibility table rather than encoded in the version number.

Contributing

See CONTRIBUTING.md. Commits follow Conventional Commits; commitlint enforces this in CI and CHANGELOG.md is generated automatically by semantic-release on push to main.

Support this project

If this saves you time, the cheapest way to support development is to sign up for RunPod through this link. Costs you nothing extra and lets the maintainer keep iterating.

License

The wrapper code is MIT. The underlying MinerU and its model retain the MinerU Open Source License; the RunPod SDK is MIT.