Документация PaddleOCR 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

Получить задание results

Прочитайте 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 ежедневных единиц плюс 1,000 ежемесячных единиц, используя сначала дневные единицы. Использование резервируется после проверки и взимается при сохранении результата базового анализа. Подтвержденный сбой синтаксического анализа или его завершение освобождают резервирования. Ошибка публикации/export не возвращает деньги за успешный синтаксический анализ; failed или выполнение по истечении времени ожидания автоматически освобождает неоплаченные резервирования. Экспорт снова не взимается.

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

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

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

ZIP results и загрузки

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"
}