0
# Context Caching
1

2
Create and manage cached content to reduce costs and latency for repeated requests with shared context. Context caching stores frequently used content (like large documents or conversation context) so it doesn't need to be sent with every request, significantly reducing token costs and improving response times.
3

4
## Capabilities
5

6
### Create Cached Content
7

8
Create a new cached content resource containing frequently used context.
9

10
```python { .api }
11
class Caches:
12
    """Synchronous cached content management API."""
13

14
    def create(
15
        self,
16
        *,
17
        model: str,
18
        config: CreateCachedContentConfig
19
    ) -> CachedContent:
20
        """
21
        Create cached content for reuse across requests.
22

23
        Parameters:
24
            model (str): Model identifier (e.g., 'gemini-2.0-flash', 'gemini-1.5-pro').
25
            config (CreateCachedContentConfig): Cache configuration including:
26
                - contents: Content to cache (documents, conversation history, etc.)
27
                - system_instruction: System instruction to cache
28
                - tools: Tool definitions to cache
29
                - ttl: Time-to-live duration (e.g., '3600s' for 1 hour)
30
                - expire_time: Absolute expiration time
31
                - display_name: Display name for the cache
32

33
        Returns:
34
            CachedContent: Created cache with name, expiration info, and metadata.
35

36
        Raises:
37
            ClientError: For client errors (4xx status codes)
38
            ServerError: For server errors (5xx status codes)
39
        """
40
        ...
41

42
class AsyncCaches:
43
    """Asynchronous cached content management API."""
44

45
    async def create(
46
        self,
47
        *,
48
        model: str,
49
        config: CreateCachedContentConfig
50
    ) -> CachedContent:
51
        """Async version of create."""
52
        ...
53
```
54

55
**Usage Example:**
56

57
```python
58
from google.genai import Client
59
from google.genai.types import (
60
    CreateCachedContentConfig,
61
    Content,
62
    Part
63
)
64

65
client = Client(api_key='YOUR_API_KEY')
66

67
# Create large document content
68
document = """
69
[Large document text here - e.g., 50,000 tokens of product documentation]
70
"""
71

72
config = CreateCachedContentConfig(
73
    contents=[Content(parts=[Part(text=document)])],
74
    system_instruction='You are a product support assistant.',
75
    ttl='3600s',  # Cache for 1 hour
76
    display_name='Product Documentation Cache'
77
)
78

79
cache = client.caches.create(
80
    model='gemini-2.0-flash',
81
    config=config
82
)
83

84
print(f"Created cache: {cache.name}")
85
print(f"Expires: {cache.expire_time}")
86
print(f"Usage: {cache.usage_metadata.total_token_count} tokens")
87

88
# Use cache in requests
89
from google.genai.types import GenerateContentConfig
90

91
gen_config = GenerateContentConfig(
92
    cached_content=cache.name
93
)
94

95
response = client.models.generate_content(
96
    model='gemini-2.0-flash',
97
    contents='What is the return policy?',
98
    config=gen_config
99
)
100
print(response.text)
101
```
102

103
### Get Cached Content
104

105
Retrieve information about a cached content resource.
106

107
```python { .api }
108
class Caches:
109
    """Synchronous cached content management API."""
110

111
    def get(self, *, name: str) -> CachedContent:
112
        """
113
        Get cached content information.
114

115
        Parameters:
116
            name (str): Cache name in format 'cachedContents/{cache_id}'.
117

118
        Returns:
119
            CachedContent: Cache information including expiration and usage.
120

121
        Raises:
122
            ClientError: For client errors including 404 if cache not found
123
            ServerError: For server errors (5xx status codes)
124
        """
125
        ...
126

127
class AsyncCaches:
128
    """Asynchronous cached content management API."""
129

130
    async def get(self, *, name: str) -> CachedContent:
131
        """Async version of get."""
132
        ...
133
```
134

135
### Update Cached Content
136

137
Update cached content expiration time or other mutable fields.
138

139
```python { .api }
140
class Caches:
141
    """Synchronous cached content management API."""
142

143
    def update(
144
        self,
145
        *,
146
        name: str,
147
        config: UpdateCachedContentConfig
148
    ) -> CachedContent:
149
        """
150
        Update cached content.
151

152
        Parameters:
153
            name (str): Cache name in format 'cachedContents/{cache_id}'.
154
            config (UpdateCachedContentConfig): Update configuration including:
155
                - ttl: New time-to-live duration
156
                - expire_time: New absolute expiration time
157

158
        Returns:
159
            CachedContent: Updated cache information.
160

161
        Raises:
162
            ClientError: For client errors including 404 if cache not found
163
            ServerError: For server errors (5xx status codes)
164
        """
165
        ...
166

167
class AsyncCaches:
168
    """Asynchronous cached content management API."""
169

170
    async def update(
171
        self,
172
        *,
173
        name: str,
174
        config: UpdateCachedContentConfig
175
    ) -> CachedContent:
176
        """Async version of update."""
177
        ...
178
```
179

