> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-eugene-1763577327-bfe51c2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# ChatGoogleGenerativeAI
> Get started using Gemini [chat models](/oss/python/langchain/models) in LangChain.
Access Google's Generative AI models, including the Gemini family, directly via the Gemini API or experiment rapidly using Google AI Studio. This is often the best starting point for individual developers.
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).
**API Reference**
For detailed documentation of all features and configuration options, head to the [`ChatGoogleGenerativeAI`](https://reference.langchain.com/python/integrations/langchain_google_genai/#langchain_google_genai.ChatGoogleGenerativeAI) API reference.
## Overview
### Integration details
| Class | Package | Local | Serializable | [JS support](https://js.langchain.com/docs/integrations/chat/google_generative_ai) | Downloads | Version |
| :---------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- | :---: | :----------: | :--------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------: |
| [`ChatGoogleGenerativeAI`](https://reference.langchain.com/python/integrations/langchain_google_genai/#langchain_google_genai.ChatGoogleGenerativeAI) | [`langchain-google-genai`](https://reference.langchain.com/python/integrations/langchain_google_genai) | ❌ | beta | ✅ |  |  |
### Model features
| [Tool calling](/oss/python/langchain/tools) | [Structured output](/oss/python/langchain/structured-output) | JSON mode | [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
Head to the [Google AI Studio](https://ai.google.dev/gemini-api/docs/api-key) to generate a Google AI API key. Once you've done this set the `GOOGLE_API_KEY` environment variable in your environment:
```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: ")
```
To enable automated tracing of your model calls, set your [LangSmith](https://docs.smith.langchain.com/) 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:
```python theme={null}
from langchain_google_genai import ChatGoogleGenerativeAI
llm = ChatGoogleGenerativeAI(
model="gemini-2.5-flash",
temperature=0,
max_tokens=None,
timeout=None,
max_retries=2,
# other params...
)
```
See the [`ChatGoogleGenerativeAI`](https://reference.langchain.com/python/integrations/langchain_google_genai/#langchain_google_genai.ChatGoogleGenerativeAI) API Reference for the full set of available model parameters.
## 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 = llm.invoke(messages)
ai_msg
```
```output 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}})
```
```python theme={null}
print(ai_msg.content)
```
```output theme={null}
J'adore la programmation.
```
## Multimodal usage
Gemini models can accept multimodal inputs (text, images, audio, video) and, for some models, generate multimodal outputs.
### Image input
Provide image inputs along with text using a [`HumanMessage`](https://reference.langchain.com/python/langchain/messages/#langchain.messages.HumanMessage) with a list content format.
Make sure to use a model that supports image input, such as `gemini-2.5-flash`.
```python theme={null}
import base64
from langchain.messages import HumanMessage
from langchain_google_genai import ChatGoogleGenerativeAI
# Example using a public URL (remains the same)
message_url = HumanMessage(
content=[
{
"type": "text",
"text": "Describe the image at the URL.",
},
{"type": "image_url", "image_url": "https://picsum.photos/seed/picsum/200/300"},
]
)
result_url = llm.invoke([message_url])
print(f"Response for URL image: {result_url.content}")
# Example using a local image file encoded in base64
image_file_path = "/Users/philschmid/projects/google-gemini/langchain/docs/static/img/agents_vs_chains.png"
with open(image_file_path, "rb") as image_file:
encoded_image = base64.b64encode(image_file.read()).decode("utf-8")
message_local = HumanMessage(
content=[
{"type": "text", "text": "Describe the local image."},
{"type": "image_url", "image_url": f"data:image/png;base64,{encoded_image}"},
]
)
result_local = llm.invoke([message_local])
print(f"Response for local image: {result_local.content}")
```
Other supported `image_url` formats:
* A Google Cloud Storage URI (`gs://...`). Ensure the service account has access.
* A PIL Image object (the library handles encoding).
### Audio input
Provide audio file inputs along with text.
```python theme={null}
import base64
from langchain.messages import HumanMessage
# Ensure you have an audio file named 'example_audio.mp3' or provide the correct path.
audio_file_path = "example_audio.mp3"
audio_mime_type = "audio/mpeg"
with open(audio_file_path, "rb") as audio_file:
encoded_audio = base64.b64encode(audio_file.read()).decode("utf-8")
message = HumanMessage(
content=[
{"type": "text", "text": "Transcribe the audio."},
{
"type": "media",
"data": encoded_audio, # Use base64 string directly
"mime_type": audio_mime_type,
},
]
)
response = llm.invoke([message]) # Uncomment to run
print(f"Response for audio: {response.content}")
```
### Video input
Provide video file inputs along with text.
```python theme={null}
import base64
from langchain.messages import HumanMessage
from langchain_google_genai import ChatGoogleGenerativeAI
# Ensure you have a video file named 'example_video.mp4' or provide the correct path.
video_file_path = "example_video.mp4"
video_mime_type = "video/mp4"
with open(video_file_path, "rb") as video_file:
encoded_video = base64.b64encode(video_file.read()).decode("utf-8")
message = HumanMessage(
content=[
{"type": "text", "text": "Describe the first few frames of the video."},
{
"type": "media",
"data": encoded_video, # Use base64 string directly
"mime_type": video_mime_type,
},
]
)
response = llm.invoke([message]) # Uncomment to run
print(f"Response for video: {response.content}")
```
### Image generation
Certain models (such as `gemini-2.5-flash-image`) can generate text and images inline.
See more information on the [Gemini API docs](https://ai.google.dev/gemini-api/docs/image-generation) for details.
```python theme={null}
# Running in a Jupyter notebook environment
import base64
from IPython.display import Image, display
from langchain.messages import AIMessage
from langchain_google_genai import ChatGoogleGenerativeAI, Modality
llm = ChatGoogleGenerativeAI(model="models/gemini-2.5-flash-image")
message = {
"role": "user",
"content": "Generate a photorealistic image of a cuddly cat wearing a hat.",
}
response = llm.invoke(
[message],
response_modalities=[Modality.TEXT, Modality.IMAGE],
)
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))
```
### Audio generation
Certain models (such as `gemini-2.5-flash-preview-tts`) can generate audio files.
See more information on the [Gemini API docs](https://ai.google.dev/gemini-api/docs/speech-generation) for details.
```python theme={null}
from langchain_google_genai import ChatGoogleGenerativeAI
llm = ChatGoogleGenerativeAI(model="gemini-2.5-flash-preview-tts")
response = llm.invoke(
"Please say The quick brown fox jumps over the lazy dog",
generation_config=dict(response_modalities=["AUDIO"]),
)
# 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, ToolMessage
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-2.5-flash-lite").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)
```
```output theme={null}
[{'name': 'get_weather', 'args': {'location': 'Boston'}, 'id': 'fb91e46d-e3f7-445b-a62f-50ae024bcdac', 'type': 'tool_call'}]
```
```output theme={null}
AIMessage(content='The weather in Boston is sunny.', additional_kwargs={}, response_metadata={'prompt_feedback': {'block_reason': 0, 'safety_ratings': []}, 'finish_reason': 'STOP', 'model_name': 'gemini-2.5-flash-lite', 'safety_ratings': [], 'model_provider': 'google_genai'}, id='lc_run--3fb38729-285b-4b43-aa3e-499cbc910544-0', usage_metadata={'input_tokens': 83, 'output_tokens': 7, 'total_tokens': 90, 'input_token_details': {'cache_read': 0}})
```
## 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
llm = ChatGoogleGenerativeAI(model="gemini-2.5-pro")
structured_llm = llm.with_structured_output(
schema=Feedback.model_json_schema(), method="json_schema"
)
response = structured_llm.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_llm.stream("The interface is intuitive and beautiful!")
full = next(stream)
for chunk in stream:
full.update(chunk) # Merge dictionaries
print(full) # Complete structured response
```
### Structured output methods
Two methods are supported for structured output:
* **`method="function_calling"` (default)**: Uses tool calling to extract structured data.
* **`method="json_mode"`**: Uses Gemini's native structured output.
The `json_mode` method is **recommended for better reliability** as it constrains the model's generation process directly rather than relying on post-processing tool calls.
## Token usage tracking
Access token usage information from the response metadata.
```python theme={null}
from langchain_google_genai import ChatGoogleGenerativeAI
llm = ChatGoogleGenerativeAI(model="gemini-2.5-flash-lite")
result = llm.invoke("Explain the concept of prompt engineering in one sentence.")
print(result.content)
print("\nUsage Metadata:")
print(result.usage_metadata)
```
```output 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}}
```
## Built-in tools
Google Gemini supports a variety of built-in tools ([google search](https://ai.google.dev/gemini-api/docs/grounding/search-suggestions), [code execution](https://ai.google.dev/gemini-api/docs/code-execution?lang=python)), which can be bound to the model in the usual way.
```python theme={null}
from google.ai.generativelanguage_v1beta.types import Tool as GenAITool
resp = llm.invoke(
"When is the next total solar eclipse in US?",
tools=[GenAITool(google_search={})],
)
print(resp.content)
```
```output theme={null}
The next total solar eclipse visible in the United States will occur on August 23, 2044. However, the path of totality will only pass through Montana, North Dakota, and South Dakota.
For a total solar eclipse that crosses a significant portion of the continental U.S., you'll have to wait until August 12, 2045. This eclipse will start in California and end in Florida.
```
```python theme={null}
from google.ai.generativelanguage_v1beta.types import Tool as GenAITool
resp = llm.invoke(
"What is 2*2, use python",
tools=[GenAITool(code_execution={})],
)
for c in resp.content:
if isinstance(c, dict):
if c["type"] == "code_execution_result":
print(f"Code execution result: {c['code_execution_result']}")
elif c["type"] == "executable_code":
print(f"Executable code: {c['executable_code']}")
else:
print(c)
```
```output theme={null}
Executable code: print(2*2)
Code execution result: 4
2*2 is 4.
```
## Thinking Support
See the [Gemini API docs](https://ai.google.dev/gemini-api/docs/thinking) for more info.
```python theme={null}
from langchain_google_genai import ChatGoogleGenerativeAI
llm = ChatGoogleGenerativeAI(
model="models/gemini-2.5-flash",
thinking_budget=1024
)
response = llm.invoke("How many O's are in Google? How did you verify your answer?")
reasoning_score = response.usage_metadata["output_token_details"]["reasoning"]
print("Response:", response.content)
print("Reasoning tokens used:", reasoning_score)
```
## 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-2.5-pro",
safety_settings={
HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT: HarmBlockThreshold.BLOCK_NONE,
},
)
```
For an enumeration of the categories and thresholds available, see Google's [safety setting types](https://ai.google.dev/api/python/google/generativeai/types/SafetySettingDict).
***
## API reference
For detailed documentation of all features and configuration options, head to the [`ChatGoogleGenerativeAI`](https://reference.langchain.com/python/integrations/langchain_google_genai/#langchain_google_genai.ChatGoogleGenerativeAI) API reference.
***
[Edit the source of this page on GitHub.](https://github.com/langchain-ai/docs/edit/main/src/oss/python/integrations/chat/google_generative_ai.mdx)
[Connect these docs programmatically](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.