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

はじめに

Claude Files APIは、PDFなどのファイルを一度アップロードし、返されたfile_idでClaudeに読み込ませるAnthropic APIの機能です。PDFを毎回base64エンコードして送る必要がなくなります。同じPDFへ繰り返し問い合わせる場合や、複数のリクエストで同じPDFを参照する場合に、ペイロードとエンコード処理を省けます。

Claude APIでPDFを読み込む最短の流れは2手順です。/v1/filesへPDFをアップロードしてfile_idを受け取り、Messages APIのdocumentブロックにそのfile_idを渡します。コードは後半の節に載せています。

本チュートリアルでは、PDFをアップロードしてClaudeに解析させる一連の流れを、実装コード付きで扱います。サイズとページ数の制限、コスト試算、ファイルの寿命管理、ワークスペース単位のアクセス範囲まで含めます。チャット画面でPDFを読ませたいだけなら、APIは不要です(末尾の節で扱います)。API全体の料金体系やモデル選択はAnthropic API完全ガイドにまとめています。

前提条件

• Anthropic APIキー(console.anthropic.comで取得)
• Files APIはベータを終えており、anthropic-beta: files-api-2025-04-14ヘッダーは不要です。古い記事やサンプルに残るヘッダーの扱いは、後半の移行の節で説明します
• PDF処理そのものは現行の全モデルで使えますが、Files APIが使える基盤は限られます(制限の節で扱います)

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

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

PDFが大きい場合も、リクエスト本体を小さく保つ手段としてFiles APIの利用が案内されています。

PDFをアップロードしてfile_idで参照する

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

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

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

const uploaded = await client.files.upload({
  file: await toFile(
    fs.createReadStream("/path/to/document.pdf"),
    undefined,
    { type: "application/pdf" },
  ),
});
console.log(uploaded.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 "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "messages": [{
      "role": "user",
      "content": [
        {"type": "document", "source": {"type": "file", "file_id": "'"$FILE_ID"'"}},
        {"type": "text", "text": "この文書の主な論点を教えてください"}
      ]
    }]
  }'

documentブロックにはtitle、context、citations({"enabled": true})を任意で足せます。引用付きの回答が欲しいなら、ここでcitationsを有効にします。

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

.docxや.xlsxはdocumentブロックが直接対応していない形式です。プレーンテキストに変換してメッセージ本文に含めるか、PDFに変換してから渡します。.csvや.mdのようなテキストファイルは、MIMEタイプをtext/plainと明示すればFiles APIにそのままアップロードできます。抽出した内容を構造化データとして取り出したい場合は、documentブロックとtool useを組み合わせます。組み合わせ方は高度なTool useで扱っています。

古いベータヘッダーが付いたコードはどうなるか

Files APIがベータだった時期のサンプルには、anthropic-beta: files-api-2025-04-14ヘッダーとclient.beta.filesが付いています。ベータ終了後の挙動は次の通りです。

移行は任意です。外すときはヘッダーを削るだけでなく、SDKではclient.beta.filesではなくclient.filesを呼びます。client.beta.filesがヘッダーを送らなくなったのは、次のSDKバージョン以降です。

• Python SDK 1.2.0 / TypeScript SDK 0.122.0 / Go SDK 1.68.0
• Java SDK 2.59.0 / Ruby SDK 1.67.0 / C# SDK 12.44.0

これより前のSDKは、betas引数を渡さなくてもclient.beta.filesからヘッダーを送ります。ページ送りのループがafter_id前提で書かれていれば、同時にpage方式へ書き換える必要があります。

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

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

32MBとページ数の上限は、PDF単体ではなくリクエストペイロード全体に対してかかります。他のPDFやテキストを同じリクエストに含めていれば、その分だけ余裕が減ります。

小さなフォントが多いページや複雑な表・図版を多く含むPDFは、ページ数の上限より先にコンテキストウィンドウを埋めることがあります。大きなPDFは、Files APIを使っていてもページ上限に届く前に失敗することがあります。この場合はセクションごとに分割するか、各ページが画像として処理されるため埋め込み画像を間引くと通りやすくなります。テキストファイルでも同様で、500MBのプレーンテキストを/v1/messagesに渡すと、コンテキストウィンドウを超えたとして400エラーになります。

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

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

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

各ページを画像に変換する際のラスタライズ寸法はサーバー側が決めるため、返ってきた座標をそのまま元のPDFページに重ねるとズレが生じることがあります。ズレが起きる仕組みと回避策はClaudeでPDFの座標がずれる原因と直し方にまとめています。

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

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

