PaddleOCR API-documentatie — parseren naar Markdown en JSON

Overzicht

Maak één taak per bestand of URL, poll de status ervan en download vervolgens de ZIP. Verzoeken zijn asynchroon. Pro Monthly en Pro Annual ondersteunen de API; Gratis niet.

https://YOUR_API_HOST/api/open/v1

Vervang YOUR_API_HOST door uw API domein. Alle onderstaande paden gebruiken deze basis-URL. In de voorbeelden worden tijdelijke ID's en ondertekende URL's gebruikt.

Authenticatie

Verzend Authorization: Bearer gevolgd door uw Pro API-sleutel bij elk API-verzoek. Haal de sleutel op of reset deze met de sleutelknop API. Sleutels zijn hoofdlettergevoelig: sk- plus 24 willekeurige letters en cijfers. JWT's voor gebruikersaanmelding verifiëren deze eindpunten niet.

Authorization: Bearer sk-YOUR_API_KEY

Bewaar de sleutel op uw server. Stel het niet bloot in openbare frontend code, repository's of downloadverzoeken. Downloads gebruiken hun eigen ondertekende URL. Door het resetten van de sleutel wordt de oude sleutel onmiddellijk ongeldig; Voor API toegang is ook een actief Pro-lidmaatschap vereist.

Snelle start

Vervang de API host, stel MINERU_API_KEY in en geef paper.pdf op. Deze voorbeelden worden één keer geüpload, elke 3 seconden gepolst gedurende maximaal 30 minuten, en streamen vervolgens de ZIP naar schijf. De polling-time-out is een clientlimiet en annuleert de servertaak niet. Gebruik de taak-ID om door te gaan met het opvragen. Python vereist het pakket requests; Node.js heeft versie 20+ nodig; cURL gebruikt Bash en 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)

Maak een taak aan

Eén eindpunt: POST /api/open/v1/tasks. Kies één invoermethode: upload een bestand met multipart/form-data, of verzend source_url met JSON. Beide retourneren data.task_id voor dezelfde taakquerystroom. Elke geaccepteerde inzending creëert een nieuwe taak.

De chemische modus accepteert alleen PDF’s en afbeeldingen. force_ocr en extra_formats zijn niet beschikbaar.

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'

Lijst met taken

Geeft uw web- en API-taken samen weer, de nieuwste eerst. Items bevatten alleen task_id, status, credits, created_at en bestandsnaam, grootte, mime_type en source_type. Querydetails voor bestandsmetadata, foutreden, vervaldatum en resultaat-URL's. page_size accepteert 1–100; ongeldige waarden zijn standaard 20. pagina hieronder 1 standaard 1.

Queryparameters

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

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

Taak results ophalen

Lees data.task.status. results is altijd een woordenboek: leeg voor queued, running, failed of expired, en bevat document-URL's als completed. De ZIP-URL is results.full_zip_url. Mislukte taken retourneren HTTP 200 met code task_failed en de reden in msg; expired results gebruik code result_expired.

Padparameters

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

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

Formaten en limieten

Pro-limieten: 200 MiB per document, 50 MiB per afbeelding en 500 factureerbare eenheden. API en webshare 5 dagelijks plus 1,000 maandelijkse eenheden, waarbij eerst de dagelijkse eenheden worden gebruikt. Het gebruik wordt gereserveerd na validatie en in rekening gebracht wanneer het basisparseresultaat wordt opgeslagen. Bij een bevestigde parseerfout of beëindiging worden reserveringen vrijgegeven. Een publicatie/export-fout geeft geen restitutie voor succesvol paren; Bij failed of een time-outuitvoering worden niet-gefactureerde reserveringen automatisch vrijgegeven. Bij export worden geen kosten in rekening gebracht.

Het uploadformaat wordt bepaald door de bestandsnaamextensie, hoofdletterongevoelig. PDF, PowerPoint en Excel moeten leesbare pagina/unit-metagegevens hebben. MIME wordt niet gebruikt om geüploade inhoud te valideren. Lege bestanden, niet-ondersteunde extensies, gecodeerde of onleesbare PDF's en invoerlimieten worden afgewezen. HTML parseren is statisch en er wordt geen JavaScript uitgevoerd. 1 MiB = 1,048,576 bytes.

Taakstatussen

Blijf pollen queued of running. Downloaden op completed; lees error en stop bij failed. expired betekent dat de bewaring is beëindigd. status beschrijft de hele taak; API taken zijn pas voltooid als de laatste ZIP klaar is.

ZIP results en downloads

De API produceert één laatste ZIP. Markdown, Midden JSON, gestructureerde JSON en opgeslagen afbeeldingen zijn standaard inbegrepen. extra_formats ondersteunt alleen html, docx en latex; de gevraagde bestanden worden toegevoegd aan diezelfde ZIP. Maak geen afzonderlijke webexporttaak voor een API-taak. Geen extra's betekent dat results.full_zip_url verwijst naar base.zip; extra's betekenen dat het verwijst naar het exports/a ZIP bestand.

Chemische taken leveren results.original_url en results.json_url, zonder ZIP of andere exportformaten.

Chemische resultaten zijn een JSON-array met alle oorspronkelijke MolParser-velden per molecuul. Zonder moleculen wordt [] geretourneerd.

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)

Resultaten worden 7 dagen bewaard. results.full_zip_url wordt voor maximaal 15 minuten ondertekend en nooit langer bewaard. Download met een gewone GET, zonder Authorization. Als de handtekening verloopt terwijl deze nog steeds behouden is, vraagt ​​u de details opnieuw op voor een nieuwe URL. Links naar voorbeeldafbeeldingen duren maximaal 2 uur; andere bestandslinks duren maximaal 15 minuten.

ZIP documenten behouden de oorspronkelijke relatieve afbeeldingsreferenties en bevatten opgeslagen afbeeldingen, zodat deze referenties niet afhankelijk zijn van CDN handtekeningen. Pak het hele archief uit en behoud de mappenstructuur. Afbeeldingen op afstand waarnaar wordt verwezen door HTML-invoer, worden niet automatisch gearchiveerd en verwijzen mogelijk nog steeds naar de bronwebsite.

Fouten en herstel

code 0 betekent succes. Een andere code geeft de foutcategorie aan; msg geeft de reden. Opvragen van mislukte of verlopen taken retourneert HTTP 200 met task_failed of result_expired en een leeg results-object.

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