MinerU OCR Local API

Hard Rules

1. 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

• - Use --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.
• Use --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.
• Use --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. 1. For a hosted API parse from URL:

CODEBLOCK0

1. 2. For a hosted API parse from a local file:

CODEBLOCK1

1. 3. For a local open-source MinerU parse:

CODEBLOCK2

1. 4. When the input is a local file and the user will need an IDE-accessible path, prefer saving beside the source file:

CODEBLOCK3

1. 5. Read these output fields before answering:

- mode: actual execution mode used - text: complete document Markdown from full.md or <file_stem>.md - 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 INLINECODE21

Useful Flags

• - --mode api|local|auto: choose hosted API, local runtime, or automatic selection
• INLINECODE23: return after submission without polling; API mode only
• INLINECODE24: skip downloading full_zip_url; API mode only
• INLINECODE26: store API downloads or local MinerU outputs in a specific directory
• INLINECODE27: pass a language hint
• INLINECODE28: force OCR mode
• INLINECODE29: turn off formula extraction
• INLINECODE30: explicit path to mineru.exe or INLINECODE32
• INLINECODE33: explicit Python path for INLINECODE34
• INLINECODE35: choose the local MinerU backend
• INLINECODE36: choose the local MinerU parse method
• INLINECODE37: useful in environments where Hugging Face access is restricted
• INLINECODE38: force a local inference device when needed

Present Results

• - If the user asks for all text, show the top-level text field.
• If the user asks where files were saved, report the paths in artifacts.
• If the output is large, give the saved file paths first and then the requested excerpt or summary.
• If API mode completed but archive download failed, report artifacts.full_zip_url.

Configuration

For API mode:

CODEBLOCK4

Windows PowerShell examples:

CODEBLOCK5

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:

CODEBLOCK6

Local mode only supports --file-path. It does not accept --file-url.

Error Handling

• - Missing API token: show the configuration error, tell the user to set MINERU_API_TOKEN, and include one-shot plus persistent commands.
• Missing local runtime: show the configuration error and stop.
• Failed task or failed local CLI run: show the error and stop.
• Poll timeout: tell the user the task id and that polling timed out.
• API archive download TLS error: rely on the built-in curl fallback before reporting failure.
• Missing expected output files: return any artifact paths that do exist and report the missing output.

References

• - references/output_schema.md: JSON envelope and artifact layout for both modes.

Load the reference file when:

• - You need to explain which saved files matter.
• You need to inspect mode-specific artifacts such as downloaded_zip, local_parse_dir, middle_json, or content_list.

Verification

Validate the skill folder:

CODEBLOCK7

Run a local runtime check against a sample PDF:

CODEBLOCK8

Run an API runtime check against a remote PDF:

CODEBLOCK9