MinerU OCR Local & API
by @focusshang
Parse complex PDFs and document images with MinerU through either the hosted MinerU API or the local open-source MinerU runtime. Use when Codex, OpenClaw, Cl...
clawhub install mineru-ocr-local-apiπ About This Skill
name: mineru-ocr-local-api description: Parse complex PDFs and document images with MinerU through either the hosted MinerU API or the local open-source MinerU runtime. Use when Codex, OpenClaw, Claude Code, or similar coding agents need MinerU-based OCR, layout-aware Markdown extraction, formula extraction, local-file upload to the MinerU API, local MinerU CLI parsing from https://github.com/opendatalab/MinerU, mode selection between api and local, task polling, archive download, or complete document text extraction. metadata: openclaw: homepage: https://github.com/opendatalab/MinerU primaryEnv: MINERU_API_TOKEN requires: anyBins: - python - python.exe envVars: - name: MINERU_API_TOKEN required: false description: Required for hosted MinerU API mode. - name: MINERU_API_BASE_URL required: false description: Optional MinerU API base URL override. - name: MINERU_API_TIMEOUT required: false description: Optional HTTP timeout for MinerU API mode. - name: MINERU_API_POLL_TIMEOUT required: false description: Optional polling timeout for MinerU API mode. - name: MINERU_API_POLL_INTERVAL required: false description: Optional polling interval for MinerU API mode. - name: MINERU_LOCAL_CMD required: false description: Optional path to mineru or mineru.exe for local mode. - name: MINERU_LOCAL_PYTHON required: false description: Optional Python interpreter for python -m mineru.cli.client. - name: MINERU_LOCAL_BACKEND required: false description: Optional local MinerU backend override. - name: MINERU_LOCAL_METHOD required: false description: Optional local MinerU parse method override. - name: MINERU_LOCAL_LANG required: false description: Optional local MinerU language hint. - name: MINERU_LOCAL_MODEL_SOURCE required: false description: Optional local MinerU model source override. - name: MINERU_LOCAL_DEVICE_MODE required: false description: Optional local MinerU device override. - name: MINERU_LOCAL_TIMEOUT required: false description: Optional timeout for local MinerU mode. dependencies: - name: httpx type: pip version: ">=0.27" url: https://pypi.org/project/httpx/ repository: https://github.com/encode/httpx
MinerU OCR Local API
Hard Rules
1. Use python scripts/mineru_caller.py for every MinerU request.
2. Do not parse the document yourself as a fallback.
3. If MinerU returns an error, show the error and stop.
4. Treat the saved JSON envelope and generated artifact files as the source of truth.
5. Prefer the top-level text field when the user asks for the full extracted document.
Choose The Mode
--mode api when the user wants the hosted MinerU service, already has MINERU_API_TOKEN, needs URL input, or wants the official cloud API workflow.--mode local when the user wants the open-source MinerU runtime from https://github.com/opendatalab/MinerU, wants data to stay local, or explicitly asks for local parsing.--mode auto only when the user does not care which mode is used. auto prefers API when MINERU_API_TOKEN is configured and falls back to local only for local files.Standard Workflow
1. For a hosted API parse from URL:
python scripts/mineru_caller.py --mode api --file-url "https://example.com/paper.pdf" --pretty
2. For a hosted API parse from a local file:
python scripts/mineru_caller.py --mode api --file-path "C:/docs/paper.pdf" --pretty
3. For a local open-source MinerU parse:
python scripts/mineru_caller.py --mode local --file-path "C:/docs/paper.pdf" --pretty
4. When the input is a local file and the user will need an IDE-accessible path, prefer saving beside the source file:
python scripts/mineru_caller.py --mode local --file-path "C:/docs/paper.pdf" --download-dir "C:/docs/paper.mineru" --pretty
5. Read these output fields before answering:
- mode: actual execution mode used
- text: complete document Markdown from full.md or
- result.submit: raw task-creation response for API URL parsing
- result.batch: raw upload-batch response for API local-file parsing
- result.poll: final API task-status payload
- result.local: local MinerU CLI invocation summary
- artifacts.full_md_path: absolute path to the main Markdown file
- artifacts.local_parse_dir: local MinerU parse directory when using --mode local
- artifacts.downloaded_zip: downloaded MinerU archive when using --mode api
Useful Flags
--mode api|local|auto: choose hosted API, local runtime, or automatic selection--no-wait: return after submission without polling; API mode only--no-download: skip downloading full_zip_url; API mode only--download-dir DIR: store API downloads or local MinerU outputs in a specific directory--language en: pass a language hint--ocr: force OCR mode--disable-formula: turn off formula extraction--local-cmd PATH: explicit path to mineru.exe or mineru--local-python PATH: explicit Python path for python -m mineru.cli.client--local-backend pipeline: choose the local MinerU backend--local-method auto|txt|ocr: choose the local MinerU parse method--local-model-source modelscope: useful in environments where Hugging Face access is restricted--local-device cpu: force a local inference device when neededPresent Results
text field.artifacts.artifacts.full_zip_url.Configuration
For API mode:
MINERU_API_TOKEN
MINERU_API_BASE_URL=https://mineru.net
MINERU_API_TIMEOUT=60
MINERU_API_POLL_TIMEOUT=900
MINERU_API_POLL_INTERVAL=5
Windows PowerShell examples:
$env:MINERU_API_TOKEN="YOUR_MINERU_TOKEN"
setx MINERU_API_TOKEN "YOUR_MINERU_TOKEN"
Use the first command for the current terminal only. Use setx to persist it for future terminals, then restart Codex/Cursor or open a new terminal.
For local mode, configure at least one runtime entry point:
MINERU_LOCAL_CMD=C:\path\to\mineru.exe
MINERU_LOCAL_PYTHON=C:\path\to\python.exe
MINERU_LOCAL_BACKEND=pipeline
MINERU_LOCAL_METHOD=auto
MINERU_LOCAL_LANG=ch
MINERU_LOCAL_MODEL_SOURCE=modelscope
MINERU_LOCAL_DEVICE_MODE=cpu
MINERU_LOCAL_TIMEOUT=3600
Local mode only supports --file-path. It does not accept --file-url.
Error Handling
MINERU_API_TOKEN, and include one-shot plus persistent commands.curl fallback before reporting failure.References
references/output_schema.md: JSON envelope and artifact layout for both modes.Load the reference file when:
downloaded_zip, local_parse_dir, middle_json, or content_list.Verification
Validate the skill folder:
python /path/to/quick_validate.py /path/to/mineru-ocr-api-local
Run a local runtime check against a sample PDF:
python scripts/mineru_caller.py --mode local --file-path "D:/path/to/file.pdf" --pretty --stdout
Run an API runtime check against a remote PDF:
python scripts/mineru_caller.py --mode api --file-url "https://example.com/file.pdf" --pretty --stdout
βοΈ Configuration
For API mode:
MINERU_API_TOKEN
MINERU_API_BASE_URL=https://mineru.net
MINERU_API_TIMEOUT=60
MINERU_API_POLL_TIMEOUT=900
MINERU_API_POLL_INTERVAL=5
Windows PowerShell examples:
$env:MINERU_API_TOKEN="YOUR_MINERU_TOKEN"
setx MINERU_API_TOKEN "YOUR_MINERU_TOKEN"
Use the first command for the current terminal only. Use setx to persist it for future terminals, then restart Codex/Cursor or open a new terminal.
For local mode, configure at least one runtime entry point:
MINERU_LOCAL_CMD=C:\path\to\mineru.exe
MINERU_LOCAL_PYTHON=C:\path\to\python.exe
MINERU_LOCAL_BACKEND=pipeline
MINERU_LOCAL_METHOD=auto
MINERU_LOCAL_LANG=ch
MINERU_LOCAL_MODEL_SOURCE=modelscope
MINERU_LOCAL_DEVICE_MODE=cpu
MINERU_LOCAL_TIMEOUT=3600
Local mode only supports --file-path. It does not accept --file-url.