SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsmineru-ocr

mineru-ocr

Office & productivity

View repository

Updated 10-15 20:10

About this skill

MinerU PDF to Markdown

Prerequisite Configuration

Default Auto Mode: When no Token is configured, it automatically uses the official login-free lightweight interface; after a Token is configured, it automatically switches to the standard API.

Quick Use Without Configuration

  • No login required, no need to create .env
  • Suitable for quickly converting small local files or remote document URLs
  • Subject to official lightweight interface limits: rate-limited by IP, single file 10 MB, up to 20 pages

Upgrade to Standard API (Optional)

If you encounter the following situations, it is recommended to configure a Token:

  • File exceeds 10 MB
  • More than 20 pages
  • The lightweight interface encounters IP rate limiting
  • Need to extract web page URLs
  • Want to use the standard API quota more stably

Apply for an API Token

  1. Visit https://mineru.net/apiManage/token
  2. Register/log in to your account
  3. Create an API Token and copy it (format:eyJ0eXAiOiJKV1QiLCJhbGc...）

Configure Token

Method 1: Let AI configure it

"Help me configure MinerU, the Token is:xxx"

Method 2: Manual configuration

cd .claude/skills/mineru-ocr/config
cp .env.example .env
nano .env  # 填入 MINERU_API_TOKEN

Method 3: Reuse the Token already saved by the official CLI

If you have already run the official mineru-open-api auth, this skill will also try to fall back to reading ~/.mineru/config.yaml the Token saved in.

The current reading priority is:

  1. This skill's .claude/skills/mineru-ocr/config/.env in the MINERU_API_TOKEN
  2. Environment variable MINERU_API_TOKEN
  3. Environment variable MINERU_TOKEN
  4. Official CLI configuration ~/.mineru/config.yaml

Token Update

According to current rules, the Token validity period is 3 months (about 90 days). After expiration, conversion fails (error 401 or Unauthorized）。

Update method: tell the AI "My MinerU Token has expired, the new Token is: xxx"

Feature Description

Convert documents to Markdown format via MinerU, supporting:

  • Auto mode: without a Token it uses the login-free lightweight interface, with a Token it uses the standard API
  • PDF、DOC、DOCX、PPT、PPTX、PNG、JPG、JPEG
  • Local files, remote document URLs, web page URLs
  • OCR text recognition
  • Table recognition and preservation
  • Mathematical formula recognition
  • Result archiving, preserving Markdown, API responses, and related image resources for traceback

Capability Boundaries

Scenario Login-free lightweight interface Standard Token API
Local PDF / image / Docx / Pptx Supported Supported
Remote document URL (PDF, image, Doc/Docx, PPT/PPTx) Supported Supported
Web page URL / HTML Not supported Supported
Single file size Within 10 MB Within 200 MB
Page limit Within 20 pages Within 600 pages
Table recognition Not supported; according to official guidance, upgrade to standard mode is required Support
Formula recognition Not supported; per official guidance, upgrade to standard mode Support
Output Markdown Zip result package + Markdown / JSON / additional formats

Use cases for lightweight mode

  • First-time use, quick trial runs
  • Local small files
  • Remote PDF / Doc / Ppt links
  • Table recognition and formula recognition not required

Use cases for standard API

  • Large files, long documents
  • Scenarios more sensitive to tables, formulas, and complex layouts
  • Web page URL extraction
  • Want a more complete result package and to retain more intermediate results

Usage

/usr/bin/osascript -l JavaScript .claude/skills/mineru-ocr/scripts/convert.js "/path/to/file.pdf"
/usr/bin/osascript -l JavaScript .claude/skills/mineru-ocr/scripts/convert.js "https://cdn-mineru.openxlab.org.cn/demo/example.pdf"
/usr/bin/osascript -l JavaScript .claude/skills/mineru-ocr/scripts/convert.js "https://example.com/article"
/usr/bin/osascript -l JavaScript .claude/skills/mineru-ocr/scripts/convert.js checktoken

Configuration options

Edit .claude/skills/mineru-ocr/config/.env：

Option Default value Description
MINERU_API_TOKEN Empty Optional; if filled in, forces use of the standard Token API
MINERU_ENABLE_OCR true Enable OCR
MINERU_ENABLE_TABLE true Enable table recognition; mainly takes effect for the standard Token API
MINERU_ENABLE_FORMULA false Enable formula recognition; mainly takes effect for the standard Token API
MINERU_LANGUAGE_CODE ch Language code
MINERU_API_BASE https://mineru.net/api/v4 Standard API address
MINERU_MODEL_VERSION pipeline Standard Token API model; for legal documents, it is recommended to use the default pipeline, for complex layouts you can change it to vlm
MINERU_PAGE_RANGES Empty Standard Token API page range, e.g., 1-20、2,4-6
MINERU_POLL_MAX 20 Maximum polling attempts
MINERU_POLL_SLEEP 10 Polling interval (seconds)
MINERU_LOG_LEVEL medium Log level

Output

  • Local file: Markdown is saved to the same directory as the source file
  • Remote document URL / web page URL: Markdown is saved by default to the current directory when the command is executed
  • Archive：.claude/skills/mineru-ocr/archive/日期_时间_文件名/
  • Archive contents: the converted Markdown, API response, original input files, and the list of downloadable image resources

Recommendations for legal documents

  • By default, keep MINERU_MODEL_VERSION=pipeline
  • For formal materials such as complaints, evidence lists, court notices, and summonses, prioritize stability and low hallucination risk; it is not recommended to change the default to vlm
  • Only when scan quality is poor, the layout is extremely complex, or tables are dense should you consider switching to vlm
  • If you only need to view the first few pages of a case file first, you can set MINERU_PAGE_RANGES=1-20

Token self-check

When you want to confirm whether the current Token is valid, you can run:

/usr/bin/osascript -l JavaScript .claude/skills/mineru-ocr/scripts/convert.js checktoken
  • Token not configured: it will indicate that it is currently in lightweight mode
  • Token valid: it will indicate that the standard API is available
  • Token invalid: it will clearly indicate to reapply and update

Cloud mode / custom address

This skill currently only targets the official cloud API。

If you need to use your own cloud forwarding gateway, and that gateway is compatible with the official v4 API, you can modify it in .env :

MINERU_API_BASE=https://your-gateway.example.com/api/v4

The current script is adapted by default to the official cloud v4 API workflow.

If you have deployed the official mineru-api / mineru-router FastAPI service, they mainly expose /tasks、/file_parse and other interfaces,which are not within the current support scope of this skill. For such scenarios, it is recommended to:

  • Prefer using the official CLI / SDK to connect directly to the self-hosted service
  • This skill continues to maintain only the cloud mode, avoiding mixing in a second protocol

About the official Crawl

Web page extraction in the official skill is mainly implemented through the CLI's mineru-open-api crawl <url> , which belongs to Token mode capability, not a lightweight interface capability.

The CLI here is the command-line wrapper layer provided by the official. Under the hood, the CLI still calls MinerU's cloud API; it is not a local offline parser.

Your current skill also supports web page URLs now, but only when a Token is configured ; when no Token is configured, web page URLs will prompt the user to switch to the standard API.

Troubleshooting

Issue Solution
Lightweight interface rate limiting Retry later, or configure a Token to switch to the standard API
File too large / too many pages Configure a Token and switch to the standard API
Web page URL cannot be parsed by the lightweight interface The lightweight interface does not support HTML; please configure a Token
401/Unauthorized Token has expired; reapply and update it
Conversion timeout Increase MINERU_POLL_MAX or check the file size
Insufficient quota Check your MinerU account quota