### Install and Initialize Gemini API Client

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/README.md

Install the SDK and initialize the client with your API key. Ensure you have the latest version of the SDK installed.

```python
# Install the SDK
# pip install -q -U "google-genai>=1.0.0"

from google import genai
from google.genai import types

# Initialize client
client = genai.Client(api_key="YOUR_API_KEY")
```

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

### Conceptual MCP Tool Use Example

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/README.md

Demonstrates how to integrate an MCP server with the Gemini SDK for automatic tool-use handshake. Requires prior setup for MCP server connection.

```python
# Conceptual example of using an MCP server
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# ... setup for MCP server connection ...
async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        response = await client.aio.models.generate_content(
            model="gemini-2.0-flash",
            contents="What is the weather in London?",
            config=genai.types.GenerateContentConfig(
                tools=[session]  # Pass the MCP session as a tool
            )
        )
        print(response.text)
```

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

### Use Few-Shot Examples for Classification

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/README.md

Provide examples of input-output pairs to guide the model's classification task. This helps the model understand the desired format and criteria.

```python
prompt = """
Classify the sentiment as positive, negative, or neutral:

Example 1:
Text: "This product exceeded all my expectations!"
Sentiment: positive

Example 2:
Text: "The service was okay, nothing special."
Sentiment: neutral

Example 3:  
Text: "I'm extremely disappointed with this purchase."
Sentiment: negative

Now classify:
Text: "The quality is decent for the price."
Sentiment:"""
```

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

### MCP Integration Example

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/tools.md

Connect to an MCP server using ClientSession and StdioServerParameters to enable integrated tool access for content generation.

```python
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def example():
    server_params = StdioServerParameters(
        command="path/to/mcp/server"
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            response = await client.aio.models.generate_content(
                model="gemini-2.0-flash",
                contents="What is the weather in London?",
                config=genai.types.GenerateContentConfig(
                    tools=[session]
                )
            )
            print(response.text)
```

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

### Simple Content Generation

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/README.md

Basic example of generating content using a specified model and prompt. Prints the text response.

```python
response = client.models.generate_content(
    model="gemini-2.5-flash-preview-05-20",
    contents="Your prompt here"
)
print(response.text)
```

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

### Implement Role-Based Prompting

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/README.md

Use `system_instruction` to define the model's persona, expertise, and communication style. This guides the model to respond as a specific expert, providing tailored explanations and examples.

```python
config = types.GenerateContentConfig(
    system_instruction='''You are an experienced data scientist with expertise in machine learning.
    You explain complex concepts in simple terms and always provide practical examples.''''
)

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="Explain gradient descent",
    config=config
)
```

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

### Generate Content Example

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/README.md

A basic example of generating content using the Gemini API client. This code is production-ready and uses the current Gemini API (2025 version).

```python
# This is executable code
response = client.models.generate_content(...)
```

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

### Install Google Generative AI Library

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/README.md

Install the Google Generative AI library using pip. Ensure you are using a recent version for the latest features and fixes.

```bash
pip install -q -U "google-genai>=1.0.0"
```

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

### Example: Grounding Metadata

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/types.md

Shows how to generate content with search tools and access the grounding metadata from the response, printing search queries and source URIs/titles.

```python
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="Latest news about AI",
    config=types.GenerateContentConfig(
        tools=[types.Tool(google_search=types.GoogleSearch())]
    )
)

if response.candidates[0].grounding_metadata:
    metadata = response.candidates[0].grounding_metadata
    print(f"Queries: {metadata.web_search_queries}")
    for chunk in metadata.grounding_chunks:
        print(f"Source: {chunk.web.uri}")
        print(f"Title: {chunk.web.title}")
```

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

### Guide Step-by-Step Reasoning

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/README.md

For complex problems, explicitly ask the model to solve it step by step and show its work. This encourages detailed reasoning and reduces errors.

```python
# Complex problems benefit from explicit steps
prompt = """
Solve this problem step by step:

A store offers a 20% discount on all items. If you buy 3 items
priced at $50, $30, and $70, and there's an additional 10% off
for purchases over $100, what's the final price?

Step 1: Calculate the original total
Step 2: Apply the 20% discount
Step 3: Check if eligible for additional discount
Step 4: Calculate final price

Show your work for each step."""
```

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

### Generate Content with Specific Tool Configuration

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/generate-content.md

Example showing how to configure tool usage for content generation, specifically setting the function calling mode to 'ANY' and allowing only the 'get_weather' function.

```python
config = types.GenerateContentConfig(
    tools=[tools],
    tool_config=types.ToolConfig(
        function_calling_config=types.FunctionCallingConfig(
            mode="ANY",
            allowed_function_names=["get_weather"]
        )
    )
)
```

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

### Example: Embedding Content

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/types.md

Demonstrates how to embed content using the client and iterate through the resulting embeddings to print their dimensions and initial vector values.

