Documentation de l’API PaddleOCR — analyse vers Markdown et JSON

Aperçu

Créez une tâche par fichier ou URL, interrogez son status, puis téléchargez le ZIP. Les demandes sont asynchrones. Pro Monthly et Pro Annual prennent en charge le API ; Ce n’est pas le cas de la gratuité.

https://YOUR_API_HOST/api/open/v1

Remplacez YOUR_API_HOST par votre domaine API. Tous les chemins ci-dessous utilisent cette URL de base. Les exemples utilisent des ID d'espace réservé et des URL signées.

Authentification

Envoyez Authorization : Bearer suivi de votre clé Pro API à chaque demande API. Obtenez ou réinitialisez la clé à l’aide du bouton clé API. Les clés sont sensibles à la casse : sk- plus 24 lettres et chiffres aléatoires. Les JWT de connexion utilisateur n'authentifient pas ces points de terminaison.

Authorization: Bearer sk-YOUR_API_KEY

Conservez la clé sur votre serveur. Ne l'exposez pas dans l'interface publique code, dans les référentiels ou dans les demandes de téléchargement. Les téléchargements utilisent leur propre URL signée. La réinitialisation de la clé invalide immédiatement l'ancienne clé ; L’accès API nécessite également un abonnement Pro actif.

Démarrage rapide

Remplacez l'hôte API, définissez MINERU_API_KEY et fournissez paper.pdf. Ces exemples sont téléchargés une fois, interrogés toutes les 3 secondes pendant 30 minutes maximum, puis diffusent les ZIP sur le disque. Le délai d'attente d'interrogation est une limite client et n'annule pas la tâche serveur. Utilisez l'ID de tâche pour continuer l'interrogation. Python nécessite le paquet requests ; Node.js nécessite la version 20+ ; cURL utilise Bash et 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)

Créer une tâche

Un point de terminaison : POST /api/open/v1/tasks. Choisissez une méthode de saisie : téléchargez un fichier en utilisant multipart/form-data ou envoyez source_url en utilisant JSON. Les deux renvoient data.task_id pour le même flux de requête de tâche. Chaque soumission acceptée crée une nouvelle tâche.

Le mode chimique accepte uniquement les PDF et images. force_ocr et extra_formats ne sont pas disponibles.

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'

Liste des tâches

Répertorie vos tâches Web et API ensemble, la plus récente en premier. Les éléments contiennent uniquement task_id, status, credits, created_at et le nom du fichier, sa taille, mime_type et source_type. Détails de la requête pour les métadonnées du fichier, le motif de l'échec, l'expiration et les URL de résultat. page_size accepte 1–100 ; valeurs non valides par défaut à 20. page ci-dessous 1 par défaut à 1.

Paramètres de requête

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

Champs de réponse · 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

Obtenir la tâche results

Lisez data.task.status. results est toujours un dictionnaire : vide pour queued, running, failed ou expired, et contient les URL des documents lorsque completed. L'URL ZIP est results.full_zip_url. Les tâches ayant échoué renvoient HTTP 200 avec code task_failed et la raison en msg ; expired results utilisez code result_expired.

Paramètres du chemin

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

Champs de réponse · 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

Formats et limites

Limites Pro : 200 MiB par document, 50 MiB par image et 500 unités facturables. API et partagez sur le Web 5 quotidiennement plus 1,000 unités mensuelles, en utilisant d'abord les unités quotidiennes. L'utilisation est réservée après validation et facturée lorsque le résultat de l'analyse de base est enregistré. L’échec ou la résiliation confirmé de l’analyse libère les réservations. L’échec de la publication/export ne rembourse pas l’analyse réussie ; failed ou une exécution expirée libère automatiquement les réservations non facturées. Les exportations ne sont plus facturées.

Le format de téléchargement est déterminé par l'extension du nom de fichier, sans tenir compte de la casse. PDF, PowerPoint et Excel doivent avoir des métadonnées de page/unit lisibles. MIME n'est pas utilisé pour valider le contenu téléchargé. Les fichiers vides, les extensions non prises en charge, les PDF cryptés ou illisibles et les entrées dépassant la limite sont rejetés. L'analyse HTML est statique et n'exécute pas JavaScript. 1 MiB = 1,048,576 octets.

États des tâches

Continuez à interroger queued ou running. Télécharger le completed ; lisez error et arrêtez-vous sur failed. expired signifie que la rétention est terminée. status décrit l'ensemble de la tâche ; Les tâches API ne sont terminées que lorsque le ZIP final est prêt.

ZIP results et téléchargements

Le API produit un ZIP final. Markdown, Middle JSON, structuré JSON et les images enregistrées sont incluses par défaut. extra_formats prend en charge html, docx et latex uniquement ; les fichiers demandés sont ajoutés à ce même ZIP. Ne créez pas de tâche d'exportation Web distincte pour une tâche API. Aucun extra signifie results.full_zip_url points à base.zip ; les extras signifient qu'il pointe vers le fichier exports/a ZIP.

Les tâches chimiques renvoient results.original_url et results.json_url, sans ZIP ni autres formats d’export.

Le résultat chimique est un tableau JSON conservant tous les champs natifs MolParser pour chaque molécule. Sans molécule, il vaut [].

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)

Les résultats sont conservés pendant 7 jours. results.full_zip_url est signé pour une durée maximale de 15 minutes et jamais au-delà de la durée de conservation. Téléchargez avec un simple GET, sans Authorization. Si la signature expire alors qu'elle est encore conservée, interrogez à nouveau les détails pour obtenir une nouvelle URL. Les liens d’image d’aperçu durent au maximum 2 heures ; les autres liens de fichiers durent au maximum 15 minutes.

Les documents ZIP conservent les références d'images relatives natives et incluent les images enregistrées, de sorte que ces références ne dépendent pas des signatures CDN. Extrayez l’intégralité de l’archive et conservez sa structure de dossiers. Les images distantes référencées par l'entrée HTML ne sont pas automatiquement archivées et peuvent toujours pointer vers le site Web source.

Erreurs et récupération

code 0 indique un succès. Un code non nul identifie la catégorie d’erreur ; msg en explique la raison. Les tâches échouées ou expirées renvoient HTTP 200 avec task_failed ou result_expired et un objet results vide.

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