Claude Files APIの容量上限 — 1ファイル500MB・組織1TBの総容量と消え方

Files APIには、1ファイルあたり500MB、組織全体で1TBという2段階の容量上限があります。アップロード後のファイルは内容もファイル名も変更できず、更新には新規アップロードと旧ファイルの削除が必要です。ファイルが消える経路は、明示的な削除とexpires_in_secondsによる自動失効の2つに分かれます。

Files APIの容量上限 — 1ファイルと組織全体で別枠

Files APIは、ファイルを一度アップロードしてfile_idで繰り返し参照できるAnthropicの仕組みです。「ファイル上限」と「総容量」は別の枠で、超えたときに返るエラーも違います。

ここでの数字はAPIのFiles機能のものです。claude.aiのチャット添付やProjects、Claude Codeの上限は別の仕組みで、この表の値は当てはまりません。経路ごとの上限はClaudeファイル上限の一覧で比べています。

表の3つに加えて、自動失効の指定幅と呼び出し頻度にも上限があります。

削除せずに使い捨てる運用だと、個々のアップロードは成功し続けるので、組織全体の1TB上限へ近づいていることに気づきにくくなります。

容量とは別に、400になる経路もあります。ファイルサイズがコンテキストウィンドウを超えた場合で、500MBのプレーンテキストを/v1/messagesに渡すとこのエラーになります。アップロードが成功しても、Messagesで使えるとは限りません。

大量のアップロード・削除を一括で回すときは、約500回/分を超えないよう間隔を空けます。

容量は組織単位で数えますが、アップロードしたファイルの可視範囲はワークスペース単位です。そのワークスペースにアクセスできるAPIキーなら、誰でもそのファイルを参照できます。

Files APIの操作自体(アップロード・ダウンロード・一覧取得・メタデータ取得・削除)はすべて無料です。ただし、自分でアップロードしたファイルは"downloadable": falseで、ダウンロードできるのはスキルやコード実行ツールが作ったファイルだけです。理由はFiles APIでダウンロードできない理由にまとめています。課金が発生するのは、ファイルの内容をMessagesリクエストに含めたときのinput tokenだけです。容量上限は課金とは別レイヤーの制約です。

この容量上限が掛かるのは、Files APIが使える基盤に限られます。Claude API・Claude Platform on AWS・Microsoft Foundry(Hosted on Anthropicデプロイのみ)の3つが対象で、いずれもGAです。Amazon BedrockとGoogle CloudにはFiles APIがなく、ファイルはBase64で毎回埋め込みます。この2基盤には本記事の容量上限そのものが存在しません。

PDFをMessagesに渡す場合は、Files APIの容量とは別に、リクエスト全体で32MBの上限があります(プラットフォームで異なります)。ページ数の上限は、コンテキストウィンドウが1Mトークン未満のとき100ページ、それ以外は600ページです。これらはPDF以外に同じリクエストで送る内容も含めた総量に掛かります。

大きなPDFは、Files APIにアップロードしてfile_idで参照すると、リクエスト本体を小さく保てます。Base64で埋め込んだデータも、リクエストの32MB枠に数えられます。

ただしfile_id経由でも、密度の高いPDFはページ数の上限より先にコンテキストウィンドウを埋めることがあります。小さな文字のページ、複雑な表、図版の多いページが該当します。Files APIを使っていても大きなPDFのリクエストは失敗することがあるので、そのときは文書を節ごとに分割します。

アップロード後のファイルは編集できない

Files APIのファイルは、アップロード後に内容もファイル名も変更できません。部分的な上書きや追記も用意されていません。内容を差し替える手順は次のとおりです。

ファイル名にも制約があります。1〜255文字までで、< > : " | ? * \ /の記号とUnicodeの0〜31番(制御文字)は使えません。外れるとアップロードが400エラー(Invalid filename)で失敗します。パスの区切りや引用符を含む元ファイル名をそのまま渡す実装では、このエラーに当たります。

