Claude キャッシュ課金を把握するための3つの重要ポイント：なぜ Anthropic ネイティブ形式で呼び出す必要があるのか

多くの開発者が Claude API を使用する際、ある疑問に直面します：「Prompt Caching を有効にしているはずなのに、なぜ請求書にキャッシュ割引が反映されないのか？」

答えは非常にシンプルです。OpenAI 互換モードで呼び出しているからです。Claude のキャッシュ課金は、Anthropic ネイティブの Messages API 形式のみをサポートしています。

これはバグではなく、Anthropic の公式ドキュメントで明記されている設計上の制限です。この記事では、技術的な原理、呼び出し方法、価格比較の 3 つの側面から、Claude Prompt Caching の正しい使い方を徹底解説し、無駄なコストを抑える方法を紹介します。

Claude Prompt Caching キャッシュメカニズムの核心原理

呼び出し形式の違いを深掘りする前に、まずは Claude Prompt Caching がどのように機能するかを理解しましょう。

Claude キャッシュの仕組み

Prompt Caching を有効にしたリクエストを送信すると、システムは以下のプロセスを実行します：

1. キャッシュの確認: システムは、リクエストのプロンプトのプレフィックス（接頭辞）が最近のクエリですでにキャッシュされているかを確認します。
2. キャッシュヒット: 一致するものが見つかった場合、キャッシュされたバージョンを直接使用します。これにより、処理時間とコストが大幅に削減されます。
3. キャッシュへの書き込み: ヒットしなかった場合、プロンプト全体を処理し、レスポンスの開始後にプレフィックスをキャッシュします。

Claude Prompt Caching がサポートするコンテンツ

Claude Prompt Caching は、リクエスト内のほとんどのコンテンツブロックをキャッシュできます：

• Tools: tools 配列内のツール定義
• System messages: system 配列内のコンテンツブロック
• Text messages: messages.content 配列内のテキストコンテンツブロック
• Images & Documents: ユーザーメッセージ内の画像やドキュメント
• Tool use & tool results: ツール呼び出しと結果のコンテンツブロック

🎯 テクニカルアドバイス: 同じシステムプロンプトを頻繁に呼び出す必要があるシナリオでは、Prompt Caching は最も効果的なコスト最適化手段です。APIYI（apiyi.com）プラットフォームを通じて Anthropic ネイティブ形式で Claude API を呼び出し、キャッシュ課金割引を最大限に活用することをお勧めします。

Anthropic ネイティブ形式 vs OpenAI 互換モード：Claude キャッシュ対応の差異

この記事で最も重要な部分、つまり Claude のキャッシュ機能における 2 つの呼び出し形式の根本的な違いについて解説します。

Anthropic 公式による明確な声明

Anthropic 公式の OpenAI SDK 互換性ドキュメントには、次のように明記されています。

"Prompt caching is not supported, but it is supported in the Anthropic SDK"
（プロンプトキャッシュはサポートされていませんが、Anthropic SDK ではサポートされています）

これは、OpenAI 互換モード（/v1/chat/completions エンドポイント）経由で Claude を呼び出す場合、プロンプトキャッシュ（prompt caching）機能を一切使用できないことを意味します。

Claude API 2つの呼び出し形式の機能比較

なぜ OpenAI 互換モードは Claude キャッシュをサポートしていないのか

OpenAI 互換モードは、生産環境での使用ではなく、モデルの能力のテストや比較を目的として設計されています。

1. プロトコルの差異: cache_control パラメータは Anthropic Messages API 独自のフィールドであり、OpenAI の chat completions 形式には対応するフィールドが存在しません。
2. アーキテクチャの制限: 互換レイヤーは OpenAI 形式を Anthropic 形式に変換する必要がありますが、この変換プロセスでキャッシュ制御情報が失われてしまいます。
3. 優先順位の考慮: Anthropic 公式は、互換レイヤーの優先順位はネイティブな Claude API の信頼性と機能の完全性よりも低いとしています。

💡 重要: 業務においてコスト削減のために prompt caching に依存している場合は、OpenAI 互換モードではなく、必ず Anthropic ネイティブの Messages API 形式を使用してください。

Claude Prompt Caching キャッシュ料金詳細：最大 90% のコスト削減

Claude prompt caching の料金体系は非常に魅力的です。キャッシュヒット時の読み取り価格は、基本入力価格のわずか 10% です。

Claude 全モデルのキャッシュ料金比較

MTok = 100万トークン。データソース: Anthropic 公式料金ページ (2026年2月時点)

Claude キャッシュ料金の計算ルール

キャッシュ料金は、以下の 3 つのシンプルな乗数ルールに従います。

• 5 分間キャッシュ書き込み: 基本入力価格 × 1.25
• 1 時間キャッシュ書き込み: 基本入力価格 × 2.0
• キャッシュ読み取り（ヒット）: 基本入力価格 × 0.1

Claude Sonnet 4.6 を例に、10 万トークンのシステムプロンプトを使用する場合を考えてみましょう。

