Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

1時間のプロンプトキャッシュTTLが5分に暗黙的にダウングレードされていた問題を修正しました。

原文（英語） ​

Fixed 1-hour prompt cache TTL being silently downgraded to 5 minutes

概要 ​

プロンプトキャッシュのTTL（Time to Live）を1時間に設定していた場合、実際には5分のTTLが適用されてしまっていた問題が修正されました。この問題により、長期間のキャッシュが期待通りに動作せず、不必要なキャッシュミスが発生してコストと遅延が増加していました。修正後は1時間のTTL設定が正しく維持されます。

基本的な使い方 ​

この修正は自動的に適用されます。プロンプトキャッシュの1時間TTLを使用している場合、正しく機能するようになります。

bash
# 1時間キャッシュを使用したAPIコール例（Python）
import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "長いシステムプロンプト...",
            "cache_control": {"type": "ephemeral", "ttl": 3600}  # 1時間TTL
        }
    ],
    messages=[{"role": "user", "content": "質問"}]
)

修正後は ttl: 3600 が正しく1時間のキャッシュとして機能します。

実践例 ​

大きなシステムプロンプトのキャッシュ ​

python
import anthropic

client = anthropic.Anthropic()

# 大きなコードベースや文書をシステムプロンプトとしてキャッシュ
large_codebase_context = "...大量のコードや文書..."

# 1時間TTLで最初のリクエスト（キャッシュ作成）
response = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=2048,
    system=[
        {
            "type": "text",
            "text": large_codebase_context,
            "cache_control": {"type": "ephemeral", "ttl": 3600}
        }
    ],
    messages=[{"role": "user", "content": "このコードのバグを見つけてください"}]
)

# 修正後: 1時間以内の次のリクエストでキャッシュヒット
# 修正前: 5分後にはキャッシュミス（予期しない動作）

キャッシュ動作の確認 ​

python
# キャッシュヒットを確認するためにusage情報を確認
print(f"入力トークン: {response.usage.input_tokens}")
print(f"キャッシュ作成トークン: {response.usage.cache_creation_input_tokens}")
print(f"キャッシュ読み取りトークン: {response.usage.cache_read_input_tokens}")

# キャッシュヒット時: cache_read_input_tokens > 0
# キャッシュミス時: cache_creation_input_tokens > 0

コスト最適化のための1時間キャッシュ活用 ​

python
# 繰り返し使用する大きなコンテキストをキャッシュして
# APIコストを削減する

# 1時間TTLを正しく設定（修正後は確実に1時間有効）
cache_params = {
    "type": "ephemeral",
    "ttl": 3600  # 1時間（修正前は誤って300秒=5分として扱われていた）
}

注意点 ​

  • この問題は Claude Code v2.1.129 で修正されました。それ以前のバージョンでは1時間TTLを設定しても実際には5分のキャッシュしか有効ではありませんでした。
  • キャッシュTTLの設定はAnthropicのAPIが対応している場合のみ有効です。モデルやアカウントによってはサポートされない場合があります。
  • 長いTTLはコスト最適化に役立ちますが、キャッシュストレージのコストも発生します。ユースケースに応じて適切なTTLを選択してください。
  • プロンプトキャッシュの詳細な仕様については、公式ドキュメントを参照してください。

関連情報 ​