やす研究所 AI Lab
戻る

Claude Files API実践2026:PDFを一度上げて使い回す実装手順

Claude Files API実践2026:PDFを一度上げて使い回す実装手順

同じPDFを毎回base64で送っていて、料金明細を見て青ざめたことはありませんか。私も一度、200ページ級の契約書を10回読ませて、想定の3倍のトークン請求が来たことがあります。原因はシンプルで、ドキュメントを毎回投げ直していたから。

この記事では Claude Files API を使って「1回アップロード → file_id を使い回す」構成に切り替える手順を、Python の実コード付きで解説します。読み終わる頃には、あなたのPDF処理コストは目に見えて下がっているはずです。

結論:Files API は「使い回すPDF」を持つ全員が今すぐ入れるべき

先に結論から書きます。同じドキュメントを2回以上参照するワークフローがあるなら、Files API を入れない理由がありません。

理由は3つあります。ネットワーク転送とbase64エンコードのオーバーヘッドが消える。プロンプトキャッシュとの併用でコスト構造が根本から変わる。そして Code Execution ツールに渡すファイルの受け渡しが一気にラクになる。

公式ドキュメントによると、Files API は現在ベータで、anthropic-beta: files-api-2025-04-14 ヘッダを付けて呼び出す必要があります。ここを忘れると 400 が返ってくるので最初のハマりポイントです。

Claude Files API とは何か(2026年7月時点の仕様)

Files API は、Claude API に対してファイルを事前アップロードし、以降のリクエストでは file_id だけを参照する仕組みです。

公式ドキュメントには、Files API は将来のAPI呼び出しで参照するためにファイルをアップロード・管理できる仕組みだと明記されています。特に、Code Execution ツールへの入力(データセットや文書)を渡したり、頻繁に使うドキュメントや画像の再アップロードを避けたい場面で有効です。

サポートされるファイルと上限

直近の公式ドキュメントを見ると、次のような制約があります。

上限を超えると 413(File too large)や 403(Storage limit exceeded)が返ります。ここで慌てて再試行を回すと沼るので、事前チェックを入れるのが吉です。

PDF は「画像+テキスト」で処理される

これは意外と知られていない挙動なんですが、Claude の PDF 処理は裏で OCR を回しているわけではありません。各ページを画像としても、テキスト層としても両方理解する ハイブリッド入力 として扱っていて、レイアウトや署名欄、脚注まで文脈として捉えます。

その代わり、トークン消費は素のテキストより重い。100ページのPDFで実テキストが3万トークンでも、PDF入力としては7〜10万トークンほど食う目安です。「便利だから何でもPDFで渡そう」は逆効果で、Markdown で渡せるならそちらの方が安く済みます。

3ステップで動く最小実装(Python)

実装は驚くほど短いです。私が最初に書いたコードは30行に収まりました。

ステップ1: アップロードして file_id を取得

import anthropic

client = anthropic.Anthropic(
    default_headers={"anthropic-beta": "files-api-2025-04-14"}
)

uploaded = client.beta.files.upload(
    file=("contract.pdf", open("/path/to/contract.pdf", "rb"), "application/pdf"),
)

print(uploaded.id)  # file_011CNha8iCJcU1wXNR6q4V8w のような ID が返る

この file_id を DB か JSON にでも保存しておきます。私は SHA-256 で重複チェックをかけた {hash: file_id} の辞書を SQLite に持たせています。同じPDFを2回上げる事故が地味に多いので。

ステップ2: Messages リクエストで参照

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "この契約書の解除条項を抜き出してください"},
            {
                "type": "document",
                "source": {"type": "file", "file_id": uploaded.id},
                "title": "契約書A",
                "context": "2026年締結の業務委託契約"
            }
        ]
    }]
)
print(response.content[0].text)

document ブロックの title と context は任意ですが、citation を有効にする際に効くので入れておくのを推奨します。

ステップ3: 不要になったら削除

client.beta.files.delete(uploaded.id)

公式ドキュメントによると、削除後もアクティブな Messages 呼び出しや関連するツール利用にはしばらく残るとされています。「削除したら即消える」ではないので、機密文書の扱いは注意してください。

コストが劇的に下がる:プロンプトキャッシュとの合わせ技

ここが Files API の本当の価値です。単体で使うのはもったいない。

同じ文書を何度も読ませるなら 5分TTL キャッシュ

