وثائق PaddleOCR API — تحليل المستندات إلى Markdown و JSON

نظرة عامة

أنشئ مهمة واحدة لكل ملف أو عنوان URL، واستطلع status، ثم قم بتنزيل ZIP. الطلبات غير متزامنة. الدعم الشهري والسنوي الاحترافي لـ API؛ مجاني لا.

https://YOUR_API_HOST/api/open/v1

استبدل YOUR_API_HOST بالنطاق API الخاص بك. تستخدم جميع المسارات أدناه عنوان URL الأساسي هذا. تستخدم الأمثلة معرفات العناصر النائبة وعناوين URL الموقعة.

التوثيق

أرسل Authorization: Bearer متبوعًا بمفتاح Pro API الخاص بك في كل طلب API. احصل على المفتاح أو أعد ضبطه باستخدام زر المفتاح API. المفاتيح حساسة لحالة الأحرف: sk- plus 24 أحرف وأرقام عشوائية. لا تقوم JWTs بتسجيل دخول المستخدم بمصادقة نقاط النهاية هذه.

Authorization: Bearer sk-YOUR_API_KEY

احتفظ بالمفتاح على الخادم الخاص بك. لا تعرضه في الواجهة الأمامية العامة code أو المستودعات أو طلبات التنزيل. تستخدم التنزيلات عنوان URL الموقع الخاص بها. تؤدي إعادة ضبط المفتاح إلى إبطال صلاحية المفتاح القديم على الفور؛ يتطلب الوصول إلى API أيضًا عضوية Pro نشطة.

بداية سريعة

استبدل المضيف API واضبط MINERU_API_KEY وقم بتوفير paper.pdf. يتم تحميل هذه الأمثلة مرة واحدة، والاستطلاع كل 3 ثانية لمدة تصل إلى 30 دقيقة، ثم يتم بث ZIP إلى القرص. تعد مهلة الاستقصاء حدًا للعميل ولا تؤدي إلى إلغاء مهمة الخادم. استخدم معرف المهمة لمتابعة الاستعلام. يتطلب Python مكتبة requests؛ Node.js يحتاج إلى الإصدار 20+؛ cURL يستخدم Bash و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)

إنشاء مهمة

نقطة نهاية واحدة: POST /api/open/v1/tasks. اختر طريقة إدخال واحدة: قم بتحميل ملف باستخدام multipart/form-data، أو أرسل source_url باستخدام JSON. يقوم كلاهما بإرجاع data.task_id لنفس تدفق استعلام المهمة. يقوم كل إرسال مقبول بإنشاء مهمة جديدة.

الوضع الكيميائي يقبل PDF والصور فقط. لا يدعم force_ocr أو 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'

قائمة المهام

يسرد مهام الويب وAPI معًا، الأحدث أولاً. تحتوي العناصر فقط على task_id وstatus وcredits وcreated_at واسم الملف وحجمه وmime_type وsource_type. تفاصيل الاستعلام عن بيانات تعريف الملف وسبب الفشل وانتهاء الصلاحية وعناوين URL للنتائج. page_size يقبل 1–100؛ القيم الافتراضية غير الصالحة هي 20. الصفحة الموجودة أسفل 1 الافتراضية هي 1.

معلمات الاستعلام

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

حقول الرد · 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

الحصول على المهمة results

إقرأ data.task.status. results هو دائمًا قاموس: فارغ لـ queued، running، failed أو expired، ويحتوي على عناوين URL للمستندات عندما completed. عنوان URL ZIP هو results.full_zip_url. تُرجع المهام الفاشلة HTTP 200 مع code task_failed والسبب في msg؛ expired results استخدم code result_expired.

معلمات المسار

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

حقول الرد · 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

التنسيقات والحدود

