開発者向けハブ

PDF to Markdown（マークダウン）APIで開発

REST APIと同等のホスト型MCPで、予測可能なジョブ処理を提供します。作成、readyまで待機、Markdown取得、スロット解放の順です。製品の上限は共通です。ready

料金を見る APIへ移動 OpenAPI

概要

2つの入口、1つのエンジン

用途に合う連携方法を選べます。どちらも同じ変換エンジンを呼び出し、同じスロット、上限、保存期間に従います。

REST API

Bearer APIキーを使うHTTPSエンドポイントです。安定したDTO、予測可能なエラー、冪等な作成を提供します。

処理フローを見る

ホスト型MCP

変換をエージェントツールとして公開する管理済みModel Context Protocolエンドポイントです。同じAPIの薄いラッパーです。

MCPに接続

Custom GPT Actions

簡易OpenAPI仕様をChatGPT Custom GPTへ取り込み、PDF変換を組み込みツールとして利用できます。

Actionを設定

認証

HTTPS上のBearer APIキー

APIとMCPはBearer APIキーを使います。Chrome拡張機能の端末署名経路とは別です。キー発行には無料Googleアカウントが必要です。

キーを取得

無料Googleアカウントでログインします。
アカウントでAPIキーを生成します。表示は1回だけです。
各リクエストでAuthorization: Bearer p2m_…として送ります。Authorization: Bearer p2m_…
キーは秘密情報です。サーバー側で保管し、ローテーションや失効を行えます。

明確な標準設定

パスワードではなくキーを使います。拡張機能は匿名の端末署名を維持し、API/MCPキーは別のアカウント資格情報です。

HTTPSのみ。キーは必ずTLS上で送り、利用者へ配布するクライアント側コードへ埋め込まないでください。

冪等な作成。任意のIdempotency-Keyにより、重複ジョブを作らず安全に再試行できます。

スコープ。各APIキーにはjobs:create、jobs:read、jobs:download、jobs:deleteと、任意のsettings:read / settings:writeがあります。必要最小限のキーを発行してください。jobs:create jobs:read jobs:download jobs:delete settings:read settings:write

REST API

ジョブを作成し、待機して取得後にスロットを解放

REST APIまたは同等のホスト型MCPツールで同じ処理を実行します。status=readyになる前に結果が得られたと判断しないでください。REST API ホスト型MCP status=ready

REST API ホスト型MCP

ジョブを作成

PDFのURLまたはファイルをPOSTします。ジョブIDとスロットが返ります。Idempotency-Keyは任意で利用できます。Idempotency-Key

POST /api/v2/jobsmcp · pdf_to_markdown_create_job_from_url

状態を確認

readyまたはerrorになるまで状態を確認します。有料プランでは署名付きWebhookを使えます。ready error

GET /api/v2/jobs/{id}mcp · pdf_to_markdown_get_job

Markdownを取得

readyになったら結果を取得します。長い文書が一部だけ返ったかはtruncatedとpagesで確認できます。truncated pages

GET /api/v2/jobs/{id}/downloadmcp · pdf_to_markdown_get_markdown

削除してスロットを解放

完了後はスロットを解放します。queuedまたはprocessingのジョブ削除は破壊的操作なので利用者に確認してください。

DELETE /api/v2/jobs/{id}mcp · pdf_to_markdown_delete_job

# 1. create a job from a PDF URL
curl -X POST https://pdf2md.dev/api/v2/jobs \
  -H "Authorization: Bearer p2m_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/report.pdf"}'
# → { "job_id": "job_9f3c…", "status": "queued" }

# 2. poll status
curl https://pdf2md.dev/api/v2/jobs/job_9f3c… \
  -H "Authorization: Bearer p2m_…"
# → { "status": "ready", "pages": 24, "truncated": false }

# 3. fetch the Markdown
curl https://pdf2md.dev/api/v2/jobs/job_9f3c…/download \
  -H "Authorization: Bearer p2m_…"

# 4. free the slot
curl -X DELETE https://pdf2md.dev/api/v2/jobs/job_9f3c… \
  -H "Authorization: Bearer p2m_…"

エラー。レスポンス形式とHTTPコードは安定しています。400、401、404、409 / slots_full、413、429を返します。完全なスキーマはOpenAPI仕様にあります。400 401 404 409 slots_full 413 429 OpenAPI仕様

その他のジョブエンドポイント

ファイルから作成（multipart）POST /api/v2/jobs

ジョブ一覧GET /api/v2/jobs

