--- title: "文書変換 API" description: "文書変換 API は HTTPS API で、1 回の POST /v1/convert/{name} 呼び出しでファイル、URL、HTML を受け取り、Markdown を返します。" url: https://markitdown.ai/developers updated: 2026-09-26 source: markitdown.ai --- # 文書変換 API > 文書変換 API は HTTPS API で、1 回の POST /v1/convert/{name} 呼び出しでファイル、URL、HTML を受け取り、Markdown を返します。 匿名トライアルは最大 10 MB、25 ページまでのファイルを受け付け、1 時間あたり IP ごとに 3 回、1 日あたり 10 回まで変換できます。Lite は月額 $20 からで、ファイルは最大 100 MB。Pro は月額 $50、Max は月額 $100。 - ファイル、URL、インラインテキストごとに 1 回の POST /v1/convert/{name} 呼び出し - 応答で 60 秒以内に Markdown を返すか、ポーリングする変換を返します - Web アプリと同じ変換エンジン ## 文書変換 API の仕組み API キーから Markdown まで 3 ステップです。各呼び出しは最大 60 秒待って結果を返します。より長い、または複数ファイルのリクエストは、接続を占有し続ける代わりに 202 とポーリングする変換を返します。 **リクエスト** ```bash # Upload a local file; Markdown comes back in the same response curl -X POST https://api.markitdown.ai/v1/convert/pdf \ -H "x-api-key: mdai_…" \ -F file=@nist-cswp-29-csf-2.0.pdf # Or convert a public web page curl -X POST https://api.markitdown.ai/v1/convert/url \ -H "x-api-key: mdai_…" \ -H "content-type: application/json" \ -d '{"url":"https://markitdown.ai/blog/why-pdfs-break-llms"}' # Took longer than the wait window? Long-poll the conversion curl "https://api.markitdown.ai/v1/conversions/?wait=100" \ -H "x-api-key: mdai_…" ``` 1. API キーを作成する — 「設定 → 開発者」でキーを作成し（有効なサブスクリプションが必要）、x-api-key ヘッダーで送信します。 2. POST /v1/convert/{name} — ファイル、公開 URL、インラインテキストを、その形式のエンドポイントへ送ります。1 回の呼び出しにつき入力は 1 種類です。 3. Markdown を使う — レスポンスから出力を読むか、202 のあとに /v1/conversions/{id} を待ちます。 ## レスポンスと Webhook 下のレスポンスは、検証済みの DOCX パーサー出力を使って API の契約を説明するものです。変換 ID はプレースホルダーです。完了した変換は、消費したクレジットとともに Markdown を返します。202 はその変換への Location ヘッダーを伴います。?wait= でポーリングし、イベントをストリームし、あるいは Webhook で確定を知らせてもらいます。 **レスポンス — または conversion.completed Webhook** ```text { "id": "cnv_3f7c…", "object": "conversion", "name": "word", "status": "completed", "files": [ { "outputs": [ { "format": "markdown", "content": "## Review Findings\n\nRisk ratings follow the standard High / Medium / Low scale defined in the vendor risk management policy.\n\n| Vendor | Risk Rating | Finding | Owner |\n| --- | --- | --- | --- |\n| CloudScan OCR | Medium | No documented data retention limit on uploaded scans | Security |\n| PayBridge | Low | SOC 2 Type II renewed; no open items | Finance |\n| LingoTrans API | High | Sub-processor list not disclosed on request | Legal |\n| ArchiveNow Storage | Medium | Encryption at rest confirmed; key rotation overdue | Security |\n" } ] } ], "usage": { "credits_charged": 1 } } POST https://your-app.example.com/webhooks { "type": "conversion.completed", "data": { "id": "cnv_3f7c…", "object": "conversion", "status": "completed" } } ``` `conversion.completed` と `conversion.failed` を購読すれば、長い、または複数ファイルの変換が確定した瞬間に対応できます。ポーリングは不要です。配信は Standard Webhooks のヘッダーで署名されます。 ## 文書解析 API と Markdown 変換 API チームはファイルから構造を取り出したいときに文書解析 API を、出力をプロンプトやボールトに届けたいときに Markdown 変換 API を探します。Markdown API も含め、どの言い方もこのサービスを指します。フォーマット別のランディングページ、たとえば [pdf to markdown api](/pdf-to-markdown) や [url to markdown api](/url-to-markdown) は、それらコンバーターへのアンカーです — 同じ `/v1/convert/{name}` エンドポイントを使います。 - 変換エンドポイント — POST /v1/convert/{name} — 形式ごとに 1 つのエンドポイント — は、ファイル、URL、テキストを受け取り、Markdown、テキスト、HTML、またはページ単位の出力を返します。 - API キー — アカウント単位のキーを x-api-key ヘッダーで送るので、あらゆるサーバーやスクリプトに変換を組み込めます。 - 複数ファイルと Webhook — 1 回の変換呼び出しに多数のファイルを送って 1 つの変換結果を受け取ります。Webhook が conversion.completed や conversion.failed のたびに通知します。 - Markdown レンダリング — POST /v1/convert/markdown/html または /markdown/text は、Markdown を HTML やプレーンテキストに戻し、クレジットを消費しません。 ## チームが組み込む場所 - RAG の取り込み — チャンク分割と埋め込みの前に、取り込みジョブの中で文書を変換します。 - AI agent — agent がパイプラインの途中で任意のファイルをクリーンなテキストに変えられるようにします。 - コンテンツパイプライン — Markdown を CMS、ドキュメントサイト、ナレッジベースへ自動で流し込みます。 - 社内ツール — すでに運用しているプロダクトやバックオフィスツールに文書変換を加えます。 ## 認証、使用量、上限 - API キーはあなたのアカウントに属し、/v1 でのみ有効で、x-api-key ヘッダーで送信します — アカウントには有効な Lite、Pro、Max のサブスクリプションが必要です - 使用量は Web アプリと同じクレジットを消費します — 標準ページと OCR ページはどちらも 1 ページ 1 クレジットです - プランのレート制限は Lite が毎分 20、Pro が毎分 40、Max が毎分 60 リクエストです - POST /v1/convert/{name} のすべての呼び出しに Idempotency-Key が付くので、再試行で二重に課金されることはありません - すべての v1 エンドポイント、リクエストフィールド、レスポンスは生成された [API リファレンス](/docs/api) に記載されています。失敗時は problem+json を返し、その `type` URI は対応する[エラーコードページ](/docs/errors)に解決します ## 完了状態の扱い 文書変換 API のクライアントでは、インラインでの完了と非同期処理の両方を扱いましょう。送信が成功した場合、完了済みの結果がそのまま返ることもあれば、HTTP 202 がレスポンスのあとも作業が続いていることを示すこともあります。変換 ID を保持し、出力を読む前にドキュメント化された Location か変換ステータスのエンドポイントを使います。HTTP リクエストが成功したというだけで、想定される最初の出力へ直接インデックスを付けないようにします。完了した変換にもファイル単位の失敗が含まれることがあるので、複数ソースのリクエストでは各ファイルを点検します。返ってきた各結果を、アプリが送信したソースにつなげられるだけの文脈を保存しておきましょう。これにより、遅い変換や部分的な失敗が、下流システムの中で黙って空の文書になるのを防げます。 ## リクエストの上限とプランの上限 文書変換 API は、リクエストとアカウントの両方に上限を課します。multipart リクエストには最大 100 個のファイルを含められ、全体の上限は 100 MB です。URL リクエストは最大 20 個のソースを受け付けます。サブスクリプションは別途、クレジット、ストレージ、ファイル単位の上限、同時実行数を管理します。Pro では許されるファイルでも、1 回の multipart リクエストには大きすぎることがあります。その場合はドキュメント化された分割アップロードのフローを使います。最も高いプランなら転送の上限がなくなるという思い込みで、拒否されたリクエストを回避しようとしないでください。エラーを読み、ソースのサイズに合った入力方法を使ってください。 ## ソースの文脈を保つ 自分側のソース識別子を変換 ID の隣に保ち、結果を送信元のジョブまで追跡できるようにします。API の metadata フィールドが運ぶのは呼び出し側が渡したデータで、Web ページのタイトル、著者、公開日を抽出することを約束するものではありません。アプリがそれらの事実を必要とするなら、適切な別のステップで収集して検証します。出力のテキストを読む前に、それがインラインで返るのか参照された成果物を通るのかを確認し、監査証跡が必要なワークフローでは元の文書を保持します。文書変換 API は次の段階のためのコンテンツを用意するだけで、そのコンテンツをソースと結び付け、いつまで保持するかを決めるのはあなたのアプリの役割のままです。 ## ローンチ前のテスト 文書変換 API を本番のワークフローに統合する前に、成功する小さいファイルを 1 つだけでなく、いくつかテストしましょう。非同期完了が必要な入力、未対応または壊れたファイル、結果が混在する複数ソースのリクエスト、そしてクライアントが上限エラーとして扱うべきレスポンスを含めます。部分的な失敗のあとに、自分の再試行ロジックが成功済みのファイルを再送していないことを確認します。API の認証情報はサーバーに置き、ブラウザのコードや公開サンプルに含めないようにします。下流の検索やモデルの挙動を評価する前に、代表的なソース種別の実際の Markdown を確認します。転送エラーを正しく扱うクライアントでも、得られた文書が有用だと示すにはコンテンツ面の確認が別途必要です。 ## FAQ ### 文書変換 API の認証はどう行いますか？ アカウントで API キーを作成し、`x-api-key` ヘッダーで送信します。キーはあなたのアカウントにひも付きます。 ### 実際の変換フローはどうなっていますか？ POST /v1/convert/{name} でファイル、公開 URL、テキストを送ります。文書が待機ウィンドウ内に完了すれば、Markdown が同じレスポンスで返ります。そうでなければ 202 と、GET /v1/conversions/{id}?wait= で待つ変換が返ります。 ### 変換は同期ですか？ 既定では待機ウィンドウの範囲で同期します。POST /v1/convert/{name} は結果を待ってインラインで返すか、時間内に完了できない場合は Location 付きの 202 を返します。Prefer: respond-async を送ると待機をスキップできます。 ### 購読できるイベントは何ですか？ 送信 Webhook は conversion.completed と conversion.failed に対応しているので、ポーリングせず、変換が確定した瞬間に対応できます。 ### API アクセスはどのプランに含まれますか？ API アクセスは有料プランで利用できます。現在のプラン上限とクレジットは料金ページをご覧ください。 ### API の使用量はどう課金されますか？ API の変換は Web アプリと同じクレジット残高から引かれます。標準ページと OCR ページはどちらも 1 ページ 1 クレジットです。 ### pdf to markdown api や url to markdown api はどこにありますか？ それらの表現は形式ごとのランディングページであって、別のホストを意味するものではありません。/pdf-to-markdown にある pdf to markdown api の説明と、/url-to-markdown にある url to markdown api の説明を参照し、ここに記載された同じアップロードと変換のエンドポイントを呼び出します。 ### API キーのレート制限はどれくらいですか？ リクエストはアカウント単位で制限されます。Lite が毎分 20、Pro が毎分 40、Max が毎分 60 リクエストです。 ## Related - [Introduction](https://markitdown.ai/docs) - [PDF to Markdown Converter](https://markitdown.ai/pdf-to-markdown) - [markitdown.ai pricing for document conversion](https://markitdown.ai/pricing)