PaddleOCR API Docs — Document Parsing API for Markdown & JSON

Overview

Create one task per file or URL, poll its status, then download the ZIP. Requests are asynchronous. Pro Monthly and Pro Annual support the API; Free does not.

https://YOUR_API_HOST/api/open/v1

Replace YOUR_API_HOST with your API domain. All paths below use this base URL. The examples use placeholder IDs and signed URLs.

Authentication

Send Authorization: Bearer followed by your Pro API key on every API request. Get or reset the key using the API key button. Keys are case-sensitive: sk- plus 24 random letters and digits. User login JWTs do not authenticate these endpoints.

Authorization: Bearer sk-YOUR_API_KEY

Keep the key on your server. Do not expose it in public frontend code, repositories or download requests. Downloads use their own signed URL. Resetting the key immediately invalidates the old key; API access also requires an active Pro membership.

Quick start

Replace the API host, set MINERU_API_KEY, and provide paper.pdf. These examples upload once, poll every 3 seconds for up to 30 minutes, then stream the ZIP to disk. The polling timeout is a client limit and does not cancel the server task. Use the task ID to continue querying. Python needs requests; Node.js needs version 20+; cURL uses Bash and 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)

Create a task

One endpoint: POST /api/open/v1/tasks. Choose one input method: upload a file using multipart/form-data, or send source_url using JSON. Both return data.task_id for the same task query flow. Each accepted submission creates a new task.

Chemical structures accept PDF and images only. force_ocr and extra_formats are unavailable.

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'

List tasks

Lists your web and API tasks together, newest first. Items contain only task_id, status, credits, created_at and file name, size, mime_type and source_type. Query details for file metadata, failure reason, expiry and result URLs. page_size accepts 1–100; invalid values default to 20. page below 1 defaults to 1.

Query parameters

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

Response fields · 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

Get task results

Read data.task.status. results is always a dictionary: empty for queued, running, failed or expired, and contains document URLs when completed. The ZIP URL is results.full_zip_url. Failed tasks return HTTP 200 with code task_failed and the reason in msg; expired results use code result_expired.

Path parameters

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

Response fields · 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 and limits

Pro limits: 200 MiB per document, 50 MiB per image, and 500 billable units. API and web share 5 daily plus 1,000 monthly units, using daily units first. Usage is reserved after validation and charged when the base parse result is saved. Confirmed parse failure or termination releases reservations. Publication/export failure does not refund successful parsing; failed or timed-out execution automatically releases uncharged reservations. Exports do not charge again.

Upload format is determined by the filename extension, case-insensitively. PDF, PowerPoint and Excel must have readable page/unit metadata. MIME is not used to validate uploaded contents. Empty files, unsupported extensions, encrypted or unreadable PDFs and over-limit input are rejected. HTML parsing is static and does not run JavaScript. 1 MiB = 1,048,576 bytes.

Task states

Keep polling queued or running. Download on completed; read error and stop on failed. expired means retention has ended. status describes the whole task; API tasks complete only when the final ZIP is ready.

ZIP results and downloads

The API produces one final ZIP. Markdown, Middle JSON, structured JSON and saved images are included by default. extra_formats supports html, docx and latex only; the requested files are added to that same ZIP. Do not create a separate web export job for an API task. No extras means results.full_zip_url points to base.zip; extras mean it points to exports/a ZIP file.

Chemical tasks return results.original_url and results.json_url, without a ZIP or extra exports.

Chemical results are a JSON array. Each molecule retains all native MolParser fields; no molecules returns [].

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)

Results are retained for 7 days. results.full_zip_url is signed for at most 15 minutes and never beyond retention. Download with a plain GET, without Authorization. If the signature expires while still retained, query details again for a new URL. Preview image links last at most 2 hours; other file links last at most 15 minutes.

ZIP documents keep native relative image references and include saved images, so those references do not depend on CDN signatures. Extract the whole archive and keep its folder structure. Remote images referenced by HTML input are not automatically archived and may still point to the source website.

Errors and recovery

code 0 means success. A nonzero code identifies the error category; msg gives the reason. Queries for failed or expired tasks return HTTP 200 with task_failed or result_expired and an empty results object.

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