Google Gen AI Python SDK

https://googleapis.github.io/python-genai
Admin
The Google Gen AI Python SDK provides an interface for developers to integrate Google’s generative...
Tokens:34,672
Snippets:345
Trust Score:8.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install the SDK

Source: https://googleapis.github.io/python-genai

Install the package using pip or uv.

```bash
pip install google-genai
```

```bash
uv pip install google-genai
```

--------------------------------

### Install google-genai with uv

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Use this command to install the SDK using uv.

```shell
uv pip install google-genai
```

--------------------------------

### Install google-genai with pip

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Use this command to install the SDK using pip.

```shell
pip install google-genai
```

--------------------------------

### Configure Function Calling with ANY Mode

Source: https://googleapis.github.io/python-genai

Examples for controlling automatic function calling behavior when the mode is set to ANY.

```python
from google.genai import types

def get_current_weather(location: str) -> str:
    """Returns the current weather.

    Args:
        location: The city and state, e.g. San Francisco, CA
    """
    return "sunny"

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="What is the weather like in Boston?",
    config=types.GenerateContentConfig(
        tools=[get_current_weather],
        automatic_function_calling=types.AutomaticFunctionCallingConfig(
            disable=True
        ),
        tool_config=types.ToolConfig(
            function_calling_config=types.FunctionCallingConfig(mode='ANY')
        ),
    ),
)
```

```python
from google.genai import types

def get_current_weather(location: str) -> str:
    """Returns the current weather.

    Args:
        location: The city and state, e.g. San Francisco, CA
    """
    return "sunny"

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="What is the weather like in Boston?",
    config=types.GenerateContentConfig(
        tools=[get_current_weather],
        automatic_function_calling=types.AutomaticFunctionCallingConfig(
            maximum_remote_calls=2
        ),
        tool_config=types.ToolConfig(
            function_calling_config=types.FunctionCallingConfig(mode='ANY')
        ),
    ),
)
```

--------------------------------

### Define Batch Request File

Source: https://googleapis.github.io/python-genai

Example JSON structure for batch request files.

```json
{"key":"request_1", "request": {"contents": [{"parts": [{"text":
 "Explain how AI works in a few words"}]}], "generation_config": {"response_modalities": ["TEXT"]}}}
{"key":"request_2", "request": {"contents": [{"parts": [{"text": "Explain how Crypto works in a few words"}]}]}}
```

--------------------------------

### Configure Safety Settings

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Control model safety by providing `safety_settings` in the `GenerateContentConfig`. This example blocks only high-severity hate speech.

```python
from google.genai import types

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='Say something bad.',
    config=types.GenerateContentConfig(
        safety_settings=[
            types.SafetySetting(
                category='HARM_CATEGORY_HATE_SPEECH',
                threshold='BLOCK_ONLY_HIGH',
            )
        ]
    ),
)
print(response.text)
```

--------------------------------

### Batch Prediction Request JSON Example

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Example JSON structure for batch prediction requests, defining a request with a specific key and content.

```json
{"key":"request_1", "request": {"contents": [{"parts": [{"text":
     "Explain how AI works in a few words"}]}], "generation_config": {"response_modalities": ["TEXT"]}}}
{"key":"request_2", "request": {"contents": [{"parts": [{"text": "Explain how Crypto works in a few words"}]}]}}
```

--------------------------------

### Start Model Tuning Job

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Initiates a supervised fine-tuning job for a base model using a specified training dataset and configuration. This is only supported in Vertex AI.

```python
from google.genai import types

tuning_job = client.tunings.tune(
    base_model=model,
    training_dataset=training_dataset,
    config=types.CreateTuningJobConfig(
        epoch_count=1, tuned_model_display_name='test_dataset_examples model'
    ),
)
print(tuning_job)
```

--------------------------------

### Typed Configuration for Model Generation

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Utilize Pydantic types from `google.genai.types` for API parameters, offering type safety over dictionaries. This example shows setting various generation parameters including temperature, top_p, top_k, and stop sequences.

```python
from google.genai import types

response = client.models.generate_content(
    model='gemini-2.0-flash-001',
    contents=types.Part.from_text(text='Why is the sky blue?'),
    config=types.GenerateContentConfig(
        temperature=0,
        top_p=0.95,
        top_k=20,
        candidate_count=1,
        seed=5,
        max_output_tokens=100,
        stop_sequences=['STOP!'],
        presence_penalty=0.0,
        frequency_penalty=0.0,
    ),
)

print(response.text)
```

--------------------------------

### Invoke a Function and Get Response

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

This snippet demonstrates how to invoke a tool function based on a model's generated function call and then pass the function's response back to the model for a final answer. Ensure the `get_current_weather` function is defined and accessible.