```python
result = client.models.embed_content(
    model="gemini-embedding-exp-03-07",
    contents=["Text 1", "Text 2"]
)

for emb in result.embeddings:
    print(f"Dimension: {len(emb.values)}")  # 768
    print(f"Vector: {emb.values[:5]}...")  # First 5 values
```

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

### Function Calling with Tools

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/README.md

Example of configuring the model to call external functions by defining tools and their parameters.

```python
tools = genai.types.Tool(
    function_declarations=[
        {
            "name": "get_weather",
            "description": "Get weather for location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            }
        }
    ]
)

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="What's the weather in Tokyo?",
    config=genai.types.GenerateContentConfig(tools=[tools])
)

if response.candidates[0].content.parts[0].function_call:
    fc = response.candidates[0].content.parts[0].function_call
    print(f"Model wants to call: {fc.name}({fc.args})")
```

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

### Set System Instructions for Behavior

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/README.md

Define behavior guidelines for the model using system instructions. This example sets the model to act as a weather assistant that cannot access real-time data.

```python
# Set behavior guidelines
response = client.models.generate_content(
    model="gemini-2.5-flash-preview-05-20",
    contents="What's the weather like?",
    config=types.GenerateContentConfig(
        system_instruction="You are a helpful weather assistant. Always mention that you cannot access real-time data."
    )
)
```

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

### Creating and Interacting with a Chat

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/README.md

Example of initiating a multi-turn conversation and sending sequential messages.

```python
chat = client.chats.create(
    model="gemini-2.5-flash-preview-05-20"
)

response1 = chat.send_message("First message")
response2 = chat.send_message("Follow-up message")
```

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

### Get Model Information

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/types.md

Retrieve and display input/output token limits and default temperature for a specific model.

```python
model = client.models.get("gemini-2.5-flash-preview-05-20")
print(f"Input: {model.input_token_limit:,} tokens")
print(f"Output: {model.output_token_limit:,} tokens")
print(f"Temperature: {model.temperature}")
```

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

### Parallel Function Calling

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/tools.md

Demonstrates how the model can invoke multiple functions concurrently in a single response. This example defines two functions, 'turn_on_lights' and 'set_temperature', and shows how to handle their calls.

```python
functions = [
    {
        "name": "turn_on_lights",
        "description": "Turn lights on/off",
        "parameters": {
            "type": "object",
            "properties": {
                "on": {"type": "boolean"}
            },
            "required": ["on"]
        }
    },
    {
        "name": "set_temperature",
        "description": "Set room temperature",
        "parameters": {
            "type": "object",
            "properties": {
                "celsius": {"type": "number"}
            },
            "required": ["celsius"]
        }
    }
]

tools = types.Tool(function_declarations=functions)
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="Turn on the lights and set temperature to 22 degrees",
    config=types.GenerateContentConfig(tools=[tools])
)

# Handle multiple function calls
for part in response.candidates[0].content.parts:
    if part.function_call:
        print(f"{part.function_call.name}({part.function_call.args})")
```

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

### Media in Multi-Turn Chat Sessions

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/media.md

Seamlessly integrate media, such as images, into multi-turn chat conversations. This example shows sending an image, asking a question, and then following up with another image for comparison.

```python
chat = client.chats.create(
    model="gemini-2.5-flash-preview-05-20"
)

# First turn with image
image_file = client.files.upload(file="photo.jpg")
response = chat.send_message([
    image_file,
    "What's in this image?"
])

# Follow-up without image
response = chat.send_message("Tell me more about the background")

# Another image
image_file2 = client.files.upload(file="photo2.jpg")
response = chat.send_message([
    image_file2,
    "Compare this image to the first one"
])
```

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

### Generate Content with Thinking Enabled

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/generate-content.md

Example demonstrating how to generate content with thinking capabilities enabled, including printing both the reasoning and the final answer. This requires specifying the model and content, and configuring ThinkingConfig within GenerateContentConfig.

```python
response = client.models.generate_content(
    model="gemini-2.5-flash-preview-05-20",
    contents="Solve: If 5 machines make 5 widgets in 5 minutes, how many widgets do 100 machines make in 100 minutes?",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(
            include_thoughts=True,
            thinking_budget=1024
        )
    )
)

for part in response.candidates[0].content.parts:
    if part.thought:
        print("Reasoning:", part.text)
    elif part.text:
        print("Answer:", part.text)
```

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

### Configure System Instruction for Generate Content

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/configuration.md

Set a system instruction to guide the model's behavior for a single content generation request. This ensures consistent responses for specific tasks.

```python
config = types.GenerateContentConfig(
    system_instruction="You are a helpful Python programming tutor. Explain concepts clearly with examples."
)

response = client.models.generate_content(
    model="gemini-2.5-flash-preview-05-20",
    contents="What is a decorator in Python?",
    config=config
)
```

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

