Claude Files APIの容量上限とファイルライフサイクル

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

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

Files APIとは、ファイルを一度アップロードしてfile_idで繰り返し参照できるAnthropicの仕組みです。容量の上限は2つのレイヤーに分かれています。

1ファイル500MBまでは許容されても、組織全体の合計が1TBに達していれば新しいアップロードは400エラーで拒否されます。ファイルを削除せずに使い捨てる運用では、個々のアップロードは問題なく成功し続けるため、組織全体の上限に近づいていることに気づきにくいという性質があります。

Files APIの操作自体(アップロード・ダウンロード・一覧取得・メタデータ取得・削除)はすべて無料です。課金が発生するのは、ファイルの内容をMessagesリクエストに含めて解析させたときのinput tokenだけです。容量上限は課金の話とは独立した、別レイヤーの制約だと理解しておきます。

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

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

Files APIのファイルは、アップロード後に内容もファイル名も変更できません。内容を差し替えたい場合は、新規アップロード+旧ファイル削除の順で対応します。部分的な上書きや追記のような操作は用意されていません。

ファイル名にも制約があります。1〜255文字までで、< > : " | ? * \ /の記号やUnicode制御文字(0〜31)は使えません。この範囲を外れると、アップロード自体が400エラー(Invalid filename)で失敗します。日本語のファイル名自体は禁止されていませんが、禁止記号を含みやすい元ファイル名(パスの区切りや引用符付きの資料名など)をそのまま使う実装では、意図せずこのエラーに当たることがあります。

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

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

expires_in_secondsはアップロード時のフォームフィールドで、3,600秒(1時間)から7,776,000秒(90日)までの整数を指定します。設定は一度きりで、アップロード後に変更できません。期限を設定しなかったファイルのexpires_atはnullのままで、明示的に削除するまで残り続けます。

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時間)後に自動失効するファイルをアップロードしています。一時的な解析用途に使うファイルには、こうして最初から寿命を切っておくと、削除忘れによる容量圧迫を防げます。

容量を可視化する — 監査ログとファイル一覧

削除漏れによる容量圧迫を防ぐには、定期的にファイルの一覧を取得し、古いファイルやexpires_atがnullのまま残っているファイルを洗い出す運用が有効です。一覧取得はレスポンスのnext_pageをpageクエリパラメータへ渡してページングします。既知のfile_idの集合が決まっている場合は、1件ずつ取得する代わりにids[]パラメータへ最大100件までまとめて渡せます。存在しないfile_idは結果から黙って除外されるため、リクエストしたIDと返ってきたIDを突き合わせて漏れを確認します。

組織でCompliance APIを有効にしている場合は、Activity Feedでアップロード・ダウンロード・削除の操作履歴を追跡できます。どのファイルがいつ・誰によってアップロードされ、いつ削除されたかを後から確認でき、容量圧迫の原因になっているアップロード元を特定する手掛かりになります。ただし有効化する前の操作は記録されず、後から復元もできません。容量監視を始めるなら、有効化を先に済ませておきます。

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

500MBの壁と1TBの壁を混同する

「Storage limit exceeded」のエラーを見て、アップロードしたファイル自体が大きすぎると勘違いするケースがあります。実際には1ファイルが500MB以内でも、組織全体の合計が1TBに達していれば同じエラーが起きます。数KBの小さなファイルをアップロードしただけでも、組織全体が1TBに達していればこのエラーは発生します。エラーメッセージの文言(413か400か)で、どちらの上限に当たっているかを見分けます。

expires_in_secondsを設定し忘れて容量を圧迫する

一時的な用途で使うファイルにも期限を設定しない運用では、削除を忘れたファイルが組織全体の容量にそのまま積み上がります。使い捨てのアップロードには、用途に応じたexpires_in_secondsを最初から設定しておくと、削除漏れが自然に解消されます。

失効直後にファイルが完全に消えたと思い込む

expires_atを過ぎてもメタデータは最大30日残ります。この間はファイルの一覧にも表示され続けるため、expires_atと現在時刻を比較して除外しないと、失効済みファイルを未失効として数えてしまいます。

ファイル名の変更を試みて400エラーになる

内容を差し替えたいだけのつもりでファイル名だけ変えようとしても、Files APIにリネームの操作はありません。新しいファイルをアップロードし、file_idを参照している側をすべて更新してから、古いファイルを削除する順番になります。

大量アップロードでレート制限に当たる

Files API関連の呼び出しは、おおむね500リクエスト/分に制限されています。大量のファイルを一括でアップロード・削除するバッチ処理では、容量上限より先にこのレート制限へ当たることがあります。

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

古い実装でanthropic-beta: files-api-2025-04-14ヘッダーを付けたままにしていると、expires_atフィールドがレスポンスに含まれません。このヘッダーはFiles APIがベータだった時期の名残で、指定は不要です。ヘッダーを外すと、レスポンス形式が{ data, next_page }のページングに変わり、expires_atも常に返るようになります(期限なしのファイルはnull)。SDKではclient.beta.filesではなくclient.filesを呼ぶことで、このヘッダーを送らずに済みます。

なぜ30日のメタデータ保持を挟むのか

expires_at到達直後にコンテンツへのアクセスを止めつつ、メタデータだけ30日残す設計は、即座の完全削除とは違う選択です。コンテンツを止めるのは、契約上・規約上の失効を確実に効かせるためです。メタデータを残すのは、失効したファイルが「いつ・何のために存在したか」を運用側が後から追える猶予を確保するためだと読めます。

この設計は、DELETEという明示的な操作とは役割が分かれています。DELETEは「今すぐ消す」という利用者の意思表示で、メタデータもその場で消えます。expires_in_secondsは「一定期間後に自動で失効させる」という予約で、猶予期間つきの緩やかな消え方をします。使い捨てのアップロードには自動失効、確実な即時削除が必要な場合は明示的なDELETEと、目的で使い分けます。

もう1つ見えてくるのは、失効の設定を後から変更できない理由です。アップロード時にしかexpires_in_secondsを指定できず、途中で延長も短縮もできません。もし後から変更できる仕様だったなら、失効前提で組んだ削除フローと、延長された実際の保存期間がずれるリスクが生まれます。固定にしておけば、アップロード時点で決めた保存期間がそのまま運用の前提になり続けます。

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

まとめ

Files APIの容量上限は、1ファイル500MBと組織全体1TBの2段階に分かれます。アップロード後のファイルは内容もファイル名も変更できず、更新は新規アップロードと旧ファイルの削除で行います。ファイルを消す経路は、即座に消える明示的な削除と、expires_in_seconds(1時間〜90日)による自動失効の2つです。自動失効はコンテンツへのアクセスを即座に止めますが、メタデータは最大30日残ります。使い捨てのアップロードには期限を設定し、確実な即時削除が必要ならDELETEを呼ぶ、という使い分けが実務上の基本になります。