0
# Cached Content
1

2
Create and manage cached content to optimize repeated requests with the same context, reducing latency and token costs. Caching is useful for frequently used system instructions, large documents, or conversation starters.
3

4
## Core Imports
5

6
```java
7
import com.google.genai.Caches;
8
import com.google.genai.AsyncCaches;
9
import com.google.genai.Pager;
10
import com.google.genai.types.CachedContent;
11
import com.google.genai.types.CreateCachedContentConfig;
12
import com.google.genai.types.UpdateCachedContentConfig;
13
import com.google.genai.types.DeleteCachedContentResponse;
14
```
15

16
## Caches Service
17

18
```java { .api }
19
package com.google.genai;
20

21
public final class Caches {
22
  public CachedContent create(CreateCachedContentConfig config);
23
  public CachedContent get(String name, GetCachedContentConfig config);
24
  public CachedContent update(String name, UpdateCachedContentConfig config);
25
  public DeleteCachedContentResponse delete(String name, DeleteCachedContentConfig config);
26
  public Pager<CachedContent> list(ListCachedContentsConfig config);
27
}
28
```
29

30
## Cached Content Type
31

32
```java { .api }
33
package com.google.genai.types;
34

35
public final class CachedContent {
36
  public static Builder builder();
37

38
  public Optional<String> name();
39
  public Optional<String> displayName();
40
  public Optional<String> model();
41
  public Optional<String> createTime();
42
  public Optional<String> updateTime();
43
  public Optional<String> expireTime();
44
  public Optional<List<Content>> contents();
45
  public Optional<List<Tool>> tools();
46
  public Optional<ToolConfig> toolConfig();
47
  public Optional<Content> systemInstruction();
48
  public Optional<CachedContentUsageMetadata> usageMetadata();
49
}
50
```
51

52
## Create Cached Content
53

54
```java
55
import com.google.genai.types.CreateCachedContentConfig;
56
import com.google.genai.types.Content;
57
import com.google.genai.types.Part;
58

59
// Cache a large document
60
Content document = Content.fromParts(
61
    Part.fromText("Large document content that will be reused...")
62
);
63

64
CreateCachedContentConfig config = CreateCachedContentConfig.builder()
65
    .model("gemini-2.0-flash")
66
    .displayName("Cached Document")
67
    .contents(ImmutableList.of(document))
68
    .ttl("3600s") // Cache for 1 hour
69
    .build();
70

71
CachedContent cached = client.caches.create(config);
72
System.out.println("Cached content: " + cached.name().orElse("N/A"));
73
```
74

75
## Cache with System Instruction
76

77
```java
78
Content systemInstruction = Content.fromParts(
79
    Part.fromText("You are an expert data analyst. Analyze data carefully and provide detailed insights.")
80
);
81

82
CreateCachedContentConfig config = CreateCachedContentConfig.builder()
83
    .model("gemini-2.0-flash")
84
    .displayName("Data Analyst System")
85
    .systemInstruction(systemInstruction)
86
    .ttl("7200s") // 2 hours
87
    .build();
88

89
CachedContent cached = client.caches.create(config);
90
```
91

92
## Use Cached Content
93

94
```java
95
// Reference cached content in generation
96
GenerateContentConfig genConfig = GenerateContentConfig.builder()
97
    .cachedContent(cached.name().get())
98
    .build();
99

100
GenerateContentResponse response = client.models.generateContent(
101
    "gemini-2.0-flash",
102
    "Based on the cached context, answer this question...",
103
    genConfig
104
);
105

106
// Check token savings
107
response.usageMetadata().ifPresent(usage -> {
108
    System.out.println("Prompt tokens: " + usage.promptTokenCount().orElse(0));
109
    System.out.println("Cached tokens: " + usage.cachedContentTokenCount().orElse(0));
110
});
111
```
112

113
## Update Cached Content
114

115
```java
116
UpdateCachedContentConfig updateConfig = UpdateCachedContentConfig.builder()
117
    .ttl("7200s") // Extend to 2 hours
118
    .build();
119

120
CachedContent updated = client.caches.update(cachedName, updateConfig);
121
```
122

123
## Get Cached Content
124

125
```java
126
CachedContent cached = client.caches.get(cachedName, null);
127

128
System.out.println("Name: " + cached.name().orElse("N/A"));
129
System.out.println("Display name: " + cached.displayName().orElse("N/A"));
130
System.out.println("Model: " + cached.model().orElse("N/A"));
131
System.out.println("Expires: " + cached.expireTime().orElse("N/A"));
132

133
cached.usageMetadata().ifPresent(usage -> {
134
    System.out.println("Total tokens: " + usage.totalTokenCount().orElse(0));
135
});
136
```
137

138
## List Cached Content
139

140
```java
141
Pager<CachedContent> pager = client.caches.list(null);
142

143
for (CachedContent cached : pager) {
144
    System.out.println("Cache: " + cached.displayName().orElse("N/A"));
145
    System.out.println("  Model: " + cached.model().orElse("N/A"));
146
    System.out.println("  Expires: " + cached.expireTime().orElse("N/A"));
147
}
148
```
149

150
## Delete Cached Content
151

152
```java
153
DeleteCachedContentResponse response = client.caches.delete(cachedName, null);
154
System.out.println("Cached content deleted");
155
```
156

157
## Cache Expiration
158

159
```java
160
// Set expiration time
161
CreateCachedContentConfig config1 = CreateCachedContentConfig.builder()
162
    .model("gemini-2.0-flash")
163
    .contents(contents)
164
    .expireTime("2024-12-31T23:59:59Z") // Specific time
165
    .build();
166

167
// Set TTL (time to live)
168
CreateCachedContentConfig config2 = CreateCachedContentConfig.builder()
169
    .model("gemini-2.0-flash")
170
    .contents(contents)
171
    .ttl("3600s") // 1 hour from creation
172
    .build();
173
```
174

175
## Best Practices
176

177
### Cache Large Documents
178

179
```java
180
// Upload large file
181
File file = client.files.upload("large-document.pdf", null);
182

183
// Cache file reference
184
Content fileContent = Content.fromParts(
185
    Part.fromUri(file.uri().get(), file.mimeType().get())
186
);
187

188
CreateCachedContentConfig config = CreateCachedContentConfig.builder()
189
    .model("gemini-2.0-flash")
190
    .contents(ImmutableList.of(fileContent))
191
    .ttl("3600s")
192
    .build();
193

194
CachedContent cached = client.caches.create(config);
195

196
// Use cached content multiple times
197
for (String query : queries) {
198
    GenerateContentResponse response = client.models.generateContent(
199
        "gemini-2.0-flash",
200
        query,
201
        GenerateContentConfig.builder()
202
            .cachedContent(cached.name().get())
203
            .build()
204
    );
205
}
206
```
207

208
### Cache System Instructions
209

210
```java
211
Content systemInstruction = Content.fromParts(
212
    Part.fromText("You are a customer support agent. Be friendly and helpful.")
213
);
214

215
CreateCachedContentConfig config = CreateCachedContentConfig.builder()
216
    .model("gemini-2.0-flash")
217
    .systemInstruction(systemInstruction)
218
    .ttl("86400s") // 24 hours
219
    .build();
220

221
CachedContent cached = client.caches.create(config);
222

223
// Use for all customer support conversations
224
Chat chat = client.chats.create(
225
    "gemini-2.0-flash",
226
    GenerateContentConfig.builder()
227
        .cachedContent(cached.name().get())
228
        .build()
229
);
230
```
231