### Compare Multiple Images

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/media.md

Upload multiple image files and generate content to compare them, for example, to identify changes between images. Ensure all image files are accessible.

```python
image1 = client.files.upload(file="before.jpg")
image2 = client.files.upload(file="after.jpg")

response = client.models.generate_content(
    model="gemini-2.5-flash-preview-05-20",
    contents=[
        "What changed between these images?",
        image1,
        image2
    ]
)
```

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

### Get file metadata, list files, and delete a file

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/README.md

Demonstrates how to retrieve information about an uploaded file, list all files in storage, and remove a file. Requires a previously uploaded file object.

```python
# Get file metadata
file_info = client.files.get(name=myfile.name)
print(f"Size: {file_info.size_bytes}")
print(f"MIME: {file_info.mime_type}")
print(f"State: {file_info.state}")

# List all files
for f in client.files.list():
    print(f" - {f.name} ({f.display_name})")

# Delete file
client.files.delete(name=myfile.name)

```

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

### Create a New Chat Session

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/client.md

Use this method to initiate a new conversation with a specified model. You can optionally provide configuration, such as system instructions, to guide the AI's behavior.

```python
chat = client.chats.create(
    model="gemini-2.5-flash-preview-05-20",
    config=types.GenerateContentConfig(
        system_instruction="You are a helpful coding assistant"
    )
)

response = chat.send_message("What is a Python decorator?")
print(response.text)
```

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

### Configure Thinking Parameters

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/configuration.md

Set `include_thoughts` to True to get thought summaries in the response. Use `thinking_budget` to control the maximum tokens for thinking, especially for Flash models. Set to 0 to disable thinking.

```python
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(
        include_thoughts=True,
        thinking_budget=2048
    )
)
```

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

### Provide Clear and Specific Instructions

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/README.md

Vague prompts lead to generic responses. Be specific about the task, desired length, and topic.

```python
# ❌ Vague
"Tell me about dogs"

# ✅ Specific
"Write a 200-word educational summary about Golden Retrievers, covering their temperament, care needs, and suitability as family pets"
```

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

### Gemini Client Initialization Options

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/configuration.md

Demonstrates the required parameters for initializing the Gemini Client. The api_key is mandatory unless the GOOGLE_API_KEY environment variable is set.

```python
client = genai.Client(
    api_key: str  # Required
)
```

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

### Upload and Print File Details

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/types.md

Demonstrates how to upload a file and then print its key details such as name, size, state, and expiration time. Ensure you have a client instance configured.

```python
file = client.files.upload(file="document.pdf", display_name="My PDF")
print(f"Name: {file.name}")
print(f"Size: {file.size_bytes} bytes")
print(f"State: {file.state}")
print(f"Expires: {file.expiration_time}")
```

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

### get

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/client.md

Retrieves metadata and capabilities for a specific model.

```APIDOC
## client.models.get

### Description
Retrieves metadata and capabilities for a specific model.

### Method Signature
```python
client.models.get(model: str) -> types.Model
```

### Parameters
#### Path Parameters
* **model** (str) - Required - Model identifier

#### Query Parameters
* None

#### Request Body
* None

### Request Example
```python
model_info = client.models.get(model="gemini-2.5-flash-preview-05-20")
print(f"Input limit: {model_info.input_token_limit:,} tokens")
print(f"Output limit: {model_info.output_token_limit:,} tokens")
```

### Response
#### Success Response
* **input_token_limit** (int) - The maximum number of input tokens the model can accept.
* **output_token_limit** (int) - The maximum number of output tokens the model can generate.
* Other model metadata attributes.

#### Response Example
```json
{
  "input_token_limit": 32768,
  "output_token_limit": 8192,
  "name": "gemini-2.5-flash-preview-05-20",
  "version": "001",
  "display_name": "Gemini 2.5 Flash Preview",
  "description": "A fast and efficient model for a wide range of tasks.",
  "capabilities": [
    "SMART_REPLY",
    "SMART_FEEDBACK"
  ],
  "temperature_range": {
    "min": 0.0,
    "max": 1.0
  },
  "top_p_range": {
    "min": 0.0,
    "max": 1.0
  },
  "top_k_range": {
    "min": 1,
    "max": 40
  }
}
```
```

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

### Create Part Objects

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/types.md

Demonstrates creating different types of Part objects, including text, image from bytes, and file references. Shows how to combine these parts for a content generation request.

```python
# Text part
part1 = types.Part(text="Hello")

# Image from bytes
part2 = types.Part.from_bytes(
    data=image_bytes,
    mime_type="image/jpeg"
)

# File reference
part3 = types.Part(
    file_data=types.FileData(
        mime_type="application/pdf",
        file_uri="files/...name"
    )
)

# Combine
response = client.models.generate_content(
    model="gemini-2.5-flash-preview-05-20",
    contents=[part1, part2, part3]
)
```

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

