Claude Files API完全解説：ファイルを事前アップロードしてAPIコストを削減する

TL;DR

• ファイルを事前アップロード → file_id で参照 → 毎回base64エンコード不要
• 同じPDF・コードベースを繰り返し使うワークフローでトークンコストを大幅削減
• Code Execution Toolと組み合わせると「CSVをアップロードして分析」が1APIコールで完結
• GA済み。betaヘッダーは不要になり、アップロード時に有効期限を指定できるようになりました

---

概要

Claude Files API は、2025年5月22日にbetaとして公開されたファイル管理APIです。PDFや画像・テキストファイルを事前にアップロードしておき、Messages APIから file_id で参照できます。

従来は毎回ファイルをbase64エンコードしてリクエストペイロードに含める必要がありましたが、Files APIによりファイルの送信コストが初回アップロードの1回だけになります。

2026年8月27日のSDK更新でFiles APIはGAとなり、files-api-2025-04-14 betaヘッダーは不要になりました。client.beta.files は client.files と同じ形を返すようになっています。旧ヘッダーを送り続けているコードもそのまま動くため、移行は任意です。

---

基本的な使い方

1. ファイルをアップロード

import anthropic

client = anthropic.Anthropic()

# PDFをアップロード
with open("specification.pdf", "rb") as f:
    response = client.files.upload(
        file=("specification.pdf", f, "application/pdf"),
        # 任意。3,600秒（1時間）〜7,776,000秒（90日）で指定できる
        expires_in_seconds=7 * 24 * 60 * 60,
    )

file_id = response.id
print(file_id)  # file_abc123...

2. file_id でメッセージに組み込む

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "file",
                        "file_id": file_id,
                    },
                },
                {
                    "type": "text",
                    "text": "この仕様書の要点を箇条書きで整理してください。"
                }
            ],
        }
    ],
)

---

Code Execution Tool との組み合わせ

# CSVをアップロード
with open("sales_data.csv", "rb") as f:
    file = client.files.upload(
        file=("sales_data.csv", f, "text/plain"),
    )

# アップロードしたCSVをPythonで分析
message = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    tools=[{"type": "code_execution_20260521", "name": "code_execution"}],
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {"type": "file", "file_id": file.id},
                },
                {
                    "type": "text",
                    "text": "このCSVを月別に集計して折れ線グラフを作成してください。"
                }
            ],
        }
    ],
    betas=["code-execution-2025-08-25"],
)

---

プロンプトキャッシュとの組み合わせ

繰り返し参照するファイル（仕様書・コードベース等）はFiles APIでアップロードし、さらにプロンプトキャッシュを適用することで二重のコスト削減が可能です。

messages=[
    {
        "role": "user",
        "content": [
            {
                "type": "document",
                "source": {"type": "file", "file_id": file_id},
                "cache_control": {"type": "ephemeral", "ttl": "1h"}  # 1時間キャッシュ
            },
            {"type": "text", "text": "質問内容"}
        ],
    }
]

---

ファイル管理

# アップロード済みファイル一覧
files = client.files.list()

# ファイルのメタデータを取得
file_info = client.files.retrieve_metadata(file_id)

# ファイルを削除
client.files.delete(file_id)

有効期限と上限

項目	値
有効期限の指定範囲	3,600秒（1時間）〜7,776,000秒（90日）
期限を指定しない場合	失効しない（expires_at は null）
失効後の挙動	本体は404。メタデータは最大30日間参照できる
1ファイルの最大サイズ	500 MB
組織あたりの総容量	1 TB
ファイル系APIのレート制限	約500リクエスト/分

短期の分析用ファイルには expires_in_seconds を付けておくと、1TBの枠を手動整理せずに済みます。

---

対応ファイル形式

形式	MIMEタイプ
PDF	application/pdf
テキスト	text/plain
HTML	text/html
Markdown	text/markdown
CSV	text/csv
画像（PNG/JPEG/GIF/WebP）	image/*

---

参考リンク

• Files API Documentation | Anthropic
• Claude Platform Release Notes | Anthropic