💰 コスト最適化: 同じシステムプロンプトを繰り返し使用するシナリオでは、APIYI（apiyi.com）プラットフォームを通じて Anthropic ネイティブ形式で Claude API を呼び出すことで、prompt caching を最大限に活用し、最大 90% のコスト削減を実現できます。

Claude Prompt Caching 実戦コード：Anthropic ネイティブ形式での呼び出し

ここでは、具体的なコード例を通じて、Claude の prompt caching（プロンプトキャッシュ）を正しく有効化する方法を解説します。

基礎的な呼び出し例：Anthropic ネイティブ形式 + Extended Thinking

curl https://api.apiyi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 16000,
    "stream": false,
    "thinking": {
      "type": "enabled",
      "budget_tokens": 10000
    },
    "messages": [
      {
        "role": "user",
        "content": "27 * 453 はいくつですか？"
      }
    ]
  }'

上記は、Extended Thinking（思考拡張）機能を使用した Anthropic ネイティブ形式の基本的な呼び出しです。次に、これをベースに prompt caching を有効化する方法を見ていきましょう。

自動キャッシュモード：最も簡単な Claude キャッシュの有効化方法

自動キャッシュは、Claude の prompt caching を有効にする最もシンプルな方法です。リクエストボディのトップレベルに cache_control フィールドを追加するだけです。

curl https://api.apiyi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "system": "あなたは専門的な技術ドキュメントアシスタントです。ユーザーが AI モデルの使用方法やベストプラクティスを理解するのを助けます。回答は正確、簡潔、かつ実用的である必要があります。",
    "messages": [
      {"role": "user", "content": "Claude Sonnet 4.6 にはどのような主要な特性がありますか？"},
      {"role": "assistant", "content": "Claude Sonnet 4.6 は Anthropic がリリースした高性能モデルで..."},
      {"role": "user", "content": "そのコンテキストウィンドウのサイズはどれくらいですか？"}
    ]
  }'

自動キャッシュモードでは、システムが自動的に最後のキャッシュ可能なコンテンツブロックにキャッシュブレークポイントを配置します。マルチターンの対話では、対話が進むにつれてキャッシュポイントも自動的に前方に移動します。

明示的キャッシュモード：Claude キャッシュ内容を精密に制御

キャッシュの動作を細かく制御する必要があるシナリオでは、特定のコンテンツブロックに cache_control を配置できます。

curl https://api.apiyi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "あなたは法律ドキュメント分析アシスタントです。契約条項の分析や法的リスクの特定を得意としています。"
      },
      {
        "type": "text",
        "text": "[ここに50ページの法律契約書の全文を入れる...約10万トークンの内容]",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "この契約書における主要な条項と潜在的なリスクを分析してください。"
      }
    ]
  }'

この例では、大量の法律ドキュメントがキャッシュ対象としてマークされています。初回のリクエストでキャッシュに書き込まれ、その後 5 分以内に同じドキュメントに対して異なる質問を投げた場合、すべてキャッシュにヒットします。この場合、支払うのは通常の入力料金のわずか 10%（読み取り費用）のみです。

1 時間の長期キャッシュ：Claude のキャッシュ保持時間を延長

デフォルトの 5 分間では足りない場合、1 時間のキャッシュを選択することも可能です。

"cache_control": {"type": "ephemeral", "ttl": "1h"}

1 時間キャッシュは以下のようなケースに適しています：

• エージェントのワークフローにおける長時間タスク（5 分を超えるもの）
• ユーザーとの対話間隔が 5 分を超える可能性があるシナリオ
• レート制限（Rate Limit）の利用効率を高めたい場合（キャッシュヒット分はレート制限を消費しません）

🚀 クイックスタート: Claude の prompt caching 機能を素早くテストするには、APIYI (apiyi.com) プラットフォームの使用をお勧めします。このプラットフォームは、cache_control パラメータを含む Anthropic ネイティブの Messages API 形式を完全にサポートしており、わずか 5 分で統合の検証が完了します。

Claude Prompt Caching のパフォーマンス監視とデバッグ

キャッシュを有効化した後は、API レスポンス内の usage フィールドを通じてキャッシュの効果を監視する必要があります。

Claude キャッシュレスポンス内の主要フィールド

{
  "usage": {
    "input_tokens": 50,
    "cache_creation_input_tokens": 100000,
    "cache_read_input_tokens": 0,
    "output_tokens": 500
  }
}

総入力トークンの計算式:

合計入力 = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

Claude キャッシュ未ヒットの主な原因と対策

キャッシュが全くヒットしない場合は、以下の項目を確認してください：

1. 呼び出し形式の誤り: Anthropic ネイティブ形式ではなく、OpenAI 互換モードを使用している。
2. 内容の不一致: キャッシュのマッチングには、プロンプトの接頭辞（Prefix）が 100% 完全に一致する必要があります。
3. トークン不足: モデルの最低キャッシュトークン数要件を満たしていない。
4. タイムアウト: 5 分間（または指定した TTL）使用されなかったため、キャッシュが期限切れになった。
5. パラメータの変更: tool_choice、画像の内容、または thinking パラメータを変更した。

