Claude Prompt Caching

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "stream": true,
    "model": "claude-opus-4-20250514",
    "max_tokens": 20000,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style."
      },
      {
        "type": "text",
        "text": "Pride and Prejudice by Jane Austen... [Place complete text content here]",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 16000
    },
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

import os
import anthropic

client = anthropic.Anthropic(
    api_key="sk-***", # Replace with the key you generated in AiHubMix
    base_url="https://aihubmix.com"
)

# Streaming response with caching
with client.messages.stream(
    model="claude-opus-4-20250514",
    max_tokens=20000,
    system=[
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
        },
        {
            "type": "text",
            "text": "<the entire contents of 'Pride and Prejudice'>",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    thinking={
        "type": "enabled",
        "budget_tokens": 16000
    },
    messages=[
        {"role": "user", "content": "Analyze the major themes in 'Pride and Prejudice'."}
    ]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

# Non-streaming response
message = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=20000,
    system=[
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing literary works."
        },
        {
            "type": "text",
            "text": "<the entire contents of 'Pride and Prejudice'>",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "Analyze the major themes in 'Pride and Prejudice'."}
    ]
)
print(message.content)

import requests

url = "https://aihubmix.com/v1/messages"
headers = {
    "content-type": "application/json",
    "x-api-key": "sk-***", # Replace with the key you generated in AiHubMix
    "anthropic-version": "2023-06-01"
}
data = {
    "stream": True,
    "model": "claude-opus-4-20250514",
    "max_tokens": 20000,
    "system": [
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
        },
        {
            "type": "text",
            "text": "<the entire contents of 'Pride and Prejudice'>",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "thinking": {
        "type": "enabled",
        "budget_tokens": 16000
    },
    "messages": [{"role": "user", "content": "Analyze the major themes in 'Pride and Prejudice'."}]
}

response = requests.post(url, headers=headers, json=data, stream=True)

# Check response status
if response.status_code == 200:
    # Process the streaming response
    for line in response.iter_lines():
        if line:
            print(line.decode('utf-8'))
else:
    print(f"Error: {response.status_code}, {response.text}")

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

​

So funktioniert Prompt-Caching

1. Das System prüft, ob ein Prompt-Präfix bis zu einem bestimmten Cache-Breakpoint bereits aus einer kürzlichen Abfrage gecached ist.
2. Falls gefunden, wird die gecachte Version verwendet, wodurch Verarbeitungszeit und Kosten sinken.
3. Andernfalls wird der gesamte Prompt verarbeitet und das Präfix gecached, sobald die Antwort beginnt. Besonders nützlich für:

• Prompts mit vielen Beispielen
• Große Kontext- oder Hintergrundinformationen
• Wiederkehrende Aufgaben mit gleichbleibenden Anweisungen
• Lange Multi-Turn-Konversationen

​

Häufiger Fehler: Cache wird geschrieben, aber „nur geschrieben, nie gelesen”

​

❌ Falsch: Die in jeder Runde wechselnde Frage vor dem Breakpoint platzieren

{
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "请总结这份资料的核心观点。" },                          // ← 每轮会变,却放在断点前
        { "type": "text", "text": "<大文档>", "cache_control": { "type": "ephemeral" } }   // 断点
      ]
    }
  ]
}

​

✅ Richtig: Großes Dokument ganz nach vorn + Breakpoint + Frage ganz nach hinten

{
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "<固定不变的大文档/参考资料，≥4096 token>", "cache_control": { "type": "ephemeral" } },  // 断点;前缀恒定
        { "type": "text", "text": "请总结这份资料的核心观点。" }                                                          // ← 每轮变化的问题,放在断点之后
      ]
    }
  ]
}

​

Messvergleich (claude-opus-4-6, wenige Sekunden zwischen den beiden Aufrufen)