### Get File Info

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/media.md

Retrieve information about a specific uploaded file.

```APIDOC
## GET /files/{name}

### Description
Retrieve information about a specific uploaded file.

### Method
GET

### Endpoint
/files/{name}

### Parameters
#### Path Parameters
- **name** (str) - Required - Unique file identifier

### Response
#### Success Response (200)
- **name** (str) - Unique file identifier
- **display_name** (str) - User-provided display name
- **mime_type** (str) - MIME type
- **size_bytes** (int) - File size
- **state** (str) - File state ("ACTIVE", "PROCESSING", "FAILED")
- **create_time** (datetime) - Upload timestamp
- **update_time** (datetime) - Last modification time

### Request Example
```python
file_info = client.files.get(name="file-abcdef12345")
```

### Response Example
```json
{
  "name": "file-abcdef12345",
  "display_name": "My Document",
  "mime_type": "application/pdf",
  "size_bytes": 102400,
  "state": "ACTIVE",
  "create_time": "2023-10-27T10:00:00Z",
  "update_time": "2023-10-27T10:01:00Z"
}
```
```

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

### List All Files

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/media.md

Iterate through and print the display name, MIME type, and size of all uploaded files in the project.

```python
for f in client.files.list():
    print(f"{f.display_name} ({f.mime_type}): {f.size_bytes} bytes")
```

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

### Generating Embeddings

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/README.md

Example of generating content embeddings for a list of texts and printing the dimension of the embeddings.

```python
result = client.models.embed_content(
    model="gemini-embedding-exp-03-07",
    contents=["Text 1", "Text 2"]
)

for embedding in result.embeddings:
    print(f"Dimension: {len(embedding.values)}")
```

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

### Basic Function Calling with Gemini API

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/README.md

Demonstrates the step-by-step process of defining a function, configuring tools, sending a request to the model, checking for a function call, executing the function, and sending the result back for a natural language response. Use this for single function calls.

```python
# Step 1: Define function declaration
get_weather_declaration = {
    "name": "get_weather",
    "description": "Get current weather for a location",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "City and state, e.g., 'San Francisco, CA'"
            },
            "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"],
                "description": "Temperature unit"
            }
        },
        "required": ["location"]
    }
}

# Step 2: Configure tools
tools = types.Tool(function_declarations=[get_weather_declaration])
config = types.GenerateContentConfig(tools=[tools])

# Step 3: Send request
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="What's the weather in Tokyo?",
    config=config
)

# Step 4: Check for function call
if response.candidates[0].content.parts[0].function_call:
    function_call = response.candidates[0].content.parts[0].function_call
    print(f"Function: {function_call.name}")
    print(f"Arguments: {function_call.args}")
    
    # Step 5: Execute function (your code)
    weather_result = {"temperature": 22, "condition": "sunny"}
    
    # Step 6: Send the function's result back to the model, along with the 
    # original prompt and the model's function call request. This gives the
    # model the full conversational context to generate a final, natural language response.
    function_response = types.Part.from_function_response(
        name=function_call.name,
        response={"result": weather_result}
    )
    
    final_response = client.models.generate_content(
        model="gemini-2.5-flash-preview-05-20", # Using a more current model
        contents=[
            types.Content(role="user", parts=[types.Part(text="What's the weather in Tokyo?")]), # Original prompt
            types.Content(role="model", parts=[types.Part(function_call=function_call)]),     # Model's function call
            types.Content(role="user", parts=[function_response])                             # Your function's result
        ]
        # Note: Do not include `tools` config in this final call unless you
        # want the model to be able to call another function.
    )
    print(final_response.text)
```

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

### Get Model Metadata with Client

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/client.md

Retrieves metadata and capabilities for a specific model, such as token limits. Use this to understand model constraints.

```python
model_info = client.models.get(model="gemini-2.5-flash-preview-05-20")
print(f"Input limit: {model_info.input_token_limit:,} tokens")
print(f"Output limit: {model_info.output_token_limit:,} tokens")
```

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

### Client Initialization, Content Generation, File Management, Caching

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/README.md

This section details the client initialization process, how to generate content, manage files, and utilize caching mechanisms within the Gemini API.

```APIDOC
## Client API

### Description
Provides functionalities for initializing the client, generating content, managing files, and implementing caching strategies.

### Method
N/A (SDK Reference)

### Endpoint
N/A (SDK Reference)

### Parameters
N/A (SDK Reference)

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

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

response = client.models.generate_content(
    model="gemini-2.5-flash-preview-05-20",
    contents="What is artificial intelligence?"
)

print(response.text)
```

### Response
#### Success Response
Details on the structure of successful responses from content generation and file management operations.

