Claude Prompt Caching

Documentation Index

Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt

Use this file to discover all available pages before exploring further.

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."
      }
    ]
  }'

{"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

​

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

• Claude Opus 4
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Sonnet 3.5
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3

​

Aufbau Ihres Prompts

​

Cache-Einschränkungen

• 1024 Token für Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 und Claude Opus 3
• 2048 Token für Claude Haiku 3.5 und Claude Haiku 3

• „ephemeral”: Standard-Lebensdauer 5 Minuten
• 1-Stunden-Cache (Beta): Für Szenarien mit längerer Cache-Dauer

​

1-Stunden-Cache-Dauer (Beta)

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: extended-cache-ttl-2025-04-11" \
  -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.

​

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. Gecachte Prompts werden nicht in Rechnung gestellt, das Lesen gecachter Token kostet die Hälfte des Normalpreises, und Caches werden nach 5–10 Minuten Inaktivität automatisch geleert. Details
• 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.