1. Den unveränderlichen großen Block (Referenzdokument, langer Kontext) ganz an den Anfang der user-Nachricht in messages setzen, cache_control an dessen Ende markieren – an diesem Inhalt darf kein einziges Zeichen geändert werden;
2. Die in jeder Runde wechselnde Frage/Anweisung nach den Breakpoint setzen (in derselben user-Nachricht nach dem großen Dokument oder in nachfolgenden Nachrichten); in Multi-Turn-Konversationen nur nach hinten anfügen und nicht zurückgehen, um den Verlauf zu ändern;
3. Bei aktiviertem thinking müssen die Thinking-Blöcke aus früheren Assistant-Turns unverändert zurückgesendet werden, sonst bricht das Präfix ebenfalls (siehe unten „Was nicht gecached werden kann”);
4. Liegt ein Block unter der Mindest-Cache-Schwelle (je nach Modell zwischen 512 und 4.096 Token, siehe unten „Cache-Einschränkungen”), wird er auch mit gesetztem cache_control nicht in den Cache geschrieben – das ist erwartetes Verhalten.

​

Preisgestaltung

• 5-Minuten-Cache-Write-Token kosten das 1,25-Fache der Basis-Input-Token-Preise
• 1-Stunden-Cache-Write-Token kosten das 2-Fache der Basis-Input-Token-Preise
• Cache-Read-Token kosten das 0,1-Fache der Basis-Input-Token-Preise
• Reguläre Input- und Output-Token werden zu den Standardpreisen der Plattform abgerechnet

​

So implementieren Sie Prompt-Caching

​

Unterstützte Modelle

​

Automatisches Caching (cache_control auf oberster Ebene)

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "cache_control": {"type": "ephemeral"},
  "system": "You are an AI assistant tasked with analyzing literary works.",
  "messages": [
    {"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}
  ]
}

​

Aufbau Ihres Prompts

​

Cache-Einschränkungen

• „ephemeral”: Standard-Lebensdauer 5 Minuten
• 1-Stunden-Cache: Setzen Sie "ttl": "1h" in cache_control, für Szenarien mit längerer Cache-Dauer

​

1-Stunden-Cache-Dauer

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-20250514",
    "system": [
      {
        "type": "text",
        "text": "Long-term instructions...",
        "cache_control": {
          "type": "ephemeral",
          "ttl": "1h"
        }
      }
    ],
    "messages": [...]
  }'

{
  "cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
  }
}

​

Wann der 1-Stunden-Cache verwendet werden sollte

• Batch-Verarbeitung: Bearbeitung großer Mengen an Requests mit gemeinsamen Präfixen
• Langläufige Sessions: Konversationen, die Kontext über längere Zeit benötigen
• Analyse großer Dokumente: Verschiedene Analysen am selben Dokument
• Code-Base-Q&A: Mehrere Abfragen über längere Zeiträume hinweg

​

Verschiedene TTLs mischen

{
  "system": [
    {
      "type": "text", 
      "text": "Long-term instructions...",
      "cache_control": {
        "type": "ephemeral",
        "ttl": "1h"
      }
    },
    {
      "type": "text",
      "text": "Short-term context...", 
      "cache_control": {
        "type": "ephemeral",
        "ttl": "5m"
      }
    }
  ]
}

​

Was gecached werden kann

• Tools: Tool-Definitionen im tools-Array
• System-Nachrichten: Content-Blöcke im system-Array
• Nachrichten: Content-Blöcke im messages.content-Array, sowohl für User- als auch für Assistant-Turns
• Bilder und Dokumente: Content-Blöcke im messages.content-Array, in User-Turns
• Tool-Use und Tool-Results: Content-Blöcke im messages.content-Array in User- und Assistant-Turns

​

Was nicht gecached werden kann

• Thinking-Blöcke können nicht direkt mit cache_control gecached werden. Sie KÖNNEN jedoch zusammen mit anderem Inhalt gecached werden, wenn sie in vorangegangenen Assistant-Turns auftauchen. So gecached zählen sie beim Lesen aus dem Cache als Input-Token.
• Sub-Content-Blöcke (wie Citations) können nicht direkt gecached werden. Cachen Sie stattdessen den übergeordneten Block.
• Leere Text-Blöcke können nicht gecached werden.

​

Cache-Performance überwachen

• cache_creation_input_tokens: Anzahl der Token, die beim Erstellen eines neuen Eintrags in den Cache geschrieben wurden.
• cache_read_input_tokens: Anzahl der Token, die aus dem Cache für diesen Request gelesen wurden.
• input_tokens: Anzahl der Input-Token, die nicht aus dem Cache gelesen oder zum Erstellen eines Caches verwendet wurden.