• Prompt cachingを使う: 同じPDFに複数の質問を投げるなら、documentブロックにcache_control: {"type": "ephemeral"}を付けます。付けた時点でキャッシュへ書き込まれ、2回目以降の問い合わせはキャッシュ読み込みになり、同じPDFを毎回フルコストで処理せずに済みます。仕組みの詳細はPrompt Cachingの解説で扱っています
• Message Batches APIでまとめて処理する: 大量のPDFに同じ質問を投げる場合は、個別にリクエストを打つよりBatch APIで非同期処理するほうが効率的です。結果の取得はバッチ完了後に別のリクエストで行います
• 配置とフォーマットを整える: PDFはプロンプトのテキストより前に置く、標準的なフォントを使う、ページの向きを正しく揃える、PDFビューアー上のページ番号で参照します

Files APIの操作そのものは無料です。対象はアップロード、ダウンロード、一覧、メタデータ取得、削除で、Messagesリクエストで使ったファイルの内容が入力トークンとして課金されます。

大量にアップロードする処理を組むときは、Files API自体のレート制限も見ておきます。ファイル関連の呼び出しは約500リクエスト/分に制限され、引き上げが必要なときは営業窓口への連絡が案内されています。

ファイルの一覧・削除と寿命の管理

アップロードしたファイルは、削除するかexpires_atに達するまで保持されます。一覧取得・メタデータ取得・削除が使えます。

# 一覧(既定20件・最大1,000件。次ページは next_page を page に渡す)
curl https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"
 
# 削除
curl -X DELETE "https://api.anthropic.com/v1/files/$FILE_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"

一覧は新しい順で返り、SDKには自動ページングのヘルパーがあります。特定のファイルだけ取りたいときは、最大100件のファイルIDをids[]クエリパラメーターで渡せます。ワークスペースに存在しないIDは黙って除外され、ids[]はpageやlimitと併用できません。

削除は取り消せません。削除後まもなくAPIからは参照できなくなりますが、進行中のMessages API呼び出しと関連するツール使用には残ることがあります。内容の変更や名前の変更もできないため、差し替えたいときは新しいファイルをアップロードして古いほうを削除します。

後始末を忘れたくないなら、アップロード時にexpires_in_secondsフォームフィールドで自動失効を設定できます。値は3,600秒(1時間)から7,776,000秒(90日)までの整数で、後から変更できません。

# 1日後に失効するファイルとしてアップロード
curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F "file=@/path/to/document.pdf" \
  -F "expires_in_seconds=86400"

失効後の挙動は、ダウンロードが404、そのファイルを参照するMessagesリクエストは推論の前に失敗します。メタデータは最長30日読め、一覧にも残ります。残った分はexpires_atを現在時刻と比べて除外します。保存容量の枠は失効で解放されます。失効はあくまで寿命管理の機能で、確実な削除を保証する手段ではありません。早く消したいときはDELETEを使います。

ファイルはワークスペース全体から見える

ここは運用で事故につながりやすい点です。アップロードしたファイルは、エンドユーザーや会話、セッション単位ではなく、ワークスペース全体からアクセスできます。そのワークスペースにアクセスできるAPIキーなら、どのキーからでも同じファイルを参照できます。サービスアカウントと、組織のロールでAPIアクセスが許されたユーザーは、追加していなくてもDefault Workspaceを使えます。

アプリケーションに組み込むなら、設計は次の3点になります。

• ユーザーから渡されたfile_idをそのまま受け付けない。ユーザーとファイルの対応表はアプリケーション側で持つ
• マルチテナントなら、テナントごとにワークスペースを分ける。ワークスペースがファイルの分離境界で、1組織あたり最大100個まで作れる
• 複数のワークスペースを操作できる認証情報では、anthropic-workspace-idヘッダーでリクエストごとに対象ワークスペースを選べる

なお、Files APIはゼロデータ保持(ZDR)の対象外です。PDF処理側は対象ですが、Covered Modelsは除外されます。保持要件のある組織は、PDF処理側とFiles API側で扱いが違う点に注意が必要です。Compliance APIを有効にしている組織では、アップロード・内容のダウンロード・削除がActivity Feedに記録されます。一覧取得とメタデータ取得は記録されません。

よくあるつまずき

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

ファイル種別とブロック種別が一致しないと、400エラーになります。内容自体が壊れているPDFは別の400エラー『Could not process PDF』になり、原因の切り分け方をまとめています。

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

ファイル名の上限は、公式ページ同士で記述が一致しません。ガイドのエラー処理では1〜255文字で、< > : " | ? * \ /とUnicode制御文字(0〜31)を含められません。一方、APIリファレンスのアップロードでは、filenameが空ならunnamedに拡張子を付けた名前へ置き換えられ、パスの最後の部分だけが残ります。レスポンスのfilenameは最大500文字です。空の名前がエラーになるのか置き換えられるのか、ページごとに違うため、1〜255文字で禁止文字を除いた名前を自分で付けて送る形が安全側の扱いです。

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

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

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

原因と2つの直し方はClaudeのBedrock ConverseでPDFの画像が読めない原因と直し方にまとめています。

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

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

まとめ

導入前の判断材料は、利用基盤がFiles APIに対応しているかと、file_idをワークスペース内のどのキーからでも使える前提で設計できるかです。