Dokumentacja API PaddleOCR — analiza dokumentów do Markdown i JSON

Przegląd

Utwórz jedno zadanie na plik lub adres URL, odpytuj jego status, a następnie pobierz ZIP. Żądania są asynchroniczne. Pro Monthly i Pro Annual obsługują API; Bezpłatne nie.

https://YOUR_API_HOST/api/open/v1

Zamień YOUR_API_HOST na swoją domenę API. Wszystkie poniższe ścieżki korzystają z tego podstawowego adresu URL. W przykładach używane są identyfikatory zastępcze i podpisane adresy URL.

Uwierzytelnianie

Wyślij Authorization: Bearer, a następnie swój klucz Pro API przy każdym żądaniu API. Uzyskaj lub zresetuj klucz za pomocą przycisku klucza API. W kluczach rozróżniana jest wielkość liter: sk- plus 24 losowe litery i cyfry. Tokeny JWT logowania użytkownika nie uwierzytelniają tych punktów końcowych.

Authorization: Bearer sk-YOUR_API_KEY

Zachowaj klucz na swoim serwerze. Nie ujawniaj go w publicznym interfejsie code, repozytoriach ani żądaniach pobrania. Pobieranie korzysta z własnego podpisanego adresu URL. Zresetowanie klucza natychmiast unieważnia stary klucz; Dostęp API wymaga również aktywnego członkostwa Pro.

Szybki start

Zastąp hosta API, ustaw MINERU_API_KEY i podaj paper.pdf. Te przykłady przesyłane są raz, odpytują co 3 sekundy przez maksymalnie 30 minut, a następnie przesyłają strumieniowo ZIP na dysk. Limit czasu odpytywania jest limitem klienta i nie powoduje anulowania zadania serwera. Użyj identyfikatora zadania, aby kontynuować wykonywanie zapytań. Python wymaga pakietu requests; Node.js potrzebuje wersji 20+; cURL używa Bash i 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)

Utwórz zadanie

Jeden punkt końcowy: POST /api/open/v1/tasks. Wybierz jedną metodę wprowadzania: prześlij plik za pomocą wieloczęściowego/form-data lub wyślij source_url za pomocą JSON. Obydwa zwracają data.task_id dla tego samego przepływu zapytania dotyczącego zadania. Każde zaakceptowane zgłoszenie tworzy nowe zadanie.

Tryb chemiczny obsługuje tylko PDF i obrazy. force_ocr i extra_formats są niedostępne.

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'

Lista zadań

Wyświetla listę zadań internetowych i API, zaczynając od najnowszych. Elementy zawierają tylko task_id, status, credits, created_at oraz nazwę pliku, rozmiar, mime_type i source_type. Zapytaj o szczegóły dotyczące metadanych pliku, przyczyny niepowodzenia, adresu URL wygaśnięcia i wyniku. page_size akceptuje 1–100; nieprawidłowe wartości domyślnie 20. strona poniżej 1 domyślnie 1.

Parametry zapytania

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

Pola odpowiedzi · 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

Pobierz zadanie results

Przeczytaj data.task.status. results jest zawsze słownikiem: pusty dla queued, running, failed lub expired i zawiera adresy URL dokumentów, gdy completed. Adres URL ZIP to results.full_zip_url. Zadania zakończone niepowodzeniem zwracają HTTP 200 z code task_failed i przyczyną w msg; expired results użyj code result_expired.

Parametry ścieżki

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

Pola odpowiedzi · 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

Formaty i ograniczenia

Limity Pro: 200 MiB na dokument, 50 MiB na obraz i 500 jednostek płatnych. API i udział sieciowy 5 dziennie plus 1,000 jednostek miesięcznych, używając najpierw jednostek dziennych. Użycie jest rezerwowane po sprawdzeniu poprawności i naliczane w momencie zapisania wyniku analizy podstawowej. Potwierdzony błąd analizy lub zakończenie zwalnia rezerwacje. Błąd publikacji/export nie zwraca pomyślnej analizy; failed lub przekroczenie limitu czasu powoduje automatyczne zwolnienie nieobciążonych rezerwacji. Eksport nie jest ponownie naliczany.

Format przesyłania jest określany na podstawie rozszerzenia nazwy pliku, bez uwzględniania wielkości liter. PDF, PowerPoint i Excel muszą mieć czytelne metadane page/unit. MIME nie jest używany do sprawdzania przesłanych treści. Puste pliki, nieobsługiwane rozszerzenia, zaszyfrowane lub nieczytelne pliki PDF oraz dane wejściowe przekraczające limit są odrzucane. Analiza HTML jest statyczna i nie uruchamia JavaScript. 1 MiB = 1,048,576 bajtów.

Stany zadań

Kontynuuj odpytywanie queued lub running. Pobierz na completed; przeczytaj error i zatrzymaj się na failed. expired oznacza, że ​​przechowywanie zostało zakończone. status opisuje całe zadanie; Zadania API są kończone dopiero wtedy, gdy gotowe jest ostatnie ZIP.

ZIP results i pliki do pobrania

API tworzy jeden końcowy ZIP. Domyślnie uwzględniane są obrazy Markdown, średnie JSON, strukturyzowane JSON i zapisane obrazy. extra_formats obsługuje tylko html, docx i latex; żądane pliki są dodawane do tego samego ZIP. Nie twórz osobnego zadania eksportu internetowego dla zadania API. Brak dodatków oznacza, że ​​results.full_zip_url wskazuje na base.zip; dodatki oznaczają, że wskazuje plik eksportu/a ZIP.

Zadania chemiczne zwracają results.original_url i results.json_url, bez ZIP i dodatkowych formatów eksportu.

Wynik chemiczny to tablica JSON zawierająca wszystkie natywne pola MolParser dla każdej cząsteczki. Bez cząsteczek zwraca [].

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)

Wyniki są przechowywane przez 7 dni. results.full_zip_url jest podpisywany na maksymalnie 15 minut i nigdy nie dłużej niż okres przechowywania. Pobierz za pomocą zwykłego GET, bez Authorization. Jeśli podpis wygaśnie, mimo że jest nadal zachowany, ponownie zapytaj o szczegóły, aby uzyskać nowy adres URL. Linki do obrazów podglądu trwają maksymalnie 2 godzin; inne łącza do plików trwają maksymalnie 15 minut.

Dokumenty ZIP zawierają natywne odniesienia do obrazów względnych i zawierają zapisane obrazy, więc odniesienia te nie zależą od podpisów CDN. Wyodrębnij całe archiwum i zachowaj strukturę folderów. Zdalne obrazy, do których odwołują się dane wejściowe HTML, nie są automatycznie archiwizowane i nadal mogą wskazywać źródłową witrynę internetową.

Błędy i odzyskiwanie

code 0 oznacza sukces. Inny code określa kategorię błędu, a msg podaje przyczynę. Zapytania o zadania nieudane lub wygasłe zwracają HTTP 200 z task_failed lub result_expired i pustym obiektem results.

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