PaddleOCR API ドキュメント

はじめに

概要

ファイルまたはURLごとに1つのタスクを作成し、状態を確認してZIPを取得します。非同期APIです。Pro月額・年額プランのみ対応します。

APIベースURL

https://YOUR_API_HOST/api/open/v1

YOUR_API_HOSTをAPIドメインに置き換えてください。以下のパスはこのURLが基準です。IDと署名URLは例示用です。

POST/tasksタスクの作成 GET/tasks/{id}タスク結果の取得 GET/tasksタスク一覧の取得

認証とヘッダー

各リクエストにAuthorization: BearerとPro APIキーを付けます。API keyボタンで確認・再発行できます。キーはsk-と24文字のランダムな英数字で、大文字・小文字を区別します。ログインJWTは使用できません。

フィールド	型	必須	説明
`Authorization`	`string`	はい	BearerとPro APIキー。全APIで必須です。

リクエストヘッダー

Authorization: Bearer sk-YOUR_API_KEY

キーはサーバー側で保管し、公開フロントエンド・リポジトリ・ダウンロード要求に含めないでください。ダウンロードは署名URLを使います。再発行で旧キーは即時無効になり、有効なPro契約が必要です。

実行例

APIホストを変更し、MINERU_API_KEYとpaper.pdfを用意します。1回アップロード後、3秒間隔で最大30分確認し、ZIPを保存します。クライアントの待機終了はサーバータスクをキャンセルしません。IDで再確認できます。Pythonはrequests、Node.jsは20以上、cURLはBashとjqが必要です。

Python

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

APIエンドポイント

タスクの作成

POST/api/open/v1/tasks

作成エンドポイントは POST /api/open/v1/tasks の1つです。multipart/form-dataでファイルを送信するか、JSONでsource_urlを送信してください。どちらもdata.task_idを返し、同じ結果取得フローを使います。受理された送信ごとに新しいタスクを作成します。

化学モードは PDF と画像のみ対応。force_ocr と extra_formats は使用できません。

方法1：ファイルの送信

APIサーバーへファイル1つを直接送信します。multipart境界はHTTPクライアントに任せ、Content-Typeを手動指定しないでください。fileと任意のforce_ocr・extra_formatsのみ対応します。実サイズ・単位数を検証して保存・待機列へ登録します。完了通知は不要です。

ボディパラメーター · multipart/form-data

フィールド	型	必須	説明
`file`	`binary`	はい	対応拡張子を持つファイル1つ。
`parse_type`	`string (0 \| 1)`	いいえ	0：一般ドキュメント（既定）、1：化学構造認識。既定値: `0`
`force_ocr`	`string (true \| false)`	いいえ	true / false; PDF のみに適用されます。オンでは既存のテキスト層を無視して OCR を使用し、オフでは自動判定します。他の形式には影響しません。既定値: `false`
`extra_formats`	`string (JSON)`	いいえ	JSON配列の文字列。html・docx・latexのみ。既定値: `[]`

リクエスト例 · cURL

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"]'

レスポンスフィールド · 200 OK

HTTP 200 はタスクの作成成功を示します。code は 0、msg は ok、data には task_id のみが含まれます。状態と結果はタスク取得 API で確認します。

フィールド	型	説明
`code`	`integer`	タスク作成成功時は 0。
`data.task_id`	`string (UUID)`	作成時の data.task_id に入るタスク UUID。
`msg`	`string`	タスク作成成功時は ok。

レスポンス例

{
  "code": 0,
  "data": {
    "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436"
  },
  "msg": "ok"
}

方法2：URLの送信

multipartではなくJSONを送信します。source_urlは公開HTTP/HTTPSの文書・画像・HTMLです。正のContent-Lengthと、ヘッダーまたは名前で判定できる対応形式が必要です。欠落・矛盾・変更で失敗します。内部アドレス・認証情報付きURL・圧縮・チャンク応答は拒否し、リダイレクトは最大5回です。作成時はqueued、取得エラーはtask.errorに記録します。