一括作成（有料）POST /api/v2/jobs/batch

作成はJSONのurlまたはmultipartのfileを受け取り、file_name、external_id、tags、callback_url / callback_secretも指定できます。一括作成は全件成功または全件失敗です。url file file_name external_id tags callback_url callback_secret

ジョブオブジェクト

job_idstring

statusqueued · processing · ready · error

pages · output_sizeinteger

truncatedboolean

error_code · error_message理由（error時）

download_url文字列（ready時）

external_id · tags利用者のメタデータ

slot_usage · tier使用枠の情報

アカウントと使用量。GET /api/v2/me、/api/v2/limits、/api/v2/usageでプラン、上限、使用量を確認し、キーとWebhookを管理できます。GET /api/v2/me /api/v2/limits /api/v2/usage /api/v2/api-keys /api/v2/webhooks

クイックスタート

PythonでPDFをMarkdown（マークダウン）へ変換

どの言語からも同じ4回の呼び出しを使います。ここではrequestsを使います。エラー処理を含む詳細はPythonチュートリアルを参照してください。requests Pythonチュートリアル

# pip install requests
import time, requests

API = "https://pdf2md.dev/api/v2"
H = {"Authorization": "Bearer p2m_…"}

# 1. create a job from a PDF URL (or post a file with files={"file": ...})
job = requests.post(f"{API}/jobs", headers=H,
    json={"url": "https://example.com/report.pdf"}).json()
jid = job["job_id"]

# 2. poll until ready (or register a webhook instead)
while True:
    j = requests.get(f"{API}/jobs/{jid}", headers=H).json()
    if j["status"] in ("ready", "error"):
        break
    time.sleep(3)

# 3. download the Markdown
md = requests.get(f"{API}/jobs/{jid}/download", headers=H).text
print(md)

その他のレシピ: ファイルアップロードとNode

ローカルファイルから作成（curl）

# multipart upload of a local PDF
curl -X POST https://pdf2md.dev/api/v2/jobs \
  -H "Authorization: Bearer p2m_…" \
  -F "[email protected]" \
  -F "file_name=document.pdf"

Node 18+（global fetch）

// create from URL, poll, download
const API = "https://pdf2md.dev/api/v2";
const H = { Authorization: "Bearer p2m_…" };

let job = await (await fetch(`${API}/jobs`, {
  method: "POST",
  headers: { ...H, "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com/report.pdf" })
})).json();

while (job.status === "queued" || job.status === "processing") {
  await new Promise(s => setTimeout(s, 2000));
  job = await (await fetch(`${API}/jobs/${job.job_id}`, { headers: H })).json();
}

if (job.status === "ready") {
  const md = await (await fetch(`${API}/jobs/${job.job_id}/download`, { headers: H })).text();
  console.log(md);
}

Webhook署名検証はWebhook節、MCPクライアント設定はMCP節にあります。完全なスキーマはOpenAPIです。Webhook MCP OpenAPI

ホスト型MCP

エージェントツールとして変換

対応エージェントを管理済みMCPエンドポイントへ接続します。同じREST APIの薄いラッパーなので、同じスロット、上限、保存期間が適用されます。

エージェントをエンドポイントへ接続

APIキーをBearer tokenとして使うStreamable HTTP上のJSON-RPC 2.0です。ローカルサーバーは不要です。initialize、tools/list、tools/call、pingを利用できます。initialize tools/list tools/call ping

POST https://pdf2md.dev/api/v2/mcp

ツールを呼び出す

同じ処理フローと上限を7つのツールとして公開します。各ツールはキースコープを守り、tools/callはslot_usageとtierを返します。tools/call slot_usage tier

create_job_from_url · create_job_from_upload (jobs:create)list_jobs · get_job (jobs:read)get_markdown (jobs:download) · delete_job (jobs:delete)get_limits

ルールを守る

出力利用前にreadyを待ち、queued/processingの削除前に確認し、truncatedと429 Retry-Afterを処理します。ツール名にはpdf_to_markdown_が付きます。ready truncated 429 Retry-After pdf_to_markdown_

// MCP client config (hosted, no local process)
{
  "mcpServers": {
    "pdf2md": {
      "url": "https://pdf2md.dev/api/v2/mcp",
      "headers": {
        "Authorization": "Bearer p2m_…"
      }
    }
  }
}

OpenAPIとCustom GPT Actions

仕様を取り込み、組み込みツールを作成

開発者向け完全版OpenAPIと、AIクライアントやChatGPT Custom GPT Actions向けの安全な最小構成仕様を公開しています。