​

Best Practices für effektives Caching

• Cachen Sie stabilen, wiederverwendbaren Inhalt wie System-Anweisungen, Hintergrundinformationen, große Kontexte oder häufig genutzte Tool-Definitionen.
• Platzieren Sie gecachte Inhalte am Anfang des Prompts.
• Setzen Sie Cache-Breakpoints gezielt, um verschiedene cachefähige Präfixabschnitte zu trennen.
• Analysieren Sie regelmäßig Cache-Hit-Raten und passen Sie Ihre Strategie an.
• Für langfristige Inhalte sollten Sie den 1-Stunden-Cache für bessere Kosteneffizienz erwägen.

​

Optimierung für verschiedene Anwendungsfälle

• Konversationsagenten: Kosten und Latenz für längere Konversationen senken, besonders bei langen Anweisungen oder hochgeladenen Dokumenten.
• Coding-Assistenten: Autovervollständigung und Code-Base-Q&A verbessern, indem relevante Abschnitte oder eine zusammengefasste Version der Codebasis im Prompt verbleiben.
• Verarbeitung langer Dokumente: Komplette Langtexte inklusive Bilder im Prompt einbinden, ohne dass die Antwortlatenz steigt.
• Ausführliche Anweisungssets: Lange Listen von Anweisungen, Prozeduren und Beispielen teilen, um Claudes Antworten feinzutunen. Entwickler fügen üblicherweise ein bis zwei Beispiele in den Prompt ein, aber mit Prompt-Caching erzielen Sie mit 20+ vielfältigen Beispielen hoher Qualität noch bessere Ergebnisse.
• Agentische Tool-Nutzung: Verbessert Szenarien mit mehrfachen Tool-Aufrufen und iterativen Code-Änderungen, bei denen jeder Schritt einen neuen API-Aufruf erfordert.
• „Talk to” Bücher, Papers, Dokumentationen, Podcast-Transkripte und andere Langtextinhalte: Bringen Sie eine Wissensbasis zum Leben, indem Sie ganze Dokumente in den Prompt einbetten und Nutzer Fragen stellen lassen.

​

Häufige Probleme beheben

• Stellen Sie sicher, dass die gecachten Abschnitte identisch und an denselben Stellen mit cache_control markiert sind.
• Prüfen Sie, ob die Aufrufe innerhalb der Cache-Lebensdauer (5 Minuten oder 1 Stunde) erfolgen.
• Verifizieren Sie, dass tool_choice und die Bildverwendung zwischen Aufrufen konsistent bleiben.
• Stellen Sie sicher, dass Sie mindestens die Mindestanzahl an Token cachen.
• Das System versucht, vorherig gecachten Inhalt an Positionen vor einem Cache-Breakpoint zu nutzen; bei Anfragen mit sehr langen Listen von Content-Blöcken können Sie einen zusätzlichen cache_control-Parameter setzen, um den Cache-Lookup explizit zu erzwingen.

​

Cache-Speicherung und -Sharing

• Organisationsisolierung: Caches sind zwischen Organisationen isoliert. Verschiedene Organisationen teilen sich nie einen Cache, selbst bei identischen Prompts.
• Exakter Match: Cache-Hits erfordern zu 100 % identische Prompt-Segmente, einschließlich aller Texte und Bilder bis einschließlich des mit cache_control markierten Blocks. Derselbe Block muss bei Cache-Lese- und Schreibvorgängen mit cache_control markiert sein.
• Output-Token-Generierung: Prompt-Caching beeinflusst die Output-Token-Generierung nicht. Die Antwort ist identisch mit der ohne Prompt-Caching.

​

Claude-Caching in Clients / Plattformen aktivieren

​

Dify (über das Aihubmix-Plugin)

1. Umschließen Sie den zu cachenden Prompt (unveränderlicher System-Prompt / langer Kontext) mit <cache>…</cache>; das Plugin wandelt diese Stelle automatisch in einen cache_control-Breakpoint um;
2. Setzen Sie in den Modellparametern den Wert „Automatische Cache-Schwelle für große Nachrichten” auf eine positive Ganzzahl: Erst wenn der Inhalt diese Token-Schwelle erreicht, wird tatsächlich in den Cache geschrieben (weiterhin gebunden an die unten unter „Cache-Einschränkungen” genannte Mindest-Cache-Größe, 4096 Token für Opus 4.5/4.6 und Haiku 4.5); 0 oder leer schaltet die Funktion ab.

