MinerU Open API SDK (Python)
MinerU Open API SDK is a completely free Python library for the MinerU document extraction service. Turn any document (PDF, Images, Word, PPT, Excel) or Web Page into high-quality Markdown with just one line of code.
🚀 Key Features
- Completely Free: No hidden costs for document extraction.
- Flash Extract (No Auth): Extract text instantly without an API token.
- Precision Extract: Comprehensive extraction with layout preservation, images, and formula support.
- Batch & Polling Primitives: Blocking methods for simple flows plus submit/query methods for asynchronous workflows.
- Simple Save Helpers: Save Markdown, HTML, LaTeX, DOCX, or the full extracted zip with built-in helpers.
📦 Install
pip install mineru-open-sdk
🛠️ Quick Start
1. Flash Extract (Fast, No Auth)
Ideal for quick previews. No token required.
from mineru import MinerU
# No token needed for Flash Extract
client = MinerU()
result = client.flash_extract("https://cdn-mineru.openxlab.org.cn/demo/example.pdf")
print(result.markdown)
2. Precision Extract (Auth Required)
Supports large files, rich assets (images/tables), and multiple formats.
from mineru import MinerU
# Get your free token from https://mineru.net/apiManage/token
client = MinerU("your-api-token")
result = client.extract("https://cdn-mineru.openxlab.org.cn/demo/example.pdf")
print(result.markdown)
print(result.images) # Access extracted images
🧩 Supported Public API
Client lifecycle
MinerU(token: str | None = None, base_url: str = ..., flash_base_url: str | None = None)client.close()client.set_source("your-app")- context manager support:
with MinerU(...) as client:
Blocking extraction methods
client.extract(...) -> ExtractResultclient.extract_batch(...) -> Iterator[ExtractResult]client.crawl(...) -> ExtractResultclient.crawl_batch(...) -> Iterator[ExtractResult]client.flash_extract(...) -> ExtractResult
Submit/query methods
client.submit(...) -> strclient.submit_batch(...) -> strclient.get_batch(batch_id) -> list[ExtractResult]client.get_task(task_id) -> ExtractResult
Result helpers
result.save_markdown(path, with_images=True)result.save_docx(path)result.save_html(path)result.save_latex(path)result.save_all(dir)image.save(path)
Result fields you will usually use
result.stateresult.progressresult.markdownresult.imagesresult.content_listresult.docxresult.htmlresult.latexresult.task_id
📊 Mode Comparison
| Feature | Flash Extract | Precision Extract |
|---|---|---|
| Auth | No Auth Required | Auth Required (Token) |
| Speed | Blazing Fast | Standard |
| File Limit | Max 10 MB | Max 200 MB |
| Page Limit | Max 20 Pages | Max 600 Pages |
| Formats | PDF, Images, Docx, PPTx, Excel | PDF, Images, Doc/x, Ppt/x, Html |
| Content | Markdown (formula & table on by default, OCR off) | Full assets (Images, Tables, Formulas) |
| Output | Markdown | MD, Docx, LaTeX, HTML, JSON |
⚙️ Defaults And Option Behavior
MinerU(...)
| Argument | Default | Behavior |
|---|---|---|
token |
None |
If omitted, the SDK reads MINERU_TOKEN from the environment |
base_url |
https://mineru.net/api/v4 |
Standard API base URL |
flash_base_url |
SDK default flash URL | Override flash API endpoint for testing/private deployments |
If neither token nor MINERU_TOKEN is set, the client works in flash-only mode: flash_extract() works, while auth-required methods raise NoAuthClientError.
Precision methods
These defaults apply to extract(), extract_batch(), submit(), submit_batch(), and indirectly to crawl() / crawl_batch() unless noted otherwise.
| Option | Default | Behavior when omitted |
|---|---|---|
model |
None |
Auto-infers model: .html/.htm uses "html", everything else uses "vlm" |
ocr |
not set | OCR is disabled (API default) |
formula |
not set | Formula recognition is enabled (API default) |
table |
not set | Table recognition is enabled (API default) |
language |
not set | Chinese "ch" (API default) |
pages |
None |
Full document is processed |
extra_formats |
None |
Only the default Markdown/JSON payload is returned |
file_params |
None |
Per-file overrides for batch methods. A dict[str, FileParam] keyed by path/URL, where FileParam has fields pages, ocr, data_id |
timeout |
300 seconds for single-item methods |
Max total polling time for extract() / crawl() |
timeout |
1800 seconds for batch methods |
Max total polling time for extract_batch() / crawl_batch() |
Flash Extract
| Option | Default | Behavior when omitted |
|---|---|---|
language |
"ch" |
Default language is Chinese |
page_range |
None |
Full page range allowed by the flash API |
is_ocr |
None |
OCR is off (API default) |
enable_formula |
None |
Formula recognition is on (API default) |
enable_table |
None |
Table recognition is on (API default) |
timeout |
300 seconds |
Max total polling time |
crawl() / crawl_batch()
crawl()is shorthand forextract(url, model="html", ...)crawl_batch()is shorthand forextract_batch(urls, model="html", ...)
📖 Detailed Usage
Precision Extraction Options
result = client.extract(
"./paper.pdf",
model="vlm", # "vlm" | "pipeline" | "html"
ocr=True, # Enable OCR for scanned documents
formula=True, # Formula recognition
table=True, # Table recognition
language="en", # "ch" | "en" | etc.
pages="1-20", # Page range
extra_formats=["docx"], # Export as docx, html, or latex
timeout=600,
)
result.save_all("./output/") # Save markdown and all assets
Context Manager
from mineru import MinerU
with MinerU("your-api-token") as client:
result = client.extract("./paper.pdf")
print(result.markdown)
Batch Processing
# Yields results as they complete
for result in client.extract_batch(["a.pdf", "b.pdf", "c.pdf"]):
print(f"{result.filename}: Done")
Batch With Per-File Pages
from mineru import FileParam
batch_id = client.submit_batch(
["a.pdf", "b.pdf"],
file_params={
"a.pdf": FileParam(pages="1-5"),
"b.pdf": FileParam(pages="10-20"),
},
)
Web Crawling
result = client.crawl("https://www.baidu.com")
print(result.markdown)
🔄 submit() / get_batch() Semantics
This is the part most people get wrong at first:
submit()returns a batch IDsubmit_batch()also returns a batch ID- the common async flow is therefore
submit(...) -> get_batch(batch_id) - recommends staying on the batch-based flow for async polling
Recommended async flow
batch_id = client.submit("large-report.pdf")
# poll the batch until the first item is done
while True:
results = client.get_batch(batch_id)
result = results[0]
if result.state in ("done", "failed"):
break
if result.state == "done":
do_something(result.markdown)
🤖 Integration for AI Agents
The SDK is designed to be easily integrated into LLM workflows. For status updates, you can check result.state and result.progress.
batch_id = client.submit("large-report.pdf")
# ... later ...
result = client.get_batch(batch_id)[0]
if result.state == "done":
do_something(result.markdown)
📄 License
This project is licensed under the Apache-2.0 License.
🔗 Links
Metadata
Release files for mineru-open-sdk 0.2.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mineru_open_sdk-0.2.5.tar.gz | 32.1 kB | Without provenance | Details for mineru_open_sdk-0.2.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mineru_open_sdk-0.2.5-py3-none-any.whl | Python 3 | none | any | Details for mineru_open_sdk-0.2.5-py3-none-any.whl |
Total release size: 51.6 kB
Release files / mineru_open_sdk-0.2.5.tar.gz
| Download URL | mineru_open_sdk-0.2.5.tar.gz |
|---|---|
| Size | 32.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
430baeacae3f18537edb62e69532620ce7fbead7d43f72b986d0cb1cc7932ee9
|
|
BLAKE2b-256 checksum How to use checksums |
645bbe9b0ae9f515132741f91b64f3de7dcb448d8701503b82e3fee72f0aa402
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / mineru_open_sdk-0.2.5-py3-none-any.whl
| Download URL | mineru_open_sdk-0.2.5-py3-none-any.whl |
|---|---|
| Size | 19.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
db22bb764318eb3167d4cfb28849df70159b76a0ad268648ad91e9f2d47c0c1c
|
|
BLAKE2b-256 checksum How to use checksums |
96dd667e108350a0b4683e913d2b15b21da3b3117469f586bb0652c9cbc2754d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Security for mineru-open-sdk 0.2.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.