Claude APIの Files API は、大きなドキュメントを一度アップロードして複数のAPIリクエストで再利用できる強力な機能です。このガイドでは、Files APIの基本概念から実装、そしてコスト削減の実践的な活用法までを網羅します。
Files APIとは？なぜ重要か
毎回のAPIリクエストで同じドキュメント（PDF、テキスト、画像）を送信していませんか？Files API を使うと、ドキュメントを一度Anthropicのサーバーにアップロードして、複数のリクエストで再利用できます。
これにより：
- トークンコストの削減：同じドキュメントを何度も送信せずに済む
- レスポンス速度の向上：キャッシュされたファイルはすばやく処理される
- API呼び出しの簡潔化：file_idで参照するだけでよい
特に、日報、契約書、技術仕様書など、定期的に分析するドキュメントがある場合に威力を発揮します。
Files APIの基本概念
ファイルID（file_id）とは
Files APIでアップロードしたファイルには、一意の file_id が割り当てられます。このIDを使って、後続のAPIリクエストでファイルを参照できます。
ファイルID例: file_123456789abcdef
サポートされるファイル形式
Files APIは以下の形式をサポートしています：
- PDF:
.pdf - テキスト:
.txt,.json,.csv,.jsonl,.xml,.md - 画像:
.jpg,.jpeg,.png,.gif,.webp - Office形式:
.docx,.xlsx,.pptx（注：テキスト抽出のみ） - その他:
.zip,.tar.gz（階層的なテキスト抽出）
各ファイルの上限は 20 MB です。
ストレージ制限と有効期限
アップロードしたファイルは 最大30日間 Anthropicのサーバーに保存されます。期間終了後、ファイルは自動削除されます。保存容量に制限はありませんが、30日以上保持する必要がある場合は定期的に再アップロードしましょう。
環境準備とインストール
Pythonライブラリのインストール
pip install anthropic python-dotenvAPIキーの設定
環境変数を使ってAPIキーを管理します。
export ANTHROPIC_API_KEY='your-api-key-here'または、.env ファイルを作成：
ANTHROPIC_API_KEY=your-api-key-here
Pythonコードで読み込む：
from dotenv import load_dotenv
load_dotenv()
api_key = os.getenv('ANTHROPIC_API_KEY')Files APIの実装チュートリアル
ステップ1：ファイルのアップロード
import os
from anthropic import Anthropic
# クライアント初期化
client = Anthropic()
# ファイルをアップロード
with open('sample_document.pdf', 'rb') as f:
response = client.beta.files.create(
file=(f.name, f, 'application/pdf')
)
file_id = response.id
print(f"File uploaded. ID: {file_id}")
print(f"Filename: {response.filename}")
print(f"Size: {response.size_bytes} bytes")期待される出力：
File uploaded. ID: file_abc123def456
Filename: sample_document.pdf
Size: 156789 bytes
ステップ2：file_idを使ったメッセージ送信
アップロード後、file_idを使ってファイルをメッセージに含めます。
# file_idを使ってメッセージを送信
file_id = "file_abc123def456" # ステップ1でアップロードしたID
message = client.beta.messages.create(
model="claude-opus-4-1",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "このドキュメントの要点を箇条書きで5つ教えてください。"
},
{
"type": "document",
"source": {
"type": "file",
"file_id": file_id
}
}
]
}
]
)
print(message.content[0].text)期待される出力：
このドキュメントの主要なポイント：
1. APIの基本認証について…
2. レート制限の仕様…
3. エラーハンドリング…
4. ベストプラクティス…
5. セキュリティ考慮事項…
ステップ3：ファイル一覧の取得
# アップロード済みのファイル一覧を取得
files = client.beta.files.list()
print(f"Total files: {len(files.data)}")
for file in files.data:
print(f"- {file.filename} ({file.id})")
print(f" Size: {file.size_bytes} bytes")
print(f" Created: {file.created_at}")ステップ4：ファイルの削除
# ファイルを削除
delete_response = client.beta.files.delete(file_id="file_abc123def456")
print(f"File deleted: {delete_response.deleted}")コスト削減の実践例
シナリオ：同じPDFを100回分析する場合
Files API使用前
- PDFサイズ：100 KB（約25,000トークン）
- リクエスト数：100回
- 総トークン：2,500,000トークン
Files API使用後
- アップロード時：25,000トークン（1回）
- 各リクエスト時：参照トークンのみ（約5,000トークン × 100回）
- 総トークン：525,000トークン
削減率：約79% のコスト削減です！
よくあるエラーと対処法
ファイルサイズ制限エラー
Error: File size exceeds 20MB limit
対処法：
- ファイルを分割する
- PDFの場合、不要なページを削除する
- 画像解像度を下げる
有効期限切れエラー
Error: File not found. File may have expired.
対処法：
- 30日以上経過したファイルは再アップロードする
- 長期保存が必要な場合は、独自のストレージバックエンド（S3など）を使用する
認証エラー
Error: Invalid API key or insufficient permissions
対処法：
- APIキーが正しく設定されているか確認
- APIキーに必要な権限があるか確認（organization管理画面で確認）
全体を振り返って
Claude API の Files API は、大量のドキュメント処理が必要なアプリケーションにおいて、コスト削減とパフォーマンス向上の両立を実現します。
活用シーン：
- 日々の契約書レビュー
- 定期的なログ分析
- 繰り返しの法務文書チェック
- 社内マニュアルの自動要約
API クイックスタートガイドで基礎を固めた上で、Files APIを組み込むことで、より実用的なアプリケーション構築が可能になります。また、自動キャッシュ機能ガイドと組み合わせることで、さらなるコスト最適化も期待できます。
さらに深掘りしたい方は、バッチ処理ガイドで非同期処理パターンも学ぶことをお勧めします。