الحدود الاحترافية: 200 MiB لكل مستند، 50 MiB لكل صورة، و500 وحدات قابلة للفوترة. API ومشاركة الويب 5 يوميًا بالإضافة إلى 1,000 وحدة شهرية، باستخدام الوحدات اليومية أولاً. يتم حجز الاستخدام بعد التحقق من الصحة ويتم فرض رسوم عليه عند حفظ نتيجة التحليل الأساسية. تأكيد فشل التحليل أو إنهاء عمليات النشر للتحفظات. لا يؤدي فشل المنشور /export إلى استرداد قيمة التحليل الناجح؛ failed أو التنفيذ الذي انتهت مهلته يؤدي تلقائيًا إلى تحرير الحجوزات غير المدفوعة. الصادرات لا تهمة مرة أخرى.

يتم تحديد تنسيق التحميل من خلال امتداد اسم الملف، بشكل غير حساس لحالة الأحرف. يجب أن تحتوي PDF وPowerPoint وExcel على بيانات تعريف صفحة /unit قابلة للقراءة. لا يُستخدم MIME للتحقق من صحة المحتويات التي تم تحميلها. يتم رفض الملفات الفارغة والامتدادات غير المدعومة وملفات PDF المشفرة أو غير القابلة للقراءة والإدخال الزائد عن الحد. تحليل HTML ثابت ولا يقوم بتشغيل JavaScript. 1 MiB = 1,048,576 بايت.

حالات المهمة

استمر في الاقتراع queued أو running. التنزيل على completed; اقرأ error وتوقف عند failed. expired يعني أن الاحتفاظ بالبيانات قد انتهى. يصف status المهمة بأكملها؛ تكتمل مهام API فقط عندما تكون ZIP النهائية جاهزة.

ZIP results والتنزيلات

ينتج API ZIP نهائيًا. يتم تضمين الصور Markdown والوسطى JSON والصور المنظمة JSON والصور المحفوظة بشكل افتراضي. extra_formats يدعم html، docx وlatex فقط؛ تتم إضافة الملفات المطلوبة إلى نفس ZIP. لا تقم بإنشاء مهمة تصدير ويب منفصلة لمهمة API. عدم وجود إضافات يعني أن results.full_zip_url يشير إلى base.zip؛ الإضافات تعني أنها تشير إلى ملف Export/a ZIP.

تُرجع المهام الكيميائية results.original_url وresults.json_url، دون ZIP أو صيغ تصدير إضافية.

النتيجة مصفوفة JSON تحتفظ بجميع حقول MolParser الأصلية لكل جزيء. عند عدم وجود جزيئات تُرجع [].

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)

تُحفظ النتائج لمدة 7 أيام. يتم التوقيع على results.full_zip_url لمدة 15 دقيقة على الأكثر ولا يتجاوز الاحتفاظ بها أبدًا. قم بالتنزيل باستخدام GET عادي، بدون Authorization. إذا انتهت صلاحية التوقيع مع استمرار الاحتفاظ به، فاستفسر عن التفاصيل مرة أخرى للحصول على عنوان URL جديد. تدوم روابط معاينة الصور لمدة 2 ساعة على الأكثر؛ تستمر روابط الملفات الأخرى لمدة 15 دقيقة على الأكثر.

تحتفظ مستندات ZIP بمراجع الصور النسبية الأصلية وتتضمن الصور المحفوظة، لذلك لا تعتمد تلك المراجع على توقيعات CDN. قم باستخراج الأرشيف بالكامل واحتفظ ببنية المجلد الخاص به. لا تتم أرشفة الصور البعيدة المشار إليها بواسطة إدخال HTML تلقائيًا وقد تظل تشير إلى موقع الويب المصدر.

الأخطاء والإسترجاع

تعني القيمة 0 في code النجاح. يحدد code غير الصفري فئة الخطأ، ويوضح msg السبب. تعيد استعلامات المهام الفاشلة أو المنتهية HTTP 200 مع task_failed أو result_expired وكائن results فارغ.

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