Types

Learn how to use Pydantic models and dictionaries for type-safe API calls

Overview

The Google Gen AI SDK supports both Pydantic models and dictionaries for specifying parameters. This flexibility allows you to choose between type-safe Pydantic models or simple Python dictionaries based on your preferences.

Importing Types

All types are available in the types module:

from google.genai import types

Using Pydantic Models vs Dictionaries

The SDK accepts both Pydantic model instances and plain dictionaries for most parameters.

Using Pydantic Models

Pydantic models provide type safety and validation:

from google.genai import types

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents=types.Part.from_text(text='Why is the sky blue?'),
    config=types.GenerateContentConfig(
        temperature=0,
        top_p=0.95,
        top_k=20,
    ),
)

Using Dictionaries

Dictionaries provide a more concise syntax:

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents={'text': 'Why is the sky blue?'},
    config={
        'temperature': 0,
        'top_p': 0.95,
        'top_k': 20,
    },
)

Both approaches produce the same result. The SDK automatically converts dictionaries to the appropriate Pydantic models internally.

Common Types

Part

Represents a single piece of content (text, image, file, function call, etc.):

from google.genai import types

# Text part
text_part = types.Part.from_text(text='Hello, world!')

# Image from URI
image_part = types.Part.from_uri(
    file_uri='gs://bucket/image.jpg',
    mime_type='image/jpeg'
)

# Image from bytes
with open('image.jpg', 'rb') as f:
    image_bytes = f.read()
image_part = types.Part.from_bytes(
    data=image_bytes,
    mime_type='image/jpeg'
)

# Function call
function_part = types.Part.from_function_call(
    name='get_weather',
    args={'location': 'Boston'}
)

# Function response
response_part = types.Part.from_function_response(
    name='get_weather',
    response={'result': 'sunny'}
)

Content

Represents a message with a role and multiple parts:

from google.genai import types

# User content
user_content = types.Content(
    role='user',
    parts=[types.Part.from_text(text='What is the weather?')]
)

# Model content
model_content = types.Content(
    role='model',
    parts=[types.Part.from_text(text='The weather is sunny.')]
)

GenerateContentConfig

Configuration for content generation:

from google.genai import types

config = types.GenerateContentConfig(
    temperature=0.9,
    top_p=0.95,
    top_k=40,
    max_output_tokens=1024,
    system_instruction='You are a helpful assistant.',
    safety_settings=[
        types.SafetySetting(
            category='HARM_CATEGORY_HATE_SPEECH',
            threshold='BLOCK_ONLY_HIGH'
        )
    ]
)

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='Tell me a story',
    config=config
)

HttpOptions

Customize HTTP behavior for requests:

from google.genai import types

http_options = types.HttpOptions(
    api_version='v1',
    timeout=60000,  # milliseconds
    headers={'Custom-Header': 'value'},
    retry_options=types.HttpRetryOptions(
        attempts=5,
        initial_delay=1.0,
        max_delay=60.0,
        exp_base=2.0,
        jitter=1.0
    )
)

client = genai.Client(
    api_key='GEMINI_API_KEY',
    http_options=http_options
)

TypedDict Variants

For each Pydantic model, there’s a corresponding TypedDict variant with a Dict suffix:

• types.Content → types.ContentDict
• types.Part → types.PartDict
• types.GenerateContentConfig → types.GenerateContentConfigDict
• types.HttpOptions → types.HttpOptionsDict

These TypedDict variants are useful for type hints when using dictionaries:

from google.genai import types

def create_config() -> types.GenerateContentConfigDict:
    return {
        'temperature': 0.9,
        'top_p': 0.95,
        'max_output_tokens': 1024
    }

Schema Types

JSONSchema

Define response schemas using JSON Schema format:

from google.genai import types

