Google Gen AI Python SDK

google-genai is Google’s official Python SDK for integrating generative models — including the Gemini family — into Python applications. A single Client object provides a unified interface to both the Gemini Developer API and Vertex AI, covering text and chat generation, streaming, function calling, file and cache management, batch jobs, live/realtime sessions, and embeddings.

The SDK is organized around resource-oriented submodules (chats, files, caches, batches, live, live_music) built on a shared HTTP/auth layer (_api_client.py), with dedicated sync and async client surfaces, automatic function-calling support, and a replay-based test harness for recording and replaying API interactions in tests.

What You Get

• A unified Client object that targets either the Gemini Developer API or Vertex AI with the same interface
• Sync and async APIs for text/chat generation, streaming responses, and multi-turn chats sessions
• Automatic function calling, letting the model invoke Python functions passed directly to the client
• File, cache, and batch job management (files.py, caches.py, batches.py) for large-context and asynchronous workloads
• Live/realtime session support (live.py, live_music.py) for streaming audio/text interactions

Common Use Cases

• Building chat or agent applications on top of Gemini models from Python backends
• Switching between the Gemini Developer API and Vertex AI without rewriting client code
• Running batch generation jobs or managing large uploaded files/context caches for long-context prompts
• Building realtime, streaming voice or text assistants using the live session API

Under The Hood

Architecture The SDK centers on a Client entry point (client.py) that wires together resource-specific modules — chats.py, files.py, caches.py, batches.py, documents.py, interactions.py, live.py, live_music.py — each delegating HTTP calls to a shared _api_client.py layer that handles authentication (API key or Google Cloud credentials via google-auth), request/response transformation, and switching between the Gemini Developer API and Vertex AI endpoints. _transformers.py and _automatic_function_calling_util.py handle converting Python types and functions into the request/response shapes each backend expects.

Tech Stack Pure Python (>=3.10, tested through 3.14), built with setuptools, depending on httpx for HTTP, anyio for async support, pydantic for schema validation, google-auth for credential handling, and websockets for the live session transport.

Code Quality Tests live alongside the source under google/genai/tests, and the SDK includes a dedicated _replay_api_client.py that records and replays real API responses for deterministic testing without live network calls — a pattern purpose-built for testing an SDK whose backend behavior can’t be fully mocked. Internal modules are prefixed with underscores to clearly separate public surface from implementation detail.

API Design The client exposes both synchronous and asynchronous variants of nearly every operation, and automatic function calling lets callers pass plain Python functions as tool definitions without hand-writing JSON schemas — reducing the boilerplate typically required to wire up model tool-use. A single Client(vertexai=True/False) toggle switches the entire SDK between the Gemini Developer API and Vertex AI, avoiding the need for separate client libraries per backend.