MinerU API Belgeleri — Markdown ve JSON için belge ayrıştırma

Genel Bakış

Dosya veya URL başına bir görev oluşturun, status öğesini yoklayın ve ardından ZIP dosyasını indirin. İstekler eşzamansızdır. Pro Aylık ve Pro Yıllık API'yi destekler; Ücretsiz değil.

https://YOUR_API_HOST/api/open/v1

YOUR_API_HOST'yi API alanınızla değiştirin. Aşağıdaki tüm yollar bu temel URL'yi kullanır. Örneklerde yer tutucu kimlikleri ve imzalı URL'ler kullanılır.

Kimlik Doğrulama

Her API isteğinde Authorization: Bearer ve ardından Pro API anahtarınızı gönderin. API anahtar düğmesini kullanarak anahtarı alın veya sıfırlayın. Tuşlar büyük/küçük harfe duyarlıdır: sk- artı 24 rastgele harfler ve rakamlar. Kullanıcı oturum açma JWT'leri bu uç noktaların kimliğini doğrulamaz.

Authorization: Bearer sk-YOUR_API_KEY

Anahtarı sunucunuzda tutun. Bunu genel ön uç code, depolarda veya indirme isteklerinde göstermeyin. İndirilenler kendi imzalı URL'lerini kullanır. Anahtarın sıfırlanması eski anahtarın derhal geçersiz kılınmasına neden olur; API erişimi ayrıca aktif bir Pro üyeliği gerektirir.

Hızlı başlangıç

API ana bilgisayarını değiştirin, MINERU_API_KEY ayarlayın ve paper.pdf sağlayın. Bu örnekler bir kez yüklenir, 30 dakikaya kadar her 3 saniyede bir yoklanır, ardından ZIP diske aktarılır. Yoklama zaman aşımı bir istemci sınırıdır ve sunucu görevini iptal etmez. Sorgulamaya devam etmek için görev kimliğini kullanın. Python için requests paketi gereklidir; Node.js'nin 20+ sürümüne ihtiyacı var; cURL, Bash ve jq kullanır.

# 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)

Bir görev oluştur

Tek oluşturma uç noktası: POST /api/open/v1/tasks. multipart/form-data ile dosya yükleyin veya JSON ile source_url gönderin. Her iki yöntem de aynı sorgulama akışı için data.task_id döndürür. Kabul edilen her gönderim yeni bir görev oluşturur.

Kimya modu yalnızca PDF ve görsel kabul eder. force_ocr ve extra_formats kullanılamaz.

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'

Görevleri listele

Web ve API görevlerinizi, en yenisi önce gelecek şekilde birlikte listeler. Öğeler yalnızca task_id, status, credits, created_at ve dosya adı, boyutu, mime_type ve source_type içerir. Dosya meta verileri, hata nedeni, süre sonu ve sonuç URL'leri için sorgu ayrıntıları. page_size, 1–100'yi kabul eder; geçersiz değerler varsayılan olarak 20. sayfanın altındadır 1 varsayılan olarak 1. olarak ayarlanır

Sorgu parametreleri

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

Yanıt alanları · 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

Görev sonuçlarını alın

data.task.status'yi okuyun. results her zaman bir sözlüktür: queued, running, failed veya expired için boştur ve completed olduğunda belge URL'lerini içerir. ZIP URL'si results.full_zip_url'dir. Başarısız olan görevler, HTTP 200 ile code task_failed ve nedenini msg ile döndürür; expired results code result_expired kullanın.

Yol parametreleri

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

Yanıt alanları · 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

Formatlar ve sınırlar

Pro sınırları: belge başına 200 MiB, görüntü başına 50 MiB ve 500 ücretlendirilen birim. API ve web, günlük 5 ve aylık 1000 birimi ortak kullanır; önce günlük birimler tüketilir. Doğrulamadan sonra kota ayrılır ve temel ayrıştırma sonucu kaydedilince düşülür. Doğrulanmış bir ayrıştırma hatası veya sonlandırma durumunda ayrılan kota serbest bırakılır. Yayınlama ya da dışa aktarma hatası, başarıyla tamamlanan ayrıştırmanın kotasını iade etmez. Yürütme başarısız olursa veya zaman aşımına uğrarsa henüz düşülmemiş kota otomatik olarak serbest bırakılır. Dışa aktarma için ek kota düşülmez.

Yükleme formatı, büyük/küçük harfe duyarlı olmaksızın dosya adı uzantısına göre belirlenir. PDF, PowerPoint ve Excel okunabilir sayfa/unit meta verilerine sahip olmalıdır. MIME yüklenen içerikleri doğrulamak için kullanılmaz. Boş dosyalar, desteklenmeyen uzantılar, şifrelenmiş veya okunamayan PDF'ler ve limiti aşan girişler reddedilir. HTML ayrıştırma statiktir ve JavaScript'i çalıştırmaz. 1 MiB = 1,048,576 bayt.

Görev durumları

Durum queued veya running ise düzenli olarak sorgulamaya devam edin. completed olduğunda sonucu indirin; failed olduğunda error alanını okuyup sorgulamayı durdurun. expired, saklama süresinin dolduğunu gösterir. status tüm görevin durumudur; genel belge görevlerinde completed, son ZIP hazır olduğunda döndürülür.

ZIP sonuçları ve indirme

API son bir ZIP üretir. Markdown, Orta JSON, yapılandırılmış JSON ve kaydedilen resimler varsayılan olarak dahil edilir. extra_formats yalnızca html, docx ve latex'yi destekler; istenen dosyalar aynı ZIP dosyasına eklenir. API görevi için ayrı bir web dışa aktarma işi oluşturmayın. Ekstraların olmaması, results.full_zip_url'in base.zip'a işaret ettiği anlamına gelir; ekstralar, ihracat/a ZIP dosyasına işaret ettiği anlamına gelir.

Kimyasal görevler results.original_url ve results.json_url döndürür. ZIP veya ek biçim dışa aktarımı yoktur.

Kimyasal sonuç, her molekül için tüm özgün MolParser alanlarını içeren bir JSON dizisidir. Molekül yoksa [] döndürülür.

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)

Sonuçlar 7 gün saklanır. results.full_zip_url en fazla 15 dakika süreyle imzalanır ve hiçbir zaman saklama süresinin ötesine geçmez. Authorization olmadan düz bir GET ile indirin. İmzanın geçerliliği hâlâ korunuyorken sona ererse, yeni bir URL için ayrıntıları tekrar sorgulayın. Önizleme resmi bağlantıları en fazla 2 saat sürer; diğer dosya bağlantıları en fazla 15 dakika sürer.

ZIP belgeler yerel göreceli görüntü referanslarını tutar ve kayıtlı görüntüleri içerir; dolayısıyla bu referanslar CDN imzalarına bağlı değildir. Arşivin tamamını çıkarın ve klasör yapısını koruyun. HTML girişi tarafından başvurulan uzak görüntüler otomatik olarak arşivlenmez ve yine de kaynak web sitesine işaret edebilir.

Hatalar ve kurtarma

code 0 başarılı demektir. Sıfırdan farklı code hata kategorisini, msg ise nedenini belirtir. Başarısız veya süresi dolmuş görev sorguları HTTP 200 ile task_failed veya result_expired ve boş bir results nesnesi döndürür.

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