Документация MinerU API — разбор документов в Markdown и JSON

Обзор

Создайте одну задачу для каждого файла или URL-адреса, опросите его status, затем загрузите ZIP. Запросы асинхронны. Pro Monthly и Pro Annual поддерживают API; Бесплатно нет.

https://YOUR_API_HOST/api/open/v1

Замените YOUR_API_HOST на свой домен API. Все пути ниже используют этот базовый URL. В примерах используются идентификаторы заполнителей и подписанные URL-адреса.

Аутентификация

Отправляйте Authorization: Bearer, а затем ключ Pro API при каждом запросе API. Получите или сбросьте ключ с помощью кнопки ключа API. Ключи чувствительны к регистру: sk- плюс 24 случайных букв и цифр. JWT входа пользователя не аутентифицируют эти конечные точки.

Authorization: Bearer sk-YOUR_API_KEY

Храните ключ на своем сервере. Не размещайте его в общедоступном интерфейсе code, репозиториях или запросах на загрузку. Загрузки используют собственный подписанный URL-адрес. Сброс ключа немедленно делает старый ключ недействительным; Для доступа к API также требуется активное членство Pro.

Быстрый старт

Замените хост API, установите MINERU_API_KEY и укажите paper.pdf. Эти примеры загружаются один раз, опрашиваются каждые 3 секунд в течение 30 минут, а затем передаются ZIP на диск. Тайм-аут опроса является ограничением клиента и не отменяет задачу сервера. Используйте идентификатор задачи, чтобы продолжить запрос. Для Python нужен пакет requests; Node.js нужна версия 20+; cURL использует Bash и jq.

# pip install requests
import os
import time
import requests

API = "https://YOUR_API_HOST/api/open/v1"
headers = {"Authorization": "Bearer " + os.environ["MINERU_API_KEY"]}
with open("paper.pdf", "rb") as source:
    response = requests.post(API + "/tasks", headers=headers, files={"file": ("paper.pdf", source, "application/pdf")},
        data={"force_ocr": "true", "extra_formats": '["docx","html"]'}, timeout=120)
response.raise_for_status()
body = response.json()
if body["code"] != 0:
    raise RuntimeError(body["code"] + ": " + body["msg"])
task_id = body["data"]["task_id"]

deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    response = requests.get(API + "/tasks/" + task_id, headers=headers, timeout=30)
    response.raise_for_status()
    body = response.json()
    if body["code"] != 0:
        raise RuntimeError(body["code"] + ": " + body["msg"])
    data = body["data"]
    task = data["task"]
    if task["status"] == "completed":
        url = data["results"].get("full_zip_url")
        if not url:
            raise RuntimeError("ZIP unavailable; check expires_at")
        # Download separately: do not send the API key to the download host.
        with requests.get(url, stream=True, timeout=120) as download:
            download.raise_for_status()
            with open("result.zip", "wb") as output:
                for chunk in download.iter_content(1024 * 1024):
                    output.write(chunk)
        print("Saved result.zip")
        break
    if task["status"] in {"failed", "expired"}:
        raise RuntimeError(task["status"] + ": " + task["error"])
    time.sleep(3)
else:
    raise TimeoutError("Polling timed out; task ID: " + task_id)

Создать задачу

Одна конечная точка: POST /api/open/v1/tasks. Выберите один метод ввода: загрузите файл с помощью multipart/form-data или отправьте source_url с помощью JSON. Оба возвращают data.task_id для одного и того же потока запроса задачи. Каждая принятая отправка создает новую задачу.

Химический режим принимает только PDF и изображения. force_ocr и extra_formats недоступны.

curl --fail-with-body "https://YOUR_API_HOST/api/open/v1/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -F '[email protected]' \
  -F 'force_ocr=true' \
  -F 'extra_formats=["docx","html"]'

{
  "code": 0,
  "data": {
    "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436"
  },
  "msg": "ok"
}

curl --fail-with-body "https://YOUR_API_HOST/api/open/v1/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"source_url":"https://example.com/paper.pdf","force_ocr":true,"extra_formats":["docx","html"]}'

{
  "code": 0,
  "data": {
    "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436"
  },
  "msg": "ok"
}

curl --fail-with-body "https://YOUR_API_HOST/api/open/v1/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -F '[email protected]' \
  -F 'parse_type=1'

Список задач