複数の解説記事で報告されている挙動として、ドキュメント内容は初回はフルプライスで課金され、5分以内のキャッシュヒットは通常の約10分の1の価格で処理されます。契約書レビューのように「同じPDFに20問聞く」ような使い方だと、実質1回分の課金で済むイメージです。

実装は cache_control を document ブロックに足すだけ。

{
    "type": "document",
    "source": {"type": "file", "file_id": uploaded.id},
    "cache_control": {"type": "ephemeral"}
}

非同期でよければ Batch API で追加50%オフ

夜間バッチや請求書処理のように即時性が不要なワークロードは、Batch API に流すと約50%のコスト削減になります。24時間SLAは付きますが、月末にまとめて数千件処理するようなユースケースにはハマります。

Haiku で分類 → Sonnet で本処理のルーティング

これは私も実運用で効いた設計です。Files API に上げた PDF をまず Haiku 4.5 に「このドキュメントの種別は?」と聞いて、複雑な契約書だけ Sonnet 4.6 に回す。分類コストは無視できるレベルで、精度を落とさずコストを圧縮できます。

複数の技術ブログでも、Haiku での事前分類 → Sonnet 本処理のパターンが「精度低下なくコスト最適化できる」と報告されています。

100ページを超えるPDFはどう扱うか

1つの Messages リクエストで扱えるPDFは最大100ページが目安です。長尺の文書はどうすればいいか。

セクション単位で分割 → ルーティング

私が試して良かったのは、章単位で分割してそれぞれ file_id を持たせる方法です。目次を最初に Claude に抽出させて、{section_name: file_id} の索引を作る。質問が来たら Haiku で「これはどのセクションの話か」を判定して、該当セクションの file_id だけを Sonnet に渡す。

この「ルーティング+ピンポイント読み込み」で、全ページを毎回投げるのに比べてトークン消費が7割前後減った実感があります(文書構造に依存するのであくまで目安)。

完全にRAGに寄せる判断基準

構造が読めないスキャンPDFの束や、横断検索が必要な場合は素直にベクトルDBに逃がした方がいいです。Files API は RAG の代替ではなく、小〜中規模ドキュメントQAのインデックス構築を省略できる仕組み と割り切ると設計が楽になります。

本番で踏んだ落とし穴3つ

最後に、私が実際に踏んだ地雷を共有します。

1. Bedrock/Vertex では使えない

複数の解説記事で指摘されている通り、Files API は Amazon Bedrock と Google Vertex AI では利用できません。マルチクラウド前提の設計をしている場合は、Anthropic 直APIか Claude Platform on AWS を経由する必要があります。エンタープライズ案件で最後に気づくと痛いので最初にチェックすべきポイントです。

2. file_id は無限に生きない

削除ポリシーや保持期間はワークスペース設定に依存します。「1年前の file_id を叩いたら 404 が返ってきた」というのは十分ありえる話で、参照時に file not found を捕まえて再アップロードにフォールバックする処理を最初から入れておくと安心です。

3. ストレージ上限はサイレントに刺さる

組織のストレージ上限に達すると 403 が返ります。開発中は気にならないんですが、本番でアップロード用途を増やすと数ヶ月で上限に触ります。用途別に retention ポリシーを決めて、定期的に一括削除するジョブを回す のがおすすめです。私は「一時解析用は7日で削除、参照ドキュメントは無期限」というルールで運用しています。

まとめ:今日からやる4つのアクション

Files API は地味な機能ですが、ドキュメント処理のコスト構造を根本から変える レバレッジポイントです。難しい話ではなく、ヘッダを1行足してfile_id を保持するだけ。

今日中にできる具体アクションを4つ挙げます。

  1. anthropic-beta: files-api-2025-04-14 ヘッダを SDK 初期化に追加する
  2. よく使うPDF 1本を実際にアップロードして、file_id で参照するコードを動かす
  3. SHA-256 ベースの {hash: file_id} インデックスを SQLite か JSON で作る
  4. 同じPDFに複数回問い合わせるフローには cache_control: ephemeral を付ける

これだけで、体感の請求額が変わります。私の場合、契約書解析パイプラインで月の Claude API 費が想定の半分以下になりました。まずは1本、手元のPDFで試してみてください。

参考リンク

この記事をシェア:
X で共有 Facebook で共有 Telegram で共有
次の記事
AIボイスエージェント構築を副業にする方法2026|電話応答代行で継続収益を作る実践設計