Claude Files API完全ガイド：一度アップロードするだけでどこからでも参照可能（GA版）

Claude Files API を使うと、ファイルを一度 https://api.anthropic.com/v1/files にアップロードして file_id を取得し、以降は毎回コンテンツを再送信する代わりに、その ID を任意の Messages リクエストで参照できるようになります。2026年8月20日時点で、これは Claude Platform 上で一般提供されています。ベータヘッダーは不要で、組織あたり 1 TB のストレージ、そしてレート制限はベータ版の 5 倍です。Anthropic はこの変更をプロダクションエージェントに関する投稿で発表しました。computer use、ブラウザツール、Skills API の GA と合わせての発表です。

このガイドではライフサイクル全体を扱います。アップロード、メッセージ内でのファイル参照、生成された出力のダウンロード、有効期限、ワークスペースのセキュリティモデル、そして本番環境でぶつかる制限です。ここでのすべてのステップは HTTP 呼び出しなので、コーディングエージェントを使えばフロー全体を、一回限りの curl コマンドの山ではなく Apidog CLI のテストシナリオに変換できます。

Files API の役割

Files API は、Claude API 向けの「一度作成して何度も使う」ストレージ層です。これが解決するのは特定のコストです。たとえば、同じ 40 ページの PDF について数百件のリクエストで質問するアプリがある場合、毎回その PDF を再アップロードすると帯域幅が無駄になり、クライアントコードも複雑になります。Files API を使えば、次のことができます。

Claude Files API lifecycle: upload, reference by file_id, download, delete

Anthropic のストレージにファイルをアップロードし、一意の file_id を受け取る
Messages リクエスト内でコンテンツブロックを通じてその ID を参照する
スキルやコード実行ツールが生成したファイル（チャート、スプレッドシート、スライド）をダウンロードする
一覧取得、メタデータ取得、削除の各操作で管理する

エンドポイントの構成はわずかです。

操作	エンドポイント
ファイルをアップロード	`POST /v1/files`
ファイルを一覧取得	`GET /v1/files`
ファイルのメタデータを取得	`GET /v1/files/{file_id}`
ファイルのコンテンツをダウンロード	`GET /v1/files/{file_id}/content`
ファイルを削除	`DELETE /v1/files/{file_id}`

すべて標準の x-api-key と anthropic-version: 2023-06-01 ヘッダーで動作します。Messages API 自体が初めての方は、Claude Opus 5 API ガイドで認証とリクエスト形式の基本を扱っています。

GA で変わったこと

Files API は数か月間、ヘッダーを必要とするベータ版でした。2026年8月20日の GA リリースでは、本番計画に関わる 4 つの点が変更されました。

What changed when the Claude Files API went GA

ベータヘッダーが不要。Claude API 上で標準ヘッダーのみでリクエストが動作します。
レート制限が 5 倍。ファイル操作は現在およそ毎分 500 リクエストが可能で、営業経由でより高い制限も利用できます。
組織あたり 1 TB のストレージ、1 ファイルあたりの上限は 500 MB。
プラットフォーム対応の拡大。Files API は Claude API 上で直接動作し、AWS 上の Claude Platform ではベータ版、Microsoft Foundry では Hosted on Anthropic デプロイメントを使用する場合に動作します。Amazon Bedrock や Google Cloud Vertex AI では利用できず、ゼロデータ保持契約の対象にもなりません。厳格な保持ポリシーを採用している場合は、それを踏まえて計画してください。

ファイルのアップロード

アップロードは JSON ではなく、マルチパートフォームリクエストです。

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"

レスポンスには、後でファイルを参照するために必要なものがすべて含まれます。

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "report.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2026-08-24T00:00:00Z",
  "downloadable": false,
  "expires_at": null
}

注目すべきフィールドが 2 つあります。あなたがアップロードしたものについては downloadable は false です。ダウンロードして取り戻せるのは、Claude がスキルやコード実行を通じて生成したファイルだけです。そして expires_at は、アップロード時に有効期限を設定しない限り null です（詳細は後述）。

後述の Apidog CLI テストでは、アップロードのステップで id を変数として保存するため、以降のすべてのリクエストはハードコードされた文字列ではなく {{claude_file_id}} を参照します。

メッセージ内でのファイル参照

一度アップロードすると、ファイルはその種類に応じて 3 つのコンテンツブロックタイプのいずれかを通じて Messages リクエストに組み込まれます。

