Claude Files APIでPDFを処理する方法 — アップロードから解析まで

はじめに

Files APIは、ファイルを一度アップロードしてfile_idで使い回せる仕組みです。PDFやテキスト、画像を毎回base64エンコードして送る代わりに、アップロード時に受け取ったIDをメッセージで参照するだけで済みます。同じPDFに繰り返し問い合わせる場合や、複数のリクエストから同じPDFを参照する場合に、ペイロードとエンコード処理を省けるのが利点です。

本チュートリアルでは、PDFをFiles APIにアップロードしてClaudeに解析させる一連の手順を扱います。アップロードからメッセージでの参照、サイズとページ数の制限、コスト試算、大量処理時の最適化、そしてファイルのライフサイクル管理までを実装コード付きで確認します。Files APIはAnthropic APIが提供する機能の1つです。API全体の料金体系やモデル選択はAnthropic API完全ガイドにまとめています。

前提条件

Anthropic APIキー(console.anthropic.comで取得)
Files APIはベータ機能のため、anthropic-beta: files-api-2025-04-14ヘッダーが必須です(SDKのbeta.files名前空間を使えば自動付与されます)
PDF処理そのものは現行の全モデルで使えますが、Files APIが使える基盤は限られます(この後の節で確認します)

PDFをClaudeに渡す3つの方法 — どれを選ぶか

Messages APIのdocumentブロックには、PDFを渡す方法が3種類あります。

方法	向いている場面	注意点
URL参照	向いている場面公開URL上のPDFを一度だけ問い合わせる	注意点URLがリクエストのたびに到達可能である必要
Base64埋め込み	向いている場面手元のファイルをその場で1回だけ送る	注意点ペイロードが肥大化し、毎回エンコード処理が発生
Files API(`file_id`)	向いている場面同じPDFへ繰り返し問い合わせる・複数リクエストで使い回す	注意点ベータヘッダー必須、アップロードとID管理の手間

一回きりの問い合わせならBase64埋め込みかURL参照で十分です。同じ契約書やレポートに何度も質問する、あるいは複数のエンドポイントから同じPDFを参照するなら、Files APIでエンコード処理と転送量を省けます。

手順1: PDFをFiles APIにアップロードする

FILE_ID=$(curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -F "file=@/path/to/document.pdf" | jq -r '.id')
echo "$FILE_ID"

アップロードに成功すると、file_011...形式のfile_idとfilename・mime_type・size_bytesを含むレスポンスが返ります。自分でアップロードしたファイルはdownloadableが常にfalseです。ダウンロードできるのは、Skillsやcode executionツールが生成したファイルだけです。

Python / TypeScriptでの実装例

uploaded = client.beta.files.upload(
    file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)
file_id = uploaded.id

const uploaded = await client.beta.files.upload({
  file: await toFile(
    fs.createReadStream("/path/to/document.pdf"),
    undefined,
    { type: "application/pdf" },
  ),
});
console.log(uploaded.id);

手順2: file_idをメッセージで参照する

アップロードしたfile_idをdocumentブロックのsourceに渡すと、以降のリクエストで同じPDFを何度でも参照できます。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "messages": [{
      "role": "user",
      "content": [
        {"type": "document", "source": {"type": "file", "file_id": "'"$FILE_ID"'"}},
        {"type": "text", "text": "この文書の主な論点を教えてください"}
      ]
    }]
  }'

画像を渡す場合はdocumentではなくimageブロック、データセットをcode executionツールに渡す場合はcontainer_uploadブロックを使います。ファイル種別とブロックの対応は次の通りです。

