> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-opensw-1782332329-96d87c7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ChatGoogleGenerativeAI integration

> Integrate with the ChatGoogleGenerativeAI chat model using LangChain Python.

Access Google's Generative AI models, including the Gemini family, via the **Gemini Developer API** or **Vertex AI**. The Gemini Developer API offers quick setup with API keys, ideal for individual developers. Vertex AI provides enterprise features and integrates with Google Cloud Platform.

For information on the latest models, model IDs, their features, context windows, etc. head to the [Google AI docs](https://ai.google.dev/gemini-api/docs).

<Note>
  **Vertex AI consolidation & compatibility**

  As of `langchain-google-genai` 4.0.0, this package uses the consolidated [`google-genai`](https://googleapis.github.io/python-genai/) SDK instead of the legacy [`google-ai-generativelanguage`](https://googleapis.dev/python/generativelanguage/latest/) SDK.

  This migration brings support for Gemini models both via the Gemini Developer API and Gemini API in Vertex AI, superseding certain classes in `langchain-google-vertexai`, such as `ChatVertexAI`.

  Read the [full announcement and migration guide](https://github.com/langchain-ai/langchain-google/discussions/1422).
</Note>

<Tip>
  **API Reference**

  For detailed documentation of all features and configuration options, head to the [`ChatGoogleGenerativeAI`](https://reference.langchain.com/python/langchain-google-genai/chat_models/ChatGoogleGenerativeAI) API reference.
</Tip>

## Overview

### Integration details

| Class                                                                                                                        | Package                                                                                    | Serializable | [JS support](https://js.langchain.com/docs/integrations/chat/google_generative_ai) |                                                Downloads                                                |                                                Version                                               |
| :--------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | :----------: | :--------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------: |
| [`ChatGoogleGenerativeAI`](https://reference.langchain.com/python/langchain-google-genai/chat_models/ChatGoogleGenerativeAI) | [`langchain-google-genai`](https://reference.langchain.com/python/langchain-google-genai/) |     beta     |                                          ✅                                         | ![PyPI - Downloads](https://img.shields.io/pypi/dm/langchain-google-genai?style=flat-square\&label=%20) | ![PyPI - Version](https://img.shields.io/pypi/v/langchain-google-genai?style=flat-square\&label=%20) |

### Model features

| [Tool calling](/oss/python/langchain/tools) | [Structured output](/oss/python/langchain/structured-output) | [Image input](/oss/python/langchain/messages#multimodal) | Audio input | Video input | [Token-level streaming](/oss/python/langchain/streaming/) | Native async | [Token usage](/oss/python/langchain/models#token-usage) | [Logprobs](/oss/python/langchain/models#log-probabilities) |
| :-----------------------------------------: | :----------------------------------------------------------: | :------------------------------------------------------: | :---------: | :---------: | :-------------------------------------------------------: | :----------: | :-----------------------------------------------------: | :--------------------------------------------------------: |
|                      ✅                      |                               ✅                              |                             ✅                            |      ✅      |      ✅      |                             ✅                             |       ✅      |                            ✅                            |                             ⚠️                             |

## Setup

To access Google AI models you'll need to create a Google Account, get a Google AI API key, and install the `langchain-google-genai` integration package.

### Installation

```python theme={null}
pip install -U langchain-google-genai
```

### Credentials

This integration supports two backends: **Gemini Developer API** and **Vertex AI**. The backend is selected automatically based on your configuration.

#### Backend selection

The backend is determined as follows:

1. If `GOOGLE_GENAI_USE_VERTEXAI` env var is set, uses that value
2. If `credentials` parameter is provided, uses Vertex AI
3. If `project` parameter is provided, uses Vertex AI
4. Otherwise, uses Gemini Developer API

You can also explicitly set `vertexai=True` or `vertexai=False` to override auto-detection.

<Tabs>
  <Tab title="Gemini Developer API">
    **Quick setup with API key**

    Recommended for individual developers / new users.

    Head to [Google AI Studio](https://ai.google.dev/gemini-api/docs/api-key) to generate an API key:

    ```python theme={null}
    import getpass
    import os

    if "GOOGLE_API_KEY" not in os.environ:
        os.environ["GOOGLE_API_KEY"] = getpass.getpass("Enter your Google AI API key: ")
    ```

    The integration checks for `GOOGLE_API_KEY` first, then `GEMINI_API_KEY` as a fallback.
  </Tab>

  <Tab title="Vertex AI with API key">
    **Vertex AI using API key authentication**

    You can use Vertex AI with API key authentication for simpler setup:

    ```bash theme={null}
    export GEMINI_API_KEY='your-api-key'
    export GOOGLE_GENAI_USE_VERTEXAI=true
    export GOOGLE_CLOUD_PROJECT='your-project-id'
    ```

    Or programmatically:

    ```python theme={null}
    from langchain_google_genai import ChatGoogleGenerativeAI

    llm = ChatGoogleGenerativeAI(
        model="gemini-2.5-flash",
        api_key="your-api-key", # [!code highlight]
        project="your-project-id", # [!code highlight]
        vertexai=True, # [!code highlight]
    )
    ```
  </Tab>

  <Tab title="Vertex AI with credentials">
    **Vertex AI using service account or ADC**

    Set up [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials):

    ```bash theme={null}
    gcloud auth application-default login
    ```

    Set your Google Cloud project:

    ```bash theme={null}
    export GOOGLE_CLOUD_PROJECT='your-project-id'
    # Optional: set region (defaults to us-central1)
    export GOOGLE_CLOUD_LOCATION='us-central1'
    ```

    Or use service account credentials:

    ```python theme={null}
    from google.oauth2 import service_account
    from langchain_google_genai import ChatGoogleGenerativeAI

    credentials = service_account.Credentials.from_service_account_file(
        "path/to/service-account.json",
        scopes=["https://www.googleapis.com/auth/cloud-platform"],
    )

    llm = ChatGoogleGenerativeAI(
        model="gemini-2.5-flash",
        credentials=credentials, # [!code highlight]
        project="your-project-id", # [!code highlight]
    )
    ```
  </Tab>
</Tabs>

#### Environment variables

| Variable                    | Purpose                                  | Backend                                |
| --------------------------- | ---------------------------------------- | -------------------------------------- |
| `GOOGLE_API_KEY`            | API key (primary)                        | Both (see `GOOGLE_GENAI_USE_VERTEXAI`) |
| `GEMINI_API_KEY`            | API key (fallback)                       | Both (see `GOOGLE_GENAI_USE_VERTEXAI`) |
| `GOOGLE_GENAI_USE_VERTEXAI` | Force Vertex AI backend (`true`/`false`) | Vertex AI                              |
| `GOOGLE_CLOUD_PROJECT`      | GCP project ID                           | Vertex AI                              |
| `GOOGLE_CLOUD_LOCATION`     | GCP region (default: `us-central1`)      | Vertex AI                              |

To enable automated tracing of your model calls, set your [LangSmith](/langsmith/observability) API key:

```python theme={null}
os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter your LangSmith API key: ")
os.environ["LANGSMITH_TRACING"] = "true"
```

## Instantiation

Now we can instantiate our model object and generate responses:

<Tabs>
  <Tab title="Gemini Developer API">
    ```python theme={null}
    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(
        model="gemini-3.5-flash",
        temperature=1.0,  # Gemini 3.0+ defaults to 1.0
        max_tokens=None,
        timeout=None,
        max_retries=2,
        # other params...
    )
    ```
  </Tab>

  <Tab title="Vertex AI">
    ```python theme={null}
    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(
        model="gemini-3.5-flash",
        project="your-project-id", # [!code highlight]
        location="us-central1",  # Optional, defaults to us-central1 [!code highlight]
        temperature=1.0,  # Gemini 3.0+ defaults to 1.0
        max_tokens=None,
        timeout=None,
        max_retries=2,
        # other params...
    )
    ```

    Providing `project` automatically selects the Vertex AI backend unless you explicitly set `vertexai=False`.
  </Tab>
</Tabs>

<Note>
  **Temperature for Gemini 3.0+ models**

  If `temperature` is not explicitly set and the model is Gemini 3.0 or later, it will be automatically set to `1.0` instead of the default `0.7` per Google GenAI API best practices. Using `0.7` with Gemini 3.0+ can cause infinite loops, degraded reasoning performance, and failure on complex tasks.
</Note>

See the [`ChatGoogleGenerativeAI`](https://reference.langchain.com/python/langchain-google-genai/chat_models/ChatGoogleGenerativeAI) API Reference for the full set of available model parameters.

### Proxy configuration

If you need to use a proxy, set these environment variables before initializing:

```bash theme={null}
export HTTPS_PROXY='http://username:password@proxy_uri:port'
export SSL_CERT_FILE='path/to/cert.pem'  # Optional: custom SSL certificate
```

For SOCKS5 proxies or advanced proxy configuration, use the `client_args` parameter:

```python theme={null}
model = ChatGoogleGenerativeAI(
    model="gemini-3.5-flash",
    client_args={"proxy": "socks5://user:pass@host:port"},
)
```

### Custom endpoints and headers

Use `base_url` and `additional_headers` for model-level HTTP options, such as routing requests through an internal gateway:

```python theme={null}
model = ChatGoogleGenerativeAI(
    model="gemini-3.5-flash",
    base_url="https://your-gemini-gateway.example.com",
    additional_headers={"X-Custom-Header": "value"},
)
```

To pass headers or other HTTP options for a single request, provide `http_options` when invoking the model:

```python theme={null}
token = "..."
messages = [("human", "Hello!")]

response = model.invoke(
    messages,
    http_options={
        "headers": {
            "Authorization": f"Bearer {token}",
        }
    },
)
```

The same call-time options work with async invocation:

```python theme={null}
response = await model.ainvoke(
    messages,
    http_options={"headers": {"Authorization": f"Bearer {token}"}},
)
```

The per-request `http_options` may be a dictionary or a `google.genai.types.HttpOptions` object. Header dictionaries are merged with model-level `additional_headers`, and per-request header values take precedence. Model-level `timeout` and `max_retries` settings are preserved unless you explicitly override `timeout` or `retry_options` in `http_options`.

```python theme={null}
from google.genai.types import HttpOptions

response = model.invoke(
    messages,
    http_options=HttpOptions(
        headers={"Authorization": f"Bearer {token}"},
    ),
)
```

## Invocation

```python theme={null}
messages = [
    (
        "system",
        "You are a helpful assistant that translates English to French. Translate the user sentence.",
    ),
    ("human", "I love programming."),
]
ai_msg = model.invoke(messages)
ai_msg
```

<CodeGroup>
  ```plaintext Gemini 3 theme={null}
  AIMessage(content=[{'type': 'text', 'text': "J'adore la programmation.", 'extras': {'signature': 'EpoWCpc...'}}], additional_kwargs={}, response_metadata={'prompt_feedback': {'block_reason': 0, 'safety_ratings': []}, 'finish_reason': 'STOP', 'model_name': 'gemini-3.5-flash', 'safety_ratings': [], 'model_provider': 'google_genai'}, id='lc_run--fb732b64-1ab4-4a28-b93b-dcfb2a164a3d-0', usage_metadata={'input_tokens': 21, 'output_tokens': 779, 'total_tokens': 800, 'input_token_details': {'cache_read': 0}, 'output_token_details': {'reasoning': 772}})
  ```

  ```plaintext Gemini 2.5 theme={null}
  AIMessage(content="J'adore la programmation.", additional_kwargs={}, response_metadata={'prompt_feedback': {'block_reason': 0, 'safety_ratings': []}, 'finish_reason': 'STOP', 'model_name': 'gemini-2.5-flash', 'safety_ratings': []}, id='run-3b28d4b8-8a62-4e6c-ad4e-b53e6e825749-0', usage_metadata={'input_tokens': 20, 'output_tokens': 7, 'total_tokens': 27, 'input_token_details': {'cache_read': 0}})
  ```
</CodeGroup>

<Note>
  **Message content shape**

  Gemini 3 series models return a list of content blocks to capture [thought signatures](#thought-signatures). Use `.text` to get string content:

  ```python theme={null}
  response.content  # -> [{"type": "text", "text": "Hello!", "extras": {"signature": "EpQFCp..."}}]
  response.text     # -> "Hello!"
  ```

  Gemini 2.5 and earlier return a plain string for `.content`.
</Note>

## Multimodal usage

Gemini models accept multimodal inputs (text, images, audio, video, PDFs) and some models can generate multimodal outputs.

### Supported input methods

| Method                                  | [Image](#image-input) | [Video](#video-input) | [Audio](#audio-input) | [PDF](#pdf-input) |
| --------------------------------------- | :-------------------: | :-------------------: | :-------------------: | :---------------: |
| [File upload](#file-upload) (Files API) |           ✅           |           ✅           |           ✅           |         ✅         |
| Base64 inline data                      |           ✅           |           ✅           |           ✅           |         ✅         |
| HTTP/HTTPS URLs\*                       |           ✅           |           ✅           |           ✅           |         ✅         |
| GCS URIs (`gs://...`)                   |           ✅           |           ✅           |           ✅           |         ✅         |

\*YouTube URLs are supported for video input in preview.

### File upload

You can upload files to Google's servers and reference them by URI. This works for PDFs, images, videos, and audio files.

```python theme={null}
import time
from google import genai
from langchain.messages import HumanMessage
from langchain_google_genai import ChatGoogleGenerativeAI

client = genai.Client()
model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

# Upload file to Google's servers
myfile = client.files.upload(file="/path/to/your/file.pdf")
while myfile.state.name == "PROCESSING":
    time.sleep(2)
    myfile = client.files.get(name=myfile.name)

# Reference by file_id in FileContentBlock
message = HumanMessage(
    content=[
        {"type": "text", "text": "What is in the document?"},
        {
            "type": "file",
            "file_id": myfile.uri,  # or myfile.name
            "mime_type": "application/pdf",
        },
    ]
)
response = model.invoke([message])
```

Once uploaded, you can reference the file in any of the media-specific sections below using the `file_id` pattern.

### Image input

Provide image inputs along with text using a [`HumanMessage`](https://reference.langchain.com/python/langchain-core/messages/human/HumanMessage) with a list content format.

<CodeGroup>
  ```python Image URL theme={null}
  from langchain.messages import HumanMessage
  from langchain_google_genai import ChatGoogleGenerativeAI

  model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

  message = HumanMessage(
      content=[
          {"type": "text", "text": "Describe the image at the URL."},
          {
              "type": "image",
              "url": "https://picsum.photos/seed/picsum/200/300",
          },
      ]
  )
  response = model.invoke([message])
  ```

  ```python Chat Completions image_url format theme={null}
  from langchain.messages import HumanMessage
  from langchain_google_genai import ChatGoogleGenerativeAI

  model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

  message = HumanMessage(
      content=[
          {"type": "text", "text": "Describe the image at the URL."},
          {"type": "image_url", "image_url": "https://picsum.photos/seed/picsum/200/300"},
      ]
  )
  response = model.invoke([message])
  ```

  ```python Base64 encoded theme={null}
  import base64
  from langchain.messages import HumanMessage
  from langchain_google_genai import ChatGoogleGenerativeAI

  model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

  image_bytes = open("path/to/your/image.jpg", "rb").read()
  image_base64 = base64.b64encode(image_bytes).decode("utf-8")
  mime_type = "image/jpeg"

  message = HumanMessage(
      content=[
          {"type": "text", "text": "Describe the local image."},
          {
              "type": "image",
              "base64": image_base64,
              "mime_type": mime_type,
          },
      ]
  )
  response = model.invoke([message])
  ```

  ```python Uploaded file theme={null}
  import time
  from google import genai
  from langchain.messages import HumanMessage
  from langchain_google_genai import ChatGoogleGenerativeAI

  client = genai.Client()
  model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

  # Upload and wait for processing
  myfile = client.files.upload(file="/path/to/image.jpg")
  while myfile.state.name == "PROCESSING":
      time.sleep(2)
      myfile = client.files.get(name=myfile.name)

  message = HumanMessage(
      content=[
          {"type": "text", "text": "Describe this image."},
          {
              "type": "file",
              "file_id": myfile.uri,
              "mime_type": "image/jpeg",
          },
      ]
  )
  response = model.invoke([message])
  ```
</CodeGroup>

Other supported image formats:

* A Google Cloud Storage URI (`gs://...`). Ensure the service account has access.

### PDF input

Provide PDF file inputs along with text.

<CodeGroup>
  ```python URL theme={null}
  from langchain.messages import HumanMessage
  from langchain_google_genai import ChatGoogleGenerativeAI

  model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

  message = HumanMessage(
      content=[
          {"type": "text", "text": "Describe the document in a sentence."},
          {
              "type": "image_url",  # (PDFs are treated as images)
              "image_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
          },
      ]
  )
  response = model.invoke([message])
  ```

  ```python Base64 encoded theme={null}
  import base64
  from langchain.messages import HumanMessage
  from langchain_google_genai import ChatGoogleGenerativeAI

  model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

  pdf_bytes = open("path/to/your/document.pdf", "rb").read()
  pdf_base64 = base64.b64encode(pdf_bytes).decode("utf-8")
  mime_type = "application/pdf"

  message = HumanMessage(
      content=[
          {"type": "text", "text": "Describe the document in a sentence."},
          {
              "type": "file",
              "base64": pdf_base64,
              "mime_type": mime_type,
          },
      ]
  )
  response = model.invoke([message])
  ```

  ```python Uploaded file theme={null}
  import time
  from google import genai
  from langchain.messages import HumanMessage
  from langchain_google_genai import ChatGoogleGenerativeAI

  client = genai.Client()
  model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

  # Upload and wait for processing
  myfile = client.files.upload(file="/path/to/document.pdf")
  while myfile.state.name == "PROCESSING":
      time.sleep(2)
      myfile = client.files.get(name=myfile.name)

  message = HumanMessage(
      content=[
          {"type": "text", "text": "Describe the document in a sentence."},
          {
              "type": "file",
              "file_id": myfile.uri,
              "mime_type": "application/pdf",
          },
      ]
  )
  response = model.invoke([message])
  ```
</CodeGroup>

### Audio input

Provide audio file inputs along with text.

<CodeGroup>
  ```python URL theme={null}
  from langchain.messages import HumanMessage
  from langchain_google_genai import ChatGoogleGenerativeAI

  model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

  message = HumanMessage(
      content=[
          {"type": "text", "text": "Summarize this audio in a sentence."},
          {
              "type": "image_url",
              "image_url": "https://example.com/audio.mp3",
          },
      ]
  )
  response = model.invoke([message])
  ```

  ```python Base64 encoded theme={null}
  import base64
  from langchain.messages import HumanMessage
  from langchain_google_genai import ChatGoogleGenerativeAI

  model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

  audio_bytes = open("path/to/your/audio.mp3", "rb").read()
  audio_base64 = base64.b64encode(audio_bytes).decode("utf-8")
  mime_type = "audio/mpeg"

  message = HumanMessage(
      content=[
          {"type": "text", "text": "Summarize this audio in a sentence."},
          {
              "type": "audio",
              "base64": audio_base64,
              "mime_type": mime_type,
          },
      ]
  )
  response = model.invoke([message])
  ```

  ```python Uploaded file theme={null}
  import time
  from google import genai
  from langchain.messages import HumanMessage
  from langchain_google_genai import ChatGoogleGenerativeAI

  client = genai.Client()
  model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

  # Upload and wait for processing
  myfile = client.files.upload(file="/path/to/audio.mp3")
  while myfile.state.name == "PROCESSING":
      time.sleep(2)
      myfile = client.files.get(name=myfile.name)

  message = HumanMessage(
      content=[
          {"type": "text", "text": "Summarize this audio in a sentence."},
          {
              "type": "file",
              "file_id": myfile.uri,
              "mime_type": "audio/mpeg",
          },
      ]
  )
  response = model.invoke([message])
  ```
</CodeGroup>

### Video input

Provide video file inputs along with text.

<CodeGroup>
  ```python Base64 encoded theme={null}
  import base64
  from langchain.messages import HumanMessage
  from langchain_google_genai import ChatGoogleGenerativeAI

  model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

  video_bytes = open("path/to/your/video.mp4", "rb").read()
  video_base64 = base64.b64encode(video_bytes).decode("utf-8")
  mime_type = "video/mp4"

  message = HumanMessage(
      content=[
          {"type": "text", "text": "Describe what's in this video in a sentence."},
          {
              "type": "video",
              "base64": video_base64,
              "mime_type": mime_type,
          },
      ]
  )
  response = model.invoke([message])
  ```

  ```python Uploaded file theme={null}
  import time
  from google import genai
  from langchain.messages import HumanMessage
  from langchain_google_genai import ChatGoogleGenerativeAI

  client = genai.Client()
  model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

  # Upload and wait for processing
  myfile = client.files.upload(file="/path/to/video.mp4")
  while myfile.state.name == "PROCESSING":
      time.sleep(2)
      myfile = client.files.get(name=myfile.name)

  message = HumanMessage(
      content=[
          {"type": "text", "text": "Summarize the video in 3 sentences."},
          {
              "type": "file",
              "file_id": myfile.uri,
              "mime_type": "video/mp4",
          },
      ]
  )
  response = model.invoke([message])
  ```

  ```python YouTube URL theme={null}
  from langchain.messages import HumanMessage
  from langchain_google_genai import ChatGoogleGenerativeAI

  model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

  message = HumanMessage(
      content=[
          {"type": "text", "text": "Summarize the video in 3 sentences."},
          {
              "type": "video",
              "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
              "mime_type": "video/mp4",
          },
      ]
  )
  response = model.invoke([message])
  ```
</CodeGroup>

<Note>
  **YouTube video input (preview)**

  * Only public videos are supported (not private or unlisted)
  * Free tier: max 8 hours of YouTube video per day
</Note>

### Image generation

Certain models can generate text and images inline. See [Gemini API docs](https://ai.google.dev/gemini-api/docs/image-generation) for details.

```python theme={null}
import base64
from IPython.display import Image, display
from langchain.messages import AIMessage
from langchain_google_genai import ChatGoogleGenerativeAI

model = ChatGoogleGenerativeAI(model="gemini-2.5-flash-image") # [!code highlight]

response = model.invoke("Generate a photorealistic image of a cuddly cat wearing a hat.")

def _get_image_base64(response: AIMessage) -> None:
    image_block = next(
        block
        for block in response.content
        if isinstance(block, dict) and block.get("image_url")
    )
    return image_block["image_url"].get("url").split(",")[-1]

image_base64 = _get_image_base64(response)
display(Image(data=base64.b64decode(image_base64), width=300))
```

Use `image_config` to control image dimensions and quality (see [`genai.types.ImageConfig`](https://googleapis.github.io/python-genai/genai.html#genai.types.ImageConfig)). It can be set at instantiation (applies to all calls) or at invocation (per-call override):

```python theme={null}
from langchain_google_genai import ChatGoogleGenerativeAI

# Set at instantiation (applies to all calls)
model = ChatGoogleGenerativeAI(
    model="gemini-2.5-flash-image",
    image_config={"aspect_ratio": "16:9"}, # [!code highlight]
)

# Or override per call
response = model.invoke(
    "Generate a photorealistic image of a cuddly cat wearing a hat.",
    image_config={"aspect_ratio": "1:1"}, # [!code highlight]
)
```

By default, image generation models may return both text and images (e.g. *"Ok! Here's an image of a..."*).

You can request that the model only return images by setting the `response_modalities` parameter:

<CodeGroup>
  ```python Instantiation theme={null}
  from langchain_google_genai import ChatGoogleGenerativeAI, Modality

  model = ChatGoogleGenerativeAI(
      model="gemini-2.5-flash-image",
      response_modalities=[Modality.IMAGE],  # [!code highlight]
  )

  # All invocations will return only images
  response = model.invoke("Generate a photorealistic image of a cuddly cat wearing a hat.")
  ```

  ```python Invocation theme={null}
  from langchain_google_genai import ChatGoogleGenerativeAI, Modality

  model = ChatGoogleGenerativeAI(model="gemini-2.5-flash-image")

  # Only this invocation will return images; others may return text+images
  response = model.invoke(
      "Generate a photorealistic image of a cuddly cat wearing a hat.",
      response_modalities=[Modality.IMAGE], # [!code highlight]
  )
  ```
</CodeGroup>

### Audio generation

Certain models can generate audio files. See [Gemini API docs](https://ai.google.dev/gemini-api/docs/speech-generation) for details.

<Warning>
  **Vertex AI Limitation**

  Audio generation models are currently in limited preview on Vertex AI and may require allowlist access. If you encounter an `INVALID_ARGUMENT` error when using TTS models with `vertexai=True`, your GCP project may need to be allowlisted.

  For more details, see this [Google AI forum discussion](https://discuss.ai.google.dev/t/request-allowlist-access-for-audio-output-in-gemini-2-5-pro-flash-tts-vertex-ai/108067).
</Warning>

```python theme={null}
from langchain_google_genai import ChatGoogleGenerativeAI

model = ChatGoogleGenerativeAI(model="gemini-2.5-flash-preview-tts") # [!code highlight]

response = model.invoke("Please say The quick brown fox jumps over the lazy dog")

# Base64 encoded binary data of the audio
wav_data = response.additional_kwargs.get("audio")
with open("output.wav", "wb") as f:
    f.write(wav_data)
```

## Tool calling

You can equip the model with tools to call.

```python theme={null}
from langchain.tools import tool
from langchain.messages import HumanMessage
from langchain_google_genai import ChatGoogleGenerativeAI


# Define the tool
@tool(description="Get the current weather in a given location")
def get_weather(location: str) -> str:
    return "It's sunny."


# Initialize and bind (potentially multiple) tools to the model
model_with_tools = ChatGoogleGenerativeAI(model="gemini-3.5-flash").bind_tools([get_weather])

# Step 1: Model generates tool calls
messages = [HumanMessage("What's the weather in Boston?")]
ai_msg = model_with_tools.invoke(messages)
messages.append(ai_msg)

# Check the tool calls in the response
print(ai_msg.tool_calls)

# Step 2: Execute tools and collect results
for tool_call in ai_msg.tool_calls:
    # Execute the tool with the generated arguments
    tool_result = get_weather.invoke(tool_call)
    messages.append(tool_result)

# Step 3: Pass results back to model for final response
final_response = model_with_tools.invoke(messages)
final_response
```

```text theme={null}
[{'name': 'get_weather', 'args': {'location': 'Boston'}, 'id': '879b4233-901b-4bbb-af56-3771ca8d3a75', 'type': 'tool_call'}]
```

## Structured output

Force the model to respond with a specific structure. See the [Gemini API docs](https://ai.google.dev/gemini-api/docs/structured-output) for more info.

```python theme={null}
from langchain_google_genai import ChatGoogleGenerativeAI
from pydantic import BaseModel
from typing import Literal


class Feedback(BaseModel):
    sentiment: Literal["positive", "neutral", "negative"]
    summary: str


model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")
structured_model = model.with_structured_output(
    schema=Feedback.model_json_schema(), method="json_schema"
)

response = structured_model.invoke("The new UI is great!")
response["sentiment"]  # "positive"
response["summary"]  # "The user expresses positive..."
```

For streaming structured output, merge dictionaries instead of using `+=`:

```python theme={null}
stream = structured_model.stream("The interface is intuitive and beautiful!")
full = next(stream)
for chunk in stream:
    full.update(chunk)  # Merge dictionaries
print(full)  # Complete structured response
# -> {'sentiment': 'positive', 'summary': 'The user praises...'}
```

### Structured output methods

Two methods are supported for structured output:

* **`method="json_schema"` (default)**: Uses Gemini's native structured output. Recommended for better reliability, as it constrains the model's generation process directly rather than relying on post-processing tool calls.
* **`method="function_calling"`**: Uses tool calling to extract structured data.

### Combining structured output with Google Search

When using `with_structured_output(method="function_calling")`, do not pass additional tools (like Google Search) in the same call.

To get structured output **and** search grounding in a single call, use `.bind()` with `response_mime_type` and `response_schema` instead of `with_structured_output`:

```python theme={null}
from langchain_google_genai import ChatGoogleGenerativeAI
from pydantic import BaseModel


class MatchResult(BaseModel):
    winner: str
    final_match_score: str
    scorers: list[str]


llm = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

llm_with_search = llm.bind(
    tools=[{"google_search": {}}],
    response_mime_type="application/json",
    response_schema=MatchResult.model_json_schema(),
)

response = llm_with_search.invoke(
    "Search for details of the latest Euro championship final match."
)
```

This uses Gemini's native JSON schema mode for structuring the output while allowing tools like Google Search for grounding—all in a single LLM call.

## Token usage tracking

Access token usage information from the response metadata.

```python theme={null}
from langchain_google_genai import ChatGoogleGenerativeAI

model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

result = model.invoke("Explain the concept of prompt engineering in one sentence.")

print(result.content)
print("\nUsage Metadata:")
print(result.usage_metadata)
```

```python theme={null}
Prompt engineering is the art and science of crafting effective text prompts to elicit desired and accurate responses from large language models.

Usage Metadata:
{'input_tokens': 10, 'output_tokens': 24, 'total_tokens': 34, 'input_token_details': {'cache_read': 0}}
```

## Thinking support

Certain Gemini models support configurable thinking depth. The parameter depends on the model version:

| Model family | Parameter         | Values                                                         |
| ------------ | ----------------- | -------------------------------------------------------------- |
| Gemini 3+    | `thinking_level`  | `"minimal"`, `"low"`, `"medium"`, `"high"` (default for Pro)   |
| Gemini 2.5   | `thinking_budget` | `0` (off), `-1` (dynamic), or a positive integer (token limit) |

```python theme={null}
from langchain_google_genai import ChatGoogleGenerativeAI

# Gemini 3+: use thinking_level
llm = ChatGoogleGenerativeAI(
    model="gemini-3.5-flash",
    thinking_level="low",  # [!code highlight]
)

response = llm.invoke("How many O's are in Google?")
```

### Gemini 2.5 models: `thinking_budget`

For Gemini 2.5 models, use `thinking_budget` (an integer token count) instead:

* Set to `0` to disable thinking (where supported)
* Set to `-1` for dynamic thinking (model decides)
* Set to a positive integer to constrain token usage

```python theme={null}
from langchain_google_genai import ChatGoogleGenerativeAI

llm = ChatGoogleGenerativeAI(
    model="gemini-2.5-flash",
    thinking_budget=1024,  # [!code highlight]
)
```

<Warning>
  Not all models allow disabling thinking. See the [Gemini models documentation](https://ai.google.dev/gemini-api/docs/models) for details.
</Warning>

### Viewing model thoughts

To see a thinking model's reasoning, set `include_thoughts=True`:

```python theme={null}
from langchain_google_genai import ChatGoogleGenerativeAI

llm = ChatGoogleGenerativeAI(
    model="gemini-3.5-flash",
    include_thoughts=True,  # [!code highlight]
)

response = llm.invoke("How many O's are in Google? How did you verify your answer?")
reasoning_tokens = response.usage_metadata["output_token_details"]["reasoning"]

print("Response:", response.content)
print("Reasoning tokens used:", reasoning_tokens)
```

```text theme={null}
Response: [{'type': 'thinking', 'thinking': '**Analyzing and Cou...'}, {'type': 'text', 'text': 'There a...', 'extras': {'signature': 'EroR...'}}]
Reasoning tokens used: 672
```

See the [Gemini API docs](https://ai.google.dev/gemini-api/docs/thinking) for more information on thinking.

### Thought signatures

[Thought signatures](https://ai.google.dev/gemini-api/docs/thinking) are encrypted representations of the model's reasoning. They enable Gemini to maintain thought context across multi-turn conversations, since the API is stateless.

<Note>
  Gemini 3 may raise 4xx errors if thought signatures are not passed back with tool call responses. Upgrade to `langchain-google-genai >= 3.1.0` to ensure this is handled correctly.
</Note>

Signatures appear in `AIMessage` responses:

* **Text blocks**: `extras.signature` within the content block
* **Tool calls**: `additional_kwargs["__gemini_function_call_thought_signatures__"]`

For multi-turn conversations, pass the full `AIMessage` back to the model so signatures are preserved. This happens automatically when you append the `AIMessage` to your messages list (as shown in the [tool calling](#tool-calling) example above).

<Warning>
  **Don't reconstruct messages manually.** If you create a new `AIMessage` instead of passing the original object, the signatures will be lost and the API may reject the request.
</Warning>

## Built-in tools

Google Gemini supports a variety of built-in tools, which can be bound to the model in the usual way.

### Google search

See [Gemini docs](https://ai.google.dev/gemini-api/docs/grounding/search-suggestions) for detail.

<CodeGroup>
  ```python Bind to model theme={null}
  from langchain_google_genai import ChatGoogleGenerativeAI

  model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

  model_with_search = model.bind_tools([{"google_search": {}}]) # [!code highlight]
  response = model_with_search.invoke("When is the next total solar eclipse in US?")

  response.content_blocks
  ```

  ```python Use on invocation theme={null}
  from langchain_google_genai import ChatGoogleGenerativeAI

  model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

  response = model.invoke(
      "When is the next total solar eclipse in US?",
      tools=[{"google_search": {}}], # [!code highlight]
  )

  response.content_blocks
  ```
</CodeGroup>

```text theme={null}
[{'type': 'text',
  'text': 'The next total solar eclipse visible in the contiguous United States will occur on...',
  'annotations': [{'type': 'citation',
    'id': 'abc123',
    'url': '<url for source 1>',
    'title': '<source 1 title>',
    'start_index': 0,
    'end_index': 99,
    'cited_text': 'The next total solar eclipse...',
    'extras': {'google_ai_metadata': {'web_search_queries': ['next total solar eclipse in US'],
       'grounding_chunk_index': 0,
       'confidence_scores': []}}},
   ...
```

### Google maps

Certain models support grounding using Google Maps. Maps grounding connects Gemini's generative capabilities with Google Maps' current, factual location data. This enables location-aware applications that provide accurate, geographically specific responses. See [Gemini docs](https://ai.google.dev/gemini-api/docs/maps-grounding) for detail.

<CodeGroup>
  ```python Bind to model theme={null}
  from langchain_google_genai import ChatGoogleGenerativeAI

  model = ChatGoogleGenerativeAI(model="gemini-2.5-pro")

  model_with_maps = model.bind_tools([{"google_maps": {}}]) # [!code highlight]
  response = model_with_maps.invoke(
      "What are some good Italian restaurants near the Eiffel Tower in Paris?"
  )
  ```

  ```python Use on invocation theme={null}
  from langchain_google_genai import ChatGoogleGenerativeAI

  model = ChatGoogleGenerativeAI(model="gemini-2.5-pro")

  response = model.invoke(
      "What are some good Italian restaurants near the Eiffel Tower in Paris?",
      tools=[{"google_maps": {}}], # [!code highlight]
  )
  ```
</CodeGroup>

The response will include grounding metadata with location information from Google Maps.

You can optionally provide a specific location context using `tool_config` with `lat_lng`. This is useful when you want to ground queries relative to a specific geographic point.

<CodeGroup>
  ```python Bind to model theme={null}
  from langchain_google_genai import ChatGoogleGenerativeAI

  model = ChatGoogleGenerativeAI(model="gemini-2.5-pro")

  # Provide location context (latitude and longitude)
  model_with_maps = model.bind_tools(
      [{"google_maps": {}}], # [!code highlight]
      tool_config={
          "retrieval_config": {  # Eiffel Tower
              "lat_lng": { # [!code highlight]
                  "latitude": 48.858844, # [!code highlight]
                  "longitude": 2.294351, # [!code highlight]
              } # [!code highlight]
          }
      },
  )

  response = model_with_maps.invoke(
      "What Italian restaurants are within a 5 minute walk from here?"
  )
  ```

  ```python Use on invocation theme={null}
  from langchain_google_genai import ChatGoogleGenerativeAI

  model = ChatGoogleGenerativeAI(model="gemini-2.5-pro")

  response = model.invoke(
      "What Italian restaurants are within a 5 minute walk from here?",
      tools=[{"google_maps": {}}], # [!code highlight]
      tool_config={
          "retrieval_config": {  # Eiffel Tower
              "lat_lng": { # [!code highlight]
                  "latitude": 48.858844, # [!code highlight]
                  "longitude": 2.294351, # [!code highlight]
              } # [!code highlight]
          }
      },
  )
  ```
</CodeGroup>

### URL context

The URL context tool enables the model to access and analyze content from URLs you provide in your prompt. This is useful for tasks like summarizing web pages, extracting data from multiple sources, or answering questions about online content. See [Gemini docs](https://ai.google.dev/gemini-api/docs/url-context) for detail and limitations.

<CodeGroup>
  ```python Bind to model theme={null}
  from langchain_google_genai import ChatGoogleGenerativeAI

  model = ChatGoogleGenerativeAI(model="gemini-2.5-flash")

  model_with_url_context = model.bind_tools([{"url_context": {}}]) # [!code highlight]
  response = model_with_url_context.invoke(
      "Summarize the content at https://docs.langchain.com"
  )
  ```

  ```python Use on invocation theme={null}
  from langchain_google_genai import ChatGoogleGenerativeAI

  model = ChatGoogleGenerativeAI(model="gemini-2.5-flash")

  response = model.invoke(
      "Summarize the content at https://docs.langchain.com",
      tools=[{"url_context": {}}], # [!code highlight]
  )
  ```
</CodeGroup>

### Code execution

See [Gemini docs](https://ai.google.dev/gemini-api/docs/code-execution?lang=python) for detail.

<CodeGroup>
  ```python Bind to model theme={null}
  from langchain_google_genai import ChatGoogleGenerativeAI

  model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

  model_with_code_interpreter = model.bind_tools([{"code_execution": {}}]) # [!code highlight]
  response = model_with_code_interpreter.invoke("Use Python to calculate 3^3.")

  response.content_blocks
  ```

  ```python Use on invocation theme={null}
  from langchain_google_genai import ChatGoogleGenerativeAI

  model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

  response = model.invoke(
      "Use Python to calculate 3^3.",
      tools=[{"code_execution": {}}], # [!code highlight]
  )

  response.content_blocks
  ```
</CodeGroup>

```text theme={null}
[{'type': 'server_tool_call',
  'name': 'code_interpreter',
  'args': {'code': 'print(3**3)', 'language': <Language.PYTHON: 1>},
  'id': '...'},
 {'type': 'server_tool_result',
  'tool_call_id': '',
  'status': 'success',
  'output': '27\n',
  'extras': {'block_type': 'code_execution_result',
   'outcome': <Outcome.OUTCOME_OK: 1>}},
 {'type': 'text', 'text': 'The calculation of 3 to the power of 3 is 27.'}]
```

### Computer use

The Gemini 2.5 Computer Use model (`gemini-2.5-computer-use-preview-10-2025`) can interact with browser environments to automate web tasks like clicking, typing, and scrolling.

<Warning>
  **Preview model limitations**

  The Computer Use model is in preview and may produce unexpected behavior. Always supervise automated tasks and avoid use with sensitive data or critical operations. See the [Gemini API docs](https://ai.google.dev/gemini-api/docs/computer-use) for safety best practices.
</Warning>

<CodeGroup>
  ```python Bind to model theme={null}
  from langchain_google_genai import ChatGoogleGenerativeAI

  model = ChatGoogleGenerativeAI(model="gemini-2.5-computer-use-preview-10-2025") # [!code highlight]
  model_with_computer = model.bind_tools([{"computer_use": {}}]) # [!code highlight]

  response = model_with_computer.invoke("Please navigate to example.com")

  response.content_blocks
  ```

  ```python Use on invocation theme={null}
  from langchain_google_genai import ChatGoogleGenerativeAI

  model = ChatGoogleGenerativeAI(model="gemini-2.5-computer-use-preview-10-2025") # [!code highlight]

  response = model.invoke(
      "Please navigate to example.com",
      tools=[{"computer_use": {}}], # [!code highlight]
  )

  response.content_blocks
  ```
</CodeGroup>

```text theme={null}
[{'type': 'tool_call',
  'id': '08a8b175-16ab-4861-8965-b736d5d4dd7e',
  'name': 'open_web_browser',
  'args': {}}]
```

You can configure the environment and exclude specific UI actions:

```python Advanced configuration theme={null}
from langchain_google_genai import ChatGoogleGenerativeAI, Environment

model = ChatGoogleGenerativeAI(model="gemini-2.5-computer-use-preview-10-2025") # [!code highlight]

# Specify the environment (browser is default)
model_with_computer = model.bind_tools(
    [{"computer_use": {"environment": Environment.ENVIRONMENT_BROWSER}}] # [!code highlight]
)

# Exclude specific UI actions
model_with_computer = model.bind_tools(
    [
        {
            "computer_use": {
                "environment": Environment.ENVIRONMENT_BROWSER,
                "excludedPredefinedFunctions": [ # [!code highlight]
                    "drag_and_drop", # [!code highlight]
                    "key_combination", # [!code highlight]
                ], # [!code highlight]
            }
        }
    ]
)

response = model_with_computer.invoke("Search for Python tutorials")
```

The model returns function calls for UI actions (like `click_at`, `type_text_at`, `scroll`) with normalized coordinates. You'll need to implement the actual execution of these actions in your browser automation framework.

## Safety settings

Gemini models have default safety settings that can be overridden. If you are receiving lots of `'Safety Warnings'` from your models, you can try tweaking the `safety_settings` attribute of the model. For example, to turn off safety blocking for dangerous content, you can construct your LLM as follows:

```python theme={null}
from langchain_google_genai import (
    ChatGoogleGenerativeAI,
    HarmBlockThreshold,
    HarmCategory,
)

llm = ChatGoogleGenerativeAI(
        model="gemini-3.5-flash",
        safety_settings={
        HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT: HarmBlockThreshold.BLOCK_NONE,
    },
)
```

For an enumeration of the categories and thresholds available, see Google's [safety settings guide](https://ai.google.dev/gemini-api/docs/safety-settings).

## Context caching

Context caching allows you to store and reuse content (e.g., PDFs, images) for faster processing. The `cached_content` parameter accepts a cache name created via the Google Generative AI API.

<Accordion title="Single file example">
  This caches a single file and queries it.

  ```python theme={null}
  import time
  from google import genai
  from google.genai import types
  from langchain.messages import HumanMessage
  from langchain_google_genai import ChatGoogleGenerativeAI

  client = genai.Client()

  # Upload file
  file = client.files.upload(file="path/to/your/file")
  while file.state.name == "PROCESSING":
      time.sleep(2)
      file = client.files.get(name=file.name)

  # Create cache
  model = "gemini-3.5-flash"
  cache = client.caches.create(
      model=model,
      config=types.CreateCachedContentConfig(
          display_name="Cached Content",
          system_instruction=(
              "You are an expert content analyzer, and your job is to answer "
              "the user's query based on the file you have access to."
          ),
          contents=[file],
          ttl="300s",
      ),
  )

  # Query with LangChain
  llm = ChatGoogleGenerativeAI(
      model=model,
      cached_content=cache.name,
  )
  message = HumanMessage(content="Summarize the main points of the content.")
  llm.invoke([message])
  ```
</Accordion>

<Accordion title="Multiple files example">
  This caches two files using `Part` and queries them together.

  ```python theme={null}
  import time
  from google import genai
  from google.genai.types import CreateCachedContentConfig, Content, Part
  from langchain.messages import HumanMessage
  from langchain_google_genai import ChatGoogleGenerativeAI

  client = genai.Client()

  # Upload files
  file_1 = client.files.upload(file="./file1")
  while file_1.state.name == "PROCESSING":
      time.sleep(2)
      file_1 = client.files.get(name=file_1.name)

  file_2 = client.files.upload(file="./file2")
  while file_2.state.name == "PROCESSING":
      time.sleep(2)
      file_2 = client.files.get(name=file_2.name)

  # Create cache with multiple files
  contents = [
      Content(
          role="user",
          parts=[
              Part.from_uri(file_uri=file_1.uri, mime_type=file_1.mime_type),
              Part.from_uri(file_uri=file_2.uri, mime_type=file_2.mime_type),
          ],
      )
  ]
  model = "gemini-3.5-flash"
  cache = client.caches.create(
      model=model,
      config=CreateCachedContentConfig(
          display_name="Cached Contents",
          system_instruction=(
              "You are an expert content analyzer, and your job is to answer "
              "the user's query based on the files you have access to."
          ),
          contents=contents,
          ttl="300s",
      ),
  )

  # Query with LangChain
  llm = ChatGoogleGenerativeAI(
      model=model,
      cached_content=cache.name,
  )
  message = HumanMessage(
      content="Provide a summary of the key information across both files."
  )
  llm.invoke([message])
  ```
</Accordion>

See the Gemini API docs on [context caching](https://ai.google.dev/gemini-api/docs/caching?lang=python) for more information.

## Response metadata

Access response metadata from the model response.

```python theme={null}
from langchain_google_genai import ChatGoogleGenerativeAI

llm = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

response = llm.invoke("Hello!")
response.response_metadata
```

```text theme={null}
{'prompt_feedback': {'block_reason': 0, 'safety_ratings': []},
 'finish_reason': 'STOP',
 'model_name': 'gemini-3.5-flash',
 'safety_ratings': [],
 'model_provider': 'google_genai'}
```

***

## API reference

For detailed documentation of all features and configuration options, head to the [`ChatGoogleGenerativeAI`](https://reference.langchain.com/python/langchain-google-genai/chat_models/ChatGoogleGenerativeAI) API reference.

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>

  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/python/integrations/chat/google_generative_ai.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>
