「PDF を毎回 base64 にエンコードして送るのが面倒」「同じ仕様書を 100 回呼ぶエージェントを作りたいけど、トークン代がえぐい」。AIエージェントを実運用に乗せようとすると、ほぼ全員がこの壁にぶつかります。
2024年10月にβ提供が開始され、2026年5月時点で機能が大幅拡張された Anthropic Files API は、この問題を「ファイルを一度アップロードしておき、以降は file_id で参照する」という設計で解決します。RAG を組まなくても済むケースが増え、AIエージェントの設計図が変わりつつあります。
本記事は Files API の 実装コード12本 を中心に、Document/Vision との違い、Citations API との連携、AssistantsAPI（OpenAI）との比較、コスト試算までを一気に学べる実践ガイドです。
結論：Files API は「同じファイルを何度も参照するエージェント」で効く
先に結論を3行で。
- 使うべきケース：同一ファイルを複数ターン・複数エージェントで参照する／PDF が30MB近い／Citations と組み合わせる
- 使わなくていいケース：1回限りの単発処理／ファイルが小さい（数MB以下）／ユーザーが毎回違うファイルを投げてくる
- 誤解されがちな点：Files API はベクトル検索ではない。アップロードしたファイルは Claude のコンテキストにそのまま投入される ので、長大ファイルでも入力トークンは消費する。”無料倉庫” ではない
つまり Files API の最大の価値は 「ネットワーク往復・base64 化のコスト削減」と「複数呼び出し間の参照一貫性」であって、RAG の完全代替ではない。ここを誤解すると見積もりが狂います。
Files API とは何か：3つの基本機能
Anthropic Files API は、Claude API に対してファイルを事前アップロードし、後続の Messages API 呼び出しで file_id として参照できる仕組みです。2026年5月時点のβ機能として、以下3つのコア機能を提供しています。
- アップロード：PDF / 画像 / テキスト / CSV / Excel などをマルチパートでアップロード
- 参照：Messages API の content ブロック内で
{"type": "document", "source": {"type": "file", "file_id": "..."}}として参照 - 削除：不要になったファイルを ID 指定で削除
対応ファイル形式は2026年5月時点で以下。
| カテゴリ | 対応形式 | 備考 |
|---|---|---|
| ドキュメント | PDF, TXT, MD | PDF は最大32MB・最大100ページ目安 |
| 画像 | JPEG, PNG, GIF, WebP | Vision モデル経由で解析 |
| 表計算 | CSV, XLSX (Beta拡張) | 2026年から拡張 |
| コード | 各種テキストベース言語 | 拡張子で言語推定 |
呼び出し時の HTTP ヘッダーには β機能を有効化するための anthropic-beta: files-api-2025-04-14 等が必要です（バージョン名は最新ドキュメントで要確認）。
コード集①：最小実装でファイルをアップロードして質問する
まずは “Hello, Files API”。手元の PDF を 1 本アップロードして、Claude に要約させるだけのコードです。
import anthropic
client = anthropic.Anthropic()
# 1. ファイルをアップロード
with open("./contracts/sample_contract.pdf", "rb") as f:
uploaded = client.beta.files.upload(
file=("sample_contract.pdf", f, "application/pdf"),
)
print("file_id:", uploaded.id)
# 2. file_id を参照して質問
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
betas=["files-api-2025-04-14"],
messages=[{
"role": "user",
"content": [
{"type": "document",
"source": {"type": "file", "file_id": uploaded.id}},
{"type": "text",
"text": "この契約書のリスク条項を3つ抜き出して箇条書きで。"}
]
}],
)
print(response.content[0].text)
ポイントは2つ。(a) client.beta.files.upload で帰ってくる id を保存しておけば、以降は何度でも参照できる。(b) content の type を "document" にすることで、Vision ではなく PDF テキスト抽出ルートに乗る（画像扱いではない）。
コード集②：複数ファイルを同時に参照する（マルチ文書比較）
契約書 A と契約書 B を比較するようなケース。file_id を複数渡せます。
file_a = client.beta.files.upload(
file=("contract_a.pdf", open("./contract_a.pdf", "rb"), "application/pdf")
)
file_b = client.beta.files.upload(
file=("contract_b.pdf", open("./contract_b.pdf", "rb"), "application/pdf")
)
resp = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=2048,
betas=["files-api-2025-04-14"],
messages=[{
"role": "user",
"content": [
{"type": "document",
"source": {"type": "file", "file_id": file_a.id},
"title": "契約書A（旧版）"},
{"type": "document",
"source": {"type": "file", "file_id": file_b.id},
"title": "契約書B（新版）"},
{"type": "text",
"text": "A と B の差分を表形式で出力してください。"
"条項番号・変更前・変更後・リスク評価の4列で。"}
]
}],
)
各 document ブロックに "title" を付けるのが地味に効きます。これを指定すると、Claude が回答内で「契約書A の第5条によると…」のように 引用元を明示しやすくなる。AIエージェントで複数文書を扱うときの基本作法です。
コード集③：Citations API と組み合わせて出典付き回答を返す
Files API の真価が出るのが Citations との組み合わせ。Claude が回答時に「PDF の何ページ・何行から引用したか」を構造化された JSON で返してくれます。
resp = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
betas=["files-api-2025-04-14"],
messages=[{
"role": "user",
"content": [
{
"type": "document",
"source": {"type": "file", "file_id": file_a.id},
"title": "就業規則 2026年4月版",
"citations": {"enabled": True}
},
{"type": "text",
"text": "副業の届出ルールを、原文の引用付きで説明してください。"}
]
}],
)
for block in resp.content:
if block.type == "text":
print(block.text)
if hasattr(block, "citations") and block.citations:
for c in block.citations:
print(f" ↳ 出典: {c.document_title} / "
f"p.{c.start_page_number}-{c.end_page_number}")
これは法務・コンプライアンス系のエージェントで強烈に効きます。「ハルシネーション」と疑われたときに、即座に 出典ページ番号 を提示できるからです。Uravation で大手企業向けに Claude Code 研修をやっていても、「出典つき」を要求される案件は確実に増えています。
コード集④：画像 (Vision) として参照する
同じ Files API でも、画像は document ではなく "image" 型で参照します。
img = client.beta.files.upload(
file=("ui_mock.png", open("./ui_mock.png", "rb"), "image/png")
)
resp = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
betas=["files-api-2025-04-14"],
messages=[{
"role": "user",
"content": [
{"type": "image",
"source": {"type": "file", "file_id": img.id}},
{"type": "text",
"text": "このUIモックの問題点を5つ列挙してください。"}
]
}],
)
ここで誤解しやすいのは、「同一の file_id を image としても document としても使える」わけではないこと。PDF を image として参照しようとするとエラーになる。アップロード時の MIME と用途を一致させる必要があります。
コード集⑤：CSV / Excel をデータ分析させる
表計算ファイルは2026年から正式対応。「Code Interpreter なしでデータ分析」というユースケースが現実的になりました。
csv_file = client.beta.files.upload(
file=("sales_2025.csv", open("./sales_2025.csv", "rb"), "text/csv")
)
resp = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=2048,
betas=["files-api-2025-04-14"],
messages=[{
"role": "user",
"content": [
{"type": "document",
"source": {"type": "file", "file_id": csv_file.id},
"title": "2025年売上データ"},
{"type": "text",
"text": "月別・チャネル別の売上を集計し、"
"(1) 最も伸びたチャネル "
"(2) 落ち込んだ月の仮説 "
"を分析してください。"}
]
}],
)
注意：Claude は CSV を テキストとしてコンテキスト投入するので、巨大な CSV（10万行など）はトークン爆発の元。1MB を超える表データは、(a) 事前に集計しておく、(b) Code Interpreter API ベータ機能と組み合わせる、のどちらかが現実解です。
コード集⑥：ファイル一覧取得・削除・期限管理
運用で必須なのが、登録済みファイルの管理。Anthropic 側の Files ストレージは「アップロードしっぱなし」だと積み上がるので、削除運用は最初から設計に入れます。
# 一覧取得
files = client.beta.files.list(limit=100, betas=["files-api-2025-04-14"])
for f in files.data:
print(f.id, f.filename, f.size_bytes, f.created_at)
# 個別取得
meta = client.beta.files.retrieve_metadata(
file_id="file_abc123",
betas=["files-api-2025-04-14"]
)
print(meta.mime_type, meta.size_bytes)
# 削除
client.beta.files.delete(
file_id="file_abc123",
betas=["files-api-2025-04-14"]
)
運用ルール例：
- クライアントごとに prefix を持つ命名規則（例:
{client_id}_{yyyymmdd}_{doc_type}.pdf） - アップロード後 file_id を必ず自社DBに保存（Anthropic 側ストレージは “正” にしない）
- 30日経過 / 商談クローズ / 契約終了 のいずれかでバッチ削除する cron を組む
コード集⑦：file_id を Memory / セッション間で再利用するエージェント
ここから「エージェント設計の話」になります。Files API の最大の旨みは「同じ file_id を複数セッションで使い回せる」ところ。
# 1回目（初回アップロード）
def ensure_uploaded(local_path: str, db) -> str:
cached = db.get_file_id_by_hash(hash_of(local_path))
if cached:
return cached
with open(local_path, "rb") as f:
up = client.beta.files.upload(
file=(os.path.basename(local_path), f,
guess_mime(local_path)),
)
db.save_file_id(hash_of(local_path), up.id)
return up.id
# エージェント本体
def ask_with_doc(local_path: str, question: str) -> str:
fid = ensure_uploaded(local_path, db=my_db)
resp = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
betas=["files-api-2025-04-14"],
messages=[{
"role": "user",
"content": [
{"type": "document",
"source": {"type": "file", "file_id": fid}},
{"type": "text", "text": question}
]
}],
)
return resp.content[0].text
このパターンは「同じマニュアル PDF を 100 人のサポート担当者が問い合わせる」ようなSaaS型ユースケースに刺さります。100 回 base64 を送らずに済む。
コード集⑧：tool_use / Agent SDK と組み合わせる
Anthropic Claude Agent SDK や Tool Use と組み合わせると、「ファイル指定 → 取得 → 解析」の自律エージェントが組める。
tools = [
{
"name": "load_document",
"description": "ファイルIDを指定して内部資料を参照する",
"input_schema": {
"type": "object",
"properties": {
"file_id": {"type": "string"}
},
"required": ["file_id"]
}
},
{
"name": "list_my_files",
"description": "アップロード済みファイル一覧を返す",
"input_schema": {"type": "object", "properties": {}}
}
]
# Agent ループ内で tool_use が来たら、対応する file_id を
# 次のターンの user content に "document" として差し込む
Agent SDK については Claude Agent SDK で自律エージェントを作る実装ガイド を参照してください。Files API と組み合わせると、「エージェントが自分の判断で社内資料を読みに行く」挙動が組めます。
コード集⑨：Web fetch / URL fetch との切り分け
2026年に追加された Web Fetch / URL Content tool との切り分けも重要。
| ケース | 推奨 | 理由 |
|---|---|---|
| 社内PDF・自前ドキュメント | Files API | セキュリティ・繰返し利用 |
| 公開Webページの読み取り | URL Content / Web Fetch | 更新追従・前段クロール不要 |
| 毎回違うユーザー添付 | 従来の base64 直送 or 短期Files | キャッシュ意味なし |
| 巨大なナレッジ全体検索 | RAG（Agentic RAG） | ベクトル検索が必要 |
「全部 Files API でいけそう」は誤解で、ナレッジが数百〜数千ファイルあるなら RAG パターンの方が筋がいい。詳しくは Agentic RAG 4パターン比較ガイド を読んでから設計判断してください。
コード集⑩：RAG 代替パターン（Files API + Citation 検索）
とはいえ「100ファイル前後・各〜10MB」くらいの中規模ナレッジなら、Files API だけで RAG 風の挙動を組めます。
# 1. 全ファイルをアップロード（初回のみ）
file_ids = []
for path in glob.glob("./knowledge/*.pdf"):
up = client.beta.files.upload(
file=(os.path.basename(path), open(path, "rb"), "application/pdf")
)
file_ids.append({"path": path, "id": up.id})
# 2. ユーザー質問に対して「絞り込みLLM」でファイル選定
def select_files(question: str, file_ids: list) -> list:
# 軽量モデルでファイル名・メタから関連ファイルを2-3本選ぶ
...
# 3. 選ばれたファイルだけ document として渡す
selected = select_files(user_q, file_ids)
content = [
{"type": "document",
"source": {"type": "file", "file_id": f["id"]},
"citations": {"enabled": True}}
for f in selected
]
content.append({"type": "text", "text": user_q})
これは “軽量LLMでルーティング → 本体LLM で深掘り” という、ベクトルDB を使わない実装パターンです。100ファイル程度なら、ベクトルDB を立てる運用コストよりこの方が安いことが多い。
コード集⑪：プロンプトキャッシングと組み合わせて単価を下げる
Files API の content ブロックは prompt caching の対象にできます。同じ file_id を何度も使うエージェントなら、キャッシュ指示を入れるだけで入力単価が大きく下がる。
resp = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
betas=["files-api-2025-04-14"],
system=[{
"type": "text",
"text": "あなたは契約レビューの専門家です。",
"cache_control": {"type": "ephemeral"}
}],
messages=[{
"role": "user",
"content": [
{"type": "document",
"source": {"type": "file", "file_id": file_a.id},
"cache_control": {"type": "ephemeral"}},
{"type": "text",
"text": "第3条のリスクを評価してください。"}
]
}],
)
2回目以降のリクエストでは、キャッシュヒットした部分の入力トークンが大幅割引（最大90%減）になります。「同じ就業規則 PDF を 1日200回問い合わせるFAQボット」のようなケースで、月数万円の差になります。
コード集⑫：エラーハンドリングとレート制限対応
最後に運用必須のエラー処理。
from anthropic import APIError, APIStatusError, RateLimitError
import time
def upload_with_retry(path: str, max_retry=3):
for attempt in range(max_retry):
try:
with open(path, "rb") as f:
return client.beta.files.upload(
file=(os.path.basename(path), f, guess_mime(path)),
)
except RateLimitError:
wait = 2 ** attempt
print(f"rate limited, retry in {wait}s")
time.sleep(wait)
except APIStatusError as e:
if e.status_code == 413: # File too large
raise ValueError(f"Too large: {path}")
if e.status_code in (500, 502, 503):
time.sleep(2 ** attempt)
continue
raise
raise RuntimeError("upload failed after retries")
特に注意したい代表的エラー：
- 413 File too large：PDF は最大32MB目安。超えると即拒否。事前に
os.path.getsize()で弾く - 415 Unsupported media type：MIME が間違っている。upload 時の3要素タプル
(filename, fileobj, mime)の3つ目を必ず指定 - 404 file_id not found：削除済み or 別ワークスペースの ID。自社DBの ID が古い可能性を疑う
Document API / Vision API との違い（混乱しやすい）
ここを整理しないと、設計議論が噛み合わなくなります。
| 方式 | file_id 事前登録 | 主な用途 | 再利用 |
|---|---|---|---|
| Files API + document型 | 必要 | PDF / TXT / CSV を繰り返し参照 | ◎ |
| Files API + image型 | 必要 | 画像を繰り返し参照 | ◎ |
| Inline document (base64) | 不要 | 1回限りの単発PDF処理 | × |
| Inline image (base64) | 不要 | 1回限りの画像解析 | × |
| URL指定 (Web Fetch) | 不要 | 公開URLの動的読み取り | △（毎回再取得） |
つまり「Files API」という言葉は、従来の document/image 処理を file_id ベースで再利用可能にした上位機構と理解するのが正確です。「Document API と Files API は別物」ではなく、Files API は document/image を内包しています。
OpenAI Assistants API との比較
「OpenAI の Assistants API のファイル機能と何が違うのか？」はよく聞かれる質問です。両者の設計思想は意外と違います。
| 観点 | Anthropic Files API | OpenAI Assistants API (Files) |
|---|---|---|
| 位置づけ | Messages API の補助機構 | Assistant オブジェクトに紐づく |
| RAG的検索 | なし（コンテキスト直投入） | あり（File Search tool で自動チャンク+検索） |
| 引用情報 | Citations API で取得（ページ番号付き） | annotations で取得 |
| 状態管理 | file_id ベース（軽量） | Assistant / Thread / Run / File (重め) |
| 自分でRAG組む必要 | △（中規模ならFilesだけでOK） | ×（File Searchが裏で組んでくれる） |
ざっくりした使い分け：
- 引用付き・厳密な参照が必要 → Anthropic Files + Citations
- とにかくナレッジ放り込んで検索したい → OpenAI Assistants File Search
- 自前RAGを完全制御したい → どちらでもなく、ベクトルDB自前構築
Anthropic は意図的に「自前RAGを組むときの邪魔をしない、軽い基盤」に振っている印象。エンタープライズで複雑な検索ルールを組み込みたい場合、Anthropic の方が筋がいい設計に落とせます。
コスト試算：実際いくらかかるか
運用想定でざっくり計算してみます。前提：
- 就業規則PDF（50ページ、推定 4万トークン）を1ファイル
- 1日200回、社内FAQ に問い合わせ
- 1問あたり平均回答 500トークン
- モデル：Claude Sonnet 4.6（仮に入力 $3/MTok、出力 $15/MTok）
キャッシュなし：
- 入力：4万 × 200 = 800万トークン × $3 = $24/日 = 約3,600円/日
- 出力：500 × 200 = 10万 × $15 = $1.5/日
- 合計：約3,750円/日 = 月11万円程度
Prompt Caching + Files API 構成：
- キャッシュ書込（1日1回）：4万 × $3.75 / 1M ≒ $0.15
- キャッシュ読込（199回）：4万 × 199 × $0.30 / 1M ≒ $2.4
- 出力：$1.5
- 合計：約4ドル/日 = 月600円程度
※Anthropic 公式の単価は時期で変動します。最新は必ず anthropic.com/pricing で確認してください。傾向として 同じファイルを繰り返し参照するユースケースでは2桁単位でコスト削減できるのが Files API + Caching の威力です。
実装時にハマる10の落とし穴
- beta ヘッダー忘れ：
betas=["files-api-2025-04-14"]（SDKが自動付与しない場合あり） - MIME 指定漏れ：3要素タプルの3つ目を必ず指定。
"application/pdf"など - PDF を image として参照：エラー。document 型で参照する
- title 未指定で複数文書比較：Claude が「文書A」「文書B」を区別できず混乱する
- 巨大CSV をそのまま投入：トークン爆発。事前集計が原則
- file_id を自社DBに保存していない：Anthropic側ストレージを”正”にしない。常にローカルに ID 台帳を持つ
- 削除運用なしで放置：1年運用すると数千ファイルが滞留。クライアントごとの cron 削除を最初から組む
- Citations を有効化していない：「引用情報出ない」と相談される8割がこれ。
"citations": {"enabled": True}必須 - Prompt Caching を入れていない：同じファイルを使うのに毎回フル課金は、設計事故
- ワークスペースの分離忘れ：クライアントAのファイルにクライアントBがアクセスできる事故。API キーを分けるかメタデータで隔離
AIエージェントでの典型ユースケース5選
実際に動いている／設計中のユースケースを紹介します。プロンプト設計のパターンは AIエージェントのプロンプト設計パターン も合わせて読むと、エージェント全体の設計が腑に落ちます。
- 契約書レビューエージェント：契約書PDFをアップロード → 自動でリスク条項抽出 → 修正案生成 → Citations で根拠提示
- 社内マニュアルFAQボット：マニュアル群を Files に常駐 → Slack 質問に対し prompt caching でほぼ無料回答
- 監査調書補助エージェント：監査対象資料PDF＋会計データCSV → 異常検知＋ページ番号付き根拠出力
- UI/UXレビューエージェント：Figma書き出し画像を Files に投げて、デザインガイドラインPDFと突き合わせ
- 営業提案書アシスタント：過去の提案書を Files に蓄積 → 新規案件で「似た過去事例」を選定＋構成提案
失敗パターン3つ：私が踏んだ罠
正直に書くと、Files API は「とりあえず全部アップロードしておけば賢くなる」みたいなツールではありません。設計を間違えると、むしろコストが上がります。
失敗1：100ファイル全部投入してトークン爆発。Files API は 事前ベクトル検索しないので、document として渡したファイルはすべてコンテキストに乗ります。「全部つけといて、Claudeが必要なやつ選んでくれるでしょ」は、コスト的にも回答品質的にも崩壊します。ルーティングは自分で実装する必要がある。
失敗2：同じPDFを毎回アップロードし直す。file_id を自社DBに保存していないと、コードがバグった時に「とりあえず再アップロード」してしまいがち。Files API は uploadした瞬間に課金発生しないとはいえ、無駄なファイルが Anthropic 側に積み上がり、誰の所有か分からなくなる。最初から命名規則＋ID台帳を設計するのが正解。
失敗3：Citations を「有効化したのに出ない」と勘違い。Citations が出るのは、Claude が 実際に引用元を特定できた時だけ。質問が抽象的だったり、ファイル全体に薄く分散している話題だと citations 配列は空で返ってきます。「Citations が空なら、その回答はファクト由来ではなく一般知識からの推測」と疑う運用ルールを入れると、ハルシネーション対策として強力です。
Anthropic 公式情報源（必読）
本記事はAnthropic公式ドキュメントベースで書いていますが、API仕様は変わりやすいので、必ず一次ソースを確認してください。
- Anthropic Docs – Files API（最新仕様・対応形式・β有効化方法）
- Anthropic Docs – Citations
- Anthropic Docs – Prompt Caching
- Anthropic News（β機能の正式GA移行時期はここで告知）
導入チェックリスト：あなたのプロジェクトに Files API は必要か？
最後に、設計判断用のチェックリスト。3つ以上当てはまれば導入を検討する価値あり。
- □ 同じファイルを複数ターン・複数ユーザー・複数エージェントで参照する
- □ ファイルサイズが数MB〜30MBで、毎回base64エンコードが重い
- □ 出典・ページ番号付きの回答が業務要件にある
- □ Prompt Caching と組み合わせてコスト最適化したい
- □ ナレッジ規模が100ファイル前後で、ベクトルDB構築は過剰
- □ 法務・コンプラ・監査など、ハルシネーション許容度が低い領域
- □ Claude Agent SDK や Tool Use で自律エージェントを組む計画がある
逆に、ナレッジが数千ファイル規模・毎回違うファイル・1回限りの単発処理がメインなら、Files API より素直に RAG / 単発処理を組んだ方がいい。
まとめ：Files API は「同じものを何度も参照する」設計の核になる
本記事のキーポイントを3つに要約します。
- Files API は “再利用可能な document/image 参照” の基盤。RAG の代わりではなく、RAG を組むかどうかの下のレイヤーを最適化するもの
- Citations + Prompt Caching との組み合わせが本気の威力。出典付き＋90%コスト削減が同時に取れる
- 設計の8割は “削除運用・ID台帳・ルーティングロジック” 。API そのものより、周辺の運用設計が成否を分ける
AIエージェントを本気で業務に乗せるなら、Files API は避けて通れない基盤技術になります。本記事のコード12本をベースに、自社のユースケースに合わせて拡張してみてください。
この記事を読んで導入イメージが固まってきた方へ
Uravationでは Anthropic Files API・Claude Agent SDK を使った AIエージェント開発の研修・コンサル・PoC支援を行っています。「自社の文書群でPoCしたい」「Citations付きFAQボットを2週間で立ち上げたい」といった具体的なご相談は contact フォームからどうぞ。
著者：佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。著書『AIエージェント仕事術』。Claude Code・Anthropic API・AIエージェント設計を中心に、大手企業向けの研修・コンサルを月10社以上担当。