```python
from google.genai import types

# Assume client and tool are already initialized
# Assume get_current_weather function is defined elsewhere

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='What is the weather like in Boston?',
    config=types.GenerateContentConfig(
        tools=[tool],
    ),
)

user_prompt_content = types.Content(
    role='user',
    parts=[types.Part.from_text(text='What is the weather like in Boston?')],
)
function_call_part = response.function_calls[0]
function_call_content = response.candidates[0].content


try:
    function_result = get_current_weather(
        **function_call_part.function_call.args
    )
    function_response = {'result': function_result}
except (
    Exception
) as e:  # instead of raising the exception, you can let the model handle it
    function_response = {'error': str(e)}


function_response_part = types.Part.from_function_response(
    name=function_call_part.name,
    response=function_response,
)
function_response_content = types.Content(
    role='tool', parts=[function_response_part]
)

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents=[
        user_prompt_content,
        function_call_content,
        function_response_content,
    ],
    config=types.GenerateContentConfig(
        tools=[tool],
    ),
)

print(response.text)
```

--------------------------------

### Create client using environment variables

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Create a client that automatically picks up configuration from environment variables.

```python
from google import genai

client = genai.Client()
```

--------------------------------

### Initialize the client

Source: https://googleapis.github.io/python-genai

Create a client instance for either the Gemini Developer API or Vertex AI.

```python
from google import genai

# Only run this block for Gemini Developer API
client = genai.Client(api_key='GEMINI_API_KEY')
```

```python
from google import genai

# Only run this block for Vertex AI API
client = genai.Client(
    vertexai=True, project='your-project-id', location='us-central1'
)
```

```python
from google import genai

client = genai.Client()
```

--------------------------------

### Get and Monitor Tuning Job

Source: https://googleapis.github.io/python-genai

Retrieves a tuning job status and polls until completion.

```python
tuning_job = client.tunings.get(name=tuning_job.name)
print(tuning_job)
```

```python
import time

completed_states = set(
    [
        'JOB_STATE_SUCCEEDED',
        'JOB_STATE_FAILED',
        'JOB_STATE_CANCELLED',
    ]
)

while tuning_job.state not in completed_states:
    print(tuning_job.state)
    tuning_job = client.tunings.get(name=tuning_job.name)
    time.sleep(10)
```

--------------------------------

### Integrate External Tools with Stdio Client

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Demonstrates using the `stdio_client` to integrate external tools, enabling automatic function calling. Requires setting up server parameters and initializing the client session.

```python
import asyncio
from datetime import datetime
from google.generativeai.client import genai
from google.generativeai.types import StdioServerParameters, ClientSession, stdio_client


server_params = StdioServerParameters(
    command="npx",  # Executable
    args=["-y", "@philschmid/weather-mcp"],  # MCP Server
    env=None,  # Optional environment variables
)

async def run():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Prompt to get the weather for the current day in London.
            prompt = f"What is the weather in London in {datetime.now().strftime('%Y-%m-%d')}?"

            # Initialize the connection between client and server
            await session.initialize()

            # Send request to the model with MCP function declarations
            response = await client.aio.models.generate_content(
                model="gemini-2.5-flash",
                contents=prompt,
                config=genai.types.GenerateContentConfig(
                    temperature=0,
                    tools=[session],  # uses the session, will automatically call the tool using automatic function calling
                ),
            )
            print(response.text)

# Start the asyncio event loop and run the main function
asyncio.run(run())
```

--------------------------------

### Generate Content with Configuration

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Demonstrates how to generate content using the `generate_content` method with various configuration options like `max_output_tokens` and `temperature` to influence the model's response.

```APIDOC
## Generate Content with Configuration

### Description
This example shows how to use the `generate_content` method with a `GenerateContentConfig` object to control aspects of the model's output, such as system instructions, maximum output tokens, and response randomness.

### Method
`client.models.generate_content`

### Parameters
#### Request Body
- **model** (string) - Required - The model to use for generation.
- **contents** (string or Part) - Required - The input prompt for the model.
- **config** (GenerateContentConfig) - Optional - Configuration for content generation.
  - **system_instruction** (string) - Optional - An instruction for the model to follow.
  - **max_output_tokens** (integer) - Optional - The maximum number of tokens to generate.
  - **temperature** (float) - Optional - Controls randomness; lower values make output more deterministic.

### Request Example
```python
from google.genai import types

response = client.models.generate_content(
    model='gemini-2.0-flash-001',
    contents='high',
    config=types.GenerateContentConfig(
        system_instruction='I say high, you say low',
        max_output_tokens=3,
        temperature=0.3,
    ),
)
print(response.text)
```
```

--------------------------------

### Configuring Async Client Arguments

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Demonstrates how to pass additional arguments to the aiohttp client session for faster async performance.

```APIDOC
## Configuring Async Client Arguments

### Description
Demonstrates how to pass additional arguments to the aiohttp client session for faster async performance.

### Method
```python
http_options = types.HttpOptions(
    async_client_args={'cookies': ..., 'ssl': ...},
)

client=Client(..., http_options=http_options)
```
```

--------------------------------

### Get Batch Prediction Job

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Retrieves the status and details of a specific batch prediction job by its name.

```APIDOC
## Get Batch Prediction Job

### Description
Retrieves the status and details of a specific batch prediction job.

### Method
GET

### Endpoint
/v1beta/batches/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the batch job to retrieve.
```

--------------------------------

### Use and Get Tuned Model

Source: https://googleapis.github.io/python-genai

Generates content using a tuned model endpoint or retrieves model details.

```python
response = client.models.generate_content(
    model=tuning_job.tuned_model.endpoint,
    contents='why is the sky blue?',
)

print(response.text)
```