​

Cherry Studio

1. Klicken Sie auf das Zahnrad rechts neben dem Anbieternamen Aihubmix, um die „API Settings” zu öffnen:

2. Konfigurieren Sie die folgenden drei Optionen; der Client injiziert daraufhin automatisch cache_control für Claude:

• Cache Token Threshold: Erst wenn der Inhalt diese Token-Anzahl überschreitet, wird ein Cache-Breakpoint injiziert (eine positive Zahl aktiviert, 0 oder leer deaktiviert);
• Cache System Message: Aktiviert setzt einen Cache-Breakpoint auf die system-Nachricht (geeignet zum Cachen eines festen, langen System-Prompts);
• Cache Last N Messages: Setzt einen Cache-Breakpoint auf die letzten N Nachrichten (geeignet für rollierendes Caching in Multi-Turn-Konversationen).

​

Häufig gestellte Fragen (FAQ)

​

Warum wird der Cache geschrieben (cache_creation_input_tokens ist groß), aber nie gelesen (cache_read_input_tokens ist 0)?

​

Wie viele Token sind mindestens für Caching nötig?

​

Wie lange ist der Cache gültig? Lässt sich das auf 1 Stunde ändern?

​

Wie aktiviere ich Caching in Dify / Cherry Studio?

​

Unterstützung in verschiedenen Modellen

• Ob Prompt-Caching unterstützt wird, hängt vom Modell selbst ab.
• Wenn das Modell Caching nativ unterstützt, ohne explizite Parameter zu benötigen, kann es über OpenAI-kompatibles Forwarding unterstützt werden.
• OpenAI unterstützt Prompt-Caching standardmäßig; es greift automatisch (Präfix ≥1024 Token). Bei Modellen vor GPT-5.6 werden Cache-Writes nicht separat abgerechnet, und der Cache wird nach 5–10 Minuten Inaktivität automatisch geleert; ab GPT-5.6 werden Cache-Writes mit dem 1,25-Fachen des Inputpreises abgerechnet, Cache-Reads mit dem 0,1-Fachen, der Cache bleibt mindestens 30 Minuten erhalten, und explizite Cache-Breakpoints werden unterstützt. Details siehe GPT Prompt Caching.
• Claude erfordert die native Deklaration cache_control: { type: "ephemeral" }. Cache-Raten betragen das 1,25-Fache (5 Minuten) oder 2-Fache (1 Stunde) der Standard-Eingabekosten; das Lesen gecachter Token kostet das 0,1-Fache des Normalpreises, mit 5-Minuten- oder 1-Stunden-Lebenszyklus. Details
• Deepseek V3 und R1 unterstützen Caching nativ. Cache-Rate entspricht den Standard-Eingabekosten, das Lesen gecachter Token kostet das 0,1-Fache des Normalpreises. Details
• Gemini Implicit-Caching-Unterstützung:
  • Implicit Caching: Standardmäßig für alle Gemini-2.5-Modelle aktiviert. Trifft Ihr Request den Cache, wird die Kostenersparnis automatisch angewandt. Diese Funktion ist seit dem 8. Mai 2025 verfügbar. Mindest-Token-Anzahl für Kontext-Caching: 1.024 für Gemini 2.5 Flash und 2.048 für Gemini 2.5 Pro.
  • Tipps, um die Implicit-Cache-Hit-Rate zu erhöhen:
    • Platzieren Sie große, häufig wiederverwendete Inhalte am Anfang des Prompts.
    • Senden Sie Anfragen mit ähnlichen Präfixen innerhalb eines kurzen Zeitfensters.
  • Die Anzahl der Cache-Hit-Token sehen Sie im Feld usage_metadata des Response-Objekts.
  • Die Kostenersparnis basiert auf Prefilled-Cache-Hits. Nur Prefill-Cache und YouTube-Video-Preprocessing-Cache sind für Implicit Caching geeignet.