google-genai 1.7.0__py3-none-any.whl → 1.53.0__py3-none-any.whl

{google_genai-1.7.0.dist-info → google_genai-1.53.0.dist-info}/METADATA

@@ -1,43 +1,65 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: google-genai
-Version: 1.7.0
+Version: 1.53.0
 Summary: GenAI Python SDK
 Author-email: Google LLC <googleapis-packages@google.com>
-License: Apache-2.0
+License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/googleapis/python-genai
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Internet
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: anyio<5.0.0,>=4.8.0
-Requires-Dist: google-auth<3.0.0,>=2.14.1
+Requires-Dist: google-auth[requests]<3.0.0,>=2.14.1
 Requires-Dist: httpx<1.0.0,>=0.28.1
-Requires-Dist: pydantic<3.0.0,>=2.0.0
+Requires-Dist: pydantic<3.0.0,>=2.9.0
 Requires-Dist: requests<3.0.0,>=2.28.1
+Requires-Dist: tenacity<9.2.0,>=8.2.3
 Requires-Dist: websockets<15.1.0,>=13.0.0
 Requires-Dist: typing-extensions<5.0.0,>=4.11.0
+Provides-Extra: aiohttp
+Requires-Dist: aiohttp<3.13.3; extra == "aiohttp"
+Provides-Extra: local-tokenizer
+Requires-Dist: sentencepiece>=0.2.0; extra == "local-tokenizer"
+Requires-Dist: protobuf; extra == "local-tokenizer"
+Dynamic: license-file
 
 # Google Gen AI SDK
 
 [![PyPI version](https://img.shields.io/pypi/v/google-genai.svg)](https://pypi.org/project/google-genai/)
+![Python support](https://img.shields.io/pypi/pyversions/google-genai)
+[![PyPI - Downloads](https://img.shields.io/pypi/dw/google-genai)](https://pypistats.org/packages/google-genai)
 
 --------
 **Documentation:** https://googleapis.github.io/python-genai/
 
 -----
 
-Google Gen AI Python SDK provides an interface for developers to integrate Google's generative models into their Python applications. It supports the [Gemini Developer API](https://ai.google.dev/gemini-api/docs) and [Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/overview) APIs.
+Google Gen AI Python SDK provides an interface for developers to integrate
+Google's generative models into their Python applications. It supports the
+[Gemini Developer API](https://ai.google.dev/gemini-api/docs) and
+[Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/overview)
+APIs.
+
+## Code Generation
+
+Generative models are often unaware of recent API and SDK updates and may suggest outdated or legacy code.
+
+We recommend using our Code Generation instructions [codegen_instructions.md](https://raw.githubusercontent.com/googleapis/python-genai/refs/heads/main/codegen_instructions.md) when generating Google Gen AI SDK code to guide your model towards using the more recent SDK features.
+
+Copy and paste the instructions from [this file](https://raw.githubusercontent.com/googleapis/python-genai/refs/heads/main/codegen_instructions.md)
+into your development environment to provide the model with the necessary
+context
 
 ## Installation
 
@@ -45,6 +67,12 @@ Google Gen AI Python SDK provides an interface for developers to integrate Googl
 pip install google-genai
 ```
 
+<small>With `uv`:</small>
+
+```sh
+uv pip install google-genai
+```
+
 ## Imports
 
 ```python
@@ -58,31 +86,76 @@ Please run one of the following code blocks to create a client for
 different services ([Gemini Developer API](https://ai.google.dev/gemini-api/docs) or [Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/overview)).
 
 ```python
+from google import genai
+
 # Only run this block for Gemini Developer API
 client = genai.Client(api_key='GEMINI_API_KEY')
 ```
 
 ```python
+from google import genai
+
 # Only run this block for Vertex AI API
 client = genai.Client(
     vertexai=True, project='your-project-id', location='us-central1'
 )
 ```
 
+## Using types
+
+All API methods support Pydantic types and dictionaries, which you can access
+from `google.genai.types`. You can import the types module with the following:
+
+```python
+from google.genai import types
+```
+
+Below is an example `generate_content()` call using types from the types module:
+
+```python
+response = client.models.generate_content(
+    model='gemini-2.0-flash-001',
+    contents=types.Part.from_text(text='Why is the sky blue?'),
+    config=types.GenerateContentConfig(
+        temperature=0,
+        top_p=0.95,
+        top_k=20,
+    ),
+)
+```
+
+Alternatively, you can accomplish the same request using dictionaries instead of
+types:
+
+```python
+response = client.models.generate_content(
+    model='gemini-2.0-flash-001',
+    contents={'text': 'Why is the sky blue?'},
+    config={
+        'temperature': 0,
+        'top_p': 0.95,
+        'top_k': 20,
+    },
+)
+```
+
 **(Optional) Using environment variables:**
 
 You can create a client by configuring the necessary environment variables.
 Configuration setup instructions depends on whether you're using the Gemini
 Developer API or the Gemini API in Vertex AI.
 
-**Gemini Developer API:** Set `GOOGLE_API_KEY` as shown below:
+**Gemini Developer API:** Set the `GEMINI_API_KEY` or `GOOGLE_API_KEY`.
+It will automatically be picked up by the client. It's recommended that you
+set only one of those variables, but if both are set, `GOOGLE_API_KEY` takes
+precedence.
 
 ```bash
-export GOOGLE_API_KEY='your-api-key'
+export GEMINI_API_KEY='your-api-key'
 ```
 
-**Gemini API on Vertex AI:** Set `GOOGLE_GENAI_USE_VERTEXAI`, `GOOGLE_CLOUD_PROJECT`
-and `GOOGLE_CLOUD_LOCATION`, as shown below:
+**Gemini API on Vertex AI:** Set `GOOGLE_GENAI_USE_VERTEXAI`,
+`GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION`, as shown below:
 
 ```bash
 export GOOGLE_GENAI_USE_VERTEXAI=true
@@ -91,9 +164,88 @@ export GOOGLE_CLOUD_LOCATION='us-central1'
 ```
 
 ```python
+from google import genai
+
 client = genai.Client()
 ```
 
+## Close a client
+
+Explicitly close the sync client to ensure that resources, such as the
+ underlying HTTP connections, are properly cleaned up and closed.
+
+```python
+from google.genai import Client
+
+client = Client()
+response_1 = client.models.generate_content(
+    model=MODEL_ID,
+    contents='Hello',
+)
+response_2 = client.models.generate_content(
+    model=MODEL_ID,
+    contents='Ask a question',
+)
+# Close the sync client to release resources.
+client.close()
+```
+
+To explicitly close the async client:
+
+```python
+from google.genai import Client
+
+aclient = Client(
+    vertexai=True, project='my-project-id', location='us-central1'
+).aio
+response_1 = await aclient.models.generate_content(
+    model=MODEL_ID,
+    contents='Hello',
+)
+response_2 = await aclient.models.generate_content(
+    model=MODEL_ID,
+    contents='Ask a question',
+)
+# Close the async client to release resources.
+await aclient.aclose()
+```
+
+## Client context managers
+
+By using the sync client context manager, it will close the underlying
+ sync client when exiting the with block.
+
+```python
+from google.genai import Client
+
+with Client() as client:
+    response_1 = client.models.generate_content(
+        model=MODEL_ID,
+        contents='Hello',
+    )
+    response_2 = client.models.generate_content(
+        model=MODEL_ID,
+        contents='Ask a question',
+    )
+```
+
+By using the async client context manager, it will close the underlying
+ async client when exiting the with block.
+
+```python
+from google.genai import Client
+
+async with Client().aio as aclient:
+    response_1 = await aclient.models.generate_content(
+        model=MODEL_ID,
+        contents='Hello',
+    )
+    response_2 = await aclient.models.generate_content(
+        model=MODEL_ID,
+        contents='Ask a question',
+    )
+```
+
 ### API Selection
 
 By default, the SDK uses the beta API endpoints provided by Google to support
@@ -104,6 +256,9 @@ To set the API version use `http_options`. For example, to set the API version
 to `v1` for Vertex AI:
 
 ```python
+from google import genai
+from google.genai import types
+
 client = genai.Client(
     vertexai=True,
     project='your-project-id',
@@ -115,12 +270,72 @@ client = genai.Client(
 To set the API version to `v1alpha` for the Gemini Developer API:
 
 ```python
+from google import genai
+from google.genai import types
+
 client = genai.Client(
     api_key='GEMINI_API_KEY',
     http_options=types.HttpOptions(api_version='v1alpha')
 )
 ```
 
+### Faster async client option: Aiohttp
+
+By default we use httpx for both sync and async client implementations. In order
+to have faster performance, you may install `google-genai[aiohttp]`. In Gen AI
+SDK we configure `trust_env=True` to match with the default behavior of httpx.
+Additional args of `aiohttp.ClientSession.request()` ([see _RequestOptions args](https://github.com/aio-libs/aiohttp/blob/v3.12.13/aiohttp/client.py#L170)) can be passed
+through the following way:
+
+```python
+http_options = types.HttpOptions(
+    async_client_args={'cookies': ..., 'ssl': ...},
+)
+
+client=Client(..., http_options=http_options)
+```
+
+### Proxy
+
+Both httpx and aiohttp libraries use `urllib.request.getproxies` from
+environment variables. Before client initialization, you may set proxy (and
+optional SSL_CERT_FILE) by setting the environment variables:
+
+```bash
+export HTTPS_PROXY='http://username:password@proxy_uri:port'
+export SSL_CERT_FILE='client.pem'
+```
+
+If you need `socks5` proxy, httpx [supports](https://www.python-httpx.org/advanced/proxies/#socks) `socks5` proxy if you pass it via
+args to `httpx.Client()`. You may install `httpx[socks]` to use it.
+Then, you can pass it through the following way:
+
+```python
+http_options = types.HttpOptions(
+    client_args={'proxy': 'socks5://user:pass@host:port'},
+    async_client_args={'proxy': 'socks5://user:pass@host:port'},
+)
+
+client=Client(..., http_options=http_options)
+```
+
+### Custom base url
+
+In some cases you might need a custom base url (for example, API gateway proxy
+ server) and bypass some authentication checks for project, location, or API key.
+You may pass the custom base url like this:
+
+```python
+base_url = 'https://test-api-gateway-proxy.com'
+client = Client(
+    vertexai=True,  # Currently only vertexai=True is supported
+    http_options={
+        'base_url': base_url,
+        'headers': {'Authorization': 'Bearer test_token'},
+    },
+)
+```
+
 ## Types
 
 Parameter types can be specified as either dictionaries(`TypedDict`) or
@@ -129,19 +344,42 @@ Pydantic model types are available in the `types` module.
 
 ## Models
 
-The `client.models` modules exposes model inferencing and model getters.
+The `client.models` module exposes model inferencing and model getters.
+See the 'Create a client' section above to initialize a client.
 
 ### Generate Content
 
-#### with text content
+#### with text content input (text output)
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.0-flash-001', contents='Why is the sky blue?'
+    model='gemini-2.5-flash', contents='Why is the sky blue?'
 )
 print(response.text)
 ```
 
+#### with text content input (image output)
+
+```python
+from google.genai import types
+
+response = client.models.generate_content(
+    model='gemini-2.5-flash-image',
+    contents='A cartoon infographic for flying sneakers',
+    config=types.GenerateContentConfig(
+        response_modalities=["IMAGE"],
+        image_config=types.ImageConfig(
+            aspect_ratio="9:16",
+        ),
+    ),
+)
+
+for part in response.parts:
+    if part.inline_data:
+        generated_image = part.as_image()
+        generated_image.show()
+```
+
 #### with uploaded file (Gemini Developer API only)
 download the file in console.
 
@@ -154,7 +392,7 @@ python code.
 ```python
 file = client.files.upload(file='a11.txt')
 response = client.models.generate_content(
-    model='gemini-2.0-flash-001',
+    model='gemini-2.5-flash',
     contents=['Could you summarize this file?', file]
 )
 print(response.text)
@@ -171,9 +409,11 @@ This is the canonical way to provide contents, SDK will not do any conversion.
 ##### Provide a `types.Content` instance
 
 ```python
+from google.genai import types
+
 contents = types.Content(
-  role='user',
-  parts=[types.Part.from_text(text='Why is the sky blue?')]
+    role='user',
+    parts=[types.Part.from_text(text='Why is the sky blue?')]
 )
 ```
 
@@ -181,10 +421,10 @@ SDK converts this to
 
 ```python
 [
-  types.Content(
-    role='user',
-    parts=[types.Part.from_text(text='Why is the sky blue?')]
-  )
+    types.Content(
+        role='user',
+        parts=[types.Part.from_text(text='Why is the sky blue?')]
+    )
 ]
 ```
 
@@ -198,11 +438,11 @@ The SDK will assume this is a text part, and it converts this into the following
 
 ```python
 [
-  types.UserContent(
-    parts=[
-      types.Part.from_text(text='Why is the sky blue?')
-    ]
-  )
+    types.UserContent(
+        parts=[
+            types.Part.from_text(text='Why is the sky blue?')
+        ]
+    )
 ]
 ```
 
@@ -220,12 +460,12 @@ like the following:
 
 ```python
 [
-  types.UserContent(
-    parts=[
-      types.Part.from_text(text='Why is the sky blue?'),
-      types.Part.from_text(text='Why is the cloud white?'),
-    ]
-  )
+    types.UserContent(
+        parts=[
+            types.Part.from_text(text='Why is the sky blue?'),
+            types.Part.from_text(text='Why is the cloud white?'),
+        ]
+    )
 ]
 ```
 
@@ -235,9 +475,11 @@ Where a `types.UserContent` is a subclass of `types.Content`, the
 ##### Provide a function call part
 
 ```python
+from google.genai import types
+
 contents = types.Part.from_function_call(
-  name='get_weather_by_location',
-  args={'location': 'Boston'}
+    name='get_weather_by_location',
+    args={'location': 'Boston'}
 )
 ```
 
@@ -245,14 +487,14 @@ The SDK converts a function call part to a content with a `model` role:
 
 ```python
 [
-  types.ModelContent(
-    parts=[
-      types.Part.from_function_call(
-        name='get_weather_by_location',
-        args={'location': 'Boston'}
-      )
-    ]
-  )
+    types.ModelContent(
+        parts=[
+            types.Part.from_function_call(
+                name='get_weather_by_location',
+                args={'location': 'Boston'}
+            )
+        ]
+    )
 ]
 ```
 
@@ -262,15 +504,17 @@ Where a `types.ModelContent` is a subclass of `types.Content`, the
 ##### Provide a list of function call parts
 
 ```python
+from google.genai import types
+
 contents = [
-  types.Part.from_function_call(
-    name='get_weather_by_location',
-    args={'location': 'Boston'}
-  ),
-  types.Part.from_function_call(
-    name='get_weather_by_location',
-    args={'location': 'New York'}
-  ),
+    types.Part.from_function_call(
+        name='get_weather_by_location',
+        args={'location': 'Boston'}
+    ),
+    types.Part.from_function_call(
+        name='get_weather_by_location',
+        args={'location': 'New York'}
+    ),
 ]
 ```
 
@@ -278,18 +522,18 @@ The SDK converts a list of function call parts to the a content with a `model` r
 
 ```python
 [
-  types.ModelContent(
-    parts=[
-      types.Part.from_function_call(
-        name='get_weather_by_location',
-        args={'location': 'Boston'}
-      ),
-      types.Part.from_function_call(
-        name='get_weather_by_location',
-        args={'location': 'New York'}
-      )
-    ]
-  )
+    types.ModelContent(
+        parts=[
+            types.Part.from_function_call(
+                name='get_weather_by_location',
+                args={'location': 'Boston'}
+            ),
+            types.Part.from_function_call(
+                name='get_weather_by_location',
+                args={'location': 'New York'}
+            )
+        ]
+    )
 ]
 ```
 
@@ -299,9 +543,11 @@ Where a `types.ModelContent` is a subclass of `types.Content`, the
 ##### Provide a non function call part
 
 ```python
+from google.genai import types
+
 contents = types.Part.from_uri(
-  file_uri: 'gs://generativeai-downloads/images/scones.jpg',
-  mime_type: 'image/jpeg',
+    file_uri: 'gs://generativeai-downloads/images/scones.jpg',
+    mime_type: 'image/jpeg',
 )
 ```
 
@@ -309,24 +555,26 @@ The SDK converts all non function call parts into a content with a `user` role.
 
 ```python
 [
-  types.UserContent(parts=[
-    types.Part.from_uri(
-     file_uri: 'gs://generativeai-downloads/images/scones.jpg',
-      mime_type: 'image/jpeg',
-    )
-  ])
+    types.UserContent(parts=[
+        types.Part.from_uri(
+            file_uri: 'gs://generativeai-downloads/images/scones.jpg',
+            mime_type: 'image/jpeg',
+        )
+    ])
 ]
 ```
 
 ##### Provide a list of non function call parts
 
 ```python
+from google.genai import types
+
 contents = [
-  types.Part.from_text('What is this image about?'),
-  types.Part.from_uri(
-    file_uri: 'gs://generativeai-downloads/images/scones.jpg',
-    mime_type: 'image/jpeg',
-  )
+    types.Part.from_text('What is this image about?'),
+    types.Part.from_uri(
+        file_uri: 'gs://generativeai-downloads/images/scones.jpg',
+        mime_type: 'image/jpeg',
+    )
 ]
 ```
 
@@ -334,15 +582,15 @@ The SDK will convert the list of parts into a content with a `user` role
 
 ```python
 [
-  types.UserContent(
-    parts=[
-      types.Part.from_text('What is this image about?'),
-      types.Part.from_uri(
-        file_uri: 'gs://generativeai-downloads/images/scones.jpg',
-        mime_type: 'image/jpeg',
-      )
-    ]
-  )
+    types.UserContent(
+        parts=[
+            types.Part.from_text('What is this image about?'),
+            types.Part.from_uri(
+                file_uri: 'gs://generativeai-downloads/images/scones.jpg',
+                mime_type: 'image/jpeg',
+            )
+        ]
+    )
 ]
 ```
 
@@ -360,11 +608,17 @@ If you put a list within a list, the inner list can only contain
 ### System Instructions and Other Configs
 
 The output of the model can be influenced by several optional settings
-available in generate_content's config parameter. For example, the
-variability and length of the output can be influenced by the temperature
-and max_output_tokens respectively.
+available in generate_content's config parameter. For example, increasing
+`max_output_tokens` is essential for longer model responses. To make a model more
+deterministic, lowering the `temperature` parameter reduces randomness, with
+values near 0 minimizing variability. Capabilities and parameter defaults for
+each model is shown in the
+[Vertex AI docs](https://cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/2-5-flash)
+and [Gemini API docs](https://ai.google.dev/gemini-api/docs/models) respectively.
 
 ```python
+from google.genai import types
+
 response = client.models.generate_content(
     model='gemini-2.0-flash-001',
     contents='high',
@@ -377,31 +631,6 @@ response = client.models.generate_content(
 print(response.text)
 ```
 
-### Typed Config
-
-All API methods support Pydantic types for parameters as well as
-dictionaries. You can get the type from `google.genai.types`.
-
-```python
-response = client.models.generate_content(
-    model='gemini-2.0-flash-001',
-    contents=types.Part.from_text(text='Why is the sky blue?'),
-    config=types.GenerateContentConfig(
-        temperature=0,
-        top_p=0.95,
-        top_k=20,
-        candidate_count=1,
-        seed=5,
-        max_output_tokens=100,
-        stop_sequences=['STOP!'],
-        presence_penalty=0.0,
-        frequency_penalty=0.0,
-    ),
-)
-
-print(response.text)
-```
-
 ### List Base Models
 
 To retrieve tuned models, see [list tuned models](#list-tuned-models).
@@ -419,7 +648,7 @@ pager.next_page()
 print(pager[0])
 ```
 
-#### Async
+#### List Base Models (Asynchronous)
 
 ```python
 async for job in await client.aio.models.list():
@@ -437,8 +666,10 @@ print(async_pager[0])
 ### Safety Settings
 
 ```python
+from google.genai import types
+
 response = client.models.generate_content(
-    model='gemini-2.0-flash-001',
+    model='gemini-2.5-flash',
     contents='Say something bad.',
     config=types.GenerateContentConfig(
         safety_settings=[
@@ -460,17 +691,19 @@ You can pass a Python function directly and it will be automatically
 called and responded by default.
 
 ```python
+from google.genai import types
+
 def get_current_weather(location: str) -> str:
     """Returns the current weather.
 
     Args:
-      location: The city and state, e.g. San Francisco, CA
+        location: The city and state, e.g. San Francisco, CA
     """
     return 'sunny'
 
 
 response = client.models.generate_content(
-    model='gemini-2.0-flash-001',
+    model='gemini-2.5-flash',
     contents='What is the weather like in Boston?',
     config=types.GenerateContentConfig(tools=[get_current_weather]),
 )
@@ -483,15 +716,17 @@ automatic function calling, you can disable automatic function calling
 as follows:
 
 ```python
+from google.genai import types
+
 response = client.models.generate_content(
-  model='gemini-2.0-flash-001',
-  contents='What is the weather like in Boston?',
-  config=types.GenerateContentConfig(
-    tools=[get_current_weather],
-    automatic_function_calling=types.AutomaticFunctionCallingConfig(
-      disable=True
+    model='gemini-2.5-flash',
+    contents='What is the weather like in Boston?',
+    config=types.GenerateContentConfig(
+        tools=[get_current_weather],
+        automatic_function_calling=types.AutomaticFunctionCallingConfig(
+            disable=True
+        ),
     ),
-  ),
 )
 ```
 
@@ -511,25 +746,27 @@ The following example shows how to declare a function and pass it as a tool.
 Then you will receive a function call part in the response.
 
 ```python
+from google.genai import types
+
 function = types.FunctionDeclaration(
     name='get_current_weather',
     description='Get the current weather in a given location',
-    parameters=types.Schema(
-        type='OBJECT',
-        properties={
-            'location': types.Schema(
-                type='STRING',
-                description='The city and state, e.g. San Francisco, CA',
-            ),
+    parameters_json_schema={
+        'type': 'object',
+        'properties': {
+            'location': {
+                'type': 'string',
+                'description': 'The city and state, e.g. San Francisco, CA',
+            }
         },
-        required=['location'],
-    ),
+        'required': ['location'],
+    },
 )
 
 tool = types.Tool(function_declarations=[function])
 
 response = client.models.generate_content(
-    model='gemini-2.0-flash-001',
+    model='gemini-2.5-flash',
     contents='What is the weather like in Boston?',
     config=types.GenerateContentConfig(tools=[tool]),
 )
@@ -543,6 +780,8 @@ the model.
 The following example shows how to do it for a simple function invocation.
 
 ```python
+from google.genai import types
+
 user_prompt_content = types.Content(
     role='user',
     parts=[types.Part.from_text(text='What is the weather like in Boston?')],
@@ -571,7 +810,7 @@ function_response_content = types.Content(
 )
 
 response = client.models.generate_content(
-    model='gemini-2.0-flash-001',
+    model='gemini-2.5-flash',
     contents=[
         user_prompt_content,
         function_call_content,
@@ -595,16 +834,18 @@ maximum remote call for automatic function calling (default to 10 times).
 If you'd like to disable automatic function calling in `ANY` mode:
 
 ```python
+from google.genai import types
+
 def get_current_weather(location: str) -> str:
     """Returns the current weather.
 
     Args:
-      location: The city and state, e.g. San Francisco, CA
+        location: The city and state, e.g. San Francisco, CA
     """
     return "sunny"
 
 response = client.models.generate_content(
-    model="gemini-2.0-flash-001",
+    model="gemini-2.5-flash",
     contents="What is the weather like in Boston?",
     config=types.GenerateContentConfig(
         tools=[get_current_weather],
@@ -623,16 +864,18 @@ configure the maximum remote calls to be `x + 1`.
 Assuming you prefer `1` turn for automatic function calling.
 
 ```python
+from google.genai import types
+
 def get_current_weather(location: str) -> str:
     """Returns the current weather.
 
     Args:
-      location: The city and state, e.g. San Francisco, CA
+        location: The city and state, e.g. San Francisco, CA
     """
     return "sunny"
 
 response = client.models.generate_content(
-    model="gemini-2.0-flash-001",
+    model="gemini-2.5-flash",
     contents="What is the weather like in Boston?",
     config=types.GenerateContentConfig(
         tools=[get_current_weather],
@@ -645,18 +888,100 @@ response = client.models.generate_content(
     ),
 )
 ```
+
+#### Model Context Protocol (MCP) support (experimental)
+
+Built-in [MCP](https://modelcontextprotocol.io/introduction) support is an
+experimental feature. You can pass a local MCP server as a tool directly.
+
+```python
+import os
+import asyncio
+from datetime import datetime
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+from google import genai
+
+client = genai.Client()
+
+# Create server parameters for stdio connection
+server_params = StdioServerParameters(
+    command="npx",  # Executable
+    args=["-y", "@philschmid/weather-mcp"],  # MCP Server
+    env=None,  # Optional environment variables
+)
+
+async def run():
+    async with stdio_client(server_params) as (read, write):
+        async with ClientSession(read, write) as session:
+            # Prompt to get the weather for the current day in London.
+            prompt = f"What is the weather in London in {datetime.now().strftime('%Y-%m-%d')}?"
+
+            # Initialize the connection between client and server
+            await session.initialize()
+
+            # Send request to the model with MCP function declarations
+            response = await client.aio.models.generate_content(
+                model="gemini-2.5-flash",
+                contents=prompt,
+                config=genai.types.GenerateContentConfig(
+                    temperature=0,
+                    tools=[session],  # uses the session, will automatically call the tool using automatic function calling
+                ),
+            )
+            print(response.text)
+
+# Start the asyncio event loop and run the main function
+asyncio.run(run())
+```
+
 ### JSON Response Schema
 
 However you define your schema, don't duplicate it in your input prompt,
 including by giving examples of expected JSON output. If you do, the generated
 output might be lower in quality.
 
+#### JSON Schema support
+Schemas can be provided as standard JSON schema.
+```python
+user_profile = {
+    'properties': {
+        'age': {
+            'anyOf': [
+                {'maximum': 20, 'minimum': 0, 'type': 'integer'},
+                {'type': 'null'},
+            ],
+            'title': 'Age',
+        },
+        'username': {
+            'description': "User's unique name",
+            'title': 'Username',
+            'type': 'string',
+        },
+    },
+    'required': ['username', 'age'],
+    'title': 'User Schema',
+    'type': 'object',
+}
+
+response = client.models.generate_content(
+    model='gemini-2.5-flash',
+    contents='Give me a random user profile.',
+    config={
+        'response_mime_type': 'application/json',
+        'response_json_schema': user_profile
+    },
+)
+print(response.parsed)
+```
+
 #### Pydantic Model Schema support
 
 Schemas can be provided as Pydantic Models.
 
 ```python
 from pydantic import BaseModel
+from google.genai import types
 
 
 class CountryInfo(BaseModel):
@@ -670,7 +995,7 @@ class CountryInfo(BaseModel):
 
 
 response = client.models.generate_content(
-    model='gemini-2.0-flash-001',
+    model='gemini-2.5-flash',
     contents='Give me information for the United States.',
     config=types.GenerateContentConfig(
         response_mime_type='application/json',
@@ -681,8 +1006,10 @@ print(response.text)
 ```
 
 ```python
+from google.genai import types
+
 response = client.models.generate_content(
-    model='gemini-2.0-flash-001',
+    model='gemini-2.5-flash',
     contents='Give me information for the United States.',
     config=types.GenerateContentConfig(
         response_mime_type='application/json',
@@ -720,56 +1047,62 @@ You can set response_mime_type to 'text/x.enum' to return one of those enum
 values as the response.
 
 ```python
+from enum import Enum
+
 class InstrumentEnum(Enum):
-  PERCUSSION = 'Percussion'
-  STRING = 'String'
-  WOODWIND = 'Woodwind'
-  BRASS = 'Brass'
-  KEYBOARD = 'Keyboard'
+    PERCUSSION = 'Percussion'
+    STRING = 'String'
+    WOODWIND = 'Woodwind'
+    BRASS = 'Brass'
+    KEYBOARD = 'Keyboard'
 
 response = client.models.generate_content(
-      model='gemini-2.0-flash-001',
-      contents='What instrument plays multiple notes at once?',
-      config={
-          'response_mime_type': 'text/x.enum',
-          'response_schema': InstrumentEnum,
-      },
-  )
+    model='gemini-2.5-flash',
+    contents='What instrument plays multiple notes at once?',
+    config={
+        'response_mime_type': 'text/x.enum',
+        'response_schema': InstrumentEnum,
+    },
+)
 print(response.text)
 ```
 
 #### JSON Response
 
-You can also set response_mime_type to 'application/json', the response will be identical but in quotes.
+You can also set response_mime_type to 'application/json', the response will be
+identical but in quotes.
 
 ```python
 from enum import Enum
 
 class InstrumentEnum(Enum):
-  PERCUSSION = 'Percussion'
-  STRING = 'String'
-  WOODWIND = 'Woodwind'
-  BRASS = 'Brass'
-  KEYBOARD = 'Keyboard'
+    PERCUSSION = 'Percussion'
+    STRING = 'String'
+    WOODWIND = 'Woodwind'
+    BRASS = 'Brass'
+    KEYBOARD = 'Keyboard'
 
 response = client.models.generate_content(
-      model='gemini-2.0-flash-001',
-      contents='What instrument plays multiple notes at once?',
-      config={
-          'response_mime_type': 'application/json',
-          'response_schema': InstrumentEnum,
-      },
-  )
+    model='gemini-2.5-flash',
+    contents='What instrument plays multiple notes at once?',
+    config={
+        'response_mime_type': 'application/json',
+        'response_schema': InstrumentEnum,
+    },
+)
 print(response.text)
 ```
 
-### Streaming
+### Generate Content (Synchronous Streaming)
+
+Generate content in a streaming format so that the model outputs streams back
+to you, rather than being returned as one chunk.
 
 #### Streaming for text content
 
 ```python
 for chunk in client.models.generate_content_stream(
-    model='gemini-2.0-flash-001', contents='Tell me a story in 300 words.'
+    model='gemini-2.5-flash', contents='Tell me a story in 300 words.'
 ):
     print(chunk.text, end='')
 ```
@@ -780,8 +1113,10 @@ If your image is stored in [Google Cloud Storage](https://cloud.google.com/stora
 you can use the `from_uri` class method to create a `Part` object.
 
 ```python
+from google.genai import types
+
 for chunk in client.models.generate_content_stream(
-    model='gemini-2.0-flash-001',
+    model='gemini-2.5-flash',
     contents=[
         'What is this image about?',
         types.Part.from_uri(
@@ -797,13 +1132,15 @@ If your image is stored in your local file system, you can read it in as bytes
 data and use the `from_bytes` class method to create a `Part` object.
 
 ```python
+from google.genai import types
+
 YOUR_IMAGE_PATH = 'your_image_path'
 YOUR_IMAGE_MIME_TYPE = 'your_image_mime_type'
 with open(YOUR_IMAGE_PATH, 'rb') as f:
     image_bytes = f.read()
 
 for chunk in client.models.generate_content_stream(
-    model='gemini-2.0-flash-001',
+    model='gemini-2.5-flash',
     contents=[
         'What is this image about?',
         types.Part.from_bytes(data=image_bytes, mime_type=YOUR_IMAGE_MIME_TYPE),
@@ -812,27 +1149,27 @@ for chunk in client.models.generate_content_stream(
     print(chunk.text, end='')
 ```
 
-### Async
+### Generate Content (Asynchronous Non Streaming)
 
 `client.aio` exposes all the analogous [`async` methods](https://docs.python.org/3/library/asyncio.html)
-that are available on `client`
+that are available on `client`. Note that it applies to all the modules.
 
 For example, `client.aio.models.generate_content` is the `async` version
 of `client.models.generate_content`
 
 ```python
 response = await client.aio.models.generate_content(
-    model='gemini-2.0-flash-001', contents='Tell me a story in 300 words.'
+    model='gemini-2.5-flash', contents='Tell me a story in 300 words.'
 )
 
 print(response.text)
 ```
 
-### Streaming
+### Generate Content (Asynchronous Streaming)
 
 ```python
 async for chunk in await client.aio.models.generate_content_stream(
-    model='gemini-2.0-flash-001', contents='Tell me a story in 300 words.'
+    model='gemini-2.5-flash', contents='Tell me a story in 300 words.'
 ):
     print(chunk.text, end='')
 ```
@@ -841,7 +1178,7 @@ async for chunk in await client.aio.models.generate_content_stream(
 
 ```python
 response = client.models.count_tokens(
-    model='gemini-2.0-flash-001',
+    model='gemini-2.5-flash',
     contents='why is the sky blue?',
 )
 print(response)
@@ -853,7 +1190,7 @@ Compute tokens is only supported in Vertex AI.
 
 ```python
 response = client.models.compute_tokens(
-    model='gemini-2.0-flash-001',
+    model='gemini-2.5-flash',
     contents='why is the sky blue?',
 )
 print(response)
@@ -863,26 +1200,42 @@ print(response)
 
 ```python
 response = await client.aio.models.count_tokens(
-    model='gemini-2.0-flash-001',
+    model='gemini-2.5-flash',
     contents='why is the sky blue?',
 )
 print(response)
 ```
 
+#### Local Count Tokens
+
+```python
+tokenizer = genai.LocalTokenizer(model_name='gemini-2.5-flash')
+result = tokenizer.count_tokens("What is your name?")
+```
+
+#### Local Compute Tokens
+
+```python
+tokenizer = genai.LocalTokenizer(model_name='gemini-2.5-flash')
+result = tokenizer.compute_tokens("What is your name?")
+```
+
 ### Embed Content
 
 ```python
 response = client.models.embed_content(
-    model='text-embedding-004',
+    model='gemini-embedding-001',
     contents='why is the sky blue?',
 )
 print(response)
 ```
 
 ```python
+from google.genai import types
+
 # multiple contents with config
 response = client.models.embed_content(
-    model='text-embedding-004',
+    model='gemini-embedding-001',
     contents=['why is the sky blue?', 'What is your age?'],
     config=types.EmbedContentConfig(output_dimensionality=10),
 )
@@ -897,9 +1250,11 @@ print(response)
 Support for generate images in Gemini Developer API is behind an allowlist
 
 ```python
+from google.genai import types
+
 # Generate Image
 response1 = client.models.generate_images(
-    model='imagen-3.0-generate-002',
+    model='imagen-4.0-generate-001',
     prompt='An umbrella in the foreground, and a rainy night sky in the background',
     config=types.GenerateImagesConfig(
         number_of_images=1,
@@ -915,9 +1270,11 @@ response1.generated_images[0].image.show()
 Upscale image is only supported in Vertex AI.
 
 ```python
+from google.genai import types
+
 # Upscale the generated image from above
 response2 = client.models.upscale_image(
-    model='imagen-3.0-generate-001',
+    model='imagen-4.0-upscale-preview',
     image=response1.generated_images[0].image,
     upscale_factor='x2',
     config=types.UpscaleImageConfig(
@@ -936,6 +1293,7 @@ Edit image is only supported in Vertex AI.
 
 ```python
 # Edit the generated image from above
+from google.genai import types
 from google.genai.types import RawReferenceImage, MaskReferenceImage
 
 raw_ref_image = RawReferenceImage(
@@ -968,18 +1326,19 @@ response3.generated_images[0].image.show()
 
 ### Veo
 
-#### Generate Videos
+Support for generating videos is considered public preview
 
-Support for generate videos in Vertex and Gemini Developer API is behind an allowlist
+#### Generate Videos (Text to Video)
 
 ```python
+from google.genai import types
+
 # Create operation
 operation = client.models.generate_videos(
-    model='veo-2.0-generate-001',
+    model='veo-3.1-generate-preview',
     prompt='A neon hologram of a cat driving at top speed',
     config=types.GenerateVideosConfig(
         number_of_videos=1,
-        fps=24,
         duration_seconds=5,
         enhance_prompt=True,
     ),
@@ -990,51 +1349,124 @@ while not operation.done:
     time.sleep(20)
     operation = client.operations.get(operation)
 
-video = operation.result.generated_videos[0].video
+video = operation.response.generated_videos[0].video
+video.show()
+```
+
+#### Generate Videos (Image to Video)
+
+```python
+from google.genai import types
+
+# Read local image (uses mimetypes.guess_type to infer mime type)
+image = types.Image.from_file("local/path/file.png")
+
+# Create operation
+operation = client.models.generate_videos(
+    model='veo-3.1-generate-preview',
+    # Prompt is optional if image is provided
+    prompt='Night sky',
+    image=image,
+    config=types.GenerateVideosConfig(
+        number_of_videos=1,
+        duration_seconds=5,
+        enhance_prompt=True,
+        # Can also pass an Image into last_frame for frame interpolation
+    ),
+)
+
+# Poll operation
+while not operation.done:
+    time.sleep(20)
+    operation = client.operations.get(operation)
+
+video = operation.response.generated_videos[0].video
+video.show()
+```
+
+#### Generate Videos (Video to Video)
+
+Currently, only Gemini Developer API supports video extension on Veo 3.1 for
+previously generated videos. Vertex supports video extension on Veo 2.0.
+
+```python
+from google.genai import types
+
+# Read local video (uses mimetypes.guess_type to infer mime type)
+video = types.Video.from_file("local/path/video.mp4")
+
+# Create operation
+operation = client.models.generate_videos(
+    model='veo-3.1-generate-preview',
+    # Prompt is optional if Video is provided
+    prompt='Night sky',
+    # Input video must be in GCS for Vertex or a URI for Gemini
+    video=types.Video(
+        uri="gs://bucket-name/inputs/videos/cat_driving.mp4",
+    ),
+    config=types.GenerateVideosConfig(
+        number_of_videos=1,
+        duration_seconds=5,
+        enhance_prompt=True,
+    ),
+)
+
+# Poll operation
+while not operation.done:
+    time.sleep(20)
+    operation = client.operations.get(operation)
+
+video = operation.response.generated_videos[0].video
 video.show()
 ```
 
 ## Chats
 
-Create a chat session to start a multi-turn conversations with the model.
+Create a chat session to start a multi-turn conversations with the model. Then,
+use `chat.send_message` function multiple times within the same chat session so
+that it can reflect on its previous responses (i.e., engage in an ongoing
+ conversation). See the 'Create a client' section above to initialize a client.
 
-### Send Message
+### Send Message (Synchronous Non-Streaming)
 
 ```python
-chat = client.chats.create(model='gemini-2.0-flash-001')
+chat = client.chats.create(model='gemini-2.5-flash')
 response = chat.send_message('tell me a story')
 print(response.text)
+response = chat.send_message('summarize the story you told me in 1 sentence')
+print(response.text)
 ```
 
-### Streaming
+### Send Message (Synchronous Streaming)
 
 ```python
-chat = client.chats.create(model='gemini-2.0-flash-001')
+chat = client.chats.create(model='gemini-2.5-flash')
 for chunk in chat.send_message_stream('tell me a story'):
     print(chunk.text)
 ```
 
-### Async
+### Send Message (Asynchronous Non-Streaming)
 
 ```python
-chat = client.aio.chats.create(model='gemini-2.0-flash-001')
+chat = client.aio.chats.create(model='gemini-2.5-flash')
 response = await chat.send_message('tell me a story')
 print(response.text)
 ```
 
-### Async Streaming
+### Send Message (Asynchronous Streaming)
 
 ```python
-chat = client.aio.chats.create(model='gemini-2.0-flash-001')
+chat = client.aio.chats.create(model='gemini-2.5-flash')
 async for chunk in await chat.send_message_stream('tell me a story'):
     print(chunk.text)
 ```
 
 ## Files
 
-Files are only supported in Gemini Developer API.
+Files are only supported in Gemini Developer API. See the 'Create a client'
+section above to initialize a client.
 
-```cmd
+```sh
 !gsutil cp gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf .
 !gsutil cp gs://cloud-samples-data/generative-ai/pdf/2403.05530.pdf .
 ```
@@ -1066,11 +1498,14 @@ client.files.delete(name=file3.name)
 
 ## Caches
 
-`client.caches` contains the control plane APIs for cached content
+`client.caches` contains the control plane APIs for cached content. See the
+'Create a client' section above to initialize a client.
 
 ### Create
 
 ```python
+from google.genai import types
+
 if client.vertexai:
     file_uris = [
         'gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf',
@@ -1080,7 +1515,7 @@ else:
     file_uris = [file1.uri, file2.uri]
 
 cached_content = client.caches.create(
-    model='gemini-1.5-pro-002',
+    model='gemini-2.5-flash',
     config=types.CreateCachedContentConfig(
         contents=[
             types.Content(
@@ -1112,8 +1547,10 @@ cached_content = client.caches.get(name=cached_content.name)
 ### Generate Content with Caches
 
 ```python
+from google.genai import types
+
 response = client.models.generate_content(
-    model='gemini-1.5-pro-002',
+    model='gemini-2.5-flash',
     contents='Summarize the pdfs',
     config=types.GenerateContentConfig(
         cached_content=cached_content.name,
@@ -1125,33 +1562,26 @@ print(response.text)
 ## Tunings
 
 `client.tunings` contains tuning job APIs and supports supervised fine
-tuning through `tune`.
+tuning through `tune`. Only supported in Vertex AI. See the 'Create a client'
+section above to initialize a client.
 
 ### Tune
 
--   Vertex AI supports tuning from GCS source
--   Gemini Developer API supports tuning from inline examples
+-   Vertex AI supports tuning from GCS source or from a [Vertex AI Multimodal Dataset](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/multimodal/datasets)
 
 ```python
-if client.vertexai:
-    model = 'gemini-1.5-pro-002'
-    training_dataset = types.TuningDataset(
-        gcs_uri='gs://cloud-samples-data/ai-platform/generative_ai/gemini-1_5/text/sft_train_data.jsonl',
-    )
-else:
-    model = 'models/gemini-1.0-pro-001'
-    training_dataset = types.TuningDataset(
-        examples=[
-            types.TuningExample(
-                text_input=f'Input text {i}',
-                output=f'Output text {i}',
-            )
-            for i in range(5)
-        ],
-    )
+from google.genai import types
+
+model = 'gemini-2.5-flash'
+training_dataset = types.TuningDataset(
+    # or gcs_uri=my_vertex_multimodal_dataset
+    gcs_uri='gs://your-gcs-bucket/your-tuning-data.jsonl',
+)
 ```
 
 ```python
+from google.genai import types
+
 tuning_job = client.tunings.tune(
     base_model=model,
     training_dataset=training_dataset,
@@ -1172,14 +1602,15 @@ print(tuning_job)
 ```python
 import time
 
-running_states = set(
+completed_states = set(
     [
-        'JOB_STATE_PENDING',
-        'JOB_STATE_RUNNING',
+        'JOB_STATE_SUCCEEDED',
+        'JOB_STATE_FAILED',
+        'JOB_STATE_CANCELLED',
     ]
 )
 
-while tuning_job.state in running_states:
+while tuning_job.state not in completed_states:
     print(tuning_job.state)
     tuning_job = client.tunings.get(name=tuning_job.name)
     time.sleep(10)
@@ -1238,6 +1669,8 @@ print(async_pager[0])
 ### Update Tuned Model
 
 ```python
+from google.genai import types
+
 model = pager[0]
 
 model = client.models.update(
@@ -1283,20 +1716,68 @@ print(async_pager[0])
 
 ## Batch Prediction
 
-Only supported in Vertex AI.
+Only supported in Vertex AI. See the 'Create a client' section above to
+initialize a client.
 
 ### Create
 
+Vertex AI:
+
 ```python
 # Specify model and source file only, destination and job display name will be auto-populated
 job = client.batches.create(
-    model='gemini-1.5-flash-002',
-    src='bq://my-project.my-dataset.my-table',
+    model='gemini-2.5-flash',
+    src='bq://my-project.my-dataset.my-table',  # or "gs://path/to/input/data"
+)
+
+print(job)
+```
+
+Gemini Developer API:
+
+```python
+# Create a batch job with inlined requests
+batch_job = client.batches.create(
+    model="gemini-2.5-flash",
+    src=[{
+        "contents": [{
+            "parts": [{
+                "text": "Hello!",
+            }],
+            "role": "user",
+        }],
+        "config": {"response_modalities": ["text"]},
+    }],
 )
 
 job
 ```
 
+In order to create a batch job with file name. Need to upload a json file.
+For example myrequests.json:
+
+```
+{"key":"request_1", "request": {"contents": [{"parts": [{"text":
+ "Explain how AI works in a few words"}]}], "generation_config": {"response_modalities": ["TEXT"]}}}
+{"key":"request_2", "request": {"contents": [{"parts": [{"text": "Explain how Crypto works in a few words"}]}]}}
+```
+Then upload the file.
+
+```python
+# Upload the file
+file = client.files.upload(
+    file='myrequests.json',
+    config=types.UploadFileConfig(display_name='test-json')
+)
+
+# Create a batch job with file name
+batch_job = client.batches.create(
+    model="gemini-2.0-flash",
+    src="files/test-json",
+)
+```
+
+
 ```python
 # Get a job by name
 job = client.batches.get(name=job.name)
@@ -1373,11 +1854,32 @@ To handle errors raised by the model service, the SDK provides this [APIError](h
 from google.genai import errors
 
 try:
-  client.models.generate_content(
-      model="invalid-model-name",
-      contents="What is your name?",
-  )
+    client.models.generate_content(
+        model="invalid-model-name",
+        contents="What is your name?",
+    )
 except errors.APIError as e:
-  print(e.code) # 404
-  print(e.message)
+    print(e.code) # 404
+    print(e.message)
+```
+
+## Extra Request Body
+
+The `extra_body` field in `HttpOptions` accepts a dictionary of additional JSON
+properties to include in the request body. This can be used to access new or
+experimental backend features that are not yet formally supported in the SDK.
+The structure of the dictionary must match the backend API's request structure.
+
+- VertexAI backend API docs: https://cloud.google.com/vertex-ai/docs/reference/rest
+- GeminiAPI backend API docs: https://ai.google.dev/api/rest
+
+```python
+response = client.models.generate_content(
+    model="gemini-2.5-pro",
+    contents="What is the weather in Boston? and how about Sunnyvale?",
+    config=types.GenerateContentConfig(
+        tools=[get_current_weather],
+        http_options=types.HttpOptions(extra_body={'tool_config': {'function_calling_config': {'mode': 'COMPOSITIONAL'}}}),
+    ),
+)
 ```