```python
tuned_model = client.models.get(model=tuning_job.tuned_model.model)
print(tuned_model)
```

--------------------------------

### Client Initialization with Vertex AI

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Initializes a GenAI client for use with Vertex AI, specifying project, location, and API version.

```APIDOC
## Client Initialization with Vertex AI

### Description
Initializes a GenAI client for use with Vertex AI, specifying project, location, and API version.

### Method
```python
client = genai.Client(
    vertexai=True,
    project='your-project-id',
    location='us-central1',
    http_options=types.HttpOptions(api_version='v1')
)
```
```

--------------------------------

### Provide Contents as a list of types.Content

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Demonstrates the canonical way to provide input to the 'contents' argument by creating a list of types.Content instances.

```python
from google.genai import types

contents = types.Content(
    role='user',
```

--------------------------------

### Get Batch Job Status

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Retrieves the current state of a batch job by repeatedly fetching its status until it is completed.

```APIDOC
while job.state not in completed_states:
    print(job.state)
    job = client.batches.get(name=job.name)
    time.sleep(30)

job
```

--------------------------------

### Create Vertex AI client

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Create a client for the Vertex AI API. Specify your project ID and location.

```python
from google import genai

# Only run this block for Vertex AI API
client = genai.Client(
    vertexai=True, project='your-project-id', location='us-central1'
)
```

--------------------------------

### Configure environment variables

Source: https://googleapis.github.io/python-genai

Set environment variables for authentication and service configuration.

```bash
export GEMINI_API_KEY='your-api-key'
```

```bash
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT='your-project-id'
export GOOGLE_CLOUD_LOCATION='us-central1'
```

--------------------------------

### Get Tuned Model

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Retrieves details about a specific tuned model. This allows you to inspect the configuration and status of your fine-tuned models.

```APIDOC
## Get Tuned Model

### Description
Retrieves details about a specific tuned model.

### Method
GET

### Endpoint
/v1beta/models/{model}

### Parameters
#### Path Parameters
- **model** (string) - Required - The name or ID of the tuned model to retrieve.
```

--------------------------------

### Get a Tuned Model

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Retrieves a specific tuned model using its identifier. The 'tuning_job' object should contain the 'tuned_model.model' attribute.

```python
tuned_model = client.models.get(model=tuning_job.tuned_model.model)
print(tuned_model)
```

--------------------------------

### Client Initialization with Gemini Developer API Key

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Initializes a GenAI client for the Gemini Developer API using an API key and setting the API version to 'v1alpha'.

```APIDOC
## Client Initialization with Gemini Developer API Key

### Description
Initializes a GenAI client for the Gemini Developer API using an API key and setting the API version to 'v1alpha'.

### Method
```python
client = genai.Client(
    api_key='GEMINI_API_KEY',
    http_options=types.HttpOptions(api_version='v1alpha')
)
```
```

--------------------------------

### Get Batch Prediction Job by Name

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Retrieves a specific batch prediction job using its name and prints its current state.

```python
# Get a job by name
job = client.batches.get(name=job.name)

job.state
```

--------------------------------

### Paginate Through Tuning Jobs Asynchronously

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Demonstrates asynchronous pagination for tuning jobs, including accessing page size, the first item, and fetching the next page.

```python
async_pager = await client.aio.tunings.list(config={'page_size': 10})
print(async_pager.page_size)
print(async_pager[0])
await async_pager.next_page()
print(async_pager[0])
```

--------------------------------

### Use Tuned Model

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Generates content using a specified tuned model. This is useful for getting responses from a model that has been fine-tuned for a specific task.

```APIDOC
## Use Tuned Model

### Description
Generates content using a specified tuned model.

### Method
POST

### Endpoint
/v1beta/models/{model}:generateContent

### Parameters
#### Path Parameters
- **model** (string) - Required - The name of the tuned model to use.

#### Request Body
- **contents** (string) - Required - The prompt or content to send to the model.

### Request Example
```json
{
  "contents": "why is the sky blue?"
}
```

### Response
#### Success Response (200)
- **text** (string) - The generated text response from the model.
```

--------------------------------

### Get Cached Content

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Retrieves information about a previously created cached content using its name. This is useful for managing or verifying existing caches.

```python
cached_content = client.caches.get(name=cached_content.name)
```

--------------------------------

### Manage Files via gcloud

Source: https://googleapis.github.io/python-genai

Downloads sample PDF files from Google Cloud Storage using the gcloud CLI.

```bash
gcloud storage cp gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf .
gcloud storage cp gs://cloud-samples-data/generative-ai/pdf/2403.05530.pdf .
```

--------------------------------

### Create a Batch Job

Source: https://googleapis.github.io/python-genai

Initializes a batch job using a BigQuery table or GCS file as the source.

```python
# Specify model and source file only, destination and job display name will be auto-populated
job = client.batches.create(
    model='gemini-2.5-flash',
    src='bq://my-project.my-dataset.my-table',  # or "gs://path/to/input/data"
)

print(job)
```

--------------------------------

### Handle API Errors Python

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Catch and process errors from the model service using the `google.genai.errors.APIError` class. This example demonstrates how to access error codes and messages.