ボディパラメーター · application/json

フィールド	型	必須	説明
`source_url`	`string`	はい	公開HTTP/HTTPS URL。メタデータ・サイズ検証対象。
`parse_type`	`integer (0 \| 1)`	いいえ	0：一般ドキュメント（既定）、1：化学構造認識。既定値: `0`
`force_ocr`	`boolean`	いいえ	true / false; PDF のみに適用されます。オンでは既存のテキスト層を無視して OCR を使用し、オフでは自動判定します。他の形式には影響しません。既定値: `false`
`extra_formats`	`string[]`	いいえ	文字列ではなく配列。html・docx・latexを指定します。Markdown・JSONは標準です。既定値: `[]`

リクエスト例 · cURL

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"]}'

レスポンスフィールド · 200 OK

HTTP 200 はタスクの作成成功を示します。code は 0、msg は ok、data には task_id のみが含まれます。状態と結果はタスク取得 API で確認します。

フィールド	型	説明
`code`	`integer`	タスク作成成功時は 0。
`data.task_id`	`string (UUID)`	作成時の data.task_id に入るタスク UUID。
`msg`	`string`	タスク作成成功時は ok。

レスポンス例

{
  "code": 0,
  "data": {
    "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436"
  },
  "msg": "ok"
}

化学構造認識 · cURL

curl --fail-with-body "https://YOUR_API_HOST/api/open/v1/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -F '[email protected]' \
  -F 'parse_type=1'

タスク一覧の取得

GET/api/open/v1/tasks

Web と API のタスクを作成日時の降順でまとめて返します。各項目は task_id、status、credits、created_at と file の name、size、mime_type、source_type のみです。詳細、失敗理由、期限、結果 URL は詳細 API で取得します。page_size は 1–100、無効値は 20、page の最小値は 1 です。

クエリパラメーター

フィールド	型	必須	説明
`page`	`integer`	いいえ	1始まり。不正・1未満は1。既定値: `1`
`page_size`	`integer`	いいえ	1–100件。不正値は20。既定値: `20`
`search`	`string`	いいえ	すべての自分のタスクからファイル名を検索（最大255文字）。
`status`	`string`	いいえ	任意の状態：queued、running、completed、failed、expired。複数はカンマで区切ります。

リクエスト例 · cURL

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

レスポンスフィールド · 200 OK

フィールド	型	説明
`data.items`	`TaskSummary[]`	TaskSummary 表のフィールドのみを含むタスク概要です。
`data.has_more`	`boolean`	次のページがあるかどうか。
`data.page`	`integer`	1始まり。不正・1未満は1。
`data.page_size`	`integer`	1–100件。不正値は20。

レスポンス例

{
  "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

フィールド	型	説明
`task_id`	`string (UUID)`	作成時の data.task_id に入るタスク UUID。
`parse_type`	`integer (0 \| 1)`	0：一般ドキュメント（既定）、1：化学構造認識。
`status`	`string`	全体のタスク状態。状態表を参照。
`credits`	`integer`	課金対象数：PDF のページ、PPT のスライド、Excel のシート。Word、HTML、画像は 1。URL ファイルの検査完了前は 0。
`created_at`	`string (RFC3339)`	作成時刻、RFC3339。
`file.name`	`string`	入力名。URL取得前はホスト名の場合があります。
`file.size`	`integer (int64)`	実サイズ（バイト）。URL取得前は0。
`file.mime_type`	`string`	保存MIME型。取得中は空の場合があります。
`file.source_type`	`string`	uploadまたはurl。

タスク結果の取得

GET/api/open/v1/tasks/{id}

data.task.status を確認します。results は常に辞書で、queued、running、failed、expired では空、completed では文書の結果 URL を含みます。ZIP の URL は results.full_zip_url です。失敗時は HTTP 200、code task_failed、msg に理由を返します。期限切れは code result_expired です。

パスパラメーター

フィールド	型	必須	説明
`id`	`string (UUID)`	はい	作成時の data.task_id に入るタスク UUID。

リクエスト例 · cURL

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

レスポンスフィールド · 200 OK

フィールド	型	説明
`data.task`	`Task`	Taskオブジェクト。取得成功時に返します。
`data.file`	`File`	入力File。URLメタデータは未取得の場合があります。
`data.results`	`object`	ファイルと画像の URL を含む辞書です。未完了、失敗、期限切れでは空の辞書を返します。

処理中のレスポンス · running

{
  "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": {}
  }
}

