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

mineru-ocr

Coding & development

View repository

Updated 10-15 20:10

About this skill

MinerU PDF to Markdown

Prerequisite Configuration

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

Quick Start 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, maximum 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 reliably

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 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 read priority is:

  1. This skill's .claude/skills/mineru-ocr/config/.env in 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 the current rules, the Token is valid for 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, use the login-free lightweight interface; with a Token, use 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, retaining Markdown, interface responses, and related image resources for traceback

Capability Boundaries

Scenario Login-free lightweight interface Standard Token API
Local PDF / images / Docx / Pptx Supported Supported
Remote document URL (PDF, images, 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; per official guidance, upgrade to standard mode Supported
Formula recognition Not supported; according to the official statement, an upgrade to standard mode is required Supported
Output Markdown Zip result package + Markdown / JSON / additional formats

Applicable to lightweight mode

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

Applicable to standard API

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

How to use

/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, the standard Token API is forcibly used
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 URL
MINERU_MODEL_VERSION pipeline Standard Token API model; for legal documents, the default is recommended 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 number of polling attempts
MINERU_POLL_SLEEP 10 Polling interval (seconds)
MINERU_LOG_LEVEL medium Log level

Output

  • Local files: 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 a 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 look at 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 lightweight mode is currently in use
  • Token valid: it will indicate that the standard API is available
  • Token invalid: it will clearly indicate that you need to reapply and update it

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 what you have deployed is the official mineru-api / mineru-router FastAPI service, they mainly expose /tasks、/file_parse and other interfaces,which are not within the scope currently supported by 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

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

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

Your current skill now also supports web page URLs, but only when Token is configured ; when Token is not 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 Token to switch to the standard API
File too large / too many pages Configure 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 Token
401/Unauthorized Token has expired, reapply and update
Conversion timed out Increase MINERU_POLL_MAX or check the file size
Insufficient quota Check the MinerU account balance