ファイル種別	MIMEタイプ	ブロック種別
PDF	MIMEタイプapplication/pdf	ブロック種別document
プレーンテキスト	MIMEタイプtext/plain	ブロック種別document
画像(JPEG/PNG/GIF/WebP)	MIMEタイプimage/*	ブロック種別image
データセットほか	MIMEタイプ形式による	ブロック種別container_upload

.docxや.xlsxはdocumentブロックが直接対応していない形式です。プレーンテキストに変換して地の文に含めるか、画像を含む.docxならPDFに変換してから渡すと、PDF側の画像解析と引用機能をそのまま使えます。抽出した内容を構造化データとして取り出したい場合は、documentブロックとtool useを組み合わせます。組み合わせ方は高度なTool useで扱っています。

PDFのサイズとページ数の制限を確認する

Files APIへのアップロード自体は1ファイル500MB、組織全体で500GBまで許容されます。ただし、documentブロックに含めてメッセージとして送る段階では、これより厳しい制限が別に掛かります。

項目	上限
リクエスト全体のサイズ	上限32MB(プラットフォームにより変動)
1リクエストあたりのページ数	上限600ページ(コンテキストウィンドウが100万トークン未満のモデルでは100ページ)
形式	上限標準PDF(パスワード・暗号化なし)

32MBとページ数の上限は、PDF単体ではなくリクエストペイロード全体に対してかかります。他のPDFやテキストを同じリクエストに含めていれば、その分だけ余裕が減ります。小さなフォントが多いページや複雑な表・図版を多く含むPDFは、ページ数の上限に達する前にコンテキストウィンドウを圧迫することがあります。大きなPDFは分割するか、埋め込み画像を間引くと通りやすくなります。

PDFの処理の仕組みとコスト試算

Claudeは送られたPDFを次の3段階で処理します。

各ページを画像に変換し、同時にページごとのテキストを抽出する
抽出したテキストと画像の両方を突き合わせて解析する。グラフや図版など視覚要素への質問もこの段階で扱える
テキストと画像の両方を参照しながら応答する

テキストと画像の両方を送るため、トークン消費は本文の長さだけでは決まりません。ページあたりのテキストは内容密度に応じて概ね1,500〜3,000トークン、加えて各ページが画像として扱われる分のトークンが上乗せされます。PDF処理専用の追加料金はなく、通常のinput tokenと同じ単価で課金されます。正確な見積もりが必要な場合は、送信前にtoken counting機能で概算しておくと安全です。

大量のPDFを扱うときの最適化

一回きりの問い合わせを超えて運用に組み込む場合は、次の3つが効きます。

Prompt cachingを使う: 同じPDFに複数の質問を投げるなら、documentブロックにcache_control: {"type": "ephemeral"}を付けてキャッシュへ書き込みます。2回目以降の問い合わせはキャッシュ読み込みになり、同じPDFを毎回フルコストで処理せずに済みます。仕組みの詳細はPrompt Cachingの解説で扱っています
Message Batches APIでまとめて処理する: 大量のPDFに同じ質問を投げる、あるいは1つのPDFに複数の質問を投げる場合は、個別にリクエストを打つよりBatch APIでまとめて非同期処理したほうが効率的です。なおFiles API自体はベータ期間中、呼び出しが約100リクエスト/分に制限されるため、大量アップロードを組む際はこの上限も考慮します
配置とフォーマットを整える: PDFはプロンプトのテキストより前に置く、標準的なフォントを使う、ページの向きを正しく揃える、PDFビューアー上のページ番号で参照する。この4点だけでも解析精度が安定します

ファイルを一覧・取得・削除する

アップロードしたファイルは、明示的に削除するまで保持され続けます。一覧・メタデータ取得・削除の3操作が使えます。

# 一覧(既定20件、before_id/after_idでページング)
curl https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"
 
# 削除
curl -X DELETE "https://api.anthropic.com/v1/files/$FILE_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

ファイルは同じワークスペースのAPIキーであれば、アップロードしたキーと別のキーからでも参照できます。削除は取り消せません。削除直後でも、実行中のバッチ処理など進行中の呼び出しには一時的に残ることがあります。

よくあるつまずき

ダウンロードしようとして400エラーになる

ダウンロードできるのは、Skillsやcode executionツールが生成したファイルだけです。自分でアップロードしたPDFはダウンロード対象ではありません。

file_idのブロック種別を間違えて400エラーになる

PDFはdocumentブロック、画像はimageブロック、データセットはcontainer_uploadブロックと、ファイル種別ごとにブロックが決まっています。取り違えるとinvalid file typeエラーになります。

ファイル名で400エラーになる

ファイル名は1〜255文字までで、< > : " | ? * \ /やUnicode制御文字(0〜31)を含められません。

組織のストレージ上限(500GB)に達する

使い終わったファイルを都度削除する運用にしておかないと、繰り返しアップロードするワークフローで気づかないうちに上限へ近づきます。

Bedrock Converse APIでPDFの図表が読めない

Bedrock経由(Opus 4.6以前のレガシー統合)でCitationsを有効にしないと、視覚解析にならずテキスト抽出のみのフォールバックになります。Citations有効化を必須としないInvokeModel APIを使うか、Converse APIでCitationsを明示的に有効にしてください。

claude.aiアプリでPDFを読ませたいとき

ここまでの内容は、すべて自分のアプリケーションに組み込むAPI機能としてのFiles API・PDF処理です。チャット画面でPDFを添付して質問したいだけなら、Files APIを触る必要はありません。claude.aiやデスクトップアプリでのファイル添付の使い方はClaudeアプリ完全ガイドで扱っています。

よくある質問

Files APIは無料ですか

アップロード・ダウンロード・一覧取得・メタデータ取得・削除といったFiles API自体の操作はすべて無料です。課金が発生するのは、ファイルの内容をメッセージリクエストに含めて解析させたときのinput tokenだけです。

アップロードしたPDFは編集できますか

できません。アップロード後のファイルは内容を変更したり名前を変えたりできません。内容を差し替えたい場合は、新しいファイルをアップロードして古いファイルを削除します。

Files APIとBase64埋め込み、どちらが速いですか

一回きりの問い合わせなら体感差はほとんどありません。差が出るのは同じPDFに何度も問い合わせる場合で、Files APIならエンコードと転送を初回だけで済ませられます。

PDFの一部のページだけを解析させたいときは

Files API・PDF support自体にはページ範囲を絞る機能はありません。ページ数が多いPDFは、必要な範囲だけを事前に抽出して別のPDFとして渡す運用が現実的です。

まとめ

Files APIは、PDFを含むファイルをfile_idで使い回すための仕組みです。一回きりの問い合わせにはURL参照やBase64埋め込みで十分ですが、同じPDFに繰り返し問い合わせる、あるいは複数のリクエストから参照する場合はFiles APIが向いています。導入時は、リクエストペイロード全体に掛かる32MB・ページ数の上限を先に確認します。加えてAmazon Bedrock・Google CloudではFiles API自体が使えない基盤ごとの違いも把握しておくと、実装時のエラーを減らせます。大量処理に発展させる段階では、Prompt cachingとBatch APIを組み合わせるとコストを抑えられます。

Claude Files APIでPDFを処理する方法 — アップロードから解析まで

はじめに

前提条件

PDFをClaudeに渡す3つの方法 — どれを選ぶか

手順1: PDFをFiles APIにアップロードする

手順2: file_idをメッセージで参照する

PDFのサイズとページ数の制限を確認する

PDFの処理の仕組みとコスト試算

大量のPDFを扱うときの最適化

ファイルを一覧・取得・削除する

よくあるつまずき

ダウンロードしようとして400エラーになる

file_idのブロック種別を間違えて400エラーになる

ファイル名で400エラーになる

組織のストレージ上限(500GB)に達する

Bedrock Converse APIでPDFの図表が読めない

claude.aiアプリでPDFを読ませたいとき

よくある質問

Files APIは無料ですか

アップロードしたPDFは編集できますか

Files APIとBase64埋め込み、どちらが速いですか

PDFの一部のページだけを解析させたいときは

まとめ

Tool RunnerでAnthropic APIのツール呼び出しループを自動化する

Claude JSONモードの使い方 — structured outputsでJSON出力を固定する

Claude RAGの構築ガイド — 埋め込みと引用付き回答の実装

Claude Batch APIの使い方 — 料金50%引きと非同期処理

ダリオ・アモデイとは — Anthropic CEOの経歴とAI観を読み解く

Claude APIのエラーハンドリング設計 — コード別対処とリトライ実装

はじめに

前提条件

PDFをClaudeに渡す3つの方法 — どれを選ぶか

手順1: PDFをFiles APIにアップロードする

手順2: file_idをメッセージで参照する

PDFのサイズとページ数の制限を確認する

PDFの処理の仕組みとコスト試算

大量のPDFを扱うときの最適化

ファイルを一覧・取得・削除する

よくあるつまずき

ダウンロードしようとして400エラーになる

file_idのブロック種別を間違えて400エラーになる

ファイル名で400エラーになる

組織のストレージ上限(500GB)に達する

Bedrock Converse APIでPDFの図表が読めない

claude.aiアプリでPDFを読ませたいとき

よくある質問

Files APIは無料ですか

アップロードしたPDFは編集できますか

Files APIとBase64埋め込み、どちらが速いですか

PDFの一部のページだけを解析させたいときは

まとめ

関連する記事

Tool RunnerでAnthropic APIのツール呼び出しループを自動化する

Claude JSONモードの使い方 — structured outputsでJSON出力を固定する

Claude RAGの構築ガイド — 埋め込みと引用付き回答の実装

Claude Batch APIの使い方 — 料金50%引きと非同期処理

ダリオ・アモデイとは — Anthropic CEOの経歴とAI観を読み解く

Claude APIのエラーハンドリング設計 — コード別対処とリトライ実装