user_schema = {
    'type': 'object',
    'properties': {
        'username': {
            'type': 'string',
            'description': "User's unique name"
        },
        'age': {
            'type': 'integer',
            'minimum': 0,
            'maximum': 120
        }
    },
    'required': ['username', 'age']
}

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='Generate a random user profile',
    config=types.GenerateContentConfig(
        response_mime_type='application/json',
        response_json_schema=user_schema
    )
)

Pydantic Model Schema

Use Pydantic models directly for schema definition:

from pydantic import BaseModel
from google.genai import types

class CountryInfo(BaseModel):
    name: str
    population: int
    capital: str
    continent: str
    gdp: int
    official_language: str
    total_area_sq_mi: int

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='Give me information for the United States',
    config=types.GenerateContentConfig(
        response_mime_type='application/json',
        response_json_schema=CountryInfo.model_json_schema()
    )
)

Enum Types

The SDK provides numerous enum types for various settings:

HarmCategory

from google.genai import types

safety_settings = [
    types.SafetySetting(
        category='HARM_CATEGORY_HARASSMENT',
        threshold='BLOCK_MEDIUM_AND_ABOVE'
    ),
    types.SafetySetting(
        category='HARM_CATEGORY_HATE_SPEECH',
        threshold='BLOCK_ONLY_HIGH'
    )
]

FunctionCallingConfigMode

from google.genai import types

config = types.GenerateContentConfig(
    tools=[my_function],
    tool_config=types.ToolConfig(
        function_calling_config=types.FunctionCallingConfig(
            mode='ANY'  # or 'AUTO', 'NONE', 'VALIDATED'
        )
    )
)

FinishReason

The response includes a finish reason enum:

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='Hello'
)

finish_reason = response.candidates[0].finish_reason
# Possible values: 'STOP', 'MAX_TOKENS', 'SAFETY', 'RECITATION', etc.

File and Blob Types

FileData

References files stored in Google Cloud Storage:

from google.genai import types

file_data = types.FileData(
    file_uri='gs://bucket/document.pdf',
    mime_type='application/pdf'
)

part = types.Part(file_data=file_data)

Blob

Contains inline binary data:

from google.genai import types

with open('image.jpg', 'rb') as f:
    image_bytes = f.read()

blob = types.Blob(
    data=image_bytes,
    mime_type='image/jpeg'
)

part = types.Part(inline_data=blob)

Function Calling Types

FunctionDeclaration

Manually declare functions for the model to call:

from google.genai import types

function_declaration = types.FunctionDeclaration(
    name='get_weather',
    description='Get the current weather for a location',
    parameters_json_schema={
        'type': 'object',
        'properties': {
            'location': {
                'type': 'string',
                'description': 'The city and state, e.g. San Francisco, CA'
            }
        },
        'required': ['location']
    }
)

tool = types.Tool(function_declarations=[function_declaration])

FunctionCall and FunctionResponse

from google.genai import types

# Function call from model
function_call = types.FunctionCall(
    name='get_weather',
    args={'location': 'Boston'}
)

# Your function response
function_response = types.FunctionResponse(
    name='get_weather',
    response={'result': 'sunny'}
)

Cache Types

CreateCachedContentConfig

from google.genai import types

cache_config = types.CreateCachedContentConfig(
    contents=[
        types.Content(
            role='user',
            parts=[types.Part.from_uri(
                file_uri='gs://bucket/large-document.pdf',
                mime_type='application/pdf'
            )]
        )
    ],
    system_instruction='Summarize the document',
    ttl='3600s',
    display_name='document-cache'
)

cached_content = client.caches.create(
    model='gemini-2.5-flash',
    config=cache_config
)

Best Practices

Use Pydantic models for:

• Large, complex configurations
• When you want IDE autocomplete and type checking
• When building reusable configuration objects

Use dictionaries for:

• Quick prototyping and experimentation
• Simple, one-off configurations
• When you prefer a more concise syntax

When using dictionaries, ensure that key names exactly match the Pydantic field names (usually in snake_case). Typos will not be caught until runtime.