180
**Usage Example:**
181

182
```python
183
from google.genai import Client
184
from google.genai.types import UpdateCachedContentConfig
185

186
client = Client(api_key='YOUR_API_KEY')
187

188
# Extend cache expiration
189
config = UpdateCachedContentConfig(
190
    ttl='7200s'  # Extend to 2 hours
191
)
192

193
updated_cache = client.caches.update(
194
    name='cachedContents/abc123',
195
    config=config
196
)
197

198
print(f"New expiration: {updated_cache.expire_time}")
199
```
200

201
### Delete Cached Content
202

203
Delete a cached content resource. Caches are automatically deleted after expiration, but you can delete them early to free resources.
204

205
```python { .api }
206
class Caches:
207
    """Synchronous cached content management API."""
208

209
    def delete(self, *, name: str) -> None:
210
        """
211
        Delete cached content.
212

213
        Parameters:
214
            name (str): Cache name in format 'cachedContents/{cache_id}'.
215

216
        Raises:
217
            ClientError: For client errors including 404 if cache not found
218
            ServerError: For server errors (5xx status codes)
219
        """
220
        ...
221

222
class AsyncCaches:
223
    """Asynchronous cached content management API."""
224

225
    async def delete(self, *, name: str) -> None:
226
        """Async version of delete."""
227
        ...
228
```
229

230
### List Cached Contents
231

232
List all cached content resources with optional pagination.
233

234
```python { .api }
235
class Caches:
236
    """Synchronous cached content management API."""
237

238
    def list(
239
        self,
240
        *,
241
        config: Optional[ListCachedContentsConfig] = None
242
    ) -> Union[Pager[CachedContent], Iterator[CachedContent]]:
243
        """
244
        List cached contents.
245

246
        Parameters:
247
            config (ListCachedContentsConfig, optional): List configuration including:
248
                - page_size: Number of items per page
249
                - page_token: Token for pagination
250

251
        Returns:
252
            Union[Pager[CachedContent], Iterator[CachedContent]]: Paginated cache list.
253

254
        Raises:
255
            ClientError: For client errors (4xx status codes)
256
            ServerError: For server errors (5xx status codes)
257
        """
258
        ...
259

260
class AsyncCaches:
261
    """Asynchronous cached content management API."""
262

263
    async def list(
264
        self,
265
        *,
266
        config: Optional[ListCachedContentsConfig] = None
267
    ) -> Union[AsyncPager[CachedContent], AsyncIterator[CachedContent]]:
268
        """Async version of list."""
269
        ...
270
```
271

272
**Usage Example:**
273

274
```python
275
from google.genai import Client
276

277
client = Client(api_key='YOUR_API_KEY')
278

279
# List all caches
280
for cache in client.caches.list():
281
    print(f"{cache.display_name}: {cache.name}")
282
    print(f"  Expires: {cache.expire_time}")
283
    print(f"  Tokens: {cache.usage_metadata.total_token_count}")
284
```
285

286
## Types
287