#### Response Example
```json
{
  "example": "response body"
}
```
```

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

### Configure Basic Tools

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/configuration.md

Define a list of tools for the model to use, including custom function declarations, Google Search, and code execution.

```python
config = types.GenerateContentConfig(
    tools=[
        types.Tool(function_declarations=[my_function_def]),
        types.Tool(google_search=types.GoogleSearch()),
        types.Tool(code_execution=types.ToolCodeExecution())
    ]
)
```

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

### Set Stop Sequences for Generation

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/configuration.md

Configures stop sequences to halt generation when specific strings are encountered. This example shows multiple stop sequences.

```python
config = types.GenerateContentConfig(
    stop_sequences=["END", "---", "\n\n"]
)
```

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

### Generate Content Asynchronously

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/client.md

Demonstrates how to generate content using the asynchronous client. Ensure the `client.aio` module is imported and available.

```python
async def example():
    response = await client.aio.models.generate_content(
        model="gemini-2.5-flash-preview-05-20",
        contents="Your prompt here"
    )
    return response
```

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

### Basic Content Generation

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/generate-content.md

Demonstrates a basic content generation request with a specified model and prompt. Sets a temperature and maximum output tokens for the response.

```python
response = client.models.generate_content(
    model="gemini-2.5-flash-preview-05-20",
    contents="Your prompt here",
    config=types.GenerateContentConfig(
        temperature=0.7,
        max_output_tokens=1024
    )
)
```

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

### Example Versioned Model Identifiers

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/models.md

Use versioned model identifiers for consistency, caching, and reliability. The specific version is recommended for explicit cache creation.

```python
model="models/gemini-2.0-flash-001"  # Specific version
vs
model="gemini-2.0-flash"  # Latest version (may change)
```

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

### Configure Generation Parameters

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/configuration.md

Sets up generation configuration using types.GenerateContentConfig, including parameters like temperature, top_p, top_k, max_output_tokens, stop_sequences, response_modalities, and response_mime_type.

```python
config = types.GenerateContentConfig(
    temperature=0.7,
    top_p=0.95,
    top_k=40,
    max_output_tokens=8192,
    stop_sequences=["END"],
    response_modalities=["TEXT"],
    response_mime_type="text/plain"
)

response = client.models.generate_content(
    model="gemini-2.5-flash-preview-05-20",
    contents="Your prompt",
    config=config
)
```

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

### Retrieve Chat Conversation History

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/client.md

Get the entire history of the current chat session. The history is returned as a list of content objects, each with a role and parts.

```python
for message in chat.get_history():
    print(f"{message.role}: {message.parts[0].text}")
```

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

### Send a Message in a Chat

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/client.md

Send a text message or a list of content parts to the chat session and get a single response. This is suitable for standard turn-based interactions.

```python
response = chat.send_message("Can you show me an example?")
print(response.text)
```

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

### Embed Content with Text Embedding 004 (Default)

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/embeddings.md

This example demonstrates using the `text-embedding-004` model with its default settings for generating embeddings. The default output dimension is 768.

```APIDOC
## Embed Content with Text Embedding 004 (Default)

### Description
Use the `text-embedding-004` model for generating embeddings. By default, this model outputs embeddings with a dimension of 768. Dimensionality reduction is supported if needed.

### Method
`client.models.embed_content`

### Parameters
- **model** (string) - Required - The model to use for embedding. Use `"text-embedding-004"`.
- **contents** (string) - Required - The text content to embed.

### Request Example
```python
result = client.models.embed_content(
    model="text-embedding-004",
    contents="Text to embed"
)
```

### Response
- **embeddings** (list) - A list of embedding objects.
  - **values** (list of floats) - The embedding vector values.

### Response Example
```json
{
  "embeddings": [
    {
      "values": [0.0123, -0.0456, ...]
    }
  ]
}
```
```

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

### Initialize Gemini Client with API Key

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/configuration.md

Initializes the Gemini client, automatically reading the GOOGLE_API_KEY environment variable. Alternatively, the api_key can be passed explicitly during client instantiation.

```python
from google import genai

# Client reads from environment automatically
client = genai.Client()

# Or pass explicitly
client = genai.Client(api_key="your-api-key")
```

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

### Configure Embedding with Output Dimensionality

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/configuration.md

Reduce the output dimensionality of embeddings for specific use cases. This example sets the output dimensionality to 256, a reduction from the default 768.

```python
config = types.EmbedContentConfig(
    output_dimensionality=256  # Default 768
)

result = client.models.embed_content(
    model="text-embedding-004",
    contents="Text to embed",
    config=config
)

# 256-dimensional vectors instead of 768
```

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

### Processing Uploaded Files

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/README.md

Shows how to upload a file and then use it as context for content generation.

```python
file = client.files.upload(file="document.pdf")