ファイルはいつ消えるか — 削除と自動失効の2経路

消す方法は2つあります。APIで明示的に削除するか、アップロード時にexpires_in_secondsを指定して自動失効させるかです。

expires_in_secondsはアップロード時のフォームフィールドで、3,600秒(1時間)から7,776,000秒(90日)までの整数を指定します。

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/report.pdf" \
  -F "expires_in_seconds=86400"

この例は86,400秒(24時間)後に失効するファイルのアップロードです。失効したファイルの内容は、組織の1TB枠からも解放されます。一時的な解析用ファイルに最初から寿命を付けておけば、削除忘れによる容量圧迫を避けられます。

expires_atに達したあとの経過は、時間軸で見ると次のとおりです。

容量を可視化する — 一覧取得と監査ログ

削除漏れを防ぐには、定期的にファイル一覧を取り、古いファイルやexpires_atがnullのまま残っているファイルを洗い出します。一覧は新しい順で、1回の返却は既定20件・最大1,000件です。レスポンスのnext_pageをpageクエリパラメータへ渡すとページングできます。

既知のfile_idの集合が決まっているなら、ids[]に最大100件まとめて渡せます。このときは常に1ページで返り、pageやlimitとは併用できません。存在しないIDは黙ってdataから除かれるので、リクエストしたIDと返ってきたIDを突き合わせて漏れを確認します。

組織でCompliance APIを有効にしている場合は、Activity Feedでアップロード・内容のダウンロード・削除の履歴を追えます。対象はClaude APIキーまたはClaude Consoleから行った操作で、活動名はplatform_file_uploaded・platform_file_content_downloaded・platform_file_deletedです。どのユーザーまたはAPIキーが、いつアップロードしたかが分かるので、容量を圧迫している元を特定する手掛かりになります。

記録されない操作が2種類あります。1つは一覧取得とメタデータ取得で、容量監視に使う読み取りはログに残りません。もう1つはCompliance APIが無効だった間の操作で、後から復元もできません。容量監視を始めるなら、有効化を先に済ませておきます。AWS上のClaude Platformでは、監査にAWS CloudTrailのデータイベントを使います。

容量とライフサイクルでよくあるつまずき

ベータヘッダーを付けたままexpires_atが取れない

古い実装でanthropic-beta: files-api-2025-04-14を付けたままだと、expires_atがレスポンスに含まれません。Files APIはベータを終えており、このヘッダーは不要です。付けたままでも動作は続き、ベータ形式のレスポンスが返ります。

ヘッダーを外すと一覧は{ data, next_page }の形に変わり、expires_atが常に返ります(期限なしはnull)。同時にbefore_idとafter_idは400エラーになるので、ページングはpageで書き直します。SDKではclient.beta.filesではなくclient.filesを呼びます。Python 1.2.0、TypeScript 0.122.0以降などの新しいSDKでは、client.beta.filesもこのヘッダーを送りません。

ヘッダーを外すと、アップロード時のファイル部分のContent-Typeも任意になり、省略すると種別が自動判定されます。ヘッダー付きでは必須でした。

Managed Agents用のmanaged-agents-2026-04-01だけを付けた場合は例外です。GET /v1/filesでbefore_idとafter_idが引き続き使えます。

このときのレスポンスには、next_pageと並んでhas_more・first_id・last_idも入ります。before_idとafter_idはpageやids[]とは併用できません。Managed Agentsの後続のベータ版では、通常の形に戻ります。

Files APIを含むAnthropic API全体の料金体系やモデル選びはAnthropic API完全ガイドにまとめています。

まとめ

容量・失効・リクエスト上限は別々の仕組みで効くので、エラーが出たら、まず413か400か、種別は何かを見て、どの上限に当たったかを切り分けます。失効したファイルは、メタデータが残る30日の間も使えません。