---
title: Prompt-Caching
url: https://platform.claude.com/docs/de/build-with-claude/prompt-caching
description: Speichere Prompt-Präfixe mit `cache_control` im Cache, um Kosten und Latenz zu senken – per automatischem Caching oder mit expliziten Breakpoints und TTLs von 5 Minuten oder 1 Stunde.
---
„Prompt caching" (Prompt-Caching) optimiert deine API-Nutzung, indem es ermöglicht, ab bestimmten Präfixen in deinen Prompts fortzufahren. Dies reduziert die Verarbeitungszeit und die Kosten für sich wiederholende Aufgaben oder Prompts mit gleichbleibenden Elementen erheblich.
Um zu erfahren, wie „zero data retention“ (Null-Datenspeicherung), oder ZDR, auf diese Funktion angewendet wird, siehe [API und Datenspeicherung](https://platform.claude.com/docs/de/manage-claude/api-and-data-retention).
Es gibt zwei Möglichkeiten, Prompt-Caching zu aktivieren:
* **[Automatisches Caching](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#automatic-caching)**: Füge ein einzelnes `cache_control`-Feld auf der obersten Ebene deiner Anfrage hinzu. Das System setzt den „cache breakpoint" (Cache-Haltepunkt) automatisch auf den letzten cachebaren Block und verschiebt ihn nach vorne, während Gespräche wachsen. Am besten geeignet für Gespräche mit mehreren Runden, bei denen der wachsende Nachrichtenverlauf automatisch gecacht werden soll.
* **[Explizite Cache-Breakpoints](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#explicit-cache-breakpoints)**: Platziere `cache_control` direkt auf einzelnen Inhaltsblöcken, um genau zu steuern, was gecacht wird.
Am einfachsten beginnst du mit automatischem Caching:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"cache_control": {"type": "ephemeral"},
"system": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
"messages": [
{
"role": "user",
"content": "Analyze the major themes in Pride and Prejudice."
}
]
}'
```
```bash CLI
ant messages create --transform usage <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
cache_control:
type: ephemeral
system: >-
You are an AI assistant tasked with analyzing literary works. Your goal is
to provide insightful commentary on themes, characters, and writing style.
messages:
- role: user
content: Analyze the major themes in Pride and Prejudice.
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
cache_control={"type": "ephemeral"},
system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
messages=[
{
"role": "user",
"content": "Analyze the major themes in 'Pride and Prejudice'.",
}
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
cache_control: { type: "ephemeral" },
system:
"You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
messages: [
{
role: "user",
content: "Analyze the major themes in 'Pride and Prejudice'."
}
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
CacheControl = new CacheControlEphemeral(),
System = "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
Messages =
[
new()
{
Role = Role.User,
Content = "Analyze the major themes in 'Pride and Prejudice'."
}
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
CacheControl: anthropic.NewCacheControlEphemeralParam(),
System: []anthropic.TextBlockParam{
{Text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style."},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the major themes in 'Pride and Prejudice'.")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
public class PromptCachingExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.cacheControl(CacheControlEphemeral.builder().build())
.system("You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.")
.addUserMessage("Analyze the major themes in 'Pride and Prejudice'.")
.build();
Message message = client.messages().create(params);
System.out.println(message.usage());
}
}
```
```php PHP
use Anthropic\Messages\CacheControlEphemeral;
// ...
$client = new Client();
$response = $client->messages->create(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => "Analyze the major themes in 'Pride and Prejudice'."]
],
model: 'claude-opus-5-5',
cacheControl: CacheControlEphemeral::with(),
system: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
);
echo json_encode($response->usage);
```
```ruby Ruby
client = Anthropic::Client.new
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
cache_control: {type: "ephemeral"},
system: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
messages: [
{
role: "user",
content: "Analyze the major themes in 'Pride and Prejudice'."
}
]
)
puts response.usage
```
Beim automatischen Caching speichert das System alle Inhalte bis einschließlich des letzten cachebaren Blocks im Cache. Bei nachfolgenden Anfragen mit demselben Präfix werden gecachte Inhalte automatisch wiederverwendet.
***
## Wie Prompt-Caching funktioniert
Wenn du eine Anfrage mit aktiviertem Prompt-Caching sendest:
1. Das System prüft, ob ein Prompt-Präfix bis zu einem angegebenen Cache-Breakpoint bereits aus einer kürzlichen Anfrage im Cache gespeichert ist.
2. Falls ja, verwendet es die gecachte Version, was Verarbeitungszeit und Kosten reduziert.
3. Andernfalls verarbeitet es den vollständigen Prompt und speichert das Präfix im Cache, sobald die Antwort beginnt.
Dies ist besonders nützlich für:
* Prompts mit vielen Beispielen
* Große Mengen an Kontext oder Hintergrundinformationen
* Sich wiederholende Aufgaben mit gleichbleibenden Anweisungen
* Lange Gespräche mit mehreren Runden
Standardmäßig hat der Cache eine Lebensdauer von 5 Minuten. Der Cache wird jedes Mal ohne zusätzliche Kosten aufgefrischt, wenn die gecachten Inhalte verwendet werden.
Die Lebensdauer wird ab dem Beginn der Anfrage gemessen, die den Cache-Eintrag schreibt oder liest, nicht ab dem Ende ihrer Antwort. Die Zeit, die für das Generieren einer Antwort benötigt wird, zählt zur Lebensdauer: Wenn das Streaming einer Antwort 4 Minuten dauert, muss eine Folgeanfrage, die dasselbe gecachte Präfix wiederverwendet, innerhalb von etwa 1 Minute nach Abschluss dieser Antwort beginnen.
Wenn dir 5 Minuten zu kurz sind, bietet Anthropic auch eine Cache-Dauer von 1 Stunde [gegen Aufpreis](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#pricing) an.
Weitere Informationen findest du unter [Cache-Dauer von 1 Stunde](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#1-hour-cache-duration).
**Prompt-Caching speichert das vollständige Präfix**
Prompt-Caching bezieht sich auf den gesamten Prompt: `tools`, `system` und `messages` (in dieser Reihenfolge), bis einschließlich des mit `cache_control` gekennzeichneten Blocks.
***
## Preise
Prompt-Caching führt eine neue Preisstruktur ein. Die folgende Tabelle zeigt den Preis pro Million Token für jedes unterstützte Modell:
| Model | Base input tokens | 5m cache writes | 1h cache writes | Cache hits and refreshes | Output tokens |
| :----------------------------------------------------------------------------------------------------------------------------------- | :---------------- | :-------------- | :-------------- | :----------------------- | :------------ |
| Claude Fable 5.1 | $10 / MTok | $12.50 / MTok | $20 / MTok | $0.25 / MTok1 | $50 / MTok |
| Claude Mythos 5.1 ([limited availability](https://support.claude.com/en/articles/14604842)) | $10 / MTok | $12.50 / MTok | $20 / MTok | $0.25 / MTok1 | $50 / MTok |
| Claude Fable 5 | $10 / MTok | $12.50 / MTok | $20 / MTok | $1 / MTok | $50 / MTok |
| Claude Mythos 5 ([limited availability](https://support.claude.com/en/articles/14604842)) | $10 / MTok | $12.50 / MTok | $20 / MTok | $1 / MTok | $50 / MTok |
| Claude Opus 5.5 | $4 / MTok | $5 / MTok | $8 / MTok | $0.20 / MTok2 | $20 / MTok |
| Claude Opus 5 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.8 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.7 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.6 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.5 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.1 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/de/about-claude/model-deprecations)) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Opus 4 ([retired, except on Google Cloud](https://platform.claude.com/docs/de/about-claude/model-deprecations)) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Sonnet 5.5 | $2 / MTok | $2.50 / MTok | $4 / MTok | $0.10 / MTok2 | $10 / MTok |
| Claude Sonnet 5 | $2 / MTok | $2.50 / MTok | $4 / MTok | $0.20 / MTok | $10 / MTok |
| Claude Sonnet 4.6 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 4.5 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 4 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/de/about-claude/model-deprecations)) | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Haiku 5.5 (for prompts up to 100,000 tokens) | $0.10 / MTok | $0.125 / MTok | $0.20 / MTok | $0.01 / MTok | $0.50 / MTok |
| Claude Haiku 5.5 (for prompts over 100,000 tokens) | $0.50 / MTok | $0.625 / MTok | $1 / MTok | $0.05 / MTok | $2.50 / MTok |
| Claude Haiku 4.5 | $1 / MTok | $1.25 / MTok | $2 / MTok | $0.10 / MTok | $5 / MTok |
| Claude Haiku 3.5 ([retired, except on Google Cloud](https://platform.claude.com/docs/de/about-claude/model-deprecations)) | $0.80 / MTok | $1 / MTok | $1.60 / MTok | $0.08 / MTok | $4 / MTok |
*1 Cache hits and refreshes on Claude Fable 5.1 and Claude Mythos 5.1 are priced at 0.025x the base input price.*
*2 Cache hits and refreshes on Claude Opus 5.5 and Claude Sonnet 5.5 are priced at 0.05x the base input price.*
*All other models use the standard 0.1x multiplier.*
Die vorherige Tabelle spiegelt die folgenden Preismultiplikatoren für Prompt-Caching wider:
* Token für 5-Minuten-Cache-Schreibvorgänge kosten das 1,25-Fache des Basispreises für Input-Token
* Token für 1-Stunden-Cache-Schreibvorgänge kosten das 2-Fache des Basispreises für Input-Token
* Token für Cache-Lesevorgänge kosten das 0,1-Fache des Basispreises für Input-Token (modellspezifische Ausnahmen findest du in der Fußnote der Tabelle)
Diese Multiplikatoren werden mit anderen Preismodifikatoren wie dem Batch-API-Rabatt, [Preisen für langen Kontext](https://platform.claude.com/docs/de/about-claude/pricing#long-context-pricing) und Datenresidenz kombiniert. Bei einem Modell, dessen Preis von der Prompt-Länge abhängt, zählen Cache-Lese- und Cache-Schreibvorgänge zur Prompt-Länge einer Anfrage. Alle Details findest du unter [Preise](https://platform.claude.com/docs/de/about-claude/pricing).
***
## Unterstützte Modelle
Prompt-Caching (sowohl automatisch als auch explizit) wird auf allen [aktiven Claude-Modellen](https://platform.claude.com/docs/de/models/overview) unterstützt.
***
## Automatisches Caching
Automatisches Caching ist die einfachste Möglichkeit, Prompt-Caching zu aktivieren. Anstatt `cache_control` auf einzelnen Inhaltsblöcken zu platzieren, fügst du ein einzelnes `cache_control`-Feld auf der obersten Ebene deines Anfrage-Bodys hinzu. Das System setzt den Cache-Breakpoint automatisch auf den letzten cachebaren Block.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"cache_control": {"type": "ephemeral"},
"system": "You are a helpful assistant that remembers our conversation.",
"messages": [
{"role": "user", "content": "My name is Alex. I work on machine learning."},
{"role": "assistant", "content": "Nice to meet you, Alex! How can I help with your ML work today?"},
{"role": "user", "content": "What did I say I work on?"}
]
}'
```
```bash CLI
ant messages create --transform usage <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
cache_control:
type: ephemeral
system: You are a helpful assistant that remembers our conversation.
messages:
- role: user
content: My name is Alex. I work on machine learning.
- role: assistant
content: Nice to meet you, Alex! How can I help with your ML work today?
- role: user
content: What did I say I work on?
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
cache_control={"type": "ephemeral"},
system="You are a helpful assistant that remembers our conversation.",
messages=[
{"role": "user", "content": "My name is Alex. I work on machine learning."},
{
"role": "assistant",
"content": "Nice to meet you, Alex! How can I help with your ML work today?",
},
{"role": "user", "content": "What did I say I work on?"},
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
cache_control: { type: "ephemeral" },
system: "You are a helpful assistant that remembers our conversation.",
messages: [
{ role: "user", content: "My name is Alex. I work on machine learning." },
{
role: "assistant",
content: "Nice to meet you, Alex! How can I help with your ML work today?"
},
{ role: "user", content: "What did I say I work on?" }
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
CacheControl = new CacheControlEphemeral(),
System = "You are a helpful assistant that remembers our conversation.",
Messages =
[
new()
{
Role = Role.User,
Content = "My name is Alex. I work on machine learning."
},
new()
{
Role = Role.Assistant,
Content = "Nice to meet you, Alex! How can I help with your ML work today?"
},
new()
{
Role = Role.User,
Content = "What did I say I work on?"
}
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
CacheControl: anthropic.NewCacheControlEphemeralParam(),
System: []anthropic.TextBlockParam{
{Text: "You are a helpful assistant that remembers our conversation."},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("My name is Alex. I work on machine learning.")),
anthropic.NewAssistantMessage(anthropic.NewTextBlock("Nice to meet you, Alex! How can I help with your ML work today?")),
anthropic.NewUserMessage(anthropic.NewTextBlock("What did I say I work on?")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
public class AutomaticCachingExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.cacheControl(CacheControlEphemeral.builder().build())
.system("You are a helpful assistant that remembers our conversation.")
.addUserMessage("My name is Alex. I work on machine learning.")
.addAssistantMessage("Nice to meet you, Alex! How can I help with your ML work today?")
.addUserMessage("What did I say I work on?")
.build();
Message message = client.messages().create(params);
System.out.println(message.usage());
}
}
```
```php PHP
use Anthropic\Messages\CacheControlEphemeral;
// ...
$client = new Client();
$response = $client->messages->create(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => 'My name is Alex. I work on machine learning.'],
['role' => 'assistant', 'content' => 'Nice to meet you, Alex! How can I help with your ML work today?'],
['role' => 'user', 'content' => 'What did I say I work on?'],
],
model: 'claude-opus-5-5',
cacheControl: CacheControlEphemeral::with(),
system: 'You are a helpful assistant that remembers our conversation.',
);
echo json_encode($response->usage);
```
```ruby Ruby
client = Anthropic::Client.new
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
cache_control: {type: "ephemeral"},
system: "You are a helpful assistant that remembers our conversation.",
messages: [
{role: "user", content: "My name is Alex. I work on machine learning."},
{role: "assistant", content: "Nice to meet you, Alex! How can I help with your ML work today?"},
{role: "user", content: "What did I say I work on?"}
]
)
puts response.usage
```
### Wie automatisches Caching in Gesprächen mit mehreren Runden funktioniert
Beim automatischen Caching wandert der Cache-Punkt automatisch nach vorne, während Gespräche wachsen. Jede neue Anfrage speichert alles bis zum letzten cachebaren Block im Cache, und vorherige Inhalte werden aus dem Cache gelesen.
| Anfrage | Inhalt | Cache-Verhalten |
| --------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| Anfrage 1 | System
+ User(1) + Asst(1)
+ **User(2)** ◀ Cache | Alles wird in den Cache geschrieben |
| Anfrage 2 | System
+ User(1) + Asst(1)
+ User(2) + Asst(2)
+ **User(3)** ◀ Cache | System bis User(2) aus dem Cache gelesen;
Asst(2) + User(3) in den Cache geschrieben |
| Anfrage 3 | System
+ User(1) + Asst(1)
+ User(2) + Asst(2)
+ User(3) + Asst(3)
+ **User(4)** ◀ Cache | System bis User(3) aus dem Cache gelesen;
Asst(3) + User(4) in den Cache geschrieben |
Der Cache-Breakpoint wandert in jeder Anfrage automatisch zum letzten cachebaren Block, sodass du keine `cache_control`-Markierungen aktualisieren musst, während das Gespräch wächst.
### TTL-Unterstützung
Standardmäßig verwendet automatisches Caching eine „time to live" (Lebensdauer), oder TTL, von 5 Minuten. Du kannst eine TTL von 1 Stunde zum 2-Fachen des Basispreises für Input-Token angeben:
```json
{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }
```
### Kombination mit Caching auf Blockebene
Automatisches Caching ist mit [expliziten Cache-Breakpoints](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#explicit-cache-breakpoints) kompatibel. Bei gemeinsamer Verwendung belegt der automatische Cache-Breakpoint einen der 4 verfügbaren Breakpoint-Plätze.
So kannst du beide Ansätze kombinieren. Verwende zum Beispiel einen expliziten Breakpoint, um deinen System-Prompt zu cachen, während automatisches Caching das Gespräch übernimmt:
```json
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"cache_control": { "type": "ephemeral" },
"system": [
{
"type": "text",
"text": "You are a helpful assistant.",
"cache_control": { "type": "ephemeral" }
}
],
"messages": [{ "role": "user", "content": "What are the key terms?" }]
}
```
### Was gleich bleibt
Automatisches Caching nutzt dieselbe zugrunde liegende Caching-Infrastruktur. Preise, Mindest-Token-Schwellenwerte, Anforderungen an die Kontextreihenfolge und das „lookback window" (Rückblickfenster) von 20 Blöcken gelten genauso wie bei expliziten Breakpoints.
### Sonderfälle
* Wenn der letzte Block bereits ein explizites `cache_control` mit derselben TTL hat, ist automatisches Caching wirkungslos.
* Wenn der letzte Block ein explizites `cache_control` mit einer anderen TTL hat, gibt die API einen 400-Fehler zurück.
* Wenn bereits 4 explizite Breakpoints auf Blockebene vorhanden sind, gibt die API einen 400-Fehler zurück (keine Plätze mehr für automatisches Caching frei).
* Wenn der letzte Block nicht als Ziel für einen automatischen Cache-Breakpoint infrage kommt, geht das System stillschweigend rückwärts, um den nächstgelegenen geeigneten Block zu finden. Wird keiner gefunden, wird das Caching übersprungen.
Automatisches Caching ist auf jeder Plattform verfügbar, mit Ausnahme der veralteten Integration [Amazon Bedrock (Opus 4.6 und früher)](https://platform.claude.com/docs/de/build-with-claude/claude-on-amazon-bedrock-legacy). Bei dieser Integration gibt die API für ein `cache_control`-Feld auf oberster Ebene einen 400-Fehler zurück, verwende daher stattdessen [explizite Cache-Breakpoints](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#explicit-cache-breakpoints).
***
## Explizite Cache-Breakpoints
Für mehr Kontrolle über das Caching kannst du `cache_control` direkt auf einzelnen Inhaltsblöcken platzieren. Das ist nützlich, wenn du verschiedene Abschnitte cachen musst, die sich unterschiedlich häufig ändern, oder wenn du genau steuern möchtest, was gecacht wird.
### Deinen Prompt strukturieren
Platziere statische Inhalte (Tool-Definitionen, Systemanweisungen, Kontext, Beispiele) am Anfang deines Prompts. Markiere das Ende der wiederverwendbaren Inhalte für das Caching mit dem Parameter `cache_control`.
Cache-Präfixe werden in der folgenden Reihenfolge erstellt: `tools`, `system`, dann `messages`. Diese Reihenfolge bildet eine Hierarchie, in der jede Ebene auf den vorherigen aufbaut.
#### Wie die automatische Präfixprüfung funktioniert
Du kannst nur einen einzigen Cache-Breakpoint am Ende deiner statischen Inhalte verwenden, und das System findet automatisch das längste Präfix, das eine vorherige Anfrage bereits in den Cache geschrieben hat. Wenn du verstehst, wie das funktioniert, kannst du deine Caching-Strategie optimieren.
**Drei Grundprinzipien:**
1. **Cache-Schreibvorgänge finden nur an deinem Breakpoint statt.** Das Markieren eines Blocks mit `cache_control` schreibt genau einen Cache-Eintrag: einen Hash des Präfixes, das an diesem Block endet. Das System schreibt keine Einträge für frühere Positionen. Da der Hash kumulativ ist und alles bis einschließlich des Breakpoints abdeckt, erzeugt jede Änderung an einem Block am oder vor dem Breakpoint bei der nächsten Anfrage einen anderen Hash.
2. **Cache-Lesevorgänge suchen rückwärts nach Einträgen, die vorherige Anfragen geschrieben haben.** Bei jeder Anfrage berechnet das System den Präfix-Hash an deinem Breakpoint und sucht nach einem passenden Cache-Eintrag. Existiert keiner, geht es Block für Block rückwärts und prüft, ob der Präfix-Hash an jeder früheren Position mit etwas übereinstimmt, das bereits im Cache liegt. Es sucht nach früheren Schreibvorgängen, nicht nach stabilen Inhalten.
3. **Das Lookback-Fenster umfasst 20 Blöcke.** Das System prüft höchstens 20 Positionen pro Breakpoint, wobei der Breakpoint selbst als erste zählt. Findet das System in diesem Fenster keinen passenden Eintrag, wird die Prüfung beendet (oder am nächsten expliziten Breakpoint fortgesetzt, falls vorhanden). In der Claude API zählt eine Folge aufeinanderfolgender `tool_use`-Blöcke als eine Position, ebenso eine Folge aufeinanderfolgender `tool_result`-Blöcke, sodass eine Runde mit vielen parallelen Tool-Aufrufen den Eintrag der vorherigen Anfrage nicht allein aus dem Fenster verdrängt.
**Beispiel: Lookback in einem wachsenden Gespräch**
Du hängst in jeder Runde neue Blöcke an und setzt `cache_control` auf den letzten Block jeder Anfrage:
* **Runde 1:** 10 Blöcke, Breakpoint auf Block 10. Es existieren keine vorherigen Cache-Einträge. Das System schreibt einen Eintrag bei Block 10.
* **Runde 2:** 15 Blöcke, Breakpoint auf Block 15. Block 15 hat keinen Eintrag, also geht das System zurück zu Block 10 und findet den Eintrag aus Runde 1. Cache-Treffer bei Block 10; das System verarbeitet nur die Blöcke 11 bis 15 neu und schreibt einen neuen Eintrag bei Block 15.
* **Runde 3:** 35 Blöcke, Breakpoint auf Block 35. Das System prüft 20 Positionen (Blöcke 35 bis 16) und findet nichts. Der Eintrag aus Runde 2 bei Block 15 liegt eine Position außerhalb des Fensters, daher gibt es keinen Cache-Treffer. Ein zweiter Breakpoint bei Block 15 startet dort ein zweites Lookback-Fenster, das den Eintrag aus Runde 2 findet.
**Häufiger Fehler: Breakpoint auf Inhalten, die sich bei jeder Anfrage ändern**
Dein Prompt hat einen großen statischen Systemkontext (Blöcke 1 bis 5), gefolgt von einem anfragespezifischen Block mit einem Zeitstempel und der Benutzernachricht (Block 6). Du setzt `cache_control` auf Block 6:
* **Anfrage 1:** Cache-Schreibvorgang bei Block 6. Der Hash enthält den Zeitstempel.
* **Anfrage 2:** Der Zeitstempel ist anders, daher unterscheidet sich der Präfix-Hash bei Block 6. Der Lookback durchläuft die Blöcke 5, 4, 3, 2 und 1, aber das System hat an keiner dieser Positionen jemals einen Eintrag geschrieben. Kein Cache-Treffer. Du zahlst bei jeder Anfrage für einen neuen Cache-Schreibvorgang und erhältst nie einen Lesevorgang.
Der Lookback findet keine stabilen Inhalte hinter deinem Breakpoint, um sie zu cachen. Er findet Einträge, die vorherige Anfragen bereits geschrieben haben, und Schreibvorgänge finden nur an Breakpoints statt. Verschiebe `cache_control` auf Block 5, den letzten Block, der über Anfragen hinweg gleich bleibt, und jede nachfolgende Anfrage liest das gecachte Präfix. [Automatisches Caching](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#automatic-caching) tappt in dieselbe Falle: Es setzt den Breakpoint auf den letzten cachebaren Block, der in dieser Struktur derjenige ist, der sich bei jeder Anfrage ändert. Verwende daher stattdessen einen expliziten Breakpoint auf Block 5.
**Wichtigste Erkenntnis:** Platziere `cache_control` auf dem letzten Block, dessen Präfix über die Anfragen hinweg identisch ist, die sich einen Cache teilen sollen. In einem wachsenden Gespräch funktioniert der letzte Block, solange jede Runde weniger als 20 Blöcke hinzufügt: Frühere Inhalte ändern sich nie, sodass der Lookback der nächsten Anfrage den vorherigen Schreibvorgang findet. Bei einem Prompt mit variablem Suffix (Zeitstempel, anfragespezifischer Kontext, die eingehende Nachricht) platzierst du den Breakpoint am Ende des statischen Präfixes, nicht auf dem variablen Block.
#### Wann mehrere Breakpoints sinnvoll sind
Du kannst bis zu 4 Cache-Breakpoints definieren, wenn du:
* Verschiedene Abschnitte cachen möchtest, die sich unterschiedlich häufig ändern (zum Beispiel ändern sich Tools selten, der Kontext aber täglich)
* Mehr Kontrolle darüber haben möchtest, was genau gecacht wird
* Einen Cache-Treffer sicherstellen möchtest, wenn ein wachsendes Gespräch deinen Breakpoint 20 oder mehr Blöcke über den letzten Cache-Schreibvorgang hinaus verschiebt
**Wichtige Einschränkung:** Der Lookback kann nur Einträge finden, die frühere Anfragen bereits geschrieben haben. Wenn ein wachsendes Gespräch deinen Breakpoint 20 oder mehr Blöcke über den letzten Schreibvorgang hinaus verschiebt, verfehlt das Lookback-Fenster ihn. Füge von Anfang an einen zweiten Breakpoint näher an dieser Position hinzu, damit sich dort ein Schreibvorgang ansammelt, bevor du ihn brauchst.
### Kosten von Cache-Breakpoints verstehen
**Cache-Breakpoints selbst verursachen keine Kosten.** Berechnet werden dir nur:
* **Cache-Schreibvorgänge:** Wenn neuer Inhalt in den Cache geschrieben wird (25 % mehr als Basis-Input-Token bei 5-Minuten-TTL)
* **Cache-Lesevorgänge:** Wenn gecachter Inhalt verwendet wird (10 % des Basispreises für Input-Token, bzw. 2,5 % bei Claude Fable 5.1 und Claude Mythos 5.1 und 5 % bei Claude Opus 5.5 und Claude Sonnet 5.5)
* **Reguläre Input-Token:** Für alle nicht gecachten Inhalte
Das Hinzufügen weiterer `cache_control`-Breakpoints erhöht deine Kosten nicht; du zahlst weiterhin denselben Betrag, basierend darauf, welcher Inhalt tatsächlich gecacht und gelesen wird. Die Breakpoints geben dir Kontrolle darüber, welche Abschnitte unabhängig voneinander gecacht werden können.
***
## Caching-Strategien und Überlegungen
### Cache-Einschränkungen
In der Claude API, auf [Claude Platform on AWS](https://platform.claude.com/docs/de/build-with-claude/claude-platform-on-aws), [Google Cloud](https://platform.claude.com/docs/de/build-with-claude/claude-on-vertex-ai) und [Microsoft Foundry](https://platform.claude.com/docs/de/build-with-claude/claude-in-microsoft-foundry) beträgt die minimale cachebare Prompt-Länge:
* 512 Token für Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/de/models/mythos-5-1/overview), Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/de/models/mythos-5/overview) und Claude Haiku 5.5
* 2.048 Token für [Claude Mythos Preview](https://anthropic.com/glasswing) und Claude Opus 4.7
* 4.096 Token für Claude Opus 4.6 und Claude Opus 4.5
* 1.024 Token für Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5 ([abgekündigt](https://platform.claude.com/docs/de/about-claude/model-deprecations)), Claude Opus 4.1 ([eingestellt, außer auf Bedrock und Google Cloud](https://platform.claude.com/docs/de/about-claude/model-deprecations)), Claude Opus 4 ([eingestellt, außer auf Google Cloud](https://platform.claude.com/docs/de/about-claude/model-deprecations)) und Claude Sonnet 4 ([eingestellt, außer auf Bedrock und Google Cloud](https://platform.claude.com/docs/de/about-claude/model-deprecations))
* 4.096 Token für Claude Haiku 4.5
* 2.048 Token für Claude Haiku 3.5 ([eingestellt, außer auf Google Cloud](https://platform.claude.com/docs/de/about-claude/model-deprecations))
Diese Mindestwerte gelten auf jeder Plattform, auf der das jeweilige Modell verfügbar ist.
Kürzere Prompts können nicht gecacht werden, selbst wenn sie mit `cache_control` markiert sind. Alle Anfragen, weniger als diese Anzahl an Token zu cachen, werden ohne Caching verarbeitet, und es wird kein Fehler zurückgegeben. Um zu überprüfen, ob ein Prompt gecacht wurde, prüfe die [Usage-Felder der Antwort](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#tracking-cache-performance): Wenn sowohl `cache_creation_input_tokens` als auch `cache_read_input_tokens` 0 sind, wurde der Prompt nicht gecacht (wahrscheinlich, weil er die Mindestlänge nicht erreicht hat).
Wenn dein Prompt knapp unter dem Mindestwert für dein Modell und deine Plattform liegt, lohnt es sich oft, den gecachten Inhalt zu erweitern, um den Schwellenwert zu erreichen. Cache-Lesevorgänge kosten deutlich weniger als nicht gecachte Input-Token, sodass das Erreichen des Mindestwerts die Kosten für häufig wiederverwendete Prompts senken kann.
[Bedrock](https://platform.claude.com/docs/de/build-with-claude/claude-in-amazon-bedrock) ist eine von AWS betriebene Plattform. Für Bedrock findest du in der [Bedrock-Dokumentation zum Prompt-Caching](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html) die geltenden modellspezifischen Mindestwerte, das Fehlerverhalten und die Namen der Usage-Felder.
Beachte bei gleichzeitigen Anfragen, dass ein Cache-Eintrag erst verfügbar wird, nachdem die erste Antwort begonnen hat. Wenn du Cache-Treffer für parallele Anfragen benötigst, warte auf die erste Antwort, bevor du nachfolgende Anfragen sendest.
Derzeit ist „ephemeral" der einzige unterstützte Cache-Typ, der standardmäßig eine Lebensdauer von 5 Minuten hat.
### Was gecacht werden kann
Die meisten Blöcke in der Anfrage können gecacht werden. Dazu gehören:
* Tools: Tool-Definitionen im `tools`-Array
* Systemnachrichten: Inhaltsblöcke im `system`-Array
* Textnachrichten: Inhaltsblöcke im `messages.content`-Array, sowohl für Benutzer- als auch für Assistenten-Runden
* Bilder & Dokumente: Inhaltsblöcke im `messages.content`-Array, in Benutzer-Runden
* Tool-Nutzung und Tool-Ergebnisse: Inhaltsblöcke im `messages.content`-Array, sowohl in Benutzer- als auch in Assistenten-Runden
Jedes dieser Elemente kann gecacht werden, entweder automatisch oder indem du es mit `cache_control` markierst.
### Was nicht gecacht werden kann
Obwohl die meisten Anfrageblöcke gecacht werden können, gibt es einige Ausnahmen:
* Thinking-Blöcke können nicht direkt mit `cache_control` gecacht werden. Thinking-Blöcke KÖNNEN jedoch zusammen mit anderen Inhalten gecacht werden, wenn sie in vorherigen Assistenten-Runden vorkommen. Wenn sie auf diese Weise gecacht werden, ZÄHLEN sie beim Lesen aus dem Cache als Input-Token.
* Untergeordnete Inhaltsblöcke (wie [Zitate](https://platform.claude.com/docs/de/build-with-claude/citations)) selbst können nicht direkt gecacht werden. Cache stattdessen den Block der obersten Ebene.
Im Fall von Zitaten können die Dokument-Inhaltsblöcke der obersten Ebene, die als Quellmaterial für Zitate dienen, gecacht werden. So kannst du Prompt-Caching effektiv mit Zitaten nutzen, indem du die Dokumente cachst, auf die sich die Zitate beziehen.
* Leere Textblöcke können nicht gecacht werden.
### Was den Cache ungültig macht
Änderungen an gecachten Inhalten können den Cache teilweise oder vollständig ungültig machen.
Wie unter [Deinen Prompt strukturieren](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#structuring-your-prompt) beschrieben, folgt der Cache der Hierarchie: `tools` → `system` → `messages`. Änderungen auf jeder Ebene machen diese Ebene und alle nachfolgenden Ebenen ungültig.
Die folgende Tabelle zeigt, welche Teile des Caches durch verschiedene Arten von Änderungen ungültig werden. ✘ bedeutet, dass der Cache ungültig wird, während ✓ bedeutet, dass der Cache gültig bleibt.
| Was sich ändert | Tools-Cache | System-Cache | Messages-Cache | Auswirkung |
| ---------------------------------------------------- | ---------------- | ---------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tool-Definitionen** | ✘ | ✘ | ✘ | Das Ändern von Tool-Definitionen (Namen, Beschreibungen, Parameter) macht den gesamten Cache ungültig |
| **Websuche ein/aus** | ✓ | ✘ | ✘ | Das Aktivieren/Deaktivieren der Websuche ändert den System-Prompt |
| **Zitate ein/aus** | ✓ | ✘ | ✘ | Das Aktivieren/Deaktivieren von Zitaten ändert den System-Prompt |
| **Geschwindigkeitseinstellung** | ✓ | ✘ | ✘ | Das Wechseln zwischen [`speed: "fast"` und Standardgeschwindigkeit](https://platform.claude.com/docs/de/build-with-claude/fast-mode) macht System- und Messages-Caches ungültig |
| **Tool-Auswahl** | ✓ | ✓ | ✘ | Änderungen am Parameter `tool_choice` betreffen nur Nachrichtenblöcke |
| **Bilder** | ✓ | ✓ | ✘ | Das Hinzufügen/Entfernen von Bildern an beliebiger Stelle im Prompt betrifft Nachrichtenblöcke |
| **Thinking-Parameter** | Modellspezifisch | Modellspezifisch | ✘ | Die Thinking-Konfiguration (Modus und `budget_tokens` im erweiterten Modus) wird in den Prompt gerendert, daher macht eine Änderung immer Nachrichtenblöcke ungültig; Tool- und System-Caches werden ebenfalls ungültig bei Modellen, die die Konfiguration vor ihnen rendern. Siehe [Nachdenken und Prompt-Caching](https://platform.claude.com/docs/de/build-with-claude/thinking#thinking-and-prompt-caching). |
| **Effort-Einstellung** | Modellspezifisch | Modellspezifisch | ✘ | Das Ändern des Werts [`output_config.effort`](https://platform.claude.com/docs/de/build-with-claude/effort) macht immer Nachrichtenblöcke ungültig, mit derselben modellspezifischen Auswirkung auf Tool- und System-Caches wie bei Thinking-Parametern. Effort explizit auf den Standardwert des Modells zu setzen, entspricht dem Weglassen und macht nichts ungültig. Bei Modellen, die [Effort pro Nachricht](https://platform.claude.com/docs/de/build-with-claude/effort#change-effort-mid-conversation-beta) unterstützen, lässt eine Effort-Änderung, die in einer `role: "system"`-Nachricht innerhalb von `messages` übermittelt wird, das gecachte Präfix intakt. |
| **Nicht-Tool-Ergebnisse in Anfragen mit Nachdenken** | ✓ | ✓ | Modellspezifisch | Bei Opus 4.5+, Sonnet 4.6+ und Haiku 5.5 werden Thinking-Blöcke standardmäßig beibehalten, sodass der Cache gültig bleibt (✓). Bei früheren Opus-/Sonnet-Modellen und Haiku-Modellen bis einschließlich Claude Haiku 4.5 werden alle zuvor gecachten Thinking-Blöcke aus dem Kontext entfernt, und alle Nachrichten, die auf diese Thinking-Blöcke folgen, werden aus dem Cache entfernt (✘). Weitere Details findest du unter [Caching mit Thinking-Blöcken](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#caching-with-thinking-blocks). |
| **Verworfene Thinking-Blöcke** | ✓ | ✓ | ✘ | Wenn die API einen Thinking-Block von Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5 oder Claude Haiku 5.5 verwirft, der bei dieser Anfrage nicht [beibehalten](https://platform.claude.com/docs/de/build-with-claude/thinking#preserved-thinking) wird (zum Beispiel einen, den du an ein Modell zurückspielst, das ihn nicht lesen kann), ändert sich das gecachte Präfix bei dieser Anfrage ab der Position dieses Blocks. Blöcke, die das empfangende Modell lesen kann und die unverändert zurückgegeben werden, lassen den Cache intakt. |
Bei Modellen, die [Tool-Änderungen mitten im Gespräch](https://platform.claude.com/docs/de/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes) unterstützen, ermöglicht dir der Beta-Header `inline-tools-2026-09-15`, mitten in einem Gespräch ein Tool hinzuzufügen oder die Definition eines Tools zu ändern, ohne `tools` zu bearbeiten. Sende die Definition in einem `tool_addition`-Block in einer Systemnachricht mitten im Gespräch und lass `tools` genau so, wie du es ursprünglich gesendet hast. Das gecachte Präfix stimmt weiterhin überein, sodass nur die angehängte Nachricht als neuer Input verarbeitet wird. Die einzige Ausnahme ist ein `tools`-Array ohne nicht-verzögertes Tool, bei dem das erste auf diese Weise definierte Tool bei dieser Anfrage einen vollständigen Cache-Miss kostet. Siehe [Tools in einer Nachricht definieren](https://platform.claude.com/docs/de/build-with-claude/mid-conversation-system-messages#define-tools-in-a-message-beta).
Bei Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/de/models/mythos-5-1/overview), Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/de/models/mythos-5/overview), Claude Opus 5.5, Claude Opus 4.8, Claude Opus 5, Claude Sonnet 5.5 und Claude Haiku 5.5 kannst du mitten in einem Gespräch eine neue Systemanweisung hinzufügen, ohne die System- oder Messages-Caches ungültig zu machen. Hänge eine `{"role": "system"}`-Nachricht an `messages` an, anstatt das `system`-Feld auf oberster Ebene zu bearbeiten, sodass das gecachte Präfix unverändert bleibt. Diese Funktion ist auf Claude Sonnet 5 nicht verfügbar. Verwende dort stattdessen das `system`-Feld auf oberster Ebene. Siehe [Systemnachrichten mitten im Gespräch](https://platform.claude.com/docs/de/build-with-claude/mid-conversation-system-messages).
### Cache-Leistung überwachen
Überwache die Cache-Leistung mit diesen API-Antwortfeldern innerhalb von `usage` in der Antwort (oder im `message_start`-Event beim [Streaming](https://platform.claude.com/docs/de/build-with-claude/streaming)):
* `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 für diese Anfrage aus dem Cache abgerufen wurden.
* `input_tokens`: Anzahl der Input-Token, die weder aus dem Cache gelesen noch zum Erstellen eines Caches verwendet wurden (also Token nach dem letzten Cache-Breakpoint).
**Die Aufschlüsselung der Token verstehen**
Das Feld `input_tokens` umfasst nur die Token, die **nach dem letzten Cache-Breakpoint** in deiner Anfrage kommen, nicht alle Input-Token, die du gesendet hast.
So berechnest du die gesamten Input-Token:
```text wrap
total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens
```
**Räumliche Erklärung:**
* `cache_read_input_tokens` = Token vor dem Breakpoint, die bereits gecacht sind (Lesevorgänge)
* `cache_creation_input_tokens` = Token vor dem Breakpoint, die jetzt gecacht werden (Schreibvorgänge)
* `input_tokens` = Token nach deinem letzten Breakpoint (nicht für den Cache geeignet)
**Beispiel:** Wenn du eine Anfrage mit 100.000 Token gecachter Inhalte (aus dem Cache gelesen), 0 Token neuer Inhalte, die gecacht werden, und 50 Token in deiner Benutzernachricht (nach dem Cache-Breakpoint) hast:
* `cache_read_input_tokens`: 100.000
* `cache_creation_input_tokens`: 0
* `input_tokens`: 50
* **Insgesamt verarbeitete Input-Token:** 100.050 Token
Das ist wichtig, um sowohl die Kosten als auch die Ratenlimits zu verstehen, da `input_tokens` bei effektiver Nutzung des Cachings in der Regel deutlich kleiner ist als dein gesamter Input.
### Caching mit Thinking-Blöcken
Wenn du [Nachdenken](https://platform.claude.com/docs/de/build-with-claude/thinking) mit Prompt-Caching verwendest, haben Thinking-Blöcke ein besonderes Verhalten:
**Automatisches Caching zusammen mit anderen Inhalten:** Obwohl Thinking-Blöcke nicht explizit mit `cache_control` markiert werden können, werden sie als Teil des Anfrageinhalts gecacht, wenn du nachfolgende API-Aufrufe mit Tool-Ergebnissen machst. Dies geschieht häufig bei der Tool-Nutzung, wenn du Thinking-Blöcke zurückgibst, um das Gespräch fortzusetzen.
**Zählung der Input-Token:** Wenn Thinking-Blöcke aus dem Cache gelesen werden, zählen sie in deinen Nutzungsmetriken als Input-Token. Dies ist wichtig für die Kostenberechnung und die Token-Budgetierung.
**Muster der Cache-Invalidierung:**
* Der Cache bleibt gültig, wenn nur Tool-Ergebnisse als Benutzernachrichten bereitgestellt werden
* Bei Opus 4.5+, Sonnet 4.6+ und Haiku 5.5 werden Thinking-Blöcke standardmäßig beibehalten, selbst wenn Benutzerinhalte hinzugefügt werden, die keine Tool-Ergebnisse sind, sodass der Cache gültig bleibt
* Bei früheren Opus-/Sonnet-Modellen und Haiku-Modellen bis einschließlich Claude Haiku 4.5 wird der Cache ungültig, wenn Benutzerinhalte hinzugefügt werden, die keine Tool-Ergebnisse sind, wodurch alle vorherigen Thinking-Blöcke aus dem Kontext entfernt werden
* Dieses Caching-Verhalten tritt auch ohne explizite `cache_control`-Markierungen auf
Weitere Details zur Cache-Invalidierung findest du unter [Was den Cache ungültig macht](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#what-invalidates-the-cache).
**Beispiel mit Tool-Nutzung:**
```text wrap
Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]
Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2 caches its request content (not the response)
# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1
Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# Depending on the model, this non-tool-result user block either keeps prior thinking blocks or strips them (see the next paragraph)
```
Bei früheren Opus-/Sonnet-Modellen und Haiku-Modellen bis einschließlich Claude Haiku 4.5 werden an diesem Punkt alle vorherigen Thinking-Blöcke aus dem Kontext entfernt. Bei Opus 4.5+, Sonnet 4.6+ und Haiku 5.5 werden vorherige Thinking-Blöcke standardmäßig beibehalten und bleiben Teil des gecachten Präfixes.
Ausführlichere Informationen findest du unter [Nachdenken und Prompt-Caching](https://platform.claude.com/docs/de/build-with-claude/thinking#thinking-and-prompt-caching).
### Cache-Speicherung und -Freigabe
Prompt-Caching verwendet eine Isolierung auf [Workspace](https://platform.claude.com/docs/de/manage-claude/workspaces)-Ebene. Caches sind pro Workspace isoliert, was die Datentrennung zwischen Workspaces innerhalb derselben Organisation gewährleistet. Dies gilt für die Claude API, Claude Platform on AWS und Microsoft Foundry; Bedrock und Google Cloud verwenden eine Cache-Isolierung auf Organisationsebene. Wenn du mehrere Workspaces verwendest, überprüfe deine Caching-Strategie, um diesen Unterschied zu berücksichtigen.
* **Isolierung von Organisationen und Workspaces:** Caches sind zwischen Organisationen isoliert. Verschiedene Organisationen teilen niemals Caches, selbst wenn sie identische Prompts verwenden. In der Claude API, auf Claude Platform on AWS und Microsoft Foundry sind Caches zusätzlich pro Workspace innerhalb einer Organisation isoliert; Bedrock und Google Cloud verwenden nur eine Isolierung auf Organisationsebene.
* **Exakte Übereinstimmung:** Cache-Treffer erfordern zu 100 % identische Prompt-Segmente, einschließlich aller Texte und Bilder bis einschließlich des mit Cache-Control markierten Blocks.
* **Generierung von Output-Token:** Prompt-Caching hat keinen Einfluss auf die Generierung von Output-Token. Die Antwort, die du erhältst, ist identisch mit der, die du ohne Prompt-Caching erhalten würdest.
### Best Practices für effektives Caching
So optimierst du die Leistung des Prompt-Cachings:
* Beginne bei Gesprächen mit mehreren Runden mit [automatischem Caching](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#automatic-caching). Es übernimmt die Verwaltung der Breakpoints automatisch.
* Verwende [explizite Breakpoints auf Blockebene](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#explicit-cache-breakpoints), wenn du verschiedene Abschnitte mit unterschiedlicher Änderungshäufigkeit cachen musst.
* Cache stabile, wiederverwendbare Inhalte wie Systemanweisungen, Hintergrundinformationen, große Kontexte oder häufig verwendete Tool-Definitionen.
* Platziere gecachte Inhalte für die beste Leistung am Anfang des Prompts.
* Setze Cache-Breakpoints strategisch ein, um verschiedene cachebare Präfixabschnitte voneinander zu trennen.
* Platziere den Breakpoint auf dem letzten Block, der über Anfragen hinweg identisch bleibt. Bei einem Prompt mit statischem Präfix und variablem Suffix (Zeitstempel, anfragespezifischer Kontext, die eingehende Nachricht) ist das das Ende des Präfixes, nicht der variable Block.
* Analysiere regelmäßig die Cache-Trefferquoten und passe deine Strategie bei Bedarf an.
### Optimierung für verschiedene Anwendungsfälle
Passe deine Prompt-Caching-Strategie an dein Szenario an:
* Konversationsagenten: Reduziere Kosten und „latency" (Latenz) bei längeren Gesprächen, insbesondere bei solchen mit langen Anweisungen oder hochgeladenen Dokumenten.
* Coding-Assistenten: Verbessere die Autovervollständigung und Fragen & Antworten zur Codebasis, indem du relevante Abschnitte oder eine zusammengefasste Version der Codebasis im Prompt behältst.
* Verarbeitung großer Dokumente: Binde vollständiges, umfangreiches Material einschließlich Bildern in deinen Prompt ein, ohne die Antwortlatenz zu erhöhen.
* Detaillierte Anweisungssätze: Teile umfangreiche Listen von Anweisungen, Verfahren und Beispielen, um Claudes Antworten feinabzustimmen. Entwickler fügen oft ein oder zwei Beispiele in den Prompt ein, aber mit Prompt-Caching kannst du eine noch bessere Leistung erzielen, indem du mehr als 20 vielfältige Beispiele hochwertiger Antworten einbindest.
* Agentische Tool-Nutzung: Verbessere die Leistung in Szenarien mit mehreren Tool-Aufrufen und iterativen Codeänderungen, bei denen jeder Schritt typischerweise einen neuen API-Aufruf erfordert.
* Mit Büchern, Fachartikeln, Dokumentationen, Podcast-Transkripten und anderen umfangreichen Inhalten sprechen: Erwecke jede Wissensdatenbank zum Leben, indem du das gesamte Dokument bzw. die gesamten Dokumente in den Prompt einbettest und Benutzer Fragen dazu stellen lässt.
### Behebung häufiger Probleme
Bei unerwartetem Verhalten:
Mit der [Cache-Diagnose](https://platform.claude.com/docs/de/build-with-claude/cache-diagnostics) vergleicht die API aufeinanderfolgende Anfragen und meldet, wo das Prompt-Präfix abgewichen ist, wodurch viele der Schritte in dieser Liste automatisch erledigt werden.
* Stelle sicher, dass gecachte Abschnitte über Aufrufe hinweg identisch sind. Überprüfe bei expliziten Breakpoints, dass sich die `cache_control`-Markierungen an denselben Stellen befinden
* Prüfe, ob die Aufrufe innerhalb der Cache-Lebensdauer erfolgen (standardmäßig 5 Minuten)
* Überprüfe, ob `tool_choice`, die Verwendung von Bildern, die Thinking-Konfiguration und `output_config.effort` zwischen den Aufrufen gleich bleiben
* Stelle sicher, dass du mindestens die Mindestanzahl an Token für dein Modell und deine Plattform cachst (siehe [Cache-Einschränkungen](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#cache-limitations))
* Vergewissere dich, dass dein Breakpoint auf einem Block liegt, der über Anfragen hinweg identisch bleibt. Cache-Schreibvorgänge finden nur am Breakpoint statt, und wenn sich dieser Block ändert (Zeitstempel, anfragespezifischer Kontext, die eingehende Nachricht), stimmt der Präfix-Hash nie überein. Der Lookback findet keine stabilen Inhalte hinter dem Breakpoint; er findet nur Einträge, die frühere Anfragen an ihren eigenen Breakpoints geschrieben haben
* Überprüfe, ob die Schlüssel in deinen `tool_use`-Inhaltsblöcken eine stabile Reihenfolge haben, da einige Sprachen (zum Beispiel Swift, Go) die Schlüsselreihenfolge bei der JSON-Konvertierung zufällig anordnen, was Caches unbrauchbar macht
* Verwende die [Cache-Diagnose](https://platform.claude.com/docs/de/build-with-claude/cache-diagnostics), damit die API aufeinanderfolgende Anfragen vergleicht und meldet, welcher Teil des Prompts abgewichen ist
Änderungen an `tool_choice` oder das Vorhandensein/Fehlen von Bildern an beliebiger Stelle im Prompt machen den Cache ungültig, sodass ein neuer Cache-Eintrag erstellt werden muss. Weitere Details zur Cache-Invalidierung findest du unter [Was den Cache ungültig macht](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#what-invalidates-the-cache).
***
## Cache-Dauer von 1 Stunde
Wenn dir 5 Minuten zu kurz sind, bietet Anthropic auch eine Cache-Dauer von 1 Stunde [gegen Aufpreis](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#pricing) an.
Die Cache-Dauer von 1 Stunde ist in der Claude API, auf [Amazon Bedrock](https://platform.claude.com/docs/de/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (Opus 4.6 und früher)](https://platform.claude.com/docs/de/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Platform on AWS](https://platform.claude.com/docs/de/build-with-claude/claude-platform-on-aws), [Google Cloud](https://platform.claude.com/docs/de/build-with-claude/claude-on-vertex-ai) und [Microsoft Foundry](https://platform.claude.com/docs/de/build-with-claude/claude-in-microsoft-foundry) verfügbar.
Um den erweiterten Cache zu verwenden, füge `ttl` wie folgt in die `cache_control`-Definition ein:
```json
"cache_control": {
"type": "ephemeral",
"ttl": "1h"
}
```
Die Antwort enthält detaillierte Cache-Informationen wie die folgenden:
```json Output
{
"usage": {
"input_tokens": 2048,
"cache_read_input_tokens": 1800,
"cache_creation_input_tokens": 248,
"output_tokens": 503,
"cache_creation": {
"ephemeral_5m_input_tokens": 148,
"ephemeral_1h_input_tokens": 100
}
}
}
```
Beachte, dass das aktuelle Feld `cache_creation_input_tokens` der Summe der Werte im `cache_creation`-Objekt entspricht.
Wenn du bei der Verwendung von Server-Tools wie der Websuche `ephemeral_5m_input_tokens`-Schreibvorgänge siehst, die du nicht angefordert hast, siehe [Tool-Nutzung mit Prompt-Caching](https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-use-with-prompt-caching#server-tool-results-are-cached-automatically).
### Wann der 1-Stunden-Cache sinnvoll ist
Wenn du Prompts hast, die in regelmäßigen Abständen verwendet werden (also System-Prompts, die häufiger als alle 5 Minuten verwendet werden), verwende weiterhin den 5-Minuten-Cache, da dieser weiterhin ohne zusätzliche Kosten aufgefrischt wird.
Der 1-Stunden-Cache eignet sich am besten für die folgenden Szenarien:
* Wenn du Prompts hast, die voraussichtlich seltener als alle 5 Minuten, aber häufiger als stündlich verwendet werden. Zum Beispiel, wenn ein agentischer Nebenagent länger als 5 Minuten braucht oder wenn du ein langes Chat-Gespräch mit einem Benutzer speicherst und generell davon ausgehst, dass dieser Benutzer in den nächsten 5 Minuten möglicherweise nicht antwortet.
* Wenn die Latenz wichtig ist und deine Folge-Prompts möglicherweise erst nach mehr als 5 Minuten gesendet werden.
* Wenn du die Auslastung deines Ratenlimits verbessern möchtest, da Cache-Treffer nicht auf dein Ratenlimit angerechnet werden.
Der 5-Minuten- und der 1-Stunden-Cache verhalten sich in Bezug auf die Latenz gleich. Bei langen Dokumenten wirst du in der Regel eine verbesserte Zeit bis zum ersten Token feststellen.
### Verschiedene TTLs mischen
Du kannst sowohl 1-Stunden- als auch 5-Minuten-Cache-Controls in derselben Anfrage verwenden, allerdings mit einer wichtigen Einschränkung: Cache-Einträge mit längerer TTL müssen vor kürzeren TTLs erscheinen (das heißt, ein 1-Stunden-Cache-Eintrag muss vor allen 5-Minuten-Cache-Einträgen erscheinen).
Beim Mischen von TTLs bestimmt die API drei Abrechnungspositionen in deinem Prompt:
1. Position `A`: Die Token-Anzahl beim höchsten Cache-Treffer (oder 0, wenn es keine Treffer gibt).
2. Position `B`: Die Token-Anzahl beim höchsten 1-Stunden-`cache_control`-Block nach `A` (oder gleich `A`, wenn keiner existiert).
3. Position `C`: Die Token-Anzahl beim letzten `cache_control`-Block.
Wenn `B` oder `C` größer als `A` ist, handelt es sich zwangsläufig um einen Cache-Fehltreffer, da `A` der höchste Cache-Treffer ist.
Dir wird Folgendes berechnet:
1. Cache-Lese-Token für `A`.
2. 1-Stunden-Cache-Schreib-Token für `(B - A)`.
3. 5-Minuten-Cache-Schreib-Token für `(C - B)`.
Hier sind drei Beispiele. Dargestellt sind die Eingabe-Token von 3 Anfragen, von denen jede unterschiedliche Cache-Treffer und Cache-Fehltreffer aufweist. Jede hat daher eine unterschiedlich berechnete Preisgestaltung, die in den farbigen Kästen angezeigt wird.
***
## Den Cache vorwärmen
„Cache pre-warming" (Vorwärmen des Caches) ermöglicht es dir, deinen System-Prompt oder deine Tool-Definitionen in den Prompt-Cache zu laden, bevor ein Benutzer eine echte Anfrage auslöst. Dadurch entfällt die Latenzeinbuße durch einen Cache-Fehltreffer bei der ersten Benutzerinteraktion, was die „time-to-first-token" (Zeit bis zum ersten Token), oder TTFT, für latenzempfindliche Anwendungen reduziert.
### Funktionsweise
Setze `max_tokens: 0` in deiner Anfrage. Die API liest deinen Prompt in das Modell ein und schreibt den Cache an jedem `cache_control`-Breakpoint, kehrt dann sofort zurück, ohne eine Ausgabe zu generieren. Die Antwort enthält ein leeres `content`-Array, `stop_reason: "max_tokens"` und einen vollständig befüllten `usage`-Block.
Platziere den `cache_control`-Breakpoint auf dem letzten Block, der mit der Folgeanfrage geteilt wird (typischerweise dein System-Prompt oder deine Tool-Definitionen), nicht auf der Platzhalter-Benutzernachricht. Andernfalls ist der Cache-Eintrag an den Platzhalter gebunden, und die Folgeanfrage trifft ihn nicht. Verwende außerdem dieselbe Nachdenk-Konfiguration und denselben `output_config.effort`-Wert wie in deinen Folgeanfragen: Diese Werte werden in den Prompt gerendert (siehe [Was den Cache ungültig macht](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#what-invalidates-the-cache)), sodass ein Vorwärmen mit einer anderen Konfiguration einen Eintrag schreiben kann, den dein echter Traffic nie trifft. Das bedeutet, dass du einen [expliziten Cache-Breakpoint](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#explicit-cache-breakpoints) statt [automatischem Caching](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#automatic-caching) verwendest, da automatisches Caching den Breakpoint auf den letzten Block setzt, der hier der Platzhalter ist. Die Platzhalter-Benutzernachricht kann eine beliebige Zeichenkette sein, deren Inhalt nicht nur aus Leerzeichen besteht (die Beispiele hier verwenden `"warmup"`); ihr Inhalt wird in das Modell eingelesen, aber nie beantwortet.
Eine Vorwärm-Anfrage verursacht eine Gebühr für einen **Cache-Schreibvorgang**, wenn das Präfix noch nicht gecacht ist, genau wie jede andere Anfrage. Prüfe `usage.cache_creation_input_tokens` in der Antwort, um zu bestätigen, dass ein Schreibvorgang stattgefunden hat. Es werden null Ausgabe-Token berechnet.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 0,
"system": [
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [{"role": "user", "content": "warmup"}]
}'
```
```bash CLI
ant messages create \
--transform '{stop_reason,content,usage}' --format yaml <<'YAML'
model: claude-opus-5-5
max_tokens: 0
system:
- type: text
text: >-
You are an expert software engineer with deep knowledge of
distributed systems...
cache_control:
type: ephemeral
messages:
- role: user
content: warmup
YAML
```
```python Python
client = anthropic.Anthropic()
# Führe dies aus, bevor Nutzer kommen, um den gemeinsamen System-Prompt-Cache vorzuwärmen.
prewarm = client.messages.create(
model="claude-opus-5-5",
max_tokens=0,
system=[
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"},
}
],
messages=[{"role": "user", "content": "warmup"}],
)
print(prewarm.stop_reason) # "max_tokens"
print(prewarm.content) # []
print(prewarm.usage)
```
```typescript TypeScript
const client = new Anthropic();
// Führe dies aus, bevor Nutzer kommen, um den gemeinsamen System-Prompt-Cache vorzuwärmen.
const prewarm = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 0,
system: [
{
type: "text",
text: "You are an expert software engineer with deep knowledge of distributed systems...",
cache_control: { type: "ephemeral" }
}
],
messages: [{ role: "user", content: "warmup" }]
});
console.log(prewarm.stop_reason); // "max_tokens"
console.log(prewarm.content); // []
console.log(prewarm.usage);
```
```csharp C#
AnthropicClient client = new();
var prewarm = await client.Messages.Create(
new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 0,
System = new(
[
new TextBlockParam
{
Text = "You are an expert software engineer with deep knowledge of distributed systems...",
CacheControl = new(),
},
]
),
Messages = [new() { Role = Role.User, Content = "warmup" }],
}
);
Console.WriteLine(prewarm.StopReason?.Raw()); // "max_tokens"
Console.WriteLine(prewarm.Content.Count); // 0
Console.WriteLine(prewarm.Usage);
```
```go Go
client := anthropic.NewClient()
prewarm, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 0,
System: []anthropic.TextBlockParam{
{
Text: "You are an expert software engineer with deep knowledge of distributed systems...",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("warmup")),
},
})
if err != nil {
panic(err)
}
fmt.Println(prewarm.StopReason) // "max_tokens"
fmt.Println(prewarm.Content) // []
fmt.Println(prewarm.Usage.RawJSON())
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Message prewarm = client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(0)
.systemOfTextBlockParams(List.of(TextBlockParam.builder()
.text("You are an expert software engineer with deep knowledge of distributed systems...")
.cacheControl(CacheControlEphemeral.builder().build())
.build()))
.addUserMessage("warmup")
.build());
IO.println(prewarm.stopReason()); // Optional[max_tokens]
IO.println(prewarm.content()); // []
IO.println(prewarm.usage());
```
```php PHP
$client = new Client();
$prewarm = $client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 0,
system: [
[
'type' => 'text',
'text' => 'You are an expert software engineer with deep knowledge of distributed systems...',
'cache_control' => ['type' => 'ephemeral'],
],
],
messages: [['role' => 'user', 'content' => 'warmup']],
);
echo $prewarm->stopReason, PHP_EOL; // "max_tokens"
echo json_encode($prewarm->content), PHP_EOL; // []
echo json_encode($prewarm->usage), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
prewarm = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 0,
system_: [
{
type: "text",
text: "You are an expert software engineer with deep knowledge of distributed systems...",
cache_control: {type: "ephemeral"}
}
],
messages: [{role: "user", content: "warmup"}]
)
puts prewarm.stop_reason # :max_tokens
puts prewarm.content # []
puts prewarm.usage
```
Die API gibt ein leeres `content`-Array zurück:
```json Output
{
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"content": [],
"model": "claude-opus-5-5",
"stop_reason": "max_tokens",
"stop_sequence": null,
"usage": {
"input_tokens": 8,
"cache_creation_input_tokens": 5120,
"cache_read_input_tokens": 0,
"cache_creation": {
"ephemeral_5m_input_tokens": 5120,
"ephemeral_1h_input_tokens": 0
},
"iterations": [
{
"input_tokens": 8,
"output_tokens": 0,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 5120,
"cache_creation": {
"ephemeral_5m_input_tokens": 5120,
"ephemeral_1h_input_tokens": 0
},
"type": "message"
}
],
"output_tokens": 0,
"service_tier": "standard",
"inference_geo": "global"
}
}
```
### Typisches Nutzungsmuster
Sende eine Vorwärm-Anfrage, wenn deine Anwendung startet (oder in einem geplanten Intervall), und sende dann echte Benutzeranfragen, nachdem das Vorwärmen abgeschlossen ist:
```bash cURL
# Wärme den Cache beim Anwendungsstart oder in geplanten Intervallen vor.
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 0,
"system": [
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [{"role": "user", "content": "warmup"}]
}'
# Wenn der Nutzer später eine Nachricht sendet, ist das System-Prompt-Präfix bereits im Cache.
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [{"role": "user", "content": "How do I implement a binary search tree?"}]
}'
```
```bash CLI
# Wärme den Cache beim Anwendungsstart oder in einem geplanten Intervall auf.
ant messages create --transform usage <<'YAML'
model: claude-opus-5-5
max_tokens: 0
system:
- type: text
text: >-
You are an expert software engineer with deep knowledge of
distributed systems...
cache_control:
type: ephemeral
messages:
- role: user
content: warmup
YAML
# Wenn der Nutzer später eine Nachricht sendet, ist das System-Prompt-Präfix bereits gecacht.
ant messages create --transform 'content.#(type=="text").text' --raw-output <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
system:
- type: text
text: >-
You are an expert software engineer with deep knowledge of
distributed systems...
cache_control:
type: ephemeral
messages:
- role: user
content: How do I implement a binary search tree?
YAML
```
```python Python
client = anthropic.Anthropic()
SYSTEM_PROMPT = [
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"},
}
]
def prewarm_cache() -> None:
"""Call this at application startup or on a scheduled interval."""
client.messages.create(
model="claude-opus-5-5",
max_tokens=0,
system=SYSTEM_PROMPT,
messages=[{"role": "user", "content": "warmup"}],
)
def respond(user_message: str) -> anthropic.types.Message:
"""The real user request; benefits from a warm cache."""
return client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system=SYSTEM_PROMPT,
messages=[{"role": "user", "content": user_message}],
)
# Wärme den Cache vor, bevor Nutzer-Traffic eintrifft.
prewarm_cache()
# Wenn der Nutzer später eine Nachricht sendet, ist das System-Prompt-Präfix bereits gecacht.
response = respond("How do I implement a binary search tree?")
for block in response.content:
if block.type == "text":
print(block.text)
```
```typescript TypeScript
const client = new Anthropic();
const SYSTEM_PROMPT: Anthropic.TextBlockParam[] = [
{
type: "text",
text: "You are an expert software engineer with deep knowledge of distributed systems...",
cache_control: { type: "ephemeral" }
}
];
// Rufe dies beim Anwendungsstart oder in einem festen Intervall auf.
async function prewarmCache(): Promise {
await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 0,
system: SYSTEM_PROMPT,
messages: [{ role: "user", content: "warmup" }]
});
}
// Die eigentliche Nutzeranfrage; profitiert von einem vorgewärmten Cache.
async function respond(userMessage: string): Promise {
return client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
system: SYSTEM_PROMPT,
messages: [{ role: "user", content: userMessage }]
});
}
// Wärme den Cache vor, bevor Nutzer-Traffic eintrifft.
await prewarmCache();
// Wenn der Nutzer später eine Nachricht sendet, ist das System-Prompt-Präfix bereits gecacht.
const response = await respond("How do I implement a binary search tree?");
const textBlock = response.content.find(
(block): block is Anthropic.TextBlock => block.type === "text"
);
console.log(textBlock?.text);
```
```csharp C#
AnthropicClient client = new();
List systemPrompt =
[
new TextBlockParam
{
Text = "You are an expert software engineer with deep knowledge of distributed systems...",
CacheControl = new(),
},
];
// Rufe dies beim Anwendungsstart oder in einem geplanten Intervall auf.
async Task PrewarmCache() =>
await client.Messages.Create(
new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 0,
System = new(systemPrompt),
Messages = [new() { Role = Role.User, Content = "warmup" }],
}
);
// Die eigentliche Nutzeranfrage; profitiert von einem vorgewärmten Cache.
async Task Respond(string userMessage) =>
await client.Messages.Create(
new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
System = new(systemPrompt),
Messages = [new() { Role = Role.User, Content = userMessage }],
}
);
// Wärme den Cache vor, bevor Nutzer-Traffic eintrifft.
await PrewarmCache();
// Wenn der Nutzer später eine Nachricht sendet, ist das System-Prompt-Präfix bereits gecacht.
var response = await Respond("How do I implement a binary search tree?");
foreach (var block in response.Content)
{
if (block.TryPickText(out var textBlock))
{
Console.WriteLine(textBlock.Text);
}
}
```
```go Go
var client = anthropic.NewClient()
var systemPrompt = []anthropic.TextBlockParam{
{
Text: "You are an expert software engineer with deep knowledge of distributed systems...",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
}
// Rufe dies beim Anwendungsstart oder in einem festen Intervall auf.
func prewarmCache() error {
_, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 0,
System: systemPrompt,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("warmup")),
},
})
return err
}
// Die eigentliche Nutzeranfrage; profitiert von einem vorgewärmten Cache.
func respond(userMessage string) (*anthropic.Message, error) {
return client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
System: systemPrompt,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock(userMessage)),
},
})
}
func main() {
// Wärme den Cache vor, bevor Nutzer-Traffic eintrifft.
if err := prewarmCache(); err != nil {
log.Fatal(err)
}
// Wenn der Nutzer später eine Nachricht sendet, ist das System-Prompt-Präfix bereits gecacht.
response, err := respond("How do I implement a binary search tree?")
if err != nil {
log.Fatal(err)
}
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
fmt.Println(textBlock.Text)
}
}
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
List systemPrompt = List.of(TextBlockParam.builder()
.text("You are an expert software engineer with deep knowledge of distributed systems...")
.cacheControl(CacheControlEphemeral.builder().build())
.build());
// Rufe dies beim Anwendungsstart oder in einem festen Intervall auf.
void prewarmCache() {
client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(0)
.systemOfTextBlockParams(systemPrompt)
.addUserMessage("warmup")
.build());
}
// Die eigentliche Nutzeranfrage; profitiert von einem vorgewärmten Cache.
Message respond(String userMessage) {
return client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.systemOfTextBlockParams(systemPrompt)
.addUserMessage(userMessage)
.build());
}
void main() {
// Wärme den Cache vor, bevor Nutzer-Traffic eintrifft.
prewarmCache();
// Wenn der Nutzer später eine Nachricht sendet, ist das System-Prompt-Präfix bereits gecacht.
Message response = respond("How do I implement a binary search tree?");
response.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> IO.println(textBlock.text()));
}
```
```php PHP
$client = new Client();
$systemPrompt = [
[
'type' => 'text',
'text' => 'You are an expert software engineer with deep knowledge of distributed systems...',
'cache_control' => ['type' => 'ephemeral'],
],
];
// Rufe dies beim Start der Anwendung oder in einem geplanten Intervall auf.
$prewarmCache = fn () => $client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 0,
system: $systemPrompt,
messages: [['role' => 'user', 'content' => 'warmup']],
);
// Die eigentliche Nutzeranfrage; profitiert von einem vorgewärmten Cache.
$respond = fn (string $userMessage) => $client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 1024,
system: $systemPrompt,
messages: [['role' => 'user', 'content' => $userMessage]],
);
// Wärme den Cache vor, bevor Nutzer-Traffic eintrifft.
$prewarmCache();
// Wenn der Nutzer später eine Nachricht sendet, ist das System-Prompt-Präfix bereits gecacht.
$response = $respond('How do I implement a binary search tree?');
foreach ($response->content as $block) {
if ($block->type === 'text') {
echo $block->text, PHP_EOL;
}
}
```
```ruby Ruby
client = Anthropic::Client.new
SYSTEM_PROMPT = [
{
type: "text",
text: "You are an expert software engineer with deep knowledge of distributed systems...",
cache_control: {type: "ephemeral"}
}
]
# Rufe dies beim Start der Anwendung oder in einem festen Intervall auf.
def prewarm_cache(client)
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 0,
system_: SYSTEM_PROMPT,
messages: [{role: "user", content: "warmup"}]
)
end
# Die eigentliche Nutzeranfrage; profitiert von einem vorgewärmten Cache.
def respond(client, user_message)
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
system_: SYSTEM_PROMPT,
messages: [{role: "user", content: user_message}]
)
end
# Wärme den Cache vor, bevor Nutzer-Traffic eintrifft.
prewarm_cache(client)
# Wenn der Nutzer später eine Nachricht sendet, ist das System-Prompt-Präfix bereits gecacht.
response = respond(client, "How do I implement a binary search tree?")
response.content.each do |block|
puts block.text if block.type == :text
end
```
Beachte, dass die Cache-TTL weiterhin gilt. Sende beim standardmäßigen 5-Minuten-Cache mindestens alle 5 Minuten eine neue Vorwärm-Anfrage, um den Cache warm zu halten. Verwende bei längeren Pausen zwischen Benutzeranfragen stattdessen die [1-Stunden-Cache-Dauer](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#1-hour-cache-duration).
### Einschränkungen
Eine Anfrage mit `max_tokens: 0` wird mit einem `invalid_request_error` abgelehnt, wenn eine der folgenden Optionen gesetzt ist, da jede davon eine Ausgabe voraussetzt, die ein Budget von null Token nicht erzeugen kann:
* `stream: true`
* [Erweitertes Nachdenken](https://platform.claude.com/docs/de/build-with-claude/extended-thinking) (`thinking.type: "enabled"`)
* [Strukturierte Ausgaben](https://platform.claude.com/docs/de/build-with-claude/structured-outputs) (`output_config.format`)
* `tool_choice` mit `{"type": "tool", ...}` oder `{"type": "any"}`
`max_tokens: 0` wird außerdem innerhalb einer [Message Batches](https://platform.claude.com/docs/de/build-with-claude/batch-processing)-Anfrage abgelehnt. Das Vorwärmen zielt auf die Zeit bis zum ersten Token ab, die für die Batch-Verarbeitung keine Rolle spielt, und ein während der Batch-Verarbeitung geschriebener Cache-Eintrag würde wahrscheinlich ablaufen, bevor die Folgeanfrage ausgeführt wird.
### Den max\_tokens=1-Workaround ersetzen
Bevor `max_tokens: 0` verfügbar war, verwendeten einige Anwendungen Aufwärm-Aufrufe mit `max_tokens: 1`, um denselben Effekt zu erzielen. Der Ansatz mit `max_tokens: 0` ist vorzuziehen: Es wird keine Ausgabe erzeugt, sodass keine Ein-Token-Antwort verworfen werden muss, keine Ausgabe-Token berechnet werden und die Absicht der Anfrage eindeutig ist.
***
## Beispiele für Prompt-Caching
Um dir den Einstieg in das Prompt-Caching zu erleichtern, bietet das [Prompt-Caching-Cookbook](https://platform.claude.com/cookbook/misc-prompt-caching) ausführliche Beispiele und Best Practices.
Die folgenden Code-Snippets zeigen verschiedene Prompt-Caching-Muster. Diese Beispiele demonstrieren, wie du Caching in unterschiedlichen Szenarien implementierst, und helfen dir, die praktischen Anwendungen dieser Funktion zu verstehen:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "You are an AI assistant tasked with analyzing legal documents."
},
{
"type": "text",
"text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{
"role": "user",
"content": "What are the key terms and conditions in this agreement?"
}
]
}'
```
```bash CLI
ant messages create --transform usage <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
system:
- type: text
text: You are an AI assistant tasked with analyzing legal documents.
- type: text
text: >-
Here is the full text of a complex legal agreement:
[Insert full text of a 50-page legal agreement here]
cache_control:
type: ephemeral
messages:
- role: user
content: What are the key terms and conditions in this agreement?
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system=[
{
"type": "text",
"text": "You are an AI assistant tasked with analyzing legal documents.",
},
{
"type": "text",
"text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
"cache_control": {"type": "ephemeral"},
},
],
messages=[
{
"role": "user",
"content": "What are the key terms and conditions in this agreement?",
}
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
system: [
{
type: "text",
text: "You are an AI assistant tasked with analyzing legal documents."
},
{
type: "text",
text: "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
cache_control: { type: "ephemeral" }
}
],
messages: [
{
role: "user",
content: "What are the key terms and conditions in this agreement?"
}
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new()
{
ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
};
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
System = new MessageCreateParamsSystem(new List
{
new TextBlockParam()
{
Text = "You are an AI assistant tasked with analyzing legal documents.",
},
new TextBlockParam()
{
Text = "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
CacheControl = new CacheControlEphemeral(),
},
}),
Messages =
[
new()
{
Role = Role.User,
Content = "What are the key terms and conditions in this agreement?"
}
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
System: []anthropic.TextBlockParam{
{
Text: "You are an AI assistant tasked with analyzing legal documents.",
},
{
Text: "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What are the key terms and conditions in this agreement?")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
public class LegalDocumentAnalysisExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.systemOfTextBlockParams(
List.of(
TextBlockParam.builder()
.text("You are an AI assistant tasked with analyzing legal documents.")
.build(),
TextBlockParam.builder()
.text(
"Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]"
)
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
.addUserMessage("What are the key terms and conditions in this agreement?")
.build();
Message message = client.messages().create(params);
System.out.println(message.usage());
}
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 1024,
messages: [
[
'role' => 'user',
'content' => 'What are the key terms and conditions in this agreement?'
]
],
model: 'claude-opus-5-5',
system: [
[
'type' => 'text',
'text' => 'You are an AI assistant tasked with analyzing legal documents.'
],
[
'type' => 'text',
'text' => 'Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]',
'cache_control' => ['type' => 'ephemeral']
]
],
);
echo json_encode($message->usage), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
system: [
{
type: "text",
text: "You are an AI assistant tasked with analyzing legal documents."
},
{
type: "text",
text: "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
cache_control: { type: "ephemeral" }
}
],
messages: [
{
role: "user",
content: "What are the key terms and conditions in this agreement?"
}
]
)
puts message.usage
```
Dieses Beispiel demonstriert die grundlegende Verwendung von Prompt-Caching, wobei der vollständige Text der Rechtsvereinbarung als Präfix gecacht wird, während die Benutzeranweisung ungecacht bleibt.
Für die erste Anfrage:
* `input_tokens`: Anzahl der Token nur in der Benutzernachricht
* `cache_creation_input_tokens`: Anzahl der Token in der gesamten Systemnachricht, einschließlich des Rechtsdokuments
* `cache_read_input_tokens`: 0 (kein Cache-Treffer bei der ersten Anfrage)
Für nachfolgende Anfragen innerhalb der Cache-Lebensdauer:
* `input_tokens`: Anzahl der Token nur in der Benutzernachricht
* `cache_creation_input_tokens`: 0 (keine neue Cache-Erstellung)
* `cache_read_input_tokens`: Anzahl der Token in der gesamten gecachten Systemnachricht
Tool-Definitionen können gecacht werden, indem du `cache_control` auf das letzte Tool in deinem `tools`-Array setzt. Alle Tools, die vor diesem Tool definiert sind, einschließlich dieses Tools selbst, werden als ein einziges Präfix gecacht.
```json
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"tools": [
{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": { "location": { "type": "string" } },
"required": ["location"]
}
},
{
"name": "get_time",
"description": "Get the current time in a given time zone",
"input_schema": {
"type": "object",
"properties": { "timezone": { "type": "string" } },
"required": ["timezone"]
},
"cache_control": { "type": "ephemeral" }
}
],
"messages": [{ "role": "user", "content": "What is the weather and time in New York?" }]
}
```
Bei der ersten Anfrage spiegelt `cache_creation_input_tokens` die Token-Anzahl aller Tool-Definitionen wider. Bei nachfolgenden Anfragen innerhalb der Cache-Lebensdauer erscheinen diese Token stattdessen unter `cache_read_input_tokens`.
Details zum Zusammenspiel von Tool-Definitionen, `defer_loading` und Cache-Invalidierung findest du unter [Tool-Nutzung mit Prompt-Caching](https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-use-with-prompt-caching).
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "...long system prompt",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Hello, can you tell me more about the solar system?"
}
]
},
{
"role": "assistant",
"content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?"
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "Good to know."
},
{
"type": "text",
"text": "Tell me more about Mars.",
"cache_control": {"type": "ephemeral"}
}
]
}
]
}'
```
```bash CLI
ant messages create --transform usage <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
system:
- type: text
text: "...long system prompt"
cache_control:
type: ephemeral
messages:
- role: user
content:
- type: text
text: Hello, can you tell me more about the solar system?
- role: assistant
content: >-
Certainly! The solar system is the collection of celestial bodies that
orbit our Sun. It consists of eight planets, numerous moons, asteroids,
comets, and other objects. The planets, in order from closest to farthest
from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus,
and Neptune. Each planet has its own unique characteristics and features.
Is there a specific aspect of the solar system you would like to know
more about?
- role: user
content:
- type: text
text: Good to know.
- type: text
text: Tell me more about Mars.
cache_control:
type: ephemeral
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system=[
{
"type": "text",
"text": "...long system prompt",
"cache_control": {"type": "ephemeral"},
}
],
messages=[
# ...bisher lange Unterhaltung
{
"role": "user",
"content": [
{
"type": "text",
"text": "Hello, can you tell me more about the solar system?",
}
],
},
{
"role": "assistant",
"content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you'd like to know more about?",
},
{
"role": "user",
"content": [
{"type": "text", "text": "Good to know."},
{
"type": "text",
"text": "Tell me more about Mars.",
"cache_control": {"type": "ephemeral"},
},
],
},
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
system: [
{
type: "text",
text: "...long system prompt",
cache_control: { type: "ephemeral" }
}
],
messages: [
// ...bisherige lange Unterhaltung
{
role: "user",
content: [
{
type: "text",
text: "Hello, can you tell me more about the solar system?"
}
]
},
{
role: "assistant",
content:
"Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you'd like to know more about?"
},
{
role: "user",
content: [
{
type: "text",
text: "Good to know."
},
{
type: "text",
text: "Tell me more about Mars.",
cache_control: { type: "ephemeral" }
}
]
}
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
System = new MessageCreateParamsSystem(new List
{
new TextBlockParam()
{
Text = "...long system prompt",
CacheControl = new CacheControlEphemeral(),
},
}),
Messages =
[
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new TextBlockParam("Hello, can you tell me more about the solar system?")),
}),
},
new()
{
Role = Role.Assistant,
Content = "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?"
},
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new TextBlockParam("Good to know.")),
new ContentBlockParam(new TextBlockParam()
{
Text = "Tell me more about Mars.",
CacheControl = new CacheControlEphemeral(),
}),
})
}
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
System: []anthropic.TextBlockParam{
{
Text: "...long system prompt",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, can you tell me more about the solar system?")),
anthropic.NewAssistantMessage(anthropic.NewTextBlock("Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?")),
{
Role: anthropic.MessageParamRoleUser,
Content: []anthropic.ContentBlockParamUnion{
anthropic.NewTextBlock("Good to know."),
{OfText: &anthropic.TextBlockParam{
Text: "Tell me more about Mars.",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
}},
},
},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
public class ConversationWithCacheControlExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Erstelle einen kurzlebigen System-Prompt
TextBlockParam systemPrompt = TextBlockParam.builder()
.text("...long system prompt")
.cacheControl(CacheControlEphemeral.builder().build())
.build();
// Erstelle die Nachrichtenparameter
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.systemOfTextBlockParams(List.of(systemPrompt))
// Erste Nutzernachricht (ohne Cache-Control)
.addUserMessage("Hello, can you tell me more about the solar system?")
// Antwort des Assistenten
.addAssistantMessage(
"Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?"
)
// Zweite Nutzernachricht (mit Cache-Control)
.addUserMessageOfBlockParams(
List.of(
ContentBlockParam.ofText(TextBlockParam.builder().text("Good to know.").build()),
ContentBlockParam.ofText(
TextBlockParam.builder()
.text("Tell me more about Mars.")
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
)
.build();
Message message = client.messages().create(params);
System.out.println(message.usage());
}
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 1024,
messages: [
[
'role' => 'user',
'content' => [
[
'type' => 'text',
'text' => 'Hello, can you tell me more about the solar system?'
]
]
],
[
'role' => 'assistant',
'content' => "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?"
],
[
'role' => 'user',
'content' => [
['type' => 'text', 'text' => 'Good to know.'],
[
'type' => 'text',
'text' => 'Tell me more about Mars.',
'cache_control' => ['type' => 'ephemeral']
]
]
]
],
model: 'claude-opus-5-5',
system: [
[
'type' => 'text',
'text' => '...long system prompt',
'cache_control' => ['type' => 'ephemeral']
]
],
);
echo json_encode($message->usage), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
system: [
{
type: "text",
text: "...long system prompt",
cache_control: { type: "ephemeral" }
}
],
messages: [
{
role: "user",
content: [
{
type: "text",
text: "Hello, can you tell me more about the solar system?"
}
]
},
{
role: "assistant",
content: "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?"
},
{
role: "user",
content: [
{ type: "text", text: "Good to know." },
{
type: "text",
text: "Tell me more about Mars.",
cache_control: { type: "ephemeral" }
}
]
}
]
)
puts message.usage
```
Dieses Beispiel demonstriert, wie du Prompt-Caching in einer Multi-Turn-Konversation verwendest.
In jedem Turn wird der letzte Block der letzten Nachricht mit `cache_control` markiert, sodass die Konversation inkrementell gecacht werden kann. Das System sucht automatisch die längste zuvor gecachte Sequenz von Blöcken und verwendet sie für Folgenachrichten. Das heißt, Blöcke, die zuvor mit einem `cache_control`-Block markiert waren, werden später nicht mehr damit markiert, gelten aber dennoch als Cache-Treffer (und auch als Cache-Aktualisierung!), wenn sie innerhalb von 5 Minuten getroffen werden.
Beachte außerdem, dass der `cache_control`-Parameter auf der Systemnachricht platziert ist. Damit wird sichergestellt, dass sie, falls sie aus dem Cache entfernt wird (nachdem sie mehr als 5 Minuten nicht verwendet wurde), bei der nächsten Anfrage wieder in den Cache aufgenommen wird.
Dieser Ansatz ist nützlich, um den Kontext in laufenden Konversationen beizubehalten, ohne dieselben Informationen wiederholt zu verarbeiten.
Wenn dies korrekt eingerichtet ist, solltest du in der Usage-Antwort jeder Anfrage Folgendes sehen:
* `input_tokens`: Anzahl der Token in der neuen Benutzernachricht (wird minimal sein)
* `cache_creation_input_tokens`: Anzahl der Token in den neuen Assistenten- und Benutzer-Turns
* `cache_read_input_tokens`: Anzahl der Token in der Konversation bis zum vorherigen Turn
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"tools": [
{
"name": "search_documents",
"description": "Search through the knowledge base",
"input_schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search query"
}
},
"required": ["query"]
}
},
{
"name": "get_document",
"description": "Retrieve a specific document by ID",
"input_schema": {
"type": "object",
"properties": {
"doc_id": {
"type": "string",
"description": "Document ID"
}
},
"required": ["doc_id"]
},
"cache_control": {"type": "ephemeral"}
}
],
"system": [
{
"type": "text",
"text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
"cache_control": {"type": "ephemeral"}
},
{
"type": "text",
"text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{
"role": "user",
"content": "Can you search for information about Mars rovers?"
},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "tool_1",
"name": "search_documents",
"input": {"query": "Mars rovers"}
}
]
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "tool_1",
"content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)"
}
]
},
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document."
}
]
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "Yes, please tell me about the Perseverance rover specifically.",
"cache_control": {"type": "ephemeral"}
}
]
}
]
}'
```
```bash CLI
ant messages create --transform usage <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
tools:
- name: search_documents
description: Search through the knowledge base
input_schema:
type: object
properties:
query:
type: string
description: Search query
required: [query]
- name: get_document
description: Retrieve a specific document by ID
input_schema:
type: object
properties:
doc_id:
type: string
description: Document ID
required: [doc_id]
cache_control:
type: ephemeral
system:
- type: text
text: |-
You are a helpful research assistant with access to a document knowledge base.
# Instructions
- Always search for relevant documents before answering
- Provide citations for your sources
- Be objective and accurate in your responses
- If multiple documents contain relevant information, synthesize them
- Acknowledge when information is not available in the knowledge base
cache_control:
type: ephemeral
- type: text
text: |-
# Knowledge Base Context
Here are the relevant documents for this conversation:
## Document 1: Solar System Overview
The solar system consists of the Sun and all objects that orbit it...
## Document 2: Planetary Characteristics
Each planet has unique features. Mercury is the smallest planet...
## Document 3: Mars Exploration
Mars has been a target of exploration for decades...
[Additional documents...]
cache_control:
type: ephemeral
messages:
- role: user
content: Can you search for information about Mars rovers?
- role: assistant
content:
- type: tool_use
id: tool_1
name: search_documents
input:
query: Mars rovers
- role: user
content:
- type: tool_result
tool_use_id: tool_1
content: >-
Found 3 relevant documents: Document 3 (Mars Exploration),
Document 7 (Rover Technology), Document 9 (Mission History)
- role: assistant
content:
- type: text
text: >-
I found 3 relevant documents about Mars rovers. Let me get more
details from the Mars Exploration document.
- role: user
content:
- type: text
text: Yes, please tell me about the Perseverance rover specifically.
cache_control:
type: ephemeral
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=[
{
"name": "search_documents",
"description": "Search through the knowledge base",
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "Search query"}
},
"required": ["query"],
},
},
{
"name": "get_document",
"description": "Retrieve a specific document by ID",
"input_schema": {
"type": "object",
"properties": {
"doc_id": {"type": "string", "description": "Document ID"}
},
"required": ["doc_id"],
},
"cache_control": {"type": "ephemeral"},
},
],
system=[
{
"type": "text",
"text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
"cache_control": {"type": "ephemeral"},
},
{
"type": "text",
"text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
"cache_control": {"type": "ephemeral"},
},
],
messages=[
{
"role": "user",
"content": "Can you search for information about Mars rovers?",
},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "tool_1",
"name": "search_documents",
"input": {"query": "Mars rovers"},
}
],
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "tool_1",
"content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
}
],
},
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",
}
],
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "Yes, please tell me about the Perseverance rover specifically.",
"cache_control": {"type": "ephemeral"},
}
],
},
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
tools: [
{
name: "search_documents",
description: "Search through the knowledge base",
input_schema: {
type: "object",
properties: {
query: {
type: "string",
description: "Search query"
}
},
required: ["query"]
}
},
{
name: "get_document",
description: "Retrieve a specific document by ID",
input_schema: {
type: "object",
properties: {
doc_id: {
type: "string",
description: "Document ID"
}
},
required: ["doc_id"]
},
cache_control: { type: "ephemeral" }
}
],
system: [
{
type: "text",
text: "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
cache_control: { type: "ephemeral" }
},
{
type: "text",
text: "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
cache_control: { type: "ephemeral" }
}
],
messages: [
{
role: "user",
content: "Can you search for information about Mars rovers?"
},
{
role: "assistant",
content: [
{
type: "tool_use",
id: "tool_1",
name: "search_documents",
input: { query: "Mars rovers" }
}
]
},
{
role: "user",
content: [
{
type: "tool_result",
tool_use_id: "tool_1",
content:
"Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)"
}
]
},
{
role: "assistant",
content: [
{
type: "text",
text: "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document."
}
]
},
{
role: "user",
content: [
{
type: "text",
text: "Yes, please tell me about the Perseverance rover specifically.",
cache_control: { type: "ephemeral" }
}
]
}
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new()
{
ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
};
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Tools =
[
new ToolUnion(new Tool()
{
Name = "search_documents",
Description = "Search through the knowledge base",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["query"] = JsonSerializer.SerializeToElement(new { type = "string", description = "Search query" }),
},
Required = ["query"],
},
}),
new ToolUnion(new Tool()
{
Name = "get_document",
Description = "Retrieve a specific document by ID",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["doc_id"] = JsonSerializer.SerializeToElement(new { type = "string", description = "Document ID" }),
},
Required = ["doc_id"],
},
CacheControl = new CacheControlEphemeral(),
}),
],
System = new MessageCreateParamsSystem(new List
{
new TextBlockParam()
{
Text = "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
CacheControl = new CacheControlEphemeral(),
},
new TextBlockParam()
{
Text = "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
CacheControl = new CacheControlEphemeral(),
},
}),
Messages =
[
new() { Role = Role.User, Content = "Can you search for information about Mars rovers?" },
new()
{
Role = Role.Assistant,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new ToolUseBlockParam()
{
ID = "tool_1",
Name = "search_documents",
Input = new Dictionary
{
["query"] = JsonSerializer.SerializeToElement("Mars rovers"),
},
}),
}),
},
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new ToolResultBlockParam()
{
ToolUseID = "tool_1",
Content = "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
}),
}),
},
new()
{
Role = Role.Assistant,
Content = "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",
},
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new TextBlockParam()
{
Text = "Yes, please tell me about the Perseverance rover specifically.",
CacheControl = new CacheControlEphemeral(),
}),
}),
},
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: []anthropic.ToolUnionParam{
{OfTool: &anthropic.ToolParam{
Name: "search_documents",
Description: anthropic.String("Search through the knowledge base"),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"query": map[string]any{
"type": "string",
"description": "Search query",
},
},
Required: []string{"query"},
},
}},
{OfTool: &anthropic.ToolParam{
Name: "get_document",
Description: anthropic.String("Retrieve a specific document by ID"),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"doc_id": map[string]any{
"type": "string",
"description": "Document ID",
},
},
Required: []string{"doc_id"},
},
CacheControl: anthropic.NewCacheControlEphemeralParam(),
}},
},
System: []anthropic.TextBlockParam{
{
Text: "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
{
Text: "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Can you search for information about Mars rovers?")),
anthropic.NewAssistantMessage(anthropic.NewToolUseBlock(
"tool_1",
map[string]any{"query": "Mars rovers"},
"search_documents",
)),
anthropic.NewUserMessage(anthropic.NewToolResultBlock(
"tool_1",
"Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
false,
)),
anthropic.NewAssistantMessage(anthropic.NewTextBlock("I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.")),
{
Role: anthropic.MessageParamRoleUser,
Content: []anthropic.ContentBlockParamUnion{
{OfText: &anthropic.TextBlockParam{
Text: "Yes, please tell me about the Perseverance rover specifically.",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
}},
},
},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
public class MultipleCacheBreakpointsExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Schema des Such-Tools
InputSchema searchSchema = InputSchema.builder()
.properties(
JsonValue.from(
Map.of("query", Map.of("type", "string", "description", "Search query"))
)
)
.putAdditionalProperty("required", JsonValue.from(List.of("query")))
.build();
// Schema des Tools zum Abrufen von Dokumenten
InputSchema getDocSchema = InputSchema.builder()
.properties(
JsonValue.from(
Map.of("doc_id", Map.of("type", "string", "description", "Document ID"))
)
)
.putAdditionalProperty("required", JsonValue.from(List.of("doc_id")))
.build();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
// Tools mit Cache-Control beim letzten Tool
.addTool(
Tool.builder()
.name("search_documents")
.description("Search through the knowledge base")
.inputSchema(searchSchema)
.build()
)
.addTool(
Tool.builder()
.name("get_document")
.description("Retrieve a specific document by ID")
.inputSchema(getDocSchema)
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
// System-Prompts mit Cache-Control getrennt für Anweisungen und Kontext
.systemOfTextBlockParams(
List.of(
TextBlockParam.builder()
.text(
"You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base"
)
.cacheControl(CacheControlEphemeral.builder().build())
.build(),
TextBlockParam.builder()
.text(
"# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]"
)
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
// Gesprächsverlauf
.addUserMessage("Can you search for information about Mars rovers?")
.addAssistantMessageOfBlockParams(
List.of(
ContentBlockParam.ofToolUse(
ToolUseBlockParam.builder()
.id("tool_1")
.name("search_documents")
.input(JsonValue.from(Map.of("query", "Mars rovers")))
.build()
)
)
)
.addUserMessageOfBlockParams(
List.of(
ContentBlockParam.ofToolResult(
ToolResultBlockParam.builder()
.toolUseId("tool_1")
.content(
"Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)"
)
.build()
)
)
)
.addAssistantMessageOfBlockParams(
List.of(
ContentBlockParam.ofText(
TextBlockParam.builder()
.text(
"I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document."
)
.build()
)
)
)
.addUserMessageOfBlockParams(
List.of(
ContentBlockParam.ofText(
TextBlockParam.builder()
.text("Yes, please tell me about the Perseverance rover specifically.")
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
)
.build();
Message message = client.messages().create(params);
System.out.println(message.usage());
}
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 1024,
messages: [
[
'role' => 'user',
'content' => 'Can you search for information about Mars rovers?'
],
[
'role' => 'assistant',
'content' => [
[
'type' => 'tool_use',
'id' => 'tool_1',
'name' => 'search_documents',
'input' => ['query' => 'Mars rovers']
]
]
],
[
'role' => 'user',
'content' => [
[
'type' => 'tool_result',
'tool_use_id' => 'tool_1',
'content' => 'Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)'
]
]
],
[
'role' => 'assistant',
'content' => [
[
'type' => 'text',
'text' => 'I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.'
]
]
],
[
'role' => 'user',
'content' => [
[
'type' => 'text',
'text' => 'Yes, please tell me about the Perseverance rover specifically.',
'cache_control' => ['type' => 'ephemeral']
]
]
]
],
model: 'claude-opus-5-5',
system: [
[
'type' => 'text',
'text' => "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
'cache_control' => ['type' => 'ephemeral']
],
[
'type' => 'text',
'text' => "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
'cache_control' => ['type' => 'ephemeral']
]
],
tools: [
[
'name' => 'search_documents',
'description' => 'Search through the knowledge base',
'input_schema' => [
'type' => 'object',
'properties' => [
'query' => [
'type' => 'string',
'description' => 'Search query'
]
],
'required' => ['query']
]
],
[
'name' => 'get_document',
'description' => 'Retrieve a specific document by ID',
'input_schema' => [
'type' => 'object',
'properties' => [
'doc_id' => [
'type' => 'string',
'description' => 'Document ID'
]
],
'required' => ['doc_id']
],
'cache_control' => ['type' => 'ephemeral']
]
],
);
echo json_encode($message->usage), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
tools: [
{
name: "search_documents",
description: "Search through the knowledge base",
input_schema: {
type: "object",
properties: {
query: {
type: "string",
description: "Search query"
}
},
required: ["query"]
}
},
{
name: "get_document",
description: "Retrieve a specific document by ID",
input_schema: {
type: "object",
properties: {
doc_id: {
type: "string",
description: "Document ID"
}
},
required: ["doc_id"]
},
cache_control: { type: "ephemeral" }
}
],
system: [
{
type: "text",
text: "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
cache_control: { type: "ephemeral" }
},
{
type: "text",
text: "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
cache_control: { type: "ephemeral" }
}
],
messages: [
{
role: "user",
content: "Can you search for information about Mars rovers?"
},
{
role: "assistant",
content: [
{
type: "tool_use",
id: "tool_1",
name: "search_documents",
input: { query: "Mars rovers" }
}
]
},
{
role: "user",
content: [
{
type: "tool_result",
tool_use_id: "tool_1",
content: "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)"
}
]
},
{
role: "assistant",
content: [
{
type: "text",
text: "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document."
}
]
},
{
role: "user",
content: [
{
type: "text",
text: "Yes, please tell me about the Perseverance rover specifically.",
cache_control: { type: "ephemeral" }
}
]
}
]
)
puts message.usage
```
Dieses umfassende Beispiel demonstriert, wie du alle 4 verfügbaren Cache-Breakpoints nutzt, um verschiedene Teile deines Prompts zu optimieren:
1. **Tools-Cache** (Cache-Breakpoint 1): Der `cache_control`-Parameter auf der letzten Tool-Definition cacht alle Tool-Definitionen.
2. **Cache für wiederverwendbare Anweisungen** (Cache-Breakpoint 2): Die statischen Anweisungen im System-Prompt werden separat gecacht. Diese Anweisungen ändern sich zwischen Anfragen selten.
3. **RAG-Kontext-Cache** (Cache-Breakpoint 3): Die Dokumente der Wissensdatenbank werden unabhängig gecacht, sodass du die RAG-Dokumente aktualisieren kannst, ohne den Tools- oder Anweisungs-Cache ungültig zu machen.
4. **Cache für den Konversationsverlauf** (Cache-Breakpoint 4): Die letzte Benutzernachricht wird mit `cache_control` markiert, um ein inkrementelles Caching der Konversation im Verlauf zu ermöglichen.
Dieser Ansatz bietet maximale Flexibilität:
* Wenn du einen neuen Turn an die Konversation anhängst, ohne früheren Inhalt zu ändern, werden alle vier Cache-Segmente wiederverwendet
* Wenn du die RAG-Dokumente aktualisierst, aber dieselben Tools und Anweisungen beibehältst, werden die ersten beiden Cache-Segmente wiederverwendet
* Wenn du die Konversation änderst, aber dieselben Tools, Anweisungen und Dokumente beibehältst, werden die ersten drei Segmente wiederverwendet
* Änderungen an einem beliebigen Breakpoint machen dieses Segment und alles danach ungültig, während früher gecachte Segmente gültig bleiben
Für die erste Anfrage:
* `input_tokens`: Minimal (Token nach dem letzten Cache-Breakpoint, in diesem Beispiel nahe 0)
* `cache_creation_input_tokens`: Token in allen gecachten Segmenten (Tools + Anweisungen + RAG-Dokumente + Konversationsverlauf)
* `cache_read_input_tokens`: 0 (keine Cache-Treffer)
Für nachfolgende Anfragen mit nur einer neuen Benutzernachricht (und dem vierten Breakpoint, der wie im Beispiel auf diese neue letzte Nachricht verschoben wurde):
* `input_tokens`: Minimal (Token nach dem letzten Cache-Breakpoint, in diesem Beispiel nahe 0)
* `cache_creation_input_tokens`: Token in der neuen Benutzernachricht und im vorherigen Assistenten-Turn (das neue Konversationssegment, das gecacht wird)
* `cache_read_input_tokens`: Alle zuvor gecachten Token (Tools + Anweisungen + RAG-Dokumente + vorherige Konversation)
Dieses Muster ist besonders leistungsstark für:
* RAG-Anwendungen mit großen Dokumentkontexten
* Agentensysteme, die mehrere Tools verwenden
* Lang laufende Konversationen, die den Kontext beibehalten müssen
* Anwendungen, die verschiedene Teile des Prompts unabhängig voneinander optimieren müssen
## Datenaufbewahrung
Prompt-Caching (sowohl automatisch als auch explizit) ist ZDR-berechtigt. Anthropic speichert nicht den Rohtext deiner Prompts oder der Antworten von Claude.
KV-Cache-Repräsentationen (Key-Value) und kryptografische Hashes gecachter Inhalte werden nur im Arbeitsspeicher gehalten und nicht dauerhaft gespeichert. Gecachte Einträge haben eine Mindestlebensdauer von 5 Minuten (Standard) oder 1 Stunde (erweitert), nach der sie zeitnah, wenn auch nicht sofort, gelöscht werden. Cache-Einträge sind zwischen Organisationen isoliert und auf der Claude API, Claude Platform on AWS und Microsoft Foundry zusätzlich zwischen Workspaces innerhalb einer Organisation.
Informationen zur ZDR-Berechtigung aller Funktionen findest du unter [API und Datenaufbewahrung](https://platform.claude.com/docs/de/manage-claude/api-and-data-retention).
***
## FAQ
**In den meisten Fällen reicht ein einzelner Cache-Breakpoint am Ende deines statischen Inhalts aus.** Cache-Schreibvorgänge finden nur an dem Block statt, den du markierst. Platziere ihn auf dem letzten Block, der über alle Anfragen hinweg identisch bleibt, und jede nachfolgende Anfrage liest denselben Eintrag. Wenn ein späterer Block pro Anfrage variiert (ein Zeitstempel, die eingehende Nachricht), setze den Breakpoint davor, auf den letzten stabilen Block.
Mehrere Breakpoints brauchst du nur, wenn:
* Eine wachsende Konversation deinen Breakpoint 20 oder mehr Blöcke über den letzten Cache-Schreibvorgang hinaus verschiebt, sodass der vorherige Eintrag außerhalb des Lookback-Fensters liegt
* Du Abschnitte, die sich in unterschiedlicher Häufigkeit ändern, unabhängig voneinander cachen möchtest
* Du zur Kostenoptimierung explizite Kontrolle darüber benötigst, was gecacht wird
Beispiel: Wenn du Systemanweisungen (ändern sich selten) und RAG-Kontext (ändert sich täglich) hast, könntest du zwei Breakpoints verwenden, um sie separat zu cachen.
Nein, Cache-Breakpoints selbst sind kostenlos. Du zahlst nur für:
* Das Schreiben von Inhalten in den Cache (25 % mehr als Basis-Eingabe-Token bei 5-Minuten-TTL)
* Das Lesen aus dem Cache (ein Bruchteil des Basis-Eingabe-Token-Preises, siehe [Preise](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#pricing))
* Reguläre Eingabe-Token für ungecachte Inhalte
Die Anzahl der Breakpoints beeinflusst die Preisgestaltung nicht; es zählt nur die Menge der gecachten und gelesenen Inhalte.
Die Usage-Antwort enthält drei separate Felder für Eingabe-Token, die zusammen deine gesamte Eingabe darstellen:
```text wrap
total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens
```
* `cache_read_input_tokens`: Aus dem Cache abgerufene Token (alles vor Cache-Breakpoints, was gecacht wurde)
* `cache_creation_input_tokens`: Neue Token, die in den Cache geschrieben werden (an Cache-Breakpoints)
* `input_tokens`: Token **nach dem letzten Cache-Breakpoint**, die nicht gecacht sind
**Wichtig:** `input_tokens` stellt NICHT alle Eingabe-Token dar, sondern nur den Teil nach deinem letzten Cache-Breakpoint. Wenn du gecachte Inhalte hast, ist `input_tokens` typischerweise viel kleiner als deine gesamte Eingabe.
**Beispiel:** Mit einem gecachten Dokument von 200k Token und einer Benutzerfrage mit 50 Token:
* `cache_read_input_tokens`: 200.000
* `cache_creation_input_tokens`: 0
* `input_tokens`: 50
* **Gesamt:** 200.050 Token
Diese Aufschlüsselung ist entscheidend, um sowohl deine Kosten als auch deine Ratenlimit-Nutzung zu verstehen. Weitere Details findest du unter [Cache-Leistung verfolgen](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#tracking-cache-performance).
Die standardmäßige Mindestlebensdauer (TTL) des Caches beträgt 5 Minuten. Diese Lebensdauer wird jedes Mal erneuert, wenn der gecachte Inhalt verwendet wird.
Wenn dir 5 Minuten zu kurz sind, bietet Anthropic auch eine [1-Stunden-Cache-TTL](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#1-hour-cache-duration) an.
Die Lebensdauer wird ab dem Beginn der Anfrage gemessen, die den Cache-Eintrag schreibt oder liest, nicht ab dem Ende ihrer Antwort. Die Zeit, die für das Generieren einer Antwort aufgewendet wird, zählt zur Lebensdauer, sodass das Zeitfenster, in dem eine Folgeanfrage den Cache wiederverwenden kann, der Lebensdauer abzüglich der Generierungszeit entspricht.
Wenn deine Anfragen lange Antworten erzeugen und die nächste Anfrage möglicherweise erst nach Ablauf der Lebensdauer beginnt, verwende die [1-Stunden-Cache-TTL](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#1-hour-cache-duration).
Du kannst bis zu 4 Cache-Breakpoints (mithilfe von `cache_control`-Parametern) in deinem Prompt definieren.
Prompt-Caching wird von allen [aktiven Claude-Modellen](https://platform.claude.com/docs/de/models/overview) unterstützt.
Das Ändern von Nachdenk-Parametern (Wechseln des Modus oder Ändern des Budgets im erweiterten Modus) macht gecachte Nachrichtenpräfixe ungültig und kann auch gecachte System-Prompts und Tools ungültig machen, da die Nachdenk-Konfiguration in den Prompt gerendert wird. Der Wert [`output_config.effort`](https://platform.claude.com/docs/de/build-with-claude/effort) verhält sich genauso.
Weitere Details zur Cache-Invalidierung findest du unter [Was den Cache ungültig macht](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#what-invalidates-the-cache).
Mehr zum Nachdenken, einschließlich seines Zusammenspiels mit Tool-Nutzung und Prompt-Caching, findest du unter [Nachdenken und Prompt-Caching](https://platform.claude.com/docs/de/build-with-claude/thinking#thinking-and-prompt-caching).
Am einfachsten fügst du `"cache_control": {"type": "ephemeral"}` auf der obersten Ebene deines Request-Bodys hinzu ([automatisches Caching](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#automatic-caching)). Alternativ kannst du mindestens einen `cache_control`-Breakpoint auf einzelnen Inhaltsblöcken einfügen ([explizite Cache-Breakpoints](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#explicit-cache-breakpoints)).
Ja, Prompt-Caching kann zusammen mit anderen API-Funktionen wie Tool-Nutzung und Vision-Fähigkeiten verwendet werden. Wenn du jedoch änderst, ob ein Prompt Bilder enthält, oder die Einstellungen für die Tool-Nutzung anpasst, wird der Cache ungültig.
Weitere Details zur Cache-Invalidierung findest du unter [Was den Cache ungültig macht](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#what-invalidates-the-cache).
Prompt-Caching führt eine neue Preisstruktur ein, bei der 5-Minuten-Cache-Schreibvorgänge 25 % mehr kosten als Basis-Eingabe-Token, 1-Stunden-Cache-Schreibvorgänge das 2-Fache der Basis-Eingabe-Token kosten und Cache-Treffer einen Bruchteil des Basis-Eingabe-Token-Preises kosten (den Multiplikator pro Modell findest du unter [Preise](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#pricing)).
Derzeit gibt es keine Möglichkeit, den Cache manuell zu leeren. Gecachte Präfixe laufen automatisch nach mindestens 5 Minuten Inaktivität ab.
Du kannst die Cache-Leistung mithilfe der Felder `cache_creation_input_tokens` und `cache_read_input_tokens` in der API-Antwort überwachen.
Weitere Details zur Cache-Invalidierung, einschließlich einer Liste von Änderungen, die das Erstellen eines neuen Cache-Eintrags erfordern, findest du unter [Was den Cache ungültig macht](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#what-invalidates-the-cache).
Prompt-Caching ist mit starken Maßnahmen für Datenschutz und Datentrennung konzipiert:
1. Cache-Schlüssel werden mithilfe eines kryptografischen Hashes der Prompts bis zum Cache-Control-Punkt generiert. Das bedeutet, dass nur Anfragen mit identischen Prompts auf einen bestimmten Cache zugreifen können.
2. Auf der Claude API, Claude Platform on AWS und Microsoft Foundry sind Caches pro Workspace innerhalb einer Organisation isoliert. Auf Bedrock und Google Cloud sind Caches pro Organisation isoliert. In jedem Fall werden Caches niemals organisationsübergreifend geteilt, selbst bei identischen Prompts. Details findest du unter [Cache-Speicherung und -Freigabe](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#cache-storage-and-sharing).
3. Der Caching-Mechanismus ist darauf ausgelegt, die Integrität und Vertraulichkeit jeder einzelnen Konversation bzw. jedes einzelnen Kontexts zu wahren.
4. Es ist sicher, `cache_control` an beliebiger Stelle in deinen Prompts zu verwenden. Damit Caching Lesevorgänge erzeugt, platziere den Breakpoint am Ende eines stabilen Präfixes: Wenn du ihn auf einem Block platzierst, der sich bei jeder Anfrage ändert (etwa ein Zeitstempel oder die beliebige Eingabe des Benutzers), wird jedes Mal ein neuer Eintrag geschrieben, der nie getroffen wird.
Diese Maßnahmen stellen sicher, dass Prompt-Caching Datenschutz und Sicherheit gewährleistet und gleichzeitig Leistungsvorteile bietet.
Ja, du kannst Prompt-Caching mit deinen [Batches API](https://platform.claude.com/docs/de/build-with-claude/batch-processing)-Anfragen verwenden. Da asynchrone Batch-Anfragen jedoch gleichzeitig und in beliebiger Reihenfolge verarbeitet werden können, werden Cache-Treffer nach dem Best-Effort-Prinzip bereitgestellt.
Der [1-Stunden-Cache](https://platform.claude.com/docs/de/build-with-claude/prompt-caching#1-hour-cache-duration) kann helfen, deine Cache-Treffer zu verbessern. Am kosteneffizientesten nutzt du ihn wie folgt:
* Sammle eine Reihe von Nachrichtenanfragen, die ein gemeinsames Präfix haben.
* Sende eine Batch-Anfrage mit einer einzelnen Anfrage, die dieses gemeinsame Präfix und einen 1-Stunden-Cache-Block enthält. Dadurch wird das Präfix in den 1-Stunden-Cache geschrieben.
* Sobald dies abgeschlossen ist, reiche die restlichen Anfragen ein. Du musst den Job überwachen, um zu wissen, wann er abgeschlossen ist.
Dies ist in der Regel besser als die Verwendung des 5-Minuten-Caches, da Batch-Anfragen häufig zwischen 5 Minuten und 1 Stunde bis zum Abschluss benötigen.
Dieser Fehler tritt typischerweise auf, wenn du dein SDK aktualisiert hast oder veraltete Codebeispiele verwendest. Prompt-Caching erfordert das Beta-Präfix nicht mehr. Statt:
```python Python
client.beta.prompt_caching.messages.create(**params)
```
Verwende:
```python Python
client.messages.create(**params)
```
Dieser Fehler tritt typischerweise auf, wenn du dein SDK aktualisiert hast oder veraltete Codebeispiele verwendest. Prompt-Caching erfordert das Beta-Präfix nicht mehr. Statt:
```typescript TypeScript
client.beta.promptCaching.messages.create(/* ... */);
```
Verwende:
```typescript
client.messages.create(/* ... */);
```