response = client.models.generate_content(
    model="gemini-2.5-flash-preview-05-20",
    contents=[file, "Summarize this document"]
)
```

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

### Get File Information

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/media.md

Retrieve information about a specific uploaded file using its name. This includes details like display name, MIME type, size, and state.

```python
file_info = client.files.get(name=myfile.name)
```

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

### Async API Configuration

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/configuration.md

Demonstrates how to use the same configuration options with asynchronous API calls. This allows for non-blocking operations in your application.

```python
async def example():
    response = await client.aio.models.generate_content(
        model="gemini-2.5-flash-preview-05-20",
        contents="Your prompt",
        config=types.GenerateContentConfig(
            temperature=0.7,
            max_output_tokens=2048
        )
    )
    return response
```

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

### Check Implicit Cache Usage

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/README.md

This snippet demonstrates how to check if implicit caching was used for a Gemini 2.5 model response. No setup is required as it's enabled by default.

```python
# Check implicit cache usage
response = client.models.generate_content(
    model="gemini-2.5-flash-preview-05-20",
    contents="Your content here"
)
print(f"Cached tokens: {response.usage_metadata.cached_content_token_count}")
```

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

### Object Detection with Bounding Boxes

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/media.md

Detect prominent items in an image and get their bounding box coordinates. The coordinates are normalized to a 0-1000 range and require denormalization to pixel values.

```python
prompt = """Detect all prominent items in the image.
The box_2d should be [ymin, xmin, ymax, xmax] normalized to 0-1000."""

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=[image_file, prompt]
)

# Convert normalized coordinates to pixels
def denormalize_bbox(bbox, img_width, img_height):
    ymin, xmin, ymax, xmax = bbox
    return [
        int(ymin * img_height / 1000),
        int(xmin * img_width / 1000),
        int(ymax * img_height / 1000),
        int(xmax * img_width / 1000)
    ]
```

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

### Basic Gemini API Content Generation

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/README.md

Initialize the Gemini API client and generate content using a specified model. Replace 'YOUR_API_KEY' with your actual API key.

```python
from google import genai

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

response = client.models.generate_content(
    model="gemini-2.5-flash-preview-05-20",
    contents="What is artificial intelligence?"
)

print(response.text)
```

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

### Generate Content with Gemini 2.5 Flash Preview (Adaptive Thinking)

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/models.md

This snippet demonstrates using Gemini 2.5 Flash Preview with adaptive thinking, allowing the model to manage its thinking budget automatically.

```python
# Adaptive thinking (let model decide budget)
response = client.models.generate_content(
    model="gemini-2.5-flash-preview-05-20",
    contents="Solve this puzzle..."  # Model uses thinking as needed
)
```

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

### Embed Content with Gemini Embedding Experimental

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/embeddings.md

This example shows how to use the recommended `gemini-embedding-exp-03-07` model for generating embeddings. This model provides the latest and most accurate embeddings with an output dimension of 768.

```APIDOC
## Embed Content with Gemini Embedding Experimental

### Description
Use the `gemini-embedding-exp-03-07` model for the latest and most accurate embeddings. This model is recommended for general use and offers a fixed output dimension of 768.

### Method
`client.models.embed_content`

### Parameters
- **model** (string) - Required - The model to use for embedding. Use `"gemini-embedding-exp-03-07"`.
- **contents** (string) - Required - The text content to embed.

### Request Example
```python
result = client.models.embed_content(
    model="gemini-embedding-exp-03-07",
    contents="Text to embed"
)
```

### Response
- **embeddings** (list) - A list of embedding objects.
  - **values** (list of floats) - The embedding vector values.

### Response Example
```json
{
  "embeddings": [
    {
      "values": [0.0123, -0.0456, ...]
    }
  ]
}
```
```

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

### Upload a file and use it in generation

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/README.md

Uploads an image file and then uses it as part of a content prompt for generation. Ensure the file path is correct.

```python
# Upload a file
myfile = client.files.upload(file="path/to/image.jpg")
print(f"Uploaded: {myfile.name}")

# Use in generation
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=[myfile, "Describe this image"])

```

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

### Initialize Gemini API Client

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/client.md

Initialize the Gemini API client with your API key. This client provides access to all Gemini API functionalities.

```python
from google import genai

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

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

### Debugging Structured Output: Manual Schema Validation

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/structured-output.md

This example demonstrates how to manually validate a structured output response against a Pydantic model. It includes error handling for invalid JSON and validation errors.

```python
import json

response = client.models.generate_content(
    model="gemini-2.5-flash-preview-05-20",
    contents="Your prompt",
    config={
        "response_mime_type": "application/json",
        "response_schema": YourModel,
    }
)

try:
    # Parse JSON string
    data = json.loads(response.text)
    
    # Validate with Pydantic
    validated = YourModel(**data)
    print("Validation passed")
except json.JSONDecodeError:
    print("Invalid JSON response")
except Exception as e:
    print(f"Validation error: {e}")
```

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

### Using Cached Content

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/README.md