```python
from google.genai import errors

try:
    client.models.generate_content(
        model="invalid-model-name",
        contents="What is your name?",
    )
except errors.APIError as e:
    print(e.code) # 404
    print(e.message)
```

--------------------------------

### Video.show()

Source: https://googleapis.github.io/python-genai

Displays the video content.

```APIDOC
## Video.show()

### Description
Displays the video content within the current environment.

### Method
Instance Method
```

--------------------------------

### Get Tuning Job Status

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Retrieves the status and details of a model tuning job using its name. This is useful for monitoring the progress and outcome of the tuning process.

```python
tuning_job = client.tunings.get(name=tuning_job.name)
print(tuning_job)
```

--------------------------------

### Initialize Client with Custom Base URL and Headers

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Initializes the GenAI client with a custom base URL, useful for API gateway proxies, and includes custom headers for authentication.

```python
base_url = 'https://test-api-gateway-proxy.com'
client = Client(
    vertexai=True,  # Currently only vertexai=True is supported
    http_options={
        'base_url': base_url,
        'headers': {'Authorization': 'Bearer test_token'},
    },
)
```

--------------------------------

### Get File Information

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Uploads a file and then retrieves its information using the file's name. This is useful for verifying upload status or accessing file metadata.

```python
file1 = client.files.upload(file='2312.11805v3.pdf')
file_info = client.files.get(name=file1.name)
```

--------------------------------

### Select API version

Source: https://googleapis.github.io/python-genai

Configure the API version using http_options.

```python
from google import genai
from google.genai import types

client = genai.Client(
    vertexai=True,
    project='your-project-id',
    location='us-central1',
    http_options=types.HttpOptions(api_version='v1')
)
```

```python
from google import genai
from google.genai import types

# Only run this block for Gemini Developer API
client = genai.Client(
    api_key='GEMINI_API_KEY',
    http_options=types.HttpOptions(api_version='v1alpha')
)
```

--------------------------------

### Generate Content with JSON Schema

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Use `response_json_schema` to guide the model to generate JSON output conforming to a specified schema. Ensure the schema is correctly defined.

```python
user_profile = {
    'properties': {
        'age': {
            'anyOf': [
                {'maximum': 20, 'minimum': 0, 'type': 'integer'},
                {'type': 'null'},
            ],
            'title': 'Age',
        },
        'username': {
            'description': "User's unique name",
            'title': 'Username',
            'type': 'string',
        },
    },
    'required': ['username', 'age'],
    'title': 'User Schema',
    'type': 'object',
}

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='Give me a random user profile.',
    config={
        'response_mime_type': 'application/json',
        'response_json_schema': user_profile
    },
)
print(response.parsed)
```

--------------------------------

### Video.from_file()

Source: https://googleapis.github.io/python-genai

Creates a Video object from a local file.

```APIDOC
## Video.from_file()

### Description
Creates a Video instance by loading data from a specified file path.

### Method
Static Method

### Parameters
- **path** (str) - Required - The file path to the video file.
```

--------------------------------

### Setting Proxy Environment Variables

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Shows how to set environment variables for proxy configuration, including HTTPS proxy and SSL certificate file.

```APIDOC
## Setting Proxy Environment Variables

### Description
Shows how to set environment variables for proxy configuration, including HTTPS proxy and SSL certificate file.

### Method
```bash
export HTTPS_PROXY='http://username:password@proxy_uri:port'
export SSL_CERT_FILE='client.pem'
```
```

--------------------------------

### Import genai and types

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Import the necessary modules for using the SDK.

```python
from google import genai
from google.genai import types
```

--------------------------------

### Edit Image with Imagen

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Use this code to edit an existing image. Image editing requires a separate model and is supported in Vertex AI. You can provide reference images and masks to guide the editing process. Specify the model, prompt, reference images, and editing configuration.

```python
# Edit the generated image from above
from google.genai import types
from google.genai.types import RawReferenceImage, MaskReferenceImage

raw_ref_image = RawReferenceImage(
    reference_id=1,
    reference_image=response1.generated_images[0].image,
)

# Model computes a mask of the background
mask_ref_image = MaskReferenceImage(
    reference_id=2,
    config=types.MaskReferenceConfig(
        mask_mode='MASK_MODE_BACKGROUND',
        mask_dilation=0,
    ),
)

response3 = client.models.edit_image(
    model='imagen-3.0-capability-001',
    prompt='Sunlight and clear sky',
    reference_images=[raw_ref_image, mask_ref_image],
    config=types.EditImageConfig(
        edit_mode='EDIT_MODE_INPAINT_INSERTION',
        number_of_images=1,
        include_rai_reason=True,
        output_mime_type='image/jpeg',
    ),
)
response3.generated_images[0].image.show()
```

--------------------------------

### Upload File and Generate Content from File

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Uploads a local file and then generates content by summarizing the uploaded file using the 'gemini-2.5-flash' model.

```console
!wget -q https://storage.googleapis.com/generativeai-downloads/data/a11.txt
```

```python
file = client.files.upload(file='a11.txt')
response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents=['Could you summarize this file?', file]
)
print(response.text)
```

--------------------------------

### Provide Contents as a List of types.Content

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Demonstrates the canonical way to provide input to the `contents` argument using a list of `types.Content` objects.