288
```python { .api }
289
from typing import Optional, Union, List, Iterator, AsyncIterator
290
from datetime import datetime
291
from enum import Enum
292

293
# Configuration types
294
class CreateCachedContentConfig:
295
    """
296
    Configuration for creating cached content.
297

298
    Attributes:
299
        contents (list[Content]): Content to cache (documents, examples, etc.).
300
        system_instruction (Union[str, Content], optional): System instruction to cache.
301
        tools (list[Tool], optional): Tool definitions to cache.
302
        tool_config (ToolConfig, optional): Tool configuration to cache.
303
        ttl (str, optional): Time-to-live duration (e.g., '3600s', '1h'). Either ttl
304
            or expire_time must be provided.
305
        expire_time (datetime, optional): Absolute expiration time. Either ttl or
306
            expire_time must be provided.
307
        display_name (str, optional): Display name for the cache.
308
    """
309
    contents: list[Content]
310
    system_instruction: Optional[Union[str, Content]] = None
311
    tools: Optional[list[Tool]] = None
312
    tool_config: Optional[ToolConfig] = None
313
    ttl: Optional[str] = None
314
    expire_time: Optional[datetime] = None
315
    display_name: Optional[str] = None
316

317
class UpdateCachedContentConfig:
318
    """
319
    Configuration for updating cached content.
320

321
    Attributes:
322
        ttl (str, optional): New time-to-live duration. Either ttl or expire_time
323
            must be provided.
324
        expire_time (datetime, optional): New absolute expiration time.
325
    """
326
    ttl: Optional[str] = None
327
    expire_time: Optional[datetime] = None
328

329
class ListCachedContentsConfig:
330
    """
331
    Configuration for listing cached contents.
332

333
    Attributes:
334
        page_size (int, optional): Number of items per page.
335
        page_token (str, optional): Token for pagination.
336
    """
337
    page_size: Optional[int] = None
338
    page_token: Optional[str] = None
339

340
# Response types
341
class CachedContent:
342
    """
343
    Cached content resource.
344

345
    Attributes:
346
        name (str): Resource name in format 'cachedContents/{cache_id}'.
347
        model (str): Model identifier this cache is for.
348
        display_name (str, optional): Display name.
349
        contents (list[Content]): Cached content.
350
        system_instruction (Content, optional): Cached system instruction.
351
        tools (list[Tool], optional): Cached tools.
352
        tool_config (ToolConfig, optional): Cached tool config.
353
        create_time (datetime): When cache was created.
354
        update_time (datetime): When cache was last updated.
355
        expire_time (datetime): When cache will expire.
356
        usage_metadata (CachedContentUsageMetadata): Token usage information.
357
    """
358
    name: str
359
    model: str
360
    display_name: Optional[str] = None
361
    contents: list[Content]
362
    system_instruction: Optional[Content] = None
363
    tools: Optional[list[Tool]] = None
364
    tool_config: Optional[ToolConfig] = None
365
    create_time: datetime
366
    update_time: datetime
367
    expire_time: datetime
368
    usage_metadata: CachedContentUsageMetadata
369

370
class CachedContentUsageMetadata:
371
    """
372
    Token usage metadata for cached content.
373

374
    Attributes:
375
        total_token_count (int): Total tokens in cached content.
376
    """
377
    total_token_count: int
378

379
# Core types (from content-generation)
380
class Content:
381
    """Content container with role and parts."""
382
    parts: list[Part]
383
    role: Optional[str] = None
384

385
class Part:
386
    """Individual content part."""
387
    text: Optional[str] = None
388
    inline_data: Optional[Blob] = None
389
    file_data: Optional[FileData] = None
390

391
class Blob:
392
    """Binary data with MIME type."""
393
    mime_type: str
394
    data: bytes
395

396
class FileData:
397
    """Reference to uploaded file."""
398
    file_uri: str
399
    mime_type: str
400

401
class Tool:
402
    """Tool with function declarations."""
403
    function_declarations: Optional[list[FunctionDeclaration]] = None
404

405
class FunctionDeclaration:
406
    """Function definition."""
407
    name: str
408
    description: str
409
    parameters: Optional[Schema] = None
410

411
class ToolConfig:
412
    """Tool configuration."""
413
    function_calling_config: Optional[FunctionCallingConfig] = None
414

415
class FunctionCallingConfig:
416
    """Function calling mode configuration."""
417
    mode: FunctionCallingConfigMode
418
    allowed_function_names: Optional[list[str]] = None
419

420
class FunctionCallingConfigMode(Enum):
421
    """Function calling modes."""
422
    MODE_UNSPECIFIED = 'MODE_UNSPECIFIED'
423
    AUTO = 'AUTO'
424
    ANY = 'ANY'
425
    NONE = 'NONE'
426

427
class Schema:
428
    """JSON schema."""
429
    type: Type
430
    properties: Optional[dict[str, Schema]] = None
431

432
class Type(Enum):
433
    """JSON schema types."""
434
    TYPE_UNSPECIFIED = 'TYPE_UNSPECIFIED'
435
    STRING = 'STRING'
436
    NUMBER = 'NUMBER'
437
    INTEGER = 'INTEGER'
438
    BOOLEAN = 'BOOLEAN'
439
    ARRAY = 'ARRAY'
440
    OBJECT = 'OBJECT'
441

442
# Pager types
443
class Pager[T]:
444
    """Synchronous pager."""
445
    page: list[T]
446
    def next_page(self) -> None: ...
447
    def __iter__(self) -> Iterator[T]: ...
448

449
class AsyncPager[T]:
450
    """Asynchronous pager."""
451
    page: list[T]
452
    async def next_page(self) -> None: ...
453
    async def __aiter__(self) -> AsyncIterator[T]: ...
454
```
455