Documentación de la API de PaddleOCR — análisis a Markdown y JSON

Descripción general

Cree una tarea por archivo o URL, sondee su status y luego descargue el ZIP. Las solicitudes son asincrónicas. Pro Monthly y Pro Annual admiten API; Gratis no.

https://YOUR_API_HOST/api/open/v1

Reemplace YOUR_API_HOST con su dominio API. Todas las rutas siguientes utilizan esta URL base. Los ejemplos utilizan ID de marcador de posición y URL firmadas.

Autenticación

Envíe Authorization: Bearer seguido de su clave Pro API en cada solicitud API. Obtenga o restablezca la clave usando el botón de clave API. Las claves distinguen entre mayúsculas y minúsculas: sk- más 24 letras y dígitos aleatorios. Los JWT de inicio de sesión de usuario no autentican estos puntos finales.

Authorization: Bearer sk-YOUR_API_KEY

Mantenga la clave en su servidor. No lo exponga en la interfaz pública code, repositorios o solicitudes de descarga. Las descargas utilizan su propia URL firmada. Restablecer la clave invalida inmediatamente la clave anterior; El acceso API también requiere una membresía Pro activa.

Inicio rápido

Reemplace el host API, configure MINERU_API_KEY y proporcione paper.pdf. Estos ejemplos se cargan una vez, sondean cada 3 segundos durante hasta 30 minutos y luego transmiten el ZIP al disco. El tiempo de espera del sondeo es un límite del cliente y no cancela la tarea del servidor. Utilice el ID de la tarea para continuar con la consulta. Python requiere el paquete requests; Node.js necesita la versión 20+; cURL usa Bash y 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)

Crear una tarea

Un punto final: POST /api/open/v1/tasks. Elija un método de entrada: cargue un archivo usando multipart/form-data o envíe source_url usando JSON. Ambos devuelven data.task_id para el mismo flujo de consulta de tareas. Cada envío aceptado crea una nueva tarea.

El modo químico solo acepta PDF e imágenes. No admite force_ocr ni extra_formats.

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'

Listar tareas

Enumera sus tareas web y API juntas, las más nuevas primero. Los elementos contienen solo task_id, status, credits, created_at y nombre de archivo, tamaño, mime_type y source_type. Consulta los detalles de los metadatos del archivo, el motivo del error, la caducidad y las URL de resultados. page_size acepta 1–100; los valores no válidos son predeterminados en 20. página debajo de 1 predeterminados en 1.

Parámetros de consulta

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

Campos de respuesta · 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

Obtener tarea results

Leer data.task.status. results es siempre un diccionario: vacío para queued, running, failed o expired, y contiene URL de documentos cuando completed. La URL ZIP es results.full_zip_url. Las tareas fallidas devuelven HTTP 200 con code task_failed y el motivo en msg; expired results use code result_expired.

Parámetros de ruta

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

Campos de respuesta · 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

Formatos y límites

Límites profesionales: 200 MiB por documento, 50 MiB por imagen y 500 unidades facturables. API y web comparten 5 unidades diarias más 1,000 unidades mensuales, utilizando primero las unidades diarias. El uso se reserva después de la validación y se cobra cuando se guarda el resultado del análisis base. La falla de análisis confirmada o la terminación liberan reservas. El error en la publicación /export no reembolsa el análisis exitoso; failed o la ejecución agotada libera automáticamente las reservas no cargadas. Las exportaciones no vuelven a cobrar.

El formato de carga está determinado por la extensión del nombre del archivo, sin distinguir entre mayúsculas y minúsculas. PDF, PowerPoint y Excel deben tener metadatos de página/unit legibles. MIME no se utiliza para validar los contenidos cargados. Se rechazan los archivos vacíos, las extensiones no compatibles, los archivos PDF cifrados o ilegibles y las entradas que exceden el límite. El análisis HTML es estático y no ejecuta JavaScript. 1 MiB = 1,048,576 bytes.

Estados de tarea

Sigue sondeando queued o running. Descargar en completed; lea error y deténgase en failed. expired significa que la retención ha finalizado. status describe toda la tarea; Las tareas API se completan solo cuando el ZIP final está listo.

ZIP results y descargas

El API produce un ZIP final. Markdown, Medio JSON, estructurado JSON y las imágenes guardadas se incluyen de forma predeterminada. extra_formats admite html, docx y latex únicamente; los archivos solicitados se agregan a ese mismo ZIP. No cree un trabajo de exportación web independiente para una tarea API. Sin extras significa results.full_zip_url apunta a base.zip; los extras significan que apunta al archivo exports/a ZIP.

Las tareas químicas devuelven results.original_url y results.json_url, sin ZIP ni exportaciones adicionales.

El resultado químico es un array JSON con todos los campos nativos de MolParser por molécula. Sin moléculas devuelve [].

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)

Los resultados se conservan durante 7 días. results.full_zip_url está firmado por un máximo de 15 minutos y nunca más allá de la retención. Descargue con un GET simple, sin Authorization. Si la firma caduca mientras aún se conserva, consulte los detalles nuevamente para obtener una nueva URL. Los enlaces de imágenes de vista previa duran como máximo 2 horas; otros enlaces de archivos duran como máximo 15 minutos.

Los documentos ZIP mantienen referencias de imágenes relativas nativas e incluyen imágenes guardadas, por lo que esas referencias no dependen de las firmas CDN. Extraiga todo el archivo y mantenga su estructura de carpetas. Las imágenes remotas a las que hace referencia la entrada HTML no se archivan automáticamente y aún pueden apuntar al sitio web de origen.

Errores y recuperación

code 0 indica éxito. Un code distinto de cero identifica la categoría del error; msg explica el motivo. Las consultas de tareas fallidas o caducadas devuelven HTTP 200 con task_failed o result_expired y un objeto results vacío.

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