Demonstrates creating a cache for content and then referencing it in a subsequent generation request.

```python
cache = client.caches.create(
    model="models/gemini-2.0-flash-001",
    config=genai.types.CreateCachedContentConfig(
        contents=[large_file],
        ttl="3600s"
    )
)

response = client.models.generate_content(
    model="models/gemini-2.0-flash-001",
    contents="Your prompt",
    config=genai.types.GenerateContentConfig(
        cached_content=cache.name
    )
)
```

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

### Define Property Ordering in Pydantic Model

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/structured-output.md

Use `json_schema_extra` with `propertyOrdering` to enforce a specific order for model properties in the generated JSON schema. This is useful for consistent output, especially with few-shot examples.

```python
class OrderedModel(BaseModel):
    model_config = {"json_schema_extra": {
        "propertyOrdering": ["id", "name", "description", "price", "in_stock"]
    }}
    
    id: int
    name: str
    description: str
    price: float
    in_stock: bool
```

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

### Accessing Top-Level Client Methods

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/README.md

Demonstrates how to access different modules of the genai.Client instance for various API functionalities.

```python
client.models        # Content generation, embeddings, model info
client.chats         # Multi-turn conversations
client.files         # File upload and management
client.caches        # Context caching
client.aio           # Async APIs
```

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

### Combine Multiple Tools in a Single Request

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/tools.md

Use this snippet to send a prompt that leverages multiple tools simultaneously, such as searching for information and then analyzing it. Ensure the 'client' object is initialized and 'my_function' is defined.

```python
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="Search for recent AI developments and analyze the data",
    config=types.GenerateContentConfig(
        tools=[
            types.Tool(function_declarations=[my_function]),
            types.Tool(google_search=types.GoogleSearch()),
            types.Tool(code_execution=types.ToolCodeExecution())
        ]
    )
)
```

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

### Upload Audio File for Transcription and Summarization

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/media.md

Upload an audio file (e.g., MP3) and use it to generate content, such as a transcription and summary, from a specified model.

```python
audio_file = client.files.upload(file="podcast.mp3")

response = client.models.generate_content(
    model="gemini-2.5-flash-preview-05-20",
    contents=[
        audio_file,
        "Transcribe and summarize the key points"
    ]
)

print(response.text)
```

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

### Embed Content with Dimensionality Reduction

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/embeddings.md

This example demonstrates how to reduce embedding dimensions for the `text-embedding-004` model to improve efficiency. You can choose from various output dimensionalities based on your use case, balancing accuracy with speed and storage.

```APIDOC
## Embed Content with Dimensionality Reduction

### Description
Reduce embedding dimensions for efficiency using the `text-embedding-004` model. This allows for faster comparisons and reduced storage, especially for large-scale similarity searches or memory-constrained environments.

### Method
`client.models.embed_content`

### Parameters
- **model** (string) - Required - The model to use for embedding. Use `"text-embedding-004"` for dimensionality reduction.
- **contents** (string) - Required - The text content to embed.
- **config** (object) - Optional - Configuration for embedding.
  - **output_dimensionality** (integer) - Optional - The desired output dimension for the embeddings. Defaults to 768. Can be 768, 512, 256, or 128.

### Request Example
```python
result = client.models.embed_content(
    model="text-embedding-004",
    contents="Your text here",
    config=types.EmbedContentConfig(
        output_dimensionality=256  # Example: Reduce to 256 dimensions
    )
)

embedding = result.embeddings[0]
print(f"Dimension: {len(embedding.values)}")
```

### Response
- **embeddings** (list) - A list of embedding objects.
  - **values** (list of floats) - The embedding vector values.

### Response Example
```json
{
  "embeddings": [
    {
      "values": [0.0123, -0.0456, ...]
    }
  ]
}
```

### Trade-offs for Dimensionality Reduction:
| Dimension | Use Case | Trade-off |
|-----------|----------|-----------|
| 768 (full) | Highest accuracy | More storage, slower comparisons |
| 512 | Balanced | Good accuracy with some efficiency |
| 256 | Efficient | Reduced accuracy, much faster |
| 128 | Very efficient | Significant accuracy loss, very fast |
```

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

### Declaration-Based Function Calling

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/tools.md

Demonstrates how to define a function using a JSON schema for the model to call. It includes setting up the tool and configuration, then generating content with a prompt that triggers the function call.

```python
get_weather_declaration = {
    "name": "get_weather",
    "description": "Get current weather for a location",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "City and state, e.g., 'San Francisco, CA'"
            },
            "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"],
                "description": "Temperature unit"
            }
        },
        "required": ["location"]
    }
}

tools = types.Tool(function_declarations=[get_weather_declaration])
config = types.GenerateContentConfig(tools=[tools])

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="What's the weather in Tokyo?",
    config=config
)
```

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

### Generate Content with Gemini Client

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/client.md

