PaddleOCR API-Dokumentation – Dokumentenanalyse für Markdown & JSON

Übersicht

Erstellen Sie eine Aufgabe pro Datei oder URL, fragen Sie deren status ab und laden Sie dann die ZIP herunter. Anfragen sind asynchron. Pro Monthly und Pro Annual unterstützen den API; Kostenlos nicht.

https://YOUR_API_HOST/api/open/v1

Ersetzen Sie YOUR_API_HOST durch Ihre API-Domäne. Alle unten aufgeführten Pfade verwenden diese Basis-URL. Die Beispiele verwenden Platzhalter-IDs und signierte URLs.

Authentifizierung

Senden Sie bei jeder API-Anfrage Authorization: Bearer gefolgt von Ihrem Pro API-Schlüssel. Holen Sie sich den Schlüssel mit der Schlüsseltaste API oder setzen Sie ihn zurück. Bei den Schlüsseln wird die Groß-/Kleinschreibung beachtet: sk- plus 24 zufällige Buchstaben und Ziffern. Benutzeranmeldungs-JWTs authentifizieren diese Endpunkte nicht.

Authorization: Bearer sk-YOUR_API_KEY

Bewahren Sie den Schlüssel auf Ihrem Server auf. Stellen Sie es nicht im öffentlichen Frontend code, in Repositorys oder bei Download-Anfragen bereit. Downloads verwenden ihre eigene signierte URL. Durch das Zurücksetzen des Schlüssels wird der alte Schlüssel sofort ungültig. Für den API-Zugriff ist außerdem eine aktive Pro-Mitgliedschaft erforderlich.

Schnellstart

Ersetzen Sie den Host API, legen Sie MINERU_API_KEY fest und stellen Sie paper.pdf bereit. Diese Beispiele werden einmal hochgeladen, alle 3 Sekunden bis zu 30 Minuten abgefragt und dann ZIP auf die Festplatte gestreamt. Das Polling-Timeout ist ein Client-Limit und bricht den Server-Task nicht ab. Verwenden Sie die Aufgaben-ID, um mit der Abfrage fortzufahren. Python benötigt das Paket requests; Node.js benötigt Version 20+; cURL verwendet Bash und 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)

Erstellen Sie eine Aufgabe

Ein Endpunkt: POST /api/open/v1/tasks. Wählen Sie eine Eingabemethode: Laden Sie eine Datei mit multipart/form-data hoch oder senden Sie source_url mit JSON. Beide geben data.task_id für denselben Aufgabenabfragefluss zurück. Jede akzeptierte Einreichung erstellt eine neue Aufgabe.

Chemische Aufgaben akzeptieren nur PDF und Bilder. force_ocr und extra_formats sind nicht verfügbar.

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'

Aufgaben auflisten

Listet Ihre Web- und API-Aufgaben zusammen auf, die neuesten zuerst. Elemente enthalten nur task_id, status, credits, created_at und Dateiname, Größe, mime_type und source_type. Abfragedetails für Dateimetadaten, Fehlergrund, Ablauf und Ergebnis-URLs. page_size akzeptiert 1–100; Ungültige Werte sind standardmäßig 20.. Die Seite darunter ist standardmäßig 1. Standard ist 1..

Parameter abfragen

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

Antwortfelder · 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

Holen Sie sich Aufgabe results

Lesen Sie data.task.status. results ist immer ein Wörterbuch: leer für queued, running, failed oder expired und enthält Dokument-URLs, wenn completed. Die ZIP-URL ist results.full_zip_url. Fehlgeschlagene Aufgaben geben HTTP 200 mit code task_failed und den Grund in msg zurück; expired results verwenden code result_expired.

Pfadparameter

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

Antwortfelder · 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

Formate und Grenzen

Pro-Limits: 200 MiB pro Dokument, 50 MiB pro Bild und 500 abrechenbare Einheiten. API und Web teilen 5 tägliche plus 1,000 monatliche Einheiten, wobei zuerst die täglichen Einheiten verwendet werden. Die Nutzung ist nach der Validierung reserviert und wird berechnet, wenn das Basisanalyseergebnis gespeichert wird. Bestätigter Analysefehler oder Abbruch gibt Reservierungen frei. Bei einem Veröffentlichung/export-Fehler wird die erfolgreiche Analyse nicht rückerstattet; failed oder die Ausführung aufgrund einer Zeitüberschreitung gibt nicht belastete Reservierungen automatisch frei. Für Exporte fallen keine weiteren Gebühren an.

Das Upload-Format wird durch die Dateinamenerweiterung bestimmt, ohne Berücksichtigung der Groß-/Kleinschreibung. PDF, PowerPoint und Excel müssen über lesbare Seiten-/unit-Metadaten verfügen. MIME wird nicht zur Validierung hochgeladener Inhalte verwendet. Leere Dateien, nicht unterstützte Erweiterungen, verschlüsselte oder nicht lesbare PDFs und Eingaben, die das Limit überschreiten, werden abgelehnt. Das Parsen von HTML ist statisch und führt kein JavaScript aus. 1 MiB = 1,048,576 Bytes.

Aufgabenstatus

Rufen Sie weiterhin queued oder running ab. Herunterladen auf completed; Lesen Sie error und hören Sie bei failed auf. expired bedeutet, dass die Aufbewahrung beendet ist. status beschreibt die gesamte Aufgabe; API-Aufgaben werden erst abgeschlossen, wenn die letzten ZIP fertig sind.

ZIP results und Downloads

Das API erzeugt ein letztes ZIP. Markdown, mittlere JSON, strukturierte JSON und gespeicherte Bilder sind standardmäßig enthalten. extra_formats unterstützt nur html, docx und latex; Die angeforderten Dateien werden demselben ZIP hinzugefügt. Erstellen Sie keinen separaten Webexportauftrag für eine API-Aufgabe. Keine Extras bedeutet, dass results.full_zip_url auf base.zip zeigt; Extras bedeuten, dass es auf die Datei exports/a ZIP verweist.

Chemische Aufgaben liefern results.original_url und results.json_url, ohne ZIP und weitere Exportformate.

Chemische Ergebnisse sind ein JSON-Array mit allen nativen MolParser-Feldern je Molekül. Ohne Moleküle wird [] zurückgegeben.

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)

Ergebnisse werden 7 Tage aufbewahrt. results.full_zip_url wird für höchstens 15 Minuten und nie über die Aufbewahrungsfrist hinaus signiert. Mit einem einfachen GET herunterladen, ohne Authorization. Wenn die Signatur abläuft, während sie noch erhalten bleibt, fragen Sie die Details erneut nach einer neuen URL ab. Vorschaubild-Links dauern höchstens 2 Stunden; Andere Dateilinks dauern höchstens 15 Minuten.

ZIP-Dokumente behalten native relative Bildverweise und enthalten gespeicherte Bilder, sodass diese Verweise nicht von CDN-Signaturen abhängen. Extrahieren Sie das gesamte Archiv und behalten Sie die Ordnerstruktur bei. Remote-Bilder, auf die durch die Eingabe HTML verwiesen wird, werden nicht automatisch archiviert und verweisen möglicherweise weiterhin auf die Quellwebsite.

Fehler und Wiederherstellung

code 0 bedeutet Erfolg. Ein anderer code bezeichnet die Fehlerkategorie; msg nennt den Grund. Abfragen fehlgeschlagener oder abgelaufener Aufgaben liefern HTTP 200 mit task_failed oder result_expired und einem leeren results-Objekt.

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