コマンドライン

cURLでPDFをMarkdown（マークダウン）に変換

Q: cURLの実行に何が必要ですか？

必要なのは curl と jq だけです。curlがHTTPリクエストを送り、jqがJSONレスポンスから job_id と status を読み取ります。多くの環境で利用でき、未導入でも通常は1つのパッケージで追加できます。

Q: ローカルファイルをcurlで変換するには？

multipartアップロードを使います。 url を含むJSONの -d 本文ではなく、Authorizationヘッダー付きで curl -X POST /api/v2/jobs -F file=@report.pdf を送信してください。

Q: jqなしでも実行できますか？

job_id と status を読むには jq が最も明確です。jqが使えない場合はgrepとsedでもJSONを解析できますが、信頼性のためjqを推奨します。

Q: Idempotency-Keyヘッダーの役割は？

再試行時に同じ Idempotency-Key を送ると、重複した変換を始めず、同じジョブが返ります。不安定なCIステップが再実行された場合に役立ちます。

プログラミング言語は不要です。curlとjqがあれば、ターミナル、Makefile、CIステップ、cronジョブからPDFをMarkdownに変換できます。下の例をコピーし、APIキーを設定して実行してください。

開発者向けハブ Web版を試す

要点

3回のcurlとポーリングループ

APIキーを付けてcurl -X POSTでPDFを/api/v2/jobsへ送り、jqでjob_idを取得します。/api/v2/jobs/{job_id}をreadyになるまで確認し、最後にcurlで/api/v2/jobs/{job_id}/downloadを呼び、-oでMarkdownを保存します。HTTPだけで完結するため、シェルが動く環境ならSDKやコンパイルなしで実行できます。

手順

完全なシェルスクリプト

convert.shとして保存し、chmod +xを実行してから起動します。APIキーとPDFを自分の値に置き換えてください。

#!/usr/bin/env bash
set -euo pipefail
API="https://pdf2md.dev/api/v2"
AUTH="Authorization: Bearer p2m_your_key"

# 1) create a job from a PDF URL
#    (to upload a local file instead, use: -F [email protected] )
JID=$(curl -fsS -X POST "$API/jobs" -H "$AUTH" \
  -H "Content-Type: application/json" -H "Idempotency-Key: report-2026-01" \
  -d '{"url":"https://example.com/report.pdf"}' | jq -r .job_id)

# 2) poll until ready or error
while :; do
  JOB=$(curl -fsS "$API/jobs/$JID" -H "$AUTH")
  STATUS=$(echo "$JOB" | jq -r .status)
  [ "$STATUS" = "ready" ] && break
  if [ "$STATUS" = "error" ]; then
    echo "failed: $(echo "$JOB" | jq -r .error_code)" >&2
    exit 1
  fi
  sleep 3
done

# 3) download the Markdown
curl -fsS "$API/jobs/$JID/download" -H "$AUTH" -o report.md
echo "saved report.md"

-fフラグを付けるとHTTPエラー時にcurlが失敗し、set -euo pipefailによって最初の問題でスクリプトが停止します。失敗した処理が空ファイルを黙って書き出すことを防げます。

活用場面

自動化に適した構成

終了コードを返す自己完結型のスクリプトなので、アプリ全体を書くほどではない自動処理へ簡単に組み込めます。

CIパイプライン

ビルド手順に追加すれば、コミットごとにドキュメントPDFをMarkdownへ変換できます。変換が失敗すると、そのステップも失敗します。

cronジョブ

夜間レポートを取得して変換し、ドキュメントサイトやパイプラインが参照する場所へMarkdownを書き出すようにスケジュールできます。

直書きしないシークレット

APIキーはCIのシークレットまたは環境変数に保存し、Authorizationヘッダーから参照してください。コードへの直書きは避けます。

アプリに組み込みたい場合は、Python、Node.js、Goのチュートリアルをご覧ください。

API全体を1ページで確認

すべてのエンドポイント、フィールド、エラーコードは開発者向けハブにまとまっています。OpenAPI仕様をPostmanへ読み込んだり、クライアント生成に利用したりできます。

開発者向けハブ RAG向けMarkdown OpenAPI

bash以外

ほかのシェルとWebhook

この例はbash向けですが、3回の呼び出しは単純なHTTPです。curlが動く環境なら同じ流れを移植できます。

WindowsとPowerShell

最新のWindowsにはcurlが含まれているため、PowerShellや.cmdファイルでも同じ呼び出しを使えます。調整が必要なのは引用符です。PowerShellではJSONをシングルクォートで囲むか、ハッシュテーブルの本文とInvoke-RestMethodを使えます。Makefile、Dockerfileのビルド手順、GitHub Actionsのrun:ブロックでは、そのまま利用できます。

ポーリングを省く

1件から数件ならポーリングが最も簡単です。多数のファイルを扱う場合や待機をなくしたい場合は、Webhookを登録できます。ジョブが完了するとAPIから通知されるため、変換を開始した後は結果が届いた順に処理できます。

どのシェルでも、APIキーはスクリプト本文へ書かず、環境変数またはCIシークレットから読み込んでください。保存前に結果を確認するなら、-oの代わりにダウンロードをビューアへ渡します（curl ... | less）。このエンドポイントはプレーンなMarkdownテキストを返します。

よくある質問

cURLの実行に何が必要ですか？

必要なのはcurlとjqだけです。curlがHTTPリクエストを送り、jqがJSONレスポンスからjob_idとstatusを読み取ります。多くの環境で利用でき、未導入でも通常は1つのパッケージで追加できます。

ローカルファイルをcurlで変換するには？

multipartアップロードを使います。urlを含むJSONの-d本文ではなく、Authorizationヘッダー付きでcurl -X POST /api/v2/jobs -F [email protected]を送信してください。

CIやcronジョブで使うには？

ジョブが失敗するとスクリプトは0以外の終了コードを返すため、CIステップやcronジョブへ組み込めます。APIキーはCIシークレットまたは環境変数に保存し、Authorizationヘッダーで渡してください。

jqなしでも実行できますか？

job_idとstatusを読むにはjqが最も明確です。jqが使えない場合はgrepとsedでもJSONを解析できますが、信頼性のためjqを推奨します。

Idempotency-Keyヘッダーの役割は？

再試行時に同じIdempotency-Keyを送ると、重複した変換を始めず、同じジョブが返ります。不安定なCIステップが再実行された場合に役立ちます。