ファイル種別	MIME タイプ	コンテンツブロック
PDF、プレーンテキスト	`application/pdf`、`text/plain`	`document`
画像	`image/jpeg`、`image/png`、`image/gif`、`image/webp`	`image`
データセット、その他すべて	さまざま	`container_upload`（コード実行ツール）

PDF 要約リクエストは次のようになります。

curl -X POST 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",
    "max_tokens": 1024,
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Summarize this document."},
        {"type": "document", "source": {"type": "file", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"}}
      ]
    }]
  }'

document ブロックはオプションの title、context、citations フィールドも受け付けるので、アップロードしたファイルに対して引用出力を有効にできます。画像の場合は、同じ source の形でブロックタイプを image に置き換えます。スプレッドシート、読むのではなく分析したい CSV、あるいは document ブロックが受け付けない形式については、container_upload を使ってファイルをコード実行ツールに渡します。

形式に関する注意が 1 つあります。.docx と .xlsx は document ブロックでは直接サポートされていません。画像解析と引用を維持したい場合は Word ファイルを PDF に変換するか、プレーンテキストを抽出してインラインで送信してください。

生成されたファイルのダウンロード

ダウンロードエンドポイントは入力用ではなく出力用です。Claude がコード実行でチャートを作成したり、スキルを通じてスプレッドシートを生成したりすると、レスポンスの bash_code_execution_tool_result ブロック内に file_id が含まれます。その ID はダウンロード可能です。

curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  --output chart.png

自分でアップロードしたファイルをダウンロードしようとすると 400 が返ります。リトライロジックを組む前にメタデータの downloadable フラグを確認しましょう。サポートチケットを 1 件節約できます。この「アップロードして入力、生成して出力」というループは、新たに GA となった Skills API ワークフローの中核であり、スキルが生成した Office ドキュメントを同じエンドポイント経由で取得します。Claude Skills のガイドでは、スキルとは何か、どのように実行されるかを扱っています。

有効期限とファイルのライフサイクル

ファイルは、あなたが削除するか、アップロード時に設定した有効期限が切れるまで保持されます。

アップロード時のフォームフィールドとして expires_in_seconds を渡します。有効範囲は 3,600（1 時間）から 7,776,000（90 日）です。1 度だけ設定でき、後から変更はできません。
expires_at を過ぎると、コンテンツのダウンロードは 404 を返し、そのファイルを参照する Messages リクエストは推論前に失敗します。
メタデータは有効期限後も最大 30 日間は読み取り可能で、期限切れのファイルもその期間は一覧レスポンスに表示されます。フィルタリングする際は expires_at と現在時刻を比較してください。
ファイルを削除すると即座に削除され、元に戻せません。期限切れのコンテンツはストレージクォータから解放されますが、安全確認のためにしばらく保持される場合があります。つまり有効期限はライフサイクル管理のツールであり、削除保証のコントロールではありません。

セキュリティモデル：ファイルはワークスペーススコープ

これが API 全体で最も鋭い刃です。アップロードされたファイルは、エンドユーザー、会話、セッション単位ではなく、ワークスペース全体からアクセス可能です。同じワークスペース内のどの API キーでも、そこにアップロードされた任意のファイルを読み取れます。また、キーを別の場所に割り当てない限り、すべてのキーは組織の Default Workspace を共有します。

実践的なルールは次のとおりです。

エンドユーザーから file_id の値を受け取ってはいけません。ユーザーが指定した ID をそのまま使うと、アプリのあるユーザーが別のユーザーのアップロードを読み取れてしまいます。ファイル ID はサーバー側の参照として扱い、ユーザーとファイルの対応表は自前のデータベースで保持してください。
マルチテナントを構築するなら、テナントごとに 1 ワークスペース。ワークスペースが分離の境界です。各組織は最大 100 ワークスペースを利用でき、Anthropic のアカウントチームがそれを引き上げられます。

すでにコスト配分のためにテナント単位の API キーを追跡している場合（この話題はClaude API の請求額を削減する方法で詳しく扱っています）、同じワークスペース構成でファイル分離もそのまま得られます。

制限と課金

設計の基準となる数値です。

制限	値
最大ファイルサイズ	500 MB
組織ストレージ	1 TB
Files API レート制限	約 500 リクエスト/分
ファイル名の長さ	1〜255 文字
有効期限の範囲	1 時間〜90 日