Перечисляет ваши веб-задачи и API вместе, сначала самые новые. Элементы содержат только task_id, status, credits, created_at, а также имя файла, его размер, mime_type и source_type. Подробности запроса для метаданных файла, причины сбоя, срока действия и URL-адресов результатов. page_size принимает 1–100; недопустимые значения по умолчанию — 20., страница ниже 1 — по умолчанию 1.

Параметры запроса

curl --fail-with-body "https://YOUR_API_HOST/api/open/v1/tasks?page=1&page_size=20" \
  -H "Authorization: Bearer $API_KEY"

Поля ответа · 200 OK

{
  "code": 0,
  "msg": "ok",
  "data": {
    "items": [
      {
        "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436",
        "parse_type": 0,
        "status": "completed",
        "credits": 2,
        "created_at": "2026-10-12T07:04:05Z",
        "file": {
          "name": "paper.pdf",
          "size": 12345,
          "mime_type": "application/pdf",
          "source_type": "upload"
        }
      }
    ],
    "has_more": false,
    "page": 1,
    "page_size": 20
  }
}

TaskSummary

Получить результаты задачи

Прочитайте data.task.status. results всегда является словарем: пустым для queued, running, failed или expired и содержит URL-адреса документов, если completed. URL-адрес ZIP — results.full_zip_url. Невыполненные задачи возвращают HTTP 200 с code task_failed и причиной в msg; expired results используйте code result_expired.

Параметры пути

curl --fail-with-body "https://YOUR_API_HOST/api/open/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

Поля ответа · 200 OK

{
  "code": 0,
  "msg": "ok",
  "data": {
    "task": {
      "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436",
      "parse_type": 0,
      "status": "running",
      "credits": 2,
      "force_ocr": true,
      "expires_at": "2026-10-19T07:04:05Z",
      "error": "",
      "created_at": "2026-10-12T07:04:05Z"
    },
    "file": {
      "name": "paper.pdf",
      "size": 12345,
      "mime_type": "application/pdf",
      "suffix": "pdf",
      "source_type": "upload",
      "source_url": ""
    },
    "results": {}
  }
}

{
  "code": 0,
  "msg": "ok",
  "data": {
    "task": {
      "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436",
      "parse_type": 0,
      "status": "completed",
      "credits": 2,
      "force_ocr": true,
      "expires_at": "2026-10-19T07:04:05Z",
      "error": "",
      "created_at": "2026-10-12T07:04:05Z"
    },
    "file": {
      "name": "paper.pdf",
      "size": 12345,
      "mime_type": "application/pdf",
      "suffix": "pdf",
      "source_type": "upload",
      "source_url": ""
    },
    "results": {
      "original_url": "https://downloads.example.com/uploads/4001a517-cd93-47a6-a56a-e53d2a0828df/aa0e6ab6-44f3-4554-b459-b62fe4c6b437.pdf?token=SIGNED_TOKEN",
      "markdown_url": "https://downloads.example.com/results/a90e6ab6-44f3-4554-b459-b62fe4c6b436/preview/markdown.md?token=SIGNED_TOKEN",
      "middle_json_url": "https://downloads.example.com/results/a90e6ab6-44f3-4554-b459-b62fe4c6b436/preview/middle_json.json?token=SIGNED_TOKEN",
      "structured_json_url": "https://downloads.example.com/results/a90e6ab6-44f3-4554-b459-b62fe4c6b436/preview/structured_content.json?token=SIGNED_TOKEN",
      "images": {
        "images/001.jpg": "https://downloads.example.com/results/a90e6ab6-44f3-4554-b459-b62fe4c6b436/preview/images/001.jpg?token=SIGNED_TOKEN"
      },
      "full_zip_url": "https://downloads.example.com/results/a90e6ab6-44f3-4554-b459-b62fe4c6b436/exports/6b0e6ab6-44f3-4554-b459-b62fe4c6b439.zip?token=SIGNED_TOKEN"
    }
  }
}

{
  "code": "task_failed",
  "msg": "MinerU job ended: failed",
  "data": {
    "task": {
      "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436",
      "parse_type": 0,
      "status": "failed",
      "credits": 2,
      "force_ocr": true,
      "expires_at": "2026-10-19T07:04:05Z",
      "error": "MinerU job ended: failed",
      "created_at": "2026-10-12T07:04:05Z"
    },
    "file": {
      "name": "paper.pdf",
      "size": 12345,
      "mime_type": "application/pdf",
      "suffix": "pdf",
      "source_type": "upload",
      "source_url": ""
    },
    "results": {}
  }
}

