Documentazione API PaddleOCR — analisi in Markdown e JSON

Panoramica

Crea un'attività per file o URL, esegui il poll su status, quindi scarica ZIP. Le richieste sono asincrone. Pro mensile e Pro annuale supportano API; La libertà no.

https://YOUR_API_HOST/api/open/v1

Sostituisci YOUR_API_HOST con il tuo dominio API. Tutti i percorsi seguenti utilizzano questo URL di base. Negli esempi vengono utilizzati ID segnaposto e URL firmati.

Autenticazione

Invia Authorization: Bearer seguito dalla tua chiave Pro API su ogni richiesta API. Ottieni o reimposta la chiave utilizzando il pulsante della chiave API. I tasti fanno distinzione tra maiuscole e minuscole: sk- più 24 lettere e cifre casuali. I JWT di accesso utente non autenticano questi endpoint.

Authorization: Bearer sk-YOUR_API_KEY

Conserva la chiave sul tuo server. Non esporlo nel frontend pubblico code, nei repository o nelle richieste di download. I download utilizzano il proprio URL firmato. Il ripristino della chiave invalida immediatamente la vecchia chiave; L'accesso API richiede anche un abbonamento Pro attivo.

Avvio rapido

Sostituisci l'host API, imposta MINERU_API_KEY e fornisci paper.pdf. Questi esempi vengono caricati una volta, eseguono il polling ogni 3 secondi per un massimo di 30 minuti, quindi eseguono lo streaming di ZIP su disco. Il timeout del polling è un limite del client e non annulla l'attività del server. Utilizza l'ID attività per continuare a eseguire query. Python richiede il pacchetto requests; Node.js necessita della versione 20+; cURL utilizza Bash e 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)

Crea un'attività

Un endpoint: POST /api/open/v1/tasks. Scegli un metodo di input: carica un file utilizzando multipart/form-data o invia source_url utilizzando JSON. Entrambi restituiscono data.task_id per lo stesso flusso di query dell'attività. Ogni invio accettato crea una nuova attività.

La modalità chimica accetta solo PDF e immagini. force_ocr ed extra_formats non sono disponibili.

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'

Elenca attività

Elenca insieme le tue attività web e API, iniziando dalla più recente. Gli elementi contengono solo task_id, status, credits, created_at e nome file, dimensione, mime_type e source_type. Dettagli della query per metadati del file, motivo dell'errore, scadenza e URL dei risultati. page_size accetta 1–100; valori non validi il valore predefinito è 20. la pagina sotto 1 il valore predefinito è 1.

Parametri di query

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

Campi di risposta · 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

Ottieni attività results

Leggi data.task.status. results è sempre un dizionario: vuoto per queued, running, failed o expired e contiene gli URL dei documenti quando completed. L'URL ZIP è results.full_zip_url. Le attività non riuscite restituiscono HTTP 200 con code task_failed e il motivo in msg; expired results usa code result_expired.

Parametri del percorso

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

Campi di risposta · 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

Formati e limiti

Limiti Pro: 200 MiB per documento, 50 MiB per immagine e 500 unità fatturabili. API e condividi sul web 5 al giorno più 1,000 unità mensili, utilizzando prima le unità giornaliere. L'utilizzo viene riservato dopo la convalida e addebitato quando il risultato dell'analisi di base viene salvato. L'errore di analisi confermato o la terminazione rilasciano prenotazioni. L'errore Publication/export non rimborsa l'analisi riuscita; failed o l'esecuzione scaduta rilascia automaticamente le prenotazioni non addebitate. Le esportazioni non verranno addebitate nuovamente.

Il formato di caricamento è determinato dall'estensione del nome file, senza distinzione tra maiuscole e minuscole. PDF, PowerPoint e Excel devono avere metadati della pagina/unit leggibili. MIME non viene utilizzato per convalidare i contenuti caricati. File vuoti, estensioni non supportate, PDF crittografati o illeggibili e input superiori al limite vengono rifiutati. L'analisi HTML è statica e non esegue JavaScript. 1 MiB = 1,048,576 byte.

Stati delle attività

Continua a interrogare queued o running. Scarica su completed; leggi error e fermati su failed. expired significa che la conservazione è terminata. status descrive l'intera attività; Le attività API vengono completate solo quando la ZIP finale è pronta.

ZIP results e download

API produce un ZIP finale. Markdown, Medio JSON, strutturato JSON e le immagini salvate sono incluse per impostazione predefinita. extra_formats supporta solo html, docx e latex; i file richiesti vengono aggiunti allo stesso ZIP. Non creare un processo di esportazione Web separato per un'attività API. Nessun extra significa che results.full_zip_url punta a base.zip; gli extra indicano che punta al file exports/a ZIP.

Le attività chimiche restituiscono results.original_url e results.json_url, senza ZIP né esportazioni aggiuntive.

Il risultato chimico è un array JSON con tutti i campi nativi MolParser per molecola. In assenza di molecole restituisce [].

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)

I risultati vengono conservati per 7 giorni. results.full_zip_url è firmato per un massimo di 15 minuti e mai oltre la conservazione. Scarica con un semplice GET, senza Authorization. Se la firma scade mentre è ancora conservata, richiedere nuovamente i dettagli per un nuovo URL. I collegamenti alle immagini di anteprima durano al massimo 2 ore; altri collegamenti a file durano al massimo 15 minuti.

I documenti ZIP mantengono i riferimenti alle immagini relative native e includono le immagini salvate, quindi tali riferimenti non dipendono dalle firme CDN. Estrai l'intero archivio e mantieni la struttura delle cartelle. Le immagini remote a cui fa riferimento l'input HTML non vengono archiviate automaticamente e potrebbero comunque puntare al sito Web di origine.

Errori e ripristino

code 0 indica successo. Un code diverso da zero identifica la categoria di errore; msg ne spiega il motivo. Le attività non riuscite o scadute restituiscono HTTP 200 con task_failed o result_expired e un oggetto results vuoto.

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