Use the initialized client to generate content from a specified model. Ensure you have the correct model name and content to send.

```python
from google import genai

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

# Access models
response = client.models.generate_content(
    model="gemini-2.5-flash-preview-05-20",
    contents="Hello, Gemini!"
)
print(response.text)
```

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

### Handling Tool/Function Execution Errors

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/errors.md

Wrap tool execution in a try-except block to catch exceptions during function calls or invalid return types. This example demonstrates catching errors during the `execute_function` call and general generation errors.

```Python
try:
    response = client.models.generate_content(
        model="gemini-2.0-flash",
        contents="Call my function",
        config=types.GenerateContentConfig(
            tools=[my_tools]
        )
    )
    
    if response.candidates[0].content.parts[0].function_call:
        fc = response.candidates[0].content.parts[0].function_call
        try:
            result = execute_function(fc.name, fc.args)
        except Exception as e:
            print(f"Function execution failed: {e}")
            # Handle gracefully, re-prompt model
            
except Exception as e:
    print(f"Generation error: {e}")
```

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

### Client Initialization

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/client.md

Initializes the Gemini API client with your Google API key. This client object is then used to access various Gemini API functionalities.

```APIDOC
## Client Initialization

### Constructor

```python
from google import genai

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

**Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| api_key | str | Yes | — | Google API key for authentication. Obtain from Google Cloud Console. |

**Return Type:**
`genai.Client` instance with access to all API modules.

**Example:**
```python
from google import genai

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

# Access models
response = client.models.generate_content(
    model="gemini-2.5-flash-preview-05-20",
    contents="Hello, Gemini!"
)
print(response.text)
```
```

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

### Extract Contact Information with JSON Response

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/structured-output.md

This example demonstrates extracting multiple structured entities like contact information from a document. It utilizes `response_mime_type` for JSON output and a Pydantic model to define the expected structure of the extracted data.

```python
from typing import List

class ContactInfo(BaseModel):
    name: str
    email: str
    phone: str

class ExtractionResult(BaseModel):
    contacts: List[ContactInfo]
    document_type: str

response = client.models.generate_content(
    model="gemini-2.5-flash-preview-05-20",
    contents="Extract all contact information from this document: [document text]",
    config={
        "response_mime_type": "application/json",
        "response_schema": ExtractionResult,
    }
)

result = response.parsed
for contact in result.contacts:
    print(f"{contact.name}: {contact.email}")
```

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

### Get segmentation masks for objects in an image

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/README.md

Requests segmentation masks for specified items in an image, outputting results as a JSON list containing bounding boxes, base64-encoded PNG masks, and labels. Requires setting the response MIME type to application/json.

```python
# Get segmentation masks
prompt = """Give the segmentation masks for the wooden and glass items.
Output a JSON list where each entry contains:
- "box_2d": bounding box
- "mask": base64 encoded PNG mask
- "label": descriptive label"""

response = client.models.generate_content(
    model="gemini-2.5-flash-preview-05-20",
    contents=[image_file, prompt],
    config={
        "response_mime_type": "application/json"
    })

```

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

### Async Model Generation

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/README.md

Demonstrates how to asynchronously generate content using the Gemini API. Ensure the client module supports async operations via `client.aio`.

```python
async def example():
    response = await client.aio.models.generate_content(
        model="gemini-2.5-flash-preview-05-20",
        contents="Your prompt"
    )
    return response
```

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

### Create Cached Content Configuration

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/generate-content.md

Defines the parameters for creating a cache for content. Includes display name, system instruction, the content itself, and its time-to-live.

```python
types.CreateCachedContentConfig(
    display_name: Optional[str] = None,
    system_instruction: Optional[str] = None,
    contents: List[Union[str, types.Part]],
    ttl: Optional[str] = None
)
```

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

### Upload and Analyze Image from File

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/media.md

Upload an image file and then generate content describing its contents. Ensure the image file is accessible.

```python
image_file = client.files.upload(file="photo.jpg")

response = client.models.generate_content(
    model="gemini-2.5-flash-preview-05-20",
    contents=[image_file, "What's in this image?"]
)

print(response.text)
```

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

### Creating Media Parts Inline for API Requests

Source: https://github.com/dicklesworthstone/gemini-api-updater-doc/blob/main/_autodocs/api-reference/media.md

Demonstrates how to create media parts directly within your code for API requests. This includes creating parts from raw bytes, plain text, and uploaded files.

```python
# From bytes
image_bytes = b"..."
image_part = types.Part.from_bytes(
    data=image_bytes,
    mime_type="image/jpeg"
)

# From text/JSON
text_part = types.Part(text="Your text content")

# From file
file_part = client.files.upload(file="document.pdf")

# Combine in request
response = client.models.generate_content(
    model="gemini-2.5-flash-preview-05-20",
    contents=[image_part, text_part, file_part]
)
```