```APIDOC
## Provide Contents as a List of types.Content

### Description
Demonstrates the canonical way to provide input to the `contents` argument using a list of `types.Content` objects.

### Method
```python
from google.genai import types

contents = types.Content(
    role='user',
```
```

--------------------------------

### Initialize Vertex AI Client with API Version v1

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Initializes the GenAI client for Vertex AI with a specific project, location, and API version set to 'v1'.

```python
from google import genai
from google.genai import types

client = genai.Client(
    vertexai=True,
    project='your-project-id',
    location='us-central1',
    http_options=types.HttpOptions(api_version='v1')
)
```

--------------------------------

### Integrate MCP Server as a Tool

Source: https://googleapis.github.io/python-genai

Experimental support for passing a local MCP server session as a tool for automatic function calling.

```python
import os
import asyncio
from datetime import datetime
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from google import genai

client = genai.Client()

# Create server parameters for stdio connection
server_params = StdioServerParameters(
    command="npx",  # Executable
    args=["-y", "@philschmid/weather-mcp"],  # MCP Server
    env=None,  # Optional environment variables
)

async def run():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Prompt to get the weather for the current day in London.
            prompt = f"What is the weather in London in {datetime.now().strftime('%Y-%m-%d')}?"

            # Initialize the connection between client and server
            await session.initialize()

            # Send request to the model with MCP function declarations
            response = await client.aio.models.generate_content(
                model="gemini-2.5-flash",
                contents=prompt,
                config=genai.types.GenerateContentConfig(
                    temperature=0,
                    tools=[session],  # uses the session, will automatically call the tool using automatic function calling
                ),
            )
            print(response.text)

# Start the asyncio event loop and run the main function
asyncio.run(run())
```

--------------------------------

### Generate Videos from Text with Veo

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

This snippet shows how to generate videos from a text prompt using the Veo model. The process involves creating an operation and then polling it until completion. Configuration options include number of videos, duration, and prompt enhancement.

```python
from google.genai import types

# Create operation
operation = client.models.generate_videos(
    model='veo-2.0-generate-001',
    prompt='A neon hologram of a cat driving at top speed',
    config=types.GenerateVideosConfig(
        number_of_videos=1,
        duration_seconds=5,
        enhance_prompt=True,
    ),
)

# Poll operation
while not operation.done:
    time.sleep(20)
    operation = client.operations.get(operation)

video = operation.response.generated_videos[0].video
video.show()
```

--------------------------------

### Generate Videos from Video with Veo

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

This snippet illustrates generating videos from an existing video input using the Veo model. Note that Video to Video generation is currently only supported in Vertex AI. The input video must be in Google Cloud Storage (GCS).

```python
from google.genai import types

# Read local video (uses mimetypes.guess_type to infer mime type)
video = types.Video.from_file("local/path/video.mp4")

# Create operation
operation = client.models.generate_videos(
    model='veo-2.0-generate-001',
    # Prompt is optional if Video is provided
    prompt='Night sky',
    # Input video must be in GCS
    video=types.Video(
        uri="gs://bucket-name/inputs/videos/cat_driving.mp4",
    ),
    config=types.GenerateVideosConfig(
        number_of_videos=1,
        duration_seconds=5,
        enhance_prompt=True,
    ),
)

# Poll operation
while not operation.done:
    time.sleep(20)
    operation = client.operations.get(operation)

video = operation.response.generated_videos[0].video
video.show()
```

--------------------------------

### Create Gemini Developer API client

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Create a client for the Gemini Developer API. Ensure you have your GEMINI_API_KEY set.

```python
from google import genai

# Only run this block for Gemini Developer API
client = genai.Client(api_key='GEMINI_API_KEY')
```

--------------------------------

### Create Cached Content

Source: https://googleapis.github.io/python-genai

Initializes cached content with specified files and system instructions.

```python
from google.genai import types

if client.vertexai:
    file_uris = [
        'gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf',
        'gs://cloud-samples-data/generative-ai/pdf/2403.05530.pdf',
    ]
else:
    file_uris = [file1.uri, file2.uri]

cached_content = client.caches.create(
    model='gemini-2.5-flash',
    config=types.CreateCachedContentConfig(
        contents=[
            types.Content(
                role='user',
                parts=[
                    types.Part.from_uri(
                        file_uri=file_uris[0], mime_type='application/pdf'
                    ),
                    types.Part.from_uri(
                        file_uri=file_uris[1],
                        mime_type='application/pdf',
                    ),
                ],
            )
        ],
        system_instruction='What is the sum of the two pdfs?',
        display_name='test cache',
        ttl='3600s',
    ),
)
```

--------------------------------

### Paginate Through Tuned Models Asynchronously

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Demonstrates asynchronous pagination for tuned models, including accessing page size, the first item, and fetching the next page.

```python
async_pager = await client.aio.models.list(config={'page_size': 10, 'query_base': False})
print(async_pager.page_size)
print(async_pager[0])
await async_pager.next_page()
print(async_pager[0])
```

--------------------------------

### Initialize Gemini Developer API Client with API Version v1alpha

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Initializes the GenAI client for the Gemini Developer API with an API key and sets the API version to 'v1alpha'.

```python
from google import genai
from google.genai import types

# Only run this block for Gemini Developer API
client = genai.Client(
    api_key='GEMINI_API_KEY',
    http_options=types.HttpOptions(api_version='v1alpha')
)
```

--------------------------------

### Set Vertex AI environment variables

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Set environment variables for using the Gemini API on Vertex AI.

```bash
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT='your-project-id'
export GOOGLE_CLOUD_LOCATION='us-central1'
```

--------------------------------

### Generate Content (Async)

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Perform content generation asynchronously using `client.aio.models.generate_content`. This is the async equivalent of the synchronous method.

```python
response = await client.aio.models.generate_content(
    model='gemini-2.5-flash', contents='Tell me a story in 300 words.'
)

print(response.text)
```

--------------------------------

### Generate Content Stream (Async)

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Handle asynchronous streaming of content generation. Use `async for` with `client.aio.models.generate_content_stream`.

```python
async for chunk in await client.aio.models.generate_content_stream(
    model='gemini-2.5-flash', contents='Tell me a story in 300 words.'
):
    print(chunk.text, end='')
```

--------------------------------

### Paginate Through Tuning Jobs

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Demonstrates using a pager object to access tuning jobs, including retrieving page size, accessing the first item, and fetching the next page.

```python
pager = client.tunings.list(config={'page_size': 10})
print(pager.page_size)
print(pager[0])
pager.next_page()
print(pager[0])
```

--------------------------------

### Provide a types.Content instance

Source: https://googleapis.github.io/python-genai

Explicitly define content using the types.Content class.

```python
from google.genai import types

contents = types.Content(
    role='user',
    parts=[types.Part.from_text(text='Why is the sky blue?')]
)
```

```python
[
    types.Content(
        role='user',
        parts=[types.Part.from_text(text='Why is the sky blue?')]
    )
]
```

--------------------------------

### Use sync client context manager

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Use the sync client within a 'with' statement to automatically close it upon exiting the block.

```python
from google.genai import Client

with Client() as client:
    response_1 = client.models.generate_content(
        model=MODEL_ID,
        contents='Hello',
    )
    response_2 = client.models.generate_content(
        model=MODEL_ID,
        contents='Ask a question',
    )
```

--------------------------------

### List Base Models

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Shows how to retrieve a list of available base models using the `client.models.list()` method, including options for pagination.

```APIDOC
## List Base Models

### Description
This section demonstrates how to list available base models using the `client.models.list()` method. It also shows how to use the `config` parameter for pagination, such as setting the `page_size`.

### Method
`client.models.list`

### Parameters
#### Query Parameters
- **config** (dict) - Optional - Configuration for listing models.
  - **page_size** (integer) - Optional - The number of models to return per page.

### Request Example (Synchronous)
```python
for model in client.models.list():
    print(model)

pager = client.models.list(config={'page_size': 10})
print(pager.page_size)
print(pager[0])
await pager.next_page() # Note: This example uses await, implying an async context for next_page
print(pager[0])
```

### Request Example (Asynchronous)
```python
# Asynchronous listing
async for job in await client.aio.models.list():
    print(job)

async_pager = await client.aio.models.list(config={'page_size': 10})
print(async_pager.page_size)
print(async_pager[0])
await async_pager.next_page()
print(async_pager[0])
```
```

--------------------------------

### Configuring SOCKS5 Proxy with httpx

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Configures a SOCKS5 proxy for both synchronous and asynchronous httpx clients.

```APIDOC
## Configuring SOCKS5 Proxy with httpx

### Description
Configures a SOCKS5 proxy for both synchronous and asynchronous httpx clients.

### Method
```python
http_options = types.HttpOptions(
    client_args={'proxy': 'socks5://user:pass@host:port'},
    async_client_args={'proxy': 'socks5://user:pass@host:port'},
)

client=Client(..., http_options=http_options)
```
```

--------------------------------

### Function Calling - Manual Declaration and Invocation

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Illustrates the manual process of declaring a function using `FunctionDeclaration` and passing it as a tool, allowing for explicit control over function invocation.

```APIDOC
## Function Calling - Manual Declaration and Invocation

### Description
This example shows how to manually declare a function using `types.FunctionDeclaration` and pass it as a tool. This approach gives you more control over how and when functions are called, as the response will contain function call parts that you can then process.

### Method
`client.models.generate_content`

### Parameters
#### Request Body
- **model** (string) - Required - The model to use for generation.
- **contents** (string) - Required - The input prompt for the model.
- **config** (types.GenerateContentConfig) - Optional - Configuration for content generation.
  - **tools** (list[types.FunctionDeclaration]) - Optional - A list of function declarations to be used as tools.

### Request Example
```python
from google.genai import types

function = types.FunctionDeclaration(
    name='get_current_weather',
    # ... other parameters for FunctionDeclaration ...
)

# The rest of the example would involve calling generate_content with this function declaration
# and then processing the response to manually invoke the function.
```
```

--------------------------------

### Function Calling - Automatic

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Demonstrates how to enable automatic Python function calling by passing a Python function directly as a tool in the `generate_content` configuration.

```APIDOC
## Function Calling - Automatic

### Description
This example shows how to enable automatic function calling by providing a Python function directly within the `tools` parameter of `GenerateContentConfig`. The model can then automatically invoke this function based on the user's prompt.

### Method
`client.models.generate_content`

### Parameters
#### Request Body
- **model** (string) - Required - The model to use for generation.
- **contents** (string) - Required - The input prompt for the model.
- **config** (types.GenerateContentConfig) - Optional - Configuration for content generation.
  - **tools** (list[function]) - Optional - A list of Python functions to be used as tools.

### Request Example
```python
from google.genai import types

def get_current_weather(location: str) -> str:
    """Returns the current weather.

    Args:
        location: The city and state, e.g. San Francisco, CA
    """
    return 'sunny'


response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='What is the weather like in Boston?',
    config=types.GenerateContentConfig(
        tools=[get_current_weather],
    ),
)