課金は良心的です。ファイルのアップロード、ダウンロード、一覧取得、削除はすべて無料です。料金が発生するのは、ファイルのコンテンツが Messages リクエストに入るときだけで、通常の入力トークンとして課金されます。100 ページの PDF を 10 件のリクエストで参照すると、同じ入力トークンが 10 回分のコストになります。Files API が節約するのは帯域幅とクライアントの複雑さであり、トークン消費ではありません。トークン側を節約するには、ファイル参照をプロンプトキャッシュと組み合わせてください。

次のエラーに注意してください。ファイルが 500 MB を超えると 413、組織が 1 TB の上限に達すると 400、ファイルの種類がコンテンツブロックと一致しないとき（たとえば document ブロックに画像）は 400、ワークスペース外の ID は 404 です。

Claude Code に Apidog CLI で Files API をテストさせる

Files API は多段階で状態を持つフローなので、シェル履歴ではなく回帰テストで管理する価値があります。Claude Code や任意のコーディングエージェントは、Apidog CLI を通じてそのテストを構築して実行できます。まず一度セットアップします。

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

トークンは Apidog のアカウント設定、API Access Token から取得します。次にエージェントへ 1 つのプロンプトを与えます。

Use Apidog CLI on project <id>. Add the Files API endpoints (upload, list,
metadata, download, delete) and POST /v1/messages, with x-api-key from
{{ANTHROPIC_API_KEY}} and the anthropic-version header. Build a test scenario:
upload with expires_in_seconds=3600 and assert expires_at is set, save the id
as claude_file_id, reference it in a Messages call and assert 200, delete it,
then assert the metadata call returns 404. Run it and summarize any failures.

実行されるコマンドはこちらです（Apidog CLI 2.2.7 で確認済み）。

apidog cli-schema get endpoint-create
apidog endpoint create --project <id> --file files-upload.json
apidog test-scenario create --project <id> --name "Files API lifecycle" --priority 1
apidog test-scenario import-steps <scenarioId> --project <id> --source endpoint \
  --ids <uploadId>,<messagesId>,<deleteId>,<metadataId> --sync manual
apidog cli-schema validate test-scenario-update --file lifecycle.json
apidog test-scenario update <scenarioId> --project <id> --file lifecycle.json
apidog run -t <scenarioId> --project <id> -e <envId> \
  --env-var "ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY" -r cli,json

エージェントは各エンドポイントに対して endpoint create を繰り返し、実行前に変数抽出とアサーションをシナリオに書き込みます。後でテストファイルを切り替えるときは、すべてのリクエストではなく 1 つのアップロードステップを変更するだけで済みます。アップロードレスポンスのモック（apidog mock create）も依頼すれば、バックエンドのプロキシが存在する前にフロントエンドチームが JSON の形を入手できます。同じ apidog run の行を -r junit 付きで使えば CI に組み込めます。Claude Code における Apidog CLI のガイドでは、エージェントのセットアップを端から端まで扱っています。

FAQ

ベータヘッダーはまだ必要ですか？いいえ。2026年8月20日の GA 以降、Files API は Claude API 上で標準の x-api-key と anthropic-version ヘッダーで動作します。SDK やプロキシが古い files ベータヘッダーをまだ固定している場合は、アップグレード時に削除してください。

ファイルの内容を更新できますか？いいえ。ファイルはアップロード後に不変です。新しいファイルをアップロードし、参照先を新しい ID に向けてから、古いものを削除してください。

Files API は Bedrock や Vertex AI で動作しますか？いいえ。動作するのは Claude API、AWS 上の Claude Platform（ベータ）、そして Hosted on Anthropic デプロイメントを用いた Microsoft Foundry です。Bedrock と Vertex では、依然としてインラインの base64 コンテンツが必要です。

Files API は Skills API が出力に使うものと同じですか？はい。スキルとコード実行ツールは生成したドキュメントを同じファイルストアに書き込み、GET /v1/files/{file_id}/content を通じてダウンロードします。そのワークフローの Skills API 側は自動テストと相性が良いです。

まとめ

Files API の GA により、同じドキュメントを毎回のリクエストに base64 で詰め込む最後の言い訳がなくなりました。一度アップロードし、ID で参照し、有効期限を設定し、テナントのファイルは別々のワークスペースに保ちましょう。API の構成は 5 つのエンドポイントだけで、そのすべてが数分でテスト可能です。コーディングエージェントに Apidog CLI でフローをスクリプト化させ、file_id を変数でつなぎ、ユーザーがエッジケースを見つける前にライフサイクル全体を CI に組み込んでおきましょう。