{
  "code": 0,
  "msg": "ok",
  "data": {
    "task": {
      "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436",
      "parse_type": 1,
      "status": "completed",
      "credits": 2,
      "force_ocr": false,
      "expires_at": "2026-10-19T07:04:05Z",
      "error": "",
      "created_at": "2026-10-12T07:04:05Z"
    },
    "file": {
      "name": "paper.pdf",
      "size": 12345,
      "mime_type": "application/pdf",
      "suffix": "pdf",
      "source_type": "upload",
      "source_url": ""
    },
    "results": {
      "original_url": "https://downloads.example.com/uploads/4001a517-cd93-47a6-a56a-e53d2a0828df/aa0e6ab6-44f3-4554-b459-b62fe4c6b437.pdf?token=SIGNED_TOKEN",
      "json_url": "https://downloads.example.com/results/a90e6ab6-44f3-4554-b459-b62fe4c6b436/molecular_structures.json?token=SIGNED_TOKEN"
    }
  }
}

Task

File

results

Форматы и ограничения

Ограничения Pro: 200 MiB на документ, 50 MiB на изображение и 500 расчётных единиц. API и сайт используют общий лимит: 5 единиц в день и 1000 в месяц; сначала расходуются дневные единицы. Квота резервируется после проверки и списывается после сохранения базового результата разбора. Подтверждённый сбой или остановка разбора освобождает резерв. Ошибка публикации или экспорта не возвращает квоту за успешный разбор. При сбое выполнения или превышении времени ожидания ещё не списанный резерв освобождается автоматически. Экспорт не расходует квоту повторно.

Формат загрузки определяется расширением имени файла без учета регистра. PDF, PowerPoint и Excel должны иметь читаемые метаданные страницы /unit. MIME не используется для проверки загруженного содержимого. Пустые файлы, неподдерживаемые расширения, зашифрованные или нечитаемые PDF-файлы, а также входные данные, превышающие лимит, отклоняются. Анализ HTML является статическим и не запускает JavaScript. 1 MiB = 1,048,576 байт.

Состояния задач

Продолжайте опрос queued или running. Скачать на completed; прочитайте error и остановитесь на failed. expired означает, что хранение закончилось. status описывает всю задачу; Задачи API завершаются только тогда, когда готов последний ZIP.

Результаты в ZIP и скачивание

API производит один последний ZIP. Markdown, средний JSON, структурированный JSON и сохраненные изображения включены по умолчанию. extra_formats поддерживает только html, docx и latex; запрошенные файлы добавляются в тот самый ZIP. Не создавайте отдельное задание веб-экспорта для задачи API. Отсутствие дополнений означает, что results.full_zip_url указывает на base.zip; дополнительные означают, что он указывает на файл Exports/a ZIP.

Химические задачи возвращают results.original_url и results.json_url, без ZIP и других форматов экспорта.

Результат — массив JSON со всеми исходными полями MolParser для каждой молекулы. Если молекул нет, возвращается [].

source, input_index, page_index, bbox, confidence, raw_caption, caption, smi, esmi, cxsmiles, markush, sru, groups

result.zip
├── markdown.md
├── middle_json.json
├── structured_content.json
├── images/
│   └── …
├── model_output.json       (optional)
├── result.html             (extra_formats: html)
├── result.docx             (extra_formats: docx)
└── result.tex              (extra_formats: latex)

Результаты хранятся 7 дней. results.full_zip_url подписывается максимум на 15 минут и никогда не превышает срока хранения. Загрузите с помощью простого GET, без Authorization. Если срок действия подписи истекает, но она все еще сохраняется, запросите сведения еще раз для нового URL-адреса. Ссылки на изображения для предварительного просмотра действуют не более 2 часов; другие ссылки на файлы длятся не более 15 минут.

Документы ZIP сохраняют собственные относительные ссылки на изображения и включают сохраненные изображения, поэтому эти ссылки не зависят от подписей CDN. Извлеките весь архив и сохраните его структуру папок. Удаленные изображения, на которые ссылается ввод HTML, не архивируются автоматически и могут по-прежнему указывать на исходный веб-сайт.

Ошибки и восстановление

code 0 означает успех. Другой code обозначает категорию ошибки, а msg содержит причину. Запросы неудачных задач или задач с истёкшим сроком хранения возвращают HTTP 200 с task_failed или result_expired и пустым объектом results.

{
  "code": "quota_exceeded",
  "data": null,
  "msg": "not enough available pages/units"
}