python‑genai 3.0.0: Gemini Developer API Moves to API Version v1

• Clients targeting the Gemini Developer API now default to API version v1 instead of v1beta.
• Clients with vertexai=True or enterprise=True continue to default to v1beta1.
• GOOGLE_GENAI_API_VERSION restores the beta default, or sets an explicit version string.
• httpx2 is the required dependency and default HTTP client, and httpx is no longer installed by default.
• httpx2 uses the OS certificate trust store instead of certifi when SSL_CERT_FILE and SSL_CERT_DIR are not set.
• CodeExecutionResultStep.result in Interactions changes from a string to a union type.

Gemini Developer API clients now default to API version v1 #

The change is listed under the breaking changes in the python-genai v3.0.0 release notes. Any Gemini Developer API client that does not set a version in code now sends requests to v1. The release also makes file uploads respect the configured and default API version, so uploads follow the same default.

Clients targeting the Gemini Developer API now default to API version v1 instead of v1beta.

python-genai v3.0.0

To keep v1beta without changing code, set GOOGLE_GENAI_API_VERSION to beta, which restores v1beta on the Gemini Developer API. Setting it to v1beta pins that version explicitly, and v1 is also accepted. The variable applies only when no version is set in code, because api_version in HttpOptions takes precedence over it.

Enterprise and Vertex AI clients stay on v1beta1 #

Clients created with vertexai=True or enterprise=True are unaffected by the default change and continue to default to v1beta1. The same environment variable covers them when no version is set in code. Setting GOOGLE_GENAI_API_VERSION to beta restores v1beta1 on this platform, while Gemini Developer API clients get v1beta from the same value, so one setting produces a different version on each platform.

Who is affected by httpx2 as the default HTTP client #

With this release, httpx is no longer installed by default, and httpx2 becomes the required dependency and default client. Installing google-genai[httpx] alone only makes the httpx import available, because httpx2 is already installed. To keep the SDK on httpx without code changes, install the extra with pip install "google-genai[httpx]" and set GOOGLE_GENAI_HTTP_CLIENT=httpx.

When GOOGLE_GENAI_HTTP_CLIENT is unset or auto, passing httpx objects in HttpOptions also selects the httpx backend, provided google-genai[httpx] is installed. Code that builds its own clients can pass httpx_client and httpx_async_client through HttpOptions after installing the extra.

Migrating httpx settings, exceptions and SSL trust #

Most existing httpx code moves to httpx2 by changing its import to import httpx2 as httpx. Package-specific objects passed in HttpOptions(client_args=..., async_client_args=...) must match the active HTTP client. These include Timeout, Limits, MockTransport, BaseTransport and custom Auth subclasses. Unwrapped transport exceptions caught from client.models and client.files, such as TimeoutException, ConnectError and HTTPError, must match as well.

Certificate handling also changes. When SSL_CERT_FILE and SSL_CERT_DIR are not set, httpx2 uses the OS certificate trust store, through truststore or httpx2.create_ssl_context(), instead of certifi. This replaces the certifi default for environments that leave both variables unset.

Interactions CodeExecutionResultStep.result is now a union #

CodeExecutionResultStep.result changes from a string to the CodeExecutionResultStepResult union. Code that reads result as a string must check which variant is present and read the string from that variant. The release notes state that the JSON for text-only results is unchanged, so the change applies to Python access rather than to text output on the wire.

The same release adds multimodal content support to CodeExecutionResultStep.result. This suggests the union carries non-text variants, so any code that reads the field should branch on the variant rather than assume text.

Upgrade checklist for python-genai 3.0.0 #

Work through these four steps before upgrading to python-genai 3.0.0.

1. Decide the API version: keep v1, set GOOGLE_GENAI_API_VERSION to beta, or pass api_version='v1beta' in HttpOptions.
2. Confirm the HTTP client: keep httpx2 and change imports to import httpx2 as httpx, or install google-genai[httpx] and set GOOGLE_GENAI_HTTP_CLIENT=httpx.
3. Review client_args, async_client_args and httpx exception handling against the httpx2 types listed above.
4. Search your code for reads of CodeExecutionResultStep.result and handle each variant.

The release notes do not list which calls behave differently under v1 and v1beta, so the version decision in step 1 cannot be narrowed to specific code paths from these notes.

Also in this release #

The release includes a fix to Interactions retries, where Retries equals attempts minus 1. The other items are listed below in one line each.

• Added source_text to AudioTranscriptionConfig and SmartTranscriptionMode.
• Added MALFORMED_RESPONSE to FinishReason, referenced as #2937.
• The CLI transcribe command uses gemini-3.5-transcribe as its default model.
• Disabled GenerateVideos for the Gemini API, with tests and READMEs updated.
• Added Office and OpenDocument MIME types to Interactions.
• Preserved unknown fields and open-union variants in Interactions models.
• Updated the discovery document.
• Updated embedding examples from gemini-embedding-2-preview to gemini-embedding-2.
• Updated documentation links from ai.google.dev to aistudio.google.com.

The full list of commits is in the python-genai v3.0.0 release notes.