print(response.text)
```
```

--------------------------------

### Configure SOCKS5 Proxy for httpx Client

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Configures both synchronous and asynchronous clients to use a SOCKS5 proxy by passing proxy details within the client arguments.

```python
http_options = types.HttpOptions(
    client_args={'proxy': 'socks5://user:pass@host:port'},
    async_client_args={'proxy': 'socks5://user:pass@host:port'},
)

client=Client(..., http_options=http_options)
```

--------------------------------

### List All Available Models

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Iterate through all available models using `client.models.list()`. This provides a basic way to see what models are accessible.

```python
for model in client.models.list():
    print(model)
```

--------------------------------

### Generate Videos from Image with Veo

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Generate videos from an input image using the Veo model. This method allows you to provide a local image file as input. The prompt is optional when an image is provided. Configuration options are similar to text-to-video generation.

```python
from google.genai import types

# Read local image (uses mimetypes.guess_type to infer mime type)
image = types.Image.from_file(location="local/path/file.png")

# Create operation
operation = client.models.generate_videos(
    model='veo-2.0-generate-001',
    # Prompt is optional if image is provided
    prompt='Night sky',
    image=image,
    config=types.GenerateVideosConfig(
        number_of_videos=1,
        duration_seconds=5,
        enhance_prompt=True,
        # Can also pass an Image into last_frame for frame interpolation
    ),
)

# Poll operation
while not operation.done:
    time.sleep(20)
    operation = client.operations.get(operation)

video = operation.response.generated_videos[0].video
video.show()
```