Claude 各モデルの最低キャッシュトークン要件

プロンプトが最低トークン数に満たない場合、cache_control を指定しても有効になりません。リクエストは正常に処理されますが、キャッシュは作成されません。

🎯 デバッグのコツ: APIYI (apiyi.com) プラットフォームで Claude API を呼び出す際、レスポンスの usage フィールドを確認することでキャッシュが有効かどうかを素早く判断できます。cache_read_input_tokens と cache_creation_input_tokens が共に 0 の場合、キャッシュ機能が正しく設定されていない可能性があります。

Claude Prompt Caching（プロンプトキャッシュ）に関するよくある質問 FAQ

Q1: OpenAI 互換モードで Claude を呼び出す際、キャッシュは使用できますか？

いいえ、使用できません。 これは Anthropic 公式が明確に制限している事項です。OpenAI 互換モード（/v1/chat/completions エンドポイント）は prompt caching をサポートしていません。キャッシュ機能を利用するには、Anthropic ネイティブの Messages API 形式（/v1/messages エンドポイント）を使用する必要があります。

APIYI（apiyi.com）プラットフォームを経由すれば、両方の形式で Claude API を呼び出すことが可能です。キャッシュ機能が必要な場合は、/v1/messages エンドポイントを選択してください。

Q2: Claude のキャッシュ書き込みは通常の入力より高価ですが、利用する価値はありますか？

間違いなくあります。 キャッシュの書き込みは基本入力料金より 25% 高くなります（TTL 5分の場合）が、キャッシュヒット時の料金はわずか 10% です。同じ内容を 2 回以上使用するだけで、コストを回収でき、節約が始まります。10万トークンのシステムプロンプトを例に挙げます：

• キャッシュなし：毎回 $0.30 (Sonnet 3.5)
• キャッシュ書き込み：$0.375 (初回のみ)
• キャッシュ読み取り：$0.03 (2回目以降の毎回)
• 2 回目の呼び出しからすでに節約になります

Q3: コード内で OpenAI 形式から Anthropic ネイティブ形式に移行するにはどうすればよいですか？

主な変更点は以下の通りです：

• エンドポイント：/v1/chat/completions → /v1/messages
• リクエストヘッダー：anthropic-version: 2023-06-01 を追加
• メッセージ形式：messages 配列の構造はほぼ同じです
• システムプロンプト：messages 内から独立した system フィールドに抽出します
• cache_control パラメータを追加します

APIYI（apiyi.com）プラットフォームは両方のエンドポイントをサポートしているため、移行時はリクエストパスと形式を変更するだけで済み、APIキーを交換する必要はありません。

Q4: Claude のキャッシュはリクエスト間で共有されますか？

キャッシュは同一の Workspace 内で共有されます（2025年2月5日より、組織単位から Workspace 単位の隔離に変更されました）。異なる組織間でキャッシュが共有されることは決してありません。

Q5: キャッシュと Batch API を組み合わせて使用できますか？

はい、可能です。 Batch API は 50% の割引を提供しており、キャッシュの料金倍率はその上に重ねて適用されます。これらを組み合わせることで、最大のコスト最適化を実現できます。バッチ処理のシナリオでは、ヒット率を高めるために 1 時間のキャッシュ TTL を使用することをお勧めします。

まとめ：Claude Prompt Caching キャッシュ課金の 3 つの重要ポイント

本記事の分析を通じて、Claude prompt caching のキャッシュ課金に関して覚えておくべき 3 つのポイントは以下の通りです：

1. Anthropic ネイティブ形式のみサポート: キャッシュ機能は /v1/messages エンドポイントでのみ利用可能で、OpenAI 互換モード（/v1/chat/completions）ではサポートされていません。
2. キャッシュヒット時のコストはわずか 10%: 初回の書き込みには 25% の追加料金がかかりますが、その後のヒット時は基本料金の 10 分の 1 で済み、2 回の呼び出しで元が取れます。
3. 正しい呼び出し方法が鍵: cache_control: {"type": "ephemeral"} パラメータを使用し、モデルの最小キャッシュトークン要件を満たしていることを確認してください。

Claude prompt caching の全機能を体験するには、APIYI（apiyi.com）プラットフォームの利用をお勧めします。このプラットフォームは Anthropic ネイティブの Messages API を完全にサポートしており、最適なコストで Claude モデルを活用する手助けをします。

参考文献

1. Anthropic 公式プロンプトキャッシュドキュメント: Claude API キャッシュ機能の詳細

   • リンク: platform.claude.com/docs/en/build-with-claude/prompt-caching

2. Anthropic 公式料金ページ: Claude モデルとキャッシュの料金

   • リンク: platform.claude.com/docs/en/about-claude/pricing

3. OpenAI SDK 互換性ドキュメント: 互換モードの機能制限に関する説明

   • リンク: platform.claude.com/docs/en/api/openai-sdk

📝 著者: APIYI チーム | APIYI 技術チーム。AI 大規模言語モデルの API 統合と技術共有に注力しています。apiyi.com にアクセスして、さらに多くの技術チュートリアルをご覧ください。