Implementation:Googleapis Python genai Caches Create

Knowledge Sources	googleapis/python-genai Google Gen AI Python SDK
Domains	Optimization, Cost_Reduction
Last Updated	2026-02-15 00:00 GMT

Overview

Concrete tool for creating cached content for cost-efficient repeated generation provided by the google-genai caches module.

Description

Caches.create creates a cached content resource on the server. It accepts a model identifier and a CreateCachedContentConfig specifying the content to cache (documents, system instructions), TTL or expiry time, and display name. The method returns a CachedContent object with a resource name that can be referenced in subsequent generate_content calls via config.cached_content. The cache reduces latency and cost by avoiding re-processing of the cached context.

Usage

Call client.caches.create with the model and a config containing the content to cache. Set ttl (e.g., 3600s for 1 hour) or expire_time for expiration control. Store the returned CachedContent.name for use in generation calls.

Code Reference

Source Location

• Repository: googleapis/python-genai
• File: google/genai/caches.py
• Lines: L835-842

Signature

class Caches:
    def create(
        self,
        *,
        model: str,
        config: Optional[types.CreateCachedContentConfigOrDict] = None,
    ) -> types.CachedContent:
        """Creates a cached content resource.

        Args:
            model: Model to associate with the cache.
            config: Cache configuration (contents, TTL, display_name).
        """

Import

from google import genai
from google.genai import types

I/O Contract

Inputs

Name	Type	Required	Description
model	str	Yes	Model to associate with the cache
config.contents	Optional[ContentListUnion]	No	Content to cache (documents, system instructions)
config.ttl	Optional[str]	No	Time-to-live duration (e.g., '3600s')
config.expire_time	Optional[datetime]	No	Absolute expiry time
config.system_instruction	Optional[ContentUnion]	No	System instruction to cache
config.display_name	Optional[str]	No	Human-readable name for the cache

Outputs

Name	Type	Description
CachedContent	types.CachedContent	Cached content with .name resource identifier for generation calls

Usage Examples

Cache a Document

from google import genai
from google.genai import types

client = genai.Client(api_key="YOUR_API_KEY")

# Upload a document
doc = client.files.upload(file="large_manual.pdf")

# Create a cache with the document
cache = client.caches.create(
    model="gemini-1.5-flash-002",
    config=types.CreateCachedContentConfig(
        contents=[
            types.Content(
                parts=[types.Part.from_uri(file_uri=doc.uri, mime_type="application/pdf")],
                role="user"
            )
        ],
        ttl="3600s",  # Cache for 1 hour
        display_name="Product Manual Cache",
    ),
)

print(f"Cache name: {cache.name}")

Cache a System Instruction

cache = client.caches.create(
    model="gemini-1.5-flash-002",
    config=types.CreateCachedContentConfig(
        system_instruction="You are an expert on our product manual. Answer questions precisely based on the manual content.",
        contents=[
            types.Content(
                parts=[types.Part.from_uri(file_uri=doc.uri, mime_type="application/pdf")],
                role="user"
            )
        ],
        ttl="7200s",
    ),
)

Related Pages

Implements Principle

• Principle:Googleapis_Python_genai_Cache_Creation

Requires Environment

• Environment:Googleapis_Python_genai_Python_3_10_SDK_Runtime