--------------------------------

### Import SDK modules

Source: https://googleapis.github.io/python-genai

Required imports for using the client and type definitions.

```python
from google import genai
from google.genai import types
```

--------------------------------

### Use client context managers

Source: https://googleapis.github.io/python-genai

Use context managers to automatically close clients when exiting the block.

```python
from google.genai import Client

with Client() as client:
    response_1 = client.models.generate_content(
        model=MODEL_ID,
        contents='Hello',
    )
    response_2 = client.models.generate_content(
        model=MODEL_ID,
        contents='Ask a question',
    )
```

```python
from google.genai import Client

async with Client().aio as aclient:
    response_1 = await aclient.models.generate_content(
        model=MODEL_ID,
        contents='Hello',
    )
    response_2 = await aclient.models.generate_content(
        model=MODEL_ID,
        contents='Ask a question',
    )
```

--------------------------------

### client.tunings.list

Source: https://googleapis.github.io/python-genai

Lists tuning jobs associated with the client.

```APIDOC
## client.tunings.list

### Description
Lists tuning jobs associated with the client.

### Parameters
- **config** (dict) - Optional - Configuration for pagination, such as 'page_size'.
```

--------------------------------

### Upload File and Generate Content

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Uploads a local file and then uses it as input for content generation.

```APIDOC
## Upload File and Generate Content

### Description
Uploads a local file and then uses it as input for content generation.

### Method
```console
!wget -q https://storage.googleapis.com/generativeai-downloads/data/a11.txt
```

### Method
```python
file = client.files.upload(file='a11.txt')
response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents=['Could you summarize this file?', file]
)
print(response.text)
```
```

--------------------------------

### Configure aiohttp options

Source: https://googleapis.github.io/python-genai

Pass additional arguments to aiohttp session requests.

```python
http_options = types.HttpOptions(
    async_client_args={'cookies': ..., 'ssl': ...},
)

client=Client(..., http_options=http_options)
```

--------------------------------

### Generate Content Stream (Image from Local File)

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Stream content generation for image-based prompts stored locally. Read the image as bytes and use `types.Part.from_bytes`.

```python
from google.genai import types

YOUR_IMAGE_PATH = 'your_image_path'
YOUR_IMAGE_MIME_TYPE = 'your_image_mime_type'
with open(YOUR_IMAGE_PATH, 'rb') as f:
    image_bytes = f.read()

for chunk in client.models.generate_content_stream(
    model='gemini-2.5-flash',
    contents=[
        'What is this image about?',
        types.Part.from_bytes(data=image_bytes, mime_type=YOUR_IMAGE_MIME_TYPE),
    ],
):
    print(chunk.text, end='')
```

--------------------------------

### Set Gemini Developer API key environment variable

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Set the GEMINI_API_KEY environment variable for automatic client configuration.

```bash
export GEMINI_API_KEY='your-api-key'
```

--------------------------------

### Generate video from image

Source: https://googleapis.github.io/python-genai

Uses a local image file as input for video generation. The prompt is optional when an image is provided.