完全版OpenAPI

すべてのエンドポイント、パラメーター、DTO、エラーを含む完全な契約です。クライアント生成やツール上での確認に使えます。

完全版の仕様を開く

Custom GPT向け簡易版仕様

create、status、fetchだけを含む最小Action仕様です。URLを取り込み、APIキーを認証として設定するとGPTがPDFを変換できます。

簡易版の仕様を開く

簡易仕様はAIクライアント向けの利便性のためのもので、セキュリティ境界ではありません。認証、スコープ、上限は完全版APIと同じです。

上限とレート制限

APIとMCPに共通するプラン別上限

上限はプランで決まり、すべての入口へ同じように適用されます。現在値は料金ページで確認できます。料金ページ

Freeプラン（アカウントあり）

有効スロット数（キュー深度）3

PDFの最大サイズ10 MB

文書ごとの処理時間枠15分

完了結果の保存期間1時間

有料プランではスロット、ファイルサイズ、処理時間枠、保存期間、レート上限が増え、Webhookと一括作成も利用できます。プランを比較 →

レート制限とバックプレッシャー

プラン別レート制限。超過時はRetry-After付き429を返すため、待ってから再試行します。

スロット不足。すべて使用中なら作成は409を返します。削除で解放するか完了を待ちます。

有料プランを優先。専用の有料変換プールで高いキュー優先度が適用されます。

Webhook

ポーリングせずに通知を受信

有料プランでは署名付きWebhookを登録するか、ジョブごとのcallback_urlを渡せます。job.ready、job.error、job.truncated、job.deletedをPOSTで通知します。文書本文は含みません。callback_url job.ready job.error job.truncated job.deleted

エンドポイントを登録

SSRF対策済みのHTTPS URLと任意のeventsフィルターをPOSTします。署名シークレットwhsec_…は1回だけ返ります。単一ジョブではcallback_url + callback_secretも使えます。events whsec_… 1回のみ callback_url callback_secret

POST /api/v2/webhooksGET /api/v2/webhooks/deliveries

イベントを受信

X-P2M-Event、X-P2M-Timestamp、X-P2M-Delivery、X-P2M-Signatureヘッダー付きのJSONをPOSTします。X-P2M-Event X-P2M-Timestamp X-P2M-Delivery X-P2M-Signature

検証して実行

署名を再計算し、2xxで応答して冪等に処理します。配信はバックオフ付きで再試行される場合があります。その後Markdownを取得します。2xx

# delivery → your endpoint
X-P2M-Event: job.ready
X-P2M-Timestamp: 1718900000
X-P2M-Signature: sha256=9a8b7c…

{
  "event": "job.ready",
  "job": {
    "job_id": "job_9f3c…",
    "status": "ready",
    "pages": 24, "truncated": false,
    "download_url": "/api/v2/jobs/job_9f3c…/download"
  }
}

# verify (Python): signature = sha256= + hex(HMAC(secret, "ts.rawbody"))
import hmac, hashlib
def verify(secret, ts, raw_body, sig):
    expected = "sha256=" + hmac.new(
        secret.encode(), f"{ts}.".encode() + raw_body,
        hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

プロンプトと安全性

エージェント向けの移植可能な指示

以下のルールをエージェントのsystem promptへ追加すると、ツールを正しく操作し、結果を捏造しないようにできます。

readyまで待機

status=readyになる前に結果を要約しないでください。queuedまたはprocessingの間は状態確認を続けるかWebhookを待ちます。status=ready queued processing

削除前に確認

queuedまたはprocessingのジョブ削除は破壊的です。未完了ジョブでpdf_to_markdown_delete_jobを呼ぶ前に利用者へ確認します。queued processing pdf_to_markdown_delete_job

一部結果を扱う

truncated=trueなら、処理時間枠までの部分結果であることを伝え、上位プランまたはファイル分割を提案します。truncated=true

429を守る

429ではRetry-After秒待ってから再試行します。キューへ過剰なリクエストを送らないでください。429 Retry-After

スロットを解放

不要になった完了ジョブを削除し、スロット不足を防ぎます。

ディスカバリー情報を読む

文章からエンドポイントを推測せず、/llms.txtとOpenAPI仕様から開始します。/llms.txt

機械可読ディスカバリー

ソースコードを読まずに連携できるように、概要ファイル、詳細コンテキスト、OpenAPI仕様を公開しています。

llms.txt llms-full.txt OpenAPI