Dokumentasi API PaddleOCR — parsing dokumen ke Markdown dan JSON

Ikhtisar

Buat satu tugas per file atau URL, polling status-nya, lalu unduh ZIP. Permintaan tidak sinkron. Pro Bulanan dan Pro Tahunan mendukung API; Gratis tidak.

https://YOUR_API_HOST/api/open/v1

Ganti YOUR_API_HOST dengan domain API Anda. Semua jalur di bawah menggunakan URL dasar ini. Contohnya menggunakan ID placeholder dan URL yang ditandatangani.

Otentikasi

Kirim Authorization: Bearer diikuti dengan kunci Pro API Anda pada setiap permintaan API. Dapatkan atau setel ulang kunci menggunakan tombol kunci API. Kunci peka huruf besar-kecil: sk- plus 24 huruf dan angka acak. JWT login pengguna tidak mengautentikasi titik akhir ini.

Authorization: Bearer sk-YOUR_API_KEY

Simpan kunci di server Anda. Jangan memaparkannya di frontend publik code, repositori, atau permintaan unduhan. Unduhan menggunakan URL yang ditandatanganinya sendiri. Menyetel ulang kunci akan segera membatalkan kunci lama; Akses API juga memerlukan keanggotaan Pro aktif.

Mulai cepat

Ganti host API, setel MINERU_API_KEY, dan berikan paper.pdf. Contoh ini diunggah satu kali, melakukan polling setiap 3 detik hingga 30 menit, lalu mengalirkan ZIP ke disk. Batas waktu polling adalah batas klien dan tidak membatalkan tugas server. Gunakan ID tugas untuk melanjutkan kueri. Python memerlukan paket requests; Node.js memerlukan versi 20+; cURL menggunakan Bash dan 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)

Buat tugas

Satu titik akhir: POST /api/open/v1/tasks. Pilih satu metode masukan: unggah file menggunakan multipart/form-data, atau kirim source_url menggunakan JSON. Keduanya mengembalikan data.task_id untuk alur kueri tugas yang sama. Setiap penyerahan yang diterima menciptakan tugas baru.

Mode kimia hanya menerima PDF dan gambar. force_ocr dan extra_formats tidak tersedia.

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'

Daftar tugas

Cantumkan tugas web dan API Anda secara bersamaan, yang terbaru terlebih dahulu. Item hanya berisi task_id, status, credits, created_at dan nama file, ukuran, mime_type dan source_type. Detail kueri untuk metadata file, alasan kegagalan, kedaluwarsa, dan URL hasil. page_size menerima 1–100; nilai tidak valid default ke 20. halaman di bawah 1 default ke 1.

Parameter kueri

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

Bidang respons · 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

Dapatkan tugas results

Baca data.task.status. results selalu berupa kamus: kosong untuk queued, running, failed atau expired, dan berisi URL dokumen ketika completed. URL ZIP adalah results.full_zip_url. Tugas yang gagal mengembalikan HTTP 200 dengan code task_failed dan alasannya di msg; expired results gunakan code result_expired.

Parameter jalur

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

Bidang respons · 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

Format dan batasan

Batasan pro: 200 MiB per dokumen, 50 MiB per gambar, dan 500 unit yang dapat ditagih. API dan berbagi web 5 setiap hari ditambah 1,000 unit bulanan, menggunakan unit harian terlebih dahulu. Penggunaan dicadangkan setelah validasi dan dikenakan biaya ketika hasil parse dasar disimpan. Kegagalan parse yang dikonfirmasi atau penghentian melepaskan reservasi. Kegagalan publikasi/export tidak mengembalikan dana penguraian yang berhasil; failed atau eksekusi yang waktunya habis secara otomatis melepaskan reservasi yang tidak dikenakan biaya. Ekspor tidak dikenakan biaya lagi.

Format unggahan ditentukan oleh ekstensi nama file, tidak membedakan huruf besar dan kecil. PDF, PowerPoint, dan Excel harus memiliki metadata halaman/unit yang dapat dibaca. MIME tidak digunakan untuk memvalidasi konten yang diunggah. File kosong, ekstensi yang tidak didukung, PDF terenkripsi atau tidak dapat dibaca, dan masukan yang melebihi batas akan ditolak. Penguraian HTML bersifat statis dan tidak menjalankan JavaScript. 1 MiB = 1,048,576 byte.

Status tugas

Teruskan polling queued atau running. Unduh di completed; baca error dan berhenti di failed. expired berarti retensi telah berakhir. status menjelaskan keseluruhan tugas; Tugas API selesai hanya jika ZIP akhir sudah siap.

ZIP results dan unduhan

API menghasilkan satu ZIP terakhir. Markdown, JSON Tengah, JSON terstruktur, dan gambar yang disimpan disertakan secara default. extra_formats hanya mendukung html, docx dan latex; file yang diminta ditambahkan ke ZIP yang sama. Jangan membuat pekerjaan ekspor web terpisah untuk tugas API. Tidak ada tambahan berarti results.full_zip_url menunjuk ke base.zip; tambahan berarti menunjuk ke file ekspor/a ZIP.

Tugas kimia mengembalikan results.original_url dan results.json_url, tanpa ZIP atau ekspor format tambahan.

Hasil kimia berupa array JSON yang mempertahankan semua kolom asli MolParser per molekul. Jika tidak ada molekul, hasilnya [].

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)

Hasil disimpan selama 7 hari. results.full_zip_url ditandatangani paling lama 15 menit dan tidak pernah melampaui retensi. Unduh dengan GET biasa, tanpa Authorization. Jika tanda tangan kedaluwarsa saat masih dipertahankan, tanyakan lagi detail untuk URL baru. Tautan gambar pratinjau bertahan paling lama 2 jam; tautan file lainnya bertahan paling lama 15 menit.

Dokumen ZIP menyimpan referensi gambar relatif asli dan menyertakan gambar yang disimpan, sehingga referensi tersebut tidak bergantung pada tanda tangan CDN. Ekstrak seluruh arsip dan pertahankan struktur foldernya. Gambar jarak jauh yang dirujuk oleh masukan HTML tidak diarsipkan secara otomatis dan mungkin masih mengarah ke situs web sumber.

Kesalahan dan pemulihan

code 0 berarti berhasil. code selain 0 menunjukkan kategori kesalahan; msg menjelaskan alasannya. Kueri tugas gagal atau kedaluwarsa mengembalikan HTTP 200 dengan task_failed atau result_expired dan objek results kosong.

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