```python
from google.genai import types

# Read local image (uses mimetypes.guess_type to infer mime type)
image = types.Image.from_file(location="local/path/file.png")

# Create operation
operation = client.models.generate_videos(
    model='veo-2.0-generate-001',
    # Prompt is optional if image is provided
    prompt='Night sky',
    image=image,
    config=types.GenerateVideosConfig(
        number_of_videos=1,
        duration_seconds=5,
        enhance_prompt=True,
        # Can also pass an Image into last_frame for frame interpolation
    ),
)

# Poll operation
while not operation.done:
    time.sleep(20)
    operation = client.operations.get(operation)

video = operation.response.generated_videos[0].video
video.show()
```

--------------------------------

### List Tuning Jobs

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Iterates through a paginated list of tuning jobs, setting the page size to 10.

```python
for job in client.tunings.list(config={'page_size': 10}):
    print(job)
```

--------------------------------

### client.models.list

Source: https://googleapis.github.io/python-genai

Lists tuned models available to the client.

```APIDOC
## client.models.list

### Description
Lists tuned models available to the client.

### Parameters
- **config** (dict) - Optional - Configuration for pagination and filtering, such as 'page_size' and 'query_base'.
```

--------------------------------

### client.batches.list

Source: https://googleapis.github.io/python-genai

Lists batch jobs with support for pagination and asynchronous iteration.

```APIDOC
## client.batches.list

### Description
Retrieves a list of batch jobs. Supports configuration for page size and asynchronous access.

### Parameters
- **config** (ListBatchJobsConfig) - Optional - Configuration object including page_size.

### Example
```python
for job in client.batches.list(config=types.ListBatchJobsConfig(page_size=10)):
    print(job)
```
```

--------------------------------

### Paginate Model Listing

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Use `client.models.list(config={'page_size': 10})` to paginate through the list of models. This is useful for handling large numbers of models efficiently.

```python
pager = client.models.list(config={'page_size': 10})
print(pager.page_size)
print(pager[0])
pager.next_page()
print(pager[0])
```

--------------------------------

### Upscale Image with Imagen

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

This snippet demonstrates how to upscale a previously generated image. Note that image upscaling is only supported in Vertex AI. You need to provide the model name, the image object, the desired upscale factor, and configuration.

```python
from google.genai import types

# Upscale the generated image from above
response2 = client.models.upscale_image(
    model='imagen-3.0-generate-002',
    image=response1.generated_images[0].image,
    upscale_factor='x2',
    config=types.UpscaleImageConfig(
        include_rai_reason=True,
        output_mime_type='image/jpeg',
    ),
)
response2.generated_images[0].image.show()
```

--------------------------------

### Paginate Through Tuned Models

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Demonstrates using a pager object to access tuned models, including retrieving page size, accessing the first item, and fetching the next page.

```python
pager = client.models.list(config={'page_size': 10, 'query_base': False})
print(pager.page_size)
print(pager[0])
pager.next_page()
print(pager[0])
```

--------------------------------

### Apply Typed Configuration

Source: https://googleapis.github.io/python-genai

Utilize Pydantic types from google.genai.types to define detailed generation parameters like top_p, top_k, and stop sequences.

```python
from google.genai import types

response = client.models.generate_content(
    model='gemini-2.0-flash-001',
    contents=types.Part.from_text(text='Why is the sky blue?'),
    config=types.GenerateContentConfig(
        temperature=0,
        top_p=0.95,
        top_k=20,
        candidate_count=1,
        seed=5,
        max_output_tokens=100,
        stop_sequences=['STOP!'],
        presence_penalty=0.0,
        frequency_penalty=0.0,
    ),
)

print(response.text)
```

--------------------------------

### List Batch Jobs

Source: https://googleapis.github.io/python-genai

Lists batch jobs using the synchronous client.

```python
from google.genai import types

for job in client.batches.list(config=types.ListBatchJobsConfig(page_size=10)):
    print(job)
```

--------------------------------

### Provide a string

Source: https://googleapis.github.io/python-genai

Passing a string automatically wraps it in a types.UserContent object.

```python
contents='Why is the sky blue?'
```

```python
[
    types.UserContent(
        parts=[
            types.Part.from_text(text='Why is the sky blue?')
        ]
    )
]
```

--------------------------------

### List Base Models

Source: https://googleapis.github.io/python-genai

Retrieve a list of available base models or use pagination to manage large result sets.

```python
for model in client.models.list():
    print(model)
```

```python
pager = client.models.list(config={'page_size': 10})
print(pager.page_size)
print(pager[0])
pager.next_page()
print(pager[0])
```

--------------------------------

### Configure Model Generation Parameters

Source: https://googleapis.github.io/python-genai/_sources/index.rst.txt

Use the `config` parameter in `generate_content` to control model output. Adjust `max_output_tokens` for longer responses and `temperature` to influence randomness (lower values reduce variability).

```python
from google.genai import types

response = client.models.generate_content(
    model='gemini-2.0-flash-001',
    contents='high',
    config=types.GenerateContentConfig(
        system_instruction='I say high, you say low',
        max_output_tokens=3,
        temperature=0.3,
    ),
)
print(response.text)
```
Tokens:
Raw