レスポンス例 · completed

{
  "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"
    }
  }
}

失敗タスクのレスポンス · HTTP 200

{
  "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

フィールド	型	説明
`task_id`	`string (UUID)`	作成時の data.task_id に入るタスク UUID。
`parse_type`	`integer (0 \| 1)`	0：一般ドキュメント（既定）、1：化学構造認識。
`status`	`string`	全体のタスク状態。状態表を参照。
`credits`	`integer`	課金対象数：PDF のページ、PPT のスライド、Excel のシート。Word、HTML、画像は 1。URL ファイルの検査完了前は 0。
`force_ocr`	`boolean`	true / false; PDF のみに適用されます。オンでは既存のテキスト層を無視して OCR を使用し、オフでは自動判定します。他の形式には影響しません。
`expires_at`	`string \| null (RFC3339)`	保存期限。結果・失敗記録前はnullの場合があります。
`error`	`string`	処理エラー・復旧説明。なければ空。
`created_at`	`string (RFC3339)`	作成時刻、RFC3339。

File

フィールド	型	説明
`name`	`string`	入力名。URL取得前はホスト名の場合があります。
`size`	`integer (int64)`	実サイズ（バイト）。URL取得前は0。
`mime_type`	`string`	保存MIME型。取得中は空の場合があります。
`suffix`	`string`	ドットなし小文字拡張子。取得中は空の場合があります。
`source_type`	`string`	uploadまたはurl。
`source_url`	`string`	入力されたURL。アップロードは空。

results

フィールド	型	説明
`original_url`	`string`	入力ファイル署名URL。
`json_url`	`string`	化学認識 JSON の URL。parse_type=1 の場合のみ返されます。
`markdown_url`	`string`	プレビュー用markdown.mdの署名URL。
`middle_json_url`	`string`	ページ・構造・正規化座標付きmiddle_json.jsonの署名URL。
`structured_json_url`	`string`	structured_content.json の署名付きURL。対応するファイルがない場合はこのフィールドを省略します。
`images`	`Record<string, string>`	相対パスから署名画像URLへのマップ。画像なしは空オブジェクト。
`full_zip_url`	`string`	results.full_zip_url は API 最終 ZIP の署名付き URL で、完了かつ有効期限内に返します。

参考情報

入力形式と制限

Pro上限は文書200 MiB、画像50 MiB、500単位です。APIとWebは日次5・月次1,000単位を共有し日次を先に使います。検証後に予約し基本解析結果の保存時に課金します。解析失敗・停止確認後は予約を解放します。公開・出力失敗で成功済み解析を返金せず。実行失敗やタイムアウトでは未課金の予約を自動で解放します。出力は再課金しません。

形式	ファイル拡張子	利用単位
PDF	`.pdf`	PDFの物理ページ数
Word	`.doc, .docx`	1ファイルにつき1単位
PowerPoint	`.ppt, .pptx`	スライド数
Excel	`.xls, .xlsx`	ワークシート数
画像	`.png, .jpg, .jpeg, .webp, .gif, .bmp, .tif, .tiff`	1ファイルにつき1単位
HTML	`.html, .htm`	1ファイルにつき1単位

アップロード形式は拡張子で判定し、大文字・小文字を区別しません。PDF・PowerPoint・Excelは単位数を読み取れる必要があります。MIMEによる内容検証はしません。空・未対応・暗号化PDF・上限超過は拒否します。HTMLは静的解析でJavaScriptを実行しません。1 MiB = 1,048,576バイト。

タスク状態

queued・runningでは照会を続けます。completedでダウンロードし、failedではerrorを確認して照会を止めます。expiredは保存期限切れです。statusはタスク全体を表し、APIは最終ZIPが準備できた時にcompletedになります。

task.status	説明
`queued`	受付済み。処理待ち、またはURLの入力ファイルを取得しています。
`running`	解析、結果保存、APIのZIP作成を含む処理中。
`completed`	最終結果が準備できました。取得・ダウンロードできます。
`failed`	処理失敗。errorを確認し、自動で新規作成しないでください。
`expired`	expires_atの保存期限を過ぎており、ダウンロードURLは返しません。

ZIP結果とダウンロード

APIは最終ZIPを1つ返します。標準でMarkdown・Middle JSON・構造化JSON・保存画像を含みます。extra_formatsはhtml・docx・latexのみで、同じZIPに追加します。APIタスクにウェブ出力ジョブは不要です。追加なしはbase.zip、追加ありはexports/のZIPを返します。

化学タスクは results.original_url と results.json_url を返します。ZIP や追加形式のエクスポートはありません。

化学結果は JSON 配列です。各分子の MolParser 標準フィールドをすべて保持し、未検出の場合は [] を返します。

molecular_structures.json

source, input_index, page_index, bbox, confidence, raw_caption, caption, smi, esmi, cxsmiles, markush, sru, groups

ZIP

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分で、保存期限を超えません。Authorization なしで GET ダウンロードできます。署名のみ期限切れの場合は詳細を再取得して新しい URL を取得してください。プレビュー画像は最長2時間、その他のファイルは最長15分有効です。

ZIPは元の相対画像パスと保存画像を保持するためCDN署名に依存しません。全体を解凍し、構成を保持してください。HTMLの外部画像は自動保存されず、元サイトを参照する場合があります。

エラーと対処

code が 0 なら成功です。0 以外の code はエラーの種類を示し、msg に理由が入ります。失敗・期限切れのタスクを取得すると、HTTP 200、task_failed または result_expired、空の results オブジェクトを返します。

HTTP 402

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

HTTP	code	説明
200	`task_failed`	解析に失敗しました。理由は msg を確認してください。
200	`result_expired`	結果の保存期限が過ぎています。
400	`invalid_request`	パラメーターまたはファイルが無効です。理由は msg を確認してください。
400	`too_many_pages`	文書がページ数または課金単位数の上限を超えています。
401	`unauthorized`	API 認証に失敗しました。
402	`quota_exceeded`	利用可能な残量が不足しています。
403	`user_disabled`	アカウントは無効です。
403	`pro_required`	有効な Pro 会員資格が必要です。
404	`not_found`	タスクが存在しないか、アクセス権がありません。
413	`file_too_large`	ファイルがプランのサイズ上限を超えています。
500	`internal_error`	サーバーでの処理に失敗しました。理由は msg を確認してください。

PaddleOCR API ドキュメント - 文書解析 API（Markdown / JSON）

はじめに

概要

認証とヘッダー

実行例

APIエンドポイント

タスクの作成

方法1：ファイルの送信

ボディパラメーター · multipart/form-data

レスポンスフィールド · 200 OK

方法2：URLの送信

ボディパラメーター · application/json

レスポンスフィールド · 200 OK

タスク一覧の取得

クエリパラメーター

レスポンスフィールド · 200 OK

TaskSummary

タスク結果の取得

パスパラメーター

レスポンスフィールド · 200 OK

Task

File

results

参考情報

入力形式と制限

タスク状態

ZIP結果とダウンロード

エラーと対処